@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/kernel/mcp-apps.d.ts

@@ -0,0 +1,49 @@
+/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
+export declare const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** One `ui://` resource. The HTML is a reusable asset and never carries caller data: that travels in tool results. */
+export interface McpAppResource {
+    readonly uri: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly html: string | (() => string | Promise<string>);
+    readonly csp?: {
+        readonly connectDomains?: readonly string[];
+        readonly resourceDomains?: readonly string[];
+        readonly frameDomains?: readonly string[];
+        readonly baseUriDomains?: readonly string[];
+    };
+    readonly permissions?: {
+        readonly camera?: Record<string, never>;
+        readonly microphone?: Record<string, never>;
+        readonly geolocation?: Record<string, never>;
+        readonly clipboardWrite?: Record<string, never>;
+    };
+    readonly prefersBorder?: boolean;
+    /** Tool names whose results this resource renders. */
+    readonly renders?: readonly string[];
+    /** Views only this App may call (`visibility: ["app"]`); a client without MCP Apps does not see them. A Procedure cannot be hidden from the model. */
+    readonly appOnly?: readonly string[];
+}
+export interface McpApps {
+    readonly resources: readonly McpAppResource[];
+}
+/** The resources of one endpoint's contributors; a contributor's `resources` may be a getter, so `mcp(...)` reads it once. */
+export declare const resourcesOf: (apps: McpApps | readonly McpApps[]) => McpApps;
+/** Checked when `mcp(...)` is built; without a tool table (a request-bound one) only the configuration itself is checked, the tool links wait for the first request. */
+export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: ReadonlySet<string>, views?: ReadonlySet<string>): {
+    resources: McpAppResource[];
+    renders: Map<string, string>;
+    appOnly: Set<string>;
+};
+/** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
+export declare function linkSurface(apps: McpApps | readonly McpApps[], selected: readonly {
+    name: string;
+    page?: unknown;
+}[], previous?: {
+    key: string;
+    links: ReturnType<typeof linkApps>;
+}): {
+    key: string;
+    links: ReturnType<typeof linkApps>;
+};

package/dist/kernel/mcp-apps.js

@@ -0,0 +1,40 @@
+import { ContractError } from "./contracts.js";
+/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
+export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** The resources of one endpoint's contributors; a contributor's `resources` may be a getter, so `mcp(...)` reads it once. */
+export const resourcesOf = (apps) => ({ resources: (Array.isArray(apps) ? apps : [apps]).flatMap(app => app.resources) });
+/** Checked when `mcp(...)` is built; without a tool table (a request-bound one) only the configuration itself is checked, the tool links wait for the first request. */
+export function linkApps(apps, tools, views) {
+    const resources = resourcesOf(apps).resources;
+    const uris = new Set(), names = new Set(), renders = new Map(), appOnly = new Set();
+    const refuse = (message) => { throw new ContractError("MCP_APP_CONFLICT", message, "mcp:apps", { status: 500 }); };
+    for (const resource of resources) {
+        if (!resource.uri.startsWith("ui://"))
+            refuse(`MCP App resource '${resource.name}' must use a ui:// URI.`);
+        if (uris.has(resource.uri))
+            refuse(`MCP App resource URI '${resource.uri}' is registered twice.`);
+        if (names.has(resource.name))
+            refuse(`MCP App resource name '${resource.name}' is registered twice.`);
+        uris.add(resource.uri);
+        names.add(resource.name);
+        for (const tool of [...resource.renders ?? [], ...resource.appOnly ?? []]) {
+            if (tools && !tools.has(tool))
+                refuse(`MCP App resource '${resource.name}' names tool '${tool}', which this endpoint does not serve.`);
+            if (renders.has(tool) && renders.get(tool) !== resource.uri)
+                refuse(`Tool '${tool}' is claimed by two MCP App resources.`);
+            renders.set(tool, resource.uri);
+        }
+        // an App acts for the user without the model seeing the call, so only a read may be hidden from the model
+        for (const tool of resource.appOnly ?? []) {
+            if (views && !views.has(tool))
+                refuse(`App-only tool '${tool}' must be a View this endpoint serves.`);
+            appOnly.add(tool);
+        }
+    }
+    return { resources, renders, appOnly };
+}
+/** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
+export function linkSurface(apps, selected, previous) {
+    const key = JSON.stringify(selected.map(tool => tool.name).sort());
+    return previous?.key === key ? previous : { key, links: linkApps(apps, new Set(selected.map(tool => tool.name)), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
+}

package/dist/kernel/mcp-call.d.ts

@@ -0,0 +1,5 @@
+import type { Caller } from "./contracts.js";
+import type { Tool } from "./mcp.js";
+export declare function callTool<Database, Handlers>(tool: Tool<Database, Handlers>, raw: Record<string, unknown>, db: Database, caller: Caller, handlers: Handlers): Promise<unknown>;
+/** Transport input is checked before acquiring an application-owned native handle. */
+export declare function callToolLazy<Database, Handlers>(tool: Tool<Database, Handlers>, raw: Record<string, unknown>, getDb: () => Database, caller: Caller, handlers: Handlers, dryRun?: () => unknown): Promise<unknown>;

package/dist/kernel/mcp-call.js

@@ -0,0 +1,25 @@
+import { convert, invalid } from "./surface.js";
+import { checkPageLimit } from "./paging.js";
+export async function callTool(tool, raw, db, caller, handlers) {
+    return callToolLazy(tool, raw, () => db, caller, handlers);
+}
+/** Transport input is checked before acquiring an application-owned native handle. */
+export async function callToolLazy(tool, raw, getDb, caller, handlers, dryRun) {
+    if (tool.page) {
+        const { limit, cursor, ...input } = raw;
+        if (limit !== undefined)
+            checkPageLimit(limit, tool.path);
+        if (cursor !== undefined && typeof cursor !== "string")
+            invalid("Invalid paging options.", tool.path);
+        await tool.validate(input);
+        convert(input, tool.convert);
+        if (dryRun)
+            return dryRun();
+        return tool.page(getDb(), caller, input, { limit: limit, cursor: cursor });
+    }
+    const input = await tool.validate(raw);
+    convert(input, tool.convert);
+    if (dryRun)
+        return dryRun();
+    return tool.run(getDb(), caller, input, handlers);
+}

package/dist/kernel/mcp-handler.js

@@ -0,0 +1,288 @@
+/** Request-only MCP implementation, excluded from Worker startup. */
+import { authorized, authorizeTarget } from "./authorization.js";
+import { forwarded, isAdmin, ContractError, checkOrigin, surfaceCaller, surfaceError, wire } from "./contracts.js";
+import { callToolLazy as callTool } from "./mcp-call.js";
+import { RESOURCE_MIME_TYPE, linkSurface } from "./mcp-apps.js";
+const text = (value, locale) => {
+    if (typeof value === "string")
+        return value;
+    if (!value)
+        return;
+    return Object.hasOwn(value, locale) ? value[locale] : Object.hasOwn(value, "en") ? value.en : Object.values(value)[0];
+};
+function observe(listener, event) {
+    if (listener)
+        try {
+            void Promise.resolve(listener(event)).catch(() => { });
+        }
+        catch { }
+}
+const paging = (schema) => ({ ...schema, properties: { ...schema.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } });
+/** The scopes a challenge asks for: the credential's, plus what the request needs. */
+const union = (scopes, extra) => [...new Set([...scopes, ...extra])].join(" ");
+/** The handler for `/mcp` (public tools) and `/mcp/admin` (tools for `admin` roles); other paths are undefined. */
+export function handler(tools, options, apps = {}, reads = []) {
+    return async (request, env, ctx) => {
+        const access = options.gateway ? (await import("./host-access.js")).accessRequest(ctx, options) : undefined;
+        let resolved;
+        try {
+            const requiredScopes = options.requiredScopes ?? ["mcp"], locale = options.locale ?? "en";
+            const url = new URL(request.url), path = url.pathname.replace(/\/+$/, ""), surface = path === "/mcp" ? "public" : path === "/mcp/admin" ? "admin" : undefined;
+            if (!surface)
+                return;
+            const select = async () => (typeof tools === "function" ? await tools(request, env) : tools).filter(tool => tool.surface === surface);
+            // Dynamic admin tables stay behind the admin gate; cache classification uses generated metadata only.
+            let selected = surface === "public" ? await select() : [];
+            let parsedBody, tooLarge = false;
+            const cookieOnly = request.headers.has("cookie") && !request.headers.has("authorization");
+            const parse = async () => {
+                if (options.gateway) {
+                    try {
+                        const raw = await (await import("./json-body.js")).bytes(request, 1024 * 1024, () => { tooLarge = true; throw new Error("Body limit"); });
+                        parsedBody = JSON.parse(new TextDecoder().decode(raw));
+                    }
+                    catch { }
+                    return;
+                }
+                const { readRequestBody } = await import("@modelcontextprotocol/server");
+                try {
+                    const body = await readRequestBody(request.clone(), 1024 * 1024);
+                    tooLarge = body.tooLarge;
+                    if (!body.tooLarge)
+                        parsedBody = JSON.parse(body.text);
+                }
+                catch { }
+            };
+            if (request.method === "POST" && (cookieOnly || options.gateway))
+                await parse();
+            const messages = Array.isArray(parsedBody) ? parsedBody : [parsedBody];
+            const readOnly = request.method === "POST" && messages.length > 0 && messages.every(message => {
+                if (!isRecord(message) || message.jsonrpc !== "2.0" || typeof message.method !== "string")
+                    return false;
+                if (["initialize", "tools/list", "resources/list", "resources/read"].includes(message.method))
+                    return true;
+                if (message.method !== "tools/call")
+                    return false;
+                const name = isRecord(message.params) ? message.params.name : undefined;
+                return reads.some(tool => tool.surface === surface && tool.name === name);
+            });
+            const challenge = async (error, scope, bare = false) => {
+                access?.finish(error);
+                const result = wire(error);
+                if (result.status === 401 || result.status === 403) {
+                    observe(options.onObservation, { kind: "request-refused", at: Date.now(), surface, status: result.status });
+                    observe(options.onRefusal, { at: Date.now(), status: result.status, reason: "credential" });
+                }
+                if (result.status === 401)
+                    scope ??= requiredScopes.join(" ");
+                return (await import("./host-caller.js")).hostFailure(error, resolved, `mcp ${path}`, bare ? undefined : 'Bearer ' + (scope ? (result.status === 403 ? 'error="insufficient_scope", ' : '') + 'scope="' + scope + '", ' : '') + 'resource_metadata="' + (options.resourceMetadata ?? url.origin + '/.well-known/oauth-protected-resource/mcp') + '"');
+            };
+            let caller;
+            try {
+                const requested = isRecord(parsedBody) && isRecord(parsedBody.params) ? parsedBody.params.name : undefined;
+                const requestedTool = selected.find(t => t.name === requested) ?? (typeof tools === "function" ? undefined : tools.find(t => t.surface === surface && t.name === requested));
+                await access?.select(requestedTool?.target ? `${requestedTool.target.kind}:${requestedTool.target.name}` : typeof requested === "string" ? `mcp:${requested}` : "mcp");
+                caller = resolved = forwarded(ctx, options.gateway)
+                    ? (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields)
+                    : await surfaceCaller(request, env, options.caller ?? (() => ({ kind: "anonymous" })), readOnly);
+                await access?.select(requestedTool?.target ? `${requestedTool.target.kind}:${requestedTool.target.name}` : "target" in caller && caller.target ? caller.target : "mcp", caller);
+                if (caller.kind === "anonymous" && (surface === "admin" || selected.length > 0 && selected.every(tool => tool.closed)))
+                    throw new ContractError("UNAUTHENTICATED", "Authentication is required.", "mcp");
+                if (caller.kind === "system")
+                    return challenge(new ContractError("AUTH_DENIED", "System callers cannot use MCP.", "mcp"), undefined, true);
+                if (surface === "admin" && !isAdmin(caller))
+                    return challenge(new ContractError("AUTH_DENIED", "Admin role is required.", "mcp/admin"), undefined, true);
+                if (!options.gateway && caller.kind === "user" && caller.credential !== "session" && requiredScopes.some(scope => !caller.scopes.includes(scope)))
+                    return challenge(new ContractError("AUTH_DENIED", "The credential needs the required MCP scopes.", "mcp"), union(caller.scopes, requiredScopes));
+            }
+            catch (error) {
+                return challenge(error);
+            }
+            if (surface === "admin")
+                selected = await select();
+            const { McpServer, createMcpHandler, fromJsonSchema } = await import("@modelcontextprotocol/server");
+            if (request.method === "POST" && !cookieOnly && !options.gateway)
+                await parse();
+            if (tooLarge && access)
+                return challenge(new ContractError("INPUT_VALIDATION_FAILED", "MCP body exceeds its limit.", "mcp"), undefined, true);
+            if (tooLarge)
+                return Response.json({ jsonrpc: "2.0", id: null, error: { code: -32000, message: "Request body exceeds 1048576 bytes." } }, { status: 413 });
+            const host = options.gateway && (await import("./host-caller.js")).isHostCaller(caller);
+            if (host) {
+                try {
+                    if (Array.isArray(parsedBody))
+                        throw new ContractError("INPUT_VALIDATION_FAILED", "Host calls cannot batch MCP messages.", "mcp");
+                    if (isRecord(parsedBody) && typeof parsedBody.method === "string" && !["initialize", "tools/call"].includes(parsedBody.method))
+                        throw new ContractError("AUTH_DENIED", "Host callers may only initialize or call a tool.", "mcp", { status: 403 });
+                    if (isRecord(parsedBody) && parsedBody.method === "initialize") {
+                        const pinned = "target" in caller ? caller.target : undefined;
+                        if (pinned && !selected.some(tool => (tool.target ? `${tool.target.kind}:${tool.target.name}` : `admin:tool:${tool.name}`) === pinned))
+                            throw new ContractError("TARGET_MISMATCH", "Initialize must pin a mounted tool.", pinned, { status: 412 });
+                        await access?.select(pinned ?? "mcp", caller);
+                        await access?.check(true);
+                    }
+                    else {
+                        const params = isRecord(parsedBody) && isRecord(parsedBody.params) ? parsedBody.params : undefined;
+                        const tool = selected.find(t => t.name === params?.name);
+                        if (tool) {
+                            await access?.select(tool.target ? `${tool.target.kind}:${tool.target.name}` : `admin:tool:${tool.name}`, caller);
+                            await access?.check(!!tool.page || tool.readOnly === true);
+                        }
+                    }
+                }
+                catch (error) {
+                    return challenge(error, undefined, true);
+                }
+            }
+            if (request.method === "POST") {
+                for (const message of Array.isArray(parsedBody) ? parsedBody : [parsedBody]) {
+                    if (!message || message.method !== "tools/call")
+                        continue;
+                    const tool = selected.find(tool => tool.name === message.params?.name);
+                    if (!tool)
+                        continue;
+                    const scopes = tool.scopes ?? [];
+                    if (caller.kind === "anonymous" && tool.closed)
+                        return challenge(new ContractError("UNAUTHENTICATED", "Authentication is required.", "mcp"), union(requiredScopes, scopes));
+                    if (!options.gateway && caller.kind === "user" && caller.credential === "oauth" && scopes.some(scope => !caller.scopes.includes(scope)))
+                        return challenge(new ContractError("AUTH_DENIED", "The credential needs additional scopes.", "mcp"), union(caller.scopes, scopes));
+                }
+            }
+            const app = options.apps?.[surface];
+            const links = app ? (apps[surface] = linkSurface(app, selected, apps[surface])).links : undefined;
+            if (options.authorize) {
+                try {
+                    for (const message of Array.isArray(parsedBody) ? parsedBody : [parsedBody]) {
+                        if (message?.method !== "tools/call")
+                            continue;
+                        const tool = selected.find(tool => tool.name === message.params?.name);
+                        if (!tool)
+                            continue;
+                        tool.check?.(caller);
+                        await authorizeTarget(options.authorize, tool.target ?? { kind: tool.page ? "view" : "procedure", name: tool.name }, caller);
+                    }
+                    if ((Array.isArray(parsedBody) ? parsedBody : [parsedBody]).some(message => message?.method === "tools/list")) {
+                        const visible = [];
+                        for (const tool of selected) {
+                            if (caller.kind === "anonymous" && tool.closed || !options.gateway && caller.kind === "user" && caller.credential === "oauth" && tool.scopes?.some(scope => !caller.scopes.includes(scope)))
+                                continue;
+                            try {
+                                tool.check?.(caller);
+                            }
+                            catch (error) {
+                                if (error instanceof ContractError && ["AUTH_DENIED", "UNAUTHENTICATED"].includes(error.code))
+                                    continue;
+                                throw error;
+                            }
+                            if (await authorized(options.authorize, tool.target ?? { kind: tool.page ? "view" : "procedure", name: tool.name }, caller))
+                                visible.push(tool);
+                        }
+                        selected = visible;
+                    }
+                }
+                catch (error) {
+                    return challenge(error);
+                }
+            }
+            // Host calls execute in the SDK callback, after transport validation.
+            const handler = createMcpHandler(() => {
+                const schema = (value) => fromJsonSchema(value, { getValidator() { return (input) => ({ valid: true, data: input, errorMessage: undefined }); } });
+                const server = new McpServer({ name: "aotter.mantle", version: "0.2.0", ...options.serverInfo }, { capabilities: { tools: { listChanged: false } }, ...(options.instructions ? { instructions: options.instructions } : {}) });
+                if (host)
+                    server.server.onclose = () => access?.finish(isRecord(parsedBody) && parsedBody.method === "initialize" ? undefined : new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: 400 }));
+                const appMeta = links ? registerApps(server, links, parsedBody) : undefined;
+                for (const tool of selected) {
+                    const meta = appMeta?.(tool.name);
+                    if (meta === false)
+                        continue;
+                    server.registerTool(tool.name, { ...(meta ? { _meta: meta } : {}), ...(tool.title ? { title: text(tool.title, locale) } : {}), description: text(tool.description, locale) ?? text(tool.title, locale) ?? tool.name, inputSchema: schema(tool.page ? paging(tool.inputSchema) : tool.inputSchema), ...(tool.outputSchema ? { outputSchema: schema(tool.outputSchema) } : {}), ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (raw) => {
+                        const metadata = options.onObservation ? { kind: "invocation", surface, invocationId: crypto.randomUUID(), tool: tool.name, caller: Object.freeze(caller.kind === "user" ? { ...caller, scopes: Object.freeze([...caller.scopes]) } : { ...caller }) } : undefined;
+                        const started = metadata ? performance.now() : 0;
+                        if (metadata)
+                            observe(options.onObservation, { ...metadata, phase: "attempt", at: Date.now() });
+                        let outcome = "succeeded", code;
+                        try {
+                            if (host)
+                                tool.check?.(caller);
+                            if (tool.run && (!host || !tool.readOnly))
+                                checkOrigin(request, caller);
+                            const data = await callTool(tool, raw, () => options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
+                            if (host)
+                                access?.finish();
+                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), content: [{ type: "text", text: JSON.stringify(data) }], ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}) };
+                        }
+                        catch (error) {
+                            if (host)
+                                access?.finish(error);
+                            const diagnostic = host ? (await (await import("./host-caller.js")).hostFailure(error, caller, `mcp ${tool.name}`).json()).error : surfaceError(error, `mcp ${tool.name}`).error;
+                            code = diagnostic.code;
+                            outcome = code === "AUTH_DENIED" || code === "UNAUTHENTICATED" ? "denied" : "failed";
+                            if (diagnostic.path === "request:origin")
+                                observe(options.onRefusal, { at: Date.now(), status: 403, reason: "origin" });
+                            const payload = { diagnostics: [diagnostic] };
+                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), isError: true, content: [{ type: "text", text: JSON.stringify(payload) }], ...(tool.outputSchema ? {} : { structuredContent: payload }) };
+                        }
+                        finally {
+                            if (metadata)
+                                observe(options.onObservation, { ...metadata, phase: "completion", at: Date.now(), outcome, durationMs: Math.max(0, performance.now() - started), ...(code ? { code } : {}) });
+                        }
+                    });
+                }
+                return server;
+            }, { legacy: "stateless", maxRequestBodySize: 1024 * 1024, onerror: error => console.error("[mantle mcp] request failed", error) });
+            const response = await handler.fetch(request, { parsedBody });
+            if (host) {
+                if (response.status >= 400)
+                    access?.finish(new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: response.status }));
+            }
+            return response;
+        }
+        catch (error) {
+            access?.finish(error);
+            return (await import("./host-caller.js")).hostFailure(error, resolved, "mcp");
+        }
+    };
+}
+const CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** `unknown`: a stateless request after `initialize` carries no capabilities, so only an explicit refusal hides Apps. */
+function clientUiSupport(message) {
+    for (const m of Array.isArray(message) ? message : [message]) {
+        if (!isRecord(m) || !isRecord(m.params))
+            continue;
+        const meta = m.params._meta;
+        const declared = isRecord(meta) && isRecord(meta[CLIENT_CAPABILITIES_META_KEY]) ? meta[CLIENT_CAPABILITIES_META_KEY] : m.method === "initialize" && isRecord(m.params.capabilities) ? m.params.capabilities : undefined;
+        if (!declared)
+            continue;
+        const extensions = declared.extensions, ui = isRecord(extensions) ? extensions["io.modelcontextprotocol/ui"] : undefined;
+        return isRecord(ui) && Array.isArray(ui.mimeTypes) && ui.mimeTypes.includes(RESOURCE_MIME_TYPE) ? "supported" : "unsupported";
+    }
+    return "unknown";
+}
+function appMeta(r) {
+    const ui = { ...(r.csp ? { csp: r.csp } : {}), ...(r.permissions ? { permissions: r.permissions } : {}), ...(r.prefersBorder !== undefined ? { prefersBorder: r.prefersBorder } : {}) };
+    return Object.keys(ui).length > 0 ? { ui } : undefined;
+}
+/** Registration uses the official SDK; HTML loaders run only on resources/read. */
+function registerApps(server, links, message) {
+    const enabled = clientUiSupport(message) !== "unsupported";
+    if (enabled)
+        for (const resource of links.resources) {
+            const meta = appMeta(resource);
+            server.registerResource(resource.name, resource.uri, { mimeType: RESOURCE_MIME_TYPE, title: resource.title, description: resource.description, ...(meta ? { _meta: meta } : {}) }, async () => {
+                try {
+                    return { contents: [{ uri: resource.uri, mimeType: RESOURCE_MIME_TYPE, text: typeof resource.html === "string" ? resource.html : await resource.html(), ...(meta ? { _meta: meta } : {}) }] };
+                }
+                catch {
+                    console.error("[mantle mcp] resource rendering failed");
+                    throw new Error("Internal error.");
+                }
+            });
+        }
+    return (tool) => {
+        if (!enabled)
+            return links.appOnly.has(tool) ? false : undefined;
+        const uri = links.renders.get(tool);
+        return uri ? { ui: { resourceUri: uri, ...(links.appOnly.has(tool) ? { visibility: ["app"] } : {}) }, "ui/resourceUri": uri, ...(links.appOnly.has(tool) ? {} : { "openai/outputTemplate": uri }) } : undefined;
+    };
+}

package/dist/kernel/mcp.d.ts

@@ -0,0 +1,101 @@
+/** MCP request handling for a generated tool table; the official SDK loads on the first MCP request. */
+import type { Caller, Target, Authorize, Gateway, RequestContext, GatewayOptions } from "./contracts.js";
+import type { Conversions } from "./surface.js";
+export { callTool, callToolLazy } from "./mcp-call.js";
+export type { McpApps, McpAppResource } from "./mcp-apps.js";
+/** Options of a generated `mcp(...)`; it adds required `handlers` when the app declares ref Procedures. */
+export interface Options<Env, Database> extends GatewayOptions {
+    apps?: Readonly<Partial<Record<"public" | "admin", import("./mcp-apps.js").McpApps | readonly import("./mcp-apps.js").McpApps[]>>>;
+    authorize?: Authorize;
+    gateway?: Gateway;
+    fields?: import("./user-fields.js").UserFields;
+    db: (env: Env) => Database;
+    caller?: (request: Request, env: Env, authority: {
+        readonly readOnly: boolean;
+    }) => Caller | Promise<Caller>;
+    locale?: string;
+    instructions?: string;
+    serverInfo?: {
+        name?: string;
+        title?: string;
+        version?: string;
+        icons?: {
+            src: string;
+            mimeType?: string;
+            sizes?: string[];
+            theme?: "light" | "dark";
+        }[];
+    };
+    requiredScopes?: readonly string[];
+    resourceMetadata?: string;
+    onObservation?: (event: McpObservation) => void | Promise<void>;
+    onRefusal?: (event: CallerRefusal) => void | Promise<void>;
+}
+export interface CallerRefusal {
+    readonly at: number;
+    readonly status: 401 | 403;
+    readonly reason: "origin" | "credential";
+}
+export type McpObservation = {
+    readonly kind: "request-refused";
+    readonly at: number;
+    readonly surface: "public" | "admin";
+    readonly status: 401 | 403;
+} | {
+    readonly kind: "invocation";
+    readonly at: number;
+    readonly surface: "public" | "admin";
+    readonly invocationId: string;
+    readonly tool: string;
+    readonly caller: Caller;
+} & ({
+    readonly phase: "attempt";
+} | {
+    readonly phase: "completion";
+    readonly outcome: "succeeded" | "failed" | "denied";
+    readonly durationMs: number;
+    readonly code?: string;
+});
+type LocalizedText = string | Readonly<Record<string, string>>;
+type Paging = {
+    limit?: number;
+    cursor?: string;
+};
+/** One tool: a paged View (`page`) or a Procedure (`run`, a write), on the public or admin surface. */
+export interface Tool<Database, Handlers = never> {
+    readonly readOnly?: boolean;
+    readonly name: string;
+    readonly target?: Target;
+    /** Generated requires guard, used before application authorization. */
+    readonly check?: (caller: Caller) => void;
+    readonly surface: string;
+    readonly title?: LocalizedText;
+    readonly description: LocalizedText;
+    readonly outputSchema?: unknown;
+    readonly annotations?: {
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly openWorldHint?: boolean;
+        readonly idempotentHint?: boolean;
+    };
+    readonly inputSchema: unknown;
+    /** Declares an auth requirement: anonymous callers are challenged. */
+    readonly closed?: boolean;
+    /** OAuth scopes the requirement names. */
+    readonly scopes?: readonly string[];
+    readonly validate: (raw: unknown) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    readonly convert?: Conversions;
+    /** A View tool: its operation path and paged boundary. */
+    readonly path?: string;
+    readonly page?: (db: Database, caller: Caller, input: never, paging: Paging) => Promise<unknown>;
+    readonly run?: (db: Database, caller: Caller, input: never, handlers: Handlers) => Promise<unknown>;
+}
+/** Request-bound tool tables keep native environment bindings outside the cached App catalogue. */
+export type Tools<Env, Database, Handlers = never> = readonly Tool<Database, Handlers>[] | ((request: Request, env: Env) => readonly Tool<Database, Handlers>[] | Promise<readonly Tool<Database, Handlers>[]>);
+/** The selected MCP routes; all request work loads only when an MCP request arrives. */
+export declare function mcp<Env, Database, Handlers = never>(tools: Tools<Env, Database, Handlers>, options: Options<Env, Database> & {
+    handlers?: Handlers;
+}, reads?: readonly {
+    readonly name: string;
+    readonly surface: string;
+}[]): (request: Request, env: Env, ctx?: RequestContext) => Promise<Response | undefined>;

package/dist/kernel/mcp.js

@@ -0,0 +1,25 @@
+import { linkApps, linkSurface, resourcesOf } from "./mcp-apps.js";
+export { callTool, callToolLazy } from "./mcp-call.js";
+/** The selected MCP routes; all request work loads only when an MCP request arrives. */
+export function mcp(tools, options, reads = []) {
+    let serve;
+    // a bad App configuration fails here, not on the first request
+    const linked = {};
+    const apps = {};
+    for (const surface of ["public", "admin"]) {
+        const declared = options.apps?.[surface];
+        if (declared) {
+            const app = resourcesOf(declared);
+            apps[surface] = app;
+            typeof tools === "function" ? linkApps(app) : linked[surface] = linkSurface(app, tools.filter(tool => tool.surface === surface));
+        }
+    }
+    options = { ...options, apps };
+    return async (request, env, ctx) => {
+        if (!/^\/mcp(?:\/admin)?\/*$/.test(new URL(request.url).pathname))
+            return;
+        const { handler } = await import("./mcp-handler.js");
+        serve ??= handler(tools, options, linked, reads);
+        return serve(request, env, ctx);
+    };
+}

package/dist/kernel/media.d.ts

@@ -0,0 +1,27 @@
+/** 0.2 media lifecycle over native target drivers. No bytes pass through this module. */
+import { ContractError, type Row } from "./contracts.js";
+import type { Bound } from "./binds.js";
+import type { Dialect } from "./dialect/common.js";
+import type { MediaAsset, MediaLibrary, MediaStorage, MediaPurposePolicy } from "./site-types.js";
+export interface MediaDatabase {
+    read(sql: string, binds: unknown[]): Row[] | PromiseLike<Row[]>;
+    write(steps: readonly Bound[]): Promise<Row[][]>; /** Positive native evidence that the write rolled back; absence is uncertain. */
+    definitive?(error: unknown): boolean;
+}
+/**
+ * A media, site or partial-failure error with the HTTP status (and `failure` payload) its code has on the wire. Code
+ * outside this module raising these codes uses it: core `statusOf` maps only the core codes.
+ */
+export declare const mediaError: (code: string, message: string, path?: string, options?: ErrorOptions) => ContractError;
+export declare function mediaLibrary(driver: MediaDatabase, d: Pick<Dialect, "param" | "escapeLike" | "likeEscape" | "like">, storage: MediaStorage, policies: readonly MediaPurposePolicy[], now?: () => number): MediaLibrary;
+/** The 0.2 Admin library item's convenience fields, without changing the storage DTO. */
+export declare function mediaItem(asset: MediaAsset): {
+    id: string;
+    variants: readonly import("./site-types.js").MediaVariant[];
+    primaryUrl: string | null;
+    mime: string | null;
+    byteSize: number | null;
+    alt: string | null;
+    caption: string | null;
+    createdAt: number;
+};