@cruxy/cli 1.7.0 → 1.8.0

package/dist/subagent/orchestrator.js

@@ -1,6 +1,8 @@
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { runAgent } from "../agent/loop.js";
-import { CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { classifyProviderError, CruxyError, ErrorCode, messageOf, sessionBudgetExhausted, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
+import { UsageCollector } from "../usage/index.js";
 import { UNRESOLVED_TIER, } from "../budget/index.js";
 import { resolveTaskModel } from "../routing/index.js";
 import { Workspace } from "../workspace/index.js";
@@ -52,10 +54,12 @@ export class SubagentOrchestrator {
      * withheld at the cap, so this throw is the fail-loud backstop.
      *
      * Never rejects on a *child* failure — provider or tool crashes come back as
-     * `status: "failed"` for the parent to reason over. The two exceptions that
-     * do propagate: the depth cap (above) and `CRUXY_E_APPROVAL_REQUIRED`
+     * `status: "failed"` for the parent to reason over. The three exceptions that
+     * do propagate: the depth cap (above), `CRUXY_E_APPROVAL_REQUIRED`
      * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
-     * not a way to swallow it).
+     * not a way to swallow it), and `CRUXY_E_BUDGET_EXHAUSTED` (the weighted pool
+     * refused this child — see the catch block for why that one is not a partial
+     * result).
      */
     async spawn(spec, parentDepth, opts = {}) {
         const { deps } = this;
@@ -110,6 +114,57 @@ export class SubagentOrchestrator {
         // parent's messages are never in scope here, and this array dies with the
         // spawn — only the structured result below leaves this function.
         const messages = [{ role: "user", content: spec.task }];
+        // Per-request usage for THIS child, collected exactly as the parent's turn
+        // collects its own (`agent/session.ts`) — the loop reports one entry per
+        // completed request, with the tier that served it. Two things need it and
+        // neither can be got from `AgentResult.usage`: the weighted-pool arithmetic
+        // is per-tier, and a run that THREW has no `AgentResult` at all while still
+        // having spent whatever it spent before it died.
+        const usage = new UsageCollector();
+        const startedAt = new Date().toISOString();
+        try {
+            return await this.runChild({
+                spec,
+                opts,
+                messages,
+                registry,
+                budget,
+                ctx,
+                artifacts,
+                label,
+                noun,
+                tag,
+                usage,
+            });
+        }
+        finally {
+            // CHILD SPEND IS SESSION SPEND (cli#212). `budget.record` had exactly one
+            // call site — the parent's own turn — so a fan-out drew on the pool and
+            // left the numerator where it found it. The next admission check then
+            // divided by an allowance that had already been spent, which made the
+            // bound weakest at the moment it mattered most: the second fan-out of a
+            // session that had just dispatched three children.
+            //
+            // In the `finally` because the tokens are spent on every path out of here,
+            // including the two that throw. A child that died mid-run, or that a
+            // sibling's pool denial cancelled, still drew whatever it drew before it
+            // stopped, and the record is what it reported.
+            //
+            // NOT ALSO WRITTEN TO THE USAGE STORE. Child requests have never appeared
+            // in `/usage` and this does not change that — `/budget` now counts them
+            // and `/usage` still does not, so the two figures can differ by a
+            // fan-out's worth. That gap is real and pre-dates this; closing it means
+            // persisting child runs, which is a change to what is on disk and belongs
+            // in its own right rather than smuggled in behind an admission fix.
+            this.deps.budget?.record(usage.toRecord(randomUUID(), undefined, startedAt));
+        }
+    }
+    /** One child's run, from dispatch to structured result. Split out only so the
+     * usage fold above can be a `finally` over every path this can leave by. */
+    async runChild(args) {
+        const { deps } = this;
+        const { spec, opts, messages, registry, budget, ctx, artifacts } = args;
+        const { label, noun, tag, usage } = args;
         let run;
         try {
             run = await runAgent({
@@ -128,6 +183,7 @@ export class SubagentOrchestrator {
                 router: deps.router,
                 taskClass: spec.taskClass ?? "subagent",
                 signal: opts.signal,
+                onRequestUsage: (req) => usage.record(req),
             });
         }
         catch (err) {
@@ -136,6 +192,26 @@ export class SubagentOrchestrator {
                 deps.renderer?.setPhase(null);
                 throw err;
             }
+            // THE WEIGHTED POOL REFUSED THIS CHILD (429 `budget_exhausted`), and that
+            // is not a per-child outcome (cli#212). The pool is one denominator shared
+            // by every sibling, every other surface on the account, and the parent's
+            // own next request: nothing that is about to run can succeed, so folding
+            // this into a `failed` result would let each sibling walk into its own
+            // refusal — N denials for one fact, each after its tokens were spent.
+            //
+            // Rethrown as the TYPED error rather than the raw one so `code`,
+            // `window`, `resetAt` and `miraAvailable` survive to the boundary. The
+            // last of those is the only step that unblocks the user now rather than
+            // telling them when to come back, and flattening it into a message string
+            // is exactly how it used to be lost.
+            const denial = poolDenial(err);
+            if (denial) {
+                if (deps.renderer) {
+                    deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} stopped — ${denial.title}`);
+                }
+                deps.renderer?.setPhase(null);
+                throw denial;
+            }
             if (deps.renderer) {
                 deps.renderer.note(`${deps.renderer.theme.glyph.failure} ${noun} failed: ${label}`);
             }
@@ -146,13 +222,20 @@ export class SubagentOrchestrator {
                 ...artifactsField(artifacts),
                 error: `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`,
                 iterations: 0,
-                usage: { input_tokens: 0, output_tokens: 0 },
+                // WHAT IT ACTUALLY SPENT, which is not zero and was reported as zero
+                // until now. A child that failed on its third request had two requests'
+                // tokens deducted from a pool the parent then went on to fan out
+                // against; a fabricated 0 put that spend nowhere. When NOTHING reported
+                // usage — the request died before the provider said anything — the
+                // field is absent, which the parent reads as unknown. Zero is reserved
+                // for a child that genuinely drew nothing.
+                ...usageField(usage),
             };
         }
         deps.renderer?.setPhase(null);
         const result = this.toResult(run, artifacts, label, noun);
         deps.logger.debug(`${noun} ${result.status}: ${result.iterations} turn(s), tokens in/out ` +
-            `${result.usage.input_tokens}/${result.usage.output_tokens} — ${label}`);
+            `${describeUsage(result.usage)} — ${label}`);
         return result;
     }
     /**
@@ -168,11 +251,18 @@ export class SubagentOrchestrator {
      *
      * Cancellation: children share one {@link AbortController}. A child returning a
      * `failed`/`budget-exceeded` result is a normal PARTIAL outcome — siblings run
-     * on. But a *fatal* throw from any child (non-interactive default-deny) or an
-     * abort on `opts.signal` (Ctrl-C) aborts the controller: every sibling stops at
-     * its next turn boundary and its in-flight shell child is kill-tree'd, so the
-     * fan-out leaves no orphan. All children are awaited to settle before a fatal
-     * throw propagates — never a detached, still-running sibling.
+     * on. But a *fatal* throw from any child (non-interactive default-deny, or a
+     * weighted-pool denial) or an abort on `opts.signal` (Ctrl-C) aborts the
+     * controller: every sibling stops at its next turn boundary and its in-flight
+     * shell child is kill-tree'd, so the fan-out leaves no orphan. All children are
+     * awaited to settle before a fatal throw propagates — never a detached,
+     * still-running sibling.
+     *
+     * THE POOL DENIAL IS THE ONE WORTH NAMING (cli#212). `budget_exhausted` is a
+     * statement about a denominator every sibling shares, so the first 429 is the
+     * whole batch's answer: without the abort, each remaining child walks into its
+     * own refusal and the parent gets N reports of one fact — each one arriving
+     * after that child had already spent what it spent getting there.
      */
     async spawnMany(specs, parentDepth, opts = {}) {
         const { maxDepth } = this.deps.config.subagent;
@@ -230,8 +320,11 @@ export class SubagentOrchestrator {
                     });
                 }
                 catch (err) {
-                    // A fatal throw (non-interactive default-deny) cancels the whole
-                    // fan-out — no sibling is left running — then propagates.
+                    // A fatal throw (non-interactive default-deny, or a weighted-pool
+                    // denial) cancels the whole fan-out — no sibling is left running —
+                    // then propagates. The abort is what makes the FIRST 429 the
+                    // batch's answer: siblings stop at their next turn boundary rather
+                    // than each spending its way into the same refusal.
                     controller.abort();
                     throw err;
                 }
@@ -396,6 +489,57 @@ function taskLabel(task) {
 function isWriter(spec) {
     return (spec.tools ?? []).some((t) => SUBAGENT_WRITE_TOOLS.has(t));
 }
+/**
+ * The typed pool denial behind an error, or `null` if it is not one.
+ *
+ * Two shapes reach here and both are the same fact: the raw SDK
+ * `BudgetExhaustedError` from this child's own request, and — when a child that
+ * itself spawned re-throws — the `CruxyError` a nested `spawn` already
+ * converted. Mapping goes through `classifyProviderError` so there is still ONE
+ * place that knows which SDK class means what.
+ */
+function poolDenial(err) {
+    if (CruxyError.is(err)) {
+        return err.code === ErrorCode.BudgetExhausted ? err : null;
+    }
+    const typed = classifyProviderError(err);
+    return typed?.code === ErrorCode.BudgetExhausted ? typed : null;
+}
+/**
+ * The tokens a child is KNOWN to have spent, or `undefined` when no request
+ * reported any.
+ *
+ * The loop fires `onRequestUsage` only for a request that COMPLETED, and when
+ * it does the provider's counts arrive as a pair or not at all — so an entry
+ * carries both figures or neither, and summing the ones that have them is a
+ * real measurement rather than a partial one. No entry at all is the genuinely
+ * unknown case: the request died before the provider reported anything, which
+ * does NOT mean the gateway metered nothing for it.
+ */
+function usageField(collected) {
+    const entries = collected.toRecord("", undefined, "").entries;
+    const total = sumReported(entries);
+    return total ? { usage: total } : {};
+}
+function sumReported(entries) {
+    let input = 0;
+    let output = 0;
+    let reported = false;
+    for (const e of entries) {
+        if (e.inputTokens === undefined && e.outputTokens === undefined)
+            continue;
+        input += e.inputTokens ?? 0;
+        output += e.outputTokens ?? 0;
+        reported = true;
+    }
+    return reported ? { input_tokens: input, output_tokens: output } : undefined;
+}
+/** `in/out`, or the word for an absent figure — never a stand-in `0/0`. */
+function describeUsage(usage) {
+    return usage
+        ? `${usage.input_tokens}/${usage.output_tokens}`
+        : "unknown (nothing reported)";
+}
 /** The honest result for a child cancelled before it could produce anything —
  * used when a fatal sibling / Ctrl-C fired before this slot even dispatched. */
 function cancelledResult() {

package/dist/subagent/spawn-tool.js

@@ -8,6 +8,26 @@ import { SPAWN_SUBAGENT_TOOL_NAME, SPAWN_SUBAGENTS_TOOL_NAME, } from "./registry
  * on structurally encodes how much deeper nesting may go: at the configured
  * cap the tool simply isn't registered.
  */
+/**
+ * Errors a spawn tool must NOT convert into a tool result.
+ *
+ * A tool error is an invitation to the model to try again differently, so this
+ * set is exactly the errors for which trying again differently is not a thing
+ * the model can do:
+ *
+ *  - `APPROVAL_REQUIRED` — non-interactive default-deny (U.3). There is no
+ *    variation of the call that would be approved; the boundary reports it.
+ *  - `BUDGET_EXHAUSTED` — the weighted pool refused (cli#212). Retrying, in any
+ *    shape, is a request to a gate that will refuse again, and the parent's own
+ *    next request would hit the same 429 regardless. Propagating it means the
+ *    user reads what the gateway actually said — which window, when it recovers,
+ *    and whether mira is still open — instead of the model narrating a tool
+ *    failure and reaching for another spawn.
+ */
+const PROPAGATE = new Set([
+    ErrorCode.ApprovalRequired,
+    ErrorCode.BudgetExhausted,
+]);
 const parameters = z.object({
     task: z
         .string()
@@ -42,10 +62,12 @@ function resultPayload(result) {
         ...(result.artifacts ? { artifacts: result.artifacts } : {}),
         ...(result.error ? { error: result.error } : {}),
         iterations: result.iterations,
-        tokens: {
-            input: result.usage.input_tokens,
-            output: result.usage.output_tokens,
-        },
+        // `"unknown"` rather than an omitted field or a `0/0` pair: the parent model
+        // reasons about what a child cost, and a missing key reads as nothing spent
+        // to anything skimming the payload. See `SubagentResult.usage`.
+        tokens: result.usage
+            ? { input: result.usage.input_tokens, output: result.usage.output_tokens }
+            : "unknown",
     };
 }
 /** The compact wire shape fed back to the parent model. */
@@ -84,10 +106,10 @@ export function makeSpawnSubagentTool(orchestrator, depth) {
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3) —
-                // same behavior as every other gated tool.
-                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                // same behavior as every other gated tool. So does a weighted-pool
+                // denial (cli#212): see `PROPAGATE`.
+                if (CruxyError.is(err) && PROPAGATE.has(err.code))
                     throw err;
-                }
                 // Depth-exceed and scope violations are the model's to correct: feed
                 // the coded, actionable message back as a tool error.
                 return { ok: false, error: toolErrorMessage(err) };
@@ -171,9 +193,8 @@ export function makeSpawnSubagentsTool(orchestrator, depth) {
             }
             catch (err) {
                 // Non-interactive default-deny propagates to the boundary (U.3).
-                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                if (CruxyError.is(err) && PROPAGATE.has(err.code))
                     throw err;
-                }
                 // Scope overlap / depth-exceed are the model's to correct — coded error.
                 return { ok: false, error: toolErrorMessage(err) };
             }

package/dist/tools/file/apply-patch.js

@@ -5,34 +5,93 @@ import { resolveToolPath, toPosix } from "./paths.js";
 import { applyEol, detectEol, findMatch, tierLabel } from "./match.js";
 /** How many leading lines of a created file the approval preview shows. */
 const PREVIEW_LINES = 20;
-const HunkSchema = z.object({
+/**
+ * ONE FLAT OPERATION SHAPE — deliberately flat, and it must stay that way.
+ *
+ * The provider rejects a tool schema nested 8 or more levels deep, and it
+ * rejects the entire REQUEST when any tool trips it: one over-deep schema kills
+ * every turn of every session, which is exactly how 1.7.0 died in the field.
+ * JSON Schema's own wrapper keys (`properties`, `items`, `anyOf`) are containers
+ * too, so every semantic level an author writes costs two, and a union costs two
+ * more on top. The previous shape — a discriminated union of operations, each
+ * carrying an array of hunk OBJECTS — rendered 11 levels deep.
+ *
+ * Neither lever alone was enough (both measured, see schema-depth.test.ts):
+ * keeping the union and flattening hunks still renders 8; dropping the union and
+ * keeping the hunk array renders 9. So both go. The discriminator survives as a
+ * plain `type` enum, and the per-variant field requirements the union used to
+ * encode are enforced by {@link refineOperation} below — `superRefine` is a
+ * runtime check that adds NO depth to the rendered schema, so the model still
+ * gets a precise rejection for a malformed operation, just from zod instead of
+ * from the schema's shape.
+ *
+ * The multi-hunk capability is NOT lost: a path may appear in as many `update`
+ * operations as it likes, and they apply in order against the running content —
+ * the same semantics the `hunks` array had, spelled one hunk per operation.
+ */
+const OperationSchema = z
+    .object({
+    type: z
+        .enum(["update", "create", "delete"])
+        .describe('What to do: "update" replaces oldStr with newStr in an existing file; ' +
+        '"create" writes a new file from content; "delete" removes an existing file.'),
+    path: z.string().describe("Path to the file, relative to the root."),
     oldStr: z
         .string()
         .min(1)
-        .describe("Exact text to replace; must occur exactly once in the file."),
-    newStr: z.string().describe("Replacement text."),
-});
-const OperationSchema = z.discriminatedUnion("type", [
-    z.object({
-        type: z.literal("update"),
-        path: z
-            .string()
-            .describe("Path to an existing file, relative to the root."),
-        hunks: z
-            .array(HunkSchema)
-            .min(1)
-            .describe("Edits applied in order; each oldStr must match exactly once."),
-    }),
-    z.object({
-        type: z.literal("create"),
-        path: z.string().describe("Path for a new file; must not already exist."),
-        content: z.string().describe("Full UTF-8 contents of the new file."),
-    }),
-    z.object({
-        type: z.literal("delete"),
-        path: z.string().describe("Path to an existing file to delete."),
-    }),
-]);
+        .optional()
+        .describe("update only — exact text to replace; must occur exactly once in the " +
+        "file as it stands when this operation runs."),
+    newStr: z
+        .string()
+        .optional()
+        .describe("update only — the replacement text (may be empty to delete)."),
+    content: z
+        .string()
+        .optional()
+        .describe("create only — full UTF-8 contents of the new file."),
+})
+    .superRefine(refineOperation);
+/**
+ * The per-variant requirements the discriminated union used to express in the
+ * schema. Enforced here so a malformed operation is still rejected before
+ * `execute` runs, with a message naming the exact field.
+ */
+function refineOperation(op, ctx) {
+    const needs = (field) => {
+        if (op[field] === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [field],
+                message: `"${field}" is required when type is "${op.type}"`,
+            });
+        }
+    };
+    const forbid = (field) => {
+        if (op[field] !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [field],
+                message: `"${field}" is not allowed when type is "${op.type}"`,
+            });
+        }
+    };
+    if (op.type === "update") {
+        needs("oldStr");
+        needs("newStr");
+        forbid("content");
+        return;
+    }
+    if (op.type === "create") {
+        needs("content");
+        forbid("oldStr");
+        forbid("newStr");
+        return;
+    }
+    forbid("oldStr");
+    forbid("newStr");
+    forbid("content");
+}
 const parameters = z.object({
     operations: z
         .array(OperationSchema)
@@ -50,14 +109,19 @@ export const applyPatchTool = {
     name: "apply_patch",
     description: "Apply multiple edits across one or more files in a single, atomic, reviewed change — preferred over many edit_file calls for multi-file or multi-hunk work. " +
         "Input is { operations: [...] } where each operation is one of: " +
-        '{ "type":"update", "path", "hunks":[{ "oldStr", "newStr" }] } — replace each oldStr (which must match EXACTLY ONCE in the file, like edit_file; hunks apply in order) with newStr; ' +
+        '{ "type":"update", "path", "oldStr", "newStr" } — replace oldStr (which must match EXACTLY ONCE in the file, like edit_file) with newStr; ' +
         '{ "type":"create", "path", "content" } — create a new file (must not already exist); ' +
         '{ "type":"delete", "path" } — delete an existing file. ' +
+        "To make several edits to the SAME file, list several update operations with the same path: they apply in order, each one matching against the result of the previous. " +
+        "A path used by a create or a delete may appear only once. " +
         "The whole patch is validated before anything is written: if any operation is invalid, nothing is applied and the failing operation is reported.",
     parameters,
     async execute(input, ctx) {
-        const planned = [];
-        const seen = new Set();
+        // One track per path, in first-touch order. Repeated `update` operations on
+        // a path fold into its track, each hunk matching against the running content
+        // — so a file is still written exactly once, from one final byte string.
+        const tracks = new Map();
+        const order = [];
         for (let i = 0; i < input.operations.length; i++) {
             const op = input.operations[i];
             let abs;
@@ -67,18 +131,29 @@ export const applyPatchTool = {
             catch (err) {
                 return { ok: false, error: opError(i, op, err.message) };
             }
-            if (seen.has(abs)) {
-                return {
-                    ok: false,
-                    error: opError(i, op, "duplicate path in patch"),
-                };
+            const existing = tracks.get(abs);
+            if (existing) {
+                // Only an update chain may share a path. A create or a delete alongside
+                // anything else on the same path is an order-dependent muddle, and the
+                // shape that preceded this one couldn't express it either.
+                if (existing.kind !== "update" || op.type !== "update") {
+                    return {
+                        ok: false,
+                        error: opError(i, op, `path already used by operation ${existing.firstOp + 1}; only repeated "update" operations may share a path`),
+                    };
+                }
+                const failure = applyHunk(i, op, existing);
+                if (failure)
+                    return { ok: false, error: failure };
+                continue;
             }
-            seen.add(abs);
-            const planResult = await planOp(i, op, abs, ctx);
-            if (!planResult.ok)
-                return planResult;
-            planned.push(planResult.planned);
+            const opened = await openTrack(i, op, abs, ctx);
+            if (!opened.ok)
+                return opened;
+            tracks.set(abs, opened.track);
+            order.push(abs);
         }
+        const planned = order.map((abs) => toPlanned(tracks.get(abs)));
         // One approval for the whole patch — denial writes nothing.
         const decision = await ctx.requestApproval({
             kind: "patch",
@@ -114,27 +189,31 @@ export const applyPatchTool = {
         return { ok: true, output: `applied patch:\n${applied.join("\n")}` };
     },
 };
-/** Validate one operation against the filesystem and compute its final bytes. */
-async function planOp(i, op, abs, ctx) {
+/** Validate the FIRST operation on a path and open its track. */
+async function openTrack(i, op, abs, ctx) {
     // Forward-slash for model-facing output (the `applied` lines and error
     // messages), consistent with every other path tool — see {@link toPosix}.
     const rel = toPosix(path.relative(ctx.cwd, abs));
+    const base = { abs, rel, firstOp: i, hunks: [] };
     if (op.type === "create") {
         if (await exists(abs)) {
             return { ok: false, error: opError(i, op, "file already exists") };
         }
+        const content = op.content ?? "";
         return {
             ok: true,
-            planned: { op: "create", abs, rel, content: op.content },
+            track: { ...base, kind: "create", content, eol: detectEol(content) },
         };
     }
     if (op.type === "delete") {
         if (!(await exists(abs))) {
             return { ok: false, error: opError(i, op, "file not found") };
         }
-        return { ok: true, planned: { op: "delete", abs, rel } };
+        return {
+            ok: true,
+            track: { ...base, kind: "delete", content: "", eol: "\n" },
+        };
     }
-    // update: read, then apply each hunk in order against the running content.
     let content;
     try {
         content = await fs.readFile(abs, "utf8");
@@ -145,34 +224,49 @@ async function planOp(i, op, abs, ctx) {
         }
         return { ok: false, error: opError(i, op, err.message) };
     }
-    // Detect the file's line ending once, from the original bytes, so every hunk
-    // re-encodes newStr to the same convention as content mutates across hunks.
-    const fileEol = detectEol(content);
-    for (let h = 0; h < op.hunks.length; h++) {
-        const { oldStr, newStr } = op.hunks[h];
-        const match = findMatch(content, oldStr);
-        if (match.kind === "none") {
-            return {
-                ok: false,
-                error: opError(i, op, `hunk ${h + 1}: oldStr not found`),
-            };
-        }
-        if (match.kind === "ambiguous") {
-            return {
-                ok: false,
-                error: opError(i, op, `hunk ${h + 1}: oldStr not unique (${match.count} matches${tierLabel(match.tier)})`),
-            };
-        }
-        // Splice by offset so `$` patterns in newStr aren't interpreted.
-        content =
-            content.slice(0, match.start) +
-                applyEol(newStr, fileEol) +
-                content.slice(match.end);
-    }
-    return {
-        ok: true,
-        planned: { op: "update", abs, rel, content, hunks: op.hunks },
+    const track = {
+        ...base,
+        kind: "update",
+        content,
+        eol: detectEol(content),
     };
+    const failure = applyHunk(i, op, track);
+    return failure ? { ok: false, error: failure } : { ok: true, track };
+}
+/**
+ * Apply one update operation's hunk to its track's running content. Returns an
+ * error string on failure, or `undefined` on success (the track is mutated).
+ */
+function applyHunk(i, op, track) {
+    const { oldStr, newStr } = op;
+    // Guaranteed present by `refineOperation`; re-checked so the narrowing is
+    // structural rather than a cast, and a schema regression fails loud.
+    if (oldStr === undefined || newStr === undefined) {
+        return opError(i, op, 'update requires both "oldStr" and "newStr"');
+    }
+    const match = findMatch(track.content, oldStr);
+    if (match.kind === "none") {
+        return opError(i, op, "oldStr not found");
+    }
+    if (match.kind === "ambiguous") {
+        return opError(i, op, `oldStr not unique (${match.count} matches${tierLabel(match.tier)})`);
+    }
+    // Splice by offset so `$` patterns in newStr aren't interpreted.
+    track.content =
+        track.content.slice(0, match.start) +
+            applyEol(newStr, track.eol) +
+            track.content.slice(match.end);
+    track.hunks.push({ oldStr, newStr });
+    return undefined;
+}
+/** Collapse a finished track into the single write it represents. */
+function toPlanned(track) {
+    const { kind, abs, rel, content, hunks } = track;
+    if (kind === "delete")
+        return { op: "delete", abs, rel };
+    if (kind === "create")
+        return { op: "create", abs, rel, content };
+    return { op: "update", abs, rel, content, hunks };
 }
 /** Shape a planned op into its approval-preview form. */
 function toPreview(p) {

package/dist/tools/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./registry.js";
+export * from "./schema-depth.js";
 export * from "./list-files.js";
 export * from "./git-status.js";
 export * from "./search-codebase.js";