@makaio/framework 1.0.0-dev-1784889676396 → 1.0.0-dev-1785344643235

package/dist/{load-extensions-BLdG90Zi.d.mts → load-extensions-BxsDB87B.d.mts}

@@ -1,4 +1,4 @@
-import { t as DiscoveredExtension } from "./extension-discovery-B6p3iZaV.mjs";
+import { t as DiscoveredExtension } from "./extension-discovery-CQRdbVQ6.mjs";
 import { KernelMakaioExtension } from "@makaio/framework/kernel";
 import { CliContribution } from "@makaio/framework/kernel/cli";
 

package/dist/{load-extensions-CUmFCcYi.mjs → load-extensions-D0DfjYLC.mjs}

@@ -1 +1 @@
-import{t as e}from"./descriptor-to-package-VfB8lK5w.mjs";import{pathToFileURL as t}from"node:url";import*as n from"node:path";import*as r from"node:fs";import{versionSatisfies as i}from"@makaio/framework/contracts";async function a(e,t){let{frameworkVersion:n,importModule:r=S}=t,i=[],a=new Map,s;for(let t of e){let{descriptor:e,extensionPath:c}=t,l=`[extensions] ${e.name}@${e.version}`;if(!u(t,n))continue;if(e.execution===`detached`){let t;try{s??=(await import(`./detached-extension-handle-BsywhHfk.mjs`)).createDetachedExtensionPackage,t=s(e,c)}catch(e){console.warn(`${l}: failed to synthesize detached extension package:`,e instanceof Error?e.message:e);continue}i.push(t),e.config?.defaults&&a.set(e.name,e.config.defaults);continue}if(!e.entrypoints.server){!e.entrypoints.browser&&!e.entrypoints.cli&&console.warn(`${l}: no executable entrypoint declared, skipping`);continue}let d;if(t.preloadedModule)d=t.preloadedModule;else try{let t=_(`server`,e.entrypoints.server,c);if(!t){console.warn(`${l}: server entrypoint could not be resolved within extension directory, skipping`);continue}d=await r(t)}catch(e){console.warn(`${l}: failed to import server entry:`,e instanceof Error?e.message:e);continue}let f=o(d.default,e.name,l);f&&(i.push(...f),e.config?.defaults&&a.set(e.name,e.config.defaults))}return{packages:i,configDefaults:a}}function o(e,t,n){if(Array.isArray(e)){let r=[],i=new Set;for(let t of e){if(!f(t)){console.warn(`${n}: default export array contains an invalid MakaioExtension, skipping`);return}if(i.has(t.name)){console.warn(`${n}: default export array contains duplicate package name '${t.name}', skipping`);return}i.add(t.name),r.push(t)}if(!r.some(e=>e.name===t)){console.warn(`${n}: default export array must include a package named '${t}' to match descriptor identity, skipping`);return}if(r.some(e=>e.name!==t&&!e.name.startsWith(`${t}.`))){console.warn(`${n}: default export array contains package names outside descriptor namespace '${t}', skipping`);return}return r}if(!f(e)){console.warn(`${n}: default export is not a valid MakaioExtension or MakaioExtension[], skipping`);return}if(e.name!==t){console.warn(`${n}: imported package name '${e.name}' does not match descriptor name '${t}', skipping`);return}return[e]}async function s(e,t,n){let{importModule:r=S,frameworkVersion:i}=n,a=new Map(t.map(e=>[e.name,e])),o=new Map;for(let t of e){let e=c(t,i);if(!e)continue;let n=`[extensions] ${t.descriptor.name}@${t.descriptor.version}`,s=a.get(t.descriptor.name);if(s?.cli)continue;let u=await d(t,e,n,r);if(!u)continue;if(!p(u.default)){console.warn(`${n}: default export is not a valid CliContribution, skipping`);continue}let f=t.descriptor.cli?.name??t.descriptor.name;if(u.default.name!==f){console.warn(`${n}: imported CLI contribution name '${u.default.name}' does not match descriptor CLI name '${f}', skipping`);continue}if(s){a.set(t.descriptor.name,{...s,cli:u.default});continue}if(t.descriptor.entrypoints?.server||t.descriptor.entrypoints?.browser){console.warn(`${n}: server or browser entry is present but no package was loaded, skipping CLI-only synthesis`);continue}a.set(t.descriptor.name,l(t,u.default)),t.descriptor.config?.defaults&&o.set(t.descriptor.name,t.descriptor.config.defaults)}return{packages:[...a.values()],configDefaults:o}}function c(e,t){if(u(e,t)&&e.descriptor.execution!==`detached`)return e.descriptor.entrypoints?.cli}function l(t,n){return{...e(t.descriptor),cli:n}}function u(e,t){let{descriptor:n}=e,r=`[extensions] ${n.name}@${n.version}`;try{return i(t,n.makaio.framework)?!0:(console.warn(`${r}: requires framework ${n.makaio.framework}, current is ${t}, skipping`),!1)}catch(e){return console.warn(`${r}: invalid version metadata (framework=${t}, range=${n.makaio.framework}), skipping:`,e instanceof Error?e.message:e),!1}}async function d(e,t,n,r){try{let i=_(`cli`,t,e.extensionPath);if(!i){console.warn(`${n}: cli entrypoint has no resolvable candidate within extension directory, skipping`);return}return await r(i)}catch(e){console.warn(`${n}: failed to import cli entry:`,e instanceof Error?e.message:e);return}}function f(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name==`string`&&typeof t.displayName==`string`&&typeof t.version==`string`}function p(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name!=`string`||typeof t.description!=`string`||!Array.isArray(t.subcommands)||`interactive`in t&&t.interactive!==void 0&&typeof t.interactive!=`function`?!1:t.subcommands.length===0?typeof t.interactive==`function`:t.subcommands.every(m)}function m(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name==`string`&&typeof t.description==`string`&&h(t.schema)&&typeof t.handler==`function`}function h(e){return typeof e==`object`&&!!e&&typeof e.safeParse==`function`}function g(e,t){return t===!0?e:t}function _(e,t,r){if(!n.isAbsolute(r))return;let i=g(e,t),a=x(r),o=n.resolve(r,`src`,`${i}.ts`);if(y(o,a))return o;let s=n.resolve(r,`dist`,`${i}.mjs`);if(y(s,a))return s}function v(e,t){let n=x(t);return b(x(e),n)}function y(e,t){try{return b(r.realpathSync(e),t)}catch{return!1}}function b(e,t){return e.startsWith(t+n.sep)}function x(e){let t=n.resolve(e);try{return r.realpathSync(t)}catch{return t}}async function S(e){return await import(t(e).href)}export{f as a,_ as c,u as i,g as n,v as o,p as r,a as s,s as t};
+import{t as e}from"./descriptor-to-package-DvF08krT.mjs";import{pathToFileURL as t}from"node:url";import*as n from"node:path";import*as r from"node:fs";import{versionSatisfies as i}from"@makaio/framework/contracts";async function a(e,t){let{frameworkVersion:n,importModule:r=S}=t,i=[],a=new Map,s;for(let t of e){let{descriptor:e,extensionPath:c}=t,l=`[extensions] ${e.name}@${e.version}`;if(!u(t,n))continue;if(e.execution===`detached`){let t;try{s??=(await import(`./detached-extension-handle-Ddfquy5_.mjs`)).createDetachedExtensionPackage,t=s(e,c)}catch(e){console.warn(`${l}: failed to synthesize detached extension package:`,e instanceof Error?e.message:e);continue}i.push(t),e.config?.defaults&&a.set(e.name,e.config.defaults);continue}if(!e.entrypoints.server){!e.entrypoints.browser&&!e.entrypoints.cli&&console.warn(`${l}: no executable entrypoint declared, skipping`);continue}let d;if(t.preloadedModule)d=t.preloadedModule;else try{let t=_(`server`,e.entrypoints.server,c);if(!t){console.warn(`${l}: server entrypoint could not be resolved within extension directory, skipping`);continue}d=await r(t)}catch(e){console.warn(`${l}: failed to import server entry:`,e instanceof Error?e.message:e);continue}let f=o(d.default,e.name,l);f&&(i.push(...f),e.config?.defaults&&a.set(e.name,e.config.defaults))}return{packages:i,configDefaults:a}}function o(e,t,n){if(Array.isArray(e)){let r=[],i=new Set;for(let t of e){if(!f(t)){console.warn(`${n}: default export array contains an invalid MakaioExtension, skipping`);return}if(i.has(t.name)){console.warn(`${n}: default export array contains duplicate package name '${t.name}', skipping`);return}i.add(t.name),r.push(t)}if(!r.some(e=>e.name===t)){console.warn(`${n}: default export array must include a package named '${t}' to match descriptor identity, skipping`);return}if(r.some(e=>e.name!==t&&!e.name.startsWith(`${t}.`))){console.warn(`${n}: default export array contains package names outside descriptor namespace '${t}', skipping`);return}return r}if(!f(e)){console.warn(`${n}: default export is not a valid MakaioExtension or MakaioExtension[], skipping`);return}if(e.name!==t){console.warn(`${n}: imported package name '${e.name}' does not match descriptor name '${t}', skipping`);return}return[e]}async function s(e,t,n){let{importModule:r=S,frameworkVersion:i}=n,a=new Map(t.map(e=>[e.name,e])),o=new Map;for(let t of e){let e=c(t,i);if(!e)continue;let n=`[extensions] ${t.descriptor.name}@${t.descriptor.version}`,s=a.get(t.descriptor.name);if(s?.cli)continue;let u=await d(t,e,n,r);if(!u)continue;if(!p(u.default)){console.warn(`${n}: default export is not a valid CliContribution, skipping`);continue}let f=t.descriptor.cli?.name??t.descriptor.name;if(u.default.name!==f){console.warn(`${n}: imported CLI contribution name '${u.default.name}' does not match descriptor CLI name '${f}', skipping`);continue}if(s){a.set(t.descriptor.name,{...s,cli:u.default});continue}if(t.descriptor.entrypoints?.server||t.descriptor.entrypoints?.browser){console.warn(`${n}: server or browser entry is present but no package was loaded, skipping CLI-only synthesis`);continue}a.set(t.descriptor.name,l(t,u.default)),t.descriptor.config?.defaults&&o.set(t.descriptor.name,t.descriptor.config.defaults)}return{packages:[...a.values()],configDefaults:o}}function c(e,t){if(u(e,t)&&e.descriptor.execution!==`detached`)return e.descriptor.entrypoints?.cli}function l(t,n){return{...e(t.descriptor),cli:n}}function u(e,t){let{descriptor:n}=e,r=`[extensions] ${n.name}@${n.version}`;try{return i(t,n.makaio.framework)?!0:(console.warn(`${r}: requires framework ${n.makaio.framework}, current is ${t}, skipping`),!1)}catch(e){return console.warn(`${r}: invalid version metadata (framework=${t}, range=${n.makaio.framework}), skipping:`,e instanceof Error?e.message:e),!1}}async function d(e,t,n,r){try{let i=_(`cli`,t,e.extensionPath);if(!i){console.warn(`${n}: cli entrypoint has no resolvable candidate within extension directory, skipping`);return}return await r(i)}catch(e){console.warn(`${n}: failed to import cli entry:`,e instanceof Error?e.message:e);return}}function f(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name==`string`&&typeof t.displayName==`string`&&typeof t.version==`string`}function p(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name!=`string`||typeof t.description!=`string`||!Array.isArray(t.subcommands)||`interactive`in t&&t.interactive!==void 0&&typeof t.interactive!=`function`?!1:t.subcommands.length===0?typeof t.interactive==`function`:t.subcommands.every(m)}function m(e){if(typeof e!=`object`||!e)return!1;let t=e;return typeof t.name==`string`&&typeof t.description==`string`&&h(t.schema)&&typeof t.handler==`function`}function h(e){return typeof e==`object`&&!!e&&typeof e.safeParse==`function`}function g(e,t){return t===!0?e:t}function _(e,t,r){if(!n.isAbsolute(r))return;let i=g(e,t),a=x(r),o=n.resolve(r,`src`,`${i}.ts`);if(y(o,a))return o;let s=n.resolve(r,`dist`,`${i}.mjs`);if(y(s,a))return s}function v(e,t){let n=x(t);return b(x(e),n)}function y(e,t){try{return b(r.realpathSync(e),t)}catch{return!1}}function b(e,t){return e.startsWith(t+n.sep)}function x(e){let t=n.resolve(e);try{return r.realpathSync(t)}catch{return t}}async function S(e){return await import(t(e).href)}export{f as a,_ as c,u as i,g as n,v as o,p as r,a as s,s as t};

package/dist/{materialization-s8eR1eQ4.mjs → materialization-Jd198K3y.mjs}

@@ -1 +1 @@
-import{A as e,B as t,D as n,M as r,l as i}from"./schemas-BRxU_oqL.mjs";import{z as a}from"zod";import{createBusNamespace as o}from"@makaio/framework/core";const s=r.extend({ref:i,affordance:e}),c=a.discriminatedUnion(`status`,[a.object({status:a.literal(`ok`),view:t,builderVersion:a.number().int().positive(),sourceRevision:a.string().min(1)}),a.object({status:a.literal(`artifact-not-found`),view:a.null()}),a.object({status:a.literal(`not-rendered`),view:a.null()})]),l={"surfaceBinding.register":{request:n,response:a.object({registered:a.boolean()})},"surfaceBinding.list":{request:a.object({id:a.string().min(1).optional(),provider:a.string().min(1).optional(),namespace:a.string().min(1).optional()}),response:a.object({bindings:a.array(n)})},"surfaceBinding.changed":a.object({id:a.string().min(1),provider:a.string().min(1)}),"ref.changed":a.object({artifactId:a.string().min(1),provider:a.string().min(1),externalId:a.string().min(1),operation:a.enum([`upserted`,`deleted`]),origin:a.enum([`factory`,`external`]).optional()}),"capability.resolved":a.object({provider:a.string().min(1),surface:a.string().min(1),capabilities:a.record(a.string().min(1),a.boolean()),degraded:a.boolean()}),"artifact.view.resolve":{request:s,response:c}},u=o(`materialization`,l),d=u.subjects;function f(e){return{id:e.id,toRegistration:()=>({id:e.id,provider:e.provider,namespace:e.namespace,target:structuredClone(e.target),appliesTo:[...e.appliesTo],...e.valueMapping===void 0?{}:{valueMapping:{...e.valueMapping}},...e.description===void 0?{}:{description:e.description},...e.params===void 0?{}:{params:structuredClone(e.params)}})}}export{l as a,u as i,s as n,d as o,c as r,f as t};
+import{A as e,B as t,D as n,M as r,l as i}from"./schemas-CRB2O5zo.mjs";import{z as a}from"zod";import{createBusNamespace as o}from"@makaio/framework/core";const s=r.extend({ref:i,affordance:e}),c=a.discriminatedUnion(`status`,[a.object({status:a.literal(`ok`),view:t,builderVersion:a.number().int().positive(),sourceRevision:a.string().min(1)}),a.object({status:a.literal(`artifact-not-found`),view:a.null()}),a.object({status:a.literal(`not-rendered`),view:a.null()})]),l={"surfaceBinding.register":{request:n,response:a.object({registered:a.boolean()})},"surfaceBinding.list":{request:a.object({id:a.string().min(1).optional(),provider:a.string().min(1).optional(),namespace:a.string().min(1).optional()}),response:a.object({bindings:a.array(n)})},"surfaceBinding.changed":a.object({id:a.string().min(1),provider:a.string().min(1)}),"ref.changed":a.object({artifactId:a.string().min(1),provider:a.string().min(1),externalId:a.string().min(1),operation:a.enum([`upserted`,`deleted`]),origin:a.enum([`factory`,`external`]).optional()}),"capability.resolved":a.object({provider:a.string().min(1),surface:a.string().min(1),capabilities:a.record(a.string().min(1),a.boolean()),degraded:a.boolean()}),"artifact.view.resolve":{request:s,response:c}},u=o(`materialization`,l),d=u.subjects;function f(e){return{id:e.id,toRegistration:()=>({id:e.id,provider:e.provider,namespace:e.namespace,target:structuredClone(e.target),appliesTo:[...e.appliesTo],...e.valueMapping===void 0?{}:{valueMapping:{...e.valueMapping}},...e.description===void 0?{}:{description:e.description},...e.params===void 0?{}:{params:structuredClone(e.params)}})}}export{l as a,u as i,s as n,d as o,c as r,f as t};

package/dist/mcp-http-server/index.d.mts

@@ -4,7 +4,7 @@ import { BaseService } from "@makaio/framework/service-base";
 import { McpToolDefinition, ToolInfo } from "@makaio/framework/tools";
 import { IncomingMessage, ServerResponse } from "node:http";
 import { Server as Server$1 } from "@modelcontextprotocol/sdk/server/index.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 
 //#region subsystems/mcp-http-server/src/context-registry.d.ts
@@ -60,32 +60,6 @@ declare class McpContextRegistry implements IMcpContextRegistry {
   unregister(adapterSessionId: string): void;
 }
 //#endregion
-//#region subsystems/mcp-http-server/src/approve-tool.d.ts
-/** MCP tool name for the permission prompt handler. */
-declare const APPROVE_TOOL_NAME = "approve";
-/** Payload forwarded to `agent.toolApprove`. */
-interface ToolApproveRequestPayload {
-  toolName: string;
-  args: Record<string, unknown>;
-  toolCallId: string;
-  agentId: string;
-  adapterId: string;
-  adapterName: string;
-  adapterSessionId: string;
-  /** Makaio session ID — required for approval routing to the owning tab. */
-  sessionId: string;
-}
-/** Minimal response shape consumed from `agent.toolApprove`. */
-type ToolApproveResponse = {
-  action: 'allow';
-  updatedInput?: Record<string, unknown>;
-} | {
-  action: 'deny';
-  message?: string;
-};
-/** Function seam for approval RPC. */
-type RequestToolApproval = (payload: ToolApproveRequestPayload) => Promise<ToolApproveResponse>;
-//#endregion
 //#region subsystems/mcp-http-server/src/tool-discovery.d.ts
 /**
  * Maps a runtime toolset name to the plugin that owns it.
@@ -225,45 +199,34 @@ interface CreateMcpServerOptions extends ToolExecutionTimeoutOption {
 interface HttpMcpHandlerOptions extends ToolExecutionTimeoutOption {
   agentContext?: McpAgentContext$1;
   toolDiscovery?: McpToolDiscoveryOptions;
+  /**
+   * Fires once when the endpoint itself closes.
+   *
+   * It does **not** fire when an individual MCP client disconnects or
+   * terminates its session: one endpoint serves many MCP clients, and their
+   * comings and goings are not endpoint lifecycle events.
+   */
   onclose?: () => void;
   resolveContextOverrides?: ResolveContextOverrides;
+  /**
+   * Idle time (ms) with no open HTTP exchange before an MCP client session is
+   * closed. A client holding its standalone SSE stream is never idle. Defaults
+   * to 10 minutes.
+   */
+  idleTimeoutMs?: number;
+  /** Interval (ms) between idle-session sweeps. Defaults to 60 seconds. */
+  sweepIntervalMs?: number;
 }
 /** Options for starting a standalone HTTP MCP server. */
 interface HttpMcpServerOptions extends HttpMcpHandlerOptions {
   port?: number;
 }
 //#endregion
-//#region subsystems/mcp-http-server/src/server.d.ts
+//#region subsystems/mcp-http-server/src/create-mcp-server.d.ts
 /** Query parameter name used by adapters to pass the session ID when custom headers are not available. */
 declare const ADAPTER_SESSION_ID_PARAM = "adapterSessionId";
 /** HTTP header name that carries the adapter session ID after query-param promotion. */
 declare const ADAPTER_SESSION_ID_HEADER = "x-adapter-session-id";
-/**
- * Result returned by {@link createHttpMcpHandler}.
- *
- * Provides a Node.js-compatible request handler that can be mounted on any
- * HTTP stack that exposes the raw `IncomingMessage` / `ServerResponse` pair,
- * plus lifecycle handles for the underlying MCP server. See
- * {@link createHttpMcpHandler} for usage and mounting examples.
- */
-interface HttpMcpHandlerHandle {
-  /**
-   * Mount this on any Node-compatible HTTP stack.
-   *
-   * The handler parses the raw request body internally; do not pre-read or
-   * pre-parse the body before passing the request to this function.
-   */
-  readonly handler: (req: IncomingMessage, res: ServerResponse) => void;
-  /** Context registry for registering and unregistering agent sessions. */
-  readonly contextRegistry: IMcpContextRegistry;
-  /**
-   * Gracefully close the MCP server and its transport.
-   *
-   * Idempotent: repeated calls await the same underlying close operation and
-   * do not trigger a second teardown.
-   */
-  close(): Promise<void>;
-}
 /**
  * Create and configure MCP server.
  *
@@ -308,23 +271,60 @@ declare function createMcpServer(bus: IMakaioBus, sessionId: string, options?: C
     } | undefined;
   } | undefined;
 }>>;
+//#endregion
+//#region subsystems/mcp-http-server/src/approve-tool.d.ts
+/** MCP tool name for the permission prompt handler. */
+declare const APPROVE_TOOL_NAME = "approve";
+/** Payload forwarded to `agent.toolApprove`. */
+interface ToolApproveRequestPayload {
+  toolName: string;
+  args: Record<string, unknown>;
+  toolCallId: string;
+  agentId: string;
+  adapterId: string;
+  adapterName: string;
+  adapterSessionId: string;
+  /** Makaio session ID — required for approval routing to the owning tab. */
+  sessionId: string;
+}
+/** Minimal response shape consumed from `agent.toolApprove`. */
+type ToolApproveResponse = {
+  action: 'allow';
+  updatedInput?: Record<string, unknown>;
+} | {
+  action: 'deny';
+  message?: string;
+};
+/** Function seam for approval RPC. */
+type RequestToolApproval = (payload: ToolApproveRequestPayload) => Promise<ToolApproveResponse>;
+//#endregion
+//#region subsystems/mcp-http-server/src/server.d.ts
 /**
- * Create a framework-agnostic HTTP request handler that delegates to
- * {@link StreamableHTTPServerTransport.handleRequest}.
- *
- * **External consumers should prefer {@link createHttpMcpHandler}**, which
- * constructs the transport internally so no MCP SDK type needs to appear in
- * caller code.  This lower-level function is exposed for internal composition
- * and testing.
- *
- * The transport handles body parsing internally; do not pre-parse the body
- * before calling this handler, as that would consume the request stream before
- * MCP can read it.
- * @param transport - Streamable HTTP transport instance connected to the server.
- * @param onBeforeDispatch - Optional hook called synchronously before request dispatch.
- * @returns Node.js-compatible request handler.
+ * Result returned by {@link createHttpMcpHandler}.
+ *
+ * Provides a Node.js-compatible request handler that can be mounted on any
+ * HTTP stack that exposes the raw `IncomingMessage` / `ServerResponse` pair,
+ * plus lifecycle handles for the underlying MCP server. See
+ * {@link createHttpMcpHandler} for usage and mounting examples.
  */
-declare function createMcpRequestHandler(transport: StreamableHTTPServerTransport, onBeforeDispatch?: (req: IncomingMessage, res: ServerResponse) => void): (req: IncomingMessage, res: ServerResponse) => void;
+interface HttpMcpHandlerHandle {
+  /**
+   * Mount this on any Node-compatible HTTP stack.
+   *
+   * The handler parses the raw request body internally; do not pre-read or
+   * pre-parse the body before passing the request to this function.
+   */
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => void;
+  /** Context registry for registering and unregistering agent sessions. */
+  readonly contextRegistry: IMcpContextRegistry;
+  /**
+   * Gracefully close the endpoint and every MCP client session it owns.
+   *
+   * Idempotent: repeated calls await the same underlying close operation and
+   * do not trigger a second teardown.
+   */
+  close(): Promise<void>;
+}
 /**
  * Create a mountable MCP handler without starting a dedicated HTTP server.
  *
@@ -334,6 +334,12 @@ declare function createMcpRequestHandler(transport: StreamableHTTPServerTranspor
  * framework exposing the raw `IncomingMessage` / `ServerResponse` pair (e.g.
  * Hono's Node adapter via `(c) => { handler(c.env.incoming, c.env.outgoing); }`).
  *
+ * The endpoint serves **many concurrent MCP clients**. Each client gets its own
+ * `(transport, server)` pair keyed by the MCP protocol session ID; see
+ * {@link McpTransportRegistry} for the full lifecycle contract. This is
+ * independent of the adapter session carried by the `adapterSessionId` query
+ * param, of which many may share a single MCP client.
+ *
  * The MCP SDK transport is constructed and managed internally — no MCP SDK
  * types appear in the public API.
  *
@@ -341,8 +347,8 @@ declare function createMcpRequestHandler(transport: StreamableHTTPServerTranspor
  * rate limiting, or logging in the surrounding HTTP stack *before* delegating
  * to the returned handler.
  *
- * Closing the handle shuts down the MCP server and its transport; active
- * HTTP connections are left to the caller's HTTP stack.
+ * Closing the handle shuts down every live MCP client session; active HTTP
+ * connections are left to the caller's HTTP stack.
  * @param bus - Bus instance for tool execution and approval RPC.
  * @param options - Handler options; all fields are optional.
  * @returns Handle with the request handler function, context registry, and
@@ -390,10 +396,11 @@ declare function startHttpMcpServer(bus: IMakaioBus, options?: HttpMcpServerOpti
  *
  * For the stdio transport, returns a {@link StdioMcpServerHandle} whose
  * `close()` method gracefully tears down the MCP server. Pass
- * `options.onclose` to receive a single callback when the transport closes for
- * any reason (client detach via stdin EOF, or explicit `handle.close()`). Pass
- * `options.resolveContextOverrides` to resolve current execution context on
- * every tool call, including calls after client reconnects.
+ * `options.onclose` to receive a single callback when the server stops serving:
+ * for stdio that is client detach via stdin EOF or an explicit `handle.close()`;
+ * for HTTP it is endpoint shutdown only, never an individual MCP client
+ * disconnecting. Pass `options.resolveContextOverrides` to resolve current
+ * execution context on every tool call, including calls after client reconnects.
  * Signal handling is intentionally left to the composition root — library code
  * must not own process-global resources such as `process.on('SIGINT')`.
  * @param bus - Bus instance.
@@ -425,7 +432,7 @@ interface FetchMcpHandlerHandle {
   /** Context registry for registering and unregistering agent sessions. */
   readonly contextRegistry: IMcpContextRegistry;
   /**
-   * Gracefully close the MCP server and its transport.
+   * Gracefully close the endpoint and every MCP client session it owns.
    *
    * Idempotent: repeated calls await the same underlying close operation and
    * do not trigger a second teardown.
@@ -442,6 +449,10 @@ interface FetchMcpHandlerHandle {
  * Web Standard `Request` and returns a `Promise<Response>`. Mount it on Hono,
  * Bun.serve, Cloudflare Workers, Deno, or any other fetch-compatible HTTP stack.
  *
+ * The endpoint serves many concurrent MCP clients, one `(transport, server)`
+ * pair per MCP protocol session; see `McpTransportRegistry` for the lifecycle
+ * contract shared with the Node handler.
+ *
  * ```ts
  * import { createFetchMcpHandler } from '@makaio/framework/mcp-http-server';
  *
@@ -469,6 +480,217 @@ interface FetchMcpHandlerHandle {
  */
 declare function createFetchMcpHandler(bus: IMakaioBus, options?: HttpMcpHandlerOptions): Promise<FetchMcpHandlerHandle>;
 //#endregion
+//#region subsystems/mcp-http-server/src/mcp-http-errors.d.ts
+/** Reasons the registry declined to dispatch a request to a transport. */
+type McpRouteFailure = 'unknown-session' | 'session-id-required' | 'closed' | 'create-failed';
+//#endregion
+//#region subsystems/mcp-http-server/src/mcp-transport-registry.d.ts
+/**
+ * Hooks the registry injects into the transport it asks the caller to build.
+ *
+ * The caller must forward {@link McpSessionHooks.onSessionInitialized} to the
+ * transport's `onsessioninitialized` option — that callback is the registry's
+ * only admission point.
+ */
+interface McpSessionHooks {
+  /**
+   * Admit a freshly initialized session under its MCP session ID.
+   * @param mcpSessionId - Session ID the transport generated during `initialize`.
+   */
+  onSessionInitialized(mcpSessionId: string): void;
+}
+/**
+ * Build one unconnected `(transport, server)` pair.
+ *
+ * The factory must only construct: the registry owns wiring, connecting, and
+ * teardown. The transport must expose `sessionId` once initialized.
+ */
+type CreateMcpSession<T extends Transport> = (hooks: McpSessionHooks) => Promise<{
+  transport: T;
+  server: Server$1;
+}>;
+/** Configuration for {@link McpTransportRegistry}. */
+interface McpTransportRegistryOptions<T extends Transport> {
+  /** Builds one unconnected `(transport, server)` pair per MCP client session. */
+  createSession: CreateMcpSession<T>;
+  /** Idle time with zero open exchanges before a session is closed. Defaults to 10 minutes. */
+  idleTimeoutMs?: number;
+  /** Sweep cadence for idle sessions. Defaults to 60 seconds. */
+  sweepIntervalMs?: number;
+}
+/** A request reduced to what routing actually depends on. */
+interface McpRouteRequest {
+  /** HTTP method of the incoming request. */
+  method: string;
+  /** Value of the `Mcp-Session-Id` header, when present. */
+  mcpSessionId: string | undefined;
+}
+/** Routing outcome for a session that could not be built or connected. */
+interface McpCreateFailureResult {
+  outcome: 'create-failed';
+  /** Cause of the failure, already logged by the registry. */
+  error: unknown;
+}
+/** Outcome of routing one request. */
+type McpRouteResult<T extends Transport> = {
+  outcome: 'dispatch'; /** Transport that owns this MCP session. */
+  transport: T; /** Releases the activity lease; safe to call more than once. */
+  finish(): void;
+} | {
+  outcome: Exclude<McpRouteFailure, 'create-failed'>;
+} | McpCreateFailureResult;
+/**
+ * Registry owning one `(transport, server)` pair per MCP protocol session.
+ *
+ * Generic over the transport so the Node and fetch handlers share one routing
+ * and lifecycle implementation instead of duplicating it per transport family.
+ */
+declare class McpTransportRegistry<T extends Transport> {
+  private readonly sessions;
+  private readonly pending;
+  /**
+   * In-flight session constructions.
+   *
+   * Third link in the ownership chain: a pair belongs to `startups` while it
+   * is being built, to `pending` once built but not yet initialized, and to
+   * `sessions` after admission. `closeAll()` drains all three in that order,
+   * so no phase of a pair's life can outlive a resolved shutdown.
+   */
+  private readonly startups;
+  /** In-flight background disposals started by the sweep or a lease release. */
+  private readonly disposals;
+  private readonly createSession;
+  private readonly idleTimeoutMs;
+  private readonly sweepTimer;
+  private closed;
+  /** Shared teardown, so every `closeAll()` caller awaits the same shutdown. */
+  private closePromise;
+  /**
+   * @param options - Session factory plus idle-reaping configuration.
+   * @throws RangeError When `idleTimeoutMs` or `sweepIntervalMs` is not a
+   *   positive finite number, or when `sweepIntervalMs` exceeds the runtime's
+   *   timer ceiling. Only the sweep interval is bounded by it: the idle timeout
+   *   is clock arithmetic, so a multi-week idle policy is legitimate.
+   */
+  constructor(options: McpTransportRegistryOptions<T>);
+  /**
+   * Admitted MCP client sessions.
+   * @returns Number of routable sessions currently held by the registry. A pair
+   *   whose `initialize` has not completed yet is not one of them.
+   */
+  get size(): number;
+  /**
+   * Resolve one request to a transport, or to the reason it cannot be served.
+   *
+   * Never rejects: a session that fails to build is reported as the
+   * `create-failed` outcome so callers have a single error surface.
+   * @param request - Method and `Mcp-Session-Id` of the incoming request.
+   * @returns The transport to dispatch to plus its lease, or a failure outcome.
+   */
+  route(request: McpRouteRequest): Promise<McpRouteResult<T>>;
+  /**
+   * Close every live pair and stop reaping.
+   *
+   * "Live" means both owner sets: an admitted session and a pair that has been
+   * built but has not initialized yet are equally real servers holding equally
+   * real bus subscriptions, and shutdown has to wait for both. Draining only
+   * the map would leave a pending pair to be disposed by its lease release,
+   * which an abandoned response can defer indefinitely.
+   *
+   * After this resolves the registry refuses all further routing. Concurrent
+   * and repeat callers all await the same shared teardown: without that, a
+   * second caller would observe the already-cleared owner sets and resolve
+   * while the first caller's teardown is still in flight.
+   * @returns Promise resolving once every pair has been torn down.
+   */
+  closeAll(): Promise<void>;
+  /**
+   * Tear down every owner set in lifecycle order.
+   * @returns Promise resolving once every pair has been torn down.
+   */
+  private drainAll;
+  /**
+   * Dispose a pair in the background, keeping the disposal owned until done.
+   *
+   * Used by the paths that cannot await a close — the sweep and the lease
+   * release — so `drainAll()` can still wait for every in-flight teardown.
+   * The raw close promise is what gets tracked: a rejection must stay visible
+   * to shutdown's aggregation, so background reporting happens on a separate
+   * chain that also keeps the rejection from going unhandled.
+   * @param record - Pair whose server is being closed.
+   */
+  private disposeInBackground;
+  /**
+   * Apply the routing rules for one request.
+   * @param request - Method and `Mcp-Session-Id` of the incoming request.
+   * @returns The routing outcome.
+   */
+  private resolve;
+  /**
+   * Take an activity lease on a session and hand back its transport.
+   * @param record - Session to lease.
+   * @returns Dispatch outcome carrying the lease release callback.
+   */
+  private lease;
+  /**
+   * Build a new session as a tracked startup task.
+   *
+   * The construction itself spans two awaits (`createSession`, `connect`)
+   * during which the pair exists in neither owner set. Registering the whole
+   * task in `startups` closes that window: `closeAll()` awaits these tasks, so
+   * a shutdown overlapping a slow factory or connect waits for the pair to be
+   * built and self-disposed instead of resolving while its server and bus
+   * subscription are still coming up.
+   * @returns Dispatch outcome for the new session, or `create-failed`.
+   */
+  private createPending;
+  /**
+   * Build, wire, and connect a new session, then lease it for this request.
+   * @returns Dispatch outcome for the new session, or `create-failed`.
+   */
+  private buildAndLeasePending;
+  /** Close every session that has been idle with no open exchanges. */
+  private sweep;
+}
+//#endregion
+//#region subsystems/mcp-http-server/src/mcp-endpoint.d.ts
+/**
+ * Build one unconnected transport for a new MCP client session.
+ *
+ * The implementation must forward {@link McpSessionHooks.onSessionInitialized}
+ * to the transport's `onsessioninitialized` option, which is the registry's
+ * only admission point.
+ */
+type CreateMcpTransport<T extends Transport> = (hooks: McpSessionHooks) => T;
+/** The transport-independent half of an MCP HTTP endpoint. */
+interface McpEndpoint<T extends Transport> {
+  /** Routes requests to the transport owning their MCP protocol session. */
+  readonly registry: McpTransportRegistry<T>;
+  /** Context registry for registering and unregistering adapter sessions. */
+  readonly contextRegistry: IMcpContextRegistry;
+  /**
+   * Close every MCP client session and fire the caller's `onclose` once.
+   *
+   * Idempotent: repeated calls await the same underlying teardown.
+   * @returns Promise resolving once teardown has settled.
+   */
+  close(): Promise<void>;
+}
+/**
+ * Assemble the transport-independent half of an MCP HTTP endpoint.
+ *
+ * Sessions are built lazily, on the first request that opens one, so option
+ * validation runs here rather than in the session factory: a misconfigured
+ * endpoint must fail at creation time instead of surfacing as a 500 on
+ * someone's first tool call.
+ * @param bus - Bus instance for tool execution and approval RPC.
+ * @param options - Handler options shared by both HTTP handler flavours.
+ * @param createTransport - Builds the SDK transport for one client session.
+ * @returns The endpoint's registry, context registry, and close gate.
+ * @throws RangeError When a timeout or reaping duration option is out of range.
+ */
+declare function createMcpEndpoint<T extends Transport>(bus: IMakaioBus, options: HttpMcpHandlerOptions, createTransport: CreateMcpTransport<T>): McpEndpoint<T>;
+//#endregion
 //#region subsystems/mcp-http-server/src/mcp-server-bridge-service.d.ts
 /**
  * Singleton bus service that manages the HTTP MCP server lifecycle.
@@ -478,13 +700,17 @@ declare function createFetchMcpHandler(bus: IMakaioBus, options?: HttpMcpHandler
  * using a coalescing promise so concurrent registrations never start two
  * server instances.
  *
- * The service maintains three parallel session stores:
+ * Everything here is keyed by **adapter** session, not by MCP protocol session:
+ * many adapter sessions share one endpoint, and each connected MCP client owns
+ * a separate protocol session that the HTTP server manages internally.
+ *
+ * The service maintains three parallel adapter-session stores:
  * - `pinnedSessions` (plain Map) — sessions exempt from both TTL sweep and
  *   LRU count-eviction; only removed by explicit `mcp.session.unregister` or
  *   on server close
  * - `sessions` (QuickLRU) — non-pinned sessions subject to TTL/LRU eviction
  * - `contextRegistry` (Map-backed, inside the HTTP server handle) — source of
- *   truth for the MCP server's per-request routing
+ *   truth for resolving an adapter session's agent context on every MCP request
  *
  * The `resolveContextOverrides` callback threaded into `startHttpMcpServer`
  * bridges these stores so tool execution always uses session-stable
@@ -677,4 +903,4 @@ interface McpClientBridgeOptions {
  */
 declare function startMcpClientBridge(options: McpClientBridgeOptions): Promise<McpClientBridgeHandle>;
 //#endregion
-export { ADAPTER_SESSION_ID_HEADER, ADAPTER_SESSION_ID_PARAM, APPROVE_TOOL_NAME, type CreateMcpServerOptions, type FetchMcpHandlerHandle, type HttpMcpHandlerHandle, type HttpMcpHandlerOptions, type HttpMcpServerHandle, type HttpMcpServerOptions, type IMcpContextRegistry, type McpAgentContext, type McpBridgedTool, type McpCallToolResult, type McpClientBridgeHandle, type McpClientBridgeOptions, McpContextRegistry, type McpResolvedTools, McpServerBridgeService, type McpServerOptions, type McpToolDiscoveryIdentity, type McpToolDiscoveryOptions, type McpToolEntry, type PluginToolsetMap, type RequestToolApproval, type ResolveContextOverrides, type StdioMcpServerHandle, type ToolApproveRequestPayload, type ToolApproveResponse, createFetchMcpHandler, createHttpMcpHandler, createMcpRequestHandler, createMcpServer, resolveMcpTools, startHttpMcpServer, startMcpClientBridge, startMcpServer, toolInfoToMcpTool };
+export { ADAPTER_SESSION_ID_HEADER, ADAPTER_SESSION_ID_PARAM, APPROVE_TOOL_NAME, type CreateMcpServerOptions, type CreateMcpSession, type CreateMcpTransport, type FetchMcpHandlerHandle, type HttpMcpHandlerHandle, type HttpMcpHandlerOptions, type HttpMcpServerHandle, type HttpMcpServerOptions, type IMcpContextRegistry, type McpAgentContext, type McpBridgedTool, type McpCallToolResult, type McpClientBridgeHandle, type McpClientBridgeOptions, McpContextRegistry, type McpCreateFailureResult, type McpEndpoint, type McpResolvedTools, type McpRouteRequest, type McpRouteResult, McpServerBridgeService, type McpServerOptions, type McpSessionHooks, type McpToolDiscoveryIdentity, type McpToolDiscoveryOptions, type McpToolEntry, McpTransportRegistry, type McpTransportRegistryOptions, type PluginToolsetMap, type RequestToolApproval, type ResolveContextOverrides, type StdioMcpServerHandle, type ToolApproveRequestPayload, type ToolApproveResponse, createFetchMcpHandler, createHttpMcpHandler, createMcpEndpoint, createMcpServer, resolveMcpTools, startHttpMcpServer, startMcpClientBridge, startMcpServer, toolInfoToMcpTool };