@theoremjs/web 0.0.0-stage → 0.3.4-next.375.ga2d1878

package/server/json-response.d.ts

@@ -0,0 +1,2 @@
+/** A JSON reply no cache keeps. */
+export declare function jsonResponse(status: number, body: unknown): Response;

package/server/json-response.js

@@ -0,0 +1,7 @@
+/** A JSON reply no cache keeps. */
+export function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}

package/server/mcp-handler.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One Web-standard handler that serves a host profile's tools to MCP clients over
+ * Streamable HTTP, at one endpoint that takes POST.
+ *
+ * - Clients on the current revision (`2026-07-28`) send each request with its version and
+ *   capabilities in `_meta`; nothing is kept between requests.
+ * - Clients on an earlier revision open with `initialize`; the handler answers it and serves
+ *   them the same way, without a session.
+ *
+ * Every call runs through the kernel as a host call does: the profile's gates, guardrails and
+ * trace. The client reads what a model would: the call's guarded text, never its raw output.
+ *
+ * @module
+ */
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+import { type TheoremHostHandlerOptions } from './handler.ts';
+export type TheoremMcpHandlerOptions = {
+    /** Host profile to serve. Registered with the kernel when the handler is created. */
+    profile: TheoremHostHandlerOptions['profile'];
+    /** The server's version, as clients show it. */
+    version: string;
+    /** The server's name, as clients show it. Defaults to the profile's id. */
+    name?: string;
+    /** How a model should use these tools; clients may add it to the model's context. */
+    instructions?: string;
+    /**
+     * Origins a browser page may call from, besides the endpoint's own. A request whose
+     * `Origin` is neither is refused with 403, as MCP requires against DNS rebinding.
+     */
+    origins?: readonly string[];
+    /** Handed to each tool as `ctx.host`. */
+    host?: (request: Request) => unknown;
+    /** Largest request body read, in bytes. */
+    maxRequestBytes?: number;
+    /** Who reads this host's replies: forwarded to `clientError` for a failure the handler catches. */
+    clientEvents?: ClientTurnOptions;
+    /** Called with any error the handler catches, for reporting. */
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+/**
+ * Serves a host profile's tools to MCP clients. Every tool the profile allows must run
+ * without a person's approval: an MCP client has no one to ask.
+ */
+export declare function createTheoremMcpHandler(options: TheoremMcpHandlerOptions): (request: Request) => Promise<Response>;

package/server/mcp-handler.js

@@ -0,0 +1,312 @@
+/**
+ * One Web-standard handler that serves a host profile's tools to MCP clients over
+ * Streamable HTTP, at one endpoint that takes POST.
+ *
+ * - Clients on the current revision (`2026-07-28`) send each request with its version and
+ *   capabilities in `_meta`; nothing is kept between requests.
+ * - Clients on an earlier revision open with `initialize`; the handler answers it and serves
+ *   them the same way, without a session.
+ *
+ * Every call runs through the kernel as a host call does: the profile's gates, guardrails and
+ * trace. The client reads what a model would: the call's guarded text, never its raw output.
+ *
+ * @module
+ */
+import { invokeTool, labelText, registerProfile, } from '@theoremjs/agents';
+import { caughtStatus, clientError } from '@theoremjs/agents/host';
+import { hostInterface } from "../client/host-transport.js";
+import { defineHostProfile, hostTool } from "./handler.js";
+import { boundedRequestJson, requestByteLimit } from "./request-body.js";
+/** The revision that carries its version on every request. */
+const MODERN_VERSION = '2026-07-28';
+/** Revisions that open with `initialize`, newest first. */
+const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+const SUPPORTED_VERSIONS = [MODERN_VERSION, ...LEGACY_VERSIONS];
+const META_VERSION = 'io.modelcontextprotocol/protocolVersion';
+const META_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+const META_SERVER = 'io.modelcontextprotocol/serverInfo';
+/**
+ * How long a current-revision client may keep each cacheable result, in milliseconds. Neither
+ * holds anything of the caller's, so any cache may share them.
+ */
+const CACHED = {
+    'server/discover': 3_600_000,
+    'tools/list': 300_000,
+};
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+const HEADER_MISMATCH = -32020;
+const UNSUPPORTED_VERSION = -32022;
+class RpcError extends Error {
+    status;
+    code;
+    data;
+    constructor(status, code, message, data) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.data = data;
+    }
+}
+function reply(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}
+function rpcError(id, error) {
+    return reply(error.status, {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code: error.code,
+            message: error.message,
+            ...(error.data !== undefined ? { data: error.data } : {}),
+        },
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The JSON-RPC message in `body`; one message per POST, never a batch or a response. */
+function rpcRequest(body) {
+    if (!isRecord(body) ||
+        body.jsonrpc !== '2.0' ||
+        typeof body.method !== 'string' ||
+        (body.id !== undefined && typeof body.id !== 'string' && typeof body.id !== 'number') ||
+        (body.params !== undefined && !isRecord(body.params)))
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(400, INVALID_REQUEST, 'Invalid request');
+    return {
+        ...(body.id !== undefined ? { id: body.id } : {}),
+        method: body.method,
+        params: isRecord(body.params) ? body.params : {},
+    };
+}
+/** A mirrored header's value, decoded from the `=?base64?…?=` form MCP uses for unsafe values. */
+function headerValue(value) {
+    const encoded = /^=\?base64\?(.*)\?=$/.exec(value);
+    if (!encoded)
+        return value;
+    const bytes = Uint8Array.from(atob(encoded[1]), (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * The current revision's request checks: a version this server speaks, the capabilities the
+ * client declares, and headers that agree with the body they mirror.
+ */
+function checkModern(request, message, meta) {
+    const version = meta[META_VERSION];
+    if (version !== MODERN_VERSION)
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(400, UNSUPPORTED_VERSION, 'Unsupported protocol version', {
+            supported: SUPPORTED_VERSIONS,
+            requested: version,
+        });
+    if (!isRecord(meta[META_CAPABILITIES]))
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(400, INVALID_PARAMS, `Missing _meta field ${META_CAPABILITIES}`);
+    const mirrored = [
+        ['mcp-protocol-version', version],
+        ['mcp-method', message.method],
+    ];
+    if (message.method === 'tools/call')
+        mirrored.push(['mcp-name', message.params.name]);
+    for (const [name, body] of mirrored) {
+        const header = request.headers.get(name);
+        if (header === null || headerValue(header) !== body)
+            // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+            throw new RpcError(400, HEADER_MISMATCH, `Header mismatch: ${name}`);
+    }
+}
+/** The legacy revision a client asked for in `initialize`, or the newest one this server speaks. */
+function legacyVersion(params) {
+    const asked = params.protocolVersion;
+    return LEGACY_VERSIONS.find((version) => version === asked) ?? LEGACY_VERSIONS[0];
+}
+/** What the client reads of one call, from the kernel's events for it. */
+function callResult(events, labels) {
+    for (const event of events) {
+        if (event.type === 'error')
+            return {
+                content: [
+                    { type: 'text', text: event.error ?? labelText(`error.${event.errorKind}`, {}, labels) },
+                ],
+                isError: true,
+            };
+        if (event.type !== 'tool' || !('phase' in event.tool))
+            continue;
+        const tool = event.tool;
+        if (tool.phase === 'complete')
+            return {
+                content: [
+                    { type: 'text', text: tool.readBack ?? '' },
+                    ...(tool.parts ?? []).map(partContent),
+                ],
+                isError: false,
+            };
+        if (tool.phase === 'error')
+            return {
+                content: [{ type: 'text', text: tool.readBack ?? tool.failure.message }],
+                isError: true,
+            };
+        // why: No one can answer a gate here; the client reads why the call stopped, as a model would.
+        if (tool.phase === 'gate')
+            return {
+                content: [{ type: 'text', text: tool.readBack ?? labelText('error.blocked', {}, labels) }],
+                isError: true,
+            };
+    }
+    return {
+        content: [{ type: 'text', text: labelText('error.internal', {}, labels) }],
+        isError: true,
+    };
+}
+function partContent(part, index) {
+    if (part.type === 'text')
+        return { type: 'text', text: part.text };
+    if ('uri' in part)
+        return { type: 'resource_link', uri: part.uri, name: part.uri, mimeType: part.mimeType };
+    if (part.type === 'image' || part.type === 'audio')
+        return { type: part.type, data: part.data, mimeType: part.mimeType };
+    return {
+        type: 'resource',
+        resource: { uri: `part:${index}`, mimeType: part.mimeType, blob: part.data },
+    };
+}
+/** Same origin, or one the host lists; a request with no `Origin` is not from a page. */
+function originAllowed(request, origins) {
+    const origin = request.headers.get('origin');
+    return origin === null || origin === new URL(request.url).origin || origins.includes(origin);
+}
+/**
+ * Serves a host profile's tools to MCP clients. Every tool the profile allows must run
+ * without a person's approval: an MCP client has no one to ask.
+ */
+export function createTheoremMcpHandler(options) {
+    const host = defineHostProfile('createTheoremMcpHandler', options.profile);
+    for (const name of host.tools.allow) {
+        const permission = hostTool(name)?.permission;
+        if (permission !== undefined && permission !== 'auto') {
+            // labels-exempt: builder config error at setup; no user sees it
+            throw new Error(`createTheoremMcpHandler serves tools that run without approval; '${name}' has permission '${permission}'.`);
+        }
+    }
+    const maxBytes = requestByteLimit(options.maxRequestBytes);
+    registerProfile(host);
+    const serverInfo = { name: options.name ?? host.id, version: options.version };
+    const instructions = options.instructions ? { instructions: options.instructions } : {};
+    const listed = () => hostInterface(host, hostTool).tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: {
+            readOnlyHint: tool.access === 'read-only',
+            ...(tool.access === 'destructive' ? { destructiveHint: true } : {}),
+        },
+    }));
+    async function call(request, params) {
+        const name = params.name;
+        if (typeof name !== 'string' || !listed().some((tool) => tool.name === name))
+            // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+            throw new RpcError(200, INVALID_PARAMS, `Unknown tool: ${String(name)}`);
+        const events = [];
+        for await (const event of invokeTool({
+            profile: host.id,
+            name,
+            input: params.arguments ?? {},
+            signal: request.signal,
+            host: await options.host?.(request),
+        }))
+            events.push(event);
+        return callResult(events, host.labels);
+    }
+    async function result(request, message, modern) {
+        switch (message.method) {
+            case 'server/discover':
+                if (!modern)
+                    break;
+                return {
+                    supportedVersions: SUPPORTED_VERSIONS,
+                    capabilities: { tools: {} },
+                    ...instructions,
+                };
+            case 'initialize':
+                if (modern)
+                    break;
+                return {
+                    protocolVersion: legacyVersion(message.params),
+                    capabilities: { tools: {} },
+                    serverInfo,
+                    ...instructions,
+                };
+            case 'ping':
+                if (modern)
+                    break;
+                return {};
+            case 'tools/list':
+                return { tools: listed() };
+            case 'tools/call':
+                return await call(request, message.params);
+        }
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(modern ? 404 : 200, METHOD_NOT_FOUND, `Method not found: ${message.method}`);
+    }
+    return async (request) => {
+        if (!originAllowed(request, options.origins ?? []))
+            // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+            return rpcError(null, new RpcError(403, INVALID_REQUEST, 'Origin not allowed'));
+        if (request.method !== 'POST')
+            return new Response(null, { status: 405, headers: { allow: 'POST' } });
+        let id = null;
+        try {
+            let body;
+            try {
+                body = await boundedRequestJson(request, maxBytes);
+            }
+            catch (err) {
+                if (err instanceof SyntaxError)
+                    // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+                    throw new RpcError(400, PARSE_ERROR, 'Parse error');
+                throw err;
+            }
+            const message = rpcRequest(body);
+            id = message.id ?? null;
+            const meta = isRecord(message.params._meta) ? message.params._meta : {};
+            const modern = META_VERSION in meta;
+            if (modern)
+                checkModern(request, message, meta);
+            else if (request.headers.get('mcp-protocol-version') === MODERN_VERSION)
+                // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+                throw new RpcError(400, INVALID_PARAMS, `Missing _meta field ${META_VERSION}`);
+            // invariant: A notification has no reply; the client needs only to know it arrived.
+            if (message.id === undefined)
+                return new Response(null, { status: 202 });
+            const answered = await result(request, message, modern);
+            const ttlMs = CACHED[message.method];
+            return reply(200, {
+                jsonrpc: '2.0',
+                id: message.id,
+                result: modern
+                    ? {
+                        resultType: 'complete',
+                        ...answered,
+                        ...(ttlMs !== undefined ? { ttlMs, cacheScope: 'public' } : {}),
+                        _meta: { [META_SERVER]: serverInfo },
+                    }
+                    : answered,
+            });
+        }
+        catch (err) {
+            if (err instanceof RpcError)
+                return rpcError(id, err);
+            options.onError?.(err, { request });
+            const failure = clientError(err, host.labels, options.clientEvents);
+            const code = failure.errorKind === 'request' ? INVALID_REQUEST : INTERNAL_ERROR;
+            return rpcError(id, new RpcError(caughtStatus(err), code, failure.error));
+        }
+    };
+}

package/server/mod.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Server half of `@theoremjs/web`: serve one profile to the chat UI, a
+ * decision profile to the decision UI, or a host profile's tools to the host UI or to MCP clients.
+ * `@theoremjs/react/server` re-exports it.
+ *
+ * @module
+ */
+export { theoremHostCallRequestSchema } from '../client/host-transport.ts';
+export type { LiveClientMessage, LiveOpenMessage } from '../client/live-messages.ts';
+export { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from '../client/transport.ts';
+export { answerReply, type ConversationHost, type ConversationUse, conversationView, type IssuedWalkAway, messageReply, type OpenedConversation, openConversation, type PostedMessage, postedMessage, type ReplyLine, type ReplyRunner, type ReplyTurn, readerConversationHost, rewindConversation, startConversation, statelessRefusal, type WalkedAwayCall, waitingCalls, } from './conversation.ts';
+export { type ConversationSnapshot, type ConversationWriteResult, createMemoryConversationStore, createSealedConversationStore, emptyConversation, type PausedReply, type SealedConversationStoreOptions, type StoredConversation, storedConversationSchema, type TheoremConversationStore, unknownConversation, } from './conversation-store.ts';
+export { createMemoryCredentialStore, type TheoremCredentialStore, type TheoremCredentials, } from './credential-store.ts';
+export { createTheoremDecisionHandler, type TheoremDecisionHandlerOptions, } from './decision-handler.ts';
+export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, type TheoremEmbeddingHandlerOptions, } from './embedding-handler.ts';
+export { createTheoremHandler, createTheoremHostHandler, readBody, type TheoremHandlerOptions, type TheoremHostHandlerOptions, type TheoremRequestContext, theoremSession, theoremSessionId, } from './handler.ts';
+export { createTheoremMcpHandler, type TheoremMcpHandlerOptions } from './mcp-handler.ts';
+export { createMemoryPageToolBroker, type PageToolBroker, type PageToolResult, pageToolResultSchema, sessionPageDispatch, } from './page-dispatch.ts';
+export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from './request-check.ts';
+export { sessionStateStore } from './session-authority.ts';
+export { createTheoremSessionBoundary, type PreparedLiveOpen, type SessionBoundaryOptions, type TheoremSessionBoundary, } from './session-boundary.ts';
+export type { TheoremSessionLimits } from './session-limits.ts';
+export { resolveSessionLimits } from './session-limits.ts';
+export { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, type MemorySessionStoreOptions, type PendingToolGate, type SessionSnapshot, type SessionToolOperation, type SessionWriteResult, type TheoremSessionState, type TheoremSessionStore, theoremSessionStateSchema, } from './session-store.ts';
+export { createMemorySteerInbox, type SteerInbox, type SteerUnit, steerStage, steerUnitOf, } from './steer-inbox.ts';
+export { sessionToolCoordinator } from './tool-operations.ts';
+export { kernelTurnInput, liveSessionOpen } from './turn-input.ts';

package/server/mod.js

@@ -0,0 +1,25 @@
+/**
+ * Server half of `@theoremjs/web`: serve one profile to the chat UI, a
+ * decision profile to the decision UI, or a host profile's tools to the host UI or to MCP clients.
+ * `@theoremjs/react/server` re-exports it.
+ *
+ * @module
+ */
+export { theoremHostCallRequestSchema } from "../client/host-transport.js";
+export { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremReplaySchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
+export { answerReply, conversationView, messageReply, openConversation, postedMessage, readerConversationHost, rewindConversation, startConversation, statelessRefusal, waitingCalls, } from "./conversation.js";
+export { createMemoryConversationStore, createSealedConversationStore, emptyConversation, storedConversationSchema, unknownConversation, } from "./conversation-store.js";
+export { createMemoryCredentialStore, } from "./credential-store.js";
+export { createTheoremDecisionHandler, } from "./decision-handler.js";
+export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, } from "./embedding-handler.js";
+export { createTheoremHandler, createTheoremHostHandler, readBody, theoremSession, theoremSessionId, } from "./handler.js";
+export { createTheoremMcpHandler } from "./mcp-handler.js";
+export { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch, } from "./page-dispatch.js";
+export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from "./request-check.js";
+export { sessionStateStore } from "./session-authority.js";
+export { createTheoremSessionBoundary, } from "./session-boundary.js";
+export { resolveSessionLimits } from "./session-limits.js";
+export { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, theoremSessionStateSchema, } from "./session-store.js";
+export { createMemorySteerInbox, steerStage, steerUnitOf, } from "./steer-inbox.js";
+export { sessionToolCoordinator } from "./tool-operations.js";
+export { kernelTurnInput, liveSessionOpen } from "./turn-input.js";

package/server/page-dispatch.d.ts

@@ -0,0 +1,22 @@
+import { type PageAnswer, type PageToolExecution, z } from '@theoremjs/agents';
+import type { MutableStore } from './session-authority.ts';
+import type { TheoremSessionState } from './session-store.ts';
+export type PageToolResult = {
+    callId: string;
+    operationId: string;
+    grantId: string;
+    page: PageAnswer;
+};
+export declare const pageToolResultSchema: z.ZodType<PageToolResult>;
+export interface PageToolBroker {
+    reserve(sessionId: string, grantId: string, signal?: AbortSignal): {
+        result: Promise<PageAnswer>;
+        cancel(): void;
+    };
+    deliver(sessionId: string, grantId: string, page: PageAnswer): Promise<void>;
+}
+export declare function createMemoryPageToolBroker(maxPending?: number): PageToolBroker;
+export declare function sessionPageDispatch(store: MutableStore<TheoremSessionState>, sessionId: string, broker: PageToolBroker, timeoutMs?: number): {
+    execution: PageToolExecution;
+    answer(result: PageToolResult): Promise<boolean>;
+};

package/server/page-dispatch.js

@@ -0,0 +1,127 @@
+import { jsonValueSchema, labelText, TheoremError, toolInvocationHash, z, } from '@theoremjs/agents';
+export const pageToolResultSchema = z.strictObject({
+    callId: z.string().min(1),
+    operationId: z.string().min(1).max(256),
+    grantId: z.string().min(1),
+    page: z.union([
+        z.strictObject({ output: jsonValueSchema }),
+        z.strictObject({ unanswered: z.literal(true) }),
+        z.strictObject({ timedOut: z.literal(true) }),
+    ]),
+});
+function unavailable() {
+    throw new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
+        copy: { key: 'tool.execution_uncertain' },
+    });
+}
+export function createMemoryPageToolBroker(maxPending = 128) {
+    if (!Number.isSafeInteger(maxPending) || maxPending <= 0)
+        throw new TheoremError('config', labelText('error.config'));
+    const waiting = new Map();
+    const key = (sessionId, grantId) => JSON.stringify([sessionId, grantId]);
+    return {
+        reserve(sessionId, grantId, signal) {
+            const id = key(sessionId, grantId);
+            if (signal?.aborted || waiting.has(id) || waiting.size >= maxPending)
+                unavailable();
+            let finish = () => { };
+            const result = new Promise((resolve) => {
+                finish = resolve;
+            });
+            const cancel = () => {
+                waiting.delete(id);
+                signal?.removeEventListener('abort', cancel);
+                finish({ timedOut: true });
+            };
+            waiting.set(id, (answer) => {
+                waiting.delete(id);
+                signal?.removeEventListener('abort', cancel);
+                finish(answer);
+            });
+            signal?.addEventListener('abort', cancel, { once: true });
+            return { result, cancel };
+        },
+        deliver(sessionId, grantId, page) {
+            const finish = waiting.get(key(sessionId, grantId));
+            if (!finish)
+                return Promise.reject(new TheoremError('unavailable', labelText('tool.execution_uncertain')));
+            finish(page);
+            return Promise.resolve();
+        },
+    };
+}
+export function sessionPageDispatch(store, sessionId, broker, timeoutMs = 20_000) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647)
+        throw new TheoremError('config', labelText('error.config'));
+    return {
+        execution: {
+            async dispatch(claim, signal) {
+                if (!claim.invocation)
+                    unavailable();
+                const grantId = crypto.randomUUID();
+                const expiresAt = Date.now() + timeoutMs;
+                const pending = broker.reserve(sessionId, grantId, signal);
+                try {
+                    await store.mutate(sessionId, (state) => {
+                        const record = state.operations[claim.operationId];
+                        if (record?.status !== 'running' ||
+                            record.claimToken !== claim.claimToken ||
+                            record.invocationHash !== claim.invocationHash ||
+                            record.pageGrant)
+                            unavailable();
+                        record.pageGrant = { grantId, expiresAt };
+                    });
+                }
+                catch (error) {
+                    pending.cancel();
+                    throw error;
+                }
+                const remaining = expiresAt - Date.now();
+                if (remaining <= 0 || signal?.aborted) {
+                    pending.cancel();
+                    unavailable();
+                }
+                let expire = () => { };
+                const expired = new Promise((resolve) => {
+                    expire = () => resolve({ timedOut: true });
+                });
+                const timer = setTimeout(expire, remaining);
+                signal?.addEventListener('abort', expire, { once: true });
+                return {
+                    grantId,
+                    result: Promise.race([pending.result, expired]).finally(() => {
+                        clearTimeout(timer);
+                        signal?.removeEventListener('abort', expire);
+                        pending.cancel();
+                    }),
+                };
+            },
+        },
+        async answer(raw) {
+            const result = pageToolResultSchema.parse(raw);
+            const hash = await toolInvocationHash(result.page);
+            const duplicate = await store.mutate(sessionId, (state) => {
+                const record = state.operations[result.operationId];
+                if (!record ||
+                    record.status === 'ready' ||
+                    record.callId !== result.callId ||
+                    record.pageGrant?.grantId !== result.grantId)
+                    unavailable();
+                if (record.pageGrant.resultHash !== undefined) {
+                    if (record.pageGrant.resultHash !== hash)
+                        unavailable();
+                    if (record.status === 'uncertain')
+                        unavailable();
+                    return { duplicate: true, settled: record.status === 'settled' };
+                }
+                if (record.status !== 'running' || Date.now() >= record.pageGrant.expiresAt)
+                    unavailable();
+                record.pageGrant.resultHash = hash;
+                return { duplicate: false, settled: false };
+            });
+            if (!duplicate.duplicate)
+                await broker.deliver(sessionId, result.grantId, result.page);
+            return duplicate.settled;
+        },
+    };
+}

package/server/request-body.d.ts

@@ -0,0 +1,2 @@
+export declare function requestByteLimit(bytes?: number): number;
+export declare function boundedRequestJson(request: Request, maxBytes: number): Promise<unknown>;

package/server/request-body.js

@@ -0,0 +1,42 @@
+import { labelText, TheoremError, throwIfAborted } from '@theoremjs/agents';
+const DEFAULT_REQUEST_BYTES = 16 * 1024 * 1024;
+export function requestByteLimit(bytes = DEFAULT_REQUEST_BYTES) {
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+        throw new TheoremError('config', labelText('error.config'));
+    }
+    return bytes;
+}
+export async function boundedRequestJson(request, maxBytes) {
+    if (Number(request.headers.get('content-length')) > maxBytes || !request.body) {
+        throw new TheoremError('request', labelText('error.request'));
+    }
+    const reader = request.body.getReader();
+    const abort = () => {
+        void reader.cancel(request.signal.reason).catch(() => undefined);
+    };
+    request.signal.addEventListener('abort', abort, { once: true });
+    const decoder = new TextDecoder();
+    const text = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            throwIfAborted(request.signal);
+            const next = await reader.read();
+            throwIfAborted(request.signal);
+            if (next.done)
+                break;
+            bytes += next.value.byteLength;
+            if (bytes > maxBytes)
+                throw new TheoremError('request', labelText('error.request'));
+            if (next.value.byteLength)
+                text.push(decoder.decode(next.value, { stream: true }));
+        }
+        text.push(decoder.decode());
+        return JSON.parse(text.join(''));
+    }
+    finally {
+        request.signal.removeEventListener('abort', abort);
+        void reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}

package/server/request-check.d.ts

@@ -0,0 +1,21 @@
+/**
+ * What a browser sends a host, checked: the handler's request bodies and a
+ * relay's live messages. A malformed one is a `request` error, which names
+ * only the paths and codes that broke, never the value.
+ *
+ * @module
+ */
+import { type z } from '@theoremjs/agents';
+import { type LiveClientMessage, type LiveOpenMessage } from '../client/live-messages.ts';
+/** `raw` checked against `schema`; a missing or malformed field is a `request` error. */
+export declare function checkRequest<T>(schema: z.ZodType<T>, raw: unknown, what: string): T;
+/**
+ * One text frame from the live client, as a relay reads it: JSON that passes
+ * `liveClientMessageSchema`, else a `request` error.
+ */
+export declare function parseLiveClientMessage(text: string): LiveClientMessage;
+/**
+ * The live client's first frame, as a relay reads it before it opens the
+ * session: JSON that passes `liveOpenMessageSchema`, else a `request` error.
+ */
+export declare function parseLiveOpenMessage(text: string): LiveOpenMessage;