@theoremjs/react 0.3.0 → 0.3.1

package/hooks/use-theorem-decision.js

@@ -1,75 +1,12 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { clientFailure } from "../client/failure.js";
 import { useDescribed } from "./use-described.js";
+import { useOneCall } from "./use-one-call.js";
+const decideWith = (transport, signal, state, assets) => transport.decide(state, signal, assets);
 /**
  * One decision profile: describe it once, then `decide(state)` as often as
  * needed. A new decision aborts the one still running.
  */
 export function useTheoremDecision(transport) {
     const { iface, describeFailure } = useDescribed(transport);
-    const [run, setRun] = useState({
-        transport,
-        status: 'idle',
-        result: null,
-        elapsedMs: null,
-        failure: null,
-    });
-    const running = useRef(null);
-    useEffect(() => () => running.current?.abort(), [transport]);
-    const cancel = useCallback(() => {
-        running.current?.abort();
-        running.current = null;
-        setRun((previous) => previous.status === 'deciding'
-            ? { ...previous, status: previous.result ? 'done' : 'idle' }
-            : previous);
-    }, []);
-    const decide = useCallback(async (state) => {
-        running.current?.abort();
-        const controller = new AbortController();
-        running.current = controller;
-        setRun((previous) => ({
-            transport,
-            status: 'deciding',
-            result: previous.transport === transport ? previous.result : null,
-            elapsedMs: previous.transport === transport ? previous.elapsedMs : null,
-            failure: null,
-        }));
-        const started = performance.now();
-        try {
-            const reply = await transport.decide(state, controller.signal);
-            if (controller.signal.aborted)
-                return;
-            for (const record of reply.traces ?? [])
-                transport.traces?.push(record);
-            setRun({
-                transport,
-                status: 'done',
-                result: reply.result,
-                elapsedMs: performance.now() - started,
-                failure: null,
-            });
-        }
-        catch (err) {
-            if (controller.signal.aborted)
-                return;
-            setRun((previous) => ({ ...previous, status: 'error', failure: clientFailure(err) }));
-        }
-        finally {
-            if (running.current === controller)
-                running.current = null;
-        }
-    }, [transport]);
-    const visible = run.transport === transport
-        ? run
-        : { status: 'idle', result: null, elapsedMs: null, failure: null };
-    return {
-        iface,
-        describeFailure,
-        status: visible.status,
-        result: visible.result,
-        elapsedMs: visible.elapsedMs,
-        failure: visible.failure,
-        decide,
-        cancel,
-    };
+    const { call, ...run } = useOneCall(transport, 'deciding', decideWith);
+    return { iface, describeFailure, ...run, decide: call };
 }

package/hooks/use-theorem-embedding.d.ts

@@ -0,0 +1,18 @@
+import type { EmbeddingInput, EmbeddingResult } from '@theoremjs/agents';
+import type { EmbeddingInterface, EmbeddingTransport, EmbedOptions } from '../client/embedding-transport.ts';
+import type { ClientFailure } from '../client/failure.ts';
+import { type OneCallState } from './use-one-call.ts';
+export type TheoremEmbeddingState = {
+    /** The profile as the page sees it; null until the host describes it. */
+    iface: EmbeddingInterface | null;
+    /** Why the host could not describe the profile. */
+    describeFailure: ClientFailure | null;
+} & OneCallState<'embedding', EmbeddingResult>;
+/**
+ * One embedding profile: describe it once, then `embed(inputs)` as often as
+ * needed. A new embedding aborts the one still running.
+ */
+export declare function useTheoremEmbedding(transport: EmbeddingTransport): TheoremEmbeddingState & {
+    embed: (inputs: readonly EmbeddingInput[], options?: EmbedOptions) => Promise<void>;
+    cancel: () => void;
+};

package/hooks/use-theorem-embedding.js

@@ -0,0 +1,12 @@
+import { useDescribed } from "./use-described.js";
+import { useOneCall } from "./use-one-call.js";
+const embedWith = (transport, signal, inputs, options) => transport.embed(inputs, options, signal);
+/**
+ * One embedding profile: describe it once, then `embed(inputs)` as often as
+ * needed. A new embedding aborts the one still running.
+ */
+export function useTheoremEmbedding(transport) {
+    const { iface, describeFailure } = useDescribed(transport);
+    const { call, ...run } = useOneCall(transport, 'embedding', embedWith);
+    return { iface, describeFailure, ...run, embed: call };
+}

package/hooks/use-theorem-host.d.ts

@@ -2,7 +2,8 @@ import type { TurnEvent } from '@theoremjs/agents';
 import { type ClientFailure } from '../client/failure.ts';
 import type { ToolCall } from '../client/host-call.ts';
 import type { HostInterface, HostTransport } from '../client/host-transport.ts';
-import { type ToolGateResolution } from '../client/tool-resume.ts';
+import type { PageTools } from '../client/live/live-page-tool.ts';
+import { type PersonGateResolution } from '../client/tool-resume.ts';
 export type { ToolCall };
 /** One call of one of the host's tools, as it streams. */
 export type TheoremHostCall = {
@@ -20,7 +21,7 @@ export type TheoremHostCall = {
     /** The call never reached its tool, or its stream broke. */
     failure: ClientFailure | null;
     /** The answer on its way to the gate the call paused on. */
-    answering: ToolGateResolution['action'] | null;
+    answering: PersonGateResolution['action'] | null;
     startedAt: number;
     /** Round trip, once it settles or pauses. */
     elapsedMs: number | null;
@@ -37,8 +38,8 @@ export type TheoremHostState = {
  * as often as needed, and answer the gates a call pauses on. `run` returns the
  * call's id at once; calls run side by side, and `cancel` stops one.
  */
-export declare function useTheoremHost(transport: HostTransport): TheoremHostState & {
+export declare function useTheoremHost(source: HostTransport, pageTools?: PageTools): TheoremHostState & {
     run: (name: string, input: unknown) => string;
-    answer: (id: string, resolution: ToolGateResolution) => Promise<void>;
+    answer: (id: string, resolution: PersonGateResolution) => Promise<void>;
     cancel: (id: string) => void;
 };

package/hooks/use-theorem-host.js

@@ -1,7 +1,9 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
 import { toolCallsOf, toolSnapshotFromEvents } from '@theoremjs/agents/interface';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { clientFailure } from "../client/failure.js";
+import { withPageToolDispatch } from "../client/page-dispatch.js";
 import { continueGatedToolInvocation } from "../client/tool-resume.js";
+import { issuedOperationId } from "../client/turn-client.js";
 import { useDescribed } from "./use-described.js";
 function callId() {
     return typeof crypto !== 'undefined' && 'randomUUID' in crypto
@@ -18,11 +20,11 @@ function withEvent(call, event) {
  * as often as needed, and answer the gates a call pauses on. `run` returns the
  * call's id at once; calls run side by side, and `cancel` stops one.
  */
-export function useTheoremHost(transport) {
+export function useTheoremHost(source, pageTools) {
+    const transport = useMemo(() => withPageToolDispatch(source, pageTools), [source, pageTools]);
     const { iface, describeFailure } = useDescribed(transport);
     const [calls, setCalls] = useState([]);
     const running = useRef(new Map());
-    // Tools the user allowed for the rest of the page, for a host that replays paused calls.
     const permissions = useRef([]);
     const latest = useRef(calls);
     latest.current = calls;
@@ -48,11 +50,22 @@ export function useTheoremHost(transport) {
                     return;
                 update(id, (call) => withEvent(call, event));
             }, controller.signal);
-            update(id, (call) => ({ ...call, isRunning: false, answering: null, elapsedMs: performance.now() - started }));
+            update(id, (call) => ({
+                ...call,
+                isRunning: false,
+                answering: null,
+                elapsedMs: performance.now() - started,
+            }));
         }
         catch (err) {
             const failure = controller.signal.aborted ? null : clientFailure(err);
-            update(id, (call) => ({ ...call, isRunning: false, answering: null, failure, elapsedMs: performance.now() - started }));
+            update(id, (call) => ({
+                ...call,
+                isRunning: false,
+                answering: null,
+                failure,
+                elapsedMs: performance.now() - started,
+            }));
         }
         finally {
             if (running.current.get(id) === controller)
@@ -86,6 +99,7 @@ export function useTheoremHost(transport) {
         if (!held?.call || state?.phase !== 'gate')
             return;
         const gateId = held.call.callId;
+        const operationId = issuedOperationId(held.call);
         const reply = continueGatedToolInvocation({
             toolName: held.name,
             gate: state.gate,
@@ -98,12 +112,16 @@ export function useTheoremHost(transport) {
         update(id, (call) => ({ ...call, answering: resolution.action }));
         await stream(id, (onEvent, signal) => transport.invoke({
             gateId,
+            operationId,
             decision: reply.decision,
-            ...(reply.decision === 'approve' && reply.secret !== undefined ? { secret: reply.secret } : {}),
-            // A host without sessions (the playground) replays the paused call; others ignore it.
+            ...(reply.decision === 'approve' && reply.secret !== undefined
+                ? { secret: reply.secret }
+                : {}),
+            // why: A host without sessions (the studio) replays the paused call; others ignore it.
             replay: {
                 name: held.name,
-                input: held.input,
+                input: state.gate.preparedArguments ?? held.input,
+                gateKind: state.gate.kind,
                 sessionPermissions: permissions.current,
                 ...(snapshot ? { snapshot } : {}),
             },

package/hooks/use-theorem-interface.d.ts

@@ -1,7 +1,7 @@
 import type { ProfileInterface } from '@theoremjs/agents/interface';
-import { type ClientFailure } from '../client/failure.ts';
+import type { ClientFailure } from '../client/failure.ts';
 import type { TheoremTransport } from '../client/transport.ts';
-/** `failure` is worded with the default lexicon: the profile's is not known until it loads. */
+/** `failure` is worded with the default labels: the profile's is not known until it loads. */
 export type TheoremInterfaceState = {
     status: 'loading';
     iface: null;
@@ -15,5 +15,8 @@ export type TheoremInterfaceState = {
     iface: null;
     failure: ClientFailure;
 };
-/** Ask the transport for the host profile's client-safe interface. */
+/**
+ * Ask the transport for the host profile's client-safe interface. A new transport keeps the last
+ * interface up until it describes itself, as {@link useDescribed} does.
+ */
 export declare function useTheoremInterface(transport: TheoremTransport): TheoremInterfaceState;

package/hooks/use-theorem-interface.js

@@ -1,25 +1,15 @@
-import { useEffect, useState } from 'react';
-import { clientFailure } from "../client/failure.js";
+import { useMemo } from 'react';
+import { useDescribed } from "./use-described.js";
 const LOADING = { status: 'loading', iface: null, failure: null };
-/** Ask the transport for the host profile's client-safe interface. */
+/**
+ * Ask the transport for the host profile's client-safe interface. A new transport keeps the last
+ * interface up until it describes itself, as {@link useDescribed} does.
+ */
 export function useTheoremInterface(transport) {
-    const [state, setState] = useState(LOADING);
-    useEffect(() => {
-        const controller = new AbortController();
-        // A new transport keeps the last interface up until it describes itself, so swapping one
-        // in (a recompiled playground profile) doesn't blank the chat to a spinner.
-        setState((previous) => (previous.status === 'ready' ? previous : LOADING));
-        transport.describe(controller.signal).then((iface) => {
-            if (!controller.signal.aborted)
-                setState({ status: 'ready', iface, failure: null });
-        }, (err) => {
-            if (controller.signal.aborted)
-                return;
-            setState({ status: 'error', iface: null, failure: clientFailure(err) });
-        });
-        return () => {
-            controller.abort();
-        };
-    }, [transport]);
-    return state;
+    const { iface, describeFailure } = useDescribed(transport);
+    return useMemo(() => {
+        if (describeFailure)
+            return { status: 'error', iface: null, failure: describeFailure };
+        return iface ? { status: 'ready', iface, failure: null } : LOADING;
+    }, [iface, describeFailure]);
 }

package/index.d.ts

@@ -3,12 +3,15 @@
  *
  * - `@theoremjs/react`         hooks + transport (this entry)
  * - `@theoremjs/react/ui`      Astryx chat UI built on these hooks
- * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremHostHandler`) for the host side
+ * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremEmbeddingHandler`, `createTheoremHostHandler`) for the host side
  *
  * @module
  */
 export * from './client/index.ts';
-export { type ChatSnapshot, type SentTurn, type UseTheoremChatOptions, useTheoremChat, } from './hooks/use-theorem-chat.ts';
+export { type PageDispatchResult, withPageToolDispatch } from './client/page-dispatch.ts';
+export { type EmbeddingIndex, type IndexProgress, useEmbeddingIndex, } from './hooks/use-embedding-index.ts';
+export { type SentTurn, type UseTheoremChatOptions, useTheoremChat, } from './hooks/use-theorem-chat.ts';
 export { type TheoremDecisionState, useTheoremDecision } from './hooks/use-theorem-decision.ts';
-export { type TheoremHostCall, type TheoremHostState, useTheoremHost } from './hooks/use-theorem-host.ts';
+export { type TheoremEmbeddingState, useTheoremEmbedding, } from './hooks/use-theorem-embedding.ts';
+export { type TheoremHostCall, type TheoremHostState, useTheoremHost, } from './hooks/use-theorem-host.ts';
 export { type TheoremInterfaceState, useTheoremInterface } from './hooks/use-theorem-interface.ts';

package/index.js

@@ -3,12 +3,15 @@
  *
  * - `@theoremjs/react`         hooks + transport (this entry)
  * - `@theoremjs/react/ui`      Astryx chat UI built on these hooks
- * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremHostHandler`) for the host side
+ * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremEmbeddingHandler`, `createTheoremHostHandler`) for the host side
  *
  * @module
  */
 export * from "./client/index.js";
+export { withPageToolDispatch } from "./client/page-dispatch.js";
+export { useEmbeddingIndex, } from "./hooks/use-embedding-index.js";
 export { useTheoremChat, } from "./hooks/use-theorem-chat.js";
 export { useTheoremDecision } from "./hooks/use-theorem-decision.js";
-export { useTheoremHost } from "./hooks/use-theorem-host.js";
+export { useTheoremEmbedding, } from "./hooks/use-theorem-embedding.js";
+export { useTheoremHost, } from "./hooks/use-theorem-host.js";
 export { useTheoremInterface } from "./hooks/use-theorem-interface.js";

package/live.d.ts

@@ -3,6 +3,7 @@
  *
  * @module
  */
+export type { LiveCallOptions, PageTool, PageToolAnswer, PageTools, } from './client/live/live-page-tool.ts';
 export type { LiveConnection } from './client/live-client.ts';
 export type { LiveRunnerProps } from './ui/LiveRunner.tsx';
 export { LiveRunner } from './ui/LiveRunner.tsx';

package/live.js

@@ -3,7 +3,7 @@
  *
  * @module
  */
-// Astryx's documented order: reset → components → theme.
+// why: Astryx's documented order: reset → components → theme.
 import '@astryxdesign/core/reset.css';
 import '@astryxdesign/core/astryx.css';
 import './ui/built/theme.css';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/masudl-hub/theoremai",
+    "url": "git+https://github.com/masudl-hub/theoremai.git",
     "directory": "react"
   },
   "sideEffects": [
@@ -49,17 +49,18 @@
     "./styles/*": "./styles/*"
   },
   "dependencies": {
+    "@speed-highlight/core": "2.1.0",
     "@tabler/icons-react": "^3.46.0",
     "intl-messageformat": "^11.2.9",
     "recharts": "^3.10.1"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.6.3",
-    "@astryxdesign/theme-neutral": "0.6.3",
+    "@astryxdesign/core": "0.7.0",
+    "@astryxdesign/theme-neutral": "0.7.0",
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.0"
+    "@theoremjs/agents": "^0.3.1"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/server/checkpoint-ownership.d.ts

@@ -0,0 +1,6 @@
+import { type ProviderCheckpoint, type TurnHistoryMessage } from '@theoremjs/agents';
+import type { TheoremSessionState } from './session-store.ts';
+export declare function checkpointIdentity(checkpoint: ProviderCheckpoint): Promise<string>;
+export declare function checkpointOwnershipKey(identity: string, operations: TheoremSessionState['operations']): Promise<string>;
+export declare function requireOwnedCheckpoint(identities: readonly string[], checkpoint: ProviderCheckpoint | undefined, operations?: TheoremSessionState['operations'], portableHistory?: readonly TurnHistoryMessage[]): Promise<ProviderCheckpoint | undefined>;
+export declare function retainedCheckpointIdentities(existing: readonly string[], added: readonly string[], limit: number): string[];

package/server/checkpoint-ownership.js

@@ -0,0 +1,42 @@
+import { labelText, providerCheckpointSchema, TheoremError, toolInvocationHash, } from '@theoremjs/agents';
+export function checkpointIdentity(checkpoint) {
+    return toolInvocationHash(providerCheckpointSchema.parse(checkpoint));
+}
+export async function checkpointOwnershipKey(identity, operations) {
+    const rows = Object.entries(operations)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([id, operation]) => operation.status === 'ready'
+        ? [id, operation.status, operation.profileId, operation.readyAt]
+        : [id, operation.status, operation.profileId, operation.toolId, operation.invocationHash]);
+    const epoch = await toolInvocationHash(rows);
+    return `${identity}:${epoch}`;
+}
+export async function requireOwnedCheckpoint(identities, checkpoint, operations = {}, portableHistory) {
+    if (checkpoint === undefined)
+        return undefined;
+    const parsed = providerCheckpointSchema.parse(checkpoint);
+    const identity = await checkpointIdentity(parsed);
+    const key = await checkpointOwnershipKey(identity, operations);
+    const records = Object.values(operations);
+    const portableSettlements = portableHistory !== undefined &&
+        records.length > 0 &&
+        identities.some((saved) => saved.startsWith(`${identity}:`)) &&
+        records.every((operation) => operation.status === 'settled' &&
+            operation.outcome.effects !== 'unknown' &&
+            operation.outcome.event.tool.readBack !== undefined &&
+            portableHistory.some((message) => message.role === 'tool' &&
+                message.tool_call_id === operation.callId &&
+                message.name === operation.toolId &&
+                message.content === operation.outcome.event.tool.readBack));
+    if (!identities.includes(key) &&
+        !portableSettlements &&
+        !(records.length === 0 && identities.includes(identity))) {
+        throw new TheoremError('request', labelText('session.provider_state_unowned'), {
+            copy: { key: 'session.provider_state_unowned' },
+        });
+    }
+    return parsed;
+}
+export function retainedCheckpointIdentities(existing, added, limit) {
+    return [...new Set([...existing, ...added].reverse())].slice(0, limit).reverse();
+}

package/server/conversation-store.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Where a chat's conversation lives for `createTheoremHandler`: the transcript
+ * the person reads and the history the model reads next. The host owns it; the
+ * browser holds only an opaque ref the store issued, and never sends history.
+ *
+ * A database store keys the conversation by its id. The sealed store keeps
+ * nothing: its ref is the conversation itself, encrypted and signed with the
+ * host's key, so the browser carries what it cannot read or change.
+ *
+ * @module
+ */
+import { type ProviderCheckpoint, TheoremError, type TurnEvent, type TurnHistoryMessage, z } from '@theoremjs/agents';
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+import { type MemorySessionStoreOptions } from './session-store.ts';
+/** A reply paused on gates: its events so far, and the history it was given. */
+export type PausedReply = {
+    events: TurnEvent[];
+    /** The history the reply was given; its events append to this when it commits. */
+    base: TurnHistoryMessage[];
+    /** How many of `events` `base` already holds: a compaction mid-reply moves the base. */
+    baseEvents: number;
+    /** How long the reply worked before it paused (ms), approval waits excluded. */
+    workedMs: number;
+    /** When the reply last paused (epoch ms). */
+    endedAt: number;
+    /** The model and effort the reply ran with, for the run that goes on after its gates. */
+    model?: string;
+    effort?: string;
+};
+/** One conversation as the host stores it. */
+export type StoredConversation = {
+    version: 1;
+    /** What the person reads, without the paused reply. */
+    transcript: TranscriptBlock[];
+    /** What the model reads on the next turn, compacted when the profile compacts. */
+    history: TurnHistoryMessage[];
+    providerState?: ProviderCheckpoint;
+    /** The last turn's input tokens, for the compaction meter. */
+    inputTokens?: number;
+    /** The history's size in tokens as the last compaction measured it. */
+    historyTokens?: number;
+    paused?: PausedReply;
+};
+/** A stored conversation as a host's own store reads it back. */
+export declare const storedConversationSchema: z.ZodType<StoredConversation>;
+/** An empty conversation: what a chat with no ref starts from. */
+export declare function emptyConversation(): StoredConversation;
+export interface ConversationSnapshot {
+    revision: string;
+    conversation: StoredConversation;
+}
+export type ConversationWriteResult = {
+    written: true;
+    ref: string;
+    revision: string;
+} | {
+    written: false;
+};
+/**
+ * Where conversations live. `ref` is the store's own: the handler hands it to
+ * the browser and back, and never reads it. Every read and write names the
+ * session, so a ref from another session opens nothing.
+ */
+export interface TheoremConversationStore {
+    /** The conversation, or undefined when this session has none under `ref`. */
+    read(sessionId: string, ref: string): Promise<ConversationSnapshot | undefined>;
+    /**
+     * Compare and replace. A null `ref` creates a conversation; otherwise the
+     * write lands only on a conversation this session can read, while its
+     * stored revision is still `expectedRevision`.
+     */
+    write(sessionId: string, ref: string | null, expectedRevision: string | null, next: StoredConversation): Promise<ConversationWriteResult>;
+}
+/** Refuses a ref the store does not know or cannot open: the browser reads `session.conversation_unknown`. */
+export declare function unknownConversation(cause?: unknown): TheoremError;
+/** Conversations in process memory: forgotten when idle, oldest evicted first. For one instance. */
+export declare function createMemoryConversationStore(options?: Omit<MemorySessionStoreOptions, 'sessionLimits'>): TheoremConversationStore;
+export type SealedConversationStoreOptions = {
+    /** Every sealing key still in use, by version: each at least 32 bytes, kept off the browser. */
+    keys: Readonly<Record<number, string>>;
+    /** The key that seals new writes. */
+    keyVersion: number;
+};
+/**
+ * A store for a host that keeps nothing. The ref is the conversation sealed
+ * with the host's key and bound to the session: the browser carries it and
+ * cannot read or change it, and it opens in no other session.
+ *
+ * It cannot tell an older seal from the newest, so an older seal opens: like a
+ * rewind, it returns a conversation the host wrote. Its revision is the seal.
+ */
+export declare function createSealedConversationStore(options: SealedConversationStoreOptions): TheoremConversationStore;

package/server/conversation-store.js

@@ -0,0 +1,131 @@
+/**
+ * Where a chat's conversation lives for `createTheoremHandler`: the transcript
+ * the person reads and the history the model reads next. The host owns it; the
+ * browser holds only an opaque ref the store issued, and never sends history.
+ *
+ * A database store keys the conversation by its id. The sealed store keeps
+ * nothing: its ref is the conversation itself, encrypted and signed with the
+ * host's key, so the browser carries what it cannot read or change.
+ *
+ * @module
+ */
+import { labelText, providerCheckpointSchema, TheoremError, turnEventSchema, turnHistoryMessageSchema, z, } from '@theoremjs/agents';
+import { openSecret, sealSecret } from '@theoremjs/agents/kernel';
+import { transcriptBlockSchema } from "../client/transcript-schema.js";
+import { memoryStoreLimits } from "./session-store.js";
+const pausedReply = z.object({
+    events: z.array(turnEventSchema),
+    base: z.array(turnHistoryMessageSchema),
+    baseEvents: z.number().int().nonnegative(),
+    workedMs: z.number().nonnegative(),
+    endedAt: z.number(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+});
+true;
+const storedConversation = z.object({
+    version: z.literal(1),
+    transcript: z.array(transcriptBlockSchema),
+    history: z.array(turnHistoryMessageSchema),
+    providerState: providerCheckpointSchema.optional(),
+    inputTokens: z.number().optional(),
+    historyTokens: z.number().optional(),
+    paused: pausedReply.optional(),
+});
+true;
+/** A stored conversation as a host's own store reads it back. */
+export const storedConversationSchema = storedConversation;
+/** An empty conversation: what a chat with no ref starts from. */
+export function emptyConversation() {
+    return { version: 1, transcript: [], history: [] };
+}
+/** Refuses a ref the store does not know or cannot open: the browser reads `session.conversation_unknown`. */
+export function unknownConversation(cause) {
+    return new TheoremError('request', labelText('session.conversation_unknown'), {
+        copy: { key: 'session.conversation_unknown' },
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+/** Conversations in process memory: forgotten when idle, oldest evicted first. For one instance. */
+export function createMemoryConversationStore(options = {}) {
+    const { ttlMs, maxSessions } = memoryStoreLimits(options);
+    const conversations = new Map();
+    const current = (sessionId, ref) => {
+        const entry = conversations.get(ref);
+        if (!entry || entry.sessionId !== sessionId)
+            return undefined;
+        if (Date.now() - entry.touched >= ttlMs) {
+            conversations.delete(ref);
+            return undefined;
+        }
+        return entry.snapshot;
+    };
+    const written = (...[sessionId, ref, expectedRevision, next]) => {
+        const snapshot = ref === null ? undefined : current(sessionId, ref);
+        // invariant: A ref this session cannot read takes no write, so no session overwrites another's conversation.
+        if (ref !== null && snapshot === undefined)
+            return { written: false };
+        if ((snapshot?.revision ?? null) !== expectedRevision)
+            return { written: false };
+        const conversation = storedConversation.parse(next);
+        const key = ref ?? crypto.randomUUID();
+        const revision = crypto.randomUUID();
+        conversations.delete(key);
+        conversations.set(key, {
+            sessionId,
+            snapshot: { revision, conversation: structuredClone(conversation) },
+            touched: Date.now(),
+        });
+        while (conversations.size > maxSessions) {
+            const oldest = conversations.keys().next().value;
+            if (oldest === undefined)
+                break;
+            conversations.delete(oldest);
+        }
+        return { written: true, ref: key, revision };
+    };
+    return {
+        read: (sessionId, ref) => Promise.resolve(structuredClone(current(sessionId, ref))),
+        // why: A write that fails its check rejects, as any store's does, rather than throwing at the call.
+        write: (...args) => new Promise((resolve) => resolve(written(...args))),
+    };
+}
+/**
+ * A store for a host that keeps nothing. The ref is the conversation sealed
+ * with the host's key and bound to the session: the browser carries it and
+ * cannot read or change it, and it opens in no other session.
+ *
+ * It cannot tell an older seal from the newest, so an older seal opens: like a
+ * rewind, it returns a conversation the host wrote. Its revision is the seal.
+ */
+export function createSealedConversationStore(options) {
+    const sealKey = options.keys[options.keyVersion];
+    if (sealKey === undefined) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'conversation_seal_key_missing', keyVersion: options.keyVersion },
+        });
+    }
+    return {
+        async read(sessionId, ref) {
+            const plaintext = await openSecret({ sealed: ref, keys: options.keys, binding: [sessionId] })
+                // why: A seal that does not open is a ref this session does not own; the caller refuses it.
+                .catch(() => undefined);
+            if (plaintext === undefined)
+                return undefined;
+            const conversation = storedConversation.parse(JSON.parse(plaintext));
+            return { revision: ref, conversation };
+        },
+        async write(sessionId, ref, expectedRevision, next) {
+            if (ref !== expectedRevision)
+                return { written: false };
+            const conversation = storedConversation.parse(next);
+            const sealed = await sealSecret({
+                plaintext: JSON.stringify(conversation),
+                key: sealKey,
+                binding: [sessionId],
+                keyVersion: options.keyVersion,
+            });
+            return { written: true, ref: sealed, revision: sealed };
+        },
+    };
+}