@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -1,11 +1,17 @@
 import { z } from 'zod';
-import { LEXICON_KEYS } from '../guardrails/lexicon.js';
-import { CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, KEY_SLOT_NAME, LIVE_ACTIVITY_HANDLINGS, LIVE_END_SENSITIVITIES, LIVE_START_SENSITIVITIES, PROTOCOLS, PROVIDERS, SPEECH_AUDIO_FORMATS, STREAM_MODES, THINKING_LEVELS, } from '../kernel/schema.js';
+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.enum(PROTOCOLS),
-    provider: z.enum(PROVIDERS),
+    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(),
@@ -13,8 +19,6 @@ const modelBinding = z.object({
     maxOutputTokens: z.number().optional(),
     temperature: z.number().optional(),
     builtInTools: z.array(z.string()).optional(),
-    key: z.string().regex(KEY_SLOT_NAME).optional(),
-    fallbackKey: z.string().regex(KEY_SLOT_NAME).optional(),
     compaction: z
         .object({
         maxTokens: z.number(),
@@ -25,10 +29,6 @@ const modelBinding = z.object({
         meter: z.enum(COMPACTION_METERS).optional(),
     })
         .optional(),
-    cache: z.object({ mode: z.enum(CACHE_MODES), ttl: z.enum(CACHE_TTLS).optional() }).optional(),
-    store: z.boolean().optional(),
-    persistViaInteractionId: z.boolean().optional(),
-    server: z.string().optional(),
 });
 const outputs = z.object({
     structured: z
@@ -39,35 +39,33 @@ const outputs = z.object({
     ])
         .optional(),
     streaming: z
-        .object({ mode: z.enum(STREAM_MODES).optional(), streamThoughts: z.boolean().optional() })
+        .object({
+        mode: z.enum(STREAM_MODES).optional(),
+        streamThoughts: z.boolean().optional(),
+    })
         .optional(),
 });
-const sensitiveGroups = z.object({
-    ids: z.boolean(),
-    financial: z.boolean(),
-    network: z.boolean(),
-    credentials: z.boolean(),
+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 urlCheck = z.union([
-    z.literal(false),
-    z.object({ hosts: z.array(z.string()), fromTools: 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(),
-    canary: z.boolean(),
-    sanitizeInput: z.boolean(),
-    redactSensitive: sensitiveGroups,
-    hasEgress: z.boolean(),
-    egressChecks: z
-        .object({
-        sensitive: sensitiveGroups,
-        boundary: z.boolean(),
-        injection: z.boolean(),
-        images: urlCheck,
-        links: urlCheck,
-    })
-        .nullable(),
+    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(),
@@ -80,7 +78,7 @@ const observability = z.object({
         guardrailDecisions: z.boolean(),
         guardrailMatchPreview: z.boolean(),
     }),
-    scrub: z.object({ sensitive: z.boolean(), injection: z.boolean(), canary: z.boolean() }),
+    scrub: z.object({ sensitive: scrubSwitch, injection: scrubSwitch, canary: scrubSwitch }),
     resource: traceAttributesSchema,
     retainForDays: z.number(),
     rotateAfterMiB: z.number(),
@@ -95,6 +93,7 @@ const inputs = z.object({
     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(),
@@ -102,16 +101,24 @@ const resumption = z.object({
     maxContinues: z.number().optional(),
 });
 const mediaTurnBehaviour = z.object({ resumption: resumption.optional() });
-const tools = z.object({ allow: z.array(z.string()), t2Loader: z.string().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(),
-    key: z.string().regex(KEY_SLOT_NAME).optional(),
-    fallbackKey: z.string().regex(KEY_SLOT_NAME).optional(),
-    lexicon: z.partialRecord(z.enum(LEXICON_KEYS), z.string()),
+    labels: z.partialRecord(z.enum(LABEL_KEYS), z.string()),
     guardrails: guardrails.optional(),
     observability: observability.optional(),
 };
@@ -136,7 +143,11 @@ const profileInterface = z.discriminatedUnion('type', [
         inputs,
         tools,
         turnBehaviour: z
-            .object({ resumption: resumption.optional(), allowSteering: z.boolean().optional() })
+            .object({
+            resumption: resumption.optional(),
+            allowSteering: z.boolean().optional(),
+            atStepLimit: z.enum(STEP_LIMIT_MODES).optional(),
+        })
             .optional(),
         canStop: z.literal(true),
         allowSteering: z.boolean(),
@@ -175,6 +186,8 @@ const profileInterface = z.discriminatedUnion('type', [
         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,
@@ -185,6 +198,7 @@ const profileInterface = z.discriminatedUnion('type', [
         ...common,
         type: z.literal('live'),
         identity,
+        inputs: inputs.pick({ slots: true, context: true }).optional(),
         live: z.object({
             ingress: z
                 .object({
@@ -214,7 +228,7 @@ const profileInterface = z.discriminatedUnion('type', [
                 .object({ input: z.boolean().optional(), output: z.boolean().optional() })
                 .optional(),
         }),
-        tools: z.object({ allow: z.array(z.string()) }),
+        tools: tools.pick({ allow: true, page: true }),
         turnBehaviour: z.object({ allowSteering: z.boolean().optional() }).optional(),
     }),
 ]);

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

@@ -1,20 +1,24 @@
 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.thoughtSignature`, for recording the call in history. */
-    thoughtSignature?: string;
+    /** 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;
@@ -23,10 +27,10 @@ export type AwaitingToolContext = {
     prompt: string;
     options?: string[];
 };
+/** The state a client keeps between turns: portable history, native checkpoint, and permissions. */
 export type InterfaceTurnSession = {
     history: TurnHistoryMessage[];
-    /** Google Interactions id for server-side continuity; cleared on branch. */
-    previousInteractionId?: string;
+    providerState?: import('../kernel/checkpoint.js').ProviderCheckpoint;
     sessionPermissions: string[];
     /** Last turn `tokens.input` for compaction meter `timing: 'before'`. */
     inputTokens?: number;
@@ -49,6 +53,7 @@ export type InterfaceTurnSession = {
     /** 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
@@ -57,8 +62,10 @@ declare function emptyInterfaceTurnSession(): InterfaceTurnSession;
 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 `previousInteractionId` so the next turn sends the rebuilt history, not a stale handle. */
+/** 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

@@ -1,8 +1,9 @@
-import { isAwaitingUserInput } from '../kernel/stages.js';
+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: [],
@@ -30,8 +31,9 @@ function gatedToolsFromEvents(events) {
             {
                 name: call.name,
                 callId: call.callId,
-                arguments: call.arguments,
-                ...(call.thoughtSignature ? { thoughtSignature: call.thoughtSignature } : {}),
+                ...(call.operationId ? { operationId: call.operationId } : {}),
+                arguments: gate.preparedArguments ?? call.arguments,
+                ...(call.reasoning ? { reasoning: call.reasoning } : {}),
                 gateKind: gate.kind,
                 permission: gate.permission,
                 summary: gate.summary,
@@ -52,6 +54,7 @@ function gatedToolsFromEvents(events) {
 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')
@@ -68,17 +71,21 @@ function awaitingFromEvents(events) {
         options: output.options,
     };
 }
+/** The session after the turn events are applied to it. */
 function applyTurnEventsToSession(session, events) {
-    let previousInteractionId = session.previousInteractionId;
+    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 === 'tokens' || event.type === 'done') && event.interactionId) {
-            previousInteractionId = event.interactionId;
-        }
-        // A call's own input size, not the turn's sum (`done.tokens`).
+        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;
         }
@@ -97,7 +104,7 @@ function applyTurnEventsToSession(session, events) {
     const gated = gatedToolFromEvents(events);
     return {
         ...session,
-        previousInteractionId,
+        providerState,
         inputTokens,
         historyTokens,
         gatedTool: gated,
@@ -106,7 +113,7 @@ function applyTurnEventsToSession(session, events) {
         promotedToolIds,
     };
 }
-/** Drops `previousInteractionId` so the next turn sends the rebuilt history, not a stale handle. */
+/** Drops native provider state so the next turn sends the rebuilt history, not a stale handle. */
 function branchInterfaceTurnSession(session, blocks) {
     return {
         ...emptyInterfaceTurnSession(),

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

@@ -5,9 +5,14 @@ import type { ToolCall } from './types.js';
  * 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 a call ran with: the user's edit, else the model's. */
+/** 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'> & {
@@ -15,6 +20,13 @@ type SettledToolCallEvent = TurnEventOf<'tool'> & {
         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 { applyToolEvent, settlesToolCall, toolCallRanWith, toolCallsOf };
+export { applyToolDraft, applyToolEvent, argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf, };

package/esm/src/interface/tool-calls.js

@@ -1,6 +1,8 @@
-// The model's raw call is the one owner of a call's arguments. The transcript, the interface
+// invariant: The model's raw call is the one owner of a call's arguments. The transcript, the interface
 // session and history read calls through this fold only.
 import { TheoremError } from '../guardrails/error.js';
+import { labelText } from '../guardrails/labels.js';
+import { partialJsonObject } from '../kernel/util/partial-json.js';
 /**
  * The raw call comes first for every call (`turnEventSchema`); a phase for a call never made is a
  * broken stream.
@@ -10,8 +12,9 @@ function applyToolEvent(call, tool) {
         return {
             name: tool.name,
             callId: tool.callId,
+            ...(tool.operationId ? { operationId: tool.operationId } : {}),
             arguments: tool.arguments,
-            ...(tool.thoughtSignature ? { thoughtSignature: tool.thoughtSignature } : {}),
+            ...(tool.reasoning ? { reasoning: tool.reasoning } : {}),
             ...(tool.stepId ? { stepId: tool.stepId } : {}),
             artifacts: [],
         };
@@ -19,10 +22,13 @@ function applyToolEvent(call, tool) {
     if (call === undefined) {
         throw new TheoremError('bad_response', `Tool event '${tool.phase}' for call '${tool.callId}' arrived before the call.`);
     }
+    if (call.callId !== tool.callId || call.name !== tool.name) {
+        throw new TheoremError('bad_response', labelText('error.bad_response'));
+    }
     switch (tool.phase) {
         case 'running': {
-            // A resumed call runs again: it is open until its next settle.
-            const { endedAt: _settled, ...open } = call;
+            // why: A resumed call runs again: it is open until its next settle.
+            const { endedAt: _settled, outputDraft: _drafted, ...open } = call;
             return {
                 ...open,
                 state: tool,
@@ -33,41 +39,89 @@ function applyToolEvent(call, tool) {
         }
         case 'complete':
             return {
-                ...call,
+                ...settled(call),
                 state: tool,
                 endedAt: tool.at,
                 ...(tool.activityPast ? { activityPast: tool.activityPast } : {}),
             };
         case 'error':
+            return {
+                ...settled(call),
+                state: tool,
+                endedAt: tool.at,
+                ...(tool.activityPast ? { activityPast: tool.activityPast } : {}),
+            };
         case 'cancel':
         case 'gate':
-            return { ...call, state: tool, endedAt: tool.at };
+            return { ...settled(call), state: tool, endedAt: tool.at };
+        case 'draft':
+            return { ...call, outputDraft: (call.outputDraft ?? '') + tool.text };
         case 'artifact':
             return { ...call, artifacts: [...call.artifacts, tool.artifact] };
+        case 'dispatch':
         case 'progress':
         case 'trace':
         case 'warning':
             return call;
     }
 }
+/** `call` without the preview of its output: it settled, and its output is whole. */
+function settled(call) {
+    const { outputDraft: _drafted, ...rest } = call;
+    return rest;
+}
+/**
+ * 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).
+ */
+function applyToolDraft(call, draft) {
+    return {
+        arguments: {},
+        artifacts: [],
+        ...call,
+        name: draft.name,
+        callId: draft.callId,
+        draft: (call?.draft ?? '') + draft.text,
+    };
+}
 /** Every call in `events`, in the order the model made them. */
 function toolCallsOf(events) {
     const calls = new Map();
     for (const event of events) {
+        if (event.type === 'tool_draft') {
+            calls.set(event.callId, applyToolDraft(calls.get(event.callId), event));
+            continue;
+        }
         if (event.type !== 'tool')
             continue;
         const { tool } = event;
-        calls.set(tool.callId, applyToolEvent(calls.get(tool.callId), tool));
+        const key = tool.operationId ?? tool.callId;
+        // why: The draft is keyed by the model's callId; the call that replaces it may carry an operation ID.
+        if (tool.phase === undefined && calls.get(tool.callId)?.draft !== undefined) {
+            calls.delete(tool.callId);
+        }
+        calls.set(key, applyToolEvent(calls.get(key), tool));
     }
     return [...calls.values()];
 }
-/** The arguments a call ran with: the user's edit, else the model's. */
+/** The arguments shown for approval, or the user's edit, or the model's original call. */
 function toolCallRanWith(call) {
-    return call.edited?.to ?? call.arguments;
+    return ((call.state?.phase === 'gate' ? call.state.gate.preparedArguments : undefined) ??
+        call.edited?.to ??
+        call.arguments);
 }
+/** True when the event is the complete or error event of the tool call with this id. */
 function settlesToolCall(event, callId) {
     if (event.type !== 'tool' || event.tool.callId !== callId)
         return false;
     return event.tool.phase === 'complete' || event.tool.phase === 'error';
 }
-export { applyToolEvent, settlesToolCall, toolCallRanWith, toolCallsOf };
+/**
+ * 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.
+ */
+function argumentsSoFar(call) {
+    return call.draft === undefined ? call.arguments : partialJsonObject(call.draft);
+}
+export { applyToolDraft, applyToolEvent, argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf, };

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

@@ -1,4 +1,6 @@
 import type { ToolId, TurnEvent, TurnToolSnapshot } from '../kernel/types.js';
+/** The ids of the tools a turn loaded, read from the loaded ids in its completed tool events. */
 declare function promotedToolIdsFromEvents(events: readonly TurnEvent[]): ToolId[];
+/** The tool snapshot on the last `done` event that carries one, which only a turn stopped on a tool or gate does. */
 declare function toolSnapshotFromEvents(events: readonly TurnEvent[]): TurnToolSnapshot | undefined;
 export { promotedToolIdsFromEvents, toolSnapshotFromEvents };

package/esm/src/interface/tool-invoke.js

@@ -1,5 +1,6 @@
 import { extractLoadedIds } from '../kernel/tools/resolve.js';
 import { findLast } from '../kernel/util/find-last.js';
+/** The ids of the tools a turn loaded, read from the loaded ids in its completed tool events. */
 function promotedToolIdsFromEvents(events) {
     const ids = new Set();
     for (const event of events) {
@@ -12,8 +13,9 @@ function promotedToolIdsFromEvents(events) {
     }
     return [...ids];
 }
+/** The tool snapshot on the last `done` event that carries one, which only a turn stopped on a tool or gate does. */
 function toolSnapshotFromEvents(events) {
-    // Only a `done` that stopped on `tool` or `gate` carries one (`DoneEvent`).
+    // why: Only a `done` that stopped on `tool` or `gate` carries one (`DoneEvent`).
     const done = findLast(events, (event) => event.type === 'done' && event.tools !== undefined);
     return done?.type === 'done' ? done.tools : undefined;
 }

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

@@ -1,9 +1,11 @@
+/** A media file a tool's output points to: its URL, MIME type and, when the output carried one, a smaller preview URL. */
 export type PromotedToolMedia = {
     url: string;
     mimeType: string;
     /** A smaller copy of the same file, when the output also carried one. */
     previewUrl?: string;
 };
+/** Reads an http(s) URL string as promoted media, with the MIME type taken from its file extension; returns undefined for an empty or invalid string, another scheme, or an extension it does not know. */
 export declare function promotedMediaFromUrlString(raw: string): PromotedToolMedia | undefined;
 /** One file at several sizes is promoted once: `url` its largest copy, `previewUrl` its smallest. */
 export declare function collectPromotedMediaFromToolOutput(output: unknown): PromotedToolMedia[];

package/esm/src/interface/tool-media.js

@@ -25,6 +25,7 @@ function mimeForPathname(pathname) {
     const ext = base.slice(dot + 1).toLowerCase();
     return EXT_MIME[ext];
 }
+/** Reads an http(s) URL string as promoted media, with the MIME type taken from its file extension; returns undefined for an empty or invalid string, another scheme, or an extension it does not know. */
 export function promotedMediaFromUrlString(raw) {
     const trimmed = raw.trim();
     if (trimmed.length === 0)
@@ -53,7 +54,7 @@ const MEDIAWIKI_THUMB = /^(.*)\/thumb(\/.+\/([^/]+))\/(\d+)px-\3(?:\.[a-z0-9]+)?
 function mediaAsset(url) {
     const parsed = new URL(url);
     const site = parsed.hostname.split('.').slice(-2).join('.');
-    // Tracking parameters never change the file; other query parameters may.
+    // why: Tracking parameters never change the file; other query parameters may.
     for (const name of [...parsed.searchParams.keys()]) {
         if (name.startsWith('utm_'))
             parsed.searchParams.delete(name);