@theoremjs/react 0.3.0 → 0.3.1

package/server/mod.d.ts

@@ -5,12 +5,21 @@
  * @module
  */
 export { theoremHostCallRequestSchema } from '../client/host-transport.ts';
-export type { LiveClientMessage } from '../client/live-messages.ts';
-export { theoremInvokeRequestSchema, theoremReplaySchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from '../client/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 { createTheoremHandler, createTheoremHostHandler, readBody, type TheoremHandlerOptions, type TheoremHostHandlerOptions, type TheoremRequestContext, theoremSessionId, } from './handler.ts';
-export { checkRequest, parseLiveClientMessage } from './request-check.ts';
-export { createMemorySessionStore, type MemorySessionStoreOptions, type PendingToolGate, type SettledToolGate, type TheoremSessionState, type TheoremSessionStore, } from './session-store.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 { 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 { checkWalkAway, type WalkedAwayCall, walkAway } from './walk-away.ts';
+export { sessionToolCoordinator } from './tool-operations.ts';
+export { kernelTurnInput, liveSessionOpen } from './turn-input.ts';

package/server/mod.js

@@ -5,11 +5,19 @@
  * @module
  */
 export { theoremHostCallRequestSchema } from "../client/host-transport.js";
-export { theoremInvokeRequestSchema, theoremReplaySchema, theoremSteerRequestSchema, theoremTurnRequestSchema, } from "../client/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 { createTheoremHandler, createTheoremHostHandler, readBody, theoremSessionId, } from "./handler.js";
-export { checkRequest, parseLiveClientMessage } from "./request-check.js";
-export { createMemorySessionStore, } from "./session-store.js";
+export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, } from "./embedding-handler.js";
+export { createTheoremHandler, createTheoremHostHandler, readBody, theoremSession, theoremSessionId, } from "./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 { checkWalkAway, walkAway } from "./walk-away.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

@@ -6,7 +6,7 @@
  * @module
  */
 import { type z } from '@theoremjs/agents';
-import { type LiveClientMessage } from '../client/live-messages.ts';
+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;
 /**
@@ -14,3 +14,8 @@ export declare function checkRequest<T>(schema: z.ZodType<T>, raw: unknown, what
  * `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;

package/server/request-check.js

@@ -5,30 +5,45 @@
  *
  * @module
  */
-import { TheoremError } from '@theoremjs/agents';
-import { liveClientMessageSchema } from "../client/live-messages.js";
+import { labelText, TheoremError } from '@theoremjs/agents';
+import { liveClientMessageSchema, liveOpenMessageSchema, } from "../client/live-messages.js";
 import { issueSummary } from "../client/wire-line.js";
+import { requestByteLimit } from "./request-body.js";
 /** `raw` checked against `schema`; a missing or malformed field is a `request` error. */
 export function checkRequest(schema, raw, what) {
     const parsed = schema.safeParse(raw);
     if (!parsed.success) {
-        // 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', `${what} failed its check: ${issueSummary(parsed.error)}`);
     }
     return parsed.data;
 }
+function liveFrame(text) {
+    const limit = requestByteLimit();
+    if (text.length > limit || new TextEncoder().encode(text).byteLength > limit)
+        throw new TheoremError('request', labelText('error.request'));
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // invariant: JSON parser diagnostics can contain browser values.
+        throw new TheoremError('request', labelText('error.request'), {
+            cause: { code: 'request_json' },
+        });
+    }
+}
 /**
  * One text frame from the live client, as a relay reads it: JSON that passes
  * `liveClientMessageSchema`, else a `request` error.
  */
 export function parseLiveClientMessage(text) {
-    let raw;
-    try {
-        raw = JSON.parse(text);
-    }
-    catch (cause) {
-        // lexicon-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
-        throw new TheoremError('request', 'live message must be JSON', { cause });
-    }
-    return checkRequest(liveClientMessageSchema, raw, 'live message');
+    return checkRequest(liveClientMessageSchema, liveFrame(text), 'live message');
+}
+/**
+ * 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 function parseLiveOpenMessage(text) {
+    // labels-exempt: internal diagnostic; the user reads the error kind's wording
+    return checkRequest(liveOpenMessageSchema, liveFrame(text), 'live open message');
 }

package/server/session-authority.d.ts

@@ -0,0 +1,8 @@
+import { type TheoremSessionLimits } from './session-limits.ts';
+import { type TheoremSessionState, type TheoremSessionStore } from './session-store.ts';
+export type MutableStore<T> = {
+    read(sessionId: string): Promise<T>;
+    mutate<R>(sessionId: string, change: (value: T) => R | Promise<R>): Promise<R>;
+};
+/** Session state, with expired gates dropped as it loads so they can't be answered. */
+export declare function sessionStateStore(store: TheoremSessionStore, gateTtlMs: number, operationRetentionMs: number, limits: TheoremSessionLimits): MutableStore<TheoremSessionState>;

package/server/session-authority.js

@@ -0,0 +1,78 @@
+import { labelText, TheoremError, z } from '@theoremjs/agents';
+import { checkSessionLimits } from "./session-limits.js";
+import { emptySessionState, pruneGates, theoremSessionStateSchema, } from "./session-store.js";
+/** Session state, with expired gates dropped as it loads so they can't be answered. */
+export function sessionStateStore(store, gateTtlMs, operationRetentionMs, limits) {
+    if (typeof store.compareAndSwap !== 'function') {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'session_store_contract', required: 'compareAndSwap' },
+        });
+    }
+    const writeResult = z.discriminatedUnion('written', [
+        z.strictObject({ written: z.literal(false) }),
+        z.strictObject({ written: z.literal(true), revision: z.string().min(1) }),
+    ]);
+    const load = async (sessionId, now) => {
+        const snapshot = await store.load(sessionId);
+        const parsed = theoremSessionStateSchema.safeParse(snapshot === undefined ? emptySessionState() : snapshot.state);
+        if (!parsed.success ||
+            (snapshot !== undefined && (typeof snapshot.revision !== 'string' || !snapshot.revision))) {
+            throw new TheoremError('config', labelText('error.config'), {
+                cause: { code: 'session_store_state' },
+            });
+        }
+        const state = structuredClone(parsed.data);
+        for (const gate of Object.values(state.gates))
+            gate.expiresAt ??= gate.createdAt + gateTtlMs;
+        state.gates = pruneGates(state.gates, now, gateTtlMs);
+        for (const operation of Object.values(state.operations)) {
+            if (operation.status === 'ready' && operation.answer.resume.granted === true)
+                operation.answer.resume.gateKind ??= operation.pending.gate.kind;
+        }
+        state.operations = Object.fromEntries(Object.entries(state.operations).filter(([, operation]) => operation.status !== 'settled' ||
+            now < (operation.retainUntil ?? operation.settledAt + operationRetentionMs)));
+        return { revision: snapshot?.revision ?? null, state };
+    };
+    return {
+        async read(sessionId) {
+            return (await load(sessionId, Date.now())).state;
+        },
+        async mutate(sessionId, change) {
+            const now = Date.now();
+            for (let conflict = 0; conflict < 8; conflict++) {
+                const { revision, state } = await load(sessionId, now);
+                const result = await change(state);
+                for (const gate of Object.values(state.gates))
+                    gate.expiresAt ??= gate.createdAt + gateTtlMs;
+                for (const operation of Object.values(state.operations)) {
+                    if (operation.status === 'settled')
+                        operation.retainUntil ??= operation.settledAt + operationRetentionMs;
+                }
+                checkSessionLimits(state, limits);
+                const next = theoremSessionStateSchema.safeParse(state);
+                if (!next.success) {
+                    throw new TheoremError('config', labelText('error.config'), {
+                        cause: { code: 'session_store_transition' },
+                    });
+                }
+                const written = writeResult.safeParse(await store.compareAndSwap(sessionId, revision, next.data));
+                if (!written.success) {
+                    throw new TheoremError('config', labelText('error.config'), {
+                        cause: { code: 'session_store_write_result' },
+                    });
+                }
+                if (written.data.written) {
+                    if (written.data.revision === revision) {
+                        throw new TheoremError('config', labelText('error.config'), {
+                            cause: { code: 'session_store_revision' },
+                        });
+                    }
+                    return result;
+                }
+            }
+            throw new TheoremError('unavailable', labelText('error.unavailable'), {
+                cause: { code: 'session_store_contention' },
+            });
+        },
+    };
+}

package/server/session-boundary.d.ts

@@ -0,0 +1,26 @@
+import { type PageToolExecution, type ProviderCheckpoint, type SessionRequest, type ToolExecutionCoordinator, type TurnHistoryMessage } from '@theoremjs/agents';
+import { type LiveOpenMessage } from '../client/live-messages.ts';
+import { type PageToolBroker, type PageToolResult } from './page-dispatch.ts';
+import { type TheoremSessionLimits } from './session-limits.ts';
+import { type TheoremSessionStore } from './session-store.ts';
+export interface SessionBoundaryOptions {
+    request: Request;
+    session?: (request: Request) => string | undefined | Promise<string | undefined>;
+    sessionStore: TheoremSessionStore;
+    gateTtlMs?: number;
+    operationRetentionMs?: number;
+    sessionLimits?: Partial<TheoremSessionLimits>;
+    pageToolBroker?: PageToolBroker;
+}
+export type PreparedLiveOpen = Pick<SessionRequest, 'history' | 'slots' | 'context' | 'providerState' | 'awayMs'>;
+export interface TheoremSessionBoundary {
+    sessionId: string;
+    setCookie?: string;
+    prepareLiveOpen(open: LiveOpenMessage, serverContext?: unknown): Promise<PreparedLiveOpen>;
+    prepareProviderState(checkpoint: ProviderCheckpoint | undefined, history?: readonly TurnHistoryMessage[]): Promise<ProviderCheckpoint | undefined>;
+    recordCheckpoint(checkpoint: ProviderCheckpoint): Promise<void>;
+    toolExecution: ToolExecutionCoordinator;
+    pageExecution: PageToolExecution;
+    answerPageResult(result: PageToolResult): Promise<boolean>;
+}
+export declare function createTheoremSessionBoundary(options: SessionBoundaryOptions): Promise<TheoremSessionBoundary>;

package/server/session-boundary.js

@@ -0,0 +1,64 @@
+import { labelText, TheoremError, } from '@theoremjs/agents';
+import { resolveGateTtlMs } from '@theoremjs/agents/kernel';
+import { liveOpenMessageSchema } from "../client/live-messages.js";
+import { checkpointIdentity, checkpointOwnershipKey, requireOwnedCheckpoint, retainedCheckpointIdentities, } from "./checkpoint-ownership.js";
+import { createMemoryPageToolBroker, sessionPageDispatch, } from "./page-dispatch.js";
+import { checkRequest } from "./request-check.js";
+import { sessionStateStore } from "./session-authority.js";
+import { theoremSession } from "./session-identity.js";
+import { resolveSessionLimits } from "./session-limits.js";
+import { DEFAULT_OPERATION_RETENTION_MS } from "./session-store.js";
+import { sessionToolCoordinator } from "./tool-operations.js";
+import { liveSessionOpen } from "./turn-input.js";
+export async function createTheoremSessionBoundary(options) {
+    const cookie = options.session ? undefined : theoremSession(options.request);
+    const id = options.session ? (await options.session(options.request))?.trim() : cookie?.id;
+    if (!id)
+        throw new TheoremError('auth', labelText('session.sign_in'), {
+            copy: { key: 'session.sign_in' },
+        });
+    const retention = options.operationRetentionMs ?? DEFAULT_OPERATION_RETENTION_MS;
+    if (!Number.isSafeInteger(retention) || retention <= 0)
+        throw new TheoremError('config', labelText('error.config'));
+    const limits = resolveSessionLimits(options.sessionLimits);
+    const store = sessionStateStore(options.sessionStore, resolveGateTtlMs('session boundary', options.gateTtlMs), retention, limits);
+    // invariant: Refuse unavailable or malformed authority before an upstream connection opens.
+    await store.read(id);
+    const page = sessionPageDispatch(store, id, options.pageToolBroker ?? createMemoryPageToolBroker());
+    return {
+        pageExecution: page.execution,
+        answerPageResult: page.answer,
+        sessionId: id,
+        ...(cookie?.setCookie ? { setCookie: cookie.setCookie } : {}),
+        toolExecution: sessionToolCoordinator(store, id),
+        async prepareLiveOpen(raw, server) {
+            const open = checkRequest(liveOpenMessageSchema, raw, 'live open');
+            const prepared = liveSessionOpen(open, server);
+            const state = await store.read(id);
+            const providerState = await requireOwnedCheckpoint(state.providerCheckpoints, prepared.providerState, state.operations);
+            if (providerState &&
+                Object.values(state.operations).some((operation) => operation.status !== 'settled')) {
+                throw new TheoremError('unavailable', labelText('tool.execution_uncertain'), {
+                    copy: { key: 'tool.execution_uncertain' },
+                });
+            }
+            return {
+                ...prepared,
+                providerState,
+                ...(prepared.history
+                    ? { history: prepared.history.filter((message) => message.role !== 'system') }
+                    : {}),
+            };
+        },
+        async prepareProviderState(checkpoint, history) {
+            const state = await store.read(id);
+            return requireOwnedCheckpoint(state.providerCheckpoints, checkpoint, state.operations, history);
+        },
+        async recordCheckpoint(checkpoint) {
+            const identity = await checkpointIdentity(checkpoint);
+            await store.mutate(id, async (state) => {
+                state.providerCheckpoints = retainedCheckpointIdentities(state.providerCheckpoints, [await checkpointOwnershipKey(identity, state.operations)], limits.maxCheckpoints);
+            });
+        },
+    };
+}

package/server/session-identity.d.ts

@@ -0,0 +1,16 @@
+export type Session = {
+    id: string;
+    setCookie?: string;
+};
+/**
+ * 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 declare function theoremSessionId(request: Request): string | undefined;
+/**
+ * The handler's cookie session for `request`: its id, and the `Set-Cookie` header to send when
+ * the request had none. A page that starts a conversation before the chat's first request uses
+ * it, so the chat and the conversation share one session.
+ */
+export declare function theoremSession(request: Request): Session;

package/server/session-identity.js

@@ -0,0 +1,41 @@
+import { toBase64Url } from '@theoremjs/agents/kernel';
+const SESSION_COOKIE = 'theorem_session';
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
+/** How long a visitor keeps their session, so a chat they come back to opens as theirs: 30 days. */
+const SESSION_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+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;
+}
+/**
+ * The handler's cookie session for `request`: its id, and the `Set-Cookie` header to send when
+ * the request had none. A page that starts a conversation before the chat's first request uses
+ * it, so the chat and the conversation share one session.
+ */
+export function theoremSession(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=/; Max-Age=${SESSION_MAX_AGE_SECONDS}; HttpOnly; SameSite=Lax${secure}`,
+    };
+}

package/server/session-limits.d.ts

@@ -0,0 +1,12 @@
+import type { TheoremSessionState } from './session-store.ts';
+export interface TheoremSessionLimits {
+    maxGates: number;
+    maxOperations: number;
+    maxCheckpoints: number;
+    maxPermissions: number;
+    maxStateBytes: number;
+    maxInvocationBytes: number;
+    maxOutcomeBytes: number;
+}
+export declare function resolveSessionLimits(options?: Partial<TheoremSessionLimits>): TheoremSessionLimits;
+export declare function checkSessionLimits(state: TheoremSessionState, limits: TheoremSessionLimits): void;

package/server/session-limits.js

@@ -0,0 +1,59 @@
+import { labelText, TheoremError } from '@theoremjs/agents';
+const DEFAULTS = {
+    maxGates: 32,
+    maxOperations: 128,
+    maxCheckpoints: 256,
+    maxPermissions: 2048,
+    maxStateBytes: 32 * 1024 * 1024,
+    maxInvocationBytes: 256 * 1024,
+    maxOutcomeBytes: 256 * 1024,
+};
+export function resolveSessionLimits(options = {}) {
+    const limits = { ...DEFAULTS, ...options };
+    if (Object.keys(options).some((key) => !Object.hasOwn(DEFAULTS, key)) ||
+        Object.values(limits).some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'session_limits' },
+        });
+    }
+    return limits;
+}
+function bytes(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function capacity() {
+    throw new TheoremError('unavailable', labelText('error.unavailable'), {
+        cause: { code: 'session_state_capacity' },
+    });
+}
+export function checkSessionLimits(state, limits) {
+    const gates = Object.values(state.gates);
+    const operations = Object.values(state.operations);
+    if (gates.length > limits.maxGates ||
+        operations.length > limits.maxOperations ||
+        state.providerCheckpoints.length > limits.maxCheckpoints ||
+        state.permissions.length > limits.maxPermissions)
+        capacity();
+    for (const gate of gates)
+        if (bytes(gate) > limits.maxInvocationBytes)
+            capacity();
+    let reserved = gates.length * limits.maxOutcomeBytes;
+    for (const operation of operations) {
+        if (operation.status !== 'ready' &&
+            operation.invocation &&
+            bytes(operation.invocation) > limits.maxInvocationBytes)
+            capacity();
+        if (operation.status === 'settled') {
+            if (bytes(operation.outcome) > limits.maxOutcomeBytes)
+                capacity();
+        }
+        else {
+            reserved += limits.maxOutcomeBytes;
+            if (operation.status === 'ready' && bytes(operation) > limits.maxInvocationBytes)
+                capacity();
+        }
+    }
+    // invariant: Reserve terminal evidence before dispatch; unresolved records are never evicted to make room.
+    if (bytes(state) + reserved > limits.maxStateBytes)
+        capacity();
+}