@theoremjs/react 0.0.0-stage → 0.3.1

package/server/session-store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Server-held session state for `createTheoremHandler`.
+ *
+ * Everything that grants authority lives here, never in the request body:
+ * which tools the user allowed for the session, which paused tool calls may be
+ * resumed (and with exactly what input), and which provider interactions this
+ * session may continue.
+ *
+ * @module
+ */
+import { z } from '@theoremjs/agents';
+import type { ToolGateAuth } from '@theoremjs/agents/interface';
+import type { AnsweredGate, ToolGate, ToolId, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, TurnInput, TurnToolSnapshot } from '@theoremjs/agents/kernel';
+import { type TheoremSessionLimits } from './session-limits.ts';
+/** A tool call the kernel paused on a gate, as the server saw it. */
+export type PendingToolGate = {
+    profileId: string;
+    operationId: string;
+    callId: string;
+    name: string;
+    /** The model's arguments; an approval runs the call with exactly these. */
+    arguments: Record<string, unknown>;
+    /** The gate, and for a sign-in gate the credential slot and kind it waits for. */
+    gate: Pick<ToolGate, 'kind' | 'permission'> & {
+        auth?: ToolGateAuth;
+    };
+    snapshot?: TurnToolSnapshot;
+    promoted: ToolId[];
+    turnInput: TurnInput;
+    model?: string;
+    createdAt: number;
+    expiresAt?: number;
+};
+export type SessionPageGrant = {
+    grantId: string;
+    expiresAt: number;
+    resultHash?: string;
+};
+export type SessionToolOperation = {
+    status: 'ready';
+    profileId: string;
+    pending: PendingToolGate;
+    answer: Omit<AnsweredGate, 'typed'>;
+    readyAt: number;
+} | (ToolOperationIdentity & {
+    status: 'running';
+    claimToken: string;
+    startedAt: number;
+    pageGrant?: SessionPageGrant;
+}) | (ToolOperationIdentity & {
+    status: 'settled';
+    pageGrant?: SessionPageGrant;
+    outcome: ToolOperationOutcome;
+    settledAt: number;
+    retainUntil?: number;
+}) | (ToolOperationIdentity & {
+    status: 'uncertain';
+    pageGrant?: SessionPageGrant;
+    claimToken: string;
+    reason: ToolOperationUncertainty;
+    detectedAt: number;
+});
+export declare const DEFAULT_OPERATION_RETENTION_MS: number;
+export type TheoremSessionState = {
+    version: 3;
+    operations: Record<string, SessionToolOperation>;
+    /** Tool ids the user allowed for the rest of this session. */
+    permissions: string[];
+    /** invariant: Operation IDs index issued gates; both IDs must match an answer. */
+    gates: Record<string, PendingToolGate>;
+    /** Checkpoint identities this session produced, newest last. */
+    providerCheckpoints: string[];
+};
+/** Stored authority is checked before the handler reads or changes it. */
+export declare const theoremSessionStateSchema: z.ZodType<TheoremSessionState>;
+export interface SessionSnapshot {
+    revision: string;
+    state: TheoremSessionState;
+}
+export type SessionWriteResult = {
+    written: true;
+    revision: string;
+} | {
+    written: false;
+};
+/**
+ * Where session state lives. The default is process memory — use a shared
+ * store (KV, Redis, a database row) when requests can reach different instances.
+ */
+export interface TheoremSessionStore {
+    load(sessionId: string): Promise<SessionSnapshot | undefined>;
+    /** Compare and replace atomically; null creates only an absent session. */
+    compareAndSwap(sessionId: string, expectedRevision: string | null, next: TheoremSessionState): Promise<SessionWriteResult>;
+}
+export declare function emptySessionState(): TheoremSessionState;
+/** Drop gates (waiting or settled) older than `ttlMs`. */
+export declare function pruneGates<Gate extends {
+    createdAt: number;
+    expiresAt?: number;
+}>(gates: Record<string, Gate>, now: number, ttlMs: number): Record<string, Gate>;
+export type MemorySessionStoreOptions = {
+    /** Finite authority storage bounds. */
+    sessionLimits?: Partial<TheoremSessionLimits>;
+    /** invariant: Idle retention is in milliseconds. Protected authority remains. Default 24h. */
+    ttlMs?: number;
+    /** Oldest sessions are evicted past this count. Default 10 000. */
+    maxSessions?: number;
+};
+export declare function memoryStoreLimits(options: MemorySessionStoreOptions): {
+    ttlMs: number;
+    maxSessions: number;
+};
+/** A value kept per session id for the separate credential store. */
+export type PerSessionStore<T> = {
+    load(sessionId: string): T | undefined | Promise<T | undefined>;
+    save(sessionId: string, value: T): void | Promise<void>;
+};
+/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
+export declare function createMemorySessionMap<T>(options?: MemorySessionStoreOptions): {
+    load(sessionId: string): T | undefined;
+    save(sessionId: string, value: T): void;
+};
+export declare function createMemorySessionStore(options?: MemorySessionStoreOptions): TheoremSessionStore;

package/server/session-store.js

@@ -0,0 +1,264 @@
+/**
+ * Server-held session state for `createTheoremHandler`.
+ *
+ * Everything that grants authority lives here, never in the request body:
+ * which tools the user allowed for the session, which paused tool calls may be
+ * resumed (and with exactly what input), and which provider interactions this
+ * session may continue.
+ *
+ * @module
+ */
+import { jsonObjectSchema, jsonValueSchema, labelText, savedToolInvocationSchema, TheoremError, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_PERMISSION, toolOperationOutcomeSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
+import { gateExpired } from '@theoremjs/agents/kernel';
+import { checkSessionLimits, resolveSessionLimits, } from "./session-limits.js";
+export const DEFAULT_OPERATION_RETENTION_MS = 24 * 60 * 60 * 1000;
+const blobSchema = z.strictObject({
+    data: z.string(),
+    mimeType: z.string(),
+    name: z.string().optional(),
+});
+const inputSchema = z.strictObject({
+    text: z.string().optional(),
+    role: z.string().optional(),
+    slots: z.record(z.string(), z.string()).optional(),
+    context: z
+        .strictObject({ client: jsonValueSchema.optional(), server: jsonValueSchema.optional() })
+        .optional(),
+    attachments: z
+        .array(z.union([
+        blobSchema,
+        z.strictObject({
+            uri: z.string(),
+            mimeType: z.string(),
+            name: z.string().optional(),
+        }),
+    ]))
+        .optional(),
+    voice: z.array(blobSchema).optional(),
+    history: z.array(turnHistoryMessageSchema).optional(),
+    repair: z
+        .strictObject({ previousOutput: z.string(), rejection: z.string(), guidance: z.string() })
+        .optional(),
+    historyTokens: z.number().nonnegative().optional(),
+    inputTokens: z.number().nonnegative().optional(),
+});
+const pendingSchema = z.strictObject({
+    profileId: z.string().min(1),
+    operationId: z.string().min(1).max(256),
+    callId: z.string().min(1),
+    name: z.string().min(1),
+    arguments: jsonObjectSchema,
+    gate: z
+        .strictObject({
+        kind: z.enum(TOOL_GATE_KINDS),
+        permission: z.enum(TOOL_PERMISSION).optional(),
+        auth: z
+            .strictObject({
+            slot: z.string().min(1),
+            authType: z.enum(TOOL_AUTH_TYPES),
+            service: z.string().min(1),
+        })
+            .optional(),
+    })
+        .superRefine((gate, ctx) => {
+        if ((gate.kind === 'auth') !== (gate.auth !== undefined)) {
+            ctx.addIssue({ code: 'custom', path: ['auth'] });
+        }
+    }),
+    snapshot: turnToolSnapshotSchema.optional(),
+    promoted: z.array(z.string().min(1)),
+    turnInput: inputSchema,
+    model: z.string().optional(),
+    createdAt: z.number().finite().nonnegative(),
+    expiresAt: z.number().finite().nonnegative().optional(),
+});
+const acceptedAnswerSchema = z.strictObject({
+    input: jsonObjectSchema,
+    resume: z.strictObject({
+        granted: z.boolean().optional(),
+        gateKind: z.enum(TOOL_GATE_KINDS).optional(),
+        cause: z.enum(['declined', 'abandoned', 'expired']).optional(),
+        signIn: z.boolean().optional(),
+        edited: z.strictObject({ from: jsonObjectSchema }).optional(),
+    }),
+    sessionPermissions: z.array(z.string().min(1)),
+    page: z
+        .union([
+        z.strictObject({ output: jsonValueSchema }),
+        z.strictObject({ timedOut: z.literal(true) }),
+        z.strictObject({ unanswered: z.literal(true) }),
+    ])
+        .optional(),
+});
+const identityFields = {
+    operationId: z.string().min(1).max(256),
+    callId: z.string().min(1),
+    profileId: z.string().min(1),
+    toolId: z.string().min(1),
+    invocationHash: z.string().min(1),
+    invocation: savedToolInvocationSchema.optional(),
+};
+const pageGrant = z.strictObject({
+    grantId: z.string().min(1),
+    expiresAt: z.number().finite().positive(),
+    resultHash: z.string().optional(),
+});
+const operationSchema = z.discriminatedUnion('status', [
+    z.strictObject({
+        status: z.literal('ready'),
+        profileId: z.string().min(1),
+        pending: pendingSchema,
+        answer: acceptedAnswerSchema,
+        readyAt: z.number().finite().nonnegative(),
+    }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('running'),
+        pageGrant: pageGrant.optional(),
+        claimToken: z.string().min(1),
+        startedAt: z.number().finite().nonnegative(),
+    }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('settled'),
+        pageGrant: pageGrant.optional(),
+        outcome: toolOperationOutcomeSchema,
+        settledAt: z.number().finite().nonnegative(),
+        retainUntil: z.number().finite().nonnegative().optional(),
+    }),
+    z.strictObject({
+        ...identityFields,
+        status: z.literal('uncertain'),
+        pageGrant: pageGrant.optional(),
+        claimToken: z.string().min(1),
+        reason: z.enum(['execution_interrupted', 'settlement_write_failed', 'worker_lost']),
+        detectedAt: z.number().finite().nonnegative(),
+    }),
+]);
+/** Stored authority is checked before the handler reads or changes it. */
+export const theoremSessionStateSchema = z
+    .strictObject({
+    version: z.literal(3),
+    operations: z.record(z.string().min(1), operationSchema),
+    permissions: z.array(z.string().min(1)),
+    gates: z.record(z.string().min(1), pendingSchema),
+    providerCheckpoints: z.array(z.string().min(1)),
+})
+    .superRefine((state, ctx) => {
+    for (const [operationId, operation] of Object.entries(state.operations)) {
+        const reference = operation.status === 'ready' ? operation.pending : operation;
+        if (reference.operationId !== operationId ||
+            (operation.status === 'ready' && operation.profileId !== operation.pending.profileId) ||
+            operationId in state.gates ||
+            (operation.status === 'settled' &&
+                (operation.outcome.event.tool.operationId !== operationId ||
+                    operation.outcome.event.tool.callId !== operation.callId ||
+                    operation.outcome.event.tool.name !== operation.toolId))) {
+            ctx.addIssue({ code: 'custom', path: ['operations', operationId] });
+        }
+    }
+    for (const [operationId, gate] of Object.entries(state.gates)) {
+        if (operationId !== gate.operationId)
+            ctx.addIssue({ code: 'custom', path: ['gates', operationId] });
+    }
+});
+export function emptySessionState() {
+    return {
+        version: 3,
+        operations: {},
+        permissions: [],
+        gates: {},
+        providerCheckpoints: [],
+    };
+}
+/** Drop gates (waiting or settled) older than `ttlMs`. */
+export function pruneGates(gates, now, ttlMs) {
+    return Object.fromEntries(Object.entries(gates).filter(([, gate]) => gate.expiresAt !== undefined
+        ? now < gate.expiresAt
+        : !gateExpired(gate.createdAt, now, ttlMs)));
+}
+export function memoryStoreLimits(options) {
+    const ttlMs = options.ttlMs ?? 24 * 60 * 60 * 1000;
+    const maxSessions = options.maxSessions ?? 10_000;
+    if (!Number.isFinite(ttlMs) ||
+        ttlMs <= 0 ||
+        !Number.isSafeInteger(maxSessions) ||
+        maxSessions <= 0) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'session_store_options', ttlMs, maxSessions },
+        });
+    }
+    return { ttlMs, maxSessions };
+}
+/** A per-session value kept in process memory: forgotten when idle, oldest evicted first. */
+export function createMemorySessionMap(options = {}) {
+    const { ttlMs, maxSessions } = memoryStoreLimits(options);
+    const sessions = new Map();
+    return {
+        load(sessionId) {
+            const entry = sessions.get(sessionId);
+            if (!entry)
+                return undefined;
+            if (Date.now() - entry.touched > ttlMs) {
+                sessions.delete(sessionId);
+                return undefined;
+            }
+            return structuredClone(entry.value);
+        },
+        save(sessionId, value) {
+            sessions.delete(sessionId);
+            sessions.set(sessionId, { value: structuredClone(value), touched: Date.now() });
+            while (sessions.size > maxSessions) {
+                const oldest = sessions.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                sessions.delete(oldest);
+            }
+        },
+    };
+}
+export function createMemorySessionStore(options = {}) {
+    const { ttlMs, maxSessions } = memoryStoreLimits(options);
+    const limits = resolveSessionLimits(options.sessionLimits);
+    const sessions = new Map();
+    const held = (entry) => Object.values(entry.snapshot.state.gates).some((gate) => gate.expiresAt === undefined || Date.now() < gate.expiresAt) ||
+        Object.values(entry.snapshot.state.operations).some((operation) => operation.status !== 'settled' ||
+            Date.now() <
+                (operation.retainUntil ?? operation.settledAt + DEFAULT_OPERATION_RETENTION_MS));
+    const current = (sessionId) => {
+        const entry = sessions.get(sessionId);
+        if (entry && !held(entry) && Date.now() - entry.touched >= ttlMs) {
+            sessions.delete(sessionId);
+            return undefined;
+        }
+        return entry?.snapshot;
+    };
+    return {
+        load(sessionId) {
+            return Promise.resolve(structuredClone(current(sessionId)));
+        },
+        compareAndSwap(sessionId, expectedRevision, next) {
+            const snapshot = current(sessionId);
+            if ((snapshot?.revision ?? null) !== expectedRevision)
+                return Promise.resolve({ written: false });
+            const state = theoremSessionStateSchema.parse(next);
+            checkSessionLimits(state, limits);
+            if (!snapshot && sessions.size >= maxSessions) {
+                const removable = [...sessions].find(([, entry]) => !held(entry));
+                if (!removable) {
+                    throw new TheoremError('unavailable', labelText('error.unavailable'), {
+                        cause: { code: 'session_store_capacity' },
+                    });
+                }
+                sessions.delete(removable[0]);
+            }
+            const revision = crypto.randomUUID();
+            sessions.delete(sessionId);
+            sessions.set(sessionId, {
+                snapshot: { revision, state: structuredClone(state) },
+                touched: Date.now(),
+            });
+            return Promise.resolve({ written: true, revision });
+        },
+    };
+}

package/server/single-action.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The shape the decision and embedding handlers share: `GET <base>` answers the profile's
+ * interface, `POST <base>/<action>` answers `{ result }`, and a failure is worded with the
+ * profile's labels.
+ *
+ * @module
+ */
+import { type ProfileDefinition } from '@theoremjs/agents';
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+export type SingleActionOptions = {
+    /** The last path segment the POST is sent to, such as `decide`. */
+    action: string;
+    /** What `GET <base>` answers, as `{ interface }`. */
+    iface: unknown;
+    labels: ProfileDefinition['labels'];
+    clientEvents?: ClientTurnOptions;
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+export declare function singleActionHandler({ action, iface, labels, clientEvents, onError }: SingleActionOptions, run: (request: Request) => Promise<unknown>): (request: Request) => Promise<Response>;

package/server/single-action.js

@@ -0,0 +1,30 @@
+/**
+ * The shape the decision and embedding handlers share: `GET <base>` answers the profile's
+ * interface, `POST <base>/<action>` answers `{ result }`, and a failure is worded with the
+ * profile's labels.
+ *
+ * @module
+ */
+import { labelText } from '@theoremjs/agents';
+import { caughtStatus, clientError, HTTP_METHOD, } from '@theoremjs/agents/host';
+import { jsonResponse } from "./json-response.js";
+export function singleActionHandler({ action, iface, labels, clientEvents, onError }, run) {
+    const isAction = (request) => new URL(request.url).pathname.split('/').filter(Boolean).at(-1) === action;
+    return async (request) => {
+        try {
+            if (request.method === 'GET' && !isAction(request))
+                return jsonResponse(200, { interface: iface });
+            if (request.method !== 'POST' || !isAction(request)) {
+                return jsonResponse(HTTP_METHOD, {
+                    error: labelText('error.request', {}, labels),
+                    errorKind: 'request',
+                });
+            }
+            return jsonResponse(200, { result: await run(request) });
+        }
+        catch (err) {
+            onError?.(err, { request });
+            return jsonResponse(caughtStatus(err), clientError(err, labels, clientEvents));
+        }
+    };
+}

package/server/steer-inbox.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Mid-turn steer inbox — the client posts user messages while a turn streams;
+ * the turn's stage handler drains one unit per inject-capable stage.
+ *
+ * @module
+ */
+import { type StageHandler, type TurnHistoryMessage } from '@theoremjs/agents';
+import type { TheoremSteerRequest } from '../client/transport.ts';
+/** One steer: the client's id for it, reported back in `stage.injected` once it lands. */
+export type SteerUnit = {
+    id: string;
+    messages: TurnHistoryMessage[];
+};
+/**
+ * A steer as a client posts it (a checked `TheoremSteerRequest`): its user
+ * messages. Other roles are dropped — a client never injects system,
+ * assistant or tool turns — and a steer with no user message is refused.
+ */
+export declare function steerUnitOf(steer: Pick<TheoremSteerRequest, 'id' | 'inject'>): SteerUnit;
+/** Lands the inbox's next steer, one per steerable stage, named by its id. */
+export declare function steerStage(inbox: SteerInbox, key: string): StageHandler;
+/**
+ * Keyed by client turn id. The default lives in process memory, which is only
+ * correct when steer POSTs reach the same process as the turn — swap in a
+ * shared store (KV, Redis, Durable Object) for multi-instance hosts.
+ */
+export interface SteerInbox {
+    open(turnId: string): void | Promise<void>;
+    /** Returns `false` when no turn with this id is open. */
+    enqueue(turnId: string, unit: SteerUnit): boolean | Promise<boolean>;
+    /** Next unit, FIFO, or `undefined`. */
+    consume(turnId: string): SteerUnit | undefined | Promise<SteerUnit | undefined>;
+    close(turnId: string): void | Promise<void>;
+}
+export declare function createMemorySteerInbox(): SteerInbox;

package/server/steer-inbox.js

@@ -0,0 +1,52 @@
+/**
+ * Mid-turn steer inbox — the client posts user messages while a turn streams;
+ * the turn's stage handler drains one unit per inject-capable stage.
+ *
+ * @module
+ */
+import { TheoremError } from '@theoremjs/agents';
+/** The stages a steer can land at. */
+const STEER_STAGES = new Set(['pre_turn', 'post_tool', 'before_end']);
+/**
+ * A steer as a client posts it (a checked `TheoremSteerRequest`): its user
+ * messages. Other roles are dropped — a client never injects system,
+ * assistant or tool turns — and a steer with no user message is refused.
+ */
+export function steerUnitOf(steer) {
+    const messages = steer.inject.filter((message) => message.role === 'user');
+    // labels-exempt: internal diagnostic; the user reads the error kind's (or copy key's) wording
+    if (!messages.length)
+        throw new TheoremError('request', 'inject must contain user messages');
+    return { id: steer.id, messages };
+}
+/** Lands the inbox's next steer, one per steerable stage, named by its id. */
+export function steerStage(inbox, key) {
+    return async ({ stage }) => {
+        if (!STEER_STAGES.has(stage))
+            return;
+        const unit = await inbox.consume(key);
+        return unit ? { inject: unit.messages, injectId: unit.id } : undefined;
+    };
+}
+export function createMemorySteerInbox() {
+    const queues = new Map();
+    return {
+        open(turnId) {
+            if (!queues.has(turnId))
+                queues.set(turnId, []);
+        },
+        enqueue(turnId, unit) {
+            const queue = queues.get(turnId);
+            if (!queue)
+                return false;
+            queue.push(structuredClone(unit));
+            return true;
+        },
+        consume(turnId) {
+            return queues.get(turnId)?.shift();
+        },
+        close(turnId) {
+            queues.delete(turnId);
+        },
+    };
+}

package/server/tool-operations.d.ts

@@ -0,0 +1,6 @@
+import { type ToolExecutionCoordinator } from '@theoremjs/agents';
+import type { TheoremSessionState } from './session-store.ts';
+export declare function sessionToolCoordinator(store: {
+    mutate<T>(id: string, change: (state: TheoremSessionState) => T): Promise<T>;
+}, sessionId: string): ToolExecutionCoordinator;
+export declare function sameAcceptedAnswer(left: unknown, right: unknown): boolean;

package/server/tool-operations.js

@@ -0,0 +1,132 @@
+import { labelText, TheoremError, } from '@theoremjs/agents';
+function unavailable() {
+    throw new TheoremError('unavailable', labelText('error.unavailable'));
+}
+function sameOperation(record, identity) {
+    return (record.operationId === identity.operationId &&
+        record.callId === identity.callId &&
+        record.profileId === identity.profileId &&
+        record.toolId === identity.toolId &&
+        record.invocationHash === identity.invocationHash);
+}
+function checkedRecord(state, identity) {
+    if (identity.operationId === '__proto__')
+        unavailable();
+    const record = Object.hasOwn(state.operations, identity.operationId)
+        ? state.operations[identity.operationId]
+        : undefined;
+    if (record?.status === 'ready') {
+        if (record.pending.callId !== identity.callId ||
+            record.pending.profileId !== identity.profileId ||
+            record.pending.name !== identity.toolId ||
+            record.profileId !== identity.profileId)
+            unavailable();
+    }
+    else if (record && !sameOperation(record, identity))
+        unavailable();
+    return record;
+}
+function checkedClaim(state, claim) {
+    const record = checkedRecord(state, claim);
+    if (!record ||
+        (record.status !== 'running' && record.status !== 'uncertain') ||
+        record.claimToken !== claim.claimToken)
+        unavailable();
+    return record;
+}
+function existingResult(record) {
+    if (record?.status === 'settled')
+        return { kind: 'settled', outcome: record.outcome };
+    if (record?.status === 'running')
+        return { kind: 'running' };
+    if (record?.status === 'uncertain')
+        return { kind: 'uncertain' };
+    return undefined;
+}
+function saveOutcome(state, identity, outcome) {
+    const before = state.operations[identity.operationId];
+    const pageGrant = before && before.status !== 'ready' ? before.pageGrant : undefined;
+    const settledAt = Date.now();
+    const { operationId, callId, profileId, toolId, invocationHash, invocation } = identity;
+    state.operations[identity.operationId] = {
+        operationId,
+        callId,
+        profileId,
+        toolId,
+        invocationHash,
+        ...(invocation ? { invocation } : {}),
+        status: 'settled',
+        ...(pageGrant ? { pageGrant } : {}),
+        outcome,
+        settledAt,
+    };
+}
+export function sessionToolCoordinator(store, sessionId) {
+    return {
+        lookup(identity) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedRecord(state, identity);
+                return existingResult(record);
+            });
+        },
+        begin(identity) {
+            const claimToken = crypto.randomUUID();
+            const startedAt = Date.now();
+            return store.mutate(sessionId, (state) => {
+                const record = checkedRecord(state, identity);
+                const existing = existingResult(record);
+                if (existing)
+                    return existing;
+                state.operations[identity.operationId] = {
+                    ...identity,
+                    status: 'running',
+                    claimToken,
+                    startedAt,
+                };
+                return { kind: 'acquired', claimToken };
+            });
+        },
+        settle(claim, outcome) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedClaim(state, claim);
+                saveOutcome(state, { ...claim, invocation: record.invocation }, outcome);
+            });
+        },
+        settleNotStarted(identity, outcome) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedRecord(state, identity);
+                if (record && record.status !== 'ready')
+                    unavailable();
+                if (outcome.effects !== 'not_started')
+                    unavailable();
+                saveOutcome(state, identity, outcome);
+            });
+        },
+        markUncertain(claim, reason) {
+            return store.mutate(sessionId, (state) => {
+                const record = checkedClaim(state, claim);
+                state.operations[claim.operationId] = {
+                    ...claim,
+                    invocation: record.invocation,
+                    ...(record.pageGrant ? { pageGrant: record.pageGrant } : {}),
+                    status: 'uncertain',
+                    reason,
+                    detectedAt: Date.now(),
+                };
+            });
+        },
+    };
+}
+export function sameAcceptedAnswer(left, right) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value)
+                .filter(([, item]) => item !== undefined)
+                .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+                .map(([key, item]) => [key, canonical(item)]));
+        return value;
+    };
+    return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}

package/server/turn-input.d.ts

@@ -0,0 +1,10 @@
+import type { SessionRequest, TurnInput } from '@theoremjs/agents';
+import type { LiveOpenMessage } from '../client/live-messages.ts';
+import type { TheoremTurnInput } from '../client/transport.ts';
+/** A turn input off the wire as the kernel takes it: the page's context is the client's. */
+export declare function kernelTurnInput(input: TheoremTurnInput, server?: unknown): TurnInput;
+/**
+ * What a live call's first message asks of the session, as `runSession` takes
+ * it: the page's context is the client's, and `server` is the host's own.
+ */
+export declare function liveSessionOpen(open: LiveOpenMessage, server?: unknown): Pick<SessionRequest, 'slots' | 'context' | 'providerState' | 'awayMs' | 'history'>;