@jxsuite/studio 5.3.0 → 5.4.0

package/src/services/idle.ts

@@ -3,7 +3,8 @@
  * Idle.ts — "settled" is a predicate, and it can fail.
  *
  * One question — _has Studio finished reacting?_ — asked of the five subsystems that can still be
- * mid-flight, over two consecutive animation frames (spec studio.md §13.5, plan §13.4).
+ * mid-flight, over two consecutive animation frames (spec studio.md §13.5, and "Determinism" in
+ * `scripts/screenshots/README.md`).
  *
  * **The rejection is the point.** The thing this replaces is 115 `wait: {ms}` steps totalling 73
  * seconds, and a sleep cannot fail: a subsystem that was slow that day got answered with `+500 ms`
@@ -29,7 +30,7 @@
  *    all thirty-odd `git*`/fs/fetch methods pass through.
  * 4. `layers.overlayIdleBlockers()` — overlays still in transition. Only the SETTLING window counts: a
  *    resting toast is not a blocker, which is what lets `toastsAreHeld()` hold one open for a
- *    capture without `probeIdle()` waiting forever alongside it (plan §13.7's named exception).
+ *    capture without `probeIdle()` waiting forever alongside it (§13.5's toast exception).
  * 5. `activity-panel.activityIdleBlockers()` — operations still RUNNING in the Activity tab. Not a
  *    duplicate of `platform`: an activity spans a whole operation (an install, a deploy, a clone)
  *    across many PAL calls, so the gaps between them look quiet at the seam while the operation is
@@ -38,8 +39,8 @@
  *    selection range `selectableRange: 1` gives them. Nothing else covered Tabulator: a grid
  *    command resolves when the panel mounts, which is several frames before the table is drawn.
  *
- * The consumers are the `packages/studio:verify` skill, the screenshot runner and P4.2's Activity
- * tracker (this is a read-only projection of the same in-flight set that dock renders).
+ * The consumers are the `packages/studio:verify` skill, the screenshot runner and the Activity
+ * tracker of §16.4 (this is a read-only projection of the same in-flight set that dock renders).
  */
 
 import { rendersInFlight } from "../store";

package/src/services/live-surfaces.ts

@@ -17,7 +17,8 @@
  * outside Studio reaches the shell on the next reload, as it always did, because a watcher is a
  * second writer racing the tab. And it does not diff: a saved document is re-registered whole and
  * every root re-mounted, because a surface's host scope is reused (`SurfaceMount.remount`) and only
- * the surface-local state resets, which is the contract §9.3 gives the registry.
+ * the surface-local state resets, which is the contract `studio-ui-guidelines.md` §9.3 gives the
+ * registry.
  *
  * A kit redefinition reaches the canvas frames too, with the FILE's URL under the project as its
  * base: the frame draws a project's elements from the project's own files, so a sibling `$ref` in

package/src/services/notify.ts

@@ -1,5 +1,6 @@
 /**
- * Notify.ts — the third record type (plan §1), and the app's only way to say what happened.
+ * Notify.ts — the third record type, beside `Command` and `Panel` (§16), and the app's only way to
+ * say what happened.
  *
  * What this replaces: 78 `statusMessage()` call sites — 26 failures and 52 successes — rendered in
  * identical 11px grey text in a 24px strip and destroyed after 3000 ms. A failure and a save looked
@@ -7,20 +8,20 @@
  * read them. `statusMessage` is deleted, not wrapped; `scripts/check-styles.ts` bans the name from
  * `src/` so it cannot regrow.
  *
- * **A notification is a record, and its lifetime is chosen by the action it requires** (§7.1):
+ * **A notification is a record, and its lifetime is chosen by the action it requires** (§16.1):
  *
  * | Tier      | Host                       | Lifetime           | Use when                       |
  * | --------- | -------------------------- | ------------------ | ------------------------------ |
  * | `toast`   | the fourth overlay layer   | timed, dismissible | reversible, or needs no action |
  * | `problem` | the Bottom dock's Problems | until it is fixed  | it must be fixed               |
  *
- * §7.1 names a third tier — **inline**, the refusal a field draws at the control (`jx-field`'s own
+ * §16.1 names a third tier — **inline**, the refusal a field draws at the control (`jx-field`'s own
  * `[part="error"]`, projected by whichever inspector document owns the row). It is deliberately NOT
  * a member of {@link NotificationTier}: an inline error is a value a control renders next to the
  * field the user is editing, not a record the app posts to a host, and it has no store to live in.
  * Declaring a tier here whose only possible outcome is being dropped on the floor would be exactly
  * the silence this module exists to end, so the union has two members and the third tier arrives as
- * a field's own projected value (P4.4).
+ * a field's own projected value (§16.5).
  *
  * **Recovery is a command id, not a per-call-site closure.** `notify.error("Save failed", { action:
  * "file.save" })` gives the toast and the Problems row a Retry button whose label, availability,
@@ -64,8 +65,9 @@ const DEFAULT_TIER: Readonly<Record<Severity, NotificationTier>> = {
 /**
  * How long a toast rests before it is taken away, by severity.
  *
- * §7.1 caps the band at 4–8s. A warning that nobody has to act on still deserves the long end of
- * it, because it is the one a reader is most likely to have looked away from.
+ * `studio-ui-guidelines.md` §13.2 caps the band at 4–8s. A warning that nobody has to act on still
+ * deserves the long end of it, because it is the one a reader is most likely to have looked away
+ * from.
  */
 export const TOAST_LIFETIME_MS: Readonly<Record<Severity, number>> = {
   error: 8000,
@@ -214,7 +216,7 @@ export function notify(
   return record;
 }
 
-/** `notify.success(msg, opts)` and its three siblings — the shape §7.1 names. */
+/** `notify.success(msg, opts)` and its three siblings — the shape §16.1 names. */
 function severityHelper(severity: Severity) {
   return (message: string, options: NotifyOptions = {}) => notify(severity, message, options);
 }

package/src/services/popover-report.ts

@@ -113,9 +113,9 @@ export function reportPopoverProblems(doc: JxElement, path?: string): number {
       ...(path === undefined ? {} : { path }),
     });
   }
-  /* The dialog and invoker-command rules (spec §8.7) file under the same source: one report for
-     everything the platform overlays. They carry no repair button yet — the popover repairs move
-     `display` into `:popover-open`, and a dialog's open rule is a different selector. */
+  /* The dialog and invoker-command rules (`spec.md` §8.7) file under the same source: one report
+     for everything the platform overlays. They carry no repair button yet — the popover repairs
+     move `display` into `:popover-open`, and a dialog's open rule is a different selector. */
   const dialogDefects = findDialogDefects(doc, KIT_SCOPE);
   for (const defect of dialogDefects) {
     notify(defect.severity, defect.message, {

package/src/services/preview-eval.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * Parent-side live expression preview (spec §19.9).
+ * Parent-side live expression preview (`spec.md` §19.9).
  *
  * Evaluates an expression node against the canvas iframe's last dataScope snapshot
  * (tab.session.canvas.scope) on a structuredClone, so mutating operators are safe — they mutate the

package/src/services/project-adoption.ts

@@ -10,6 +10,7 @@
  */
 
 import { initProjectRepo } from "../files/files";
+import { getPlatform, hasPlatform } from "../platform";
 import { beginBatch, endBatch, isBatching } from "../tabs/transact";
 import { workspace } from "../workspace/workspace";
 import type { Tab } from "../tabs/tab";
@@ -41,6 +42,12 @@ export interface AdoptOutcome {
   adopted: boolean;
   /** Why adoption failed, when it threw. Null when it did not (including when it silently did not). */
   error: string | null;
+  /**
+   * `adopted` is false BY DESIGN: a different project was already showing here, so the open flow
+   * below put the new one in a window of its own instead of replacing what this one is showing. Not
+   * a failure — a caller that only checks `adopted` would otherwise report a success as one.
+   */
+  openedElsewhere: boolean;
 }
 
 /** The seams {@link adoptCreatedProject} runs through, so each caller keeps the one it already had. */
@@ -84,6 +91,32 @@ export async function adoptCreatedProject(
   // Never fails the create: a project that was written stays written (initProjectRepo notifies).
   await initRepo(root);
 
+  /* `initRepo` ran git init through THIS window's backend — `platform.createProject` re-roots it to
+     `root` as a side effect of scaffolding, because git init has no explicit-root variant of its
+     own. That is fine when this window is about to show `root` too, but wrong when a DIFFERENT
+     project was already showing here: `adopt` below (`openRecentProject`) would open `root` in a
+     new window on exactly that condition, and that new-window flow dedupes by asking the backend
+     which window already has `root` open — which, thanks to the reroot above, now reads as THIS
+     one. Left alone, that either hands `root` back to this same window (skipping the new window
+     entirely) or opens a second window while leaving this one's backend silently pointed at `root`
+     even though its own UI still names the project it had before. Putting this window's backend
+     back where its UI says it is — before `adopt` runs — is what keeps both promises: the window
+     that already had a project keeps that project, backend included, and `root` gets a window of
+     its own. */
+  const platform = hasPlatform() ? getPlatform() : null;
+  const shownRoot = workspace.projectRoot;
+  const openedElsewhere = Boolean(
+    platform && shownRoot && shownRoot !== root && platform.openProjectInNewWindow,
+  );
+  if (openedElsewhere && shownRoot && platform?.setWindowProject) {
+    try {
+      await platform.setWindowProject(shownRoot);
+    } catch {
+      /* Best-effort restore — `adopt` below still runs, and a failed restore here is no worse than
+         the mismatch this guards against. */
+    }
+  }
+
   const wasBatching = isBatching();
   if (wasBatching) {
     endBatch();
@@ -98,5 +131,5 @@ export async function adoptCreatedProject(
     beginBatch(getTab());
   }
 
-  return { adopted: workspace.projectRoot === root, error: adoptionError };
+  return { adopted: workspace.projectRoot === root, error: adoptionError, openedElsewhere };
 }

package/src/services/project-path.ts

@@ -0,0 +1,53 @@
+/**
+ * Project-path.ts — the containment check the assistant's file tools run before they touch disk.
+ *
+ * `ai.md` §4: a file tool refuses a path outside the open project itself, rather than leaving the
+ * server to. `list_files`, `read_file` and `write_file` always refused one; `create_component`
+ * and `create_page` took the model's path as given and handed it to the platform write. One module,
+ * so the two sets of tools cannot disagree about what "inside the project" means, and a leaf,
+ * because the document tools and the project tools already import each other's neighbours.
+ *
+ * @docs studio/ai/chat
+ * @license MIT
+ */
+
+import type { ToolResult } from "@jxsuite/ai/tools";
+
+/**
+ * Normalize a project-relative path, or return null when it escapes the project (absolute paths,
+ * `..` segments, drive letters, a home directory). The server re-checks; this keeps the error
+ * actionable.
+ *
+ * @param {unknown} path
+ * @returns {string | null}
+ */
+export function normalizeRelPath(path: unknown): string | null {
+  if (typeof path !== "string" || !path.trim()) {
+    return null;
+  }
+  let p = path.trim().replaceAll("\\", "/");
+  while (p.startsWith("./")) {
+    p = p.slice(2);
+  }
+  if (p.startsWith("/") || p.startsWith("~") || /^[A-Za-z]:/.test(p)) {
+    return null;
+  }
+  if (p.split("/").includes("..")) {
+    return null;
+  }
+  return p;
+}
+
+/**
+ * The refusal a tool returns for a path {@link normalizeRelPath} rejected, quoting what the model
+ * sent so it can see what to change.
+ *
+ * @param {unknown} path
+ * @returns {ToolResult}
+ */
+export function invalidPathResult(path: unknown): ToolResult {
+  return {
+    success: false,
+    error: `Invalid path ${JSON.stringify(path)} — use a path relative to the project root (no leading "/", no "..").`,
+  };
+}

package/src/services/settings/kernel.ts

@@ -184,9 +184,20 @@ function apply(patch: SettingsPatch): string[] {
   return moved;
 }
 
+/**
+ * What a write of `value` would store: the definition's own `normalize`, or the value as given.
+ *
+ * The one home of that rule, and exported for a reason: a form that asks "would Save change
+ * anything?" has to compare what the store WOULD hold, not what was typed — or a pasted key's
+ * trailing newline, or an endpoint's trailing slash, reads as an edit the store would erase.
+ */
+export function normalizeSetting(definition: SettingDefinition, value: string): string {
+  return definition.normalize ? definition.normalize(value) : value;
+}
+
 /** Store a value. An empty string is a VALUE; {@link clearSetting} is the only deletion. */
 export function setSetting(definition: SettingDefinition, value: string): void {
-  const next = definition.normalize ? definition.normalize(value) : value;
+  const next = normalizeSetting(definition, value);
   const moved = apply({ [definition.key]: next });
   if (moved.length > 0) {
     queue.enqueue({ [definition.key]: next });
@@ -204,7 +215,7 @@ export function setSetting(definition: SettingDefinition, value: string): void {
 export function setSettings(entries: readonly [SettingDefinition, string][]): void {
   const patch: SettingsPatch = {};
   for (const [definition, value] of entries) {
-    patch[definition.key] = definition.normalize ? definition.normalize(value) : value;
+    patch[definition.key] = normalizeSetting(definition, value);
   }
   const moved = apply(patch);
   if (moved.length > 0) {

package/src/services/tool-executor.ts

@@ -3,16 +3,22 @@
  *
  * Streams a chat round, executes any tool calls the model makes (via a ToolRegistry backed by
  * `transactDoc()`), feeds the results back as `tool` messages, and re-streams — up to a capped
- * number of rounds (spec §10.2, ADR docs/ai-assistant-decision.md §6a).
+ * number of rounds (specs/ai.md §3.2 to §3.4).
  *
- * Two §7.4 honesty rules live here rather than in the panel, because they are properties of the RUN
- * and a panel can only render what the run recorded:
+ * Two `ai.md` §3.2 honesty rules live here rather than in the panel, because they are properties of
+ * the RUN and a panel can only render what the run recorded:
  *
  * - **A partial success is not a failure.** Running out of rounds called `setError`, which paints
  *   the turn red and — in `chat-state.ts` — DELETES the streaming message, so a turn that applied
  *   four edits and then hit the cap reported as an error that had also erased its own account of
  *   the four edits. The cap is now an ordinary assistant message whenever anything was applied, and
- *   an error only when nothing was.
+ *   an error only when nothing was. **Applied means it wrote**: a call counts when it succeeded with
+ *   a summary AND the write ledger grew by an `ok` write while it ran, not merely when it returned a
+ *   summary, because a read returns a summary too, and a turn that only looked around was reported
+ *   as having changed things.
+ * - **A turn that drew nothing says so.** A model that answered with neither text nor a tool call
+ *   left the author's message sitting there with no reply at all. That turn ends on an error row,
+ *   with Retry, instead.
  * - **A batch belongs to the tab it edits.** `beginBatch(getTab())` ran once, against whichever tab
  *   happened to be active when the loop started. A turn that then moved to a second document closed
  *   its batch against the FIRST tab, so the second document's edits got neither a history snapshot
@@ -23,16 +29,22 @@
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
 import type { StreamingClient } from "@jxsuite/ai/streaming-client";
-import type { ToolRegistry } from "@jxsuite/ai/tools";
+import { createSessionFacts, createToolContext, linkCallSignal } from "@jxsuite/ai/tools";
+import type { Actor, SessionFacts, ToolRegistry } from "@jxsuite/ai/tools";
 
 import type { Tab } from "../tabs/tab";
+import type { ImportProgressEvent } from "../types";
 import { batchTab, beginBatch, endBatch } from "../tabs/transact";
 import { ensureProxyProbe, resetModelCache } from "./ai-models";
-import { beginTurn, endTurn } from "./ai-writes";
-import { beginToolCall, beginTurnSignal, endTurnSignal } from "./ai-turn-signal";
+import { estimatePromptTokens } from "./context-manager";
+import { fileTurn, openTurnLedger, turnAnchor } from "./ai-writes";
+import { recordImportProgress } from "./import-run";
 
 const MAX_ROUNDS = 5;
 
+/** What a turn that drew nothing says: the model answered with neither text nor a tool call. */
+export const EMPTY_TURN_TEXT = "The model sent back an empty reply.";
+
 /**
  * Hard ceiling on rounds of every kind, so the loop terminates whatever the model does.
  *
@@ -44,9 +56,6 @@ const MAX_ROUNDS = 5;
  */
 const MAX_TOTAL_ROUNDS = 25;
 
-/** Tools that suspend the turn on a human rather than doing work. */
-const INTERACTIVE_TOOLS = new Set(["ask_user"]);
-
 interface RunAgentLoopOptions {
   chatState: ReturnType<typeof createChatState>;
   streamingClient: StreamingClient;
@@ -54,6 +63,8 @@ interface RunAgentLoopOptions {
   systemPrompt: string;
   signal?: AbortSignal;
   getTab?: () => Tab | null;
+  /** The conversation's facts, which every call's context carries; a fresh set when omitted. */
+  session?: SessionFacts;
 }
 
 /**
@@ -67,18 +78,24 @@ export async function runAgentLoop({
   systemPrompt,
   signal,
   getTab,
+  session = createSessionFacts(),
 }: RunAgentLoopOptions): Promise<void> {
   const allErrors: string[] = [];
   const appliedSummaries: string[] = [];
 
-  /** The ledger is filed under the assistant message the turn ends on — see services/ai-writes. */
-  const turnId = () => chatState.messages.at(-1)?.id ?? "";
-  beginTurn(`turn:${chatState.messages.length}`);
-
-  /* The signal, published for the tools rather than passed to them: `ToolRegistry.execute` takes
-     none. Without it a tool that waits for a human never learns the turn was stopped, and the
-     `await` below is the whole loop. See services/ai-turn-signal.ts. */
-  beginTurnSignal(signal);
+  /* The ledger is filed under the turn's last DRAWN assistant message (see services/ai-writes), so
+     the scan starts at the message this turn answers. */
+  const turnUserId = chatState.messages.findLast((m) => m.role === "user")?.id;
+  /* What every call's context carries (specs/ai.md §3.7): this turn's ledger, the conversation's
+     facts, and who the calls act as. The signal and the call id are the call's own, below. */
+  const ledger = openTurnLedger(`turn:${chatState.messages.length}`);
+  const actor: Actor = {
+    id: `assistant:${session.sessionId ?? "local"}:${ledger.turnId}`,
+    kind: "assistant",
+    model: chatState.model,
+    sessionId: session.sessionId,
+    turnId: ledger.turnId,
+  };
 
   // Batch all tool-call mutations into a single undo step, anchored on the tab being edited.
   if (getTab) {
@@ -149,6 +166,12 @@ export async function runAgentLoop({
             chatState.appendToolCallEnd(event.id);
             break;
           }
+          case "usage": {
+            /* The provider's own count replaces the four-characters-per-token estimate. The prompt
+               it covered is recorded with it, because the next send rebuilds the prompt. */
+            chatState.recordUsage(event, { systemTokens: estimatePromptTokens(systemPrompt) });
+            break;
+          }
           case "done": {
             ({ stopReason } = event);
             break;
@@ -164,8 +187,6 @@ export async function runAgentLoop({
         }
       }
 
-      chatState.finishStream(stopReason);
-
       if (streamError) {
         /* A lapsed hosted grant is the one stream error that makes the app's OWN reading wrong.
            The probe settles once at boot, so without this every gate keeps offering an assistant
@@ -175,36 +196,91 @@ export async function runAgentLoop({
           resetModelCache();
           ensureProxyProbe();
         }
+        /* `setError` alone, never after `finishStream`: it removes the round's partial message,
+           and only while that message is still the streaming one. Finishing first let go of it, so
+           the partial (a tool call cut off mid-arguments, as often as not) stayed in the
+           transcript and went out on the next send. */
         chatState.setError(streamError);
         return;
       }
 
-      if (stopReason !== "tool_calls" || toolCalls.size === 0) {
+      /* A turn that has drawn nothing by the end of a round with no calls ends here, as an error
+         the author can see and retry, rather than as silence under their message. `setError`
+         before `finishStream`, so it removes the empty reply. A stopped round is not empty: the
+         author ended it. */
+      const stopped = stopReason === "cancelled" || signal?.aborted === true;
+      if (toolCalls.size === 0 && !stopped && turnAnchor(chatState.messages, turnUserId) === null) {
+        chatState.setError(EMPTY_TURN_TEXT);
+        return;
+      }
+
+      chatState.finishStream(stopReason);
+
+      /* The calls the model streamed decide whether tools run, not the finish reason the provider
+         reported beside them. Some OpenAI-compatible backends (Workers AI among them) end a
+         tool-calling turn with `finish_reason: "stop"`, and gating on `tool_calls` dropped those
+         calls unrun — the turn ended looking finished, and the next send sealed them as failures.
+         A call cut off by `length` still runs: its arguments fail to parse, and the model reads
+         that as a tool error it can correct.
+
+         Cancellation is the exception, and it is not a finish reason at all: it is the author
+         pressing Stop. A stopped round runs nothing it streamed, including calls whose arguments
+         were already complete, because Stop is the one control that must not be outrun. */
+      if (toolCalls.size === 0 || stopReason === "cancelled" || signal?.aborted) {
         return;
       }
 
       let didWork = false;
       for (const [id, call] of toolCalls) {
+        /* A Stop that lands between calls (while `ask_user` waits, or during a long import) stops
+           the calls after it too. They stay unanswered, and the send path seals them. */
+        if (signal?.aborted) {
+          return;
+        }
         let result;
-        // Published, not passed: `ToolRegistry.execute` takes the args and nothing else.
-        beginToolCall(id);
+        // The ledger's length before the call, so the call can be judged by what it recorded.
+        const writesBefore = ledger.writes.length;
+        /* The call's own signal: it aborts with the turn, so a tool waiting on a person or a crawl
+           learns of a Stop, and it is unlinked once the call settles, so a Stop later in the turn
+           reaches nothing that has already finished. */
+        const link = signal ? linkCallSignal(signal) : null;
+        const ctx = createToolContext({
+          actor,
+          callId: id,
+          ledger,
+          progress: (event) => {
+            recordImportProgress(id, event as unknown as ImportProgressEvent);
+          },
+          session,
+          ...(link ? { signal: link.signal } : {}),
+        });
         try {
-          const args = call.arguments ? (JSON.parse(call.arguments) as object) : {};
-          result = await toolRegistry.execute(call.name, args);
+          result = await toolRegistry.execute(call.name, parseToolArguments(call.arguments), ctx);
         } catch (error) {
           result = {
             success: false,
             error: `Failed to parse arguments: ${(error as Error).message}`,
           };
+        } finally {
+          link?.release();
         }
-        if (!INTERACTIVE_TOOLS.has(call.name)) {
+        /* The transcript was replaced while the call ran: another chat was opened from Chat
+           History, which stops the turn. The reply belongs to a request that is no longer there,
+           so writing it would land a stray `tool` message in the other conversation, and could
+           overwrite a restored record's result where a provider reuses call ids. */
+        if (turnUserId !== undefined && !chatState.messages.some((m) => m.id === turnUserId)) {
+          return;
+        }
+        // A call that suspends the turn on a person does not spend its work budget.
+        if (toolRegistry.getDefinition(call.name)?.interactive !== true) {
           didWork = true;
         }
         reanchorBatch();
         if (!result.success && result.error) {
           allErrors.push(result.error);
         }
-        if (result.success && result.summary) {
+        const wrote = ledger.writes.slice(writesBefore).some((write) => write.ok);
+        if (result.success && result.summary && wrote) {
           appliedSummaries.push(result.summary);
         }
         chatState.appendToolResult(id, result);
@@ -214,6 +290,12 @@ export async function runAgentLoop({
       if (didWork) {
         workRounds += 1;
       }
+      /* A Stop that landed during the round's last call. Nothing is left to stop in this round, so
+         without this the loop opened the next one: a placeholder pushed after the author stopped,
+         and a request streamed on the aborted signal. */
+      if (signal?.aborted) {
+        return;
+      }
       if (workRounds < MAX_ROUNDS && round < MAX_TOTAL_ROUNDS) {
         chatState.beginAssistantTurn();
       }
@@ -222,7 +304,7 @@ export async function runAgentLoop({
     /*
      * The round cap. Surface the actual errors so the user knows what went wrong, not just a
      * generic "I couldn't do it" — and, when anything was applied, say it as the ASSISTANT rather
-     * than as a failure (§7.4). A partial success is not a failure.
+     * than as a failure (`ai.md` §3.2). A partial success is not a failure.
      */
     const uniqueErrors = [...new Set(allErrors)];
     const applied =
@@ -244,8 +326,31 @@ export async function runAgentLoop({
     }
     chatState.setError(tail);
   } finally {
-    endTurnSignal();
     endBatch();
-    endTurn(turnId());
+    fileTurn(turnAnchor(chatState.messages, turnUserId) ?? "", ledger.writes);
+  }
+}
+
+/**
+ * A call's arguments as the object a tool takes.
+ *
+ * An empty string is no arguments. JSON that parses to something other than an object (`null`, an
+ * array, a number) is refused here with its own sentence, rather than reaching the registry, where
+ * a validator reading a property of `null` threw a message about the validator. The prefix is the
+ * one a JSON syntax error already carries, so the model reads both as one kind of mistake.
+ *
+ * @param {string} text - The call's accumulated argument text
+ * @returns {object}
+ * @throws {SyntaxError | TypeError} Caught by the loop and returned to the model as a tool error
+ */
+function parseToolArguments(text: string): object {
+  if (!text) {
+    return {};
+  }
+  const parsed = JSON.parse(text) as unknown;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const type = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
+    throw new TypeError(`arguments must be a JSON object, got ${type}`);
   }
+  return parsed;
 }