@tangleai/agents 0.21.1 → 0.24.1

package/src/agent.js

@@ -1,4 +1,3 @@
-//@ts-check
 /**
  * The agent loop: a bounded, deterministic tool-call round-trip over a
  * chat client and a toolbox. The model proposes tool calls; the loop
@@ -27,35 +26,13 @@
  * conversation, so a resumed session composes today's goal rather than
  * accumulating yesterday's.
  */
-
 import { goalPrompt } from '@tangleai/context/retention';
 import { AiError } from '@tangleai/models/errors';
-import { createToolbox } from './toolbox.js';
+import { createToolbox } from "./toolbox.js";
 import { slotAddressesIn, RECALL_TOOL_NAME, createRecallTool, roundSlotName, indexSlotName, slotAddress, slotRef } from '@tangleai/context/recall';
 import { environmentTools } from '@tangleai/context/environment';
 import { excerpt, truncate, sizeOf } from '@jarenjs/core/chunk';
-
 /**
- * @typedef {Object} AgentHooks
- * @property {(text: string) => void} [onDelta] - streamed reply text
- * @property {(text: string) => void} [onReasoning] - streamed thinking
- * @property {(call: { name: string, arguments: string }) => void} [onToolCall]
- * @property {(step: { name: string, result: any }) => void} [onToolResult]
- * @property {AbortSignal} [signal]
- */
-
-/**
- * @param {{ client: { complete: (request: any) => Promise<any> },
- *   toolbox?: { toFunctionTools: () => any[], execute: (name: string, args: any) => any } | null,
- *   system?: string, maxToolRounds?: number, maxToolResultChars?: number,
- *   historyBudget?: number, ledger?: any,
- *   budget?: { turns?: number, tokens?: number, ms?: number,
- *     spent?: { turns?: number, tokens?: number, ms?: number } },
- *   retrieval?: { memories?: { tags?: string[], where?: any, limit?: number },
- *     skills?: { tags?: string[], where?: any, limit?: number } },
- *   now?: () => number,
- *   environment?: any, transcript?: { slot?: string, window?: number },
- *   compaction?: (droppedRounds: any[][], addresses?: any[]) => string }} options
  *   - `historyBudget` caps the request history in CHARACTERS (tokens
  *   are provider-private; characters are deterministic). When a
  *   request would exceed it, the middle of the conversation is
@@ -101,325 +78,295 @@ import { excerpt, truncate, sizeOf } from '@jarenjs/core/chunk';
  *   no budget to exceed when the history is addressed instead of resent.
  *   Both together is legal and redundant; neither changes the other's
  *   behaviour.
- * @returns {{ send: (history: any[], hooks?: AgentHooks) => Promise<{
- *   message: any, messages: any[], steps: any[], stopReason: string }>,
- *   resume: (history?: any[], hooks?: AgentHooks) => Promise<{
- *   message: any, messages: any[], steps: any[], stopReason: string }>,
- *   spend: () => { turns: number, tokens: number, ms: number } }}
  */
 export function createAgent(options) {
-  const client = options.client;
-  const toolbox = options.toolbox ?? null;
-  const system = options.system ?? '';
-  const maxToolRounds = options.maxToolRounds ?? 5;
-  const maxToolResultChars = options.maxToolResultChars ?? 8000;
-  const historyBudget = options.historyBudget;
-  const ledger = options.ledger ?? null;
-  const budget = options.budget ?? null;
-  const retrieval = options.retrieval ?? null;
-  const clock = options.now ?? (() => Date.now());
-  const environment = options.environment ?? null;
-  // the transcript-as-slot path is opt-in even with an environment
-  // present: an environment is a corpus to work on, and deciding that
-  // the CONVERSATION is one of its slots is a separate choice
-  const transcript = environment === null || options.transcript === undefined
-    ? null
-    : {
-      slot: options.transcript.slot ?? 'transcript',
-      window: Math.max(1, options.transcript.window ?? TRANSCRIPT_WINDOW),
-    };
-  // kept separately from the effective writer: the ledger path treats a
-  // HOST writer differently from the built-in one (see `compactToLedger`)
-  const hostCompaction = options.compaction ?? null;
-  const compaction = hostCompaction ?? synopsize;
-
-  if (ledger !== null && typeof ledger.putSlot !== 'function') {
-    throw new AiError('AI0001',
-      'ledger: expected an object with putSlot/getSlot/readSlot (createLedger())');
-  }
-  // one recall tool per agent, and only with a ledger — a toolbox is
-  // built here rather than in the loop so its schema compiles once
-  const recallBox = ledger === null ? null : recallToolbox(ledger);
-  // the environment's operations, as tools, compiled once for the same
-  // reason. The model reaches the corpus through exactly the calls a
-  // harness makes — one implementation, in `environment.js`.
-  const envBox = environment === null ? null : toolboxOf(environmentTools(environment));
-
-  // what this agent has spent, across every `send` it has served. The
-  // counters live on the agent and not on a call, because a budget that
-  // reset each turn would bound nothing a long-horizon run cares about.
-  const spent = {
-    turns: budget?.spent?.turns ?? 0,
-    tokens: budget?.spent?.tokens ?? 0,
-    ms: budget?.spent?.ms ?? 0,
-  };
-  /** Wall-clock start of the first model call, or null before it. */
-  let startedAt = null;
-  const elapsed = () => spent.ms + (startedAt === null ? 0 : clock() - startedAt);
-
-  /** What this agent has spent so far — the seed for a resumed budget. */
-  const spend = () => ({ turns: spent.turns, tokens: spent.tokens, ms: elapsed() });
-
-  /**
-   * The budget dimension that is spent, or null. Checked BEFORE every
-   * model call, so an exhausted budget refuses rather than overruns —
-   * `maxToolRounds`'s posture, applied to the three quantities a run is
-   * actually bounded by.
-   * @returns {{ reason: string, content: string } | null}
-   */
-  function budgetStop() {
-    if (budget === null) return null;
-    const spentNow = spend();
-    for (const dimension of BUDGET_DIMENSIONS) {
-      const limit = budget[dimension];
-      if (typeof limit === 'number' && spentNow[dimension] >= limit) {
-        return {
-          reason: `budget-${dimension}`,
-          content: budgetMessage(dimension, budget, spentNow),
+    const client = options.client;
+    const toolbox = options.toolbox ?? null;
+    const system = options.system ?? '';
+    const maxToolRounds = options.maxToolRounds ?? 5;
+    const maxToolResultChars = options.maxToolResultChars ?? 8000;
+    const historyBudget = options.historyBudget;
+    const ledger = options.ledger ?? null;
+    const budget = options.budget ?? null;
+    const retrieval = options.retrieval ?? null;
+    const clock = options.now ?? (() => Date.now());
+    const environment = options.environment ?? null;
+    // the transcript-as-slot path is opt-in even with an environment
+    // present: an environment is a corpus to work on, and deciding that
+    // the CONVERSATION is one of its slots is a separate choice
+    const transcript = environment === null || options.transcript === undefined
+        ? null
+        : {
+            slot: options.transcript.slot ?? 'transcript',
+            window: Math.max(1, options.transcript.window ?? TRANSCRIPT_WINDOW),
         };
-      }
+    // kept separately from the effective writer: the ledger path treats a
+    // HOST writer differently from the built-in one (see `compactToLedger`)
+    const hostCompaction = options.compaction ?? null;
+    const compaction = hostCompaction ?? synopsize;
+    if (ledger !== null && typeof ledger.putSlot !== 'function') {
+        throw new AiError('AI0001', 'ledger: expected an object with putSlot/getSlot/readSlot (createLedger())');
     }
-    return null;
-  }
-
-  /**
-   * The system prompt for this turn: the immutable base, then the active
-   * goal and its progress, then whatever `retrieval` asks for. Read once
-   * per `send` rather than once per round — a goal does not change
-   * mid-turn, and re-reading it per round would put a storage round-trip
-   * in the tool loop for nothing.
-   *
-   * Returns null when there is nothing to compose, and the caller then
-   * sends the history untouched, by the same reference: an agent with no
-   * ledger, or a ledger with no goal and no retrieval, must be
-   * byte-identical to one built before any of this existed.
-   * @param {string} base
-   * @returns {Promise<string | null>}
-   */
-  async function composeSystem(base) {
-    if (ledger === null) return null;
-    /** @type {string[]} */
-    const sections = [];
-    if (typeof ledger.getGoal === 'function') {
-      const goal = await ledger.getGoal();
-      if (goal !== null && goal !== undefined && goal.status === 'active') {
-        if (typeof ledger.composeGoal === 'function') {
-          const composed = await ledger.composeGoal();
-          if (composed.error) throw new AiError('AI0001', composed.error);
-          sections.push(composed.text);
+    // one recall tool per agent, and only with a ledger — a toolbox is
+    // built here rather than in the loop so its schema compiles once
+    const recallBox = ledger === null ? null : recallToolbox(ledger);
+    // the environment's operations, as tools, compiled once for the same
+    // reason. The model reaches the corpus through exactly the calls a
+    // harness makes — one implementation, in `environment.ts`.
+    const envBox = environment === null ? null : toolboxOf(environmentTools(environment));
+    // what this agent has spent, across every `send` it has served. The
+    // counters live on the agent and not on a call, because a budget that
+    // reset each turn would bound nothing a long-horizon run cares about.
+    const spent = {
+        turns: budget?.spent?.turns ?? 0,
+        tokens: budget?.spent?.tokens ?? 0,
+        ms: budget?.spent?.ms ?? 0,
+    };
+    /** Wall-clock start of the first model call, or null before it. */
+    let startedAt = null;
+    const elapsed = () => spent.ms + (startedAt === null ? 0 : clock() - startedAt);
+    /** What this agent has spent so far — the seed for a resumed budget. */
+    const spend = () => ({ turns: spent.turns, tokens: spent.tokens, ms: elapsed() });
+    /**
+     * The budget dimension that is spent, or null. Checked BEFORE every
+     * model call, so an exhausted budget refuses rather than overruns —
+     * `maxToolRounds`'s posture, applied to the three quantities a run is
+     * actually bounded by.
+     */
+    function budgetStop() {
+        if (budget === null)
+            return null;
+        const spentNow = spend();
+        for (const dimension of BUDGET_DIMENSIONS) {
+            const limit = budget[dimension];
+            if (typeof limit === 'number' && spentNow[dimension] >= limit) {
+                return {
+                    reason: `budget-${dimension}`,
+                    content: budgetMessage(dimension, budget, spentNow),
+                };
+            }
         }
-        else sections.push(goalPrompt(goal));
-      }
+        return null;
     }
-    if (retrieval !== null) {
-      if (retrieval.memories !== undefined && typeof ledger.recall === 'function') {
-        sections.push(...listSection('What you have learned so far',
-          await retrieved(ledger.recall(retrieval.memories), 'memories'), memoryLine));
-      }
-      if (retrieval.skills !== undefined && typeof ledger.recallSkills === 'function') {
-        sections.push(...listSection('Skills you can reuse',
-          await retrieved(ledger.recallSkills(retrieval.skills), 'skills'), skillLine));
-      }
+    /**
+     * The system prompt for this turn: the immutable base, then the active
+     * goal and its progress, then whatever `retrieval` asks for. Read once
+     * per `send` rather than once per round — a goal does not change
+     * mid-turn, and re-reading it per round would put a storage round-trip
+     * in the tool loop for nothing.
+     *
+     * Returns null when there is nothing to compose, and the caller then
+     * sends the history untouched, by the same reference: an agent with no
+     * ledger, or a ledger with no goal and no retrieval, must be
+     * byte-identical to one built before any of this existed.
+     */
+    async function composeSystem(base) {
+        if (ledger === null)
+            return null;
+        const sections = [];
+        if (typeof ledger.getGoal === 'function') {
+            const goal = await ledger.getGoal();
+            if (goal !== null && goal !== undefined && goal.status === 'active') {
+                if (typeof ledger.composeGoal === 'function') {
+                    const composed = await ledger.composeGoal();
+                    if (composed.error)
+                        throw new AiError('AI0001', composed.error);
+                    sections.push(composed.text);
+                }
+                else
+                    sections.push(goalPrompt(goal));
+            }
+        }
+        if (retrieval !== null) {
+            if (retrieval.memories !== undefined && typeof ledger.recall === 'function') {
+                sections.push(...listSection('What you have learned so far', await retrieved(ledger.recall(retrieval.memories), 'memories'), memoryLine));
+            }
+            if (retrieval.skills !== undefined && typeof ledger.recallSkills === 'function') {
+                sections.push(...listSection('Skills you can reuse', await retrieved(ledger.recallSkills(retrieval.skills), 'skills'), skillLine));
+            }
+        }
+        if (sections.length === 0)
+            return null;
+        return [base, ...sections].filter((part) => part !== '').join('\n\n');
     }
-    if (sections.length === 0) return null;
-    return [base, ...sections].filter((part) => part !== '').join('\n\n');
-  }
-
-  /**
-   * One tool call, to `recall` or to the host's toolbox. `recall` is
-   * dispatched here rather than being added to the host's registry
-   * because the host's toolbox belongs to the host: an agent may not
-   * quietly grow it a tool that outlives the agent.
-   * @param {string} name
-   * @param {any} args
-   * @param {boolean} recalling - whether this agent listed `recall`
-   */
-  async function dispatch(name, args, listed) {
-    if (listed.recalling && name === RECALL_TOOL_NAME) return recallBox.box.execute(name, args);
-    if (listed.env.has(name)) return envBox.execute(name, args);
-    if (toolbox === null) return { error: 'no tools are available' };
-    return toolbox.execute(name, args);
-  }
-
-  /**
-   * @param {any[]} history
-   * @param {AgentHooks} [hooks]
-   */
-  async function send(history, hooks = {}) {
-    const messages = system !== '' && history[0]?.role !== 'system'
-      ? [{ role: 'system', content: system }, ...history]
-      : [...history];
-    const hostTools = toolbox !== null ? toolbox.toFunctionTools() : [];
-    // a host that registered its own `recall` keeps it: two definitions
-    // of one function name is not a wire-legal request
-    const recalling = recallBox !== null
-      && !hostTools.some((tool) => tool?.function?.name === RECALL_TOOL_NAME);
-    const named = new Set(hostTools.map((tool) => tool?.function?.name));
-    // same rule as `recall`: a host that registered its own tool of that
-    // name keeps it, because two definitions of one function name is not
-    // a wire-legal request. What this agent LISTED is what it dispatches.
-    const envTools = envBox === null
-      ? []
-      : envBox.toFunctionTools().filter((tool) => !named.has(tool?.function?.name));
-    const listed = {
-      recalling,
-      env: new Set(envTools.map((tool) => tool.function.name)),
-    };
-    const tools = [
-      ...hostTools,
-      ...(recalling ? recallBox.box.toFunctionTools() : []),
-      ...envTools,
-    ];
-    /** @type {any[]} */
-    const steps = [];
-    // the goal and the retrieved state, composed onto whatever base
-    // prompt this conversation carries — into the REQUEST, never into
-    // `messages`, so the transcript the host persists never accumulates
-    // a goal it would compose a second time next turn
-    const composed = await composeSystem(
-      messages[0]?.role === 'system' ? messages[0].content : system);
-
-    for (let round = 0; ; round++) {
-      const stop = budgetStop();
-      if (stop !== null) {
-        const message = { role: 'assistant', content: stop.content };
-        messages.push(message);
-        return { message, messages, steps, stopReason: stop.reason };
-      }
-
-      const request = composeRequest(messages, composed);
-      // the transcript as a slot: the conversation is written to the
-      // environment and the request keeps a window of it plus the
-      // address of the whole. This runs BEFORE any character budget,
-      // because a request that already carries two rounds has nothing
-      // left for compaction to cut.
-      const windowed = transcript === null
-        ? request
-        : await windowThroughEnvironment(request, transcript, environment);
-      const sent = historyBudget === undefined
-        ? windowed
-        : ledger === null
-          ? compactMessages(windowed, historyBudget, compaction)
-          : await compactToLedger(windowed, historyBudget, hostCompaction,
-            ledger, recallBox.options);
-      if (startedAt === null) startedAt = clock();
-      const completion = await client.complete({
-        messages: sent,
-        tools: tools.length > 0 ? tools : undefined,
-        onDelta: hooks.onDelta,
-        onReasoning: hooks.onReasoning,
-        signal: hooks.signal,
-      });
-      spent.turns += 1;
-      // reported usage is always counted (it is free and it is the truth);
-      // the character estimate is only paid for when a token budget
-      // depends on it
-      spent.tokens += tokensOf(sent, completion, budget?.tokens !== undefined);
-      const reply = completion.message;
-
-      if (reply.toolCalls === null || reply.toolCalls === undefined
-        || reply.toolCalls.length === 0) {
-        // reasoning rides on the RETURNED message only — the wire
-        // transcript stays clean for the next request
-        const transcript = { role: 'assistant', content: reply.content };
-        messages.push(transcript);
-        const message = reply.reasoning === undefined
-          ? transcript
-          : { ...transcript, reasoning: reply.reasoning };
-        return { message, messages, steps, stopReason: completion.finishReason ?? 'stop' };
-      }
-
-      if (round >= maxToolRounds) {
-        const message = {
-          role: 'assistant',
-          content: reply.content !== ''
-            ? reply.content
-            : `Stopped after ${maxToolRounds} tool rounds without a final answer — the tool work so far has been applied; send another message to continue.`,
+    /**
+     * One tool call, to `recall` or to the host's toolbox. `recall` is
+     * dispatched here rather than being added to the host's registry
+     * because the host's toolbox belongs to the host: an agent may not
+     * quietly grow it a tool that outlives the agent.
+     * @param recalling - whether this agent listed `recall`
+     */
+    async function dispatch(name, args, listed) {
+        if (listed.recalling && name === RECALL_TOOL_NAME)
+            return recallBox.box.execute(name, args);
+        if (listed.env.has(name))
+            return envBox.execute(name, args);
+        if (toolbox === null)
+            return { error: 'no tools are available' };
+        return toolbox.execute(name, args);
+    }
+    /**
+     * @param [hooks]
+     */
+    async function send(history, hooks = {}) {
+        const messages = system !== '' && history[0]?.role !== 'system'
+            ? [{ role: 'system', content: system }, ...history]
+            : [...history];
+        const hostTools = toolbox !== null ? toolbox.toFunctionTools() : [];
+        // a host that registered its own `recall` keeps it: two definitions
+        // of one function name is not a wire-legal request
+        const recalling = recallBox !== null
+            && !hostTools.some((tool) => tool?.function?.name === RECALL_TOOL_NAME);
+        const named = new Set(hostTools.map((tool) => tool?.function?.name));
+        // same rule as `recall`: a host that registered its own tool of that
+        // name keeps it, because two definitions of one function name is not
+        // a wire-legal request. What this agent LISTED is what it dispatches.
+        const envTools = envBox === null
+            ? []
+            : envBox.toFunctionTools().filter((tool) => !named.has(tool?.function?.name));
+        const listed = {
+            recalling,
+            env: new Set(envTools.map((tool) => tool.function.name)),
         };
-        messages.push(message);
-        return { message, messages, steps, stopReason: 'tool-limit' };
-      }
-
-      messages.push({
-        role: 'assistant',
-        content: reply.content,
-        tool_calls: reply.toolCalls.map((call) => ({
-          id: call.id,
-          type: 'function',
-          function: { name: call.name, arguments: call.arguments },
-        })),
-      });
-
-      for (const call of reply.toolCalls) {
-        hooks.onToolCall?.({ name: call.name, arguments: call.arguments });
-        const parsed = parseArguments(call.arguments);
-        const result = parsed.error !== undefined
-          ? parsed
-          : await dispatch(call.name, parsed.value, listed);
-        hooks.onToolResult?.({ name: call.name, result });
-        steps.push({ name: call.name, arguments: call.arguments, result });
-        messages.push({
-          role: 'tool',
-          tool_call_id: call.id,
-          name: call.name,
-          content: truncate(JSON.stringify(result ?? null), maxToolResultChars),
-        });
-      }
+        const tools = [
+            ...hostTools,
+            ...(recalling ? recallBox.box.toFunctionTools() : []),
+            ...envTools,
+        ];
+        const steps = [];
+        // the goal and the retrieved state, composed onto whatever base
+        // prompt this conversation carries — into the REQUEST, never into
+        // `messages`, so the transcript the host persists never accumulates
+        // a goal it would compose a second time next turn
+        const composed = await composeSystem(messages[0]?.role === 'system' ? messages[0].content : system);
+        for (let round = 0;; round++) {
+            const stop = budgetStop();
+            if (stop !== null) {
+                const message = { role: 'assistant', content: stop.content };
+                messages.push(message);
+                return { message, messages, steps, stopReason: stop.reason };
+            }
+            const request = composeRequest(messages, composed);
+            // the transcript as a slot: the conversation is written to the
+            // environment and the request keeps a window of it plus the
+            // address of the whole. This runs BEFORE any character budget,
+            // because a request that already carries two rounds has nothing
+            // left for compaction to cut.
+            const windowed = transcript === null
+                ? request
+                : await windowThroughEnvironment(request, transcript, environment);
+            const sent = historyBudget === undefined
+                ? windowed
+                : ledger === null
+                    ? compactMessages(windowed, historyBudget, compaction)
+                    : await compactToLedger(windowed, historyBudget, hostCompaction, ledger, recallBox.options);
+            if (startedAt === null)
+                startedAt = clock();
+            const completion = await client.complete({
+                messages: sent,
+                tools: tools.length > 0 ? tools : undefined,
+                onDelta: hooks.onDelta,
+                onReasoning: hooks.onReasoning,
+                signal: hooks.signal,
+            });
+            spent.turns += 1;
+            // reported usage is always counted (it is free and it is the truth);
+            // the character estimate is only paid for when a token budget
+            // depends on it
+            spent.tokens += tokensOf(sent, completion, budget?.tokens !== undefined);
+            const reply = completion.message;
+            if (reply.toolCalls === null || reply.toolCalls === undefined
+                || reply.toolCalls.length === 0) {
+                // reasoning rides on the RETURNED message only — the wire
+                // transcript stays clean for the next request
+                const transcript = { role: 'assistant', content: reply.content };
+                messages.push(transcript);
+                const message = reply.reasoning === undefined
+                    ? transcript
+                    : { ...transcript, reasoning: reply.reasoning };
+                return { message, messages, steps, stopReason: completion.finishReason ?? 'stop' };
+            }
+            if (round >= maxToolRounds) {
+                const message = {
+                    role: 'assistant',
+                    content: reply.content !== ''
+                        ? reply.content
+                        : `Stopped after ${maxToolRounds} tool rounds without a final answer — the tool work so far has been applied; send another message to continue.`,
+                };
+                messages.push(message);
+                return { message, messages, steps, stopReason: 'tool-limit' };
+            }
+            messages.push({
+                role: 'assistant',
+                content: reply.content,
+                tool_calls: reply.toolCalls.map((call) => ({
+                    id: call.id,
+                    type: 'function',
+                    function: { name: call.name, arguments: call.arguments },
+                })),
+            });
+            for (const call of reply.toolCalls) {
+                hooks.onToolCall?.({ name: call.name, arguments: call.arguments });
+                const parsed = parseArguments(call.arguments);
+                const result = parsed.error !== undefined
+                    ? parsed
+                    : await dispatch(call.name, parsed.value, listed);
+                hooks.onToolResult?.({ name: call.name, result });
+                steps.push({ name: call.name, arguments: call.arguments, result });
+                messages.push({
+                    role: 'tool',
+                    tool_call_id: call.id,
+                    name: call.name,
+                    content: truncate(JSON.stringify(result ?? null), maxToolResultChars),
+                });
+            }
+        }
     }
-  }
-
-  /**
-   * Continue the active objective without a new instruction from the
-   * user — the closed-tab case, and the primitive a host schedules on
-   * top of. It is a normal `send` whose only user turn says "carry on":
-   * everything that makes carrying on possible (the objective, what has
-   * been tried, what was learned) is already composed into the prompt,
-   * so a resumed agent is not told where it got to, it reads it.
-   *
-   * Scheduling — a timer, a service worker, a cron — is deliberately not
-   * here; see the README. This package injects its environment rather
-   * than owning it, and a heartbeat is environment.
-   * @param {any[]} [history] - the persisted transcript, if there is one
-   * @param {AgentHooks} [hooks]
-   */
-  async function resume(history = [], hooks = {}) {
-    const goal = ledger !== null && typeof ledger.getGoal === 'function'
-      ? await ledger.getGoal()
-      : null;
-    if (goal === null || goal === undefined || goal.status !== 'active') {
-      throw new AiError('AI0001',
-        'resume() needs an active goal — call ledger.setGoal() first');
+    /**
+     * Continue the active objective without a new instruction from the
+     * user — the closed-tab case, and the primitive a host schedules on
+     * top of. It is a normal `send` whose only user turn says "carry on":
+     * everything that makes carrying on possible (the objective, what has
+     * been tried, what was learned) is already composed into the prompt,
+     * so a resumed agent is not told where it got to, it reads it.
+     *
+     * Scheduling — a timer, a service worker, a cron — is deliberately not
+     * here; see the README. This package injects its environment rather
+     * than owning it, and a heartbeat is environment.
+     * @param [history] - the persisted transcript, if there is one
+     * @param [hooks]
+     */
+    async function resume(history = [], hooks = {}) {
+        const goal = ledger !== null && typeof ledger.getGoal === 'function'
+            ? await ledger.getGoal()
+            : null;
+        if (goal === null || goal === undefined || goal.status !== 'active') {
+            throw new AiError('AI0001', 'resume() needs an active goal — call ledger.setGoal() first');
+        }
+        return send([...history, { role: 'user', content: RESUME_TURN }], hooks);
     }
-    return send([...history, { role: 'user', content: RESUME_TURN }], hooks);
-  }
-
-  return { send, resume, spend };
+    return { send, resume, spend };
 }
-
 /** The user turn `resume` sends. */
 const RESUME_TURN = 'Continue working on the objective in your instructions. The progress'
-  + ' recorded there is what has already been done — do not repeat it. Take the next step,'
-  + ' and say what you did.';
-
+    + ' recorded there is what has already been done — do not repeat it. Take the next step,'
+    + ' and say what you did.';
 /**
- * @param {string} text - the model's argument string
- * @returns {{ value?: any, error?: string }}
+ * @param text - the model's argument string
  */
 function parseArguments(text) {
-  if (text === '' || text === undefined || text === null) return { value: {} };
-  try {
-    return { value: JSON.parse(text) };
-  }
-  catch (err) {
-    return { error: `tool arguments are not valid JSON: ${/** @type {Error} */ (err).message}` };
-  }
+    if (text === '' || text === undefined || text === null)
+        return { value: {} };
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch (err) {
+        return { error: `tool arguments are not valid JSON: ${err.message}` };
+    }
 }
-
 //#region the objective in the prompt
-
 /** How much of one progress note, memory or skill a prompt line shows. */
 const PROMPT_LINE_CHARS = 300;
-
 /**
  * The request's messages, with the composed system prompt in front of
  * them. The transcript is not touched: composition belongs to a request
@@ -429,100 +376,82 @@ const PROMPT_LINE_CHARS = 300;
  *
  * With nothing composed the SAME array comes back, by reference, so an
  * agent without a ledger sends exactly the object it always sent.
- * @param {any[]} messages
- * @param {string | null} composed
- * @returns {any[]}
  */
 function composeRequest(messages, composed) {
-  if (composed === null) return messages;
-  if (messages[0]?.role === 'system') {
-    return [{ ...messages[0], content: composed }, ...messages.slice(1)];
-  }
-  return [{ role: 'system', content: composed }, ...messages];
+    if (composed === null)
+        return messages;
+    if (messages[0]?.role === 'system') {
+        return [{ ...messages[0], content: composed }, ...messages.slice(1)];
+    }
+    return [{ role: 'system', content: composed }, ...messages];
 }
-
 /** One retrieved memory, as a prompt line. */
 const memoryLine = (memory) => `- ${excerpt(memory.text, PROMPT_LINE_CHARS)}`
-  + `${(memory.tags ?? []).length > 0 ? ` [${memory.tags.join(', ')}]` : ''}`
-  + ` (evidence: ${excerpt(typeof memory.evidence === 'string' ? memory.evidence : JSON.stringify(memory.evidence), PROMPT_LINE_CHARS)})`;
-
+    + `${(memory.tags ?? []).length > 0 ? ` [${memory.tags.join(', ')}]` : ''}`
+    + ` (evidence: ${excerpt(typeof memory.evidence === 'string' ? memory.evidence : JSON.stringify(memory.evidence), PROMPT_LINE_CHARS)})`;
 /** One retrieved skill, as a prompt line. */
 const skillLine = (skill) => `- ${skill.name} — when ${excerpt(skill.when, PROMPT_LINE_CHARS)}:`
-  + ` ${excerpt(skill.instructions, PROMPT_LINE_CHARS)}`
-  + `${(skill.tools ?? []).length > 0 ? ` (tools: ${skill.tools.join(', ')})` : ''}`;
-
+    + ` ${excerpt(skill.instructions, PROMPT_LINE_CHARS)}`
+    + `${(skill.tools ?? []).length > 0 ? ` (tools: ${skill.tools.join(', ')})` : ''}`;
 /**
  * A retrieved section, or nothing at all when the retrieval came back
  * empty — an empty heading in a prompt is a fact about the harness, not
  * about the work.
- * @param {string} title
- * @param {any[]} records
- * @param {(record: any) => string} line
- * @returns {string[]}
  */
 function listSection(title, records, line) {
-  if (records.length === 0) return [];
-  return [[`## ${title}`, ...records.map(line)].join('\n')];
+    if (records.length === 0)
+        return [];
+    return [[`## ${title}`, ...records.map(line)].join('\n')];
 }
-
 /**
  * A retrieval's records, or a loud failure. The ledger answers a
  * `where` predicate it cannot evaluate with `{ error }` rather than
  * ignoring it (a filter silently dropped answers the wrong question),
  * and a prompt built from the wrong question is worse than a run that
  * refuses to start.
- * @param {Promise<any>} pending
- * @param {string} what
- * @returns {Promise<any[]>}
  */
 async function retrieved(pending, what) {
-  const records = await pending;
-  if (Array.isArray(records)) return records;
-  // a ranked recall (`{ near }`) answers `{ memories | skills, scores,
-  // skipped }`; the records go into the prompt exactly as an array would
-  if (Array.isArray(records?.[what])) return records[what];
-  throw new AiError('AI0001',
-    `retrieval of ${what} failed: ${records?.error ?? 'the ledger returned no records'}`);
+    const records = await pending;
+    if (Array.isArray(records))
+        return records;
+    // a ranked recall (`{ near }`) answers `{ memories | skills, scores,
+    // skipped }`; the records go into the prompt exactly as an array would
+    if (Array.isArray(records?.[what]))
+        return records[what];
+    throw new AiError('AI0001', `retrieval of ${what} failed: ${records?.error ?? 'the ledger returned no records'}`);
 }
-
 //#endregion
-
 //#region the transcript as a slot
-
 /** Round units kept in the request when the transcript is a slot. */
 const TRANSCRIPT_WINDOW = 2;
-
 /**
  * A toolbox holding one set of definitions, compiled once.
- * @param {any[]} definitions
  */
 function toolboxOf(definitions) {
-  const box = createToolbox();
-  for (const definition of definitions) box.add(definition);
-  return box;
+    const box = createToolbox();
+    for (const definition of definitions)
+        box.add(definition);
+    return box;
 }
-
 /**
  * The conversation as text a `grep` can answer from: one header line per
  * message, then its content. Line-oriented on purpose — `grep` reports
  * the line that matched, so a tool result written as one JSON line comes
  * back as one legible hit with its address beside it.
- * @param {any[]} messages
- * @returns {string}
  */
 export function transcriptText(messages) {
-  return messages.map((message, index) => {
-    const head = `[${index}] ${message.role}`;
-    if (Array.isArray(message.tool_calls)) {
-      return message.tool_calls
-        .map((call) => `${head} → ${call.function?.name}(${call.function?.arguments})`)
-        .join('\n');
-    }
-    if (message.role === 'tool') return `${head} ${message.name}: ${message.content}`;
-    return `${head}: ${message.content}`;
-  }).join('\n');
+    return messages.map((message, index) => {
+        const head = `[${index}] ${message.role}`;
+        if (Array.isArray(message.tool_calls)) {
+            return message.tool_calls
+                .map((call) => `${head} → ${call.function?.name}(${call.function?.arguments})`)
+                .join('\n');
+        }
+        if (message.role === 'tool')
+            return `${head} ${message.name}: ${message.content}`;
+        return `${head}: ${message.content}`;
+    }).join('\n');
 }
-
 /**
  * Write the whole conversation to its slot and keep a window of it in
  * the request, with the address of the rest.
@@ -537,49 +466,38 @@ export function transcriptText(messages) {
  * The window is counted in ROUND UNITS, so an assistant message and the
  * tool replies it belongs to are never split — the same wire-legality
  * rule compaction obeys.
- * @param {any[]} messages
- * @param {{ slot: string, window: number }} transcript
- * @param {any} environment
- * @returns {Promise<any[]>}
  */
 async function windowThroughEnvironment(messages, transcript, environment) {
-  const written = await environment.put(transcript.slot, transcriptText(messages),
-    { kind: 'transcript', count: messages.length });
-
-  /** @type {any[]} */
-  const pinnedSystem = [];
-  let rest = messages;
-  if (messages[0]?.role === 'system') {
-    pinnedSystem.push(messages[0]);
-    rest = messages.slice(1);
-  }
-  const units = roundUnits(rest);
-  const firstUser = units.findIndex((unit) => unit[0].role === 'user');
-  const cut = Math.max(firstUser + 1, units.length - transcript.window);
-  if (cut <= firstUser + 1) return messages;
-
-  const pointer = {
-    role: 'assistant',
-    content: `[The whole conversation is in the environment as slot "${transcript.slot}"`
-      + ` (${messages.length} messages, ${written?.size ?? 0} characters). Nothing was dropped:`
-      + ` env_grep finds the round you need and env_read returns it. This request carries the`
-      + ` last ${units.length - cut} round(s).]`,
-  };
-  return [
-    ...pinnedSystem,
-    ...(firstUser >= 0 ? units[firstUser] : []),
-    pointer,
-    ...units.slice(cut).flat(),
-  ];
+    const written = await environment.put(transcript.slot, transcriptText(messages), { kind: 'transcript', count: messages.length });
+    const pinnedSystem = [];
+    let rest = messages;
+    if (messages[0]?.role === 'system') {
+        pinnedSystem.push(messages[0]);
+        rest = messages.slice(1);
+    }
+    const units = roundUnits(rest);
+    const firstUser = units.findIndex((unit) => unit[0].role === 'user');
+    const cut = Math.max(firstUser + 1, units.length - transcript.window);
+    if (cut <= firstUser + 1)
+        return messages;
+    const pointer = {
+        role: 'assistant',
+        content: `[The whole conversation is in the environment as slot "${transcript.slot}"`
+            + ` (${messages.length} messages, ${written?.size ?? 0} characters). Nothing was dropped:`
+            + ` env_grep finds the round you need and env_read returns it. This request carries the`
+            + ` last ${units.length - cut} round(s).]`,
+    };
+    return [
+        ...pinnedSystem,
+        ...(firstUser >= 0 ? units[firstUser] : []),
+        pointer,
+        ...units.slice(cut).flat(),
+    ];
 }
-
 //#endregion
-
 //#region budgets
-
 /** The dimensions a run is bounded by, in the order they are checked. */
-const BUDGET_DIMENSIONS = /** @type {const} */ (['turns', 'tokens', 'ms']);
-
+const BUDGET_DIMENSIONS = ['turns', 'tokens', 'ms'];
 /**
  * Characters per token when a provider reports no usage. Crude and
  * deliberately stated rather than hidden: a budget that silently did not
@@ -588,111 +506,96 @@ const BUDGET_DIMENSIONS = /** @type {const} */ (['turns', 'tokens', 'ms']);
  * magnitude on JSON, which is what a tool transcript mostly is.
  */
 const TOKEN_CHARS = 4;
-
 /**
  * What one exchange cost. The provider's own `usage` wins whenever it
- * reported any (`client.js` normalizes it onto the completion); the
+ * reported any (`client.ts` normalizes it onto the completion); the
  * character estimate is the fallback, and it counts the request that was
  * actually sent plus the reply that came back.
- * @param {any[]} sent - the messages this call carried
- * @param {any} completion
- * @param {boolean} estimate - whether the fallback is worth computing
- * @returns {number}
+ * @param sent - the messages this call carried
+ * @param estimate - whether the fallback is worth computing
  */
 function tokensOf(sent, completion, estimate) {
-  const usage = completion?.usage;
-  const reported = typeof usage?.total_tokens === 'number' && usage.total_tokens > 0
-    ? usage.total_tokens
-    : (usage?.prompt_tokens ?? 0) + (usage?.completion_tokens ?? 0);
-  if (reported > 0) return reported;
-  if (!estimate) return 0;
-  let chars = String(completion?.message?.content ?? '').length;
-  for (const message of sent) chars += sizeOf(message);
-  return Math.ceil(chars / TOKEN_CHARS);
+    const usage = completion?.usage;
+    const reported = typeof usage?.total_tokens === 'number' && usage.total_tokens > 0
+        ? usage.total_tokens
+        : (usage?.prompt_tokens ?? 0) + (usage?.completion_tokens ?? 0);
+    if (reported > 0)
+        return reported;
+    if (!estimate)
+        return 0;
+    let chars = String(completion?.message?.content ?? '').length;
+    for (const message of sent)
+        chars += sizeOf(message);
+    return Math.ceil(chars / TOKEN_CHARS);
 }
-
 /**
  * The message a spent budget stops with. It names the dimension that
  * ran out and what is left of the others, because "stopped" without a
  * quantity is indistinguishable from a crash to whoever reads the
  * transcript next — including the model, on a resumed turn.
- * @param {string} dimension
- * @param {any} budget
- * @param {{ turns: number, tokens: number, ms: number }} spent
- * @returns {string}
  */
 function budgetMessage(dimension, budget, spent) {
-  const remaining = BUDGET_DIMENSIONS.map((name) => (typeof budget[name] === 'number'
-    ? `${name}: ${Math.max(0, budget[name] - spent[name])} of ${budget[name]} left`
-    : `${name}: no limit`));
-  return `Stopped: the ${dimension} budget is spent (${spent[dimension]} of ${budget[dimension]}).`
-    + ` Remaining — ${remaining.join(', ')}. The work so far has been applied and recorded;`
-    + ' raise the budget or start a new run to continue.';
+    const remaining = BUDGET_DIMENSIONS.map((name) => (typeof budget[name] === 'number'
+        ? `${name}: ${Math.max(0, budget[name] - spent[name])} of ${budget[name]} left`
+        : `${name}: no limit`));
+    return `Stopped: the ${dimension} budget is spent (${spent[dimension]} of ${budget[dimension]}).`
+        + ` Remaining — ${remaining.join(', ')}. The work so far has been applied and recorded;`
+        + ' raise the budget or start a new run to continue.';
 }
-
 //#endregion
-
 //#region history compaction
-
 /** The characters one round unit costs a request. `sizeOf` is the
  * suite's one size rule (`@jarenjs/core/chunk`); a second local copy of
  * "how big is this" is how two budgets in one repository come to
  * disagree about the same message. */
 function unitSize(unit) {
-  let total = 0;
-  for (const message of unit) total += sizeOf(message);
-  return total;
+    let total = 0;
+    for (const message of unit)
+        total += sizeOf(message);
+    return total;
 }
-
 /**
  * Group wire messages into indivisible round units: an assistant
  * message carrying `tool_calls` travels with its `tool` replies (the
  * pairing OpenAI requires); everything else is a unit of one. The
  * leading system message is NOT a unit — the caller pins it.
- * @param {any[]} messages
- * @returns {any[][]}
  */
 function roundUnits(messages) {
-  /** @type {any[][]} */
-  const units = [];
-  for (let i = 0; i < messages.length; ) {
-    const message = messages[i];
-    if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
-      const unit = [message];
-      i++;
-      while (i < messages.length && messages[i].role === 'tool') {
-        unit.push(messages[i]);
-        i++;
-      }
-      units.push(unit);
-    }
-    else {
-      units.push([message]);
-      i++;
+    const units = [];
+    for (let i = 0; i < messages.length;) {
+        const message = messages[i];
+        if (message.role === 'assistant' && Array.isArray(message.tool_calls)) {
+            const unit = [message];
+            i++;
+            while (i < messages.length && messages[i].role === 'tool') {
+                unit.push(messages[i]);
+                i++;
+            }
+            units.push(unit);
+        }
+        else {
+            units.push([message]);
+            i++;
+        }
     }
-  }
-  return units;
+    return units;
 }
-
 /**
  * The lines one dropped round contributes to a synopsis: one per tool
  * call (name, argument excerpt, result excerpt), or one for a plain
  * turn. Both writers share it, so the addressed synopsis says exactly
  * what the plain one says plus the address.
- * @param {any[]} unit
- * @returns {string[]}
  */
 function unitLines(unit) {
-  const head = unit[0];
-  if (head.role === 'assistant' && Array.isArray(head.tool_calls)) {
-    return head.tool_calls.map((call) => {
-      const reply = unit.find((m) => m.role === 'tool' && m.tool_call_id === call.id);
-      return `- called ${call.function?.name}(${excerpt(call.function?.arguments, 60)}) → ${excerpt(reply?.content, 60)}`;
-    });
-  }
-  return [`- ${head.role}: ${excerpt(head.content, 60)}`];
+    const head = unit[0];
+    if (head.role === 'assistant' && Array.isArray(head.tool_calls)) {
+        return head.tool_calls.map((call) => {
+            const reply = unit.find((m) => m.role === 'tool' && m.tool_call_id === call.id);
+            return `- called ${call.function?.name}(${excerpt(call.function?.arguments, 60)}) → ${excerpt(reply?.content, 60)}`;
+        });
+    }
+    return [`- ${head.role}: ${excerpt(head.content, 60)}`];
 }
-
 /**
  * The built-in deterministic synopsis of dropped rounds: one line per
  * tool call (name, argument excerpt, result excerpt) or plain turn. No
@@ -700,21 +603,17 @@ function unitLines(unit) {
  *
  * With no ledger this is the whole story and the excerpt is the only
  * copy — which is what `ledger` exists to fix; see `synopsizeAddressed`.
- * @param {any[][]} dropped
- * @returns {string}
  */
 function synopsize(dropped) {
-  const lines = ['[Earlier context was compacted to fit the history budget. What happened:]'];
-  for (const unit of dropped) lines.push(...unitLines(unit));
-  return lines.join('\n');
+    const lines = ['[Earlier context was compacted to fit the history budget. What happened:]'];
+    for (const unit of dropped)
+        lines.push(...unitLines(unit));
+    return lines.join('\n');
 }
-
 /** The allowance the ledger-free path holds back for the synopsis. */
 const SYNOPSIS_RESERVE = 600;
-
 /** The smallest synopsis the excess truncation will leave behind. */
 const SYNOPSIS_FLOOR = 180;
-
 /**
  * The largest share of the budget an addressed synopsis may claim: one
  * part in `SYNOPSIS_SHARE`, or `SYNOPSIS_RESERVE`, whichever is bigger.
@@ -733,7 +632,6 @@ const SYNOPSIS_FLOOR = 180;
  * oldest rounds is the cheaper half of that trade.
  */
 const SYNOPSIS_SHARE = 4;
-
 /**
  * How many times the tail selection is re-run to settle its own
  * allowance. The allowance depends on how many rounds are dropped and
@@ -743,7 +641,6 @@ const SYNOPSIS_SHARE = 4;
  * largest allowance it reached, which is the safe end of the wobble.
  */
 const RESERVE_PASSES = 4;
-
 /**
  * Choose what survives: pin the system prompt and the first user
  * message, keep the largest round-aligned tail that fits, and report
@@ -754,169 +651,142 @@ const RESERVE_PASSES = 4;
  * the ledger-free path (unchanged since it was written), and for the
  * ledger path the addressed synopsis's own size — which it can compute
  * exactly, because it is about to write it — under a cap.
- * @param {any[]} messages
- * @param {number} budget
- * @param {(dropped: any[][]) => number} reserveFor
- * @returns {{ pins: any[], dropped: any[][], tail: any[], kept: number } | null}
  */
 function planCompaction(messages, budget, reserveFor) {
-  let total = 0;
-  for (const message of messages) total += sizeOf(message);
-  if (total <= budget) return null;
-
-  /** @type {any[]} */
-  const pinnedSystem = [];
-  let rest = messages;
-  if (messages[0]?.role === 'system') {
-    pinnedSystem.push(messages[0]);
-    rest = messages.slice(1);
-  }
-  const units = roundUnits(rest);
-  const firstUser = units.findIndex((unit) => unit[0].role === 'user');
-  const pinned = pinnedSystem.reduce((n, m) => n + sizeOf(m), 0)
-    + (firstUser >= 0 ? unitSize(units[firstUser]) : 0);
-
-  // budget the pins plus room for the synopsis itself, then take tail
-  // units (newest first) while they fit — always at least the last one
-  const select = (reserve) => {
-    let used = pinned + reserve;
-    let cut = units.length;
-    for (let k = units.length - 1; k > firstUser; k--) {
-      const size = unitSize(units[k]);
-      if (cut < units.length && used + size > budget) break;
-      used += size;
-      cut = k;
+    let total = 0;
+    for (const message of messages)
+        total += sizeOf(message);
+    if (total <= budget)
+        return null;
+    const pinnedSystem = [];
+    let rest = messages;
+    if (messages[0]?.role === 'system') {
+        pinnedSystem.push(messages[0]);
+        rest = messages.slice(1);
     }
-    return cut;
-  };
-
-  let cut = select(reserveFor([]));
-  for (let pass = 0; pass < RESERVE_PASSES; pass++) {
-    const next = select(reserveFor(units.slice(firstUser + 1, cut)));
-    if (next === cut) break;
-    cut = next;
-  }
-
-  const dropped = units.slice(firstUser + 1, cut);
-  if (dropped.length === 0) return null;
-  const tail = units.slice(cut).flat();
-  return {
-    pins: [...pinnedSystem, ...(firstUser >= 0 ? units[firstUser] : [])],
-    dropped,
-    tail,
-    kept: pinned + tail.reduce((n, m) => n + sizeOf(m), 0),
-  };
+    const units = roundUnits(rest);
+    const firstUser = units.findIndex((unit) => unit[0].role === 'user');
+    const pinned = pinnedSystem.reduce((n, m) => n + sizeOf(m), 0)
+        + (firstUser >= 0 ? unitSize(units[firstUser]) : 0);
+    // budget the pins plus room for the synopsis itself, then take tail
+    // units (newest first) while they fit — always at least the last one
+    const select = (reserve) => {
+        let used = pinned + reserve;
+        let cut = units.length;
+        for (let k = units.length - 1; k > firstUser; k--) {
+            const size = unitSize(units[k]);
+            if (cut < units.length && used + size > budget)
+                break;
+            used += size;
+            cut = k;
+        }
+        return cut;
+    };
+    let cut = select(reserveFor([]));
+    for (let pass = 0; pass < RESERVE_PASSES; pass++) {
+        const next = select(reserveFor(units.slice(firstUser + 1, cut)));
+        if (next === cut)
+            break;
+        cut = next;
+    }
+    const dropped = units.slice(firstUser + 1, cut);
+    if (dropped.length === 0)
+        return null;
+    const tail = units.slice(cut).flat();
+    return {
+        pins: [...pinnedSystem, ...(firstUser >= 0 ? units[firstUser] : [])],
+        dropped,
+        tail,
+        kept: pinned + tail.reduce((n, m) => n + sizeOf(m), 0),
+    };
 }
-
 /**
  * The compacted request: the pins, one synopsis message, the tail. The
  * synopsis takes exactly the room the plan reserved — whatever the
  * writer produced is truncated to the remaining allowance, so the budget
  * holds deterministically however long a writer runs on.
- * @param {{ pins: any[], tail: any[], kept: number }} plan
- * @param {string} content
- * @param {number} budget
- * @param {number} floor - the smallest synopsis worth keeping; the
+ * @param floor - the smallest synopsis worth keeping; the
  *   ledger path raises it so its header, which carries the index
  *   address, can never be the part that gets cut
- * @returns {any[]}
  */
 function assemble(plan, content, budget, floor) {
-  const synopsis = { role: 'assistant', content };
-  const excess = plan.kept + sizeOf(synopsis) - budget;
-  if (excess > 0) {
-    synopsis.content = truncate(synopsis.content,
-      Math.max(floor, synopsis.content.length - excess));
-  }
-  return [...plan.pins, synopsis, ...plan.tail];
+    const synopsis = { role: 'assistant', content };
+    const excess = plan.kept + sizeOf(synopsis) - budget;
+    if (excess > 0) {
+        synopsis.content = truncate(synopsis.content, Math.max(floor, synopsis.content.length - excess));
+    }
+    return [...plan.pins, synopsis, ...plan.tail];
 }
-
 /**
  * Fit the history into `budget` characters, destructively: the dropped
  * middle becomes one synopsis whose 60-character excerpts are the only
  * surviving trace of what those rounds found. Under budget the array
  * passes through untouched (same reference).
- * @param {any[]} messages
- * @param {number} budget
- * @param {(droppedRounds: any[][]) => string} compaction
- * @returns {any[]}
  */
 function compactMessages(messages, budget, compaction) {
-  const plan = planCompaction(messages, budget, () => SYNOPSIS_RESERVE);
-  if (plan === null) return messages;
-  return assemble(plan, compaction(plan.dropped), budget, SYNOPSIS_FLOOR);
+    const plan = planCompaction(messages, budget, () => SYNOPSIS_RESERVE);
+    if (plan === null)
+        return messages;
+    return assemble(plan, compaction(plan.dropped), budget, SYNOPSIS_FLOOR);
 }
-
 //#endregion
-
 //#region compaction that moves
-
 /**
  * What one dropped round is worth archiving as: its exact bytes, and the
  * content-addressed name they hash to. Pure — nothing is written here,
  * because the tail selection needs the exact synopsis size before it can
  * decide what to drop, and the synopsis needs the addresses.
- * @param {any[][]} dropped
- * @returns {{ entries: any[], index: any }}
  */
 function planArchive(dropped) {
-  const entries = dropped.map((unit) => {
-    const text = JSON.stringify(unit);
-    return { name: roundSlotName(text), size: text.length, text, kind: 'agent-round' };
-  });
-  // the listing writes addresses in the SAME `recall("…")` form the
-  // synopsis lines use: one address syntax, so following the index needs
-  // no second reading rule — from a model or from anything auditing what
-  // a request can still reach
-  const lines = [`${entries.length} archived round(s) — recall(name) returns one in full.`];
-  entries.forEach((entry, i) => lines.push(
-    `${slotAddress(entry.name, entry.size)} ${unitLines(dropped[i])[0]?.slice(2) ?? ''}`));
-  const text = lines.join('\n');
-  return {
-    entries,
-    index: { name: indexSlotName(text), size: text.length, text, kind: 'agent-round-index' },
-  };
+    const entries = dropped.map((unit) => {
+        const text = JSON.stringify(unit);
+        return { name: roundSlotName(text), size: text.length, text, kind: 'agent-round' };
+    });
+    // the listing writes addresses in the SAME `recall("…")` form the
+    // synopsis lines use: one address syntax, so following the index needs
+    // no second reading rule — from a model or from anything auditing what
+    // a request can still reach
+    const lines = [`${entries.length} archived round(s) — recall(name) returns one in full.`];
+    entries.forEach((entry, i) => lines.push(`${slotAddress(entry.name, entry.size)} ${unitLines(dropped[i])[0]?.slice(2) ?? ''}`));
+    const text = lines.join('\n');
+    return {
+        entries,
+        index: { name: indexSlotName(text), size: text.length, text, kind: 'agent-round-index' },
+    };
 }
-
 /**
  * The addressed synopsis. Every line carries the address of the round it
  * previews, and the header carries the address of the index that lists
  * them all — which is the part that survives truncation, so a request
  * whose synopsis was cut short still names a way back to every round it
  * cut.
- * @param {any[][]} dropped
- * @param {{ entries: any[], index: any }} archive
- * @param {((droppedRounds: any[][], addresses: any[]) => string) | null} hostWriter
- * @returns {string}
  */
 function synopsizeAddressed(dropped, archive, hostWriter) {
-  const header = `[Earlier context was compacted. ${dropped.length} round(s) are ARCHIVED, `
-    + `not lost: ${slotRef(archive.index.name)} lists every address; recall(name) returns`
-    + ' one in full. What happened:]';
-  if (hostWriter !== null) {
-    return `${header}\n${hostWriter(dropped, archive.entries.map(
-      ({ name, size, kind }) => ({ name, size, kind })))}`;
-  }
-  const lines = [header];
-  dropped.forEach((unit, i) => {
-    const own = unitLines(unit);
-    const address = slotAddress(archive.entries[i].name, archive.entries[i].size);
-    // a round the plain writer has nothing to say about still gets its
-    // address — the whole promise is that no round leaves unaddressed,
-    // and `unitLines` says nothing about an assistant turn that carries
-    // an EMPTY `tool_calls` array (which the loop never writes, but a
-    // host's persisted history can)
-    if (own.length === 0) {
-      lines.push(`- ${address}`);
-    }
-    else {
-      own[own.length - 1] += ` ${address}`;
-      lines.push(...own);
+    const header = `[Earlier context was compacted. ${dropped.length} round(s) are ARCHIVED, `
+        + `not lost: ${slotRef(archive.index.name)} lists every address; recall(name) returns`
+        + ' one in full. What happened:]';
+    if (hostWriter !== null) {
+        return `${header}\n${hostWriter(dropped, archive.entries.map(({ name, size, kind }) => ({ name, size, kind })))}`;
     }
-  });
-  return lines.join('\n');
+    const lines = [header];
+    dropped.forEach((unit, i) => {
+        const own = unitLines(unit);
+        const address = slotAddress(archive.entries[i].name, archive.entries[i].size);
+        // a round the plain writer has nothing to say about still gets its
+        // address — the whole promise is that no round leaves unaddressed,
+        // and `unitLines` says nothing about an assistant turn that carries
+        // an EMPTY `tool_calls` array (which the loop never writes, but a
+        // host's persisted history can)
+        if (own.length === 0) {
+            lines.push(`- ${address}`);
+        }
+        else {
+            own[own.length - 1] += ` ${address}`;
+            lines.push(...own);
+        }
+    });
+    return lines.join('\n');
 }
-
 /**
  * Write the archive. The fingerprint and length propose an address;
  * exact content comparison proves it. A collision refuses compaction
@@ -926,37 +796,34 @@ function synopsizeAddressed(dropped, archive, hostWriter) {
  * this path is that nothing leaves the request without a copy, and
  * carrying on would drop the round anyway while claiming an address for
  * it that answers nothing.
- * @param {any} ledger
- * @param {{ entries: any[], index: any }} archive
  */
 async function writeArchive(ledger, archive, referenceText, protectedNames) {
-  if (typeof ledger.putArchive === 'function') {
-    const written = await ledger.putArchive([...archive.entries, archive.index], { referenceText, protectedNames, immutable: true });
-    if (written?.error) throw new AiError('AI0001', `compaction could not archive rounds: ${written.error}`);
-    return;
-  }
-  const pending = new Map();
-  for (const entry of [...archive.entries, archive.index]) {
-    const planned = pending.get(entry.name);
-    if (planned !== undefined && planned.text !== entry.text)
-      throw new AiError('AI0001', `compaction archive address collision at '${entry.name}'`);
-    const existing = await ledger.getSlot(entry.name);
-    if (existing !== null && existing !== undefined) {
-      if (await ledger.readSlot(entry.name) !== entry.text)
-        throw new AiError('AI0001', `compaction archive address collision at '${entry.name}'`);
-      continue;
+    if (typeof ledger.putArchive === 'function') {
+        const written = await ledger.putArchive([...archive.entries, archive.index], { referenceText, protectedNames, immutable: true });
+        if (written?.error)
+            throw new AiError('AI0001', `compaction could not archive rounds: ${written.error}`);
+        return;
     }
-    pending.set(entry.name, entry);
-  }
-  for (const entry of pending.values()) {
-    const written = await ledger.putSlot(entry.name, entry.text, { kind: entry.kind });
-    if (written?.error !== undefined) {
-      throw new AiError('AI0001',
-        `compaction could not archive a round to slot '${entry.name}': ${written.error}`);
+    const pending = new Map();
+    for (const entry of [...archive.entries, archive.index]) {
+        const planned = pending.get(entry.name);
+        if (planned !== undefined && planned.text !== entry.text)
+            throw new AiError('AI0001', `compaction archive address collision at '${entry.name}'`);
+        const existing = await ledger.getSlot(entry.name);
+        if (existing !== null && existing !== undefined) {
+            if (await ledger.readSlot(entry.name) !== entry.text)
+                throw new AiError('AI0001', `compaction archive address collision at '${entry.name}'`);
+            continue;
+        }
+        pending.set(entry.name, entry);
+    }
+    for (const entry of pending.values()) {
+        const written = await ledger.putSlot(entry.name, entry.text, { kind: entry.kind });
+        if (written?.error !== undefined) {
+            throw new AiError('AI0001', `compaction could not archive a round to slot '${entry.name}': ${written.error}`);
+        }
     }
-  }
 }
-
 /**
  * Fit the history into `budget` characters WITHOUT destroying anything:
  * every dropped round is archived to an addressable slot first, and the
@@ -973,49 +840,35 @@ async function writeArchive(ledger, archive, referenceText, protectedNames) {
  * that talked to a model must not be run several times per request by
  * the settling loop, and whatever it returns is truncated to the
  * allowance anyway.
- * @param {any[]} messages
- * @param {number} budget
- * @param {((droppedRounds: any[][], addresses: any[]) => string) | null} hostWriter
- * @param {any} ledger
- * @param {{ index?: string }} recallOptions - updated with the current
+ * @param recallOptions - updated with the current
  *   index address, so an unknown-slot rejection can point at the listing
- * @returns {Promise<any[]>}
  */
 async function compactToLedger(messages, budget, hostWriter, ledger, recallOptions) {
-  const ceiling = Math.max(SYNOPSIS_RESERVE, Math.floor(budget / SYNOPSIS_SHARE));
-  const reserveFor = (dropped) => Math.min(ceiling, sizeOf({
-    role: 'assistant',
-    content: synopsizeAddressed(dropped, planArchive(dropped),
-      hostWriter === null ? null : () => synopsize(dropped)),
-  }));
-  const plan = planCompaction(messages, budget, reserveFor);
-  if (plan === null) return messages;
-
-  const archive = planArchive(plan.dropped);
-  const retained = [...plan.pins, ...plan.tail];
-  await writeArchive(ledger, archive, JSON.stringify(retained),
-    slotAddressesIn(retained.map((message) => message.content ?? '').join('\n')));
-  recallOptions.index = archive.index.name;
-
-  const content = synopsizeAddressed(plan.dropped, archive, hostWriter);
-  return assemble(plan, content, budget,
-    Math.max(SYNOPSIS_FLOOR, content.indexOf('\n') + 1 || content.length));
+    const ceiling = Math.max(SYNOPSIS_RESERVE, Math.floor(budget / SYNOPSIS_SHARE));
+    const reserveFor = (dropped) => Math.min(ceiling, sizeOf({
+        role: 'assistant',
+        content: synopsizeAddressed(dropped, planArchive(dropped), hostWriter === null ? null : () => synopsize(dropped)),
+    }));
+    const plan = planCompaction(messages, budget, reserveFor);
+    if (plan === null)
+        return messages;
+    const archive = planArchive(plan.dropped);
+    const retained = [...plan.pins, ...plan.tail];
+    await writeArchive(ledger, archive, JSON.stringify(retained), slotAddressesIn(retained.map((message) => message.content ?? '').join('\n')));
+    recallOptions.index = archive.index.name;
+    const content = synopsizeAddressed(plan.dropped, archive, hostWriter);
+    return assemble(plan, content, budget, Math.max(SYNOPSIS_FLOOR, content.indexOf('\n') + 1 || content.length));
 }
-
 /**
  * A private toolbox holding just `recall`: the tool's schema compiles
  * once per agent, and a call to it answers `{ error }` under exactly the
  * rules every host tool answers under, because it goes through the same
  * registry. `options` is read at call time, so each compaction can point
  * an unknown-address rejection at the index it just wrote.
- * @param {any} ledger
  */
 function recallToolbox(ledger) {
-  /** @type {{ index?: string }} */
-  const options = {};
-  const box = createToolbox();
-  box.add(createRecallTool(ledger, options));
-  return { box, options };
+    const options = {};
+    const box = createToolbox();
+    box.add(createRecallTool(ledger, options));
+    return { box, options };
 }
-
-//#endregion