@agentium/transport 4.1.0 → 4.6.0

package/dist/a2a/a2a-server.d.cts

@@ -0,0 +1,9 @@
+import type { A2AServerOptions } from "./types.cjs";
+/**
+ * Mount an A2A-compliant server on an Express app.
+ *
+ * - Serves `/.well-known/agent.json` with the Agent Card
+ * - Handles JSON-RPC 2.0 requests at the basePath for message/send, message/stream, tasks/get, tasks/cancel
+ */
+export declare function createA2AServer(app: any, opts: A2AServerOptions): void;
+//# sourceMappingURL=a2a-server.d.ts.map

package/dist/a2a/agent-card.d.cts

@@ -0,0 +1,17 @@
+import type { A2AAgentCard, Agent } from "@agentium/core";
+/**
+ * Generate an A2A Agent Card from a Agentium Agent.
+ * The card is served at /.well-known/agent.json per the A2A spec.
+ */
+export declare function generateAgentCard(agent: Agent, serverUrl: string, provider?: {
+    organization: string;
+    url?: string;
+}, version?: string): A2AAgentCard;
+/**
+ * Generate a combined Agent Card that lists multiple agents as skills.
+ */
+export declare function generateMultiAgentCard(agents: Record<string, Agent>, serverUrl: string, provider?: {
+    organization: string;
+    url?: string;
+}, version?: string): A2AAgentCard;
+//# sourceMappingURL=agent-card.d.ts.map

package/dist/a2a/durable-v1-server.d.cts

@@ -0,0 +1,17 @@
+import type { DurableReader } from "@agentium/core";
+import type { Request, Router } from "express";
+import { type DurableProtocolHost } from "../durable/protocol-host.cjs";
+export interface DurableA2AV1ServerOptions extends DurableProtocolHost {
+    name: string;
+    /** Absolute public JSON-RPC URL; mount the returned router at its origin. */
+    url: string;
+    audience: string;
+    authenticate(request: Request, audience: string): Promise<DurableReader | null>;
+    cardPath?: string;
+    /** Blocking SendMessage waits only this long; timeout does not cancel admitted work. */
+    waitTimeoutMs?: number;
+    pollIntervalMs?: number;
+}
+/** Optional A2A 1.0 JSON-RPC bridge. Polling only; all state remains in the durable store. */
+export declare function createDurableA2AV1Server(options: DurableA2AV1ServerOptions): Promise<Router>;
+//# sourceMappingURL=durable-v1-server.d.ts.map

package/dist/a2a/types.d.cts

@@ -0,0 +1,13 @@
+import type { Agent } from "@agentium/core";
+export interface A2AServerOptions {
+    agents: Record<string, Agent>;
+    basePath?: string;
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    version?: string;
+    /** Maximum process-local tasks, including active work. Default 10000. */
+    maxTasks?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/a2a/v1-server.d.cts

@@ -0,0 +1,27 @@
+import type { A2AV1Card, Agent, RunOutput } from "@agentium/core";
+import type { Express, Request } from "express";
+export interface A2AV1Identity {
+    tenantId: string;
+    userId: string;
+}
+export interface A2AV1ServerOptions {
+    agents: Record<string, Pick<Agent, "name" | "run">>;
+    /** Absolute URL of this JSON-RPC endpoint. */
+    url: string;
+    basePath?: string;
+    cardPath?: string;
+    /** Passed to the host verifier; the verifier must validate token audience. */
+    audience: string;
+    authenticate: (request: Request, audience: string) => Promise<A2AV1Identity | null>;
+    maxTasks?: number;
+    /** Local history retention and follow-up admission bound; default 128. */
+    maxHistoryMessages?: number;
+    /** Domain-specific interrupted results remain distinguishable from success. */
+    completionState?: (output: RunOutput) => "TASK_STATE_COMPLETED" | "TASK_STATE_INPUT_REQUIRED" | "TASK_STATE_AUTH_REQUIRED" | "TASK_STATE_FAILED";
+}
+/** A2A 1.0 JSON-RPC using the optional official SDK. Local task state is
+ * process-local and ownership-scoped; this adapter does not promise recovery. */
+export declare function createA2AV1Server(app: Express, options: A2AV1ServerOptions): Promise<{
+    card: A2AV1Card;
+}>;
+//# sourceMappingURL=v1-server.d.ts.map

package/dist/durable/protocol-host.d.cts

@@ -0,0 +1,56 @@
+import type { DurableJSON, DurableReader, DurableTaskKey, DurableTaskRecord, DurableTaskSupervisor } from "@agentium/core";
+export type DurableProtocolPart = {
+    text: string;
+} | {
+    data: DurableJSON;
+};
+export type DurableProtocolAdmission = {
+    protocol: "a2a-1.0";
+    name: string;
+    messageId: string;
+    parts: DurableProtocolPart[];
+} | {
+    protocol: "mcp-2026-07-28";
+    name: string;
+    arguments: Record<string, DurableJSON>;
+};
+export interface DurableProtocolApprovalResponse {
+    approvalId: string;
+    preparedHash: string;
+    approved: boolean;
+}
+export interface DurableProtocolOutput {
+    text?: string;
+    data?: DurableJSON;
+    /** A completed tool result can contain a domain error without becoming a protocol failure. */
+    isError?: boolean;
+}
+/** Trusted admission boundary; protocol payloads cannot select identity, policy or grants. */
+export interface DurableProtocolHost {
+    supervisor: DurableTaskSupervisor;
+    /** Persist an owned task before returning. Mint/validate immutable refs and deduplicate message IDs here. */
+    admit(identity: DurableReader, input: DurableProtocolAdmission): Promise<DurableTaskKey>;
+    authorize(identity: DurableReader, task: Readonly<DurableTaskRecord>, operation: "read" | "cancel" | "input" | "wake"): Promise<boolean>;
+    /** Re-deliver a persisted task to its registered driver. Failure leaves it available for host recovery. */
+    wake(key: DurableTaskKey): Promise<unknown>;
+    /** Explicit trusted human-consent channel. Persist via DurableActionLedger.decide; never trust tool text. */
+    respond?(identity: DurableReader, task: Readonly<DurableTaskRecord>, response: DurableProtocolApprovalResponse): Promise<void>;
+    /** Return only authorized public output. Resolve artifacts through DurableRunRecords; no automatic URLs. */
+    output?(identity: DurableReader, task: Readonly<DurableTaskRecord>): Promise<DurableProtocolOutput>;
+}
+export declare class DurableProtocolError extends Error {
+    readonly code: "invalid" | "not-found" | "unsupported";
+    constructor(code: "invalid" | "not-found" | "unsupported", message: string);
+}
+export declare function protocolId(value: unknown): string;
+/** Bounds both recursion and encoded size before host callbacks. Rejects unsafe/non-JSON values. */
+export declare function protocolJSON(value: unknown, maxBytes?: number): DurableJSON;
+export declare function protocolObject(value: unknown): Record<string, DurableJSON>;
+export declare function assertProtocolHost(host: DurableProtocolHost): void;
+export declare function ownedTask(host: DurableProtocolHost, identity: DurableReader, id: string, operation?: Parameters<DurableProtocolHost["authorize"]>[2]): Promise<DurableTaskRecord>;
+export declare function wakeTask(host: DurableProtocolHost, identity: DurableReader, id: string): Promise<void>;
+export declare function admitTask(host: DurableProtocolHost, identity: DurableReader, input: DurableProtocolAdmission): Promise<DurableTaskRecord>;
+export declare function pendingApprovals(task: DurableTaskRecord, identity: DurableReader): import("@agentium/core").DurableApproval[];
+export declare function respondToApproval(host: DurableProtocolHost, identity: DurableReader, taskId: string, response: DurableProtocolApprovalResponse): Promise<void>;
+export declare function publicOutput(host: DurableProtocolHost, identity: DurableReader, task: DurableTaskRecord): Promise<DurableProtocolOutput>;
+//# sourceMappingURL=protocol-host.d.ts.map

package/dist/express/admin-router.d.cts

@@ -0,0 +1,36 @@
+import { MCPManager } from "./mcp-manager.cjs";
+export interface AdminRouterOptions {
+    /** Shared MCPManager instance. If omitted, a new one is created. */
+    mcpManager?: MCPManager;
+    /**
+     * Express middleware for authentication/authorization.
+     * **IMPORTANT**: These endpoints can add MCP servers and execute tools.
+     * Always add auth middleware in production.
+     */
+    middleware?: any[];
+}
+/**
+ * Creates an Express sub-router with admin endpoints for managing
+ * MCP servers and the toolkit catalog at runtime.
+ *
+ * Mount under a prefix: `app.use("/admin", createAdminRouter())`
+ *
+ * Routes:
+ *   GET    /mcp              — list MCP servers
+ *   POST   /mcp              — add + connect an MCP server
+ *   GET    /mcp/:id          — single server details
+ *   POST   /mcp/:id/connect  — connect a server
+ *   POST   /mcp/:id/disconnect — disconnect
+ *   DELETE /mcp/:id          — remove a server
+ *   GET    /mcp/:id/tools    — tools from a specific server
+ *   GET    /mcp/tools        — all tools across connected servers
+ *
+ *   GET    /toolkits         — list toolkit catalog
+ *   GET    /toolkits/:id     — single toolkit meta
+ *   POST   /toolkits/:id     — instantiate a toolkit with config
+ */
+export declare function createAdminRouter(opts?: AdminRouterOptions): {
+    router: any;
+    mcpManager: MCPManager;
+};
+//# sourceMappingURL=admin-router.d.ts.map

package/dist/express/durable-router.d.cts

@@ -0,0 +1,18 @@
+import { type DurableReader, type DurableRunRecords, type DurableTaskKey, type DurableTaskRecord, type DurableTaskSupervisor } from "@agentium/core";
+import type { Request, Router } from "express";
+export interface DurableTaskRouterOptions {
+    supervisor: DurableTaskSupervisor;
+    records: DurableRunRecords;
+    /** Verify credentials/audience. Returned identity must never come from body/query claims. */
+    authenticate: (request: Request) => Promise<DurableReader | null>;
+    /** Recheck current host policy/grants on every request, including event reconnections. */
+    authorize: (identity: DurableReader, task: Readonly<DurableTaskRecord>, operation: "read" | "cancel") => Promise<boolean>;
+    /** Re-deliver cancellation to a worker. Cancellation remains persisted if Redis is unavailable. */
+    wake: (key: DurableTaskKey) => Promise<unknown>;
+}
+/** Authenticated control and bounded replay for tasks already admitted by the host.
+ * Event responses close after the retained batch; reconnect with Last-Event-ID.
+ * This is an Agentium endpoint, not an A2A or MCP wire-protocol endpoint.
+ */
+export declare function createDurableTaskRouter(options: DurableTaskRouterOptions): Router;
+//# sourceMappingURL=durable-router.d.ts.map

package/dist/express/file-upload.d.cts

@@ -0,0 +1,11 @@
+export interface FileUploadOptions {
+    maxFileSize?: number;
+    maxFiles?: number;
+    maxFields?: number;
+    maxFieldSize?: number;
+    allowedMimeTypes?: string[];
+}
+export declare function createFileUploadMiddleware(opts?: FileUploadOptions): (req: any, res: any, next: (error?: unknown) => void) => void;
+export declare function filesToContentParts(files: any[]): any[];
+export declare function buildMultiModalInput(body: any, files?: any[]): string | any[];
+//# sourceMappingURL=file-upload.d.ts.map

package/dist/express/gateway.d.cts

@@ -0,0 +1,16 @@
+import type { RouterOptions } from "./types.cjs";
+export interface RemoteEndpoint {
+    baseUrl: string;
+    agents?: string[];
+    teams?: string[];
+    workflows?: string[];
+    headers?: Record<string, string>;
+    healthPath?: string;
+}
+export interface GatewayConfig {
+    locals?: RouterOptions;
+    remotes: RemoteEndpoint[];
+    healthCheckIntervalMs?: number;
+}
+export declare function createGatewayRouter(config: GatewayConfig): any;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/express/jwt-middleware.d.cts

@@ -0,0 +1,10 @@
+export interface JwtConfig {
+    secret: string;
+    algorithm?: string;
+    issuer?: string;
+    audience?: string;
+    extractFrom?: "header" | "cookie";
+    cookieName?: string;
+}
+export declare function createJwtMiddleware(config: JwtConfig): (req: any, res: any, next: any) => any;
+//# sourceMappingURL=jwt-middleware.d.ts.map

package/dist/express/mcp-manager.d.cts

@@ -0,0 +1,52 @@
+import type { MCPToolProviderConfig, ToolDef } from "@agentium/core";
+import { MCPToolProvider } from "@agentium/core";
+export interface MCPServerEntry {
+    id: string;
+    config: MCPToolProviderConfig;
+    provider: MCPToolProvider;
+    status: "disconnected" | "connecting" | "connected" | "error";
+    error?: string;
+    toolCount: number;
+    connectedAt?: Date;
+}
+export interface MCPServerSummary {
+    id: string;
+    name: string;
+    transport: string;
+    url?: string;
+    command?: string;
+    status: string;
+    toolCount: number;
+    error?: string;
+    connectedAt?: string;
+}
+/**
+ * Manages multiple MCP server connections at runtime.
+ * Servers can be added/removed/connected/disconnected dynamically,
+ * and their tools can be collected for injection into agents.
+ */
+export declare class MCPManager {
+    private servers;
+    /** Add a server config. Auto-generates an id from the name if not provided. */
+    add(config: MCPToolProviderConfig, id?: string): MCPServerSummary;
+    /** Connect a server by id. Discovers tools on success. */
+    connect(id: string): Promise<MCPServerSummary>;
+    /** Disconnect a server by id. */
+    disconnect(id: string): Promise<MCPServerSummary>;
+    /** Remove a server entirely. Disconnects first if connected. */
+    remove(id: string): Promise<void>;
+    /** Get all tools from all connected servers, merged into one array. */
+    getAllTools(): Promise<ToolDef[]>;
+    /** Get tools from a specific server. */
+    getTools(id: string): Promise<ToolDef[]>;
+    /** List all registered servers. */
+    list(): MCPServerSummary[];
+    /** Get a single server summary. */
+    get(id: string): MCPServerSummary;
+    has(id: string): boolean;
+    /** Disconnect all servers. */
+    closeAll(): Promise<void>;
+    private getEntry;
+    private summarize;
+}
+//# sourceMappingURL=mcp-manager.d.ts.map

package/dist/express/middleware.d.cts

@@ -0,0 +1,7 @@
+export declare function errorHandler(options?: {
+    logger?: Pick<Console, "error">;
+}): (err: any, _req: any, res: any, _next: any) => void;
+export declare function requestLogger(options?: {
+    logger?: Pick<Console, "log">;
+}): (req: any, _res: any, next: any) => void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/express/rbac-middleware.d.cts

@@ -0,0 +1,11 @@
+export interface RbacConfig {
+    scopeField?: string;
+    /** Override an exact route pattern. Empty scopes explicitly permit authenticated access. */
+    defaultScopes?: Record<string, string[]>;
+    agentScopes?: Record<string, string[]>;
+    /** Explicit routes accessible without authentication. Use only for intentionally public endpoints. */
+    publicRoutes?: string[];
+}
+export declare function routeMatches(actual: string, pattern: string): boolean;
+export declare function createRbacMiddleware(config?: RbacConfig): (req: any, res: any, next: any) => any;
+//# sourceMappingURL=rbac-middleware.d.ts.map

package/dist/express/router-factory.d.cts

@@ -0,0 +1,3 @@
+import type { RouterOptions } from "./types.cjs";
+export declare function createAgentRouter(opts: RouterOptions): any;
+//# sourceMappingURL=router-factory.d.ts.map

package/dist/express/swagger.d.cts

@@ -0,0 +1,30 @@
+import type { RouterOptions, SwaggerOptions } from "./types.cjs";
+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;
+    }>;
+}
+export declare function generateOpenAPISpec(routerOpts: RouterOptions, swaggerOpts?: SwaggerOptions): OpenAPISpec;
+export declare function serveSwaggerUI(spec: OpenAPISpec): {
+    setup: any;
+    serve: any;
+};
+export {};
+//# sourceMappingURL=swagger.d.ts.map

package/dist/express/types.d.cts

@@ -0,0 +1,125 @@
+import type { Agent, Registry, Servable, ServableAgent, Team, ToolDef, Toolkit, Workflow } from "@agentium/core";
+import type { FileUploadOptions } from "./file-upload.cjs";
+import type { MCPManager } from "./mcp-manager.cjs";
+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;
+}
+/** 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 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?: import("../text-stream.cjs").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?: import("./jwt-middleware.cjs").JwtConfig;
+    /**
+     * Role-based access control. Checks `req.user.scopes` against required scopes per route.
+     * Requires `jwt` to be configured first.
+     */
+    rbac?: import("./rbac-middleware.cjs").RbacConfig;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/express/ui-stream.d.cts

@@ -0,0 +1,78 @@
+import type { Agent } from "@agentium/core";
+/**
+ * Vercel AI SDK UI Message Stream adapter.
+ *
+ * Converts the chunks emitted by `agent.stream(...)` into the line-delimited
+ * JSON protocol consumed by Vercel's `useChat` / `createAgentUIStreamResponse`.
+ *
+ * Spec: https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+ */
+export interface AgentUIStreamOptions {
+    /** sessionId forwarded to `agent.run` / `agent.stream`. */
+    sessionId?: string;
+    /** userId forwarded to `agent.run` / `agent.stream`. */
+    userId?: string;
+    /** Optional per-request API key override. */
+    apiKey?: string;
+    /** Optional abort signal to cancel the run. */
+    signal?: AbortSignal;
+}
+interface AgentLikeChunk {
+    type?: string;
+    text?: string;
+    delta?: string;
+    toolCallId?: string;
+    toolName?: string;
+    arguments?: unknown;
+    args?: unknown;
+    input?: unknown;
+    output?: unknown;
+    result?: unknown;
+    finishReason?: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    error?: string | {
+        message?: string;
+    };
+    reasoning?: string;
+    thinking?: string;
+}
+interface AgentLike {
+    stream(input: string, opts?: {
+        sessionId?: string;
+        userId?: string;
+        apiKey?: string;
+        signal?: AbortSignal;
+    }): AsyncIterable<AgentLikeChunk>;
+}
+/**
+ * Render an `agent.stream()` source as a Vercel-compatible UI message stream.
+ *
+ * The returned `ReadableStream<Uint8Array>` can be wrapped in a `Response`
+ * (web / edge / fetch) or piped to a Node `ServerResponse`.
+ */
+export declare function agentUIStream(agent: Agent | AgentLike, input: string, options?: AgentUIStreamOptions): ReadableStream<Uint8Array>;
+/**
+ * Create a `Response` whose body streams Vercel UI messages. Use as the return
+ * value of a Web / Edge / Next.js Route Handler.
+ *
+ * @example
+ * ```ts
+ * import { createAgentUIStreamResponse } from "@agentium/transport";
+ *
+ * export async function POST(req: Request) {
+ *   const { input, sessionId } = await req.json();
+ *   return createAgentUIStreamResponse(agent, input, { sessionId });
+ * }
+ * ```
+ */
+export declare function createAgentUIStreamResponse(agent: Agent | AgentLike, input: string, options?: AgentUIStreamOptions): Response;
+/**
+ * Pipe a Vercel UI message stream into a Node `ServerResponse` (Express style).
+ */
+export declare function pipeAgentUIStreamToResponse(agent: Agent | AgentLike, input: string, res: any, options?: AgentUIStreamOptions): Promise<void>;
+export {};
+//# sourceMappingURL=ui-stream.d.ts.map

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+export { createA2AServer } from "./a2a/a2a-server.cjs";
+export { generateAgentCard, generateMultiAgentCard } from "./a2a/agent-card.cjs";
+export type { DurableA2AV1ServerOptions } from "./a2a/durable-v1-server.cjs";
+export { createDurableA2AV1Server } from "./a2a/durable-v1-server.cjs";
+export type { A2AServerOptions } from "./a2a/types.cjs";
+export type { A2AV1Identity, A2AV1ServerOptions } from "./a2a/v1-server.cjs";
+export { createA2AV1Server } from "./a2a/v1-server.cjs";
+export type { DurableProtocolAdmission, DurableProtocolApprovalResponse, DurableProtocolHost, DurableProtocolOutput, DurableProtocolPart, } from "./durable/protocol-host.cjs";
+export type { AdminRouterOptions } from "./express/admin-router.cjs";
+export { createAdminRouter } from "./express/admin-router.cjs";
+export type { DurableTaskRouterOptions } from "./express/durable-router.cjs";
+export { createDurableTaskRouter } from "./express/durable-router.cjs";
+export type { FileUploadOptions } from "./express/file-upload.cjs";
+export { buildMultiModalInput, createFileUploadMiddleware } from "./express/file-upload.cjs";
+export type { GatewayConfig, RemoteEndpoint } from "./express/gateway.cjs";
+export { createGatewayRouter } from "./express/gateway.cjs";
+export type { JwtConfig } from "./express/jwt-middleware.cjs";
+export { createJwtMiddleware } from "./express/jwt-middleware.cjs";
+export type { MCPServerEntry, MCPServerSummary } from "./express/mcp-manager.cjs";
+export { MCPManager } from "./express/mcp-manager.cjs";
+export { errorHandler, requestLogger } from "./express/middleware.cjs";
+export type { RbacConfig } from "./express/rbac-middleware.cjs";
+export { createRbacMiddleware } from "./express/rbac-middleware.cjs";
+export { createAgentRouter } from "./express/router-factory.cjs";
+export { generateOpenAPISpec } from "./express/swagger.cjs";
+export type { HostedIdentity, HostedResourceRequest, HostedSecurityOptions, RouterOptions, SwaggerOptions, } from "./express/types.cjs";
+export type { AgentUIStreamOptions } from "./express/ui-stream.cjs";
+export { agentUIStream, createAgentUIStreamResponse, pipeAgentUIStreamToResponse } from "./express/ui-stream.cjs";
+export type { DurableMCPTaskHandler, DurableMCPTaskHandlerOptions, DurableMCPTaskTool, } from "./mcp/durable-task-handler.cjs";
+export { createDurableMCPTaskHandler } from "./mcp/durable-task-handler.cjs";
+export type { BrowserGatewayOptions } from "./socketio/browser-gateway.cjs";
+export { createBrowserGateway } from "./socketio/browser-gateway.cjs";
+export { createAgentGateway } from "./socketio/gateway.cjs";
+export type { GatewayOptions, GatewayResourceRequest, GatewaySecurityOptions } from "./socketio/types.cjs";
+export type { VisionGatewayOptions } from "./socketio/vision-gateway.cjs";
+export { createVisionGateway } from "./socketio/vision-gateway.cjs";
+export type { VoiceGatewayOptions } from "./socketio/voice-gateway.cjs";
+export { createVoiceGateway } from "./socketio/voice-gateway.cjs";
+export type { InMemoryEventLogConfig, SSEEvent, SSEEventLog } from "./sse-event-log.cjs";
+export { defaultEventLog, formatSSEEvent, InMemoryEventLog } from "./sse-event-log.cjs";
+export type { TextStreamLimits } from "./text-stream.cjs";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/durable-task-handler.d.cts

@@ -0,0 +1,24 @@
+import type { DurableReader } from "@agentium/core";
+import { type DurableProtocolHost } from "../durable/protocol-host.cjs";
+export interface DurableMCPTaskTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface DurableMCPTaskHandlerOptions extends DurableProtocolHost {
+    name: string;
+    audience: string;
+    authenticate(request: Request, audience: string): Promise<DurableReader | null>;
+    tools: readonly DurableMCPTaskTool[];
+    pollIntervalMs?: number;
+}
+export interface DurableMCPTaskHandler {
+    fetch(request: Request): Promise<Response>;
+    close(): Promise<void>;
+}
+/** Pinned modern HTTP/Tasks extension adapter. SDK handles discovery/schema framing;
+ * task extension methods are explicitly implemented here, not by the base SDK.
+ * The modern protocol negotiates capabilities in each validated request envelope.
+ */
+export declare function createDurableMCPTaskHandler(options: DurableMCPTaskHandlerOptions): Promise<DurableMCPTaskHandler>;
+//# sourceMappingURL=durable-task-handler.d.ts.map

package/dist/socketio/browser-gateway.d.cts

@@ -0,0 +1,62 @@
+import type { EventBus } from "@agentium/core";
+/**
+ * Minimal interface for a BrowserAgent — avoids a hard dependency on @agentium/browser.
+ * Any object that matches this shape (e.g. a real BrowserAgent) works.
+ */
+interface BrowserAgentLike {
+    name: string;
+    eventBus: EventBus;
+    run(task: string, opts?: {
+        startUrl?: string;
+        apiKey?: string;
+        sessionId?: string;
+    }): Promise<{
+        result: string;
+        success: boolean;
+        finalUrl: string;
+        durationMs: number;
+        videoPath?: string;
+        steps: Array<{
+            index: number;
+            action: unknown;
+            screenshot: Buffer;
+            pageUrl: string;
+            pageTitle: string;
+            dom?: string;
+        }>;
+    }>;
+}
+export interface BrowserGatewayOptions {
+    /** Named BrowserAgent instances. Clients select one via agentName. */
+    agents: Record<string, BrowserAgentLike>;
+    /** Socket.IO server instance */
+    io: any;
+    /** Socket.IO namespace. Default: "/agentium-browser" */
+    namespace?: string;
+    /** Optional auth middleware applied to the namespace */
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+    /**
+     * Stream screenshots to the client in real-time.
+     * Default: true. Disable for bandwidth-constrained clients.
+     */
+    streamScreenshots?: boolean;
+}
+/**
+ * Create a Socket.IO gateway that streams BrowserAgent execution in real-time.
+ *
+ * ## Client → Server events
+ * - `browser.start` — kick off a browser task
+ * - `browser.stop`  — cancel a running task
+ *
+ * ## Server → Client events
+ * - `browser.started`    — task accepted
+ * - `browser.screenshot` — live screenshot (base64 PNG)
+ * - `browser.action`     — action about to execute
+ * - `browser.step`       — full step with screenshot + DOM
+ * - `browser.done`       — task finished (result, success, duration, video)
+ * - `browser.error`      — error occurred
+ * - `browser.stopped`    — task was cancelled
+ */
+export declare function createBrowserGateway(opts: BrowserGatewayOptions): void;
+export {};
+//# sourceMappingURL=browser-gateway.d.ts.map

package/dist/socketio/gateway.d.cts

@@ -0,0 +1,3 @@
+import type { GatewayOptions } from "./types.cjs";
+export declare function createAgentGateway(options: GatewayOptions): void;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/socketio/handlers.d.cts

@@ -0,0 +1,2 @@
+export { createAgentGateway } from "./gateway.cjs";
+//# sourceMappingURL=handlers.d.ts.map

package/dist/socketio/types.d.cts

@@ -0,0 +1,58 @@
+import type { Agent, Registry, Servable, ServableAgent, Team, ToolDef, Toolkit } from "@agentium/core";
+export interface GatewayResourceRequest {
+    identity: Readonly<import("../express/types.cjs").HostedIdentity>;
+    operation: "discover" | "execute" | "session:create" | "session:use" | "run:cancel";
+    resource: {
+        kind: "agent" | "team" | "workflow" | "tool" | "session" | "run";
+        id: string;
+        target?: string;
+    };
+}
+export type GatewaySecurityOptions = {
+    mode: "local";
+} | {
+    mode: "authenticated";
+    /** Read only host-verified socket.data, never handshake payload claims. */
+    resolveIdentity: (verifiedState: unknown) => import("../express/types.cjs").HostedIdentity | null | Promise<import("../express/types.cjs").HostedIdentity | null>;
+    /** session:create must atomically bind the generated ID; deny unknown session:use. */
+    authorizeResource: (request: GatewayResourceRequest) => boolean | Promise<boolean>;
+};
+export interface GatewayOptions {
+    security: GatewaySecurityOptions;
+    /** Bounds apply per socket; outgoing frames use the Engine.IO drain contract. */
+    textStream?: import("../text-stream.cjs").TextStreamLimits;
+    maxConcurrentRuns?: number;
+    /** Maximum collected final Agent text bytes. Default 256 KiB. */
+    maxOutputBytes?: number;
+    /**
+     * Use a Registry for live auto-discovery. The gateway resolves agents/teams
+     * at event time — any instance created after the gateway starts is automatically
+     * reachable.
+     *
+     * When omitted, falls back to the global registry from `@agentium/core`.
+     * Pass `false` to disable registry-based lookup (use explicit maps only).
+     *
+     * @example
+     * createAgentGateway({ io, security: { mode: "local" } });
+     * new Agent({ name: "bot", model: openai("gpt-4o") }); // immediately reachable
+     */
+    registry?: Registry | false;
+    /**
+     * Auto-discover agents and teams 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>;
+    io: any;
+    namespace?: string;
+    /** Must call next; thrown/rejected errors deny access. Returned promises settle before admission. */
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void | Promise<void>;
+    /** Max requests per minute per socket. Default: 60 */
+    maxRequestsPerMinute?: number;
+    /** Named tool library exposed via tools.list event. */
+    toolLibrary?: Record<string, ToolDef>;
+    /** Toolkit instances whose tools are exposed via tools.list. Merged with toolLibrary. */
+    toolkits?: Toolkit[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/socketio/vision-gateway.d.cts

@@ -0,0 +1,9 @@
+import type { VisionAgent } from "@agentium/core";
+export interface VisionGatewayOptions {
+    agents: Record<string, VisionAgent>;
+    io: any;
+    namespace?: string;
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+}
+export declare function createVisionGateway(opts: VisionGatewayOptions): void;
+//# sourceMappingURL=vision-gateway.d.ts.map

package/dist/socketio/voice-gateway.d.cts

@@ -0,0 +1,14 @@
+import type { VoiceAgent } from "@agentium/core";
+export interface VoiceGatewayOptions {
+    agents: Record<string, VoiceAgent>;
+    io: any;
+    namespace?: string;
+    /** Establish trusted identity in socket.data.auth {userId,tenantId,sessionId}. */
+    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
+    maxAudioFrameBytes?: number;
+    maxPendingAudioBytes?: number;
+    playbackAckTimeoutMs?: number;
+}
+/** Bounded per-connection audio delivery; each output frame must be acknowledged by the client. */
+export declare function createVoiceGateway(opts: VoiceGatewayOptions): void;
+//# sourceMappingURL=voice-gateway.d.ts.map

package/dist/sse-event-log.d.cts

@@ -0,0 +1,54 @@
+/**
+ * Per-run in-memory ring buffer of SSE events. Each event gets a monotonically
+ * increasing numeric `id` so clients can pass `Last-Event-ID` on reconnect and
+ * replay missed events.
+ *
+ * Storage is intentionally in-process; for multi-instance deployments, plug a
+ * Redis-backed implementation behind the same interface.
+ */
+export interface SSEEvent {
+    /** Monotonic numeric ID. */
+    id: number;
+    /** Optional `event:` line value. Default omitted. */
+    event?: string;
+    /** Payload (will be JSON-stringified into the `data:` field). */
+    payload: unknown;
+    /** Wall-clock time the event was recorded. */
+    recordedAt: number;
+}
+export interface SSEEventLog {
+    /** Record a new event and return its assigned id. */
+    record(runId: string, event: Omit<SSEEvent, "id" | "recordedAt">): SSEEvent;
+    /** Return events for a run with id greater than `afterId`. */
+    since(runId: string, afterId: number): SSEEvent[];
+    /** All events for a run. */
+    all(runId: string): SSEEvent[];
+    /** Mark a run completed (frees buffers after `ttlMs`). */
+    finalize(runId: string): void;
+    /** Remove a run's buffer immediately. */
+    drop(runId: string): void;
+}
+export interface InMemoryEventLogConfig {
+    /** Max events kept per run. Oldest evicted when exceeded. Default: 1024. */
+    maxEventsPerRun?: number;
+    /** Milliseconds after finalize before a run's buffer is dropped. Default: 300_000 (5min). */
+    ttlMs?: number;
+}
+export declare class InMemoryEventLog implements SSEEventLog {
+    private buffers;
+    private nextIds;
+    private finalizeTimers;
+    private maxEvents;
+    private ttlMs;
+    constructor(config?: InMemoryEventLogConfig);
+    record(runId: string, event: Omit<SSEEvent, "id" | "recordedAt">): SSEEvent;
+    since(runId: string, afterId: number): SSEEvent[];
+    all(runId: string): SSEEvent[];
+    finalize(runId: string): void;
+    drop(runId: string): void;
+}
+/** Format an `SSEEvent` for the wire. */
+export declare function formatSSEEvent(ev: SSEEvent): string;
+/** Process-wide default log so multiple endpoints can share one buffer. */
+export declare const defaultEventLog: InMemoryEventLog;
+//# sourceMappingURL=sse-event-log.d.ts.map

package/dist/text-stream.d.cts

@@ -0,0 +1,33 @@
+import type { ServerResponse } from "node:http";
+export interface TextStreamLimits {
+    /** Maximum encoded frame and queued response bytes. Default 256 KiB each. */
+    maxFrameBytes?: number;
+    maxBufferedBytes?: number;
+    /** Maximum wait for a writable drain. Default 10 seconds. */
+    writeTimeoutMs?: number;
+}
+export declare function textStreamLimits(options?: TextStreamLimits): {
+    maxFrameBytes: number;
+    maxBufferedBytes: number;
+    writeTimeoutMs: number;
+};
+/** One owner for the response lifetime. Cancellation remains cooperative. */
+export declare function responseLifetime(res: ServerResponse): {
+    controller: AbortController;
+    dispose(): void;
+};
+export declare class BoundedSSEWriter {
+    private readonly res;
+    private readonly signal;
+    private readonly limits;
+    constructor(res: ServerResponse, signal: AbortSignal, options?: TextStreamLimits);
+    write(frame: string): Promise<void>;
+}
+/** Initiate return on abort even for iterators whose next() settles only after return(). */
+export declare function ownIterator(iterator: AsyncIterator<unknown>, signal: AbortSignal): {
+    close: () => Promise<unknown>;
+    dispose: () => void;
+};
+/** Pull only after the previous frame drained; settle iterator cleanup before terminal output. */
+export declare function serveTextStream(res: ServerResponse, source: (signal: AbortSignal) => AsyncIterable<unknown>, options?: TextStreamLimits): Promise<void>;
+//# sourceMappingURL=text-stream.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentium/transport",
-  "version": "4.1.0",
+  "version": "4.6.0",
   "description": "HTTP and WebSocket transport layer for Agentium agents",
   "license": "MIT",
   "publishConfig": {
@@ -25,9 +25,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
       "default": "./dist/index.js"
     }
   },
@@ -35,7 +40,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsdown --config ../../tsdown.config.ts && tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --pretty false",
+    "build": "tsdown --config ../../tsdown.config.ts && tsc -p tsconfig.build.json --emitDeclarationOnly --declaration --pretty false && node ../../scripts/cjs-declarations.mjs",
     "dev": "tsdown --config ../../tsdown.config.ts --watch",
     "prepublishOnly": "npm run build"
   },
@@ -45,7 +50,7 @@
     "tsdown": "0.23.0"
   },
   "peerDependencies": {
-    "@agentium/core": "^4.1.0",
+    "@agentium/core": "^4.6.0",
     "@types/express": "^4.0.0 || ^5.0.0",
     "express": "^4.21.2 || ^5.2.1",
     "multer": "^2.3.0",