@theoremjs/react 0.0.0-stage → 0.3.0

package/client/transport.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Transport contract between a Theorem chat UI and the host that runs turns.
+ *
+ * The browser never holds the profile: it asks the transport to `describe` the
+ * profile's client-safe interface, then streams turns / tool invokes through it.
+ * `createHttpTransport` speaks to `createTheoremHandler` (`@theoremjs/react/server`);
+ * hosts with their own wire format implement {@link TheoremTransport} directly.
+ *
+ * @module
+ */
+import { type ErrorKind, type TurnEvent, type TurnHistoryMessage, type TurnToolSnapshot, z } from '@theoremjs/agents';
+import { type ProfileInterface } from '@theoremjs/agents/interface';
+import type { TraceFeed } from './trace-feed.ts';
+import { type MalformedEvent, type UnsupportedEvent, type WireLines } from './wire-line.ts';
+export type { MalformedEvent, UnsupportedEvent, WireLines } from './wire-line.ts';
+export type EncodedBlob = {
+    name: string;
+    mimeType: string;
+    data: string;
+};
+/** Turn input as sent over the wire (media is base64-encoded). */
+export type TheoremTurnInput = {
+    text?: string;
+    attachments?: EncodedBlob[];
+    voice?: EncodedBlob[];
+    history?: TurnHistoryMessage[];
+    historyTokens?: number;
+    inputTokens?: number;
+};
+/**
+ * State only the client holds, for hosts whose profile also lives in the browser
+ * (the playground). `createHttpTransport` never sends it: `createTheoremHandler`
+ * keeps permissions, paused calls, and tool snapshots in its own session.
+ */
+export type TheoremReplay = {
+    sessionPermissions?: string[];
+    name?: string;
+    input?: unknown;
+    turnInput?: TheoremTurnInput;
+    snapshot?: TurnToolSnapshot;
+    promoted?: string[];
+    model?: string;
+    effort?: string;
+    path?: string;
+};
+/** For a host that reads the playground's client-held state. */
+export declare const theoremReplaySchema: z.ZodType<TheoremReplay>;
+/**
+ * One text turn. The host resolves the profile; the client sends the conversation.
+ *
+ * A message sent while the reply waits on gates walks away from them: `abandon`
+ * names the waiting calls, and `input.history` ends on their step with those
+ * calls open. The host settles each one cancelled, streams those events first,
+ * and gives the model each call's answer before the message.
+ */
+export type TheoremTurnRequest = {
+    input: TheoremTurnInput;
+    previousInteractionId?: string;
+    model?: string;
+    effort?: string;
+    /** Client-generated id so mid-turn steers can find this turn's inbox. */
+    turnId?: string;
+    /** Call ids of the paused calls this message walks away from. */
+    abandon?: string[];
+    replay?: Pick<TheoremReplay, 'sessionPermissions'> & {
+        /** Each walked-away call as the client holds it, by call id, for a host without a session. */
+        abandon?: Record<string, TheoremReplay>;
+    };
+};
+/** A `/turn` body as `createTheoremHandler` reads it. */
+export declare const theoremTurnRequestSchema: z.ZodType<TheoremTurnRequest>;
+/** What the user answers a gate with; walking away rides on the next message (`TheoremTurnRequest.abandon`). */
+declare const INVOKE_DECISIONS: readonly ["approve", "deny"];
+/**
+ * The user's answer to a tool call the host paused on a gate. `approve` runs it
+ * (with `input` when the user edited it); `deny` refuses it. The host settles
+ * each one, so the model and the trace read what the user chose. The tool's
+ * registered permission decides how long an approval lasts, not the client.
+ */
+export type TheoremInvokeRequest = {
+    /** Call id of the paused tool call (`tool.callId` on its gate event). */
+    gateId: string;
+    decision: (typeof INVOKE_DECISIONS)[number];
+    /** The user's edit of the model's input; only with `approve`. */
+    input?: unknown;
+    /**
+     * The key or token the user typed at a bearer or API-key sign-in gate, only
+     * with `approve`. The server saves it for the session and never sends it
+     * back; an OAuth gate resumes with the gate id alone, once the host's
+     * callback saved the token.
+     */
+    secret?: string;
+    replay?: TheoremReplay;
+};
+/** An `/invoke` body as `createTheoremHandler` reads it. */
+export declare const theoremInvokeRequestSchema: z.ZodType<TheoremInvokeRequest>;
+/** Inject user messages into an in-flight turn. */
+export type TheoremSteerRequest = {
+    turnId: string;
+    /** The client's id for this steer; the turn's `stage` event names it in `injected` once it lands. */
+    id: string;
+    inject: TurnHistoryMessage[];
+};
+/** A `/steer` body as `createTheoremHandler` reads it. */
+export declare const theoremSteerRequestSchema: z.ZodType<TheoremSteerRequest>;
+/** A turn event, one of a kind this client does not know (`unsupported`), or one that failed its check (`malformed`). */
+export type ClientTurnEvent = TurnEvent | UnsupportedEvent | MalformedEvent;
+export type TurnEventSink = (event: ClientTurnEvent) => void;
+export interface TheoremTransport {
+    /** Client-safe interface for the host's profile (inputs, models, guardrail view). */
+    describe(signal?: AbortSignal): Promise<ProfileInterface>;
+    turn(request: TheoremTurnRequest, onEvent: TurnEventSink, signal?: AbortSignal): Promise<void>;
+    invoke(request: TheoremInvokeRequest, onEvent: TurnEventSink, signal?: AbortSignal): Promise<void>;
+    steer(request: TheoremSteerRequest): Promise<void>;
+    /** Trace records the host sends back, when it delivers them (the playground does). */
+    traces?: TraceFeed;
+}
+/**
+ * A failure the host reported: its kind, the host's wording when it sent one
+ * (the profile's lexicon, applied on the host), and raw detail when the host
+ * exposes it. `clientFailure` words it for the user.
+ */
+export declare class TheoremStreamError extends Error {
+    readonly kind: ErrorKind;
+    readonly publicMessage?: string;
+    readonly internalMessage?: string;
+    constructor(kind: ErrorKind, publicMessage?: string, internalMessage?: string);
+}
+export declare function isTheoremStreamError(err: unknown): err is TheoremStreamError;
+/** A host error reply's body (JSON reply or `{ type: 'error' }` stream line). */
+export type HostErrorBody = {
+    error?: string;
+    errorKind?: ErrorKind;
+    errorInternal?: string;
+};
+/** A host's error body, as the transport and the live client read it. */
+export declare const hostErrorBodySchema: z.ZodType<HostErrorBody>;
+/** A host's error body as a failure: its kind (else `fallbackKind`), wording, and detail. */
+export declare function hostError(body: HostErrorBody, fallbackKind: ErrorKind): TheoremStreamError;
+/**
+ * Read an NDJSON reply, checking each line against `lines`: a kind it doesn't
+ * list reaches `onLine` as `unsupported`, and a line that fails its check as
+ * `malformed`; the stream goes on. An `error` line ends it.
+ */
+export declare function readNdjsonStream<Line extends {
+    type: string;
+}>(response: Response, lines: WireLines<Line>, onLine: (line: Line | UnsupportedEvent | MalformedEvent) => void, signal?: AbortSignal): Promise<void>;
+export type HttpOptions = {
+    fetch?: typeof fetch;
+    /** Extra request headers (auth tokens, CSRF). A function is re-read per request. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Cookie policy. Default `same-origin`; use `include` when the handler is on another origin. */
+    credentials?: RequestCredentials;
+};
+/**
+ * POST JSON and stream NDJSON lines back, each checked against `lines`: turn
+ * events ({@link TURN_EVENT_SCHEMAS}), or a host's own schema beside them.
+ */
+export declare function postNdjson<Line extends {
+    type: string;
+}>(url: string, body: unknown, lines: WireLines<Line>, onLine: (line: Line | UnsupportedEvent | MalformedEvent) => void, options?: HttpOptions & {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** POST JSON; a non-OK reply throws its failure. The OK reply's body is not read. */
+export declare function postJson(url: string, body: unknown, options?: HttpOptions): Promise<void>;
+/** GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure. */
+export declare function fetchJson(url: string, init: {
+    body?: unknown;
+    signal?: AbortSignal;
+}, options?: HttpOptions): Promise<unknown>;
+export type HttpTransportOptions = HttpOptions & {
+    /** Base URL where `createTheoremHandler` is mounted. Default `/api/theorem`. */
+    endpoint?: string;
+};
+/** Transport for a host mounted with `createTheoremHandler`. */
+export declare function createHttpTransport(options?: HttpTransportOptions): TheoremTransport;

package/client/transport.js

@@ -0,0 +1,256 @@
+/**
+ * Transport contract between a Theorem chat UI and the host that runs turns.
+ *
+ * The browser never holds the profile: it asks the transport to `describe` the
+ * profile's client-safe interface, then streams turns / tool invokes through it.
+ * `createHttpTransport` speaks to `createTheoremHandler` (`@theoremjs/react/server`);
+ * hosts with their own wire format implement {@link TheoremTransport} directly.
+ *
+ * @module
+ */
+import { describeError, errorKindSchema, isAbortError, TheoremError, TURN_EVENT_SCHEMAS, throwIfAborted, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
+import { kindOfHttpStatus } from '@theoremjs/agents/guardrails';
+import { profileInterfaceSchema } from '@theoremjs/agents/interface';
+import { checkWire, parseWireJson, readWireLine, } from "./wire-line.js";
+const encodedBlob = z.object({ name: z.string(), mimeType: z.string(), data: z.string() });
+true;
+const theoremTurnInput = z.object({
+    text: z.string().optional(),
+    attachments: z.array(encodedBlob).optional(),
+    voice: z.array(encodedBlob).optional(),
+    history: z.array(turnHistoryMessageSchema).optional(),
+    historyTokens: z.number().optional(),
+    inputTokens: z.number().optional(),
+});
+true;
+const theoremReplay = z.object({
+    sessionPermissions: z.array(z.string()).optional(),
+    name: z.string().optional(),
+    input: z.unknown().optional(),
+    turnInput: theoremTurnInput.optional(),
+    snapshot: turnToolSnapshotSchema.optional(),
+    promoted: z.array(z.string()).optional(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+    path: z.string().optional(),
+});
+true;
+/** For a host that reads the playground's client-held state. */
+export const theoremReplaySchema = theoremReplay;
+/** An id the client made: trimmed, never blank. */
+const clientId = z.string().trim().min(1);
+const theoremTurnRequest = z.object({
+    input: theoremTurnInput,
+    previousInteractionId: z.string().optional(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+    turnId: clientId.optional(),
+    abandon: z.array(z.string().min(1)).min(1).optional(),
+    replay: theoremReplay
+        .pick({ sessionPermissions: true })
+        .extend({ abandon: z.record(z.string(), theoremReplay).optional() })
+        .optional(),
+});
+true;
+/** A `/turn` body as `createTheoremHandler` reads it. */
+export const theoremTurnRequestSchema = theoremTurnRequest;
+/** What the user answers a gate with; walking away rides on the next message (`TheoremTurnRequest.abandon`). */
+const INVOKE_DECISIONS = ['approve', 'deny'];
+const theoremInvokeRequest = z.object({
+    gateId: z.string().min(1),
+    decision: z.enum(INVOKE_DECISIONS),
+    input: z.unknown().optional(),
+    secret: z.string().optional(),
+    replay: theoremReplay.optional(),
+});
+true;
+/** An `/invoke` body as `createTheoremHandler` reads it. */
+export const theoremInvokeRequestSchema = theoremInvokeRequest;
+const theoremSteerRequest = z.object({
+    turnId: clientId,
+    id: clientId,
+    inject: z.array(turnHistoryMessageSchema).min(1),
+});
+true;
+/** A `/steer` body as `createTheoremHandler` reads it. */
+export const theoremSteerRequestSchema = theoremSteerRequest;
+/**
+ * A failure the host reported: its kind, the host's wording when it sent one
+ * (the profile's lexicon, applied on the host), and raw detail when the host
+ * exposes it. `clientFailure` words it for the user.
+ */
+export class TheoremStreamError extends Error {
+    kind;
+    publicMessage;
+    internalMessage;
+    constructor(kind, publicMessage, internalMessage) {
+        super(internalMessage ?? publicMessage ?? kind);
+        this.name = 'TheoremStreamError';
+        this.kind = kind;
+        if (publicMessage)
+            this.publicMessage = publicMessage;
+        if (internalMessage)
+            this.internalMessage = internalMessage;
+    }
+}
+export function isTheoremStreamError(err) {
+    return err instanceof TheoremStreamError;
+}
+/** The trimmed string, or undefined when absent or blank. */
+function textOf(value) {
+    return value?.trim() || undefined;
+}
+const hostErrorBody = z.object({
+    error: z.string().optional(),
+    errorKind: errorKindSchema.optional(),
+    errorInternal: z.string().optional(),
+});
+true;
+/** A host's error body, as the transport and the live client read it. */
+export const hostErrorBodySchema = hostErrorBody;
+/** A host's error body as a failure: its kind (else `fallbackKind`), wording, and detail. */
+export function hostError(body, fallbackKind) {
+    const publicMessage = textOf(body.error);
+    const internal = textOf(body.errorInternal);
+    return new TheoremStreamError(body.errorKind ?? fallbackKind, publicMessage, internal && internal !== publicMessage ? internal : undefined);
+}
+/** One NDJSON line checked against `lines`; an `error` line ends the stream as a {@link TheoremStreamError}. */
+function parseStreamLine(lines, text) {
+    const line = readWireLine(lines, text);
+    // An `error` line passed the error event's schema, whose fields include the body's.
+    if (line.type === 'error')
+        throw hostError(hostErrorBody.parse(line), 'internal');
+    return line;
+}
+function flushNdjsonChunk(buffer, lines, onLine) {
+    const chunks = buffer.split('\n');
+    const rest = chunks.pop() ?? '';
+    for (const chunk of chunks) {
+        if (!chunk.trim())
+            continue;
+        onLine(parseStreamLine(lines, chunk));
+    }
+    return rest;
+}
+/**
+ * Read an NDJSON reply, checking each line against `lines`: a kind it doesn't
+ * list reaches `onLine` as `unsupported`, and a line that fails its check as
+ * `malformed`; the stream goes on. An `error` line ends it.
+ */
+export async function readNdjsonStream(response, lines, onLine, signal) {
+    if (!response.body)
+        throw new TheoremError('bad_response', 'stream reply has no body'); // lexicon-exempt: internal diagnostic
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const onAbort = () => {
+        void reader.cancel();
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for (;;) {
+            throwIfAborted(signal);
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer = flushNdjsonChunk(buffer + decoder.decode(value, { stream: true }), lines, onLine);
+        }
+        const tail = buffer.trim();
+        if (tail)
+            onLine(parseStreamLine(lines, tail));
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+    }
+}
+async function resolveHeaders(options) {
+    const extra = typeof options.headers === 'function' ? await options.headers() : options.headers;
+    const headers = new Headers(extra);
+    headers.set('content-type', 'application/json');
+    return headers;
+}
+/**
+ * A non-OK reply as a failure: the host's kind and wording, else the status's
+ * kind. A body that is not JSON (a proxy's page) leaves the status to speak; a
+ * JSON body that fails the error body's schema is `bad_response`.
+ */
+async function failureFromResponse(response) {
+    const text = await response.text();
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return hostError({ errorInternal: `HTTP ${String(response.status)}` }, kindOfHttpStatus(response.status));
+    }
+    const body = hostErrorBody.safeParse(raw);
+    if (!body.success) {
+        // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+        return new TheoremError('bad_response', `HTTP ${String(response.status)} error body failed its wire check`);
+    }
+    return hostError({ ...body.data, errorInternal: body.data.errorInternal ?? `HTTP ${String(response.status)}` }, kindOfHttpStatus(response.status));
+}
+async function request(url, init, options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    try {
+        return await doFetch(url, {
+            ...init,
+            headers: await resolveHeaders(options),
+            credentials: options.credentials ?? 'same-origin',
+        });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        throw new TheoremError('network', describeError(err), { cause: err });
+    }
+}
+/**
+ * POST JSON and stream NDJSON lines back, each checked against `lines`: turn
+ * events ({@link TURN_EVENT_SCHEMAS}), or a host's own schema beside them.
+ */
+export async function postNdjson(url, body, lines, onLine, options = {}) {
+    const response = await request(url, { method: 'POST', body: JSON.stringify(body), signal: options.signal }, options);
+    if (!response.ok)
+        throw await failureFromResponse(response);
+    await readNdjsonStream(response, lines, onLine, options.signal);
+}
+/** POST JSON; a non-OK reply throws its failure. The OK reply's body is not read. */
+export async function postJson(url, body, options = {}) {
+    const response = await request(url, { method: 'POST', body: JSON.stringify(body) }, options);
+    if (!response.ok)
+        throw await failureFromResponse(response);
+}
+/** GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure. */
+export async function fetchJson(url, init, options = {}) {
+    const method = init.body === undefined ? { method: 'GET' } : { method: 'POST', body: JSON.stringify(init.body) };
+    const response = await request(url, { ...method, signal: init.signal }, options);
+    if (!response.ok)
+        throw await failureFromResponse(response);
+    return parseWireJson(await response.text());
+}
+/** Drops trailing '/'s by scanning back, not with a regex (a `/\/+$/` scan is quadratic on long runs of '/'). */
+function withoutTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === '/')
+        end -= 1;
+    return url.slice(0, end);
+}
+/** The host's `describe` reply. */
+const describedSchema = z.object({ interface: profileInterfaceSchema });
+/** Transport for a host mounted with `createTheoremHandler`. */
+export function createHttpTransport(options = {}) {
+    const base = withoutTrailingSlashes(options.endpoint ?? '/api/theorem');
+    return {
+        async describe(signal) {
+            const response = await request(base, { method: 'GET', signal }, options);
+            if (!response.ok)
+                throw await failureFromResponse(response);
+            // lexicon-exempt: internal diagnostic; the user reads error.bad_response
+            return checkWire(describedSchema, parseWireJson(await response.text()), 'the profile description').interface;
+        },
+        turn: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/turn`, body, TURN_EVENT_SCHEMAS, onEvent, { ...options, signal }),
+        invoke: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/invoke`, body, TURN_EVENT_SCHEMAS, onEvent, { ...options, signal }),
+        steer: (body) => postJson(`${base}/steer`, body, options),
+    };
+}

package/client/turn-client.d.ts

@@ -0,0 +1,35 @@
+import type { TurnEvent } from '@theoremjs/agents';
+import { type AttachmentValidationIssue, type ComposerProfileInterface, type GatedToolContext, type InterfaceTurnSession, type TranscriptBlock, type UserTurnDraft } from '@theoremjs/agents/interface';
+import type { TheoremInvokeRequest, TheoremTurnInput, TheoremTurnRequest } from './transport.ts';
+export declare function turnInputFromSession(session: InterfaceTurnSession, overrides?: TheoremTurnInput): TheoremTurnInput;
+/** A gated call as the client holds it, for a host without a session (the playground). */
+export type HeldCall = {
+    name: string;
+    /** The model's input to the call. */
+    input: unknown;
+    sessionPermissions?: string[];
+};
+/** A paused session, and the calls it waits on that a message walks away from. */
+export type WalkAway = {
+    paused: InterfaceTurnSession;
+    calls: readonly GatedToolContext[];
+};
+export declare function buildTurnRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, input: TheoremTurnInput, options?: {
+    turnId?: string;
+    walkAway?: WalkAway;
+}): TheoremTurnRequest;
+export declare function buildInvokeRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, args: HeldCall & {
+    gateId: string;
+    decision: TheoremInvokeRequest['decision'];
+    secret?: string;
+}): TheoremInvokeRequest;
+export declare function projectUserTurn(iface: ComposerProfileInterface, draft: UserTurnDraft): {
+    ok: true;
+    blocks: TranscriptBlock[];
+    draft: UserTurnDraft;
+} | {
+    ok: false;
+    issues: AttachmentValidationIssue[];
+};
+export declare function prepareComposerTurn(iface: ComposerProfileInterface, text: string, pendingFiles: readonly File[], pendingVoice?: readonly File[]): ReturnType<typeof projectUserTurn>;
+export declare function foldAssistantTurn(iface: ComposerProfileInterface, events: readonly TurnEvent[]): TranscriptBlock[];

package/client/turn-client.js

@@ -0,0 +1,93 @@
+import { foldTurnEvents, prepareUserTurn, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
+import { filesToPending } from "./encode-files.js";
+import { defaultModel } from "./generation-selection.js";
+export function turnInputFromSession(session, overrides = {}) {
+    return {
+        ...overrides,
+        history: session.history,
+        ...(session.inputTokens !== undefined ? { inputTokens: session.inputTokens } : {}),
+        ...(session.historyTokens !== undefined ? { historyTokens: session.historyTokens } : {}),
+    };
+}
+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,
+        sessionPermissions: call.sessionPermissions ?? session.sessionPermissions,
+        turnInput: turnInputFromSession(session),
+        ...(session.toolSnapshot ? { snapshot: session.toolSnapshot } : {}),
+        ...(session.promotedToolIds.length ? { promoted: [...session.promotedToolIds] } : {}),
+        ...generationFields(iface, session),
+    };
+}
+/**
+ * The paused calls a message walks away from: their ids, and each call as a
+ * host without a session replays it, from the session as it paused.
+ */
+function abandonFields(iface, walkAway) {
+    if (!walkAway.calls.length)
+        return undefined;
+    return {
+        abandon: walkAway.calls.map((call) => call.callId),
+        replays: Object.fromEntries(walkAway.calls.map((call) => [
+            call.callId,
+            gateReplay(iface, walkAway.paused, { name: call.name, input: call.arguments }),
+        ])),
+    };
+}
+export function buildTurnRequest(iface, session, input, options = {}) {
+    const walked = options.walkAway ? abandonFields(iface, options.walkAway) : undefined;
+    return {
+        previousInteractionId: session.previousInteractionId,
+        ...(options.turnId ? { turnId: options.turnId } : {}),
+        ...generationFields(iface, session),
+        input,
+        ...(walked ? { abandon: walked.abandon } : {}),
+        replay: {
+            sessionPermissions: session.sessionPermissions,
+            ...(walked ? { abandon: walked.replays } : {}),
+        },
+    };
+}
+export function buildInvokeRequest(iface, session, args) {
+    return {
+        gateId: args.gateId,
+        decision: args.decision,
+        ...(args.secret === undefined ? {} : { secret: args.secret }),
+        replay: gateReplay(iface, session, args),
+    };
+}
+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) {
+    // 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/voice-label.d.ts

@@ -0,0 +1,2 @@
+/** A voice note's audio format (`webm`, `wav`, `mp3`, `m4a`, `ogg`) from its MIME type; undefined when unknown. */
+export declare function voiceFormatFromMime(mime: string): string | undefined;

package/client/voice-label.js

@@ -0,0 +1,15 @@
+/** A voice note's audio format (`webm`, `wav`, `mp3`, `m4a`, `ogg`) from its MIME type; undefined when unknown. */
+export function voiceFormatFromMime(mime) {
+    const lower = mime.toLowerCase();
+    if (lower.includes('webm'))
+        return 'webm';
+    if (lower.includes('wav'))
+        return 'wav';
+    if (lower.includes('mpeg') || lower.includes('mp3'))
+        return 'mp3';
+    if (lower.includes('mp4') || lower.includes('m4a') || lower.includes('aac'))
+        return 'm4a';
+    if (lower.includes('ogg'))
+        return 'ogg';
+    return undefined;
+}

package/client/voice-recorder.d.ts

@@ -0,0 +1,27 @@
+/** Why recording failed; the user reads lexicon `voice.<code>`. */
+export type VoiceRecorderFailureCode = 'unsupported' | 'permission' | 'unavailable' | 'failed' | 'empty';
+/** Headless MediaRecorder session for turn-composer voice notes. */
+export declare class ComposerVoiceRecorder {
+    private readonly accept;
+    private readonly onLevel?;
+    private stream;
+    private recorder;
+    private chunks;
+    private audioContext;
+    private analyser;
+    private source;
+    private rafId;
+    private mime;
+    private recording;
+    constructor(accept: string[], onLevel?: ((level: number) => void) | undefined);
+    start(): Promise<void>;
+    stop(): Promise<File>;
+    cancel(): void;
+    dispose(): void;
+    private startMeter;
+    private stopMeter;
+    private disposeTracks;
+}
+export declare function isVoiceRecorderFailure(value: unknown): value is Error & {
+    readonly code: VoiceRecorderFailureCode;
+};