@nathapp/nax-agent 0.1.0

package/dist/tools/spill.js

@@ -0,0 +1,251 @@
+/**
+ * Spill writer and the model-facing composition of the truncation policy
+ * (US-003).
+ *
+ * The policy itself (`truncateForModel`) decides *what* the model may see; this
+ * module decides what happens to the rest. On truncation only, the untruncated
+ * body — up to `READ_CEILING` — is written under the scratchpad at
+ * `spill/<toolName>-<callId>.txt`, and the marker naming that path and both byte
+ * counts is appended to the content the model receives. `writeSpill` keeps
+ * returning the scratchpad-relative spelling; `applyModelTruncationPolicy`
+ * turns it into the path the marker names — root-relative
+ * (`.nax/scratchpad/spill/...`) by default, so the session's own tools and
+ * shell can open it verbatim, or absolute when the root is not the session's
+ * shell root. The spilled body stays recoverable with `offset`/`limit`.
+ *
+ * The composition lives here, beside the writer, because the marker and the
+ * spill are one decision: the path may only appear in the marker when the write
+ * actually succeeded. Both transports reach it — the coding-tool runtime applies
+ * it to every genuine tool result, and the native session applies it at the
+ * `after_tool` chokepoint — so there is exactly one implementation of the
+ * model-facing cap rather than one per tool.
+ *
+ * Filesystem calls are injectable (`_spillDeps`), following `_scratchpadWipeDeps`
+ * in src/execution/lifecycle/scratchpad-wipe.ts, and writes go through
+ * asynchronous Node filesystem APIs.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { SCRATCHPAD_DIR } from "./scratchpad.js";
+import { capModelLine, cutToByteCap, MODEL_MAX_BYTES, MODEL_MAX_LINE_CHARS, MODEL_MAX_LINES, READ_CEILING, splitModelLines, truncateForModel, truncationDirectionFor, } from "./truncate.js";
+/** Directory under the scratchpad that holds spilled tool output. */
+export const SPILL_DIR = "spill";
+/** Injectable filesystem seam (see docs/architecture/conventions.md §2). */
+export const _spillDeps = {
+    mkdir: (path) => mkdir(path, { recursive: true }),
+    writeFile: async (path, data) => {
+        await writeFile(path, data, "utf8");
+        return Buffer.byteLength(data);
+    },
+};
+/** A tool name or call id can only contribute path-safe characters. */
+function fileSafe(value) {
+    return value.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/** `spill/<toolName>-<callId>.txt`, relative to the scratchpad directory. */
+export function spillRelativePath(toolName, callId) {
+    return `${SPILL_DIR}/${fileSafe(toolName)}-${fileSafe(callId)}.txt`;
+}
+/**
+ * The spill file's body: the untruncated output, bounded by `READ_CEILING`.
+ *
+ * A body past the ceiling is itself cut, and the cut is recorded on the file's
+ * own last line: a spill that silently ends mid-output is indistinguishable
+ * from one that ends where the tool did, and the model is being told it holds
+ * the whole thing. The note is paid for out of the ceiling, never added on top
+ * of it — the file is the tool-layer bound, so it must not exceed it either.
+ */
+function spillBody(body) {
+    const total = Buffer.byteLength(body, "utf8");
+    if (total <= READ_CEILING)
+        return body;
+    // Two passes because the note quotes how much was kept, which depends on the
+    // note's own length. The first pass sizes the note with the largest number it
+    // could report (the ceiling), so the second can only make it shorter.
+    const noteOf = (kept) => `\n... [spill incomplete: showing ${kept} of ${total} bytes]`;
+    const firstNote = noteOf(READ_CEILING);
+    const kept = cutToByteCap(body, READ_CEILING - Buffer.byteLength(firstNote, "utf8"));
+    return `${kept}${noteOf(Buffer.byteLength(kept, "utf8"))}`;
+}
+/**
+ * Write the untruncated body under the scratchpad and return its path relative
+ * to the scratchpad, or `undefined` when the write failed.
+ *
+ * Failure is fail-open by contract: the caller still delivers the truncated
+ * result. What it must not do is name a file that is not there, which is why
+ * this returns the path rather than a boolean.
+ */
+export async function writeSpill(req) {
+    const relative = spillRelativePath(req.toolName, req.callId);
+    const target = join(req.root, SCRATCHPAD_DIR, relative);
+    try {
+        await _spillDeps.mkdir(dirname(target));
+        await _spillDeps.writeFile(target, spillBody(req.body));
+        return relative;
+    }
+    catch (err) {
+        getSafeLogger()?.warn("tools", "[spill] could not write the spilled tool result", {
+            tool: req.toolName,
+            path: target,
+            error: errorMessage(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * The marker shapes, widest first. A narrower shape is used when the wider one
+ * cannot fit the byte budget — a 40 000-byte ceiling fits a marker naming the
+ * spill path, a 32-byte one fits barely more than the word "truncated". The
+ * spill path is simply absent from a shape that has no room for it, which is
+ * also the shape failure takes: a marker never names a file that is not there.
+ */
+function markerShapes(originalBytes, spillPath) {
+    const shapes = [];
+    if (spillPath !== undefined) {
+        shapes.push((d) => `... [truncated: full output at ${spillPath} (open with Read or ScratchpadRead); showing ${d} of ${originalBytes} bytes]`);
+    }
+    shapes.push((d) => `... [truncated: showing ${d} of ${originalBytes} bytes]`);
+    shapes.push(() => "... [truncated]");
+    return shapes;
+}
+/** Lines `head` may keep once the marker occupies one of them. */
+function trimToLineBudget(head, maxLines) {
+    const lines = splitModelLines(head);
+    if (lines.length <= maxLines)
+        return head;
+    return lines.slice(0, maxLines).join("\n");
+}
+/** A marker line, plus the newline that puts it on one. */
+function renderedMarkerBytes(render, deliveredBytes) {
+    return Buffer.byteLength(render(deliveredBytes), "utf8") + 1;
+}
+/**
+ * Compose the head-direction result: the policy's content, then the marker on
+ * its own last line. The marker is inside the byte and line budgets, never
+ * appended past them.
+ */
+function composeHead(content, originalBytes, byteCap, spillPath) {
+    for (const render of markerShapes(originalBytes, spillPath)) {
+        const bodyBudget = byteCap - renderedMarkerBytes(render, originalBytes);
+        if (bodyBudget < 0)
+            continue;
+        const head = trimToLineBudget(cutToByteCap(content, bodyBudget), MODEL_MAX_LINES - 1);
+        return `${head}\n${render(Buffer.byteLength(head, "utf8"))}`;
+    }
+    return cutToByteCap(content, byteCap);
+}
+/**
+ * Compose the tail-with-first-line result: the body's first line, the marker,
+ * then the tail.
+ *
+ * The marker sits between them rather than after the tail because the tail is
+ * the whole point of the direction — a marker appended last would push the
+ * final stderr lines out of view, which is the failure the direction exists to
+ * prevent. Command output is kept line-wise, and a line too large for the
+ * remaining budget is skipped rather than cut: one 160 KB stdout blob must not
+ * spend the entire budget on itself and evict the short lines that follow it.
+ */
+function composeTail(body, content, originalBytes, byteCap, spillPath) {
+    const lines = splitModelLines(body);
+    const fullFirstLine = content.split("\n")[0] ?? "";
+    for (const render of markerShapes(originalBytes, spillPath)) {
+        // One byte for the newline after the first line, then the marker.
+        const forFirstLine = byteCap - Buffer.byteLength(render(originalBytes), "utf8") - 1;
+        if (forFirstLine < 0)
+            continue;
+        const firstLine = Buffer.byteLength(fullFirstLine, "utf8") > forFirstLine
+            ? cutToByteCap(fullFirstLine, forFirstLine)
+            : fullFirstLine;
+        // One more byte for the newline that opens the tail.
+        const tailBudget = forFirstLine - Buffer.byteLength(firstLine, "utf8") - 1;
+        const tail = tailBudget < 0 ? "" : selectTail(lines, tailBudget);
+        const firstLineBytes = Buffer.byteLength(firstLine, "utf8");
+        const tailBytes = Buffer.byteLength(tail, "utf8");
+        // The delivered count is the body text the model can read back: the retained
+        // first line, the body's own newline that still separates it from the tail,
+        // and the tail. The newline that puts the marker on a line of its own is not
+        // a body byte — here it is the one that opens the tail, and with no tail
+        // retained there is no body byte after the first line at all. `composeHead`
+        // reports its head with no marker-line byte either; counting one only here
+        // made the same marker mean a different width per tool, and reported one
+        // byte more than the model can actually read.
+        const delivered = tail === "" ? firstLineBytes : firstLineBytes + 1 + tailBytes;
+        const marker = render(delivered);
+        return tail === "" ? `${firstLine}\n${marker}` : `${firstLine}\n${marker}\n${tail}`;
+    }
+    return cutToByteCap(content, byteCap);
+}
+/**
+ * The trailing lines that fit `budget` bytes, taken from the end of the body.
+ *
+ * A line whose own length exceeds what is left is skipped, not truncated: the
+ * alternative spends the whole budget inside that one line and returns a slice
+ * of it in place of the lines that carry the signal (an echoed command, the
+ * error text). Each line kept is still shaped by the per-line cap.
+ */
+function selectTail(lines, budget) {
+    const kept = [];
+    let remaining = budget;
+    // The first line is retained separately, so the walk starts below it, and the
+    // first line plus the marker occupy one line each of the line budget.
+    for (let i = lines.length - 1; i >= 1 && kept.length < MODEL_MAX_LINES - 2; i -= 1) {
+        const line = lines[i] ?? "";
+        const cost = Buffer.byteLength(line, "utf8") + (kept.length === 0 ? 0 : 1);
+        if (cost > remaining)
+            continue;
+        kept.unshift(capModelLine(line, MODEL_MAX_LINE_CHARS));
+        remaining -= cost;
+    }
+    return kept.join("\n");
+}
+/**
+ * Apply the model-facing truncation policy to one tool result.
+ *
+ * Returns the body unchanged when it is within every cap — no spill, no marker.
+ * Otherwise the shared policy shapes the content, the untruncated body is
+ * spilled when a root is known, and the marker naming both byte counts and the
+ * spill path is composed inside the same ceilings the body obeys.
+ *
+ * The byte ceiling is the caller's `maxBytes`, defaulting to `MODEL_MAX_BYTES`;
+ * the line ceilings always come from the shared policy's constants.
+ */
+export async function applyModelTruncationPolicy(body, opts) {
+    const direction = truncationDirectionFor(opts.toolName);
+    const originalBytes = Buffer.byteLength(body, "utf8");
+    const byteCap = Math.max(0, opts.maxBytes ?? MODEL_MAX_BYTES);
+    // The one call to the shared policy: it applies the per-line cap, the
+    // line-count cap and its own byte cap, and tells us whether anything was cut.
+    const shaped = truncateForModel(body, { direction });
+    if (!shaped.truncated && originalBytes <= byteCap)
+        return body;
+    const spillPath = await spillMarkerPath(opts, body);
+    return direction === "head"
+        ? composeHead(shaped.content, originalBytes, byteCap, spillPath)
+        : composeTail(body, shaped.content, originalBytes, byteCap, spillPath);
+}
+/**
+ * Write the body and return the path as the marker should spell it, or
+ * `undefined` when there is no root or the write failed. The spill writer
+ * keeps returning the scratchpad-relative `spill/<Tool>-<callId>.txt`; this is
+ * the one place that turns it into the model-facing spelling, so the two
+ * composers receive a finished path and stay unaware of the style.
+ *
+ * The path appears whenever the wide marker shape fits the byte budget, for a
+ * body of any size: AC1/AC2/AC7/AC8 name the spill path for every truncated
+ * result, and the marker's job is to point at the file nax wrote for this call.
+ * A body past `READ_CEILING` is written capped (see `spillBody`) — that is the
+ * spill writer's own long-standing bound, pinned by `spill-recovery.test.ts`
+ * AC9 — and the cap is recorded on the file's last line rather than hidden.
+ */
+async function spillMarkerPath(opts, body) {
+    if (opts.root === undefined)
+        return undefined;
+    const relative = await writeSpill({ root: opts.root, toolName: opts.toolName, callId: opts.callId, body });
+    if (relative === undefined)
+        return undefined;
+    return opts.spillPathStyle === "absolute"
+        ? join(opts.root, SCRATCHPAD_DIR, relative)
+        : `${SCRATCHPAD_DIR}/${relative}`;
+}

package/dist/tools/tool-audit.d.ts

@@ -0,0 +1,171 @@
+import type { SandboxRecord } from "../sandbox/index.ts";
+export interface ToolCallRecord {
+    readonly tool: string;
+    readonly outcome: "ok" | "error" | "denied" | "denied:ask";
+    readonly breach?: boolean;
+    readonly input: Record<string, unknown>;
+    readonly resultBytes: number;
+    readonly storyId?: string;
+    readonly at: string;
+    /**
+     * Why a "denied" outcome was refused. runtime.ts's log() computes this for
+     * the console logger (under the `error` key) but used to drop it before it
+     * reached this sink, so a denied row's `error` field read null and the
+     * refusal reason was unrecoverable -- the exact gap this field closes.
+     */
+    readonly reason?: string;
+    /**
+     * The argv that actually ran, after normalization (workspace scoping, an
+     * appended no-scripts flag). Set only for the argv branch (`Exec`).
+     * Deliberately alongside `input.argv` (the model's requested argv) rather
+     * than instead of it: either half alone is uninformative -- `input` cannot
+     * show what actually ran, and `executed` alone cannot show whether the
+     * normalization was faithful to what was requested.
+     */
+    readonly executed?: readonly string[];
+    /** Which workspace root the argv branch executed against. */
+    readonly target?: "package" | "repoRoot";
+    /**
+     * Who approved an ask-matched call and how long the decision took. Recorded
+     * on BOTH the allow and deny paths so a human-approved execution is
+     * distinguishable in the ledger from a mechanically-allowed one.
+     *
+     * `remembered` is always false today: `AskVerdict` carries no "remembered"
+     * signal, so this is a placeholder for when the cache reports a hit.
+     */
+    readonly approval?: {
+        readonly decidedBy: string;
+        readonly remembered: boolean;
+        readonly latencyMs: number;
+    };
+    /**
+     * P4: `{ backend, wrapped, reason?, denialHint?, argv? }` on every Bash /
+     * Exec row; the exit runs gate on `wrapped`, and `argv` (wrapped calls only)
+     * is the argv the sandbox actually executed, beside the logical `executed`.
+     * Additive and optional, so `TOOL_AUDIT_SCHEMA_VERSION` stays 1 (as
+     * `approval` did).
+     */
+    readonly sandbox?: SandboxRecord;
+    /**
+     * Bash rows only: the shell's exit code, present when nax did not kill the
+     * process group (absent on timeout and turn abort; see `ToolResult.audit`).
+     * `outcome` is unchanged -- every non-zero exit is still `"error"` -- so a
+     * reader separates a negative answer (a no-match grep, exit 1) from a real
+     * failure by reading `exitCode` together with `executed`. N >= 128 may be a
+     * signal nax did not send. Additive and optional, so
+     * `TOOL_AUDIT_SCHEMA_VERSION` stays 1 (as `sandbox` did).
+     */
+    readonly exitCode?: number;
+    /** Provider id for a provider-supplied tool; absent for built-ins. */
+    readonly provider?: string;
+    /**
+     * Result size BEFORE the maxBytes slice. `resultBytes` is measured after,
+     * so elision is otherwise invisible — a 2 MB result and a 40 KB one both
+     * ledger as 40000.
+     */
+    readonly resultBytesPreTruncation?: number;
+    /**
+     * The `callOp` invocation this tool call happened under.
+     *
+     * NOT unique: one callId spans every retry, agent-swap hop and turn of the
+     * invocation, so it is 1:N over cost rows (10.0% of groups hold more than
+     * one). It is a foreign key. Use `turnId` to select a single cost row.
+     *
+     * This is the OPERATION-layer callId (`DispatchEventBase.callId`), not the
+     * stream-layer field of the same name in `agent-stream-events.ts` — joining
+     * on that one produced nax#2045's 0-of-1,940 match rate.
+     */
+    readonly callId?: string;
+    /** Caller-defined region spanning many callOp invocations. */
+    readonly scopeId?: string;
+    /**
+     * The turn this call happened in. One turn is one cost row, so this is the
+     * field that prices a tool call. Native sessions only — ACP does not route
+     * coding tools through the turn loop.
+     */
+    readonly turnId?: string;
+    /**
+     * Model round-trip index WITHIN the turn, 1-based.
+     *
+     * Not a turn index. `turn-loop.ts` pushes an interaction field named
+     * `turnIndex` whose value is this same round-trip counter; the two names
+     * have been conflated before. Native sessions only.
+     */
+    readonly roundTrips?: number;
+    /**
+     * Provider-assigned `tool_use` id, passed through verbatim — nax never mints
+     * or namespaces it. Unique within a session in practice, with no global
+     * guarantee, and NOT stable across a retry: a retried turn produces fresh
+     * ids. The unique tuple is (runId, sessionName, toolCallId).
+     */
+    readonly toolCallId?: string;
+}
+export interface ToolAuditSink {
+    record(entry: ToolCallRecord): void;
+    flush(): Promise<void>;
+}
+/**
+ * The sink `createToolAuditSink` returns, plus the shutdown-time flush.
+ *
+ * `flushPartial()` writes whatever is still buffered with `partial: true` so a
+ * sink whose hop `finally` never runs before `process.exit` still leaves its
+ * audit file behind. After it runs, the sink's own `flush()` is a no-op — the
+ * hop `finally` that runs later must not write a second file.
+ */
+export interface RegisteredSink extends ToolAuditSink {
+    flushPartial(): Promise<void>;
+}
+/** Register a sink so the run's shutdown can flush whatever it still holds. */
+export declare function registerToolAuditSink(runId: string, sink: RegisteredSink): void;
+/** Drop a sink from the run's registry (see registerToolAuditSink). */
+export declare function unregisterToolAuditSink(runId: string, sink: RegisteredSink): void;
+/**
+ * Flush every still-registered sink for `runId` with `partial: true`, then
+ * clear them. Never rejects: one sink's failure must not stop the drain.
+ */
+export declare function flushOpenToolAuditSinks(runId: string): Promise<void>;
+export declare function createNoOpToolAuditSink(): ToolAuditSink;
+/**
+ * tool-audit file schema version.
+ *
+ * 1 — first versioned generation. Adds a file header (`runId`, `featureName`,
+ *     `storyId`, `sessionRole`) and per-call correlation ids (`callId`,
+ *     `scopeId`, `turnId`, `roundTrips`, `toolCallId`).
+ *
+ *     Files written before this field existed carry none of the above and
+ *     cannot be backfilled: `runId` in particular was never in scope at the
+ *     sink's construction path, so an unversioned file's only identity is its
+ *     filename.
+ *
+ *     `sessionName` is a HUMAN LABEL from this version on, never a join key.
+ *     It is constant-prefixed and stable across re-runs by construction, so it
+ *     collides: 7.5% of review-audit sessionNames span more than one runId.
+ *     Join on `runId` plus `callId`/`turnId` instead.
+ *
+ *     NOTE ON `resultBytes`: it is measured AFTER the shared model-truncation
+ *     policy (applyModelTruncationPolicy, src/tools/spill.ts) and so counts what
+ *     the model actually received — the spill marker is composed inside the
+ *     measured content, so its bytes count. That boundary moved at the
+ *     `native-loop-events` merge (f4b3bbc7a): files written before it measured
+ *     each tool's own post-truncation `result.content.length` at `ctx.maxBytes`
+ *     instead. The policy additionally applies `MODEL_MAX_LINES` (1_000),
+ *     `MODEL_MAX_LINE_CHARS` (2_000) and a `MODEL_MAX_BYTES` (40_000) ceiling,
+ *     so the two generations are not comparable call for call. The unit was
+ *     never bytes: it is `String#length`, i.e. UTF-16 code units, so a
+ *     multi-byte result under-reports against the field name.
+ *     `resultBytesPreTruncation` is the pre-policy size and, where a tool sets
+ *     it, is UTF-8 bytes (`Buffer.byteLength` / `Bun.file().size`).
+ */
+export declare const TOOL_AUDIT_SCHEMA_VERSION = 1;
+/** Run-scoped identity stamped once per tool-audit file. */
+export interface ToolAuditHeader {
+    readonly runId?: string;
+    readonly featureName?: string;
+    readonly storyId?: string;
+    readonly sessionRole?: string;
+}
+export declare function createToolAuditSink(opts: {
+    dir: string;
+    sessionName: string;
+    header?: ToolAuditHeader;
+}): RegisteredSink;

package/dist/tools/tool-audit.js

@@ -0,0 +1,183 @@
+/**
+ * Durable record of every coding-tool call.
+ *
+ * runtime.ts already logs each outcome, and says why: a refused call that
+ * leaves no trace is indistinguishable from a call never made. But it logs
+ * through getSafeLogger(), and issue #1359 closed on a measured zero taken off
+ * exactly such a counter while the persisted records still held ten in-window
+ * findings. The zero meant "no data retained" and was read as "did not happen".
+ *
+ * So a signal a later decision depends on is written here, not there. The
+ * logger keeps its calls for operator visibility; neither replaces the other.
+ *
+ * File shape mirrors src/review/review-audit.ts: one JSON file per session,
+ * named <runId>-<epochMs>-<sessionName>.json when the runId is known, and
+ * <epochMs>-<sessionName>.json otherwise.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { errorMessage } from "#src/infra/errors";
+import { getSafeLogger } from "#src/infra/index";
+import { redactRowStrings } from "#src/permissions/index";
+/**
+ * Still-open sinks, keyed by the `runId` they were created under.
+ *
+ * A sink is addressable here precisely because its hop `finally` has not run
+ * yet: `createToolAuditSink` registers it on creation and unregisters it on its
+ * first write, so the registry only ever holds buffers that would otherwise be
+ * lost to `process.exit`.
+ */
+const openToolAuditSinks = new Map();
+/** Register a sink so the run's shutdown can flush whatever it still holds. */
+export function registerToolAuditSink(runId, sink) {
+    const sinks = openToolAuditSinks.get(runId);
+    if (sinks === undefined) {
+        openToolAuditSinks.set(runId, new Set([sink]));
+        return;
+    }
+    sinks.add(sink);
+}
+/** Drop a sink from the run's registry (see registerToolAuditSink). */
+export function unregisterToolAuditSink(runId, sink) {
+    const sinks = openToolAuditSinks.get(runId);
+    if (sinks === undefined)
+        return;
+    sinks.delete(sink);
+    if (sinks.size === 0)
+        openToolAuditSinks.delete(runId);
+}
+/**
+ * Flush every still-registered sink for `runId` with `partial: true`, then
+ * clear them. Never rejects: one sink's failure must not stop the drain.
+ */
+export async function flushOpenToolAuditSinks(runId) {
+    const sinks = openToolAuditSinks.get(runId);
+    if (sinks === undefined)
+        return;
+    // Clear before flushing: the sink's own write path calls
+    // unregisterToolAuditSink, and re-entering the registry mid-iteration would
+    // mutate the map we are reading.
+    openToolAuditSinks.delete(runId);
+    // Started concurrently, so a slow or never-settling sink cannot starve the
+    // writes of the sinks after it. Each sink owns a distinct file, so the
+    // completion order is irrelevant. Every task swallows its own rejection --
+    // one sink's failure is logged and the rest still flush.
+    await Promise.all([...sinks].map(async (sink) => {
+        try {
+            await sink.flushPartial();
+        }
+        catch (error) {
+            getSafeLogger()?.warn("tools", "tool-audit partial flush failed", { runId, error: errorMessage(error) });
+        }
+    }));
+}
+export function createNoOpToolAuditSink() {
+    return { record() { }, async flush() { } };
+}
+/**
+ * tool-audit file schema version.
+ *
+ * 1 — first versioned generation. Adds a file header (`runId`, `featureName`,
+ *     `storyId`, `sessionRole`) and per-call correlation ids (`callId`,
+ *     `scopeId`, `turnId`, `roundTrips`, `toolCallId`).
+ *
+ *     Files written before this field existed carry none of the above and
+ *     cannot be backfilled: `runId` in particular was never in scope at the
+ *     sink's construction path, so an unversioned file's only identity is its
+ *     filename.
+ *
+ *     `sessionName` is a HUMAN LABEL from this version on, never a join key.
+ *     It is constant-prefixed and stable across re-runs by construction, so it
+ *     collides: 7.5% of review-audit sessionNames span more than one runId.
+ *     Join on `runId` plus `callId`/`turnId` instead.
+ *
+ *     NOTE ON `resultBytes`: it is measured AFTER the shared model-truncation
+ *     policy (applyModelTruncationPolicy, src/tools/spill.ts) and so counts what
+ *     the model actually received — the spill marker is composed inside the
+ *     measured content, so its bytes count. That boundary moved at the
+ *     `native-loop-events` merge (f4b3bbc7a): files written before it measured
+ *     each tool's own post-truncation `result.content.length` at `ctx.maxBytes`
+ *     instead. The policy additionally applies `MODEL_MAX_LINES` (1_000),
+ *     `MODEL_MAX_LINE_CHARS` (2_000) and a `MODEL_MAX_BYTES` (40_000) ceiling,
+ *     so the two generations are not comparable call for call. The unit was
+ *     never bytes: it is `String#length`, i.e. UTF-16 code units, so a
+ *     multi-byte result under-reports against the field name.
+ *     `resultBytesPreTruncation` is the pre-policy size and, where a tool sets
+ *     it, is UTF-8 bytes (`Buffer.byteLength` / `Bun.file().size`).
+ */
+export const TOOL_AUDIT_SCHEMA_VERSION = 1;
+/**
+ * Monotonic millisecond stamp for audit filenames.
+ *
+ * `Date.now()` alone is not enough: `flushOpenToolAuditSinks` writes every
+ * still-open sink for a run in one tight loop, so two sinks sharing a
+ * `sessionName` routinely land on the same millisecond -- the second
+ * `writeFile` then silently clobbers the first and one hop's calls are gone.
+ * Nudging the stamp forward on a repeat keeps the filename shape
+ * (`<runId>-<stamp>-<sessionName>.json`) and guarantees one file per sink.
+ */
+let lastFileStamp = 0;
+function nextFileStamp() {
+    const now = Date.now();
+    lastFileStamp = now > lastFileStamp ? now : lastFileStamp + 1;
+    return lastFileStamp;
+}
+export function createToolAuditSink(opts) {
+    const calls = [];
+    const runId = opts.header?.runId;
+    // Set once the shutdown path has written this sink. The hop `finally` that
+    // may still run afterwards must not write a second, non-partial file.
+    let partialFlushed = false;
+    const write = async (partial) => {
+        if (calls.length === 0)
+            return;
+        await mkdir(opts.dir, { recursive: true });
+        const body = JSON.stringify({
+            schemaVersion: TOOL_AUDIT_SCHEMA_VERSION,
+            ...(opts.header ?? {}),
+            sessionName: opts.sessionName,
+            // Additive and optional: absent on a normal flush, `true` only when the
+            // shutdown path persisted a buffer its hop never closed.
+            ...(partial ? { partial: true } : {}),
+            calls: redactRowStrings(calls),
+        }, null, 2);
+        const prefix = runId !== undefined ? `${runId}-` : "";
+        await writeFile(join(opts.dir, `${prefix}${nextFileStamp()}-${opts.sessionName}.json`), body);
+    };
+    const sink = {
+        record(entry) {
+            // The partial file is this sink's last write (a second would duplicate
+            // it), so a row arriving after a SUCCESSFUL partial flush cannot be
+            // persisted. Drop it loudly rather than losing it without a trace.
+            if (partialFlushed) {
+                getSafeLogger()?.warn("tools", "tool-audit row recorded after the partial flush was dropped", {
+                    runId,
+                    tool: entry.tool,
+                });
+                return;
+            }
+            calls.push(entry);
+        },
+        async flushPartial() {
+            if (partialFlushed)
+                return;
+            await write(true);
+            // Only now is the buffer spent. A rejected write leaves the sink open so
+            // the hop `finally` can still write the full file instead of nothing.
+            partialFlushed = true;
+            if (runId !== undefined)
+                unregisterToolAuditSink(runId, sink);
+        },
+        async flush() {
+            // A later hop `finally` after the partial flush: nothing left to write.
+            if (partialFlushed)
+                return;
+            if (runId !== undefined)
+                unregisterToolAuditSink(runId, sink);
+            await write(false);
+        },
+    };
+    if (runId !== undefined)
+        registerToolAuditSink(runId, sink);
+    return sink;
+}