pi-supernova 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.0.8] - 2026-09-04
+
+### Changed
+
+- Result card redesigned as an aligned ledger: one row per call (status · tool · duration · `exit N` · `+a/-r` · target), no tree stems or spacer rows, durations humanized (`6.2s`), multi-line commands shown as their first line plus `…+N lines`, and paths fitted to width with the basename kept. Trace records now carry per-call `ms` and non-zero `exitCode`.
+- Guest programs run in a warm worker thread. A hard timeout or abort now terminates synchronous loops (`while (true) {}`), `process.exit()` only ends the program, and `maxHeapMb` (V8 `resourceLimits` plus a process-RSS watchdog for Bun) stops memory blow-ups — none of these can take the host down anymore. Warm-worker overhead is ~0.1ms per program and ~20µs per `nova.call`.
+- Result text is a compact JS literal (`ok 12ms` header, unquoted keys, no separator whitespace, one item per line only past 120 columns): ~43% fewer tokens than the previous pretty JSON. Logs appear under `--- logs` only when present.
+- `maxReturnChars` default lowered from 200000 to 32000.
+- Return values that JSON cannot express are rendered instead of collapsing to `[object Object]`: circular references, `Map`, `Set`, `BigInt`, `Error`, functions, typed arrays.
+- A program that finishes without a `return` statement says so instead of printing `null`.
+- Guest runtime errors include `(line:col)` on Node.
+
+- Errors teach: unknown tool names get `Did you mean "read"?` (OSA distance over callable tools), and budget, timeout, missing-file, path-escape, and edit-mismatch errors name the exact fix.
+- `nova.call` envelopes are lean when returned: `details` is reachable but non-enumerable and `truncated:false` is omitted (53 → 13 tokens for a dumped `bash` result). Tool description rewritten as signatures (327 → 252 prompt tokens per turn, more information).
+- Internals: `host-bridge.js` split into `vfs.js`, `patch.js`, `workspace.js`; `format.js` holds the text-shaping kernel so the UI no longer imports result packaging. Every function is at CC ≤ 10 (was: 14 above, max 43).
+
+### Fixed
+
+- `read([...paths])` is a single batched host call instead of one call per path, so reading 300 files no longer exhausts `maxBridgeCalls`; the native batch adapter also returned `null` items.
+- Result truncation no longer splits a surrogate pair, which produced a lone surrogate the model API rejects.
+- `bash` failures throw `command failed (exit N): <cmd>` plus output instead of a JSON details blob; stdout/stderr are joined without a blank line; truncated output is marked.
+- `read("dir")` reports a directory instead of silently running a concept search.
+- The VFS read cache is cleared at the start of every program, so files edited outside supernova are never read stale.
+- Arrow programs with default parameters containing parentheses or a leading comment are recognized and executed instead of silently returning `null`.
+- `snap` ranks deterministically (`rg --files` order is sorted) and its content-grep fallback is case-insensitive, so `quasar handshake` finds `exactQuasarHandshake` instead of returning the first listed file.
+
+## [0.0.7] - 2026-09-03
+
+### Fixed
+
+- `bash` / `exec` run through `bash -c` (and strip a wrapping quote pair), so `git status` and `echo $PATH` are not looked up as a single binary name.
+- `nova.search` / `nova.describe` return promises, so `.catch()` in guest programs works.
+
 ## [0.0.6] - 2026-09-03
 
 ### Changed

package/README.md

@@ -25,7 +25,7 @@ Load **before** other tool-owning packages so `registerTool` capture works. Rest
 | Parallel reads | Ad hoc | `callMany` Auto / `parallel()` |
 | Hosts | Separate packages | Same tarball for Pi **and** OMP |
 
-Guest code is an in-process `AsyncFunction` (same trust class as host `bash`) — not an OS/VM sandbox. Tool calls still go through `nova.call`.
+Guest code runs as an `AsyncFunction` in a worker thread (same trust class as host `bash`) — not an OS/VM sandbox. Tool calls go through `nova.call` RPC to the host thread; a hard timeout, abort, `process.exit`, or a memory blow-up terminates the worker without touching the harness.
 
 ---
 
@@ -46,21 +46,24 @@ async () => {
 }
 ```
 
-Globals: `nova` / `tools`, `parallel`, `pipeline`, `console`, plus shorthand `read`, `write`, `edit`, `patch`, `surface`, `snap`, `bash`, and `exec`.
+Globals: `nova` / `tools`, `parallel`, `pipeline`, `console`, plus shorthand `read` (path or path array), `write`, `edit`, `patch`, `surface`, `snap`, `bash`, and `exec`.
 
-Unified Pi/OMP card with bounded mutation diffs visible while collapsed:
+The returned value is rendered as a compact JS literal (unquoted keys, one item per line only when a container exceeds 120 columns) and capped at `maxReturnChars`. Strings are returned raw. This costs ~43% fewer tokens than pretty JSON — return small shaped values, not raw file dumps.
+
+Unified Pi/OMP card — one aligned row per call (status · tool · duration · target) with bounded mutation diffs:
 
 ```text
-╭─── nova: 2 calls · 84ms ───────────────────────────────╮
-│ ├─ ✓ read    packages/pi-supernova/host-bridge.js       │
-│ │                                                       │
-│ └─ ✓ edit   +1/-1 packages/pi-supernova/diff.js         │
-│       -143 │ - const oldValue = before;                 │
-│       +143 │ + const newValue = after;                  │
-╰─────────────────────────────────────────────────────────╯
+╭─── nova: 4 calls · 6.9s ─────────────────────────────────────╮
+│ ✓ bash      6.2s  python3 - <<'EOF' …+3 lines                 │
+│ × bash     120ms  exit 3  pytest -q                           │
+│ ✓ read       3ms  packages/pi-supernova/host-bridge.js        │
+│ ✓ edit       4ms  +1/-1 src/a.ts                              │
+│    -143 │ - const oldValue = before;                          │
+│    +143 │ + const newValue = after;                           │
+╰───────────────────────────────────────────────────────────────╯
 ```
 
-Collapsed cards show bounded edit/write/patch hunks immediately. Press Enter for a larger hunk budget, logs, and the returned value.
+Multi-line commands show their first line plus a hidden-line count. Press Enter for a larger hunk budget, the full returned value, and logs.
 
 ---
 
@@ -74,7 +77,7 @@ Collapsed cards show bounded edit/write/patch hunks immediately. Press Enter for
 | `nova.callMany([{name,args}])` | Auto parallel wave — iterable array with `.mode` / `.results` |
 | `nova.surface(path)` | Structural outline for a source file |
 | `nova.snap(query, searchRoot?)` | Most relevant source path, line, signature, confidence, and context |
-| `nova.has(name)` | Whether a catalog or native tool is callable |
+| `nova.has(name)` | Whether a catalog or native tool is callable (sync) |
 | `parallel(thunks)` / `pipeline(items, …stages)` | Raw `Promise.all` helpers |
 | `nova.speculate(fn)` | Counterfactual branch (rollback / commit) |
 
@@ -93,12 +96,15 @@ Optional `~/.pi/agent/supernova.json` or `~/.omp/agent/supernova.json`
   "maxCodeChars": 48000,
   "maxBridgeCalls": 256,
   "maxCallResultChars": 65536,
-  "maxReturnChars": 200000,
+  "maxReturnChars": 32000,
+  "maxHeapMb": 512,
   "maxSearchResults": 12,
   "spillDir": null
 }
 ```
 
+`maxHeapMb` caps the guest worker heap (V8 `resourceLimits` on Node) and arms a process-RSS watchdog that terminates a runaway program on both Node and Bun.
+
 Defaults also set `excludeTools` (includes `supernova` and DCE helpers). An empty `"excludeTools": []` **replaces** those defaults — omit the key unless you mean that.
 
 Slash: `/supernova` — catalog size + captured executors.
@@ -126,7 +132,7 @@ Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
 
 | Symptom | Fix |
 |---------|-----|
-| `no executor for tool "…"` | Install supernova **first**; restart; `/supernova` |
+| `unknown tool "…"` | Follow the `Did you mean` hint, or `nova.search("")`; for host tools install supernova **first**; restart; `/supernova` |
 | `Rendered line exceeds terminal width` | ≥0.0.1 and restart so `render.js` reloads |
 | `callMany` / not iterable | ≥0.0.1 — return is an array with `.mode` / `.results` |
 | Extension missing on OMP | `omp install npm:pi-supernova` (needs `"omp".extensions`) |
@@ -135,7 +141,8 @@ Pair with DCE last if you use it: `omp install npm:pi-deferred-context-engine`.
 
 ## Limitations
 
-- Guest JS is **unsandboxed**. Adapter path jails are not a boundary against `import("node:fs")`.
+- Guest JS is **unsandboxed**. Adapter path jails are not a boundary against `import("node:fs")`. The worker only contains hangs, exits, and memory — not intent.
+- Guest error messages carry `(line:col)` on Node; Bun's engine does not expose guest-relative positions.
 - `bash` / mutating tools flush speculative writes (transaction barrier); error rollback cannot undo that.
 - Pre-1.0 package — APIs and TUI may still evolve between minor releases.
 

package/bottleneck.js

@@ -1,42 +1,13 @@
-
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { isString, isObject } from "./decode.js";
-
-export function truncateChars(text, maxChars, label = "value") {
-  const normalized = isString(text) ? text : String(text ?? "");
-  const numericLimit = Number(maxChars);
-  const limit = Number.isFinite(numericLimit) ? Math.max(0, Math.floor(numericLimit)) : numericLimit === Infinity ? normalized.length : 0;
-  if (normalized.length <= limit) return { text: normalized, truncated: false };
-  if (limit <= 100) {
-    return {
-      text: normalized.slice(0, limit),
-      truncated: true,
-      originalChars: normalized.length,
-    };
-  }
-  const head = Math.floor(limit * 0.7);
-  let tail = Math.max(0, limit - head);
-  let marker = "";
-  let previousTail = -1;
-  while (tail !== previousTail) {
-    previousTail = tail;
-    const omitted = normalized.length - head - tail;
-    marker = `\n…[${label} truncated ${omitted} chars]…\n`;
-    tail = Math.max(0, limit - head - marker.length);
-  }
-  return {
-    text: normalized.slice(0, head) + marker + (tail > 0 ? normalized.slice(-tail) : ""),
-    truncated: true,
-    originalChars: normalized.length,
-  };
-}
+import { truncateChars, formatValue } from "./format.js";
 
 export function serializeBounded(value, maxChars, label = "value") {
   let serialized;
   try {
-    serialized = isString(value) ? value : JSON.stringify(value, null, 2);
+    serialized = isString(value) ? value : JSON.stringify(value);
   } catch {
     serialized = String(value);
   }
@@ -79,13 +50,28 @@ function maybeSpill(cappedText, fullText, config) {
   }
 }
 
+function batchItems(details, maxChars) {
+  if (!isObject(details) || details.batch !== true) return undefined;
+  if (!Array.isArray(details.items)) return undefined;
+  return details.items.map((item) => truncateChars(item, maxChars, "host-result").text);
+}
+
+function spillSuffix(capped, text, config) {
+  const spill = maybeSpill(capped.text, text, config);
+  if (!spill?.pointer) return { spill, value: capped.text };
+  return { spill, value: `${capped.text}\n\n[full output spilled to ${spill.pointer}]` };
+}
+
 export function packageHostResult(raw, config) {
   const maxChars = config.maxCallResultChars ?? 65536;
   const isError = isObject(raw) && raw.isError === true;
   const details = isObject(raw) ? raw.details : undefined;
   const upstreamTruncated = isObject(details) && details.outputTruncated === true;
   const text = extractRawString(raw, maxChars);
-  const summarizedDetails = details === undefined ? undefined : summarizeDetails(details, 2000);
+  const items = batchItems(details, maxChars);
+  // Batch items travel as their own field; keep the details summary small and parseable.
+  const summarizedDetails =
+    details === undefined ? undefined : summarizeDetails(items ? { ...details, items: undefined } : details, 2000);
 
   const capped = truncateChars(text, maxChars, "host-result");
   if (!capped.truncated) {
@@ -94,13 +80,11 @@ export function packageHostResult(raw, config) {
       value: capped.text,
       truncated: upstreamTruncated,
       details: summarizedDetails,
+      items,
     };
   }
 
-  const spill = maybeSpill(capped.text, text, config);
-  const value = spill?.pointer
-    ? `${capped.text}\n\n[full output spilled to ${spill.pointer}]`
-    : capped.text;
+  const { spill, value } = spillSuffix(capped, text, config);
 
   return {
     ok: !isError,
@@ -109,24 +93,31 @@ export function packageHostResult(raw, config) {
     originalChars: capped.originalChars,
     spill: spill?.pointer,
     details: summarizedDetails,
+    items,
   };
 }
 
-export function packageFinalReturn(value, logs, config) {
-  const maxReturn = config.maxReturnChars ?? 200000;
-  const serialized = serializeBounded(value, maxReturn, "return");
+function clipLogs(logs, config) {
   const logLines = Array.isArray(logs) ? logs : [];
   const maxLogLines = config.maxLogLines ?? 100;
   const maxLogLineChars = config.maxLogLineChars ?? 4096;
   const clippedLogs = logLines.slice(0, maxLogLines).map((line) => {
     const s = isString(line) ? line : String(line);
-    return s.length > maxLogLineChars ? s.slice(0, maxLogLineChars) + "…" : s;
+    if (s.length <= maxLogLineChars) return s;
+    return s.slice(0, maxLogLineChars) + "…";
   });
+  return { clippedLogs, logTruncated: logLines.length > maxLogLines };
+}
+
+export function packageFinalReturn(value, logs, config) {
+  const maxReturn = config.maxReturnChars ?? 32000;
+  const serialized = truncateChars(isString(value) ? value.replace(/\n+$/, "") : formatValue(value), maxReturn, "return");
+  const { clippedLogs, logTruncated } = clipLogs(logs, config);
   return {
     returnValue: serialized.truncated ? serialized.text : value,
     returnText: serialized.text,
     returnTruncated: serialized.truncated,
     logs: clippedLogs,
-    logTruncated: logLines.length > maxLogLines,
+    logTruncated,
   };
 }

package/catalog.js

@@ -82,6 +82,13 @@ export function mergeNativeToolDefinitions(tools, capturedNames = []) {
   return merged;
 }
 
+function sourcePathOf(tool) {
+  if (tool.sourceInfo && isString(tool.sourceInfo.path)) return tool.sourceInfo.path;
+  if (isString(tool.extensionPath)) return tool.extensionPath;
+  if (isString(tool.sourcePath)) return tool.sourcePath;
+  return undefined;
+}
+
 function normalizeTool(tool) {
   if (!tool || !isObject(tool)) return null;
   const name = isString(tool.name) ? tool.name : "";
@@ -93,14 +100,7 @@ function normalizeTool(tool) {
     description,
     descLower: description.toLowerCase(),
     parameters: tool.parameters,
-    sourcePath:
-      tool.sourceInfo && isString(tool.sourceInfo.path)
-        ? tool.sourceInfo.path
-        : isString(tool.extensionPath)
-          ? tool.extensionPath
-          : isString(tool.sourcePath)
-            ? tool.sourcePath
-            : undefined,
+    sourcePath: sourcePathOf(tool),
   };
 }
 
@@ -153,6 +153,15 @@ export function searchCatalog(catalog, query, limit = 12) {
   return scored.slice(0, Math.max(1, limit)).map(({ score: _s, ...hit }) => hit);
 }
 
+function fieldSummary(key, schema, required) {
+  const s = schema && isObject(schema) ? schema : {};
+  return {
+    type: s.type || (Array.isArray(s.anyOf) ? "union" : "unknown"),
+    required: required.has(key),
+    description: isString(s.description) ? s.description.slice(0, 120) : undefined,
+  };
+}
+
 function schemaSummary(parameters) {
   if (!parameters || !isObject(parameters)) return { type: "unknown" };
   const props = parameters.properties;
@@ -165,20 +174,57 @@ function schemaSummary(parameters) {
   const required = new Set(Array.isArray(parameters.required) ? parameters.required : []);
   const fields = {};
   for (const [key, schema] of Object.entries(props)) {
-    const s = schema && isObject(schema) ? schema : {};
-    fields[key] = {
-      type: s.type || (Array.isArray(s.anyOf) ? "union" : "unknown"),
-      required: required.has(key),
-      description: isString(s.description) ? s.description.slice(0, 120) : undefined,
-    };
+    fields[key] = fieldSummary(key, schema, required);
   }
   return { type: "object", fields };
 }
 
+/** Optimal string alignment distance: insert/delete/substitute/adjacent-transpose cost 1. */
+function editDistance(a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...new Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) rows[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let best = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) best = Math.min(best, rows[i - 2][j - 2] + 1);
+      rows[i][j] = best;
+    }
+  }
+  return rows[a.length][b.length];
+}
+
+/** Closest tool names for a mistyped name: substring hits first, then a length-scaled edit distance. */
+export function suggestNames(name, candidates, limit = 3) {
+  const needle = String(name || "").toLowerCase();
+  if (!needle) return [];
+  const maxDistance = Math.max(1, Math.floor(needle.length / 3));
+  const scored = [];
+  for (const candidate of candidates) {
+    const lower = candidate.toLowerCase();
+    if (lower === needle) continue;
+    const distance = lower.includes(needle) || needle.includes(lower) ? 1 : editDistance(needle, lower);
+    if (distance <= maxDistance) scored.push({ candidate, distance });
+  }
+  scored.sort(
+    (a, b) =>
+      a.distance - b.distance ||
+      Math.abs(a.candidate.length - needle.length) - Math.abs(b.candidate.length - needle.length) ||
+      a.candidate.localeCompare(b.candidate),
+  );
+  return scored.slice(0, limit).map((s) => s.candidate);
+}
+
+export function unknownToolMessage(name, candidates) {
+  const close = suggestNames(name, candidates);
+  const hint = close.length ? ` Did you mean ${close.map((c) => JSON.stringify(c)).join(", ")}?` : "";
+  return `unknown tool "${name}".${hint} Use nova.search("") to list every callable tool.`;
+}
+
 export function describeTool(catalog, name) {
   const row = catalog.find((t) => t.name === name);
   if (!row) {
-    return { ok: false, error: `unknown tool: ${name}` };
+    return { ok: false, error: unknownToolMessage(name, catalog.map((t) => t.name)) };
   }
   if (!row._described) {
     row._described = {

package/config.default.json

@@ -3,7 +3,8 @@
   "maxCodeChars": 48000,
   "maxBridgeCalls": 256,
   "maxCallResultChars": 65536,
-  "maxReturnChars": 200000,
+  "maxReturnChars": 32000,
+  "maxHeapMb": 512,
   "maxLogLines": 100,
   "maxLogLineChars": 4096,
   "maxSearchResults": 12,

package/config.js

@@ -1,4 +1,3 @@
-
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -18,8 +17,24 @@ const POSITIVE_INTEGER_KEYS = new Set([
   "maxReturnChars",
   "maxLogLineChars",
   "maxSearchResults",
+  "maxHeapMb",
 ]);
 
+const VALIDATORS = {
+  positiveInt: (v) => Number.isInteger(v) && v > 0,
+  nonNegativeInt: (v) => Number.isInteger(v) && v >= 0,
+  stringArray: (v) => Array.isArray(v) && v.every(isString),
+  spillDir: (v) => v === null || (isString(v) && v.length > 0),
+};
+
+const KEY_VALIDATOR = new Map();
+for (const k of POSITIVE_INTEGER_KEYS) KEY_VALIDATOR.set(k, VALIDATORS.positiveInt);
+for (const k of NONNEGATIVE_INTEGER_KEYS) KEY_VALIDATOR.set(k, VALIDATORS.nonNegativeInt);
+for (const k of Object.keys(DEFAULTS)) {
+  if (Array.isArray(DEFAULTS[k])) KEY_VALIDATOR.set(k, VALIDATORS.stringArray);
+}
+KEY_VALIDATOR.set("spillDir", VALIDATORS.spillDir);
+
 export function packageDefaults() {
   return structuredClone(DEFAULTS);
 }
@@ -53,15 +68,9 @@ export function mergeConfig(base, overlay) {
   const out = { ...base };
   for (const [key, value] of Object.entries(overlay)) {
     if (!KNOWN_KEYS.has(key)) continue;
-    if (POSITIVE_INTEGER_KEYS.has(key)) {
-      if (Number.isInteger(value) && value > 0) out[key] = value;
-    } else if (NONNEGATIVE_INTEGER_KEYS.has(key)) {
-      if (Number.isInteger(value) && value >= 0) out[key] = value;
-    } else if (Array.isArray(base[key])) {
-      if (Array.isArray(value) && value.every(isString)) out[key] = value.slice();
-    } else if (key === "spillDir") {
-      if (value === null || (isString(value) && value.length > 0)) out[key] = value;
-    }
+    const validate = KEY_VALIDATOR.get(key);
+    if (!validate) continue;
+    if (validate(value)) out[key] = Array.isArray(value) ? value.slice() : value;
   }
   return out;
 }

package/diff.js

@@ -56,6 +56,12 @@ export function buildMultiEditDiff(filePath, originalText, replacements) {
   };
 }
 
+const PATCH_LINE_KINDS = { "-": "remove", "+": "add", " ": "context" };
+
+function classifyPatchLine(line) {
+  return PATCH_LINE_KINDS[line[0]] || null;
+}
+
 export function buildPatchDiff(filePath, patchText) {
   const patchLines = isString(patchText) ? patchText.replace(/\r\n/g, "\n").split("\n") : [];
   const lines = [];
@@ -66,7 +72,7 @@ export function buildPatchDiff(filePath, patchText) {
   let inHunk = false;
 
   for (const patchLine of patchLines) {
-    const headerMatch = /^@@\s+-(\d+)(?:,\d+)?\s+\+(\d+)/.exec(patchLine);
+    const headerMatch = (/^@@\s+-(\d+)(?:,\d+)?\s+\+(\d+)/).exec(patchLine);
     if (headerMatch) {
       oldLineNum = Number(headerMatch[1]);
       newLineNum = Number(headerMatch[2]);
@@ -74,15 +80,17 @@ export function buildPatchDiff(filePath, patchText) {
       continue;
     }
     if (!inHunk || patchLine.startsWith("\\")) continue;
-    if (patchLine.startsWith("-")) {
+    const kind = classifyPatchLine(patchLine);
+    if (!kind) continue;
+    if (kind === "remove") {
       removed += 1;
       lines.push({ type: "remove", lineNum: oldLineNum, text: patchLine.slice(1) });
       oldLineNum += 1;
-    } else if (patchLine.startsWith("+")) {
+    } else if (kind === "add") {
       added += 1;
       lines.push({ type: "add", lineNum: newLineNum, text: patchLine.slice(1) });
       newLineNum += 1;
-    } else if (patchLine.startsWith(" ")) {
+    } else {
       lines.push({ type: "context", lineNum: newLineNum, text: patchLine.slice(1) });
       oldLineNum += 1;
       newLineNum += 1;

package/format.js

@@ -0,0 +1,95 @@
+import { isString } from "./decode.js";
+
+export function truncateChars(text, maxChars, label = "value") {
+  const normalized = isString(text) ? text : String(text ?? "");
+  const numericLimit = Number(maxChars);
+  const limit = Number.isFinite(numericLimit) ? Math.max(0, Math.floor(numericLimit)) : numericLimit === Infinity ? normalized.length : 0;
+  if (normalized.length <= limit) return { text: normalized, truncated: false };
+  if (limit <= 100) {
+    return {
+      text: normalized.slice(0, headEnd(normalized, limit)),
+      truncated: true,
+      originalChars: normalized.length,
+    };
+  }
+  const head = headEnd(normalized, Math.floor(limit * 0.7));
+  let tail = Math.max(0, limit - head);
+  let marker = "";
+  let previousTail = -1;
+  while (tail !== previousTail) {
+    previousTail = tail;
+    const omitted = normalized.length - head - tail;
+    marker = `\n…[${label} truncated ${omitted} chars]…\n`;
+    tail = Math.max(0, limit - head - marker.length);
+  }
+  const tailStart = tailStartIndex(normalized, tail);
+  return {
+    text: normalized.slice(0, head) + marker + normalized.slice(tailStart),
+    truncated: true,
+    originalChars: normalized.length,
+  };
+}
+
+// Lone surrogates in a tool result make the message invalid UTF-8 at the API
+// boundary, so a cut must never split a surrogate pair.
+function headEnd(text, end) {
+  const code = text.charCodeAt(end - 1);
+  return code >= 0xd800 && code <= 0xdbff ? end - 1 : end;
+}
+
+function tailStartIndex(text, tail) {
+  if (tail <= 0) return text.length;
+  const start = text.length - tail;
+  const code = text.charCodeAt(start);
+  return code >= 0xdc00 && code <= 0xdfff ? start + 1 : start;
+}
+
+const IDENT_KEY = /^[A-Za-z_$][\w$]*$/;
+const FORMAT_WIDTH = 120;
+
+function formatKey(key) {
+  return IDENT_KEY.test(key) ? key : JSON.stringify(key);
+}
+
+function formatPrimitive(value) {
+  if (value === undefined) return "undefined";
+  if (typeof value === "number" && !Number.isFinite(value)) return String(value);
+  return JSON.stringify(value) ?? String(value);
+}
+
+function formatFlatList(value) {
+  if (value.length === 0) return "[]";
+  let out = "[";
+  for (let i = 0; i < value.length; i++) out += (i ? "," : "") + formatFlat(value[i] === undefined ? null : value[i]);
+  return out + "]";
+}
+
+function formatFlat(value) {
+  if (value === null || typeof value !== "object") return formatPrimitive(value);
+  if (Array.isArray(value)) return formatFlatList(value);
+  let out = "";
+  for (const key of Object.keys(value)) {
+    if (value[key] === undefined) continue;
+    out += (out ? "," : "{") + formatKey(key) + ":" + formatFlat(value[key]);
+  }
+  return out ? out + "}" : "{}";
+}
+
+/**
+ * Compact JS-literal rendering for the model: containers that fit in FORMAT_WIDTH
+ * stay on one line with no separator whitespace, identifier keys are unquoted,
+ * indent is one space. Whitespace is what costs tokens: this measures ~43% fewer
+ * than JSON.stringify(value, null, 2) on typical shaped returns (gpt-tokenizer).
+ */
+export function formatValue(value, indent = "", width = FORMAT_WIDTH) {
+  const flat = formatFlat(value);
+  if (value === null || typeof value !== "object" || flat.length + indent.length <= width) return flat;
+  const pad = indent + " ";
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return "[\n" + value.map((item) => pad + formatValue(item === undefined ? null : item, pad, width)).join(",\n") + "\n" + indent + "]";
+  }
+  const keys = Object.keys(value).filter((key) => value[key] !== undefined);
+  if (keys.length === 0) return "{}";
+  return "{\n" + keys.map((key) => pad + formatKey(key) + ":" + formatValue(value[key], pad, width)).join(",\n") + "\n" + indent + "}";
+}