HTTP routers

export declare function buildMultiModalInput(body: any, files?: any[]): string | any[];

export declare function createAgentRouter(opts: RouterOptions): any;

export declare function createFileUploadMiddleware(opts?: FileUploadOptions): (req: any, res: any, next: (error?: unknown) => void) => void;

export declare function createGatewayRouter(config: GatewayConfig): any;

export declare function errorHandler(options?: {
    logger?: Pick<Console, "error">;
}): (err: any, _req: any, res: any, _next: any) => void;

export interface FileUploadOptions {
    maxFileSize?: number;
    maxFiles?: number;
    maxFields?: number;
    maxFieldSize?: number;
    allowedMimeTypes?: string[];
}

export interface GatewayConfig {
    locals?: RouterOptions;
    remotes: RemoteEndpoint[];
    healthCheckIntervalMs?: number;
}

export declare function generateOpenAPISpec(routerOpts: RouterOptions, swaggerOpts?: SwaggerOptions): OpenAPISpec;

/** Identity derived only from credentials verified by host middleware or JWT. */
export interface HostedIdentity {
    userId: string;
    tenantId?: string;
}

export interface HostedResourceRequest {
    identity: Readonly<HostedIdentity>;
    operation: string;
    resource: {
        kind: "session" | "run" | "approval" | "checkpoint" | "correction" | "schedule" | "admin";
        id?: string;
        agentName?: string;
        /** Requested correction visibility, for host policy evaluation. */
        scope?: string;
    };
}

export type HostedSecurityOptions = {
    mode: "local";
} | {
    mode: "authenticated";
    /** Receives req.user after trusted middleware/JWT verification; never the request body. */
    resolveIdentity: (verifiedClaims: unknown) => HostedIdentity | null | Promise<HostedIdentity | null>;
    /**
     * Check authoritative owner records. Unknown/ownerless records MUST return false.
     * session:create MUST atomically bind this new opaque ID to identity before returning true.
     * Collection operations grant access to the entire collection; deny when that is inappropriate.
     * Scopes (including admin:*) never bypass this authorization.
     */
    authorizeResource: (request: HostedResourceRequest) => boolean | Promise<boolean>;
};

export interface RemoteEndpoint {
    baseUrl: string;
    agents?: string[];
    teams?: string[];
    workflows?: string[];
    headers?: Record<string, string>;
    healthPath?: string;
}

export declare function requestLogger(options?: {
    logger?: Pick<Console, "log">;
}): (req: any, _res: any, next: any) => void;

export interface RouterOptions {
    /** Required explicit boundary. JWT/RBAC require authenticated mode and both host hooks. */
    security: HostedSecurityOptions;
    /**
     * Use a Registry for live auto-discovery. The router creates dynamic routes
     * that resolve agents/teams/workflows at request time — any instance created
     * after the router is mounted is automatically available.
     *
     * When omitted, falls back to the global registry from `@agentium/core`.
     * Pass `false` to disable registry-based routing entirely (use explicit maps only).
     *
     * @example
     * createAgentRouter({ security: { mode: "local" }, cors: true });
     * new Agent({ name: "bot", model: openai("gpt-4o") }); // immediately routable
     */
    registry?: Registry | false;
    /**
     * Auto-discover agents, teams, and workflows from a mixed array.
     * Each item is classified by its `.kind` and keyed by `.name`.
     */
    serve?: Servable[];
    agents?: Record<string, Agent | ServableAgent>;
    teams?: Record<string, Team>;
    workflows?: Record<string, Workflow<any>>;
    middleware?: any[];
    /** Swagger / OpenAPI configuration */
    swagger?: SwaggerOptions;
    /** Connection-owned text response limits. */
    textStream?: TextStreamLimits;
    /** File upload configuration for multi-modal inputs */
    fileUpload?: boolean | FileUploadOptions;
    /** CORS configuration. Pass true or '*' for permissive, a string for a single origin, or an array for multiple origins. */
    cors?: string | string[] | boolean;
    /** Rate limiting configuration. Pass true for defaults (100 req/min), or an object to customize. */
    rateLimit?: {
        windowMs?: number;
        max?: number;
    } | boolean;
    /** Named tool library exposed via GET /tools. Tools from toolkits are auto-collected. */
    toolLibrary?: Record<string, ToolDef>;
    /** Toolkit instances whose tools are exposed via GET /tools. Merged with toolLibrary. */
    toolkits?: Toolkit[];
    /**
     * Enable admin routes under `/admin` for managing MCP servers and the toolkit catalog.
     * Pass `true` to use defaults, or provide an MCPManager instance to share state.
     */
    admin?: boolean | {
        mcpManager?: MCPManager;
        middleware?: any[];
    };
    /**
     * Enable schedule management routes under `/schedules`.
     * Pass an AgentQueue instance from `@agentium/queue`.
     */
    scheduler?: any;
    /**
     * MetricsExporter instance from `@agentium/observability` for `/metrics` endpoints.
     */
    metricsExporter?: any;
    /**
     * JWT authentication middleware. Verifies tokens and attaches decoded payload to `req.user`.
     * Requires `jsonwebtoken` package.
     */
    jwt?: JwtConfig;
    /**
     * Role-based access control. Checks `req.user.scopes` against required scopes per route.
     * Requires `jwt` to be configured first.
     */
    rbac?: RbacConfig;
}

export interface SwaggerOptions {
    /** Enable Swagger UI at /docs. Default: false */
    enabled?: boolean;
    /** API title shown in Swagger UI */
    title?: string;
    /** API description shown in Swagger UI */
    description?: string;
    /** API version string */
    version?: string;
    /** Route prefix used in path generation (e.g. "/api") */
    routePrefix?: string;
    /** Server URLs for the spec */
    servers?: Array<{
        url: string;
        description?: string;
    }>;
    /** Path to serve Swagger UI. Default: "/docs" */
    docsPath?: string;
    /** Path to serve the raw OpenAPI JSON spec. Default: "/docs/spec.json" */
    specPath?: string;
}

interface OpenAPISpec {
    openapi: string;
    info: {
        title: string;
        description: string;
        version: string;
    };
    servers?: Array<{
        url: string;
        description?: string;
    }>;
    paths: Record<string, Record<string, unknown>>;
    components: {
        schemas: Record<string, unknown>;
        securitySchemes?: Record<string, unknown>;
    };
    security?: Array<Record<string, string[]>>;
    tags: Array<{
        name: string;
        description: string;
    }>;
}