@corbits/mcp 0.3.0 → 0.4.0

package/dist/extensions/tasks/index.js

@@ -0,0 +1,221 @@
+import { validateElicitationResponse } from "../elicitation.js";
+import { validateTask as validateWireTask, validateInputResponses, } from "../../protocol/index.js";
+const terminal = (task) => ["completed", "failed", "cancelled"].includes(task.status);
+const sameIdentity = (a, b) => a.tenantId === b.tenantId &&
+    a.principalId === b.principalId &&
+    a.authorizationContextId === b.authorizationContextId;
+const fail = (message) => {
+    throw Object.assign(new Error(message), { code: -32602 });
+};
+const waitingTask = (task) => {
+    if (task.status === "input_required")
+        return task;
+    return fail("Task is not waiting for input");
+};
+export function createTaskRuntime(options) {
+    const { store, executor } = options;
+    if (store.durable !== true)
+        fail("A durable task store is required");
+    const now = options.now ?? Date.now;
+    const validateTask = options.validateTask ??
+        ((task) => {
+            validateWireTask(task, true);
+        });
+    async function load(identity, taskId) {
+        const record = await store.get(taskId);
+        if (!record ||
+            !sameIdentity(identity, record.identity) ||
+            (record.task.ttlMs !== null &&
+                Date.parse(record.task.createdAt) + record.task.ttlMs <= now()))
+            return fail("Unknown task");
+        return record;
+    }
+    async function update(identity, taskId, change) {
+        for (let attempt = 0; attempt < 16; attempt++) {
+            const record = await load(identity, taskId);
+            const next = change(structuredClone(record));
+            next.revision = record.revision + 1;
+            validateTask(next.task);
+            if (await store.compareAndSwap(taskId, record.revision, next))
+                return next;
+        }
+        throw new Error("Task concurrent update limit exceeded");
+    }
+    async function transition(identity, taskId, task, backend) {
+        return update(identity, taskId, (record) => {
+            if (terminal(record.task))
+                return fail("Terminal tasks are immutable");
+            if (task.taskId !== taskId || task.createdAt !== record.task.createdAt)
+                return fail("Task identity cannot change");
+            if (task.status === "input_required")
+                for (const [key, request] of Object.entries(task.inputRequests)) {
+                    if (Object.hasOwn(record.answered, key) ||
+                        (Object.hasOwn(record.issued, key) &&
+                            JSON.stringify(record.issued[key]) !== JSON.stringify(request)))
+                        fail("Task input key reused");
+                    record.issued = { ...record.issued, [key]: structuredClone(request) };
+                }
+            record.task = structuredClone(task);
+            record.task.lastUpdatedAt = new Date(now()).toISOString();
+            if (backend)
+                record.backend = structuredClone(backend);
+            return record;
+        });
+    }
+    return {
+        async create(identity, params, ttlMs = 86_400_000) {
+            if (Object.values(identity).some((v) => !v))
+                fail("Task identity required");
+            if (ttlMs !== null && (!Number.isSafeInteger(ttlMs) || ttlMs <= 0))
+                fail("Invalid task TTL");
+            const timestamp = new Date(now()).toISOString();
+            const task = {
+                taskId: crypto.randomUUID(),
+                status: "working",
+                createdAt: timestamp,
+                lastUpdatedAt: timestamp,
+                ttlMs,
+                pollIntervalMs: 1000,
+            };
+            validateTask(task);
+            const record = {
+                identity: structuredClone(identity),
+                task,
+                revision: 0,
+                original: { method: "tools/call", params: structuredClone(params) },
+                backend: {},
+                issued: {},
+                answered: {},
+                cancelRequested: false,
+                dispatch: "pending",
+            };
+            await store.create(record);
+            // A crash or ambiguous start remains a durable pending intent for recover().
+            await executor.start(structuredClone(record));
+            await update(identity, task.taskId, (next) => ({
+                ...next,
+                dispatch: "started",
+            }));
+            return { resultType: "task", ...structuredClone(task) };
+        },
+        async get(identity, taskId) {
+            return {
+                ...(await load(identity, taskId)).task,
+                resultType: "complete",
+            };
+        },
+        transition,
+        async submitInput(identity, taskId, responses) {
+            validateInputResponses(responses);
+            const original = await load(identity, taskId);
+            await options.authorizeInput(identity, original, responses);
+            let accepted = {};
+            const next = await update(identity, taskId, (record) => {
+                accepted = {};
+                const task = waitingTask(record.task);
+                for (const [key, response] of Object.entries(responses))
+                    if (Object.hasOwn(task.inputRequests, key) &&
+                        !Object.hasOwn(record.answered, key)) {
+                        const request = task.inputRequests[key];
+                        if (request?.method === "elicitation/create")
+                            validateElicitationResponse(request.params, response);
+                        accepted = { ...accepted, [key]: structuredClone(response) };
+                        record.answered = {
+                            ...record.answered,
+                            [key]: structuredClone(response),
+                        };
+                        delete task.inputRequests[key];
+                    }
+                if (!Object.keys(accepted).length)
+                    fail("Task is not waiting for input");
+                if (!Object.keys(task.inputRequests).length) {
+                    const { inputRequests: _requests, status: _status, ...base } = task;
+                    record.task = { ...base, status: "working" };
+                }
+                return record;
+            });
+            if (Object.keys(accepted).length)
+                await executor.submitInput(next, accepted);
+            return { resultType: "complete" };
+        },
+        async cancel(identity, taskId) {
+            const record = await update(identity, taskId, (next) => {
+                next.cancelRequested = true;
+                return next;
+            });
+            if (!terminal(record.task))
+                await executor.requestCancel(record);
+            return { resultType: "complete" };
+        },
+        async recover() {
+            await store.expire(now());
+            for (const record of await store.list())
+                if (!terminal(record.task)) {
+                    let recovered;
+                    try {
+                        recovered = await executor.recover(record);
+                    }
+                    catch {
+                        /* Persist truthful JSON-RPC recovery failure below. */
+                    }
+                    if (!recovered)
+                        recovered = {
+                            taskId: record.task.taskId,
+                            createdAt: record.task.createdAt,
+                            lastUpdatedAt: new Date(now()).toISOString(),
+                            ttlMs: record.task.ttlMs,
+                            status: "failed",
+                            error: {
+                                code: -32603,
+                                message: "Task backend recovery unavailable; execution was not replayed",
+                            },
+                        };
+                    await transition(record.identity, record.task.taskId, recovered);
+                }
+        },
+    };
+}
+export async function pollTask(options) {
+    await options.persist(options.taskId);
+    const answered = new Set();
+    const sleep = options.sleep ??
+        ((ms, signal) => new Promise((resolve, reject) => {
+            const abort = () => {
+                clearTimeout(timer);
+                reject(signal?.reason ?? new Error("Polling aborted"));
+            };
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", abort);
+                resolve();
+            }, ms);
+            if (signal?.aborted)
+                abort();
+            else
+                signal?.addEventListener("abort", abort, { once: true });
+        }));
+    for (let poll = 0; poll < (options.maxPolls ?? 10_000); poll++) {
+        options.signal?.throwIfAborted();
+        const task = await options.get(options.taskId);
+        if (task.taskId !== options.taskId)
+            fail("Task polling identity mismatch");
+        options.observe?.(task);
+        if (terminal(task))
+            return task;
+        if (task.status === "input_required") {
+            if (!options.input)
+                throw new Error("Task elicitation host unavailable");
+            const pending = Object.fromEntries(Object.entries(task.inputRequests).filter(([key]) => !answered.has(key)));
+            if (Object.keys(pending).length) {
+                const responses = await options.input(pending);
+                if (Object.keys(responses).some((key) => !Object.hasOwn(pending, key)))
+                    fail("Unexpected task input response");
+                await options.update(options.taskId, responses);
+                for (const key of Object.keys(responses))
+                    answered.add(key);
+            }
+        }
+        await sleep(Math.max(1, task.pollIntervalMs ?? 1000), options.signal);
+    }
+    throw new Error("Task polling limit exceeded; durable task remains available");
+}
+export { validateTaskRecord } from "./record.js";

package/dist/extensions/tasks/record.d.ts

@@ -0,0 +1,3 @@
+import type { McpTaskRecord } from "./contracts.js";
+/** Local persisted envelope boundary; wire payloads use common protocol validators. */
+export declare function validateTaskRecord(value: unknown): McpTaskRecord;

package/dist/extensions/tasks/record.js

@@ -0,0 +1,37 @@
+import { type } from "arktype";
+import { validateTask, validateInputRequests, validateInputResponses, } from "../../protocol/index.js";
+const recordShape = type({
+    identity: {
+        tenantId: "string > 0",
+        principalId: "string > 0",
+        authorizationContextId: "string > 0",
+    },
+    task: "object",
+    revision: "number.integer >= 0",
+    original: { method: "'tools/call'", params: "object" },
+    backend: { "[string]": "string" },
+    issued: "object",
+    answered: "object",
+    cancelRequested: "boolean",
+    dispatch: "'pending' | 'started'",
+});
+/** Local persisted envelope boundary; wire payloads use common protocol validators. */
+export function validateTaskRecord(value) {
+    const result = recordShape(value);
+    if (result instanceof type.errors)
+        throw new Error(`Invalid persisted task: ${result.summary}`);
+    validateTask(result.task, true);
+    validateInputRequests(result.issued);
+    validateInputResponses(result.answered);
+    const record = result;
+    for (const key of Object.keys(record.answered))
+        if (!Object.hasOwn(record.issued, key))
+            throw new Error("Answered input was never issued");
+    if (record.task.status === "input_required")
+        for (const key of Object.keys(record.task.inputRequests)) {
+            if (!Object.hasOwn(record.issued, key) ||
+                Object.hasOwn(record.answered, key))
+                throw new Error("Inconsistent outstanding task input");
+        }
+    return record;
+}

package/dist/hub/discover.d.ts

@@ -3,7 +3,7 @@ import type { FetchLike } from "@intx/harness";
 import type { TenantEnv } from "@intx/hub-api";
 import { type CredentialCipher } from "@intx/types";
 import type { Hono, MiddlewareHandler } from "hono";
-import { type McpTool, type McpServerInfo } from "../client.js";
+import { type McpCacheScope, type McpTool, type McpServerInfo } from "../client.js";
 export type MountMcpDiscoveryOpts = {
     readonly db: DB["db"];
     readonly cipher: CredentialCipher;
@@ -30,6 +30,8 @@ export type McpCredential = {
     readonly secret: string;
     /** The provider's API origin the secret is pinned to, when it has one. */
     readonly origin?: string;
+    /** Host-stored OAuth audience; extraOrigins never overrides this binding. */
+    readonly resource?: string;
 };
 /**
  * Read a tenant credential's decrypted secret and the origin it is pinned to.
@@ -46,6 +48,8 @@ export declare function readCredential(opts: {
 export type McpDiscovery = {
     readonly serverInfo: McpServerInfo;
     readonly tools: readonly McpTool[];
+    readonly ttlMs?: number;
+    readonly cacheScope?: McpCacheScope;
 };
 /**
  * Handshake and read a server's catalog over a fetch pinned to the

package/dist/hub/discover.js

@@ -7,7 +7,7 @@ import { credentialAad } from "@intx/types";
 import { createOriginPinnedFetch, MCP_NO_TOKEN_SENTINEL, } from "@corbits/credential-http";
 import { type } from "arktype";
 import { and, eq } from "drizzle-orm";
-import { McpError, mcpInitialize, mcpListTools, } from "../client.js";
+import { McpError, mcpConnect, mcpListTools, } from "../client.js";
 import { parseMcpEndpoint } from "../url.js";
 const DiscoverBody = type({
     url: "string > 0",
@@ -34,6 +34,7 @@ export async function readCredential(opts) {
         status: credential.status,
         expiresAt: credential.expiresAt,
         apiBaseUrl: provider.apiBaseUrl,
+        metadata: credential.metadata,
     })
         .from(credential)
         .innerJoin(provider, eq(provider.id, credential.providerId))
@@ -45,10 +46,23 @@ export async function readCredential(opts) {
         (row.expiresAt !== null && row.expiresAt.getTime() <= Date.now())) {
         return undefined;
     }
+    const metadata = type({ "oauthResource?": "string > 0" })(row.metadata ?? {});
+    if (metadata instanceof type.errors)
+        return undefined;
+    const resource = metadata.oauthResource;
+    if (resource !== undefined)
+        parseMcpEndpoint(resource);
     const secret = await opts.cipher.decrypt(row.secret, credentialAad(row.id, "secret"));
-    return row.apiBaseUrl === null
-        ? { secret }
-        : { secret, origin: new URL(row.apiBaseUrl).origin };
+    return {
+        secret,
+        ...(row.apiBaseUrl !== null
+            ? { origin: parseMcpEndpoint(row.apiBaseUrl).origin }
+            : {}),
+        ...(resource !== undefined ? { resource } : {}),
+    };
+}
+/** Only this local class is safe to expose; peer McpError text is untrusted. */
+class DiscoveryPolicyError extends McpError {
 }
 const HEADER_VALUE = /^[\t\x20-\x7e]*$/;
 /** A 3xx would send the bearer onward, so the pinned fetch's manual redirect
@@ -57,7 +71,7 @@ function refusingRedirects(inner) {
     return async (input, init) => {
         const response = await inner(input, init);
         if (response.status >= 300 && response.status < 400) {
-            throw new McpError(`the MCP server answered a ${String(response.status)} redirect; refusing to follow it`);
+            throw new DiscoveryPolicyError(`the MCP server answered a ${String(response.status)} redirect; refusing to follow it`);
         }
         return response;
     };
@@ -70,23 +84,30 @@ const DISCOVERY_TIMEOUT_MS = 30_000;
  */
 export async function discoverMcpServer(args) {
     const target = parseMcpEndpoint(args.url);
+    if (args.credential?.resource !== undefined &&
+        args.credential.resource !== args.url) {
+        throw new DiscoveryPolicyError("credential resource binding does not match the MCP endpoint");
+    }
     const secret = args.credential?.secret;
     const token = secret === undefined || secret === MCP_NO_TOKEN_SENTINEL
         ? undefined
         : secret;
     const origin = token === undefined ? target.origin : args.credential?.origin;
     if (origin === undefined) {
-        throw new McpError("the credential's provider has no API origin to pin to");
+        throw new DiscoveryPolicyError("the credential's provider has no API origin to pin to");
     }
     // A secret that is not a valid header value makes fetch throw a message
     // quoting it, so it is refused here with a fixed one.
     if (token !== undefined && !HEADER_VALUE.test(token)) {
-        throw new McpError("the credential's secret is not a valid header value");
+        throw new DiscoveryPolicyError("the credential's secret is not a valid header value");
     }
-    const extraOrigins = Object.entries(args.extraOrigins ?? {}).flatMap(([pinned, extra]) => (new URL(pinned).origin === origin ? extra : []));
-    const allowed = [origin, ...extraOrigins.map((o) => new URL(o).origin)];
+    const extraOrigins = Object.entries(args.extraOrigins ?? {}).flatMap(([pinned, extra]) => parseMcpEndpoint(pinned).origin === origin ? extra : []);
+    const allowed = [
+        origin,
+        ...extraOrigins.map((o) => parseMcpEndpoint(o).origin),
+    ];
     if (!allowed.includes(target.origin)) {
-        throw new McpError(`credential is pinned to ${origin}; refusing cross-origin request to ${target.origin}`);
+        throw new DiscoveryPolicyError(`credential is pinned to ${origin}; refusing cross-origin request to ${target.origin}`);
     }
     const pinned = refusingRedirects(createOriginPinnedFetch({
         origin,
@@ -99,7 +120,7 @@ export async function discoverMcpServer(args) {
         fetch: pinned,
         timeoutMs: args.timeoutMs ?? DISCOVERY_TIMEOUT_MS,
     };
-    const session = await mcpInitialize(args.url, client);
+    const session = await mcpConnect(args.url, client);
     const tools = await mcpListTools(args.url, { ...client, session });
     return {
         serverInfo: {
@@ -109,6 +130,8 @@ export async function discoverMcpServer(args) {
                 : {}),
         },
         tools,
+        ...(tools.ttlMs !== undefined ? { ttlMs: tools.ttlMs } : {}),
+        ...(tools.cacheScope !== undefined ? { cacheScope: tools.cacheScope } : {}),
     };
 }
 /**
@@ -157,12 +180,12 @@ export function mountMcpDiscovery(app, opts) {
             // Only this package's own messages are passed on: anything else, such
             // as a fetch error, may quote the material the request carried. An
             // upstream status is not echoed, so the route is no port-probing oracle.
-            const error = cause instanceof McpError && cause.status === undefined
+            const error = cause instanceof DiscoveryPolicyError
                 ? cause
                 : new McpError(cause instanceof McpError
                     ? "the server refused the request"
                     : "the handshake failed");
-            opts.onError?.(error, { url: body.url });
+            opts.onError?.(error, { url: `${target.origin}${target.pathname}` });
             return c.json({
                 error: `the MCP server at ${target.origin} could not be discovered: ${error.message}`,
             }, 422);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { mcpTools, type McpServerConfig, type McpToolsEnv, type McpToolsOptions, } from "./tool.js";
 export { qualifiedName, isAskExempt, toolDescription } from "./naming.js";
-export { mcpInitialize, mcpListTools, mcpCallTool, McpError, McpToolSchema, type McpTool, type McpToolResult, type McpClientOptions, type McpSession, } from "./client.js";
-export { discoverMcpLoginEntry, registerMcpClient, mcpClientConfig, selectMcpScopes, type DiscoverMcpLoginEntryOptions, type McpAuthorizationServer, type McpClientConfigOptions, type McpClientRegistration, type McpLoginEntry, type RegisterMcpClientOptions, type SelectMcpScopesOptions, } from "./oauth-discovery.js";
+export { MCP_PROTOCOL_VERSION, MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS, McpErrorCode, mcpConnect, mcpInitialize, mcpListTools, mcpCallTool, mcpContinue, mcpListPrompts, mcpGetPrompt, mcpListResources, mcpReadResource, mcpListResourceTemplates, mcpComplete, mcpListen, mcpGetTask, mcpUpdateTask, mcpCancelTask, mcpListSkills, mcpGetSkill, mcpReadResourceDirectory, McpError, McpToolSchema, type McpTool, type McpToolList, type McpToolResult, type McpToolCallResult, type McpInputRequired, type McpTask, type McpTaskHandle, type McpProgress, type McpPrompt, type McpPromptResult, type McpResource, type McpResourceReadResult, type McpResourceTemplate, type McpCompletion, type McpCompletionRef, type McpSubscriptionFilter, type McpNotification, type McpSkill, type McpSkillResult, type McpCacheScope, type McpClientOptions, type McpClientCapabilities, type McpSession, } from "./client.js";
+export { discoverMcpLoginEntry, registerMcpClient, mcpClientConfig, mcpClientIdMetadataDocument, preferredMcpClientRegistration, resolveStoredMcpClient, assertAuthorizationIssuer, readAuthorizationCallback, selectMcpScopes, type DiscoverMcpLoginEntryOptions, type McpAuthorizationServer, type McpClientConfigOptions, type McpClientIdMetadataDocument, type McpClientRegistration, type McpClientRegistrationPlan, type McpLoginEntry, type RegisterMcpClientOptions, type SelectMcpScopesOptions, type StoredMcpClient, type AuthorizationIssuerOptions, } from "./oauth-discovery.js";
+export * from "./auth/index.js";

package/dist/index.js

@@ -1,4 +1,6 @@
 export { mcpTools, } from "./tool.js";
 export { qualifiedName, isAskExempt, toolDescription } from "./naming.js";
-export { mcpInitialize, mcpListTools, mcpCallTool, McpError, McpToolSchema, } from "./client.js";
-export { discoverMcpLoginEntry, registerMcpClient, mcpClientConfig, selectMcpScopes, } from "./oauth-discovery.js";
+export { MCP_PROTOCOL_VERSION, MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS, McpErrorCode, mcpConnect, mcpInitialize, mcpListTools, mcpCallTool, mcpContinue, mcpListPrompts, mcpGetPrompt, mcpListResources, mcpReadResource, mcpListResourceTemplates, mcpComplete, mcpListen, mcpGetTask, mcpUpdateTask, mcpCancelTask, mcpListSkills, mcpGetSkill, mcpReadResourceDirectory, McpError, McpToolSchema, } from "./client.js";
+export { discoverMcpLoginEntry, registerMcpClient, mcpClientConfig, mcpClientIdMetadataDocument, preferredMcpClientRegistration, resolveStoredMcpClient, assertAuthorizationIssuer, readAuthorizationCallback, selectMcpScopes, } from "./oauth-discovery.js";
+// Guarded OAuth host APIs; standalone client imports remain dependency-light.
+export * from "./auth/index.js";

package/dist/interchange/client/capabilities.d.ts

@@ -0,0 +1,4 @@
+import type { McpClientOptions } from "../../client.js";
+import type { McpHostServices } from "./contracts.js";
+export declare function assertHostExtensions(extensions?: readonly string[], host?: McpHostServices): void;
+export declare function hostClientOptions(host: McpHostServices | undefined, extensions?: readonly string[]): Pick<McpClientOptions, "clientCapabilities">;

package/dist/interchange/client/capabilities.js

@@ -0,0 +1,53 @@
+import { type } from "arktype";
+import { getAppHostRequirements } from "../../extensions/apps.js";
+import { supportedHostExtensions } from "../../extensions/maturity.js";
+import { createElicitationRuntime } from "../../extensions/elicitation.js";
+import { MCP_EXT_TASKS, MCP_EXT_UI, MCP_EXT_SKILLS, } from "../../protocol/index.js";
+// Host configuration boundary, not an MCP wire schema. Support is explicitly
+// declared by the embedding host; we do not implement or certify its renderer.
+const AppsHostSchema = type({
+    bridge: { mount: "Function", call: "Function" },
+    support: {
+        sandboxRenderer: "boolean",
+        cspEnforcement: "boolean",
+        authenticatedBridge: "boolean",
+    },
+});
+export function assertHostExtensions(extensions = [], host = {}) {
+    if (extensions.includes(MCP_EXT_TASKS) && host.adoptTask === undefined)
+        throw new Error("MCP tasks require a host adoption and delivery service");
+    if (extensions.includes(MCP_EXT_UI)) {
+        const apps = AppsHostSchema(host.apps);
+        if (apps instanceof type.errors ||
+            !supportedHostExtensions({ apps: apps.support }).includes(MCP_EXT_UI) ||
+            typeof host.presentResult !== "function") {
+            throw new Error("MCP Apps require an explicit host bridge, sandbox renderer, CSP enforcement, authenticated bridge, and presentation service");
+        }
+    }
+    if (extensions.includes(MCP_EXT_SKILLS))
+        throw new Error("Use createMcpSkillConsumer for skills; tool factories do not activate skills");
+}
+export function hostClientOptions(host, extensions = []) {
+    assertHostExtensions(extensions, host);
+    const elicitation = host?.elicitation === undefined
+        ? {}
+        : createElicitationRuntime(host.elicitation).capabilities;
+    const hasElicitation = Object.keys(elicitation).length > 0;
+    if (!hasElicitation && !extensions.includes(MCP_EXT_UI))
+        return {};
+    return {
+        clientCapabilities: {
+            ...(hasElicitation ? { elicitation } : {}),
+            ...(extensions.length === 0
+                ? {}
+                : {
+                    extensions: Object.fromEntries(extensions.map((id) => [
+                        id,
+                        id === MCP_EXT_UI
+                            ? { mimeTypes: [getAppHostRequirements().mimeType] }
+                            : {},
+                    ])),
+                }),
+        },
+    };
+}

package/dist/interchange/client/catalog.d.ts

@@ -0,0 +1,14 @@
+import { type McpTool } from "../../client.js";
+import type { McpHostContext, McpHostServices } from "./contracts.js";
+/** Expiry is host-computed from discovery time and server TTL. Private catalogs
+ * must remain scoped to one host authorization context, not a global cache. */
+export interface McpCatalogSnapshot {
+    readonly tools: readonly McpTool[];
+    readonly expiresAt: number;
+}
+/** Install as host.validateCatalog. Refresh never mutates an active tool bundle:
+ * any changed entry requires a rebuilt factory and fresh approval derivation. */
+export declare function createCatalogGuard(options: {
+    refresh: (context: McpHostContext) => Promise<McpCatalogSnapshot>;
+    now?: () => number;
+}): NonNullable<McpHostServices["validateCatalog"]>;

package/dist/interchange/client/catalog.js

@@ -0,0 +1,52 @@
+import { type } from "arktype";
+import { McpToolSchema } from "../../client.js";
+/** Install as host.validateCatalog. Refresh never mutates an active tool bundle:
+ * any changed entry requires a rebuilt factory and fresh approval derivation. */
+export function createCatalogGuard(options) {
+    const catalogs = new Map();
+    const now = options.now ?? Date.now;
+    return async (context, tool) => {
+        context.signal.throwIfAborted();
+        const key = JSON.stringify([context.server, context.url]);
+        let snapshot = await catalogs.get(key);
+        if (snapshot === undefined || snapshot.expiresAt <= now()) {
+            const pending = (async () => {
+                const refreshed = await options.refresh(context);
+                if (!Number.isFinite(refreshed.expiresAt) ||
+                    refreshed.expiresAt <= now()) {
+                    throw new Error("MCP catalog refresh returned an expired snapshot");
+                }
+                const parsed = McpToolSchema.array()(refreshed.tools);
+                if (parsed instanceof type.errors) {
+                    throw new Error(`Invalid refreshed MCP catalog: ${parsed.summary}`);
+                }
+                return structuredClone(refreshed);
+            })();
+            catalogs.set(key, pending);
+            try {
+                snapshot = await pending;
+            }
+            catch (cause) {
+                if (catalogs.get(key) === pending)
+                    catalogs.delete(key);
+                throw cause;
+            }
+        }
+        context.signal.throwIfAborted();
+        const matches = snapshot.tools.filter((candidate) => candidate.name === tool.name);
+        if (matches.length !== 1 || canonical(matches[0]) !== canonical(tool)) {
+            throw new Error("MCP catalog changed; rebuild the tool factory and re-evaluate approvals before calling");
+        }
+    };
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}

package/dist/interchange/client/contracts.d.ts

@@ -0,0 +1,47 @@
+import type { createAppHostBridge } from "../../extensions/apps.js";
+import type { supportedHostExtensions } from "../../extensions/maturity.js";
+import type { McpElicitationHost } from "../../extensions/elicitation.js";
+import type { McpInputRequired, McpTaskHandle, McpTool, McpToolResult, mcpGetTask, mcpUpdateTask, mcpCancelTask } from "../../client.js";
+/** Host-bound identity, never credentials or model-supplied routing. */
+export interface McpHostContext {
+    readonly server: string;
+    readonly url: string;
+    readonly tool: string;
+    readonly callId: string;
+    readonly signal: AbortSignal;
+}
+export interface McpTaskControls {
+    get: () => ReturnType<typeof mcpGetTask>;
+    /** The host must collect and authorize responses to outstanding inputs. */
+    update: (responses: Parameters<typeof mcpUpdateTask>[2]) => ReturnType<typeof mcpUpdateTask>;
+    /** Cooperative intent, not proof that remote work stopped. */
+    cancel: () => ReturnType<typeof mcpCancelTask>;
+}
+/** Optional services are absent capabilities, never implicit approval. */
+export interface McpHostServices {
+    /** Explicit host-provided Apps runtime, required only for UI opt-in. The host
+     * must use this bridge for UI mounting/tool calls and fulfill the support
+     * obligations; structural validation cannot certify a deployed renderer. */
+    apps?: {
+        readonly bridge: ReturnType<typeof createAppHostBridge>;
+        readonly support: NonNullable<Parameters<typeof supportedHostExtensions>[0]["apps"]>;
+    };
+    /** Concrete form/URL services; only these advertise elicitation support. */
+    elicitation?: McpElicitationHost;
+    /** Present elicitation to a user and authorize each answer. Undefined declines.
+     * This does not substitute for the Interchange tool invocation approval gate. */
+    requestInput?: (context: McpHostContext, pending: McpInputRequired) => Promise<Record<string, unknown> | undefined>;
+    /** Persist correlation and arrange eventual Agent.deliver before returning.
+     * Controls are ephemeral; durable recovery must reacquire a mediated client. */
+    adoptTask?: (context: McpHostContext, task: McpTaskHandle, controls: McpTaskControls) => Promise<{
+        correlationId: string;
+    }>;
+    /** Host-only rich content/UI channel; metadata is never model text.
+     * This callback alone does not imply Apps rendering support. When opting into
+     * UI, wire presentation to the explicitly supplied apps bridge. */
+    presentResult?: (context: McpHostContext, result: McpToolResult) => Promise<void>;
+    /** Check freshness in the host's identity partition before execution. Reject
+     * changed schemas/visibility/approval hints and rebuild the synchronous factory;
+     * never mutate definitions or grants underneath a running agent. */
+    validateCatalog?: (context: McpHostContext, tool: McpTool) => Promise<void>;
+}

package/dist/interchange/client/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/interchange/client/projection.d.ts

@@ -0,0 +1,6 @@
+import type { ToolResult } from "@intx/types/runtime";
+import { type McpClientOptions, type McpToolCallResult } from "../../client.js";
+import type { McpHostContext, McpHostServices } from "./contracts.js";
+export declare function shapeMcpContent(content: unknown): string;
+/** One lifecycle and rich-result projection for live and stored catalogs. */
+export declare function projectToolResult(context: McpHostContext, initial: McpToolCallResult, client: McpClientOptions, host?: McpHostServices): Promise<ToolResult>;