@theoremjs/react 0.0.0-stage → 0.3.1

package/server/handler.js

@@ -0,0 +1,771 @@
+import { withPublicLabels } from '@theoremjs/agents/guardrails';
+import { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch, } from "./page-dispatch.js";
+/**
+ * One Web-standard handler that serves a Theorem chat UI for a single profile.
+ *
+ * Mount it on any framework that speaks `Request` → `Response` (Deno.serve,
+ * Hono, Next route handlers, SvelteKit, Workers) under a catch-all route:
+ *
+ * - `GET  <base>`         → `{ interface }` client-safe profile interface
+ * - `POST <base>/turn`    → NDJSON turn events; a message sent while the reply
+ *                            waits on gates walks away from them first (`abandon`)
+ * - `POST <base>/invoke`  → NDJSON events for the user's answer to a paused tool call
+ * - `POST <base>/steer`   → inject messages into a running turn
+ * - `POST <base>/conversation` → the transcript and the paused reply, to draw
+ * - `POST <base>/rewind`  → `{ conversation, view }` the conversation cut after one block, and its new ref
+ *
+ * `createTheoremHostHandler` serves a host profile the same way, with no model:
+ *
+ * - `GET  <base>`         → `{ interface }` the tools the page may call, with their schemas
+ * - `POST <base>/call`    → NDJSON events for one call of one of those tools
+ * - `POST <base>/invoke`  → NDJSON events for the user's answer to a paused call
+ * - `POST <base>/page-result` → grant-correlated browser result receipt
+ *
+ * Trust boundary: the host owns the conversation and every decision that grants
+ * authority. Two stores keep them. The `conversationStore` owns the transcript,
+ * the history the model reads and the paused reply; the browser sends only what
+ * the person did now, with the opaque ref the store issued. The session store
+ * owns which paused calls may run (and with what input) and the tool
+ * permissions — request bodies can't grant any of them. A profile whose `providerContinuation.history` is
+ * `'stateless'` keeps no conversation, and takes no store.
+ * Tool credentials are held on the server too: a key the user types at a gate
+ * is sent once and saved, and no credential is ever sent back to the browser.
+ *
+ * @module
+ */
+import { authorizeToolReplay, compactHistory, defaultKernelScope, defineProfile, invokeTool, jsonObjectSchema, labelText, registerProfile, runTurn, TheoremError, toolInvocationHash, } from '@theoremjs/agents';
+import { caughtStatus, clientError, forClient, HTTP_METHOD, } from '@theoremjs/agents/host';
+import { clientProfileInterface, gatedToolsFromEvents, interfaceFromProfile, promotedToolIdsFromEvents, toolSnapshotFromEvents, } from '@theoremjs/agents/interface';
+import { answerGatedCall, resolveGateTtlMs, } from '@theoremjs/agents/kernel';
+import { hostInterface, theoremHostCallRequestSchema, } from "../client/host-transport.js";
+import { theoremConversationRequestSchema, theoremInvokeRequestSchema, theoremRewindRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from "../client/transport.js";
+import { answerReply, conversationView, messageReply, openConversation, postedMessage, readerConversationHost, requiredOperationId, rewindConversation, statelessRefusal, waitingCalls, } from "./conversation.js";
+import { unknownConversation } from "./conversation-store.js";
+import { createMemoryCredentialStore, } from "./credential-store.js";
+import { sessionStateStore } from "./session-authority.js";
+import { theoremSession } from "./session-identity.js";
+export { theoremSession, theoremSessionId } from "./session-identity.js";
+import { jsonResponse } from "./json-response.js";
+import { boundedRequestJson, requestByteLimit } from "./request-body.js";
+import { checkRequest } from "./request-check.js";
+import { resolveSessionLimits } from "./session-limits.js";
+import { createMemorySessionStore, DEFAULT_OPERATION_RETENTION_MS, } from "./session-store.js";
+import { createMemorySteerInbox, steerStage, steerUnitOf } from "./steer-inbox.js";
+import { sameAcceptedAnswer, sessionToolCoordinator } from "./tool-operations.js";
+const NDJSON_HEADERS = {
+    'content-type': 'application/x-ndjson; charset=utf-8',
+    'cache-control': 'no-store',
+};
+function withSessionCookie(response, session) {
+    if (session?.setCookie)
+        response.headers.append('set-cookie', session.setCookie);
+    return response;
+}
+/** A JSON body checked against `schema`; a missing or malformed field is a `request` error (400). */
+export async function readBody(request, schema, maxBytes) {
+    // why: JSON-only POSTs can't be sent by a cross-site form, and force a CORS preflight.
+    const type = request.headers.get('content-type') ?? '';
+    if (!type.toLowerCase().startsWith('application/json')) {
+        // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', 'Content-Type must be application/json');
+    }
+    let raw;
+    try {
+        raw = await boundedRequestJson(request, requestByteLimit(maxBytes));
+    }
+    catch (error) {
+        if (error instanceof TheoremError)
+            throw error;
+        // invariant: A JSON parser's message can contain request values and must not enter diagnostics.
+        throw new TheoremError('request', labelText('error.request'), {
+            cause: { code: 'request_json' },
+        });
+    }
+    return checkRequest(schema, raw, 'request body');
+}
+/** Last path segment after the mount point: '', a chat's route, or a host's 'call'. */
+function routeOf(request) {
+    const segments = new URL(request.url).pathname.split('/').filter(Boolean);
+    const last = segments.at(-1) ?? '';
+    return last === 'turn' ||
+        last === 'invoke' ||
+        last === 'steer' ||
+        last === 'conversation' ||
+        last === 'rewind' ||
+        last === 'call' ||
+        last === 'page-result'
+        ? last
+        : '';
+}
+function lockedStore(store, loaded) {
+    const locks = new Map();
+    const read = async (sessionId) => loaded(await store.load(sessionId));
+    return {
+        read,
+        mutate(sessionId, change) {
+            const next = (locks.get(sessionId) ?? Promise.resolve()).then(async () => {
+                const value = await read(sessionId);
+                const result = change(value);
+                await store.save(sessionId, value);
+                return result;
+            });
+            const settled = next.catch(() => { });
+            locks.set(sessionId, settled);
+            void settled.then(() => {
+                if (locks.get(sessionId) === settled)
+                    locks.delete(sessionId);
+            });
+            return next;
+        },
+    };
+}
+/** The profile as the server reads a message against it, its tools as registered now. */
+function chatInterface(chat) {
+    return interfaceFromProfile(chat.profile, defaultKernelScope.tools);
+}
+async function sessionOf(ctx, request) {
+    if (!ctx.options.session)
+        return theoremSession(request);
+    const id = (await ctx.options.session(request))?.trim();
+    if (!id) {
+        // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('auth', 'the session resolver refused the request', {
+            copy: { key: 'session.sign_in' },
+        });
+    }
+    return { id };
+}
+/** Reports the error to the host, then words it for whoever reads this host's replies. */
+function caughtError(ctx, err, request) {
+    ctx.options.onError?.(err, { request });
+    return clientError(err, ctx.profile.labels, ctx.options.clientEvents);
+}
+function eventStream(ctx, request, source) {
+    const encoder = new TextEncoder();
+    const line = (value) => encoder.encode(`${JSON.stringify(value)}\n`);
+    // invariant: The source runs to its end after the browser goes, so a stopped reply still reaches its save.
+    let cancelled = false;
+    const stream = new ReadableStream({
+        async start(controller) {
+            const send = (value) => {
+                if (!cancelled)
+                    controller.enqueue(line(value));
+            };
+            try {
+                for await (const event of source()) {
+                    send(event.type === 'conversation' ? event : forClient(event, ctx.options.clientEvents));
+                }
+            }
+            catch (err) {
+                if (!request.signal.aborted)
+                    send({ type: 'error', ...caughtError(ctx, err, request) });
+            }
+            if (!cancelled)
+                controller.close();
+        },
+        cancel() {
+            cancelled = true;
+        },
+    });
+    return new Response(stream, { headers: NDJSON_HEADERS });
+}
+function providerFor(ctx, request, model) {
+    const { provider } = ctx.options;
+    // labels-exempt: builder config error; the user reads error.config
+    if (!provider)
+        throw new TheoremError('config', `profile ${ctx.profile.id} has no provider`);
+    if (typeof provider === 'function')
+        return provider({ request, model });
+    return provider;
+}
+/** Steer inboxes are scoped to the session, so a turn id alone can't reach another user's turn. */
+function inboxKey(sessionId, turnId) {
+    return `${sessionId}\u0000${turnId}`;
+}
+/** The exact paused calls the user may now approve, when the stream stopped on gates. */
+function pendingGatesFrom(events, context) {
+    return gatedToolsFromEvents(events).map((gated) => ({
+        callId: gated.callId,
+        gate: {
+            profileId: context.profileId,
+            operationId: requiredOperationId(gated),
+            callId: gated.callId,
+            name: gated.name,
+            arguments: gated.arguments,
+            gate: {
+                kind: gated.gateKind,
+                permission: gated.permission,
+                ...(gated.auth ? { auth: gated.auth } : {}),
+            },
+            snapshot: toolSnapshotFromEvents(events),
+            promoted: [...new Set([...(context.promoted ?? []), ...promotedToolIdsFromEvents(events)])],
+            turnInput: context.turnInput,
+            model: context.model,
+            createdAt: Date.now(),
+        },
+    }));
+}
+/** When the stream paused on gates, record the exact calls the user may now approve. */
+async function recordOutcome(sessions, sessionId, events, context) {
+    const pending = pendingGatesFrom(events, context);
+    if (!pending.length)
+        return;
+    await sessions.mutate(sessionId, (state) => {
+        for (const { gate } of pending) {
+            const operation = state.operations[gate.operationId];
+            if (operation && operation.status !== 'ready')
+                throw new TheoremError('unavailable', labelText('error.unavailable'));
+            delete state.operations[gate.operationId];
+            Object.defineProperty(state.gates, gate.operationId, {
+                value: gate,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+    });
+}
+async function* recorded(sessions, sessionId, events, context, seed = []) {
+    const seen = [...seed];
+    for await (const event of events) {
+        seen.push(event);
+        if (event.type === 'done' || event.type === 'provider_checkpoint')
+            await recordOutcome(sessions, sessionId, seen, context);
+        yield event;
+    }
+}
+/** Save one credential, leaving the session's others as they are. */
+function saveCredential(ctx, sessionId, slot, credential) {
+    return ctx.credentials.mutate(sessionId, (saved) => {
+        saved[slot] = credential;
+    });
+}
+/**
+ * The session's credentials as a call reads them: one slot when a tool needs it,
+ * saved the moment the kernel sets one, so a rotated refresh token is never lost
+ * to a closed stream.
+ */
+function sessionCredentials(ctx, sessionId) {
+    return {
+        get: async (slot) => (await ctx.credentials.read(sessionId))[slot],
+        set: (slot, credential) => saveCredential(ctx, sessionId, slot, credential),
+    };
+}
+/** An OAuth gate given the host's sign-in URL. */
+async function withAuthorizationUrl(ctx, request, sessionId, event) {
+    if (event.type !== 'tool' || event.tool.phase !== 'gate')
+        return event;
+    const { tool } = event;
+    const gate = tool.gate.kind === 'auth' ? tool.gate : undefined;
+    if (gate?.authChallenge.authType !== 'oauth2' || !ctx.options.authorizationUrl)
+        return event;
+    const challenge = gate.authChallenge;
+    const authorizationUrl = await ctx.options.authorizationUrl(challenge, { request, sessionId });
+    return {
+        ...event,
+        tool: { ...tool, gate: { ...gate, authChallenge: { ...challenge, authorizationUrl } } },
+    };
+}
+/** Every OAuth gate in the stream, given the host's sign-in URL. */
+async function* withAuthorizationUrls(ctx, request, sessionId, events) {
+    for await (const event of events)
+        yield await withAuthorizationUrl(ctx, request, sessionId, event);
+}
+function answerPendingGate(state, request, profileId) {
+    const operation = Object.hasOwn(state.operations, request.operationId)
+        ? state.operations[request.operationId]
+        : undefined;
+    if (operation?.status === 'ready' &&
+        operation.profileId === profileId &&
+        operation.pending.callId === request.callId) {
+        const accepted = answerGatedCall(request, {
+            name: operation.pending.name,
+            arguments: operation.pending.arguments,
+            permission: operation.pending.gate.permission,
+            gateKind: operation.pending.gate.kind,
+            ...(operation.pending.gate.kind === 'auth' && operation.pending.gate.auth
+                ? { auth: operation.pending.gate.auth }
+                : {}),
+        }, operation.answer.sessionPermissions);
+        const { typed: _typed, ...plain } = accepted;
+        if (!sameAcceptedAnswer(plain, operation.answer))
+            throw new TheoremError('request', labelText('error.request'));
+        return {
+            callId: request.callId,
+            pending: operation.pending,
+            answer: { ...operation.answer, ...(accepted.typed ? { typed: accepted.typed } : {}) },
+        };
+    }
+    const pending = Object.hasOwn(state.gates, request.operationId)
+        ? state.gates[request.operationId]
+        : undefined;
+    if (!pending || pending.profileId !== profileId || pending.callId !== request.callId) {
+        // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', `gate ${request.callId} is not pending`, {
+            copy: { key: 'session.gate_expired' },
+        });
+    }
+    // why: A refused answer (a refused secret, an edit without an approval) throws here and leaves the gate pending.
+    const answer = answerGatedCall(request, {
+        name: pending.name,
+        arguments: pending.arguments,
+        permission: pending.gate.permission,
+        gateKind: pending.gate.kind,
+        ...(pending.gate.kind === 'auth' && pending.gate.auth ? { auth: pending.gate.auth } : {}),
+    }, state.permissions);
+    delete state.gates[request.operationId];
+    const { typed: _typed, ...accepted } = answer;
+    state.operations[request.operationId] = {
+        status: 'ready',
+        profileId,
+        pending,
+        answer: accepted,
+        readyAt: Date.now(),
+    };
+    state.permissions = answer.sessionPermissions;
+    return { callId: request.callId, pending, answer };
+}
+function walkedCallOf(state, reference, profileId) {
+    const settled = Object.hasOwn(state.operations, reference.operationId)
+        ? state.operations[reference.operationId]
+        : undefined;
+    return settled?.status === 'settled' &&
+        settled.callId === reference.callId &&
+        settled.profileId === profileId
+        ? { callId: reference.callId, settled }
+        : answerPendingGate(state, { ...reference, decision: 'abandon' }, profileId);
+}
+/**
+ * Take the calls a message or a rewind walks away from out of the session,
+ * answered `abandon`: every one of them, or none when one is neither waiting
+ * nor settled. Each comes back with the run that settles it.
+ */
+async function takeWalkedAway(ctx, request, session, abandon) {
+    // why: A throw leaves the session unsaved, so no call is taken unless all are.
+    const calls = await ctx.sessions.mutate(session.id, (state) => abandon.map((reference) => ({
+        reference,
+        call: walkedCallOf(state, reference, ctx.profile.id),
+    })));
+    return calls.map(({ reference, call }) => ({
+        ...reference,
+        events: 'settled' in call
+            ? replayOperation(ctx, request, call.settled)
+            : settleAnswered(ctx, request, session, call),
+    }));
+}
+async function* settleAnswered(ctx, request, session, answered) {
+    yield* invokeAnswered(ctx, request, session.id, answered);
+}
+async function* invokeAnswered(ctx, request, sessionId, { callId, pending, answer }) {
+    const host = await ctx.options.host?.(request);
+    yield* invokeTool({
+        profile: ctx.profile.id,
+        execution: sessionToolCoordinator(ctx.sessions, sessionId),
+        pageExecution: sessionPageDispatch(ctx.sessions, sessionId, ctx.pageToolBroker).execution,
+        name: pending.name,
+        callId,
+        operationId: pending.operationId,
+        input: answer.input,
+        resume: answer.resume,
+        // why: An approval that names no answer is the page saying it has none, so the call is not held again.
+        ...(pending.gate.kind === 'page' && answer.resume.granted
+            ? { page: answer.page ?? { unanswered: true } }
+            : {}),
+        sessionPermissions: answer.sessionPermissions,
+        credentials: sessionCredentials(ctx, sessionId),
+        turnInput: pending.turnInput,
+        snapshot: pending.snapshot,
+        promoted: pending.promoted,
+        model: pending.model,
+        signal: request.signal,
+        host,
+    });
+}
+/** A settled call's answer, streamed again. */
+async function* once(event, labels) {
+    yield withPublicLabels(event, labels);
+}
+/** One model run of a chat's reply, its gates recorded in the session as they pause. */
+async function* chatTurn(ctx, request, session, turn, turnId) {
+    const state = await ctx.sessions.read(session.id);
+    const provider = await providerFor(ctx, request, turn.model);
+    const host = await ctx.options.host?.(request);
+    const key = turnId ? inboxKey(session.id, turnId) : undefined;
+    if (key)
+        await ctx.inbox.open(key);
+    try {
+        const events = runTurn({
+            profile: ctx.profile.id,
+            execution: sessionToolCoordinator(ctx.sessions, session.id),
+            pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).execution,
+            input: turn.input,
+            ...(turn.providerState ? { providerState: turn.providerState } : {}),
+            sessionPermissions: state.permissions,
+            credentials: sessionCredentials(ctx, session.id),
+            signal: request.signal,
+            host,
+            ...(turn.model ? { model: turn.model } : {}),
+            ...(turn.effort ? { effort: turn.effort } : {}),
+            ...(key ? { onStage: steerStage(ctx.inbox, key) } : {}),
+        }, provider);
+        yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
+            profileId: ctx.profile.id,
+            turnInput: turn.input,
+            model: turn.model,
+        });
+    }
+    finally {
+        if (key)
+            await ctx.inbox.close(key);
+    }
+}
+/** How this request runs the model for a reply: its generation, and the request's abort. */
+function chatRunner(ctx, request, session, generation) {
+    return {
+        run: (turn) => chatTurn(ctx, request, session, turn, generation.turnId),
+        async compact(history, tokens, model) {
+            const provider = await providerFor(ctx, request, model);
+            const compacted = await compactHistory({
+                profile: ctx.profile.id,
+                history,
+                tokens,
+                signal: request.signal,
+                ...(model ? { model } : {}),
+            }, provider);
+            return compacted?.history;
+        },
+        ...(generation.model ? { model: generation.model } : {}),
+        ...(generation.effort ? { effort: generation.effort } : {}),
+        signal: request.signal,
+    };
+}
+/** The chat's conversation as this session's runs read and write it; undefined when the profile keeps none. */
+function conversationHost(ctx, session) {
+    const store = ctx.chat?.conversations;
+    if (!ctx.chat || !store)
+        return undefined;
+    return readerConversationHost({
+        sessionId: session.id,
+        store,
+        profile: { outputs: ctx.chat.profile.outputs, labels: ctx.profile.labels },
+        clientEvents: ctx.options.clientEvents,
+    });
+}
+/** The person's message: a new reply, run against the conversation the host keeps. */
+async function turn(ctx, chat, request, session) {
+    const body = await readBody(request, theoremTurnRequestSchema, ctx.options.maxRequestBytes);
+    const message = postedMessage(chatInterface(chat), body.input, await ctx.options.context?.(request));
+    const runner = chatRunner(ctx, request, session, body);
+    const host = conversationHost(ctx, session);
+    if (!host) {
+        if (body.conversation !== undefined)
+            throw statelessRefusal('continue');
+        // labels-exempt: internal diagnostic; the user reads error.request
+        if (body.abandon)
+            throw statelessRefusal('walk away from');
+        return eventStream(ctx, request, () => runner.run({ input: message.input, model: body.model, effort: body.effort }));
+    }
+    const opened = await openConversation(host, body.conversation, {
+        kind: 'message',
+        ...(body.abandon ? { abandon: body.abandon } : {}),
+    });
+    // why: Take the walked-away calls before streaming, so a stale one is a reply status, not a stream error.
+    const walkAway = body.abandon
+        ? await takeWalkedAway(ctx, request, session, body.abandon)
+        : undefined;
+    return eventStream(ctx, request, () => messageReply({ host, opened, message, ...(walkAway ? { walkAway } : {}), runner }));
+}
+/** The conversation as the browser draws it. */
+async function conversation(ctx, request, session) {
+    const body = await readBody(request, theoremConversationRequestSchema, ctx.options.maxRequestBytes);
+    const host = conversationHost(ctx, session);
+    if (!host)
+        throw statelessRefusal('read');
+    const opened = await openConversation(host, body.conversation, { kind: 'read' });
+    return jsonResponse(200, conversationView(host, opened.conversation));
+}
+/** The conversation cut after one block; a reply that waits on gates is walked away from first. */
+async function rewind(ctx, request, session) {
+    const body = await readBody(request, theoremRewindRequestSchema, ctx.options.maxRequestBytes);
+    const host = conversationHost(ctx, session);
+    if (!host)
+        throw statelessRefusal('rewind');
+    const opened = await openConversation(host, body.conversation, { kind: 'rewind', at: body.at });
+    const waiting = waitingCalls(opened.conversation);
+    const walkAway = waiting.length
+        ? await takeWalkedAway(ctx, request, session, waiting)
+        : undefined;
+    const next = await rewindConversation({
+        host,
+        opened,
+        at: body.at,
+        ...(walkAway ? { walkAway } : {}),
+    });
+    if (next.ref === null)
+        throw new TheoremError('internal', labelText('error.internal'));
+    const rewound = {
+        conversation: next.ref,
+        view: conversationView(host, next.conversation),
+    };
+    return jsonResponse(200, rewound);
+}
+async function* invokeEvents(ctx, request, session, answered) {
+    const { pending, answer } = answered;
+    if (answer.typed)
+        await saveCredential(ctx, session.id, answer.typed.slot, answer.typed.credential);
+    const events = settleAnswered(ctx, request, session, answered);
+    yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
+        profileId: ctx.profile.id,
+        turnInput: pending.turnInput,
+        model: pending.model,
+        promoted: pending.promoted,
+    }, [
+        {
+            type: 'tool',
+            tool: {
+                name: pending.name,
+                callId: pending.callId,
+                operationId: pending.operationId,
+                arguments: jsonObjectSchema.parse(answer.input),
+            },
+        },
+    ]);
+}
+async function steer(ctx, request, session) {
+    const body = await readBody(request, theoremSteerRequestSchema, ctx.options.maxRequestBytes);
+    if (!(await ctx.inbox.enqueue(inboxKey(session.id, body.turnId), steerUnitOf(body)))) {
+        // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        throw new TheoremError('request', `turn ${body.turnId} is not running`, {
+            copy: { key: 'session.turn_ended' },
+        });
+    }
+    return jsonResponse(200, { ok: true });
+}
+/** One call of one of a host's tools, run as the page asked it; a gate it pauses on waits in the session. */
+async function* callEvents(ctx, request, session, body) {
+    const state = await ctx.sessions.read(session.id);
+    const host = await ctx.options.host?.(request);
+    const events = invokeTool({
+        profile: ctx.profile.id,
+        execution: sessionToolCoordinator(ctx.sessions, session.id),
+        pageExecution: sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).execution,
+        name: body.name,
+        input: body.input,
+        sessionPermissions: state.permissions,
+        credentials: sessionCredentials(ctx, session.id),
+        signal: request.signal,
+        host,
+    });
+    yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
+        profileId: ctx.profile.id,
+        turnInput: {},
+    });
+}
+function answerRequest(body) {
+    return {
+        callId: body.gateId,
+        operationId: body.operationId,
+        decision: body.decision,
+        input: body.input,
+        secret: body.secret,
+        page: body.page,
+    };
+}
+/** A route this profile doesn't serve. */
+function refused(ctx) {
+    return jsonResponse(HTTP_METHOD, {
+        error: labelText('error.request', {}, ctx.profile.labels),
+        errorKind: 'request',
+    });
+}
+async function* replayOperation(ctx, request, operation) {
+    const tool = defaultKernelScope.tools.get(operation.toolId);
+    if (operation.profileId !== ctx.profile.id ||
+        !tool ||
+        tool.type === 'builtin' ||
+        !('tools' in ctx.profile) ||
+        !ctx.profile.tools?.allow.includes(operation.toolId) ||
+        (ctx.options.authorizeToolReplay &&
+            !(await ctx.options.authorizeToolReplay({ request, operation }))))
+        throw new TheoremError('blocked', labelText('error.blocked'));
+    authorizeToolReplay({
+        tools: defaultKernelScope.tools,
+        profile: ctx.profile,
+        name: operation.toolId,
+        resume: undefined,
+        outcome: operation.outcome,
+    });
+    yield* once(operation.outcome.event, ctx.profile.labels);
+}
+/**
+ * The user's answer to a paused call. In a kept conversation the reply goes on
+ * in the same stream once no call waits; otherwise the stream is the call's.
+ */
+async function invoke(ctx, request, session) {
+    const body = await readBody(request, theoremInvokeRequestSchema, ctx.options.maxRequestBytes);
+    if (body.page && 'output' in body.page)
+        throw new TheoremError('request', labelText('error.request'));
+    const host = conversationHost(ctx, session);
+    if (!host) {
+        if (body.conversation !== undefined)
+            throw statelessRefusal('continue');
+        return eventStream(ctx, request, await settlingOf(ctx, request, session, body));
+    }
+    if (body.conversation === undefined)
+        throw unknownConversation();
+    const call = { callId: body.gateId, operationId: body.operationId };
+    const opened = await openConversation(host, body.conversation, { kind: 'answer', call });
+    const settling = await settlingOf(ctx, request, session, body);
+    const runner = chatRunner(ctx, request, session, body);
+    return eventStream(ctx, request, () => answerReply({ host, opened, call, settling: settling(), runner }));
+}
+/** The answered call's events: its saved outcome again, or the call run as answered. */
+async function settlingOf(ctx, request, session, body) {
+    const saved = await ctx.sessions.read(session.id);
+    const operation = Object.hasOwn(saved.operations, body.operationId)
+        ? saved.operations[body.operationId]
+        : undefined;
+    if (operation &&
+        operation.status !== 'ready' &&
+        operation.callId === body.gateId &&
+        operation.profileId === ctx.profile.id &&
+        (operation.status === 'running' || operation.status === 'uncertain')) {
+        throw new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
+            copy: { key: 'tool.execution_uncertain' },
+        });
+    }
+    if (operation?.status === 'settled' &&
+        operation.profileId === ctx.profile.id &&
+        operation.callId === body.gateId) {
+        if (body.input !== undefined &&
+            (!operation.invocation ||
+                (await toolInvocationHash(body.input)) !==
+                    (await toolInvocationHash(operation.invocation.accepted.input))))
+            throw new TheoremError('request', labelText('error.request'), {
+                copy: { key: 'error.request' },
+            });
+        return () => replayOperation(ctx, request, operation);
+    }
+    // why: Take the answered call before streaming, so a stale answer is a reply status, not a stream error.
+    const answered = await ctx.sessions.mutate(session.id, (state) => answerPendingGate(state, answerRequest(body), ctx.profile.id));
+    return () => invokeEvents(ctx, request, session, answered);
+}
+async function hostRoute(ctx, request, session) {
+    const target = routeOf(request);
+    if (request.method === 'GET' && target === '') {
+        const tool = (name) => {
+            const registered = defaultKernelScope.tools.get(name);
+            return registered?.type === 'builtin' ? undefined : registered;
+        };
+        return jsonResponse(200, { interface: hostInterface(ctx.profile, tool) });
+    }
+    if (request.method === 'POST' && target === 'call') {
+        const body = await readBody(request, theoremHostCallRequestSchema, ctx.options.maxRequestBytes);
+        return eventStream(ctx, request, () => callEvents(ctx, request, session, body));
+    }
+    if (request.method === 'POST' && target === 'invoke')
+        return invoke(ctx, request, session);
+    return refused(ctx);
+}
+async function route(ctx, request, session) {
+    if (request.method === 'POST' && routeOf(request) === 'page-result') {
+        const body = await readBody(request, pageToolResultSchema, ctx.options.maxRequestBytes);
+        await sessionPageDispatch(ctx.sessions, session.id, ctx.pageToolBroker).answer(body);
+        return jsonResponse(200, { accepted: true });
+    }
+    if (ctx.profile.type === 'host')
+        return hostRoute({ ...ctx, profile: ctx.profile }, request, session);
+    const { chat } = ctx;
+    const target = routeOf(request);
+    if (!chat)
+        return refused(ctx);
+    if (request.method === 'GET' && target === '')
+        return jsonResponse(200, {
+            interface: clientProfileInterface(chat.profile, defaultKernelScope.tools),
+        });
+    if (request.method !== 'POST' || target === '' || target === 'call')
+        return refused(ctx);
+    if (target === 'turn')
+        return turn(ctx, chat, request, session);
+    if (target === 'invoke')
+        return invoke(ctx, request, session);
+    if (target === 'conversation')
+        return conversation(ctx, request, session);
+    if (target === 'rewind')
+        return rewind(ctx, request, session);
+    return steer(ctx, request, session);
+}
+export function createTheoremHandler(options) {
+    const profile = defineProfile(options.profile);
+    if (profile.type === 'decision') {
+        // labels-exempt: builder config error at setup; no user sees it
+        throw new Error("createTheoremHandler serves turn-based profiles; serve type 'decision' with createTheoremDecisionHandler.");
+    }
+    if (profile.type === 'host') {
+        // labels-exempt: builder config error at setup; no user sees it
+        throw new Error("createTheoremHandler serves turn-based profiles; serve type 'host' with createTheoremHostHandler.");
+    }
+    if (profile.type === 'live' || profile.type === 'embedding') {
+        // labels-exempt: builder config error at setup; no user sees it
+        throw new Error(`createTheoremHandler serves turn-based profiles; got type '${profile.type}'.`);
+    }
+    const stateless = profile.providerContinuation?.history === 'stateless';
+    if (stateless === (options.conversationStore !== undefined)) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: {
+                code: stateless ? 'conversation_store_stateless' : 'conversation_store_missing',
+                profile: profile.id,
+            },
+        });
+    }
+    return serve('createTheoremHandler', profile, options, {
+        steerInbox: options.steerInbox,
+        chat: {
+            profile,
+            ...(options.conversationStore ? { conversations: options.conversationStore } : {}),
+        },
+    });
+}
+/**
+ * Serves a host profile to `<TheoremHost />`: the page calls the profile's tools
+ * directly, and every call runs through the kernel's gates and guardrails.
+ */
+export function createTheoremHostHandler(options) {
+    const profile = defineProfile(options.profile);
+    if (profile.type !== 'host') {
+        // labels-exempt: builder config error at setup; no user sees it
+        throw new Error(`createTheoremHostHandler serves type 'host'; got type '${profile.type}'.`);
+    }
+    return serve('createTheoremHostHandler', profile, options);
+}
+function serve(name, profile, options, chatOptions = {}) {
+    const gateTtlMs = resolveGateTtlMs(name, options.gateTtlMs);
+    const operationRetentionMs = options.operationRetentionMs ?? DEFAULT_OPERATION_RETENTION_MS;
+    if (!Number.isSafeInteger(operationRetentionMs) || operationRetentionMs <= 0) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'operation_retention' },
+        });
+    }
+    const limits = resolveSessionLimits(options.sessionLimits);
+    requestByteLimit(options.maxRequestBytes);
+    registerProfile(profile);
+    const ctx = {
+        options,
+        pageToolBroker: options.pageToolBroker ?? createMemoryPageToolBroker(),
+        profile,
+        ...(chatOptions.chat ? { chat: chatOptions.chat } : {}),
+        inbox: chatOptions.steerInbox ?? createMemorySteerInbox(),
+        sessions: sessionStateStore(options.sessionStore ?? createMemorySessionStore({ sessionLimits: limits }), gateTtlMs, operationRetentionMs, limits),
+        credentials: lockedStore(options.credentialStore ?? createMemoryCredentialStore(), (saved = {}) => saved),
+    };
+    return async (request) => {
+        let session;
+        try {
+            session = await sessionOf(ctx, request);
+            return withSessionCookie(await route(ctx, request, session), session);
+        }
+        catch (err) {
+            return withSessionCookie(jsonResponse(caughtStatus(err), caughtError(ctx, err, request)), session);
+        }
+    };
+}