@corbits/mcp 0.3.1 → 0.4.0

package/dist/tool.js

@@ -2,8 +2,10 @@
 // each is grantable individually. Discovery runs up front because
 // `createAgent` calls a tool factory synchronously.
 import { defineTool, } from "@intx/agent";
-import { DEFAULT_TIMEOUT_MS, mcpCallTool, mcpInitialize, mcpListTools, } from "./client.js";
-import { assertCatalogNames, assertServers, isAskExempt, qualifiedName, toolDescription, } from "./naming.js";
+import { DEFAULT_TIMEOUT_MS, mcpCallTool, mcpConnect, mcpListTools, } from "./client.js";
+import { assertCatalogNames, assertServers, isAskExempt, isModelVisible, qualifiedName, toolDescription, } from "./naming.js";
+import { assertHostExtensions, hostClientOptions, } from "./interchange/client/capabilities.js";
+import { projectToolResult } from "./interchange/client/projection.js";
 async function resolveFetch(server, credentials) {
     if (server.credentialHandle === undefined)
         return undefined;
@@ -24,6 +26,7 @@ async function resolveFetch(server, credentials) {
 export async function mcpTools(options, discoveryEnv = {}) {
     const allowWithoutAsk = options.allowWithoutAsk ?? [];
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    assertHostExtensions(options.extensions, options.host);
     assertServers(options.servers, "MCP server name");
     const discovered = [];
     for (const server of options.servers) {
@@ -31,14 +34,18 @@ export async function mcpTools(options, discoveryEnv = {}) {
         const clientOpts = {
             ...(clientFetch !== undefined ? { fetch: clientFetch } : {}),
             timeoutMs,
+            ...hostClientOptions(options.host, options.extensions),
+            ...(options.extensions !== undefined
+                ? { extensions: options.extensions }
+                : {}),
         };
-        const session = await mcpInitialize(server.url, clientOpts);
+        const session = await mcpConnect(server.url, clientOpts);
         const tools = await mcpListTools(server.url, { ...clientOpts, session });
         assertCatalogNames(server.name, tools);
-        for (const tool of tools) {
+        for (const tool of tools.filter(isModelVisible)) {
             discovered.push({
-                server,
-                tool,
+                server: { ...server },
+                tool: structuredClone(tool),
                 qualified: qualifiedName(server.name, tool.name),
             });
         }
@@ -77,8 +84,12 @@ export async function mcpTools(options, discoveryEnv = {}) {
                         const opts = {
                             ...(clientFetch !== undefined ? { fetch: clientFetch } : {}),
                             timeoutMs,
+                            ...hostClientOptions(options.host, options.extensions),
+                            ...(options.extensions !== undefined
+                                ? { extensions: options.extensions }
+                                : {}),
                         };
-                        const session = await mcpInitialize(server.url, opts);
+                        const session = await mcpConnect(server.url, opts);
                         return { ...opts, session };
                     })();
                     clientByServer.set(server.name, client);
@@ -97,22 +108,27 @@ export async function mcpTools(options, discoveryEnv = {}) {
                         };
                     }
                     try {
-                        const result = await connect(found.server)
-                            .then((client) => mcpCallTool(found.server.url, found.tool.name, call.arguments, {
-                            ...client,
+                        const context = {
+                            server: found.server.name,
+                            url: found.server.url,
+                            tool: found.qualified,
+                            callId: call.id,
+                            signal,
+                        };
+                        await options.host?.validateCatalog?.(context, found.tool);
+                        const client = {
+                            ...(await connect(found.server)),
                             signal,
-                        }))
-                            .catch((cause) => {
+                            inputSchema: found.tool.inputSchema,
+                            ...(found.tool.outputSchema === undefined
+                                ? {}
+                                : { outputSchema: found.tool.outputSchema }),
+                        };
+                        const result = await mcpCallTool(found.server.url, found.tool.name, call.arguments, client).catch((cause) => {
                             clientByServer.delete(found.server.name);
                             throw cause;
                         });
-                        return {
-                            callId: call.id,
-                            isError: result.isError === true,
-                            content: typeof result.content === "string"
-                                ? result.content
-                                : JSON.stringify(result.content),
-                        };
+                        return await projectToolResult(context, result, client, options.host);
                     }
                     catch (err) {
                         return {

package/dist/url.js

@@ -11,12 +11,17 @@ export function parseMcpEndpoint(raw) {
     try {
         url = new URL(raw);
     }
-    catch (cause) {
-        throw new Error(`"${raw}" is not an absolute URL (${cause instanceof Error ? cause.message : String(cause)})`);
+    catch {
+        throw new Error("MCP endpoint is not an absolute URL");
     }
+    if (url.username || url.password || raw.includes("#") || /[\\\s]/.test(raw)) {
+        throw new Error("MCP endpoint must not contain userinfo, fragments, whitespace or backslashes");
+    }
+    if (url.searchParams.has("access_token"))
+        throw new Error("MCP bearer tokens must not appear in URL query parameters");
     if (url.protocol === "https:")
         return url;
     if (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname))
         return url;
-    throw new Error(`MCP endpoint "${raw}" must be https (http is allowed only on loopback)`);
+    throw new Error("MCP endpoint must be https (http is allowed only on loopback)");
 }

package/docs/conformance.md

@@ -0,0 +1,135 @@
+# Conformance evidence and release gates
+
+Snapshot: 2026-10-25. This matrix records implemented scope, assertion locators
+and qualified evidence, not a blanket MCP compliance verdict. The integration
+gate passed final QA with 423 tests and 2,116 assertions; qualified build, e2e
+and package evidence is recorded separately in integration-status.md. Counts do not prove every
+normative clause or deployment. No stale missing-export or mandatory-OAuth
+blocker applies to the current package.
+
+## Revision and maturity matrix
+
+| Surface           | Revision/source                                                                                                                                                                           | Maturity                        | Applicability                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
+| MCP core          | [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28)                                                                                                                    | Released                        | Stateless Streamable HTTP client/server                                                 |
+| Legacy MCP client | 2025-11-25, 2025-06-18, 2025-03-26, historical 2024-11-05 negotiation                                                                                                                     | Compatibility                   | Initialize/session path; no claim of removed HTTP+SSE transport support                 |
+| Legacy MCP server | 2025-11-25, 2025-06-18, 2025-03-26                                                                                                                                                        | Gated compatibility             | Opt-in implemented; session affinity required; final scoped independent legacy approval |
+| Tasks             | [2026-07-28, b3d28aceaa6d49f5f92258e3d06b61ad6f111e84](https://github.com/modelcontextprotocol/ext-tasks/blob/b3d28aceaa6d49f5f92258e3d06b61ad6f111e84/specification/2026-07-28/tasks.md) | Stable upstream                 | Opt-in; tools/call only; durable host services required                                 |
+| Skills            | [stable, c1aa87e4c381c82b99aa37471d0eae4ab50f9985](https://github.com/modelcontextprotocol/ext-skills/blob/c1aa87e4c381c82b99aa37471d0eae4ab50f9985/specification/stable/skills.mdx)      | Stable upstream                 | Core 2026-07-28+; verification is not activation                                        |
+| Apps              | [2026-01-26, 266a9e3b70dbd4a4f0546dda95da2a2c1a8be4b7](https://github.com/modelcontextprotocol/ext-apps/blob/266a9e3b70dbd4a4f0546dda95da2a2c1a8be4b7/specification/2026-01-26/apps.mdx)  | Stable upstream                 | Explicit host bridge/support/presentation gate; renderer remains host-owned             |
+| Interchange       | Installed @intx packages 0.5.0                                                                                                                                                            | Executable integration baseline | Actual ToolBundle, credential and Agent contracts, not fabricated upstream APIs         |
+| MCP SDK           | 1.30.1, development only                                                                                                                                                                  | Legacy interoperability oracle  | Does not certify 2026 behavior                                                          |
+
+All three extensions are disabled by default. Stable upstream does not mean every
+host supports them. No `/v2` MCP methods, extension identifiers or protocol names
+are introduced. Actual experimental additions require an `unstable_` local API,
+source pin and migration policy. The Apps UI protocol revision is independent of
+the core MCP revision.
+
+[Claude Code documentation](https://code.claude.com/docs/en/mcp) describes a
+2026 runtime and task public beta on CLI 2.1.304+ with runtime, provider and surface
+restrictions. This is not evidence for universal Claude Desktop/web/CLI support.
+Blank community-matrix cells are not positive support evidence.
+
+## Requirement matrix
+
+C = standalone client; S = server; IC/IS = Interchange consumption/exposure.
+The listed suites provide scoped evidence. Core F1–F11, auth neutral isolation,
+Apps gating and large Skills bounds have reported independent approvals.
+Legacy has final scoped independent approval; final reconciled QA passed.
+Clauses without a dedicated exhaustive
+mapping remain **unverified for full clause coverage**, not “missing tests” or
+“missing implementation.”
+
+| ID  | Normative clause / requirement                                                                                                                                                                                                                                                                                                    | Role / applicability              | Current evidence locator                                                                                                | Qualification                                                                  |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| C01 | [Basic](https://modelcontextprotocol.io/specification/2026-07-28/basic): JSON-RPC envelopes, required per-request _meta                                                                                                                                                                                                           | C/S, modern                       | src/protocol/protocol.test.ts; src/client/contracts.test.ts; src/server/server.test.ts                                  | Scoped suite evidence; full clause coverage not certified                      |
+| C02 | [Versioning](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning): supported revision and no invented version                                                                                                                                                                                               | C/S                               | src/protocol-2026.test.ts; src/server/server.test.ts; src/server/legacy.test.ts                                         | Scoped suite evidence; full clause coverage not certified                      |
+| C03 | [HTTP sending](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#sending-messages): POST per message, Accept JSON + SSE, one request/notification                                                                                                                                         | C/S                               | src/client.test.ts; src/server/server.test.ts; src/server/review-regressions.test.ts                                    | Scoped suite evidence; full clause coverage not certified                      |
+| C04 | [HTTP security](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#security--endpoint): invalid Origin rejected with 403                                                                                                                                                                   | S                                 | src/server/server.test.ts (Origin/auth/header/malformed requests)                                                       | Scoped suite evidence; full clause coverage not certified                      |
+| C05 | [HTTP metadata](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#request-metadata): method/name/version headers match body, encoding and custom primitive headers                                                                                                                        | C/S                               | src/protocol/headers-codec.test.ts; src/client/review-regressions.test.ts                                               | Scoped suite evidence; full clause coverage not certified                      |
+| C06 | [HTTP receiving](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#receiving-messages): JSON/SSE, notifications scoped to request, no independent server request                                                                                                                          | C/S                               | src/client/contracts.test.ts; src/client/review-regressions.test.ts; src/server/review-regressions.test.ts              | Scoped suite evidence; full clause coverage not certified                      |
+| C07 | [HTTP backward compatibility](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http#backward-compatibility): discovery fallback but not auth/rate-limit/server failures                                                                                                                       | C, legacy                         | src/protocol-2026.test.ts; src/client/review-regressions.test.ts F8; e2e/sdk-transport.test.ts                          | Scoped suite evidence; full clause coverage not certified                      |
+| C08 | [Discovery](https://modelcontextprotocol.io/specification/2026-07-28/server/discover): truthful version/capability advertisement, no modern sessions                                                                                                                                                                              | C/S                               | src/server/server.test.ts (real client and loopback); e2e/protocol-2026.test.ts                                         | Scoped suite evidence; full clause coverage not certified                      |
+| C09 | [Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools): schema-valid input/output, content, errors, unique catalog names                                                                                                                                                                                  | C/S/IC/IS                         | src/protocol/protocol.test.ts; src/server/providers.test.ts; src/client.test.ts                                         | Scoped suite evidence; full clause coverage not certified                      |
+| C10 | [Prompts](https://modelcontextprotocol.io/specification/2026-07-28/server/prompts), [resources](https://modelcontextprotocol.io/specification/2026-07-28/server/resources), [completion](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/completion): feature-specific shapes, cursors and capabilities | C/S                               | src/protocol-2026.test.ts; src/protocol/protocol.test.ts; src/server/providers.test.ts                                  | Scoped suite evidence; full clause coverage not certified                      |
+| C11 | [Caching](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching): cache fields; authenticated cache isolation                                                                                                                                                                                         | C/S/IC/IS when caching            | e2e/protocol-2026.test.ts; src/interchange/client/catalog.test.ts (host cache policy remains deployment-specific)       | Scoped suite evidence; full clause coverage not certified                      |
+| C12 | [MRTR supported requests](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr#supported-requests): only tools/call, prompts/get, resources/read permit input_required                                                                                                                                    | C/S                               | src/protocol/protocol.test.ts; src/client/review-regressions.test.ts F2/F3                                              | Scoped suite evidence; full clause coverage not certified                      |
+| C13 | [MRTR client workflow](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr#client-requirements-basic-workflow): opaque latest requestState, original params, fresh ID                                                                                                                                    | C/IC                              | src/protocol-2026.test.ts; src/interchange/client/continuation.test.ts                                                  | Scoped suite evidence; full clause coverage not certified                      |
+| C14 | [Elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation): explicit form/URL support, validated responses, no implicit consent                                                                                                                                                                   | C/S/IC/IS when opted in           | src/client/review-regressions.test.ts F9; src/extensions/host.test.ts; src/interchange/client/projection.test.ts        | Scoped suite evidence; full clause coverage not certified                      |
+| C15 | [Progress](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/progress): request-local progress only                                                                                                                                                                                                         | C/S                               | src/client/review-regressions.test.ts F11; src/server/server.test.ts                                                    | Scoped suite evidence; full clause coverage not certified                      |
+| C16 | [Cancellation](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation): modern HTTP stream closure signals cancellation, no cancelled notification                                                                                                                                                  | C/S                               | src/client/review-regressions.test.ts F5; src/server/server.test.ts; src/server/legacy.test.ts                          | Scoped suite evidence; full clause coverage not certified                      |
+| C17 | [Subscriptions](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions): negotiated filters, only allowed change notifications, terminal complete result                                                                                                                                           | C/S when provided                 | src/client/review-regressions.test.ts F7/F11; src/server/review-regressions.test.ts                                     | Scoped suite evidence; full clause coverage not certified                      |
+| C18 | [Authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization): protected-resource auth, challenge and operation authority                                                                                                                                                                         | S/IS protected endpoints          | src/auth/security.test.ts; src/auth/flows.test.ts; src/server/server.test.ts; e2e/interchange.test.ts                   | Guarded/neutral auth approved; stock dependency limits remain                  |
+| C19 | [AS discovery](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery): issuer exactness, resource binding, PKCE, registration policy                                                                                                                                        | C/hub OAuth                       | src/oauth-discovery.test.ts; src/auth/security.test.ts; src/auth/review-regressions.test.ts                             | Guarded/neutral auth approved; stock dependency limits remain                  |
+| C20 | [Deprecated features](https://modelcontextprotocol.io/specification/2026-07-28/deprecated)                                                                                                                                                                                                                                        | All                               | Explicit modern non-goals; legacy ping/cancellation are revision-scoped                                                 | Scoped exclusions; see legacy-server.md                                        |
+| T01 | Tasks Capability Negotiation / Supported Methods: opt-in each request, tools/call only, missing capability error                                                                                                                                                                                                                  | C/S/IC/IS tasks                   | src/server/extensions.test.ts; src/protocol/protocol.test.ts                                                            | Scoped suite evidence; full clause coverage not certified                      |
+| T02 | Tasks Task Status: working/input_required/completed/failed/cancelled; completed tool error differs from JSON-RPC failed                                                                                                                                                                                                           | C/S tasks                         | src/extensions/tasks/tasks.test.ts; src/client/review-regressions.test.ts F3                                            | Scoped suite evidence; full clause coverage not certified                      |
+| T03 | Tasks get/update/cancel: taskId header and outstanding input keys                                                                                                                                                                                                                                                                 | C/S tasks                         | src/extensions/tasks/tasks.test.ts; src/protocol/headers-codec.test.ts                                                  | Scoped suite evidence; full clause coverage not certified                      |
+| T04 | Tasks durability + scope §§4,7: persist before handle; tenant/principal isolation, TTL, CAS and recoverable executor                                                                                                                                                                                                              | S/IS tasks                        | src/extensions/tasks/tasks.test.ts; e2e/fixtures/packed-standalone.mjs                                                  | Scoped suite evidence; full clause coverage not certified                      |
+| T05 | Scope §5: workflow correlation and truthful cooperative cancellation                                                                                                                                                                                                                                                              | IS tasks/workflows                | src/interchange/server/accepted.test.ts; src/interchange/server/server.test.ts                                          | Scoped suite evidence; full clause coverage not certified                      |
+| K01 | Skills Capability Negotiation: resources capability, list/get; directoryRead only if declared                                                                                                                                                                                                                                     | C/S skills                        | src/server/extensions.test.ts; src/interchange/client/skills.test.ts                                                    | Scoped suite evidence; full clause coverage not certified                      |
+| K02 | Skills Skill Format / Resource Mapping: root SKILL.md, YAML name/description, name/path match, no scheme-only identity                                                                                                                                                                                                            | S/IC skills                       | src/extensions/skills/skills.test.ts                                                                                    | Scoped suite evidence; full clause coverage not certified                      |
+| K03 | Skills manifest integrity/security + scope §4: all file hashes, byte limits, origin and held-manifest binding                                                                                                                                                                                                                     | C/S/IC skills                     | src/extensions/skills/skills.test.ts; src/interchange/client/skills-large.test.ts; src/protocol/resource-bounds.test.ts | Independent authenticated-loopback/bounds approval, including 16 MiB           |
+| K04 | Scope §4 host activation: approval/provenance bound to context admission and all execution tools for acting window                                                                                                                                                                                                                | IC skills                         | src/extensions/skills/verification-race.test.ts; src/extensions/skills/skills.test.ts                                   | Scoped suite evidence; full clause coverage not certified                      |
+| A01 | Apps Capability Negotiation / Tool-UI Linkage: opt-in, metadata preserved, app-only tools not model-visible                                                                                                                                                                                                                       | C/S/IC/IS UI metadata             | src/interchange/client/apps.test.ts; src/extensions/host.test.ts                                                        | Scoped independent approval (74 tests + 6 probes); host renderer not certified |
+| A02 | Apps UI Resource Format: ui:// and text/html;profile=mcp-app; host sandbox/CSP                                                                                                                                                                                                                                                    | S metadata; browser host excluded | src/extensions/host.test.ts; src/interchange/client/apps.test.ts (actual renderer is host-owned)                        | Scoped independent approval (74 tests + 6 probes); host renderer not certified |
+| I01 | Scope §§2,5: real ToolBundle dispatch, explicit selected exposure, execution rechecks grants                                                                                                                                                                                                                                      | IC/IS                             | e2e/interchange.test.ts; src/interchange/server/server.test.ts                                                          | Scoped suite evidence; full clause coverage not certified                      |
+| I02 | Scope §§2,5: synchronous stored catalogs, credential consumer identity and origin pinning, destructive ask floor                                                                                                                                                                                                                  | IC                                | src/sidecar-bundle.test.ts; src/tool.test.ts; src/hub/discover.test.ts                                                  | Scoped suite evidence; full clause coverage not certified                      |
+| I03 | Scope §5: preserve structured/binary/private detail and truthful lifecycle projection                                                                                                                                                                                                                                             | IC                                | src/interchange/client/projection.test.ts; src/interchange/client/integration.test.ts                                   | Scoped suite evidence; full clause coverage not certified                      |
+| P01 | Scope §2: four entries, historical facades, declarations and runtime dependency isolation                                                                                                                                                                                                                                         | Package                           | e2e/package.test.ts; installed tarballs on Bun 1.4.2 / Node 24.22.1                                                     | Installed boundary passes; latest counts in integration-status.md              |
+
+## Implemented compatibility and review scope
+
+The server implements opt-in 2025-11-25/06-18/03-26 Streamable HTTP sessions;
+modern remains stateless. See [legacy deployment and limits](legacy-server.md).
+Legacy now has final scoped approval: 50 tests / 319 assertions plus 5
+independent tests / 63 assertions, as reported by the director. Both header and
+shutdown repairs are closed. This is separate from the approved core F1–F11
+repairs and does not substitute for final reconciled QA. No removed HTTP+SSE or resumption support is claimed.
+
+Apps advertisement requires explicit host bridge support, sandbox renderer,
+CSP enforcement, authenticated bridge and presentation. Metadata-only handling
+never advertises Apps. The host still supplies the actual renderer and enforces
+its security properties; the library's gate is not a deployed-browser audit.
+Skills verification supports bounded 16 MiB decoded resources; independent
+review exercised actual authenticated loopback and all bounds. Verification is
+not approval to admit context or execute code.
+
+The verified Skills adapter declines dynamic manifests, as permitted by the
+pinned specification. It requires complete resource reads with exactly one
+matching text/blob item; resource-read MRTR is unsupported by that adapter.
+These are explicit supported-shape limits, not a reopening of the approved
+resource bounds or a claim that dynamic consumption is mandatory.
+
+## Remaining actual requirements
+
+- **CL11479 — external OAuth-core defects:** stock 0.3.0 token/profile/storage
+  requires refresh tokens; stock token POST follows redirects and exposes raw
+  response errors; authorize extras can overwrite state/PKCE. Guarded MCP
+  sessions avoid those paths but do not fix stock OAuth-core. Stock hub DCR-only
+  selection and present-but-unadvertised issuer handling are additional documented
+  integration limits, not silently added issue acceptance criteria. Resource
+  exchange/refresh propagation already exists upstream; the local config omission
+  was fixed. See [guarded auth and companion limits](public-api.md).
+- **CL11480 — external credential-http defects:** old harness/types peer ranges
+  block the pinned full hub install; Request+init semantics and insecure configured
+  destination schemes also need upstream correction. Neutral installs pass and
+  must not be conflated with this optional host failure.
+- **Host obligations:** trusted identity/grants, cryptographic verification or
+  introspection, credential storage, callback/registration setup, explicit selected
+  bindings, durable recoverable executors, session affinity, skill approval and
+  context lifecycle, and Apps renderer/bridge security. These are injected
+  application responsibilities, not invented missing library features.
+- **Unverified deployments/clauses:** production DB transactions, live OAuth
+  services and callback deployment, distributed lifecycle durability, browser
+  sandbox enforcement, and exhaustive revision-by-clause coverage require their
+  own evidence. No 100% conformance or production certification is asserted.
+
+## Gates and provenance
+
+`bun run check`, `bun run test:e2e`, and the serial installed-package gate provide
+complementary evidence; exact commands, versions, counts and exit codes are in
+[integration-status.md](integration-status.md). Independent Apps (74 tests plus
+6 probes), authenticated large-Skills, core and auth approvals are reported by
+the director; they are not relabeled as fresh executions by this docs lane.

package/docs/integration-status.md

@@ -0,0 +1,98 @@
+# CL-11478 final documentation and package snapshot
+
+Snapshot: 2026-10-25, PR28 commit preparation. All implementation reviews,
+including final scoped legacy review, are approved; final QA and commit-preparation verification report 423 passing
+unit tests and 2,116 assertions. This is not a 100% conformance claim.
+
+## Current package and compatibility
+
+- Public role factories/contracts are exported and exercised through installed
+  tarballs. File-store is explicit `@corbits/mcp/server/task-store` only.
+- OAuth-core is an optional peer `^0.3.0` and pinned development dependency 0.3.0.
+  Root/login consumers install it explicitly. Neutral client/server installations
+  and module graphs exclude optional host stacks. Host/auth fixtures explicitly
+  install OAuth-core 0.3.0 and agent/harness 0.5.0.
+- Opt-in server legacy compatibility is implemented for 2025-11-25/06-18/03-26.
+  [Legacy deployment](legacy-server.md) documents defaults (1,024 sessions,
+  absolute 30-minute TTL), in-memory affinity/restart loss, 10,000 request IDs,
+  private initialization authority, March batches and GET405/no resumption.
+  Modern remains stateless by default.
+- Apps advertisement requires explicit host bridge/support, sandbox/CSP and
+  authenticated-bridge commitments, plus presentation. Metadata-only handling
+  does not advertise Apps. Actual renderer enforcement remains host-owned.
+- Large Skills resources support bounded 16 MiB decoded reads with finite wire
+  allowance and independent metadata bounds; authenticated loopback and bounds
+  were independently approved, not inferred from artifact smoke counts.
+
+## Exact executable evidence
+
+| Command                                                                            | Exit | Result                                                                                                                                       |
+| ---------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npm exec --yes --package=node@24 -- sh -c 'node --version; bun run test:package'` | 0    | **Node 24.22.1**, Bun 1.4.2; **13 pass / 0 fail**, 39 top-level assertions; one serial build/pack/install gate after legacy fixture addition |
+| `npm exec --yes --package=node@24 -- sh -c 'node --version; bun run test:e2e'`     | 0    | **Node 24.22.1**, Bun 1.4.2; **22 pass / 0 fail**, 80 assertions                                                                             |
+| `bun run build`                                                                    | 0    | Commit-preparation declaration/package build                                                                                                 |
+| `bun run check`                                                                    | 0    | Final QA and commit preparation: typecheck/lint/format and **423 pass / 0 fail**, **2,116 assertions**                                       |
+
+Ordinary npm installation is used without `--omit=peer`, `--force` or
+`--legacy-peer-deps`. The 13 current tests cover public export/declarations,
+peer-free imports, publisher/loader/task recovery/resource-auth/guarded OAuth
+behavior, legacy initialization/capacity/GET405 for three revisions, and both
+neutral graphs. They do not substitute for full revision review. Final migration
+and legacy artifact evidence is **Bun + Node24**; no final Node26 claim is made.
+
+Final QA supersedes the earlier reconciliation formatting failure. Commit
+preparation reran all four gates above serially, including fresh artifact gates
+after the test-only cancellation correction. All exited 0; source checks ran
+with Bun 1.4.2 (shell Node 26.10.0), and artifact execution used Node 24.22.1.
+No product behavior changed during commit preparation.
+
+Director-reported independent approvals cover core F1–F11, authorization,
+extensions, Interchange adapters, 16 MiB Skills bounds, and modern/legacy server
+behavior. Final scoped legacy evidence includes 50 tests / 319 assertions plus
+5 independent tests / 63 assertions, with header and shutdown repairs closed.
+These approvals remain scoped, not exhaustive revision certification.
+
+## External follow-ups versus host obligations
+
+**CL11479 (OAuth-core):** stock token-only grant conversion/storage requires a
+refresh token; token POST redirect/error handling and extra state/PKCE override
+behavior need correction. Guarded MCP login avoids relevant unsafe paths but
+stock helpers remain unchanged. Stock hub DCR-only selection and present-but-
+unadvertised issuer handling are additional integration limits, distinct from
+exact issue acceptance. Resource exchange/refresh propagation exists upstream;
+this package's local config omission was fixed.
+
+**CL11480 (credential-http):** full pinned hub installation fails npm ERESOLVE:
+0.1.0 requires harness/types ^0.4.0 against the 0.5.0 baseline. A companion
+release validated with and declaring support for both 0.5.0 peers is needed;
+no fixed release number is established. Request+init overrides and insecure
+configured schemes also require upstream correction. These optional-host
+failures do not block the passing neutral installation.
+
+Previously reproduced external install (exit 1):
+
+```sh
+npm install --prefix "$peer_dir" --ignore-scripts --no-audit --no-fund @corbits/credential-http@0.1.0 @intx/agent@0.5.0 @intx/harness@0.5.0 @intx/db@0.5.0 @intx/hub-api@0.5.0 @intx/types@0.5.0 drizzle-orm@0.45.3 hono@4.13.9
+```
+
+**Host obligations:** trusted identity/grants, real token verifier/introspection,
+encrypted persistence, callback/registration/consent setup, egress/DNS policy,
+selected bindings, recoverable executors/storage ownership, legacy affinity,
+skill approval/context lifecycle, and actual Apps renderer/bridge security.
+These are injected deployment contracts, not missing library implementations.
+
+**Unverified scope:** live production OAuth/DB/listener deployments, distributed
+lifecycle durability, actual browser sandbox enforcement and exhaustive
+revision-by-clause certification. The [requirement matrix](conformance.md)
+retains these qualifications rather than labeling resolved code/tests missing.
+
+## Final narrow documentation corrections
+
+Stored-catalog synchronous construction is correctly attributed to `mcpServers`;
+`mcpTools` performs asynchronous live discovery. The stale README OAuth URL
+scope disclaimer was removed. Packaged public API/conformance docs explicitly
+state verified Skills supported shapes: dynamic manifests declined (permitted
+by the pinned specification), exactly one matching text/blob item in a complete
+resource read, and no resource MRTR in that adapter. No implementation scope was
+expanded. Commit preparation preserves the reviewed product behavior and runs
+the repository gates serially.

package/docs/legacy-server.md

@@ -0,0 +1,58 @@
+# Opt-in legacy Streamable HTTP server
+
+`createMcpServer` is modern/stateless by default. To enable identity-bound 2025
+sessions, configure the public `legacy` option:
+
+```ts
+import { createMcpServer } from "@corbits/mcp/server";
+
+const server = createMcpServer({
+  serverInfo: { name: "example", version: "1" },
+  auth: "public", // For private servers, supply an authenticating/authorizing policy.
+  legacy: {
+    versions: ["2025-11-25", "2025-06-18", "2025-03-26"],
+    maxSessions: 1024,
+    sessionTtlMs: 30 * 60_000,
+  },
+});
+```
+
+Omitting individual legacy settings uses those defaults. Omitting `legacy`
+entirely does not create legacy sessions. Modern requests stay stateless even
+when legacy support is enabled. Public types `McpLegacyOptions` and
+`McpLegacyRevision` are available through the server entry.
+
+## Deployment and compatibility limits
+
+- Sessions live in memory in one server instance. Route all requests for a
+  session to that instance (affinity); restart loses sessions and clients must
+  initialize again. This is not a distributed session store.
+- The default absolute lifetime is 30 minutes, not extended by traffic. Capacity
+  defaults to 1,024 sessions; exhaustion refuses a new initialization.
+- A session permits at most 10,000 unique request IDs (including initialization).
+  IDs cannot be reused; initialize a new session when the limit is reached.
+- Private initialization requires authorization for resource `mcp:server`, action
+  `initialize`. Sessions bind tenant/principal/authorization context, and calls
+  recheck authorization. Session possession is not a grant.
+- Only 2025-03-26 accepts supported JSON-RPC request/notification batches.
+  Initialization cannot be batched; later revisions reject batches.
+- GET returns 405. Removed HTTP+SSE, independent GET streams and resumption are
+  not implemented. Legacy cancellation uses the session-scoped explicit
+  notification, not modern stream-close cancellation semantics.
+- No translation of modern tasks/skills/MRTR into older extension generations is
+  implied. The legacy shim exposes only supported legacy methods/results.
+
+## Evidence scope
+
+`src/server/legacy.test.ts` covers actual SDK clients over loopback HTTP for all
+three revisions, session lifecycle/bounds, identity/authorization, March batches,
+malformed envelopes, result projection and cancellation. Legacy review now has
+final scoped approval, reported by the director: 50 tests / 319 assertions plus
+5 independent tests / 63 assertions. Both header and shutdown repairs are closed.
+Final reconciled QA remains pending; this approval is not universal revision
+certification.
+
+`e2e/fixtures/packed-legacy.mjs` checks installed public factory options for all
+three revisions, initialization/session headers, configured capacity and GET405
+under Bun and Node24. It is a public-artifact smoke, not a substitute for the
+full server or independent revision review.

package/docs/migration.md

@@ -0,0 +1,143 @@
+# Bidirectional API migration
+
+## Choose the narrow entry
+
+```ts
+// Before: the historical root also imports the Interchange tool facade.
+import { mcpConnect } from "@corbits/mcp";
+// After, for standalone usage:
+import { mcpConnect } from "@corbits/mcp/client";
+```
+
+The root, `@corbits/mcp/sidecar-bundle`, and `@corbits/mcp/hub` remain supported.
+Do not change stored tool names, credential consumers or bundle IDs to migrate.
+`@corbits/mcp/interchange/client` owns remote-MCP consumption;
+`@corbits/mcp/interchange/server` owns explicit host exposure.
+The standalone server entry exports `createMcpServer` and `createToolProviders`.
+
+Agent/harness peers are optional at package-install time, not optional when
+executing their adapters. Install `@intx/agent` and `@intx/harness` for the
+historical root/Interchange consumption. Hub deployments additionally install
+the hub's documented credential, DB, Hono and authorization dependencies.
+The smoke test installs the packed package without peers to check standalone
+imports; this is runtime import isolation, not a promise of zero dependencies.
+AJV 8.20.0 and YAML 2.8.1 are lockfile-selected runtime dependencies. JSON Schema
+validation must not resolve network references implicitly.
+
+## Preserve execution and authorization semantics
+
+- Stored-catalog `mcpServers(...)` construction stays synchronous and performs no
+  network discovery at factory construction. Live `mcpTools(...)` stays async.
+- Qualified names remain `<server>.<tool>`. The `mcp-server` credential and
+  `@corbits/mcp/servers` consumer identity are unchanged. Do not widen grants.
+- All tools start ask-marked; explicit safe-tool allowlists cannot lower a
+  destructive tool's ask floor. Calling a bare ToolBundle dispatcher does not
+  itself perform host authorization.
+- Expose a finite list with `createInterchangeProviders`. The only tool
+  authorization pair is that exposure's `resource` and `action` — the same
+  pair for catalog visibility and for invocation. Do not grant a separate
+  `mcp:tools` `list` or `call` action. The server gate authorizes the selected
+  exposure pair, and `auth: "public"` on `createToolProviders` does not skip a
+  private `createMcpServer` policy. Bind tenant and approval in the host as
+  well. Catalog visibility is not execution approval; the exposure pair is
+  checked again on every invocation, and `approve` runs only after it is allowed.
+  A `tools/call` whose name is not in the catalog gets the same denial as a
+  binding `authorize` rejects, before schema or header checks, so the call
+  cannot probe membership. `tools/list`
+  stays a filtered catalog — empty when nothing is visible — and is not a 403
+  merely because the caller can see no tools.
+- Private `server/discover` returns capabilities and server info only when
+  `authorize` allows at least one registered pair (each exposure's resource and
+  action, or any other provider's resource and action). A principal allowed for
+  none receives 403 and no discover body. A private server with no providers
+  authorizes resource `mcp:server`, action `discover`. Public servers
+  (`auth: "public"`) do not perform that check.
+- Credential handles are mediated, origin-pinned fetches. Raw bearer values must
+  never enter agent tool arguments/results, skills, task records or model context.
+- Private Interchange `detail` is not automatically exported over MCP. An explicit
+  result projection is required when a host deliberately exposes richer data.
+
+## Lifecycle results are not ordinary tool output
+
+Narrow `resultType` before reading complete-result fields. `input_required` may
+repeat: fulfill only supported requests through the host UI/policy, then call
+`mcpContinue` with the latest pending result. Its opaque state may be empty or
+absent; do not reuse an older state's value. Decline/cancel is not approval.
+Tasks are negotiated per request and only augment `tools/call` in the pinned
+revision. Missing lifecycle services mean unavailable/unsupported, not success,
+a fabricated pending marker, or a new grantable tool.
+
+For durable tasks, supply atomic persistence and a recoverable executor. An
+in-memory store or surviving Promise is not production durability. A reference
+single-host file store does not imply distributed/multi-writer support. Persist
+dispatch intent before non-idempotent workflow mail and reconcile ambiguous
+crashes rather than automatically replaying them. Bind result selection to the
+specific run/message/correlation, not all events of a shared workflow.
+
+`Agent.send` cancellation in Interchange 0.5.0 cancels the waiter, not the active
+reactor cycle. Never close a shared agent for a single MCP call. Dedicated
+workflow runs can request durable cooperative cancellation, which still is not
+an immediate termination guarantee.
+
+## Security tightening
+
+Malformed wire envelopes, unsupported polymorphic result types, wrong header
+mirrors, invalid schema/data, unauthorized selections and unnegotiated extension
+operations are errors rather than permissive passthrough. Modern HTTP cancellation
+closes the response stream; it must not send the stdio cancellation notification.
+OAuth issuer equality is exact (trailing-slash aliases are not equivalent);
+resource indicators apply to authorization, code exchange and refresh. Reject
+credential-bearing/fragment endpoints and traversal before URL normalization.
+These corrections intentionally reject unsafe inputs previously accepted.
+
+## Extension deployment checklist
+
+- Tasks: opt-in capability, durable store, recoverable backend, identity isolation,
+  TTL cleanup, explicit outstanding-input and cancellation authority.
+- Skills: verified origin-scoped manifest and bytes, bounded YAML/parser/filesystem
+  access, explicit approval and provenance. Verification/read is not activation:
+  the host must gate context admission and all code-execution tools during the
+  approved acting window, including revocation/expiry.
+- Apps: advertisement requires explicit host support and bridge, sandbox/CSP/
+  authenticated-bridge commitments, and presentation. Metadata-only handling
+  never advertises Apps. The host supplies and enforces the actual renderer,
+  origins and UI lifecycle; the package gate does not implement that renderer.
+- HTTP operations: authored finite method/path bindings, host-authenticated app
+  dispatch, fixed tenant/path/origin and explicit result mapping. No automatic
+  exposure of every OpenAPI operation or hub administration route.
+
+See [conformance evidence](conformance.md) for revision pins and pending coverage.
+No release should claim full conformance while those requirements lack test evidence.
+
+## Public extension factories and guarded authorization
+
+The explicit server-only `@corbits/mcp/server/task-store` subpath exposes
+`createFileTaskStore`; it is not imported by the neutral client. Guarded OAuth
+host APIs are now exported at the historical root (`createMcpAuthorizationSession`,
+`prepareMcpClient`, `refreshMcpOAuthTokens`, callback and auth helpers).
+Root import consumers still need their historical Interchange dependencies.
+
+Publisher/task-runtime/server-auth and host skill-loader factories are now exported
+through their role entries and exercised from installed tarballs. OAuth-core is now an optional peer: historical root and guarded login consumers
+must explicitly install `@corbits/oauth-core@^0.3.0` alongside their agent/harness
+peers. Neutral client/server consumers need none of those optional host packages.
+Packed auth fixtures explicitly install OAuth-core 0.3.0. See
+[public API](public-api.md) for the neutral URL-error class distinction and the
+companion credential-http harness/types 0.5.0 support requirement.
+
+## Legacy server rollout
+
+Legacy compatibility is implemented behind `createMcpServer({ legacy: ... })`,
+not enabled by default. See [legacy-server.md](legacy-server.md) for the exact
+three revisions, session affinity/restart loss, default 1,024-session/30-minute
+bounds, 10,000 request IDs, initialization authorization, March-only batches and
+GET405/no-resumption limits. Modern requests remain stateless.
+
+## External companion follow-ups
+
+CL11479 tracks stock OAuth-core token-only/redirect/error/protected-parameter
+defects, not a generic deployment task. CL11480 tracks credential-http peer
+compatibility plus Request+init and configured-scheme policy defects. Guarded
+local login and neutral package isolation do not repair those external stock
+paths. See [public API limits](public-api.md); do not force dependency resolution
+or infer production-host approval from installed fixture results.