@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/interface/pending.js

@@ -0,0 +1,152 @@
+// invariant: `steer` injects at `onStage` boundaries of the same run; `queue` sends after the run fully ends
+// (not on tool pause); `stash` never auto-sends. `send_now` is an action, not a pending kind.
+/** Display order: steers, then queues, then stashes. */
+export const COMPOSER_PENDING_KINDS = ['steer', 'queue', 'stash'];
+function createPendingId() {
+    return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `pending-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/** True when the draft holds text, an attachment, or voice. */
+function userDraftHasPayload(draft) {
+    return Boolean(draft.text?.trim() ||
+        (draft.attachments && draft.attachments.length > 0) ||
+        (draft.voice && draft.voice.length > 0));
+}
+/** Short preview for pending bars (text, else attachment hint). */
+function composerPendingPreview(message) {
+    const text = message.draft.text?.trim();
+    if (text)
+        return text;
+    const files = (message.draft.attachments?.length ?? 0) + (message.draft.voice?.length ?? 0);
+    if (files > 0)
+        return files === 1 ? '(attachment)' : `(${files} attachments)`;
+    return '';
+}
+/** Throws on an empty draft. */
+function createComposerPendingMessage(args) {
+    if (!userDraftHasPayload(args.draft)) {
+        throw new Error('Composer pending message requires a non-empty draft'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const now = args.now ?? Date.now();
+    return {
+        id: args.id ?? createPendingId(),
+        kind: args.kind,
+        draft: cloneUserTurnDraft(args.draft),
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/** A copy of the draft that shares nothing with the original. */
+function cloneUserTurnDraft(draft) {
+    return {
+        ...(draft.text !== undefined ? { text: draft.text } : {}),
+        ...(draft.attachments ? { attachments: draft.attachments.map((a) => ({ ...a })) } : {}),
+        ...(draft.voice ? { voice: draft.voice.map((a) => ({ ...a })) } : {}),
+    };
+}
+/** Steer, then queue, then stash; FIFO within a kind. */
+function orderComposerPendingMessages(messages) {
+    return [
+        ...messages.filter((m) => m.kind === 'steer'),
+        ...messages.filter((m) => m.kind === 'queue'),
+        ...messages.filter((m) => m.kind === 'stash'),
+    ];
+}
+/** When a run ends, undelivered steers become queues ahead of the existing ones. */
+function convertSteersToFrontQueued(messages, now = Date.now()) {
+    const steers = messages
+        .filter((m) => m.kind === 'steer')
+        .map((m) => ({
+        ...m,
+        kind: 'queue',
+        updatedAt: now,
+    }));
+    const queues = messages.filter((m) => m.kind === 'queue');
+    const stashes = messages.filter((m) => m.kind === 'stash');
+    return [...steers, ...queues, ...stashes];
+}
+/**
+ * Drops the steers a turn event reports as landed in the conversation. A steer
+ * it never names stays pending, so the run's end requeues it.
+ */
+function removeLandedSteers(messages, event) {
+    if (event.type !== 'stage' || !event.injected?.length)
+        return [...messages];
+    const landed = new Set(event.injected.map((steer) => steer.id));
+    return messages.filter((m) => !(m.kind === 'steer' && landed.has(m.id)));
+}
+/** The messages without the one with this id. */
+function removeComposerPendingMessage(messages, id) {
+    return messages.filter((m) => m.id !== id);
+}
+/** The messages with this id's draft replaced; throws when the new draft is empty. */
+function updateComposerPendingDraft(messages, id, draft, now = Date.now()) {
+    if (!userDraftHasPayload(draft)) {
+        throw new Error('Composer pending message requires a non-empty draft'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    return messages.map((m) => m.id === id
+        ? {
+            ...m,
+            draft: cloneUserTurnDraft(draft),
+            updatedAt: now,
+        }
+        : m);
+}
+/** The messages with this id moved one place up or down among those of its kind. */
+function moveComposerPendingWithinKind(messages, id, direction) {
+    const message = messages.find((m) => m.id === id);
+    if (!message)
+        return [...messages];
+    const sameKind = messages.filter((m) => m.kind === message.kind);
+    const currentIndex = sameKind.findIndex((m) => m.id === id);
+    if (currentIndex < 0)
+        return orderComposerPendingMessages(messages);
+    const nextIndex = direction === 'up' ? currentIndex - 1 : currentIndex + 1;
+    if (nextIndex < 0 || nextIndex >= sameKind.length) {
+        return orderComposerPendingMessages(messages);
+    }
+    const reordered = [...sameKind];
+    const [removed] = reordered.splice(currentIndex, 1);
+    if (!removed)
+        return orderComposerPendingMessages(messages);
+    reordered.splice(nextIndex, 0, removed);
+    const byKind = {
+        steer: message.kind === 'steer' ? reordered : messages.filter((m) => m.kind === 'steer'),
+        queue: message.kind === 'queue' ? reordered : messages.filter((m) => m.kind === 'queue'),
+        stash: message.kind === 'stash' ? reordered : messages.filter((m) => m.kind === 'stash'),
+    };
+    return [...byKind.steer, ...byKind.queue, ...byKind.stash];
+}
+/** One steer per safe boundary: call once per `onStage` inject site. */
+function consumeNextComposerSteer(messages) {
+    const message = messages.find((m) => m.kind === 'steer') ?? null;
+    if (!message)
+        return { message: null, remaining: [...messages] };
+    return {
+        message,
+        remaining: messages.filter((m) => m.id !== message.id),
+    };
+}
+/** Call only after the agent run has fully ended, not on a tool pause. */
+function consumeNextComposerQueue(messages) {
+    const message = messages.find((m) => m.kind === 'queue') ?? null;
+    if (!message)
+        return { message: null, remaining: [...messages] };
+    return {
+        message,
+        remaining: messages.filter((m) => m.id !== message.id),
+    };
+}
+/** The messages with this id changed to another kind. */
+function promoteComposerPendingKind(messages, id, kind, now = Date.now()) {
+    const updated = messages.map((m) => m.id === id
+        ? {
+            ...m,
+            kind,
+            updatedAt: now,
+        }
+        : m);
+    return orderComposerPendingMessages(updated);
+}
+export { cloneUserTurnDraft, composerPendingPreview, consumeNextComposerQueue, consumeNextComposerSteer, convertSteersToFrontQueued, createComposerPendingMessage, moveComposerPendingWithinKind, orderComposerPendingMessages, promoteComposerPendingKind, removeComposerPendingMessage, removeLandedSteers, updateComposerPendingDraft, userDraftHasPayload, };

package/esm/src/interface/profile-interface.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+import type { ProfileInterface } from './types.js';
+/** `ProfileInterface`, checked: unnamed fields are dropped, a malformed one fails. */
+export declare const profileInterfaceSchema: z.ZodType<ProfileInterface>;

package/esm/src/interface/profile-interface.js

@@ -0,0 +1,237 @@
+import { z } from 'zod';
+import { BOUNDARIES, recordOf } from '../guardrails/boundaries.js';
+import { DETECT_ACTIONS, DETECTORS } from '../guardrails/detectors.js';
+import { LABEL_KEYS } from '../guardrails/labels.js';
+import { BLOCKED_REPLY_ON_BLOCK } from '../guardrails/types.js';
+import { COMPACTION_METERS, COMPACTION_TIMINGS, CONTEXT_SENDERS, CONTINUE_STOP_KINDS, LIVE_ACTIVITY_HANDLINGS, LIVE_END_SENSITIVITIES, LIVE_START_SENSITIVITIES, SPEECH_AUDIO_FORMATS, STEP_LIMIT_MODES, STREAM_MODES, THINKING_LEVELS, } from '../kernel/schema.js';
+import { traceAttributesSchema } from '../observability/trace-schema.js';
+const modelBinding = z.object({
+    protocol: z.string(),
+    provider: z.string(),
+    apiId: z.string(),
+    options: z.record(z.string(), z.json()).optional(),
+    keySlot: z.string().optional(),
+    fallbackKeySlot: z.string().optional(),
+    efforts: z.record(z.string(), z.enum(THINKING_LEVELS)).optional(),
+    defaultEffort: z.string().optional(),
+    allowEffortSelect: z.boolean().optional(),
+    summaries: z.boolean().optional(),
+    maxOutputTokens: z.number().optional(),
+    temperature: z.number().optional(),
+    builtInTools: z.array(z.string()).optional(),
+    compaction: z
+        .object({
+        maxTokens: z.number(),
+        compactAt: z.number(),
+        previousExchanges: z.number(),
+        profile: z.string().optional(),
+        timing: z.enum(COMPACTION_TIMINGS),
+        meter: z.enum(COMPACTION_METERS).optional(),
+    })
+        .optional(),
+});
+const outputs = z.object({
+    structured: z
+        .union([
+        z.string(),
+        z.object({ by: z.string(), map: z.record(z.string(), z.string()), fallback: z.string() }),
+        z.null(),
+    ])
+        .optional(),
+    streaming: z
+        .object({
+        mode: z.enum(STREAM_MODES).optional(),
+        streamThoughts: z.boolean().optional(),
+    })
+        .optional(),
+});
+const actions = z.object(recordOf(BOUNDARIES, () => z.enum(DETECT_ACTIONS)));
+const detect = z.object(recordOf(DETECTORS, () => actions));
+const hostDetector = z.object({
+    id: z.string(),
+    label: z.string(),
+    actions,
+    names: z.array(z.string()),
+    find: z.boolean(),
+});
+const urlAllow = z.object({ hosts: z.array(z.string()), fromTools: z.boolean() });
+const guardrails = z.object({
+    quota: z.object({ perDay: z.number() }).optional(),
+    detect,
+    patterns: z
+        .partialRecord(z.enum(DETECTORS), z.object({ theorem: z.boolean(), names: z.array(z.string()) }))
+        .optional(),
+    host: z.array(hostDetector).optional(),
+    allow: z.object({ ungiven_images: urlAllow, ungiven_links: urlAllow }),
+    blockedReply: z.object({ onBlock: z.enum(BLOCKED_REPLY_ON_BLOCK), maxRetries: z.number() }),
+});
+const scrubSwitch = z.union([z.boolean(), z.object({ theorem: z.boolean(), host: z.boolean() })]);
+const observability = z.object({
+    record: z.boolean(),
+    writeTo: z.union([z.literal(false), z.string()]).optional(),
+    sampleRate: z.number(),
+    include: z.object({
+        upstreamLog: z.boolean(),
+        outboundWire: z.boolean(),
+        evidenceRaw: z.boolean(),
+        usage: z.boolean(),
+        guardrailDecisions: z.boolean(),
+        guardrailMatchPreview: z.boolean(),
+    }),
+    scrub: z.object({ sensitive: scrubSwitch, injection: scrubSwitch, canary: scrubSwitch }),
+    resource: traceAttributesSchema,
+    retainForDays: z.number(),
+    rotateAfterMiB: z.number(),
+    hasOnWriteError: z.boolean(),
+});
+const inputs = z.object({
+    text: z.boolean(),
+    attachments: z.object({ accept: z.array(z.string()), acceptAttr: z.string() }).nullable(),
+    voice: z.object({ accept: z.array(z.string()) }).nullable(),
+    maxFiles: z.number().optional(),
+    maxBytes: z.number().optional(),
+    maxTurnBytes: z.number().optional(),
+    limitsByMime: z.record(z.string(), z.number()).optional(),
+    slots: z.record(z.string(), z.array(z.string())).optional(),
+    context: z.object({ from: z.array(z.enum(CONTEXT_SENDERS)), maxChars: z.number() }).optional(),
+});
+const resumption = z.object({
+    allowContinue: z.array(z.enum(CONTINUE_STOP_KINDS)).optional(),
+    autoContinue: z.array(z.enum(CONTINUE_STOP_KINDS)).optional(),
+    maxContinues: z.number().optional(),
+});
+const mediaTurnBehaviour = z.object({ resumption: resumption.optional() });
+const tools = z.object({
+    allow: z.array(z.string()),
+    page: z.array(z.string()),
+    t2Loader: z.string().optional(),
+    parallel: z.boolean().optional(),
+});
+const common = {
+    providerContinuation: z
+        .object({
+        history: z.enum(['host', 'stateless', 'provider']).optional(),
+    })
+        .optional(),
+    id: z.string(),
+    models: z.record(z.string(), modelBinding),
+    defaultModel: z.string(),
+    allowModelSelect: z.boolean().optional(),
+    maxSteps: z.number().optional(),
+    labels: z.partialRecord(z.enum(LABEL_KEYS), z.string()),
+    guardrails: guardrails.optional(),
+    observability: observability.optional(),
+};
+const systemPrompt = z.union([
+    z.string(),
+    z
+        .array(z.union([z.string(), z.strictObject({ private: z.string().min(1) })]))
+        .min(1)
+        .readonly(),
+]);
+const identity = z.object({
+    handle: z.string(),
+    system: systemPrompt.optional(),
+    systemByRole: z.record(z.string(), systemPrompt).optional(),
+});
+const profileInterface = z.discriminatedUnion('type', [
+    z.object({
+        ...common,
+        type: z.literal('text'),
+        identity,
+        outputs: outputs.optional(),
+        inputs,
+        tools,
+        turnBehaviour: z
+            .object({
+            resumption: resumption.optional(),
+            allowSteering: z.boolean().optional(),
+            atStepLimit: z.enum(STEP_LIMIT_MODES).optional(),
+        })
+            .optional(),
+        canStop: z.literal(true),
+        allowSteering: z.boolean(),
+    }),
+    z.object({
+        ...common,
+        type: z.literal('image'),
+        identity,
+        outputs: outputs.optional(),
+        image: z.object({
+            aspectRatio: z.string().optional(),
+            resolution: z.string().optional(),
+            mimeType: z.string().optional(),
+            quality: z.string().optional(),
+            background: z.string().optional(),
+            n: z.number().int().min(1).optional(),
+            seed: z.number().int().optional(),
+            outputCompression: z.number().int().min(0).max(100).optional(),
+            references: z
+                .array(z.union([
+                z.object({ mimeType: z.string(), data: z.string(), name: z.string().optional() }),
+                z.object({ mimeType: z.string(), uri: z.string(), name: z.string().optional() }),
+            ]))
+                .optional(),
+            includeText: z.boolean().optional(),
+        }),
+        inputs,
+        tools,
+        turnBehaviour: mediaTurnBehaviour.optional(),
+        canStop: z.literal(true),
+    }),
+    z.object({
+        ...common,
+        type: z.literal('speech'),
+        identity: z.object({ handle: z.string() }),
+        outputs: outputs.optional(),
+        speech: z.object({
+            voice: z.string().optional(),
+            style: z.string().optional(),
+            speed: z.number().optional(),
+            format: z.enum(SPEECH_AUDIO_FORMATS).optional(),
+        }),
+        inputs,
+        turnBehaviour: mediaTurnBehaviour.optional(),
+        canStop: z.literal(true),
+    }),
+    z.object({
+        ...common,
+        type: z.literal('live'),
+        identity,
+        inputs: inputs.pick({ slots: true, context: true }).optional(),
+        live: z.object({
+            ingress: z
+                .object({
+                audio: z.boolean().optional(),
+                video: z.boolean().optional(),
+                text: z.boolean().optional(),
+            })
+                .optional(),
+            voice: z.string().optional(),
+            vad: z
+                .object({
+                activityHandling: z.enum(LIVE_ACTIVITY_HANDLINGS).optional(),
+                startSensitivity: z.enum(LIVE_START_SENSITIVITIES).optional(),
+                endSensitivity: z.enum(LIVE_END_SENSITIVITIES).optional(),
+                prefixPaddingMs: z.number().optional(),
+                silenceDurationMs: z.number().optional(),
+            })
+                .optional(),
+            sessionResumption: z.boolean().optional(),
+            contextCompression: z
+                .object({
+                triggerTokens: z.number().optional(),
+                slidingWindow: z.object({ targetTokens: z.number().optional() }),
+            })
+                .optional(),
+            transcription: z
+                .object({ input: z.boolean().optional(), output: z.boolean().optional() })
+                .optional(),
+        }),
+        tools: tools.pick({ allow: true, page: true }),
+        turnBehaviour: z.object({ allowSteering: z.boolean().optional() }).optional(),
+    }),
+]);
+true;
+/** `ProfileInterface`, checked: unnamed fields are dropped, a malformed one fails. */
+export const profileInterfaceSchema = profileInterface;

package/esm/src/interface/session.d.ts

@@ -0,0 +1,71 @@
+import type { ToolGateAuth } from '../kernel/tools/gate-answer.js';
+import type { ToolGate, TurnToolSnapshot } from '../kernel/tools/types.js';
+import { type ReasoningPart } from '../kernel/turn-events.js';
+import type { ModelId, ToolId, TurnEvent, TurnHistoryMessage } from '../kernel/types.js';
+import type { TranscriptBlock, UserTurnDraft } from './types.js';
+export type { ToolGateAuth };
+/** A tool call held at a gate: the tool, its call id, and arguments. */
+export type GatedToolContext = {
+    operationId?: string;
+    name: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+    /** The call's `ToolCallRequest.reasoning`, for recording the call in history. */
+    reasoning?: ReasoningPart[];
+    gateKind: ToolGate['kind'];
+    permission?: ToolGate['permission'];
+    summary?: string;
+    /** Set on a sign-in gate. */
+    auth?: ToolGateAuth;
+};
+/** A tool call that paused the turn to ask the user: the tool, its call id, and arguments. */
+export type AwaitingToolContext = {
+    name: string;
+    callId: string;
+    arguments: Record<string, unknown>;
+    kind: string;
+    prompt: string;
+    options?: string[];
+};
+/** The state a client keeps between turns: portable history, native checkpoint, and permissions. */
+export type InterfaceTurnSession = {
+    history: TurnHistoryMessage[];
+    providerState?: import('../kernel/checkpoint.js').ProviderCheckpoint;
+    sessionPermissions: string[];
+    /** Last turn `tokens.input` for compaction meter `timing: 'before'`. */
+    inputTokens?: number;
+    /** Host override for compaction meter `history`. */
+    historyTokens?: number;
+    /** Active pre_tool gate awaiting host resume. */
+    gatedTool: GatedToolContext | null;
+    /** Completed ask_user (or similar) awaiting host UI — turn may already be done. */
+    awaitingTool: AwaitingToolContext | null;
+    /** Kernel events for the assistant segment still in flight (gate / resume / continue). */
+    assistantEvents: TurnEvent[];
+    /** User draft for the turn that produced `assistantEvents`. */
+    pendingUserDraft: UserTurnDraft | null;
+    /** Snapshot from the last gate `done` event — pass to `invokeTool({ snapshot })`. */
+    toolSnapshot?: TurnToolSnapshot;
+    /** T2 tool ids promoted during the current assistant segment (loader `loaded` outputs). */
+    promotedToolIds: ToolId[];
+    /** User-selected model id when `allowModelSelect` is enabled on the profile. */
+    selectedModel?: ModelId;
+    /** Selected effort alias when the active model has `allowEffortSelect`. */
+    selectedEffort?: string;
+};
+/** A session with no history and no permissions. */
+declare function emptyInterfaceTurnSession(): InterfaceTurnSession;
+/**
+ * Every call still waiting on its gate, in the order the model made them. One
+ * step can leave several: a gate holds only its own call.
+ */
+declare function gatedToolsFromEvents(events: readonly TurnEvent[]): GatedToolContext[];
+/** The gate the user answers next: the first call still waiting. */
+declare function gatedToolFromEvents(events: readonly TurnEvent[]): GatedToolContext | null;
+/** The tool call a turn paused on to ask the user, or `null`. */
+declare function awaitingFromEvents(events: readonly TurnEvent[]): AwaitingToolContext | null;
+/** The session after the turn events are applied to it. */
+declare function applyTurnEventsToSession(session: InterfaceTurnSession, events: readonly TurnEvent[]): InterfaceTurnSession;
+/** Drops native provider state so the next turn sends the rebuilt history, not a stale handle. */
+declare function branchInterfaceTurnSession(session: InterfaceTurnSession, blocks: readonly TranscriptBlock[]): InterfaceTurnSession;
+export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, };

package/esm/src/interface/session.js

@@ -0,0 +1,128 @@
+import { isAwaitingUserInput } from '../kernel/turn-events.js';
+import { findLast } from '../kernel/util/find-last.js';
+import { historyFromTranscriptBlocks } from './history.js';
+import { toolCallsOf } from './tool-calls.js';
+import { promotedToolIdsFromEvents, toolSnapshotFromEvents } from './tool-invoke.js';
+/** A session with no history and no permissions. */
+function emptyInterfaceTurnSession() {
+    return {
+        history: [],
+        sessionPermissions: [],
+        gatedTool: null,
+        awaitingTool: null,
+        assistantEvents: [],
+        pendingUserDraft: null,
+        promotedToolIds: [],
+    };
+}
+/**
+ * Every call still waiting on its gate, in the order the model made them. One
+ * step can leave several: a gate holds only its own call.
+ */
+function gatedToolsFromEvents(events) {
+    const paused = events.some((event) => event.type === 'done' && (event.stop.kind === 'gate' || event.stop.kind === 'tool'));
+    if (!paused)
+        return [];
+    return toolCallsOf(events).flatMap((call) => {
+        if (call.state?.phase !== 'gate')
+            return [];
+        const { gate } = call.state;
+        return [
+            {
+                name: call.name,
+                callId: call.callId,
+                ...(call.operationId ? { operationId: call.operationId } : {}),
+                arguments: gate.preparedArguments ?? call.arguments,
+                ...(call.reasoning ? { reasoning: call.reasoning } : {}),
+                gateKind: gate.kind,
+                permission: gate.permission,
+                summary: gate.summary,
+                ...(gate.kind === 'auth'
+                    ? {
+                        auth: {
+                            slot: gate.authChallenge.slot,
+                            authType: gate.authChallenge.authType,
+                            service: gate.authChallenge.service,
+                        },
+                    }
+                    : {}),
+            },
+        ];
+    });
+}
+/** The gate the user answers next: the first call still waiting. */
+function gatedToolFromEvents(events) {
+    return gatedToolsFromEvents(events)[0] ?? null;
+}
+/** The tool call a turn paused on to ask the user, or `null`. */
+function awaitingFromEvents(events) {
+    const call = findLast(toolCallsOf(events), (c) => c.state?.phase === 'complete');
+    if (call?.state?.phase !== 'complete')
+        return null;
+    const { output } = call.state;
+    if (!isAwaitingUserInput(output))
+        return null;
+    return {
+        name: call.name,
+        callId: call.callId,
+        arguments: call.arguments,
+        kind: output.kind,
+        prompt: output.prompt,
+        options: output.options,
+    };
+}
+/** The session after the turn events are applied to it. */
+function applyTurnEventsToSession(session, events) {
+    let providerState = session.providerState;
+    let inputTokens = session.inputTokens;
+    let historyTokens = session.historyTokens;
+    let toolSnapshot = session.toolSnapshot;
+    let promotedToolIds = session.promotedToolIds;
+    for (const event of events) {
+        if (event.type === 'provider_checkpoint')
+            providerState = event.providerState;
+        if (event.type === 'done' && event.providerState)
+            providerState = event.providerState;
+        if (event.type === 'provider_warning')
+            providerState = undefined;
+        // why: A call's own input size, not the turn's sum (`done.tokens`).
+        if (event.type === 'tokens' && event.tokens.input) {
+            inputTokens = event.tokens.input;
+        }
+        if (event.type === 'done' && event.compaction?.tokens !== undefined) {
+            historyTokens = event.compaction.tokens;
+        }
+    }
+    const snapshotFromDone = toolSnapshotFromEvents(events);
+    if (snapshotFromDone) {
+        toolSnapshot = snapshotFromDone;
+    }
+    const newPromoted = promotedToolIdsFromEvents(events);
+    if (newPromoted.length > 0) {
+        promotedToolIds = [...new Set([...promotedToolIds, ...newPromoted])];
+    }
+    const gated = gatedToolFromEvents(events);
+    return {
+        ...session,
+        providerState,
+        inputTokens,
+        historyTokens,
+        gatedTool: gated,
+        awaitingTool: awaitingFromEvents(events),
+        toolSnapshot,
+        promotedToolIds,
+    };
+}
+/** Drops native provider state so the next turn sends the rebuilt history, not a stale handle. */
+function branchInterfaceTurnSession(session, blocks) {
+    return {
+        ...emptyInterfaceTurnSession(),
+        history: historyFromTranscriptBlocks(blocks),
+        sessionPermissions: [...session.sessionPermissions],
+        inputTokens: session.inputTokens,
+        historyTokens: session.historyTokens,
+        selectedModel: session.selectedModel,
+        selectedEffort: session.selectedEffort,
+    };
+}
+export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSession, emptyInterfaceTurnSession, gatedToolFromEvents, gatedToolsFromEvents, };

package/esm/src/interface/stop.d.ts

@@ -0,0 +1,13 @@
+import { type LabelOverrides } from '../guardrails/labels.js';
+import type { TurnStop } from '../kernel/types.js';
+import type { TranscriptBlock } from './types.js';
+/** The stops that end a reply short of a whole answer. Each is worded by its `stop.<kind>` label. */
+export declare const WORDED_STOP_KINDS: readonly ["cancelled", "interrupted", "length", "filtered", "provider_error", "stream_incomplete", "step_limit"];
+/** One of {@linkcode WORDED_STOP_KINDS}. */
+export type WordedStopKind = (typeof WORDED_STOP_KINDS)[number];
+/**
+ * Why a turn ended short, in the person's words: its `stop.<kind>` label, the profile's own when it
+ * sets one. `undefined` when the turn ended whole, or when an error in `blocks` (the turn's
+ * transcript blocks) already says why.
+ */
+export declare function stopText(stop: TurnStop | undefined, blocks: readonly TranscriptBlock[], labels?: LabelOverrides): string | undefined;

package/esm/src/interface/stop.js

@@ -0,0 +1,28 @@
+import { labelText } from '../guardrails/labels.js';
+/** The stops that end a reply short of a whole answer. Each is worded by its `stop.<kind>` label. */
+export const WORDED_STOP_KINDS = [
+    'cancelled',
+    'interrupted',
+    'length',
+    'filtered',
+    'provider_error',
+    'stream_incomplete',
+    'step_limit',
+];
+const WORDED = new Set(WORDED_STOP_KINDS);
+function isWorded(kind) {
+    return WORDED.has(kind);
+}
+/**
+ * Why a turn ended short, in the person's words: its `stop.<kind>` label, the profile's own when it
+ * sets one. `undefined` when the turn ended whole, or when an error in `blocks` (the turn's
+ * transcript blocks) already says why.
+ */
+export function stopText(stop, blocks, labels) {
+    if (!stop || !isWorded(stop.kind))
+        return undefined;
+    if (blocks.some((block) => block.kind === 'error'))
+        return undefined;
+    const key = `stop.${stop.kind}`;
+    return labelText(key, {}, labels);
+}

package/esm/src/interface/tool-calls.d.ts

@@ -0,0 +1,32 @@
+import type { ToolCallEvent, TurnEvent, TurnEventOf } from '../kernel/types.js';
+import type { ToolCall } from './types.js';
+/**
+ * The raw call comes first for every call (`turnEventSchema`); a phase for a call never made is a
+ * broken stream.
+ */
+declare function applyToolEvent(call: ToolCall | undefined, tool: ToolCallEvent): ToolCall;
+/**
+ * A call the model is still writing, with the next piece of its draft added. The call that arrives
+ * whole replaces it (`applyToolEvent` builds the call from the request alone).
+ */
+declare function applyToolDraft(call: ToolCall | undefined, draft: TurnEventOf<'tool_draft'>): ToolCall;
+/** Every call in `events`, in the order the model made them. */
+declare function toolCallsOf(events: readonly TurnEvent[]): ToolCall[];
+/** The arguments shown for approval, or the user's edit, or the model's original call. */
+declare function toolCallRanWith(call: ToolCall): Record<string, unknown>;
+/** A tool event that settles its call: the call completed or failed. */
+type SettledToolCallEvent = TurnEventOf<'tool'> & {
+    tool: Extract<ToolCallEvent, {
+        phase: 'complete' | 'error';
+    }>;
+};
+/** True when the event is the complete or error event of the tool call with this id. */
+declare function settlesToolCall(event: TurnEvent, callId: string): event is SettledToolCallEvent;
+/**
+ * A call's arguments as far as the model has written them: the whole arguments once the call has
+ * arrived, else what `partialJsonObject` reads of its draft. For a preview: a field still being
+ * written is not its final value.
+ */
+declare function argumentsSoFar(call: ToolCall): Record<string, unknown>;
+export type { SettledToolCallEvent };
+export { applyToolDraft, applyToolEvent, argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf, };