@theoremjs/react 0.3.0 → 0.3.2

package/server/handler.js

@@ -1,3 +1,5 @@
+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.
  *
@@ -9,36 +11,47 @@
  *                            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 browser owns the conversation text; the server owns every
- * decision that grants authority. Tool permissions, which paused calls may run
- * (and with what input), and which provider interactions may be continued are
- * kept in a server-side session — request bodies can't grant any of them.
+ * 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 { createProvider, defaultKernelScope, defineProfile, errorKind, invokeTool, lexiconText, publicError, registerProfile, runTurn, TheoremError, } from '@theoremjs/agents';
-import { caughtStatus, forClient, HTTP_METHOD, } from '@theoremjs/agents/host';
-import { answerGatedCall, resolveGateTtlMs, toBase64Url, } from '@theoremjs/agents/kernel';
+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 { gatedToolsFromEvents, interfaceFromProfile, promotedToolIdsFromEvents, settlesToolCall, toolSnapshotFromEvents, } from '@theoremjs/agents/interface';
-import { theoremInvokeRequestSchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from "../client/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 { createMemorySessionStore, emptySessionState, pruneGates, } from "./session-store.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 { checkWalkAway, walkAway } from "./walk-away.js";
-import { jsonResponse } from "./json-response.js";
-const SESSION_COOKIE = 'theorem_session';
-const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
+import { sameAcceptedAnswer, sessionToolCoordinator } from "./tool-operations.js";
 const NDJSON_HEADERS = {
     'content-type': 'application/x-ndjson; charset=utf-8',
     'cache-control': 'no-store',
@@ -48,82 +61,41 @@ function withSessionCookie(response, session) {
         response.headers.append('set-cookie', session.setCookie);
     return response;
 }
-/** Strip server-only identity (system prompts) from the projected interface. */
-function clientInterface(profile) {
-    const iface = interfaceFromProfile(profile, defaultKernelScope.tools);
-    return { ...iface, identity: { handle: iface.identity.handle } };
-}
 /** A JSON body checked against `schema`; a missing or malformed field is a `request` error (400). */
-export async function readBody(request, schema) {
-    // JSON-only POSTs can't be sent by a cross-site form, and force a CORS preflight.
+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')) {
-        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        // 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 request.json();
+        raw = await boundedRequestJson(request, requestByteLimit(maxBytes));
     }
-    catch (cause) {
-        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
-        throw new TheoremError('request', 'Request body must be JSON', { cause });
+    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');
 }
-/** Conversation messages a browser may supply — never system instructions. */
-function conversationOnly(messages) {
-    return messages.filter((message) => message.role === 'user' || message.role === 'assistant' || message.role === 'tool');
-}
-/**
- * Keep the user-authored parts of a turn input. Drops fields that would let a
- * client speak as the host: system-role history, `role`, `repair` guidance,
- * token-meter overrides, and live resumption handles.
- */
-function userTurnInput(input) {
-    return {
-        ...(input.text !== undefined ? { text: input.text } : {}),
-        ...(input.attachments ? { attachments: input.attachments } : {}),
-        ...(input.voice ? { voice: input.voice } : {}),
-        ...(input.history ? { history: conversationOnly(input.history) } : {}),
-    };
-}
-/** Last path segment after the mount point: '', 'turn', 'invoke', 'steer', or a host's 'call'. */
+/** 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 === 'call' ? last : '';
-}
-function readCookie(request, name) {
-    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
-        const [key, ...rest] = part.trim().split('=');
-        if (key === name)
-            return rest.join('=');
-    }
-    return undefined;
-}
-function newSessionId() {
-    return toBase64Url(crypto.getRandomValues(new Uint8Array(32)));
-}
-/**
- * The session id the handler issued in its cookie, for a host route outside the
- * handler (an OAuth callback) that saves credentials under it. Hosts that pass
- * a `session` resolver use their own id instead.
- */
-export function theoremSessionId(request) {
-    const existing = readCookie(request, SESSION_COOKIE);
-    return existing && SESSION_ID_PATTERN.test(existing) ? existing : undefined;
-}
-function cookieSession(request) {
-    const existing = theoremSessionId(request);
-    if (existing)
-        return { id: existing };
-    const id = newSessionId();
-    const secure = new URL(request.url).protocol === 'https:' ? '; Secure' : '';
-    return {
-        id,
-        setCookie: `${SESSION_COOKIE}=${id}; Path=/; HttpOnly; SameSite=Lax${secure}`,
-    };
+    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();
@@ -147,59 +119,64 @@ function lockedStore(store, loaded) {
         },
     };
 }
-/** Session state, with expired gates dropped as it loads so they can't be answered. */
-function sessionStateStore(store, gateTtlMs) {
-    return lockedStore(store, (state = emptySessionState()) => ({
-        ...state,
-        gates: pruneGates(state.gates, Date.now(), gateTtlMs),
-        settled: pruneGates(state.settled, Date.now(), gateTtlMs),
-    }));
+/** 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 cookieSession(request);
+        return theoremSession(request);
     const id = (await ctx.options.session(request))?.trim();
     if (!id) {
-        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        // 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 the user from the profile's lexicon. */
-function publicMessage(ctx, err, request) {
+/** 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 publicError(err, ctx.profile.lexicon);
+    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()) {
-                    controller.enqueue(line(forClient(event, ctx.options.clientEvents)));
+                    send(event.type === 'conversation' ? event : forClient(event, ctx.options.clientEvents));
                 }
             }
             catch (err) {
-                if (!request.signal.aborted) {
-                    controller.enqueue(line({ type: 'error', error: publicMessage(ctx, err, request), errorKind: errorKind(err) }));
-                }
+                if (!request.signal.aborted)
+                    send({ type: 'error', ...caughtError(ctx, err, request) });
             }
-            controller.close();
+            if (!cancelled)
+                controller.close();
+        },
+        cancel() {
+            cancelled = true;
         },
     });
     return new Response(stream, { headers: NDJSON_HEADERS });
 }
 function providerFor(ctx, request, model) {
     const { provider } = ctx.options;
-    // lexicon-exempt: builder config error; the user reads error.config
+    // 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 createProvider(ctx.profile, provider, 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) {
@@ -210,9 +187,16 @@ 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 } : {}) },
+            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,
@@ -221,26 +205,31 @@ function pendingGatesFrom(events, context) {
         },
     }));
 }
-/**
- * Record what the stream established: interaction ids for continuation and,
- * when it paused on gates, the exact calls the user may now approve.
- */
+/** When the stream paused on gates, record the exact calls the user may now approve. */
 async function recordOutcome(sessions, sessionId, events, context) {
-    const interactionIds = events.flatMap((event) => event.type === 'done' && event.interactionId ? [event.interactionId] : []);
     const pending = pendingGatesFrom(events, context);
-    if (!interactionIds.length && !pending.length)
+    if (!pending.length)
         return;
     await sessions.mutate(sessionId, (state) => {
-        state.interactions.push(...interactionIds);
-        for (const { callId, gate } of pending)
-            state.gates[callId] = gate;
+        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) {
-    const seen = [];
+async function* recorded(sessions, sessionId, events, context, seed = []) {
+    const seen = [...seed];
     for await (const event of events) {
         seen.push(event);
-        if (event.type === 'done')
+        if (event.type === 'done' || event.type === 'provider_checkpoint')
             await recordOutcome(sessions, sessionId, seen, context);
         yield event;
     }
@@ -268,7 +257,7 @@ async function withAuthorizationUrl(ctx, request, sessionId, event) {
         return event;
     const { tool } = event;
     const gate = tool.gate.kind === 'auth' ? tool.gate : undefined;
-    if (!gate || gate.authChallenge.authType !== 'oauth2' || !ctx.options.authorizationUrl)
+    if (gate?.authChallenge.authType !== 'oauth2' || !ctx.options.authorizationUrl)
         return event;
     const challenge = gate.authChallenge;
     const authorizationUrl = await ctx.options.authorizationUrl(challenge, { request, sessionId });
@@ -282,78 +271,106 @@ async function* withAuthorizationUrls(ctx, request, sessionId, events) {
     for await (const event of events)
         yield await withAuthorizationUrl(ctx, request, sessionId, event);
 }
-function answerPendingGate(state, request) {
-    const pending = state.gates[request.callId];
-    if (!pending) {
-        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+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' },
         });
     }
-    // A refused answer (a refused secret, an edit without an approval) throws here and leaves the gate pending.
+    // 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.callId];
+    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, callId) {
-    const settled = state.settled[callId];
-    return settled ? { callId, settled } : answerPendingGate(state, { callId, decision: 'abandon' });
+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 walks away from out of the session, answered
- * `abandon`: every one of them, or none when one is neither waiting nor
- * settled. The message's history must leave exactly those calls open.
+ * 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.
  */
-function takeWalkedAway(ctx, session, input, abandon) {
-    checkWalkAway(input, abandon);
-    // A throw leaves the session unsaved, so no call is taken unless all are.
-    return ctx.sessions.mutate(session.id, (state) => abandon.map((callId) => walkedCallOf(state, callId)));
+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),
+    }));
 }
-/**
- * The run that settles an answered call, as the model asked it. The session
- * keeps the event that settles it, and `ended` names the call once it has
- * (see `restoreUnended`).
- */
-async function* settleAnswered(ctx, request, session, answered, ended) {
-    const { callId, pending } = answered;
-    for await (const event of invokeAnswered(ctx, request, session.id, answered)) {
-        if (!ended.has(callId) && settlesToolCall(event, callId)) {
-            ended.add(callId);
-            await ctx.sessions.mutate(session.id, (state) => {
-                state.settled[callId] = { event, createdAt: pending.createdAt };
-            });
-        }
-        yield event;
-    }
+async function* settleAnswered(ctx, request, session, answered) {
+    yield* invokeAnswered(ctx, request, session.id, answered);
 }
-/**
- * A request that took calls and ended before they settled (the client went
- * away, the host failed, an earlier call's run threw) puts each back to wait
- * as it did, to be answered again, unless it paused on a gate again: the run
- * recorded that gate with its outcome.
- */
-async function restoreUnended(ctx, session, calls, ended) {
-    const unended = calls.flatMap((call) => ('pending' in call && !ended.has(call.callId) ? [call] : []));
-    if (!unended.length)
-        return;
-    await ctx.sessions.mutate(session.id, (state) => {
-        for (const { callId, pending } of unended)
-            state.gates[callId] ??= pending;
-    });
-}
-function invokeAnswered(ctx, request, sessionId, { callId, pending, answer }) {
-    return invokeTool({
+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,
@@ -361,58 +378,40 @@ function invokeAnswered(ctx, request, sessionId, { callId, pending, answer }) {
         promoted: pending.promoted,
         model: pending.model,
         signal: request.signal,
-        host: ctx.options.host?.(request),
+        host,
     });
 }
-/** Settles each walked-away call, and returns the input with their answers. */
-async function* walkAwayFrom(ctx, request, session, walked, ended) {
-    return yield* walkAway(walked.input, walked.calls.map((call) => ({
-        callId: call.callId,
-        events: 'settled' in call
-            ? once(call.settled.event)
-            : settleAnswered(ctx, request, session, call, ended),
-    })));
-}
 /** A settled call's answer, streamed again. */
-async function* once(event) {
-    yield event;
+async function* once(event, labels) {
+    yield withPublicLabels(event, labels);
 }
-async function* turnEvents(ctx, request, session, body, walked) {
-    const ended = new Set();
-    let input;
-    try {
-        input = walked.calls.length ? yield* walkAwayFrom(ctx, request, session, walked, ended) : walked.input;
-    }
-    finally {
-        await restoreUnended(ctx, session, walked.calls, ended);
-    }
-    if (!input)
-        return;
+/** 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, body.model);
-    // Only continue provider-side conversations this session started.
-    const previousInteractionId = body.previousInteractionId && state.interactions.includes(body.previousInteractionId)
-        ? body.previousInteractionId
-        : undefined;
-    const key = body.turnId ? inboxKey(session.id, body.turnId) : undefined;
+    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,
-            input,
-            previousInteractionId,
+            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: ctx.options.host?.(request),
-            ...(body.model ? { model: body.model } : {}),
-            ...(body.effort ? { effort: body.effort } : {}),
+            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), {
-            turnInput: input,
-            model: body.model,
+            profileId: ctx.profile.id,
+            turnInput: turn.input,
+            model: turn.model,
         });
     }
     finally {
@@ -420,27 +419,122 @@ async function* turnEvents(ctx, request, session, body, walked) {
             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;
-    const ended = new Set();
-    try {
-        if (answer.typed)
-            await saveCredential(ctx, session.id, answer.typed.slot, answer.typed.credential);
-        const events = settleAnswered(ctx, request, session, answered, ended);
-        yield* recorded(ctx.sessions, session.id, withAuthorizationUrls(ctx, request, session.id, events), {
-            turnInput: pending.turnInput,
-            model: pending.model,
-            promoted: pending.promoted,
-        });
-    }
-    finally {
-        await restoreUnended(ctx, session, [answered], ended);
-    }
+    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);
+    const body = await readBody(request, theoremSteerRequestSchema, ctx.options.maxRequestBytes);
     if (!(await ctx.inbox.enqueue(inboxKey(session.id, body.turnId), steerUnitOf(body)))) {
-        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+        // 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' },
         });
@@ -450,47 +544,118 @@ async function steer(ctx, request, session) {
 /** 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: ctx.options.host?.(request),
+        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, decision: body.decision, input: body.input, secret: body.secret };
+    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: lexiconText('error.request', {}, ctx.profile.lexicon),
+        error: labelText('error.request', {}, ctx.profile.labels),
         errorKind: 'request',
     });
 }
-/** The user's answer to a paused call. */
+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);
-    // 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)));
-    return eventStream(ctx, request, () => invokeEvents(ctx, request, session, answered));
+    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 === 'GET' && target === '')
+        return jsonResponse(200, { interface: hostInterface(ctx.profile, hostTool) });
     if (request.method === 'POST' && target === 'call') {
-        const body = await readBody(request, theoremHostCallRequestSchema);
+        const body = await readBody(request, theoremHostCallRequestSchema, ctx.options.maxRequestBytes);
         return eventStream(ctx, request, () => callEvents(ctx, request, session, body));
     }
     if (request.method === 'POST' && target === 'invoke')
@@ -498,60 +663,103 @@ async function hostRoute(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: clientInterface(ctx.profile) });
+        return jsonResponse(200, {
+            interface: clientProfileInterface(chat.profile, defaultKernelScope.tools),
+        });
     if (request.method !== 'POST' || target === '' || target === 'call')
         return refused(ctx);
-    if (target === 'turn') {
-        const body = await readBody(request, theoremTurnRequestSchema);
-        const input = userTurnInput(body.input);
-        // Take the walked-away calls before streaming, so a stale one is a reply status, not a stream error.
-        const calls = body.abandon ? await takeWalkedAway(ctx, session, input, body.abandon) : [];
-        return eventStream(ctx, request, () => turnEvents(ctx, request, session, body, { input, calls }));
-    }
+    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') {
-        // lexicon-exempt: builder config error at setup; no user sees it
+        // 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') {
-        // lexicon-exempt: builder config error at setup; no user sees it
+        // 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') {
-        // lexicon-exempt: builder config error at setup; no user sees it
+    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}'.`);
     }
-    return serve('createTheoremHandler', profile, options, options.steerInbox);
+    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);
+    return serve('createTheoremHostHandler', defineHostProfile('createTheoremHostHandler', options.profile), options);
+}
+/** The host profile a handler serves; any other type is the builder's mistake, refused at setup. */
+export function defineHostProfile(handler, definition) {
+    const profile = defineProfile(definition);
     if (profile.type !== 'host') {
-        // lexicon-exempt: builder config error at setup; no user sees it
-        throw new Error(`createTheoremHostHandler serves type 'host'; got type '${profile.type}'.`);
+        // labels-exempt: builder config error at setup; no user sees it
+        throw new Error(`${handler} serves type 'host'; got type '${profile.type}'.`);
     }
-    return serve('createTheoremHostHandler', profile, options);
+    return profile;
 }
-function serve(name, profile, options, steerInbox) {
+/** A registered tool a host profile can serve: builtins run only inside a model's turn. */
+export function hostTool(name) {
+    const registered = defaultKernelScope.tools.get(name);
+    return registered?.type === 'builtin' ? undefined : registered;
+}
+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,
-        inbox: steerInbox ?? createMemorySteerInbox(),
-        sessions: sessionStateStore(options.sessionStore ?? createMemorySessionStore(), gateTtlMs),
+        ...(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) => {
@@ -561,8 +769,7 @@ function serve(name, profile, options, steerInbox) {
             return withSessionCookie(await route(ctx, request, session), session);
         }
         catch (err) {
-            const error = publicMessage(ctx, err, request);
-            return withSessionCookie(jsonResponse(caughtStatus(err), { error, errorKind: errorKind(err) }), session);
+            return withSessionCookie(jsonResponse(caughtStatus(err), caughtError(ctx, err, request)), session);
         }
     };
 }