@theoremjs/web 0.0.0-stage → 0.3.4-next.375.ga2d1878

package/client/turn-client.js

@@ -0,0 +1,88 @@
+import { labelText, TheoremError } from '@theoremjs/agents';
+import { foldTurnEvents, prepareUserTurn, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
+import { filesToPending } from "./encode-files.js";
+import { defaultModel } from "./generation-selection.js";
+export function issuedOperationId(call) {
+    if (!call.operationId)
+        throw new TheoremError('request', labelText('session.gate_expired'));
+    return call.operationId;
+}
+function resolveModelId(iface, session) {
+    return session.selectedModel ?? defaultModel(iface);
+}
+function resolveEffort(iface, session, modelId) {
+    if (!modelId || !Object.hasOwn(iface.models, modelId))
+        return undefined;
+    const binding = iface.models[modelId];
+    if (!binding.allowEffortSelect)
+        return undefined;
+    return session.selectedEffort ?? binding.defaultEffort;
+}
+/** Model / effort selection the host should honour for this session. */
+function generationFields(iface, session) {
+    const modelId = resolveModelId(iface, session);
+    const model = iface.allowModelSelect ? modelId : undefined;
+    const effort = resolveEffort(iface, session, modelId);
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}) };
+}
+function gateReplay(iface, session, call) {
+    return {
+        name: call.name,
+        input: call.input,
+        ...(call.gateKind ? { gateKind: call.gateKind } : {}),
+        sessionPermissions: call.sessionPermissions ?? session.sessionPermissions,
+        ...(session.toolSnapshot ? { snapshot: session.toolSnapshot } : {}),
+        ...(session.promotedToolIds.length ? { promoted: [...session.promotedToolIds] } : {}),
+        ...generationFields(iface, session),
+    };
+}
+function scopeFields(scope) {
+    return {
+        ...(scope.conversation ? { conversation: scope.conversation } : {}),
+        ...(scope.turnId ? { turnId: scope.turnId } : {}),
+    };
+}
+export function buildTurnRequest(iface, session, input, options = {}) {
+    const abandon = (options.walkAway?.calls ?? []).map((call) => ({
+        callId: call.callId,
+        operationId: issuedOperationId(call),
+    }));
+    return {
+        ...scopeFields(options),
+        ...generationFields(iface, session),
+        input,
+        ...(abandon.length ? { abandon } : {}),
+        replay: { sessionPermissions: session.sessionPermissions },
+    };
+}
+export function buildInvokeRequest(iface, session, args, scope = {}) {
+    return {
+        ...scopeFields(scope),
+        gateId: args.gateId,
+        operationId: args.operationId,
+        decision: args.decision,
+        ...(args.secret === undefined ? {} : { secret: args.secret }),
+        ...(args.page === undefined ? {} : { page: args.page }),
+        replay: gateReplay(iface, session, {
+            ...args,
+            gateKind: args.gateKind ??
+                (session.gatedTool?.callId === args.gateId ? session.gatedTool.gateKind : undefined),
+        }),
+    };
+}
+export function projectUserTurn(iface, draft) {
+    return prepareUserTurn(iface.inputs, draft, iface.guardrails);
+}
+export function prepareComposerTurn(iface, text, pendingFiles, pendingVoice = []) {
+    return projectUserTurn(iface, {
+        ...(text.trim() ? { text } : {}),
+        ...(pendingFiles.length ? { attachments: filesToPending(pendingFiles) } : {}),
+        ...(pendingVoice.length ? { voice: filesToPending(pendingVoice) } : {}),
+    });
+}
+export function foldAssistantTurn(iface, events) {
+    // why: Its `turn-done` blocks stay: hidden in the view, they carry the reply's worked time.
+    return foldTurnEvents(events, {
+        showThoughts: streamThoughtsEnabled(iface.outputs),
+    });
+}

package/client/wire-line.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Every value that reaches the browser over a wire (NDJSON lines, live
+ * envelopes) is checked against its schema here. A line or event of a kind the
+ * client does not know is reported as `unsupported`, and one that fails its
+ * check (not JSON, no kind, or a known kind that fails its schema) as
+ * `malformed`; either way the reply goes on. A whole reply that fails its check
+ * (the profile description) is `bad_response`.
+ *
+ * @module
+ */
+import { TheoremError, z } from '@theoremjs/agents';
+/**
+ * A line or envelope of a kind the client does not know. The server never
+ * sends it; the client's parser makes it so the host sees what arrived. Theorem
+ * shows nothing for it.
+ */
+export type UnsupportedEvent = {
+    type: 'unsupported';
+    received: string;
+    raw: unknown;
+};
+/**
+ * A line or event that failed its wire check. The server never sends it; the
+ * client's reader makes it, leaves the line out, and the reply goes on. `error`
+ * is `bad_response`: its message names what broke, never the value, and the
+ * user reads `session.part_skipped`.
+ */
+export type MalformedEvent = {
+    type: 'malformed';
+    error: TheoremError;
+};
+/** Every kind a wire carries, and the schema a value of that kind must pass. */
+export type WireLines<Line extends {
+    type: string;
+}> = {
+    readonly [K in Line['type']]: z.ZodType<Extract<Line, {
+        type: K;
+    }>>;
+};
+/**
+ * Issue paths and codes only: a failure names what broke, never the value. A
+ * union that matched no branch lists each branch's issues.
+ */
+export declare function issueSummary(error: z.ZodError): string;
+/** `raw` as `schema` reads it; one that fails is `bad_response`, naming `what`. */
+export declare function checkWire<T>(schema: z.ZodType<T>, raw: unknown, what: string): T;
+/** One wire value: a known kind that passed its schema, `unsupported`, or `malformed`. */
+export declare function readWireValue<Line extends {
+    type: string;
+}>(lines: WireLines<Line>, raw: unknown): Line | UnsupportedEvent | MalformedEvent;
+/** One wire line's text: {@link readWireValue} of its JSON, or `malformed` when it is not JSON. */
+export declare function readWireLine<Line extends {
+    type: string;
+}>(lines: WireLines<Line>, text: string): Line | UnsupportedEvent | MalformedEvent;
+/** A whole reply's JSON text as a value; text that is not JSON is `bad_response`. */
+export declare function parseWireJson(text: string): unknown;

package/client/wire-line.js

@@ -0,0 +1,90 @@
+/**
+ * Every value that reaches the browser over a wire (NDJSON lines, live
+ * envelopes) is checked against its schema here. A line or event of a kind the
+ * client does not know is reported as `unsupported`, and one that fails its
+ * check (not JSON, no kind, or a known kind that fails its schema) as
+ * `malformed`; either way the reply goes on. A whole reply that fails its check
+ * (the profile description) is `bad_response`.
+ *
+ * @module
+ */
+import { TheoremError, z } from '@theoremjs/agents';
+const wireKind = z.object({ type: z.string() });
+function isKnown(lines, type) {
+    return Object.hasOwn(lines, type);
+}
+function issuesSummary(issues, at) {
+    return issues
+        .map((issue) => {
+        const path = [...at, ...issue.path];
+        const head = `${path.map(String).join('.') || '(root)'} ${issue.code}`;
+        if (issue.code !== 'invalid_union' || issue.errors.length === 0)
+            return head;
+        return `${head} [${issue.errors.map((branch) => issuesSummary(branch, path)).join(' | ')}]`;
+    })
+        .join('; ');
+}
+/**
+ * Issue paths and codes only: a failure names what broke, never the value. A
+ * union that matched no branch lists each branch's issues.
+ */
+export function issueSummary(error) {
+    return issuesSummary(error.issues, []);
+}
+function badResponse(what, error) {
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    return new TheoremError('bad_response', `${what} failed its wire check: ${issueSummary(error)}`);
+}
+/** `raw` as `schema` reads it; one that fails is `bad_response`, naming `what`. */
+export function checkWire(schema, raw, what) {
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success)
+        throw badResponse(what, parsed.error);
+    return parsed.data;
+}
+function malformed(message) {
+    return {
+        type: 'malformed',
+        error: new TheoremError('bad_response', message, { copy: { key: 'session.part_skipped' } }),
+    };
+}
+/** One wire value: a known kind that passed its schema, `unsupported`, or `malformed`. */
+export function readWireValue(lines, raw) {
+    const kind = wireKind.safeParse(raw);
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
+    if (!kind.success)
+        return malformed(`a line without a kind failed its wire check: ${issueSummary(kind.error)}`);
+    const { type } = kind.data;
+    if (!isKnown(lines, type))
+        return { type: 'unsupported', received: type, raw };
+    const line = lines[type].safeParse(raw);
+    if (line.success)
+        return line.data;
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
+    return malformed(`a '${type}' line failed its wire check: ${issueSummary(line.error)}`);
+}
+/** JSON text as a value, or undefined when it is not JSON. The parser's own error quotes the text, so it is not kept. */
+function jsonValue(text) {
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return undefined;
+        throw err;
+    }
+}
+/** One wire line's text: {@link readWireValue} of its JSON, or `malformed` when it is not JSON. */
+export function readWireLine(lines, text) {
+    const json = jsonValue(text);
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
+    return json ? readWireValue(lines, json.value) : malformed('a line is not JSON');
+}
+/** A whole reply's JSON text as a value; text that is not JSON is `bad_response`. */
+export function parseWireJson(text) {
+    const json = jsonValue(text);
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    if (!json)
+        throw new TheoremError('bad_response', 'a line is not JSON');
+    return json.value;
+}

package/client/worklets/mic-capture.js

@@ -0,0 +1,16 @@
+/**
+ * AudioWorklet processor that forwards mono mic frames to the main thread.
+ * Plain JS: it runs in the AudioWorkletGlobalScope as its own module, loaded
+ * by URL (see `../mic-capture.ts`), so it imports nothing and ships as is.
+ */
+registerProcessor(
+  'mic-capture-processor',
+  class MicCaptureProcessor extends AudioWorkletProcessor {
+    process(inputs) {
+      const channel = inputs[0][0];
+      const copy = new Float32Array(channel);
+      this.port.postMessage(copy, [copy.buffer]);
+      return true;
+    }
+  },
+);

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@theoremjs/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.4-next.375.ga2d1878",
+  "description": "Theorem on the web platform, with no UI framework: Web-standard server handlers that serve a profile, and the browser client that talks to them.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masudl-hub/theoremai.git",
+    "directory": "web"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./server": {
+      "types": "./server/mod.d.ts",
+      "default": "./server/mod.js"
+    },
+    "./client": {
+      "types": "./client/index.d.ts",
+      "default": "./client/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.6.5",
+    "@theoremjs/agents": "^0.3.4-next.375.ga2d1878"
+  }
+}

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 };
+        },
+    };
+}