apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/tools/contract.js

@@ -6,6 +6,7 @@
  * permission, context, evidence), which is what keeps a new tool from silently
  * defaulting into "unclassified".
  */
+import { Type } from "typebox";
 export const ALL_CAPABILITIES = new Set([
     "fs.read",
     "fs.write",
@@ -16,8 +17,10 @@ export const ALL_CAPABILITIES = new Set([
     "state",
 ]);
 /**
- * Conservative contract for a tool registered without one — MCP servers and
- * third-party extensions cannot supply a `contract`. Full capability set (so it can
+ * Conservative contract for a tool registered without one -- third-party extension
+ * tools, which cannot supply a `contract`. MCP tools no longer land here: they reach
+ * the model through the built-in `mcp` proxy, whose contract is declared in
+ * `core/mcp/contract.ts`. Full capability set (so it can
  * never widen a delegation ceiling), `ask` by default, never evicted, schema
  * deferred, emits nothing. Matching is exact-argument only: a foreign tool's rule
  * authorizes exactly the call it was generated from, never a pattern.
@@ -45,4 +48,21 @@ export function resolveToolContract(lookup, toolName) {
 export function resolveToolContext(lookup, toolName) {
     return lookup(toolName) ?? UNCLASSIFIED;
 }
+/**
+ * A tool whose call shapes differ, declared so a provider can still see its fields.
+ *
+ * `Type.Union` compiles to `{ anyOf: [...] }`, which carries no top-level
+ * `properties`. The Anthropic request builder reads `properties` and `required`
+ * directly (`anthropic-messages.js`, `legacyInputSchema`), so a union reached the
+ * model as an object with no fields at all. It then guessed, and our own
+ * validation rejected the guess.
+ *
+ * The union still decides what is valid. `properties` is advertisement, listing
+ * every field across the variants so a provider that ignores `anyOf` has
+ * something to work from. It deliberately carries no `required`, because no field
+ * is required by every variant.
+ */
+export function toolUnion(variants, properties) {
+    return Type.Union(variants, { type: "object", properties });
+}
 //# sourceMappingURL=contract.js.map

package/dist/core/tools/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/core/tools/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,MAAM,CAAC,MAAM,gBAAgB,GAA4B,IAAI,GAAG,CAAa;IAC5E,SAAS;IACT,UAAU;IACV,MAAM;IACN,KAAK;IACL,UAAU;IACV,IAAI;IACJ,OAAO;CACP,CAAC,CAAC;AAgMH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,YAAY,GAAmC;IAC3D,YAAY,EAAE,gBAAgB;IAC9B,UAAU,EAAE;QACX,eAAe,EAAE,KAAK;QACtB,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QACxE,QAAQ,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,eAAe,WAAW,EAAE;QACvD,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;KAC/C;IACD,OAAO,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE;IACzD,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;CACjD,CAAC;AAEF,kEAAkE;AAClE,MAAM,UAAU,mBAAmB,CAClC,MAAsD,EACtD,QAAgB,EACD;IACf,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC;AAAA,CACxC;AAED,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CACjC,MAAuE,EACvE,QAAgB,EACgB;IAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC;AAAA,CACxC","sourcesContent":["/**\n * The canonical tool contract. Settled by ADR 0010 and specified in full at\n * docs/architecture/contracts.md § 1 — this module implements that shape, it does\n * not redesign it. `contract` is required on every registered tool, and so is every\n * sub-field: a tool cannot compile without answering all four axes (capabilities,\n * permission, context, evidence), which is what keeps a new tool from silently\n * defaulting into \"unclassified\".\n */\n\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport type { Static, TSchema } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\n\n/** What class of thing a tool does. A set, not a single value — `bash` is `{exec}`. */\nexport type Capability = \"fs.read\" | \"fs.write\" | \"exec\" | \"net\" | \"delegate\" | \"ui\" | \"state\";\n\nexport const ALL_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([\n\t\"fs.read\",\n\t\"fs.write\",\n\t\"exec\",\n\t\"net\",\n\t\"delegate\",\n\t\"ui\",\n\t\"state\",\n]);\n\nexport type PermissionBehavior = \"allow\" | \"deny\" | \"ask\";\n\n/**\n * `ruleContent` is interpreted by the tool, never by the rule engine (ADR 0010).\n * That is what lets `Bash(git commit:*)` and `Read(~/.ssh/**)` mean entirely\n * different things while the engine that resolves precedence stays tool-agnostic.\n */\nexport interface PermissionSpec<TParams extends TSchema = TSchema> {\n\t/** Behavior when no rule matches. Read-only tools may default to \"allow\". */\n\tdefaultBehavior: PermissionBehavior;\n\n\t/** Does this call match this rule's content? The tool owns the grammar. */\n\tmatches(ruleContent: string, params: Static<TParams>): boolean;\n\n\t/** Human-readable rendering of a rule, for prompts and denial messages. */\n\tdescribe(ruleContent: string): string;\n\n\t/**\n\t * The rule that would allow this exact call — what \"always allow this\"\n\t * persists. Return null when the call is not generalizable into a rule.\n\t */\n\truleForCall(params: Static<TParams>): string | null;\n}\n\nexport interface ContextSpec {\n\t/**\n\t * True when the result's information is recoverable — the same content can be\n\t * obtained again by re-running the tool or reading the workspace.\n\t *\n\t * ONLY recoverable results may be evicted (Phase 3). A tool whose result cannot\n\t * be regenerated (a nondeterministic command, a consumed one-shot resource)\n\t * must set this false, or eviction would silently destroy information the\n\t * transcript is the only record of.\n\t */\n\tresultRecoverable: boolean;\n\n\t/** Marker substituted for an evicted result. */\n\tevictionMarker?: string;\n\n\t/** Announce by name only; load the parameter schema on demand. */\n\tdeferSchema: boolean;\n\n\t/** Soft cap on result tokens before truncation. */\n\toutputBudgetTokens?: number;\n}\n\nexport type EvidenceKind = \"diff\" | \"test\" | \"command\" | \"manual\" | \"workflow\" | \"diagnostic\";\n\n/** Source-observed command facts. `exitCode` is absent only when execution never began. */\nexport interface CommandEvidenceRecord {\n\tkind: \"command\";\n\tcommand: string;\n\tcwd?: string;\n\texecutable?: string;\n\targv?: string[];\n\texitCode?: number | null;\n}\n\n/** A file mutation is identified by hashes and paths, never raw file or patch contents. */\nexport interface DiffEvidenceRecord {\n\tkind: \"diff\";\n\tpath: string;\n\tpatchHash?: string;\n\tcontentHash?: string;\n\tbyteCount?: number;\n}\n\n/** Zero-filled diagnostic severity buckets for one bounded language-server outcome. */\nexport interface DiagnosticSeverityCounts {\n\terror: number;\n\twarning: number;\n\tinformation: number;\n\thint: number;\n\tunspecified: number;\n\tother: number;\n}\n\n/** Stable durable classification. Free-form server and process errors never enter evidence. */\nexport type DiagnosticUnavailableKind =\n\t| \"no-server\"\n\t| \"disposed\"\n\t| \"unsupported-sync\"\n\t| \"timed-out\"\n\t| \"aborted\"\n\t| \"superseded\"\n\t| \"server-failed\";\n\n/** Bounded post-mutation diagnostic facts, never diagnostic messages or rendered failure reasons. */\nexport type DiagnosticEvidenceRecord =\n\t| {\n\t\t\tkind: \"diagnostic\";\n\t\t\tpath: string;\n\t\t\tstatus: \"ok\";\n\t\t\tserverId: string;\n\t\t\tdiagnosticCount: number;\n\t\t\tseverityCounts: DiagnosticSeverityCounts;\n\t\t\ttruncated: boolean;\n\t  }\n\t| {\n\t\t\tkind: \"diagnostic\";\n\t\t\tpath: string;\n\t\t\tstatus: \"unavailable\";\n\t\t\tserverId?: string;\n\t\t\tunavailableKind: DiagnosticUnavailableKind;\n\t  };\n\n/** Normalized argv-based test execution facts. */\nexport interface TestEvidenceRecord {\n\tkind: \"test\";\n\tcwd: string;\n\texecutable: string;\n\targv: string[];\n\texitCode: number | null;\n}\n\n/** Explicit human attestation; policy decides how, or whether, it is sufficient. */\nexport interface ManualEvidenceRecord {\n\tkind: \"manual\";\n\tvalue?: unknown;\n\tobserved?: unknown;\n\tstatus?: string;\n}\n\n/** Source facts from approval and delegation workflows. */\nexport interface WorkflowEvidenceRecord {\n\tkind: \"workflow\";\n\tplan?: string;\n\tapproved?: boolean;\n\tagentType?: string;\n\ttask?: string;\n\thandle?: string;\n}\n\n/** A structured source record. Policy is a separate consumer, not an additional variant. */\nexport type EvidenceRecord =\n\t| CommandEvidenceRecord\n\t| DiffEvidenceRecord\n\t| DiagnosticEvidenceRecord\n\t| TestEvidenceRecord\n\t| ManualEvidenceRecord\n\t| WorkflowEvidenceRecord;\n\n/** Durable destination for source-level tool evidence. Policy is deliberately not part of this boundary. */\nexport interface EvidenceSink {\n\trecord(entry: { toolName: string; records: EvidenceRecord[] }): void;\n\trecordDiagnostic?(diagnostic: EvidenceCaptureDiagnostic): void;\n}\n\n/** A capture failure is observable but never changes an already-completed tool result. */\nexport interface EvidenceCaptureDiagnostic {\n\ttoolName: string;\n\treason: string;\n}\n\nexport interface EvidenceSpec<TParams extends TSchema = TSchema, TDetails = unknown> {\n\t/** Kinds this tool can emit. Empty set is valid and explicit. */\n\temits: ReadonlySet<EvidenceKind>;\n\n\t/**\n\t * Derive evidence from a completed call. Runs inside the tool's own execution\n\t * path, with access to what actually happened, not a reconstruction from\n\t * rendered output.\n\t */\n\tcapture(params: Static<TParams>, result: AgentToolResult<TDetails>): EvidenceRecord[];\n}\n\nexport interface ToolContract<TParams extends TSchema = TSchema, TDetails = unknown> {\n\tcapabilities: ReadonlySet<Capability>;\n\tpermission: PermissionSpec<TParams>;\n\tcontext: ContextSpec;\n\tevidence: EvidenceSpec<TParams, TDetails>;\n}\n\n/**\n * Apex Code extends upstream ToolDefinition with exactly one required field.\n *\n * `TState` defaults to `any`, matching upstream `ToolDefinition` exactly (not\n * `unknown`). That default is load-bearing: TypeScript compares two instantiations\n * of the *same* generic interface (here, both rooted in `ToolDefinition`) using each\n * type parameter's declared variance, without expanding `Static<TParams>`\n * structurally — but only when every type argument lines up, including the ones a\n * caller left defaulted. A mismatched default reintroduces a full structural check,\n * where `Static<any>` does not behave like `any`, and breaks every pre-existing\n * `ToolDefinition<any, X>`-typed consumer across the codebase.\n */\nexport interface ApexToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>\n\textends ToolDefinition<TParams, TDetails, TState> {\n\tcontract: ToolContract<TParams, TDetails>;\n}\n\n/**\n * Conservative contract for a tool registered without one — MCP servers and\n * third-party extensions cannot supply a `contract`. Full capability set (so it can\n * never widen a delegation ceiling), `ask` by default, never evicted, schema\n * deferred, emits nothing. Matching is exact-argument only: a foreign tool's rule\n * authorizes exactly the call it was generated from, never a pattern.\n *\n * This must also be reported as unclassified wherever a consumer describes the tool\n * registry (contracts.md invariant 1) — a conservative default nobody can see is\n * indistinguishable from a bug.\n */\nexport const UNCLASSIFIED: ToolContract<TSchema, unknown> = {\n\tcapabilities: ALL_CAPABILITIES,\n\tpermission: {\n\t\tdefaultBehavior: \"ask\",\n\t\tmatches: (ruleContent, params) => ruleContent === JSON.stringify(params),\n\t\tdescribe: (ruleContent) => `Exact call: ${ruleContent}`,\n\t\truleForCall: (params) => JSON.stringify(params),\n\t},\n\tcontext: { resultRecoverable: false, deferSchema: false },\n\tevidence: { emits: new Set(), capture: () => [] },\n};\n\n/** Resolve a complete tool contract for enforcement consumers. */\nexport function resolveToolContract(\n\tlookup: (toolName: string) => ToolContract | undefined,\n\ttoolName: string,\n): ToolContract {\n\treturn lookup(toolName) ?? UNCLASSIFIED;\n}\n\n/** Resolve the context projection using the same canonical foreign-tool fallback. */\nexport function resolveToolContext(\n\tlookup: (toolName: string) => Pick<ToolContract, \"context\"> | undefined,\n\ttoolName: string,\n): Pick<ToolContract, \"context\"> {\n\treturn lookup(toolName) ?? UNCLASSIFIED;\n}\n"]}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/core/tools/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAA6B,IAAI,EAAE,MAAM,SAAS,CAAC;AAO1D,MAAM,CAAC,MAAM,gBAAgB,GAA4B,IAAI,GAAG,CAAa;IAC5E,SAAS;IACT,UAAU;IACV,MAAM;IACN,KAAK;IACL,UAAU;IACV,IAAI;IACJ,OAAO;CACP,CAAC,CAAC;AAiOH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,YAAY,GAAmC;IAC3D,YAAY,EAAE,gBAAgB;IAC9B,UAAU,EAAE;QACX,eAAe,EAAE,KAAK;QACtB,OAAO,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,WAAW,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QACxE,QAAQ,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,eAAe,WAAW,EAAE;QACvD,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;KAC/C;IACD,OAAO,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE;IACzD,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;CACjD,CAAC;AAEF,kEAAkE;AAClE,MAAM,UAAU,mBAAmB,CAClC,MAAsD,EACtD,QAAgB,EACD;IACf,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC;AAAA,CACxC;AAED,qFAAqF;AACrF,MAAM,UAAU,kBAAkB,CACjC,MAAuE,EACvE,QAAgB,EACgB;IAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,YAAY,CAAC;AAAA,CACxC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAsB,QAAgB,EAAE,UAAmC,EAAE;IACrG,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;AAAA,CAC5D","sourcesContent":["/**\n * The canonical tool contract. Settled by ADR 0010 and specified in full at\n * docs/architecture/contracts.md § 1 — this module implements that shape, it does\n * not redesign it. `contract` is required on every registered tool, and so is every\n * sub-field: a tool cannot compile without answering all four axes (capabilities,\n * permission, context, evidence), which is what keeps a new tool from silently\n * defaulting into \"unclassified\".\n */\n\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, type TSchema, Type } from \"typebox\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport type { PermissionPreview } from \"../permissions/responder.ts\";\n\n/** What class of thing a tool does. A set, not a single value — `bash` is `{exec}`. */\nexport type Capability = \"fs.read\" | \"fs.write\" | \"exec\" | \"net\" | \"delegate\" | \"ui\" | \"state\";\n\nexport const ALL_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([\n\t\"fs.read\",\n\t\"fs.write\",\n\t\"exec\",\n\t\"net\",\n\t\"delegate\",\n\t\"ui\",\n\t\"state\",\n]);\n\nexport type PermissionBehavior = \"allow\" | \"deny\" | \"ask\";\n\n/**\n * `ruleContent` is interpreted by the tool, never by the rule engine (ADR 0010).\n * That is what lets `Bash(git commit:*)` and `Read(~/.ssh/**)` mean entirely\n * different things while the engine that resolves precedence stays tool-agnostic.\n */\nexport interface PermissionSpec<TParams extends TSchema = TSchema> {\n\t/** Behavior when no rule matches. Read-only tools may default to \"allow\". */\n\tdefaultBehavior: PermissionBehavior;\n\n\t/**\n\t * Per-call behavior when no rule matches, for tools whose calls differ in\n\t * nature (bash: launching a command is \"ask\", retrieving or killing an\n\t * already-approved background command is \"allow\"). Return undefined to fall\n\t * back to `defaultBehavior`. Floors and matching rules still outrank it --\n\t * this only replaces the fallthrough, never a rule or a mode floor.\n\t */\n\tdefaultBehaviorFor?(params: Static<TParams>): PermissionBehavior | undefined;\n\n\t/** Prepare canonical operation facts on the validated call before authorization and execution. */\n\tprepareCall?(params: Static<TParams>): void;\n\n\t/**\n\t * Describe, for a human about to approve it, what this call would change.\n\t *\n\t * Called by the gate only once it has resolved to `ask`, so an allowed or denied\n\t * call never pays for it. It must read through the value `prepareCall` stored\n\t * rather than re-deriving a target, which is what keeps the diff the user\n\t * approves and the bytes execution writes the same file (ADR 0029). It must not\n\t * execute the tool, write, or widen what the gate already validated.\n\t */\n\tpreviewCall?(params: Static<TParams>): PermissionPreview;\n\t/** Does this call match this rule's content as an allow rule? */\n\tmatches(ruleContent: string, params: Static<TParams>): boolean;\n\t/** Optional deny matcher. It may identify any prohibited part of a structured call. */\n\tmatchesDeny?(ruleContent: string, params: Static<TParams>): boolean;\n\t/** True when the call contains grammar that cannot be safely authorized by an allow. */\n\tisUnknown?(params: Static<TParams>): boolean;\n\n\t/** Human-readable rendering of a rule, for prompts and denial messages. */\n\tdescribe(ruleContent: string): string;\n\n\t/**\n\t * The rule that would allow this exact call — what \"always allow this\"\n\t * persists. Return null when the call is not generalizable into a rule.\n\t */\n\truleForCall(params: Static<TParams>): string | null;\n}\n\nexport interface ContextSpec {\n\t/**\n\t * True when the result's information is recoverable — the same content can be\n\t * obtained again by re-running the tool or reading the workspace.\n\t *\n\t * ONLY recoverable results may be evicted (Phase 3). A tool whose result cannot\n\t * be regenerated (a nondeterministic command, a consumed one-shot resource)\n\t * must set this false, or eviction would silently destroy information the\n\t * transcript is the only record of.\n\t */\n\tresultRecoverable: boolean;\n\n\t/** Marker substituted for an evicted result. */\n\tevictionMarker?: string;\n\n\t/** Announce by name only; load the parameter schema on demand. */\n\tdeferSchema: boolean;\n\n\t/** Soft cap on result tokens before truncation. */\n\toutputBudgetTokens?: number;\n}\n\nexport type EvidenceKind = \"diff\" | \"test\" | \"command\" | \"manual\" | \"workflow\" | \"diagnostic\";\n\n/** Source-observed command facts. `exitCode` is absent only when execution never began. */\nexport interface CommandEvidenceRecord {\n\tkind: \"command\";\n\tcommand: string;\n\tcwd?: string;\n\texecutable?: string;\n\targv?: string[];\n\texitCode?: number | null;\n}\n\n/** A file mutation is identified by hashes and paths, never raw file or patch contents. */\nexport interface DiffEvidenceRecord {\n\tkind: \"diff\";\n\tpath: string;\n\tpatchHash?: string;\n\tcontentHash?: string;\n\tbyteCount?: number;\n}\n\n/** Zero-filled diagnostic severity buckets for one bounded language-server outcome. */\nexport interface DiagnosticSeverityCounts {\n\terror: number;\n\twarning: number;\n\tinformation: number;\n\thint: number;\n\tunspecified: number;\n\tother: number;\n}\n\n/** Stable durable classification. Free-form server and process errors never enter evidence. */\nexport type DiagnosticUnavailableKind =\n\t| \"no-server\"\n\t| \"disposed\"\n\t| \"unsupported-sync\"\n\t| \"timed-out\"\n\t| \"aborted\"\n\t| \"superseded\"\n\t| \"server-failed\";\n\n/** Bounded post-mutation diagnostic facts, never diagnostic messages or rendered failure reasons. */\nexport type DiagnosticEvidenceRecord =\n\t| {\n\t\t\tkind: \"diagnostic\";\n\t\t\tpath: string;\n\t\t\tstatus: \"ok\";\n\t\t\tserverId: string;\n\t\t\tdiagnosticCount: number;\n\t\t\tseverityCounts: DiagnosticSeverityCounts;\n\t\t\ttruncated: boolean;\n\t  }\n\t| {\n\t\t\tkind: \"diagnostic\";\n\t\t\tpath: string;\n\t\t\tstatus: \"unavailable\";\n\t\t\tserverId?: string;\n\t\t\tunavailableKind: DiagnosticUnavailableKind;\n\t  };\n\n/** How a `test` run actually ended. */\nexport type TestProcessOutcome = \"exit\" | \"signal\" | \"timeout\" | \"cancelled\" | \"spawn-failed\";\n\n/** Bounded argv-based test execution facts. Full output never enters evidence; it lives in artifacts. */\nexport interface TestEvidenceRecord {\n\tkind: \"test\";\n\tcwd: string;\n\texecutable: string;\n\targv: string[];\n\texitCode: number | null;\n\t/** How the run ended. Unset means a legacy record; derive from `exitCode` when reading. */\n\toutcome?: TestProcessOutcome;\n\t/** True when the model-facing view omitted part of a stream (full output lives in artifacts). */\n\toutputTruncated?: boolean;\n}\n\n/** Explicit human attestation; policy decides how, or whether, it is sufficient. */\nexport interface ManualEvidenceRecord {\n\tkind: \"manual\";\n\tvalue?: unknown;\n\tobserved?: unknown;\n\tstatus?: string;\n}\n\n/** Source facts from approval and delegation workflows. */\nexport interface WorkflowEvidenceRecord {\n\tkind: \"workflow\";\n\tplan?: string;\n\tapproved?: boolean;\n\tagentType?: string;\n\ttask?: string;\n\thandle?: string;\n}\n\n/** A structured source record. Policy is a separate consumer, not an additional variant. */\nexport type EvidenceRecord =\n\t| CommandEvidenceRecord\n\t| DiffEvidenceRecord\n\t| DiagnosticEvidenceRecord\n\t| TestEvidenceRecord\n\t| ManualEvidenceRecord\n\t| WorkflowEvidenceRecord;\n\n/** Durable destination for source-level tool evidence. Policy is deliberately not part of this boundary. */\nexport interface EvidenceSink {\n\trecord(entry: { toolName: string; records: EvidenceRecord[] }): void;\n\trecordDiagnostic?(diagnostic: EvidenceCaptureDiagnostic): void;\n}\n\n/** A capture failure is observable but never changes an already-completed tool result. */\nexport interface EvidenceCaptureDiagnostic {\n\ttoolName: string;\n\treason: string;\n}\n\nexport interface EvidenceSpec<TParams extends TSchema = TSchema, TDetails = unknown> {\n\t/** Kinds this tool can emit. Empty set is valid and explicit. */\n\temits: ReadonlySet<EvidenceKind>;\n\n\t/**\n\t * Derive evidence from a completed call. Runs inside the tool's own execution\n\t * path, with access to what actually happened, not a reconstruction from\n\t * rendered output.\n\t */\n\tcapture(params: Static<TParams>, result: AgentToolResult<TDetails>): EvidenceRecord[];\n}\n\nexport interface ToolContract<TParams extends TSchema = TSchema, TDetails = unknown> {\n\tcapabilities: ReadonlySet<Capability>;\n\tpermission: PermissionSpec<TParams>;\n\tcontext: ContextSpec;\n\tevidence: EvidenceSpec<TParams, TDetails>;\n}\n\n/**\n * Apex Code extends upstream ToolDefinition with exactly one required field.\n *\n * `TState` defaults to `any`, matching upstream `ToolDefinition` exactly (not\n * `unknown`). That default is load-bearing: TypeScript compares two instantiations\n * of the *same* generic interface (here, both rooted in `ToolDefinition`) using each\n * type parameter's declared variance, without expanding `Static<TParams>`\n * structurally — but only when every type argument lines up, including the ones a\n * caller left defaulted. A mismatched default reintroduces a full structural check,\n * where `Static<any>` does not behave like `any`, and breaks every pre-existing\n * `ToolDefinition<any, X>`-typed consumer across the codebase.\n */\nexport interface ApexToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>\n\textends ToolDefinition<TParams, TDetails, TState> {\n\tcontract: ToolContract<TParams, TDetails>;\n}\n\n/**\n * Conservative contract for a tool registered without one -- third-party extension\n * tools, which cannot supply a `contract`. MCP tools no longer land here: they reach\n * the model through the built-in `mcp` proxy, whose contract is declared in\n * `core/mcp/contract.ts`. Full capability set (so it can\n * never widen a delegation ceiling), `ask` by default, never evicted, schema\n * deferred, emits nothing. Matching is exact-argument only: a foreign tool's rule\n * authorizes exactly the call it was generated from, never a pattern.\n *\n * This must also be reported as unclassified wherever a consumer describes the tool\n * registry (contracts.md invariant 1) — a conservative default nobody can see is\n * indistinguishable from a bug.\n */\nexport const UNCLASSIFIED: ToolContract<TSchema, unknown> = {\n\tcapabilities: ALL_CAPABILITIES,\n\tpermission: {\n\t\tdefaultBehavior: \"ask\",\n\t\tmatches: (ruleContent, params) => ruleContent === JSON.stringify(params),\n\t\tdescribe: (ruleContent) => `Exact call: ${ruleContent}`,\n\t\truleForCall: (params) => JSON.stringify(params),\n\t},\n\tcontext: { resultRecoverable: false, deferSchema: false },\n\tevidence: { emits: new Set(), capture: () => [] },\n};\n\n/** Resolve a complete tool contract for enforcement consumers. */\nexport function resolveToolContract(\n\tlookup: (toolName: string) => ToolContract | undefined,\n\ttoolName: string,\n): ToolContract {\n\treturn lookup(toolName) ?? UNCLASSIFIED;\n}\n\n/** Resolve the context projection using the same canonical foreign-tool fallback. */\nexport function resolveToolContext(\n\tlookup: (toolName: string) => Pick<ToolContract, \"context\"> | undefined,\n\ttoolName: string,\n): Pick<ToolContract, \"context\"> {\n\treturn lookup(toolName) ?? UNCLASSIFIED;\n}\n\n/**\n * A tool whose call shapes differ, declared so a provider can still see its fields.\n *\n * `Type.Union` compiles to `{ anyOf: [...] }`, which carries no top-level\n * `properties`. The Anthropic request builder reads `properties` and `required`\n * directly (`anthropic-messages.js`, `legacyInputSchema`), so a union reached the\n * model as an object with no fields at all. It then guessed, and our own\n * validation rejected the guess.\n *\n * The union still decides what is valid. `properties` is advertisement, listing\n * every field across the variants so a provider that ignores `anyOf` has\n * something to work from. It deliberately carries no `required`, because no field\n * is required by every variant.\n */\nexport function toolUnion<T extends TSchema[]>(variants: [...T], properties: Record<string, TSchema>) {\n\treturn Type.Union(variants, { type: \"object\", properties });\n}\n"]}

package/dist/core/tools/delegate.d.ts

@@ -1,6 +1,6 @@
 import { type Static, Type } from "typebox";
 import type { DelegationRuntimeOptions } from "../delegation/runtime.ts";
-import type { ApexToolDefinition } from "./contract.ts";
+import { type ApexToolDefinition } from "./contract.ts";
 declare const delegateSchema: Type.TUnion<[Type.TObject<{
     agentType: Type.TString;
     task: Type.TString;
@@ -21,9 +21,11 @@ export interface DelegateDetails {
  * real child through the injected `DelegationRuntimeOptions` -- capability ceiling,
  * derived permission store, and child-session construction all live behind that
  * injection (ADR 0008), matching the `todo_write`/`tool_schema` convention of
- * injecting collaborators rather than reaching for global state. Recursion depth
- * (task 5.3), artifact isolation (task 5.4), and real agent discovery (task 5.5,
- * replacing the resolver a test or caller injects here) are not yet wired.
+ * injecting collaborators rather than reaching for global state. Recursion
+ * depth, artifact isolation, and real agent discovery are wired:
+ * `../delegation/runtime.ts` bounds depth and roots per-child artifact
+ * directories, and `../delegation/agents.ts` supplies production markdown
+ * discovery through the injected resolver.
  */
 export declare function createDelegateToolDefinition(runtime: DelegationRuntimeOptions): ApexToolDefinition<typeof delegateSchema, DelegateDetails>;
 export declare function createDelegateTool(runtime: DelegationRuntimeOptions): import("apex-code-agent-core").AgentTool<Type.TUnion<[Type.TObject<{

package/dist/core/tools/delegate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../../src/core/tools/delegate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,eAAe,CAAC;AAGxE,QAAA,MAAM,cAAc;;;;;;;IAYlB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,wBAAwB,GAC/B,kBAAkB,CAAC,OAAO,cAAc,EAAE,eAAe,CAAC,CAiD5D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,wBAAwB;;;;;;;uBAEnE","sourcesContent":["import { Text } from \"@earendil-works/pi-tui\";\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport { minimatch } from \"minimatch\";\nimport { type Static, Type } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { DelegationRuntimeOptions } from \"../delegation/runtime.ts\";\nimport { retrieveDelegationResult, runDelegation } from \"../delegation/runtime.ts\";\nimport type { ApexToolDefinition, EvidenceRecord } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst delegateSchema = Type.Union([\n\tType.Object({\n\t\tagentType: Type.String({ description: \"The type of subagent to delegate to.\" }),\n\t\ttask: Type.String({ description: \"The task to delegate.\" }),\n\t\tbackground: Type.Optional(\n\t\t\tType.Boolean({ description: \"Return a handle immediately instead of waiting for the child.\" }),\n\t\t),\n\t}),\n\tType.Object({\n\t\tagentType: Type.String({ description: \"The agent type that produced the background result.\" }),\n\t\thandle: Type.String({ description: \"A background delegation handle returned by an earlier call.\" }),\n\t}),\n]);\n\nexport type DelegateInput = Static<typeof delegateSchema>;\n\nexport interface DelegateDetails {\n\tagentType: string;\n\ttask: string;\n\toutput: string;\n\thandle?: string;\n}\n\nfunction formatDelegateCall(input: DelegateInput, theme: Theme): string {\n\tif (\"handle\" in input) {\n\t\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · retrieve`;\n\t}\n\tconst task = input.task.replace(/\\s+/g, \" \").trim();\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · ${theme.fg(\"toolOutput\", task)}`;\n}\n\nfunction formatDelegateResult(details: DelegateDetails, expanded: boolean, theme: Theme): string {\n\tif (expanded) return theme.fg(\"toolOutput\", details.output);\n\tconst lineCount = details.output ? details.output.split(\"\\n\").length : 0;\n\treturn `${theme.fg(\"accent\", details.agentType)} · ${lineCount} ${lineCount === 1 ? \"line\" : \"lines\"}`;\n}\n\n/**\n * The delegation entry point (task 4.6's contract, task 5.2's execution). Runs a\n * real child through the injected `DelegationRuntimeOptions` -- capability ceiling,\n * derived permission store, and child-session construction all live behind that\n * injection (ADR 0008), matching the `todo_write`/`tool_schema` convention of\n * injecting collaborators rather than reaching for global state. Recursion depth\n * (task 5.3), artifact isolation (task 5.4), and real agent discovery (task 5.5,\n * replacing the resolver a test or caller injects here) are not yet wired.\n */\nexport function createDelegateToolDefinition(\n\truntime: DelegationRuntimeOptions,\n): ApexToolDefinition<typeof delegateSchema, DelegateDetails> {\n\treturn {\n\t\tname: \"delegate\",\n\t\tlabel: \"delegate\",\n\t\tdescription: \"Delegate a task to a subagent.\",\n\t\tparameters: delegateSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"delegate\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"ask\",\n\t\t\t\tmatches: (ruleContent, params) => minimatch(params.agentType, ruleContent),\n\t\t\t\tdescribe: (ruleContent) => `Delegate to agent types matching \"${ruleContent}\"`,\n\t\t\t\truleForCall: (params) => params.agentType,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: {\n\t\t\t\temits: new Set([\"workflow\"]),\n\t\t\t\tcapture: (params): EvidenceRecord[] =>\n\t\t\t\t\t\"task\" in params\n\t\t\t\t\t\t? [{ kind: \"workflow\", agentType: params.agentType, task: params.task }]\n\t\t\t\t\t\t: [{ kind: \"workflow\", agentType: params.agentType, handle: params.handle }],\n\t\t\t},\n\t\t},\n\t\tasync execute(_toolCallId, input: DelegateInput): Promise<AgentToolResult<DelegateDetails>> {\n\t\t\tconst result =\n\t\t\t\t\"task\" in input\n\t\t\t\t\t? await runDelegation(runtime, input.agentType, input.task, { background: input.background })\n\t\t\t\t\t: await retrieveDelegationResult(runtime, input.handle, input.agentType);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: result.output }],\n\t\t\t\tdetails: {\n\t\t\t\t\tagentType: result.agentType,\n\t\t\t\t\ttask: result.task,\n\t\t\t\t\toutput: result.output,\n\t\t\t\t\thandle: result.handleId,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t\trenderCall(input, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateCall(input, theme));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateResult(result.details, options.expanded, theme));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createDelegateTool(runtime: DelegationRuntimeOptions) {\n\treturn wrapToolDefinition(createDelegateToolDefinition(runtime));\n}\n"]}
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../../src/core/tools/delegate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,EAAE,KAAK,kBAAkB,EAAkC,MAAM,eAAe,CAAC;AAgBxF,QAAA,MAAM,cAAc;;;;;;;IAUnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC3C,OAAO,EAAE,wBAAwB,GAC/B,kBAAkB,CAAC,OAAO,cAAc,EAAE,eAAe,CAAC,CAiD5D;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,wBAAwB;;;;;;;uBAEnE","sourcesContent":["import { Text } from \"@earendil-works/pi-tui\";\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport { minimatch } from \"minimatch\";\nimport { type Static, Type } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { DelegationRuntimeOptions } from \"../delegation/runtime.ts\";\nimport { retrieveDelegationResult, runDelegation } from \"../delegation/runtime.ts\";\nimport { type ApexToolDefinition, type EvidenceRecord, toolUnion } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst delegateSchemaProperties = {\n\tagentType: Type.String({\n\t\tdescription: \"The subagent type. Required both to launch a task and to retrieve a background result.\",\n\t}),\n\ttask: Type.String({ description: \"The task to delegate. Supply it to launch a delegation.\" }),\n\tbackground: Type.Optional(\n\t\tType.Boolean({ description: \"Return a handle immediately instead of waiting for the child.\" }),\n\t),\n\thandle: Type.String({\n\t\tdescription: \"A background delegation handle returned by an earlier call. Supply it to retrieve the result.\",\n\t}),\n};\n\nconst delegateSchema = toolUnion(\n\t[\n\t\tType.Object({\n\t\t\tagentType: Type.String(),\n\t\t\ttask: Type.String(),\n\t\t\tbackground: Type.Optional(Type.Boolean()),\n\t\t}),\n\t\tType.Object({ agentType: Type.String(), handle: Type.String() }),\n\t],\n\tdelegateSchemaProperties,\n);\n\nexport type DelegateInput = Static<typeof delegateSchema>;\n\nexport interface DelegateDetails {\n\tagentType: string;\n\ttask: string;\n\toutput: string;\n\thandle?: string;\n}\n\nfunction formatDelegateCall(input: DelegateInput, theme: Theme): string {\n\tif (\"handle\" in input) {\n\t\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · retrieve`;\n\t}\n\tconst task = input.task.replace(/\\s+/g, \" \").trim();\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · ${theme.fg(\"toolOutput\", task)}`;\n}\n\nfunction formatDelegateResult(details: DelegateDetails, expanded: boolean, theme: Theme): string {\n\tif (expanded) return theme.fg(\"toolOutput\", details.output);\n\tconst lineCount = details.output ? details.output.split(\"\\n\").length : 0;\n\treturn `${theme.fg(\"accent\", details.agentType)} · ${lineCount} ${lineCount === 1 ? \"line\" : \"lines\"}`;\n}\n\n/**\n * The delegation entry point (task 4.6's contract, task 5.2's execution). Runs a\n * real child through the injected `DelegationRuntimeOptions` -- capability ceiling,\n * derived permission store, and child-session construction all live behind that\n * injection (ADR 0008), matching the `todo_write`/`tool_schema` convention of\n * injecting collaborators rather than reaching for global state. Recursion\n * depth, artifact isolation, and real agent discovery are wired:\n * `../delegation/runtime.ts` bounds depth and roots per-child artifact\n * directories, and `../delegation/agents.ts` supplies production markdown\n * discovery through the injected resolver.\n */\nexport function createDelegateToolDefinition(\n\truntime: DelegationRuntimeOptions,\n): ApexToolDefinition<typeof delegateSchema, DelegateDetails> {\n\treturn {\n\t\tname: \"delegate\",\n\t\tlabel: \"delegate\",\n\t\tdescription: \"Delegate a task to a subagent.\",\n\t\tparameters: delegateSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"delegate\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"ask\",\n\t\t\t\tmatches: (ruleContent, params) => minimatch(params.agentType, ruleContent),\n\t\t\t\tdescribe: (ruleContent) => `Delegate to agent types matching \"${ruleContent}\"`,\n\t\t\t\truleForCall: (params) => params.agentType,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: {\n\t\t\t\temits: new Set([\"workflow\"]),\n\t\t\t\tcapture: (params): EvidenceRecord[] =>\n\t\t\t\t\t\"task\" in params\n\t\t\t\t\t\t? [{ kind: \"workflow\", agentType: params.agentType, task: params.task }]\n\t\t\t\t\t\t: [{ kind: \"workflow\", agentType: params.agentType, handle: params.handle }],\n\t\t\t},\n\t\t},\n\t\tasync execute(_toolCallId, input: DelegateInput): Promise<AgentToolResult<DelegateDetails>> {\n\t\t\tconst result =\n\t\t\t\t\"task\" in input\n\t\t\t\t\t? await runDelegation(runtime, input.agentType, input.task, { background: input.background })\n\t\t\t\t\t: await retrieveDelegationResult(runtime, input.handle, input.agentType);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: result.output }],\n\t\t\t\tdetails: {\n\t\t\t\t\tagentType: result.agentType,\n\t\t\t\t\ttask: result.task,\n\t\t\t\t\toutput: result.output,\n\t\t\t\t\thandle: result.handleId,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t\trenderCall(input, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateCall(input, theme));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateResult(result.details, options.expanded, theme));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createDelegateTool(runtime: DelegationRuntimeOptions) {\n\treturn wrapToolDefinition(createDelegateToolDefinition(runtime));\n}\n"]}

package/dist/core/tools/delegate.js

@@ -2,18 +2,26 @@ import { Text } from "@earendil-works/pi-tui";
 import { minimatch } from "minimatch";
 import { Type } from "typebox";
 import { retrieveDelegationResult, runDelegation } from "../delegation/runtime.js";
+import { toolUnion } from "./contract.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
-const delegateSchema = Type.Union([
-    Type.Object({
-        agentType: Type.String({ description: "The type of subagent to delegate to." }),
-        task: Type.String({ description: "The task to delegate." }),
-        background: Type.Optional(Type.Boolean({ description: "Return a handle immediately instead of waiting for the child." })),
+const delegateSchemaProperties = {
+    agentType: Type.String({
+        description: "The subagent type. Required both to launch a task and to retrieve a background result.",
+    }),
+    task: Type.String({ description: "The task to delegate. Supply it to launch a delegation." }),
+    background: Type.Optional(Type.Boolean({ description: "Return a handle immediately instead of waiting for the child." })),
+    handle: Type.String({
+        description: "A background delegation handle returned by an earlier call. Supply it to retrieve the result.",
     }),
+};
+const delegateSchema = toolUnion([
     Type.Object({
-        agentType: Type.String({ description: "The agent type that produced the background result." }),
-        handle: Type.String({ description: "A background delegation handle returned by an earlier call." }),
+        agentType: Type.String(),
+        task: Type.String(),
+        background: Type.Optional(Type.Boolean()),
     }),
-]);
+    Type.Object({ agentType: Type.String(), handle: Type.String() }),
+], delegateSchemaProperties);
 function formatDelegateCall(input, theme) {
     if ("handle" in input) {
         return `${theme.fg("toolTitle", theme.bold("delegate"))} ${theme.fg("accent", input.agentType)} · retrieve`;
@@ -32,9 +40,11 @@ function formatDelegateResult(details, expanded, theme) {
  * real child through the injected `DelegationRuntimeOptions` -- capability ceiling,
  * derived permission store, and child-session construction all live behind that
  * injection (ADR 0008), matching the `todo_write`/`tool_schema` convention of
- * injecting collaborators rather than reaching for global state. Recursion depth
- * (task 5.3), artifact isolation (task 5.4), and real agent discovery (task 5.5,
- * replacing the resolver a test or caller injects here) are not yet wired.
+ * injecting collaborators rather than reaching for global state. Recursion
+ * depth, artifact isolation, and real agent discovery are wired:
+ * `../delegation/runtime.ts` bounds depth and roots per-child artifact
+ * directories, and `../delegation/agents.ts` supplies production markdown
+ * discovery through the injected resolver.
  */
 export function createDelegateToolDefinition(runtime) {
     return {

package/dist/core/tools/delegate.js.map

@@ -1 +1 @@
-{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../../../src/core/tools/delegate.ts"],"names":[],"mappings":"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","sourcesContent":["import { Text } from \"@earendil-works/pi-tui\";\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport { minimatch } from \"minimatch\";\nimport { type Static, Type } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { DelegationRuntimeOptions } from \"../delegation/runtime.ts\";\nimport { retrieveDelegationResult, runDelegation } from \"../delegation/runtime.ts\";\nimport type { ApexToolDefinition, EvidenceRecord } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst delegateSchema = Type.Union([\n\tType.Object({\n\t\tagentType: Type.String({ description: \"The type of subagent to delegate to.\" }),\n\t\ttask: Type.String({ description: \"The task to delegate.\" }),\n\t\tbackground: Type.Optional(\n\t\t\tType.Boolean({ description: \"Return a handle immediately instead of waiting for the child.\" }),\n\t\t),\n\t}),\n\tType.Object({\n\t\tagentType: Type.String({ description: \"The agent type that produced the background result.\" }),\n\t\thandle: Type.String({ description: \"A background delegation handle returned by an earlier call.\" }),\n\t}),\n]);\n\nexport type DelegateInput = Static<typeof delegateSchema>;\n\nexport interface DelegateDetails {\n\tagentType: string;\n\ttask: string;\n\toutput: string;\n\thandle?: string;\n}\n\nfunction formatDelegateCall(input: DelegateInput, theme: Theme): string {\n\tif (\"handle\" in input) {\n\t\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · retrieve`;\n\t}\n\tconst task = input.task.replace(/\\s+/g, \" \").trim();\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · ${theme.fg(\"toolOutput\", task)}`;\n}\n\nfunction formatDelegateResult(details: DelegateDetails, expanded: boolean, theme: Theme): string {\n\tif (expanded) return theme.fg(\"toolOutput\", details.output);\n\tconst lineCount = details.output ? details.output.split(\"\\n\").length : 0;\n\treturn `${theme.fg(\"accent\", details.agentType)} · ${lineCount} ${lineCount === 1 ? \"line\" : \"lines\"}`;\n}\n\n/**\n * The delegation entry point (task 4.6's contract, task 5.2's execution). Runs a\n * real child through the injected `DelegationRuntimeOptions` -- capability ceiling,\n * derived permission store, and child-session construction all live behind that\n * injection (ADR 0008), matching the `todo_write`/`tool_schema` convention of\n * injecting collaborators rather than reaching for global state. Recursion depth\n * (task 5.3), artifact isolation (task 5.4), and real agent discovery (task 5.5,\n * replacing the resolver a test or caller injects here) are not yet wired.\n */\nexport function createDelegateToolDefinition(\n\truntime: DelegationRuntimeOptions,\n): ApexToolDefinition<typeof delegateSchema, DelegateDetails> {\n\treturn {\n\t\tname: \"delegate\",\n\t\tlabel: \"delegate\",\n\t\tdescription: \"Delegate a task to a subagent.\",\n\t\tparameters: delegateSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"delegate\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"ask\",\n\t\t\t\tmatches: (ruleContent, params) => minimatch(params.agentType, ruleContent),\n\t\t\t\tdescribe: (ruleContent) => `Delegate to agent types matching \"${ruleContent}\"`,\n\t\t\t\truleForCall: (params) => params.agentType,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: {\n\t\t\t\temits: new Set([\"workflow\"]),\n\t\t\t\tcapture: (params): EvidenceRecord[] =>\n\t\t\t\t\t\"task\" in params\n\t\t\t\t\t\t? [{ kind: \"workflow\", agentType: params.agentType, task: params.task }]\n\t\t\t\t\t\t: [{ kind: \"workflow\", agentType: params.agentType, handle: params.handle }],\n\t\t\t},\n\t\t},\n\t\tasync execute(_toolCallId, input: DelegateInput): Promise<AgentToolResult<DelegateDetails>> {\n\t\t\tconst result =\n\t\t\t\t\"task\" in input\n\t\t\t\t\t? await runDelegation(runtime, input.agentType, input.task, { background: input.background })\n\t\t\t\t\t: await retrieveDelegationResult(runtime, input.handle, input.agentType);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: result.output }],\n\t\t\t\tdetails: {\n\t\t\t\t\tagentType: result.agentType,\n\t\t\t\t\ttask: result.task,\n\t\t\t\t\toutput: result.output,\n\t\t\t\t\thandle: result.handleId,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t\trenderCall(input, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateCall(input, theme));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateResult(result.details, options.expanded, theme));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createDelegateTool(runtime: DelegationRuntimeOptions) {\n\treturn wrapToolDefinition(createDelegateToolDefinition(runtime));\n}\n"]}
+{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../../../src/core/tools/delegate.ts"],"names":[],"mappings":"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","sourcesContent":["import { Text } from \"@earendil-works/pi-tui\";\nimport type { AgentToolResult } from \"apex-code-agent-core\";\nimport { minimatch } from \"minimatch\";\nimport { type Static, Type } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { DelegationRuntimeOptions } from \"../delegation/runtime.ts\";\nimport { retrieveDelegationResult, runDelegation } from \"../delegation/runtime.ts\";\nimport { type ApexToolDefinition, type EvidenceRecord, toolUnion } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst delegateSchemaProperties = {\n\tagentType: Type.String({\n\t\tdescription: \"The subagent type. Required both to launch a task and to retrieve a background result.\",\n\t}),\n\ttask: Type.String({ description: \"The task to delegate. Supply it to launch a delegation.\" }),\n\tbackground: Type.Optional(\n\t\tType.Boolean({ description: \"Return a handle immediately instead of waiting for the child.\" }),\n\t),\n\thandle: Type.String({\n\t\tdescription: \"A background delegation handle returned by an earlier call. Supply it to retrieve the result.\",\n\t}),\n};\n\nconst delegateSchema = toolUnion(\n\t[\n\t\tType.Object({\n\t\t\tagentType: Type.String(),\n\t\t\ttask: Type.String(),\n\t\t\tbackground: Type.Optional(Type.Boolean()),\n\t\t}),\n\t\tType.Object({ agentType: Type.String(), handle: Type.String() }),\n\t],\n\tdelegateSchemaProperties,\n);\n\nexport type DelegateInput = Static<typeof delegateSchema>;\n\nexport interface DelegateDetails {\n\tagentType: string;\n\ttask: string;\n\toutput: string;\n\thandle?: string;\n}\n\nfunction formatDelegateCall(input: DelegateInput, theme: Theme): string {\n\tif (\"handle\" in input) {\n\t\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · retrieve`;\n\t}\n\tconst task = input.task.replace(/\\s+/g, \" \").trim();\n\treturn `${theme.fg(\"toolTitle\", theme.bold(\"delegate\"))} ${theme.fg(\"accent\", input.agentType)} · ${theme.fg(\"toolOutput\", task)}`;\n}\n\nfunction formatDelegateResult(details: DelegateDetails, expanded: boolean, theme: Theme): string {\n\tif (expanded) return theme.fg(\"toolOutput\", details.output);\n\tconst lineCount = details.output ? details.output.split(\"\\n\").length : 0;\n\treturn `${theme.fg(\"accent\", details.agentType)} · ${lineCount} ${lineCount === 1 ? \"line\" : \"lines\"}`;\n}\n\n/**\n * The delegation entry point (task 4.6's contract, task 5.2's execution). Runs a\n * real child through the injected `DelegationRuntimeOptions` -- capability ceiling,\n * derived permission store, and child-session construction all live behind that\n * injection (ADR 0008), matching the `todo_write`/`tool_schema` convention of\n * injecting collaborators rather than reaching for global state. Recursion\n * depth, artifact isolation, and real agent discovery are wired:\n * `../delegation/runtime.ts` bounds depth and roots per-child artifact\n * directories, and `../delegation/agents.ts` supplies production markdown\n * discovery through the injected resolver.\n */\nexport function createDelegateToolDefinition(\n\truntime: DelegationRuntimeOptions,\n): ApexToolDefinition<typeof delegateSchema, DelegateDetails> {\n\treturn {\n\t\tname: \"delegate\",\n\t\tlabel: \"delegate\",\n\t\tdescription: \"Delegate a task to a subagent.\",\n\t\tparameters: delegateSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"delegate\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"ask\",\n\t\t\t\tmatches: (ruleContent, params) => minimatch(params.agentType, ruleContent),\n\t\t\t\tdescribe: (ruleContent) => `Delegate to agent types matching \"${ruleContent}\"`,\n\t\t\t\truleForCall: (params) => params.agentType,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: {\n\t\t\t\temits: new Set([\"workflow\"]),\n\t\t\t\tcapture: (params): EvidenceRecord[] =>\n\t\t\t\t\t\"task\" in params\n\t\t\t\t\t\t? [{ kind: \"workflow\", agentType: params.agentType, task: params.task }]\n\t\t\t\t\t\t: [{ kind: \"workflow\", agentType: params.agentType, handle: params.handle }],\n\t\t\t},\n\t\t},\n\t\tasync execute(_toolCallId, input: DelegateInput): Promise<AgentToolResult<DelegateDetails>> {\n\t\t\tconst result =\n\t\t\t\t\"task\" in input\n\t\t\t\t\t? await runDelegation(runtime, input.agentType, input.task, { background: input.background })\n\t\t\t\t\t: await retrieveDelegationResult(runtime, input.handle, input.agentType);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: result.output }],\n\t\t\t\tdetails: {\n\t\t\t\t\tagentType: result.agentType,\n\t\t\t\t\ttask: result.task,\n\t\t\t\t\toutput: result.output,\n\t\t\t\t\thandle: result.handleId,\n\t\t\t\t},\n\t\t\t};\n\t\t},\n\t\trenderCall(input, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateCall(input, theme));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatDelegateResult(result.details, options.expanded, theme));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createDelegateTool(runtime: DelegationRuntimeOptions) {\n\treturn wrapToolDefinition(createDelegateToolDefinition(runtime));\n}\n"]}

package/dist/core/tools/edit-diff.d.ts

@@ -60,11 +60,46 @@ export interface AppliedEditsResult {
  * Unicode quotes/dashes normalized to ASCII).
  */
 export declare function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult;
-/** Strip UTF-8 BOM if present, return both the BOM (if any) and the text without it */
-export declare function stripBom(content: string): {
-    bom: string;
-    text: string;
-};
+/**
+ * Explicit budgets for the advisory edit-failure diagnostics below. Diagnostics
+ * are a best-effort hint, never an apply path, so every dimension of the scan
+ * is bounded and the ordinary failure is returned untouched when a bound is
+ * exceeded (spec 2026-09-01-tool-reliability-and-execution-budgets.md § 2).
+ */
+export declare const EDIT_DIAGNOSTIC_MAX_FILE_BYTES = 1048576;
+export declare const EDIT_DIAGNOSTIC_MAX_TARGET_BYTES = 65536;
+export declare const EDIT_DIAGNOSTIC_MAX_CANDIDATES = 3;
+export declare const EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS = 20000;
+export declare const EDIT_DIAGNOSTIC_MAX_OCCURRENCES = 5;
+export declare const EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS = 160;
+export interface EditCandidateLocation {
+    /** 1-based, inclusive. */
+    startLine: number;
+    /** 1-based, inclusive. */
+    endLine: number;
+    /** Bigram Dice similarity against the failed target, rounded to two decimals. */
+    similarity: number;
+    /** Bounded snippet of the candidate source lines, each line-numbered. */
+    snippet: string;
+}
+/**
+ * Advisory diagnostics attached to a failed edit match. These describe where a
+ * target almost matched or where duplicates live; they are never a replacement
+ * location and must never be applied.
+ */
+export interface EditFailureDiagnostics {
+    kind: "missing-match" | "duplicate-match";
+    candidates: EditCandidateLocation[];
+    /** 1-based source lines of up to EDIT_DIAGNOSTIC_MAX_OCCURRENCES duplicates. */
+    occurrenceLines: number[];
+    omittedOccurrences: number;
+    /** True when the scan stopped at a work or time bound before finishing. */
+    scanTruncated: boolean;
+    /** Set when scanning was unsafe or oversized; no candidates are reported. */
+    unavailableReason?: string;
+}
+/** Render advisory diagnostics as an error-message appendix. Empty when there is nothing to say. */
+export declare function formatEditFailureDiagnostics(diagnostics: EditFailureDiagnostics | undefined): string;
 /**
  * Apply one or more exact-text replacements to LF-normalized content.
  *
@@ -97,6 +132,14 @@ export interface EditDiffError {
  * Used for preview rendering in the TUI before the tool executes.
  */
 export declare function computeEditsDiff(path: string, edits: Edit[], cwd: string): Promise<EditDiffResult | EditDiffError>;
+/**
+ * The half of `computeEditsDiff` that does not choose which bytes to read.
+ *
+ * The permission preview must describe the operation the gate authorized rather
+ * than whatever the pathname resolves to a second time, so it supplies content
+ * read through the prepared operation and calls this (ADR 0029).
+ */
+export declare function computeEditsDiffFromContent(path: string, rawContent: string, edits: Edit[]): EditDiffResult | EditDiffError;
 /**
  * Compute the diff for a single edit operation without applying it.
  * Kept as a convenience wrapper for single-edit callers.

package/dist/core/tools/edit-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit-diff.d.ts","sourceRoot":"","sources":["../../../src/core/tools/edit-diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared diff computation utilities for the edit and similar tools.\n */\n\nimport * as Diff from \"diff\";\nimport { constants } from \"fs\";\nimport { access, readFile } from \"fs/promises\";\nimport { resolveToCwd } from \"./path-utils.ts\";\n\nexport function detectLineEnding(content: string): \"\\r\\n\" | \"\\n\" {\n\tconst crlfIdx = content.indexOf(\"\\r\\n\");\n\tconst lfIdx = content.indexOf(\"\\n\");\n\tif (lfIdx === -1) return \"\\n\";\n\tif (crlfIdx === -1) return \"\\n\";\n\treturn crlfIdx < lfIdx ? \"\\r\\n\" : \"\\n\";\n}\n\nexport function normalizeToLF(text: string): string {\n\treturn text.replace(/\\r\\n/g, \"\\n\").replace(/\\r/g, \"\\n\");\n}\n\nexport function restoreLineEndings(text: string, ending: \"\\r\\n\" | \"\\n\"): string {\n\treturn ending === \"\\r\\n\" ? text.replace(/\\n/g, \"\\r\\n\") : text;\n}\n\n/**\n * Normalize text for fuzzy matching. Applies progressive transformations:\n * - Strip trailing whitespace from each line\n * - Normalize smart quotes to ASCII equivalents\n * - Normalize Unicode dashes/hyphens to ASCII hyphen\n * - Normalize special Unicode spaces to regular space\n */\nexport function normalizeForFuzzyMatch(text: string): string {\n\treturn (\n\t\ttext\n\t\t\t.normalize(\"NFKC\")\n\t\t\t// Strip trailing whitespace per line\n\t\t\t.split(\"\\n\")\n\t\t\t.map((line) => line.trimEnd())\n\t\t\t.join(\"\\n\")\n\t\t\t// Smart single quotes → '\n\t\t\t.replace(/[\\u2018\\u2019\\u201A\\u201B]/g, \"'\")\n\t\t\t// Smart double quotes → \"\n\t\t\t.replace(/[\\u201C\\u201D\\u201E\\u201F]/g, '\"')\n\t\t\t// Various dashes/hyphens → -\n\t\t\t// U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,\n\t\t\t// U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus\n\t\t\t.replace(/[\\u2010\\u2011\\u2012\\u2013\\u2014\\u2015\\u2212]/g, \"-\")\n\t\t\t// Special spaces → regular space\n\t\t\t// U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,\n\t\t\t// U+205F medium math space, U+3000 ideographic space\n\t\t\t.replace(/[\\u00A0\\u2002-\\u200A\\u202F\\u205F\\u3000]/g, \" \")\n\t);\n}\n\nfunction splitLinesWithEndings(content: string): string[] {\n\treturn content.match(/[^\\n]*\\n|[^\\n]+/g) ?? [];\n}\n\ninterface LineSpan {\n\tstart: number;\n\tend: number;\n}\n\ninterface MatchedEdit {\n\teditIndex: number;\n\tmatchIndex: number;\n\tmatchLength: number;\n\tnewText: string;\n}\n\ntype TextReplacement = Pick<MatchedEdit, \"matchIndex\" | \"matchLength\" | \"newText\">;\n\nfunction getLineSpans(content: string): LineSpan[] {\n\tlet offset = 0;\n\treturn splitLinesWithEndings(content).map((line) => {\n\t\tconst span = { start: offset, end: offset + line.length };\n\t\toffset = span.end;\n\t\treturn span;\n\t});\n}\n\nfunction getReplacementLineRange(lines: LineSpan[], replacement: TextReplacement) {\n\tconst replacementStart = replacement.matchIndex;\n\tconst replacementEnd = replacement.matchIndex + replacement.matchLength;\n\n\tlet startLine = -1;\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (replacementStart >= line.start && replacementStart < line.end) {\n\t\t\tstartLine = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (startLine === -1) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\tlet endLine = startLine;\n\twhile (endLine < lines.length && lines[endLine].end < replacementEnd) {\n\t\tendLine++;\n\t}\n\tif (endLine >= lines.length) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\treturn { startLine, endLine: endLine + 1 };\n}\n\nfunction applyReplacements(content: string, replacements: TextReplacement[], offset = 0): string {\n\tlet result = content;\n\tfor (let i = replacements.length - 1; i >= 0; i--) {\n\t\tconst replacement = replacements[i];\n\t\tconst matchIndex = replacement.matchIndex - offset;\n\t\tresult =\n\t\t\tresult.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);\n\t}\n\treturn result;\n}\n\n/**\n * Apply replacements matched against `baseContent` to `originalContent` while\n * preserving unchanged line blocks from the original.\n *\n * This is useful when `baseContent` is a normalized view of the original. Each\n * replacement is widened to the lines it actually touches, those touched lines\n * are rewritten from the normalized base, and all other lines are copied back\n * from `originalContent`. The actual replacement ranges drive preservation so\n * duplicate normalized lines cannot be aligned to the wrong occurrence.\n */\nexport function applyReplacementsPreservingUnchangedLines(\n\toriginalContent: string,\n\tbaseContent: string,\n\treplacements: TextReplacement[],\n): string {\n\tconst originalLines = splitLinesWithEndings(originalContent);\n\tconst baseLines = getLineSpans(baseContent);\n\tif (originalLines.length !== baseLines.length) {\n\t\tthrow new Error(\"Cannot preserve unchanged lines because the base content has a different line count.\");\n\t}\n\n\tconst groups: Array<{ startLine: number; endLine: number; replacements: TextReplacement[] }> = [];\n\tconst sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (const replacement of sortedReplacements) {\n\t\tconst range = getReplacementLineRange(baseLines, replacement);\n\t\tconst current = groups[groups.length - 1];\n\t\tif (current && range.startLine < current.endLine) {\n\t\t\tcurrent.endLine = Math.max(current.endLine, range.endLine);\n\t\t\tcurrent.replacements.push(replacement);\n\t\t\tcontinue;\n\t\t}\n\t\tgroups.push({ ...range, replacements: [replacement] });\n\t}\n\n\tlet originalLineIndex = 0;\n\tlet result = \"\";\n\tfor (const group of groups) {\n\t\tresult += originalLines.slice(originalLineIndex, group.startLine).join(\"\");\n\n\t\tconst groupStartOffset = baseLines[group.startLine].start;\n\t\tconst groupEndOffset = baseLines[group.endLine - 1].end;\n\t\tresult += applyReplacements(\n\t\t\tbaseContent.slice(groupStartOffset, groupEndOffset),\n\t\t\tgroup.replacements,\n\t\t\tgroupStartOffset,\n\t\t);\n\t\toriginalLineIndex = group.endLine;\n\t}\n\tresult += originalLines.slice(originalLineIndex).join(\"\");\n\n\treturn result;\n}\n\nexport interface FuzzyMatchResult {\n\t/** Whether a match was found */\n\tfound: boolean;\n\t/** The index where the match starts (in the content that should be used for replacement) */\n\tindex: number;\n\t/** Length of the matched text */\n\tmatchLength: number;\n\t/** Whether fuzzy matching was used (false = exact match) */\n\tusedFuzzyMatch: boolean;\n\t/**\n\t * The content to use for replacement operations.\n\t * When exact match: original content. When fuzzy match: normalized content.\n\t */\n\tcontentForReplacement: string;\n}\n\nexport interface Edit {\n\toldText: string;\n\tnewText: string;\n}\n\nexport interface AppliedEditsResult {\n\tbaseContent: string;\n\tnewContent: string;\n}\n\n/**\n * Find oldText in content, trying exact match first, then fuzzy match.\n * When fuzzy matching is used, the returned contentForReplacement is the\n * fuzzy-normalized version of the content (trailing whitespace stripped,\n * Unicode quotes/dashes normalized to ASCII).\n */\nexport function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult {\n\t// Try exact match first\n\tconst exactIndex = content.indexOf(oldText);\n\tif (exactIndex !== -1) {\n\t\treturn {\n\t\t\tfound: true,\n\t\t\tindex: exactIndex,\n\t\t\tmatchLength: oldText.length,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// Try fuzzy match - work entirely in normalized space\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\tconst fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);\n\n\tif (fuzzyIndex === -1) {\n\t\treturn {\n\t\t\tfound: false,\n\t\t\tindex: -1,\n\t\t\tmatchLength: 0,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// When fuzzy matching, return offsets in normalized space. Callers can use\n\t// the normalized content to compute replacements, then decide how much of\n\t// that normalized output should be written back.\n\treturn {\n\t\tfound: true,\n\t\tindex: fuzzyIndex,\n\t\tmatchLength: fuzzyOldText.length,\n\t\tusedFuzzyMatch: true,\n\t\tcontentForReplacement: fuzzyContent,\n\t};\n}\n\n/** Strip UTF-8 BOM if present, return both the BOM (if any) and the text without it */\nexport function stripBom(content: string): { bom: string; text: string } {\n\treturn content.startsWith(\"\\uFEFF\") ? { bom: \"\\uFEFF\", text: content.slice(1) } : { bom: \"\", text: content };\n}\n\nfunction countOccurrences(content: string, oldText: string): number {\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\treturn fuzzyContent.split(fuzzyOldText).length - 1;\n}\n\nfunction getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,\n\t);\n}\n\nfunction getDuplicateError(path: string, editIndex: number, totalEdits: number, occurrences: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Found ${occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Found ${occurrences} occurrences of edits[${editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`,\n\t);\n}\n\nfunction getEmptyOldTextError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(`oldText must not be empty in ${path}.`);\n\t}\n\treturn new Error(`edits[${editIndex}].oldText must not be empty in ${path}.`);\n}\n\nfunction getNoChangeError(path: string, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,\n\t\t);\n\t}\n\treturn new Error(`No changes made to ${path}. The replacements produced identical content.`);\n}\n\n/**\n * Apply one or more exact-text replacements to LF-normalized content.\n *\n * All edits are matched against the same original content. Replacements are\n * then applied in reverse order so offsets remain stable. If any edit needs\n * fuzzy matching, the operation runs in fuzzy-normalized content space and then\n * overlays those line-level changes onto the original content so unchanged line\n * blocks keep their original bytes.\n */\nexport function applyEditsToNormalizedContent(\n\tnormalizedContent: string,\n\tedits: Edit[],\n\tpath: string,\n): AppliedEditsResult {\n\tconst normalizedEdits = edits.map((edit) => ({\n\t\toldText: normalizeToLF(edit.oldText),\n\t\tnewText: normalizeToLF(edit.newText),\n\t}));\n\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tif (normalizedEdits[i].oldText.length === 0) {\n\t\t\tthrow getEmptyOldTextError(path, i, normalizedEdits.length);\n\t\t}\n\t}\n\n\tconst initialMatches = normalizedEdits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));\n\tconst usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);\n\tconst replacementBaseContent = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;\n\n\tconst matchedEdits: MatchedEdit[] = [];\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tconst edit = normalizedEdits[i];\n\t\tconst matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);\n\t\tif (!matchResult.found) {\n\t\t\tthrow getNotFoundError(path, i, normalizedEdits.length);\n\t\t}\n\n\t\tconst occurrences = countOccurrences(replacementBaseContent, edit.oldText);\n\t\tif (occurrences > 1) {\n\t\t\tthrow getDuplicateError(path, i, normalizedEdits.length, occurrences);\n\t\t}\n\n\t\tmatchedEdits.push({\n\t\t\teditIndex: i,\n\t\t\tmatchIndex: matchResult.index,\n\t\t\tmatchLength: matchResult.matchLength,\n\t\t\tnewText: edit.newText,\n\t\t});\n\t}\n\n\tmatchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (let i = 1; i < matchedEdits.length; i++) {\n\t\tconst previous = matchedEdits[i - 1];\n\t\tconst current = matchedEdits[i];\n\t\tif (previous.matchIndex + previous.matchLength > current.matchIndex) {\n\t\t\tthrow new Error(\n\t\t\t\t`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst baseContent = normalizedContent;\n\tconst newContent = usedFuzzyMatch\n\t\t? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)\n\t\t: applyReplacements(replacementBaseContent, matchedEdits);\n\n\tif (baseContent === newContent) {\n\t\tthrow getNoChangeError(path, normalizedEdits.length);\n\t}\n\n\treturn { baseContent, newContent };\n}\n\n/** Generate a standard unified patch. */\nexport function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines = 4): string {\n\treturn Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, {\n\t\tcontext: contextLines,\n\t\theaderOptions: Diff.FILE_HEADERS_ONLY,\n\t});\n}\n\n/**\n * Generate a display-oriented diff string with line numbers and context.\n * Returns both the diff string and the first changed line number (in the new file).\n */\nexport function generateDiffString(\n\toldContent: string,\n\tnewContent: string,\n\tcontextLines = 4,\n): { diff: string; firstChangedLine: number | undefined } {\n\tconst parts = Diff.diffLines(oldContent, newContent);\n\tconst output: string[] = [];\n\n\tconst oldLines = oldContent.split(\"\\n\");\n\tconst newLines = newContent.split(\"\\n\");\n\tconst maxLineNum = Math.max(oldLines.length, newLines.length);\n\tconst lineNumWidth = String(maxLineNum).length;\n\n\tlet oldLineNum = 1;\n\tlet newLineNum = 1;\n\tlet lastWasChange = false;\n\tlet firstChangedLine: number | undefined;\n\n\tfor (let i = 0; i < parts.length; i++) {\n\t\tconst part = parts[i];\n\t\tconst raw = part.value.split(\"\\n\");\n\t\tif (raw[raw.length - 1] === \"\") {\n\t\t\traw.pop();\n\t\t}\n\n\t\tif (part.added || part.removed) {\n\t\t\t// Capture the first changed line (in the new file)\n\t\t\tif (firstChangedLine === undefined) {\n\t\t\t\tfirstChangedLine = newLineNum;\n\t\t\t}\n\n\t\t\t// Show the change\n\t\t\tfor (const line of raw) {\n\t\t\t\tif (part.added) {\n\t\t\t\t\tconst lineNum = String(newLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`+${lineNum} ${line}`);\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t} else {\n\t\t\t\t\t// removed\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`-${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t}\n\t\t\t}\n\t\t\tlastWasChange = true;\n\t\t} else {\n\t\t\t// Context lines - only show a few before/after changes\n\t\t\tconst nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);\n\t\t\tconst hasLeadingChange = lastWasChange;\n\t\t\tconst hasTrailingChange = nextPartIsChange;\n\n\t\t\tif (hasLeadingChange && hasTrailingChange) {\n\t\t\t\tif (raw.length <= contextLines * 2) {\n\t\t\t\t\tfor (const line of raw) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tconst leadingLines = raw.slice(0, contextLines);\n\t\t\t\t\tconst trailingLines = raw.slice(raw.length - contextLines);\n\t\t\t\t\tconst skippedLines = raw.length - leadingLines.length - trailingLines.length;\n\n\t\t\t\t\tfor (const line of leadingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\n\t\t\t\t\tfor (const line of trailingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else if (hasLeadingChange) {\n\t\t\t\tconst shownLines = raw.slice(0, contextLines);\n\t\t\t\tconst skippedLines = raw.length - shownLines.length;\n\n\t\t\t\tfor (const line of shownLines) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\t\t\t} else if (hasTrailingChange) {\n\t\t\t\tconst skippedLines = Math.max(0, raw.length - contextLines);\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\n\t\t\t\tfor (const line of raw.slice(skippedLines)) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Skip these context lines entirely\n\t\t\t\toldLineNum += raw.length;\n\t\t\t\tnewLineNum += raw.length;\n\t\t\t}\n\n\t\t\tlastWasChange = false;\n\t\t}\n\t}\n\n\treturn { diff: output.join(\"\\n\"), firstChangedLine };\n}\n\nexport interface EditDiffResult {\n\tdiff: string;\n\tfirstChangedLine: number | undefined;\n}\n\nexport interface EditDiffError {\n\terror: string;\n}\n\n/**\n * Compute the diff for one or more edit operations without applying them.\n * Used for preview rendering in the TUI before the tool executes.\n */\nexport async function computeEditsDiff(\n\tpath: string,\n\tedits: Edit[],\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\tconst absolutePath = resolveToCwd(path, cwd);\n\n\ttry {\n\t\t// Check if file exists and is readable\n\t\ttry {\n\t\t\tawait access(absolutePath, constants.R_OK);\n\t\t} catch (error: unknown) {\n\t\t\tconst errorMessage = error instanceof Error && \"code\" in error ? `Error code: ${error.code}` : String(error);\n\t\t\treturn { error: `Could not edit file: ${path}. ${errorMessage}.` };\n\t\t}\n\n\t\t// Read the file\n\t\tconst rawContent = await readFile(absolutePath, \"utf-8\");\n\n\t\t// Strip BOM before matching (LLM won't include invisible BOM in oldText)\n\t\tconst { text: content } = stripBom(rawContent);\n\t\tconst normalizedContent = normalizeToLF(content);\n\t\tconst { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);\n\n\t\t// Generate the diff\n\t\treturn generateDiffString(baseContent, newContent);\n\t} catch (err) {\n\t\treturn { error: err instanceof Error ? err.message : String(err) };\n\t}\n}\n\n/**\n * Compute the diff for a single edit operation without applying it.\n * Kept as a convenience wrapper for single-edit callers.\n */\nexport async function computeEditDiff(\n\tpath: string,\n\toldText: string,\n\tnewText: string,\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\treturn computeEditsDiff(path, [{ oldText, newText }], cwd);\n}\n"]}
+{"version":3,"file":"edit-diff.d.ts","sourceRoot":"","sources":["../../../src/core/tools/edit-diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared diff computation utilities for the edit and similar tools.\n */\n\nimport * as Diff from \"diff\";\nimport { constants } from \"fs\";\nimport { access, readFile } from \"fs/promises\";\nimport { splitBom } from \"../../utils/text.ts\";\nimport { resolveToCwd } from \"./path-utils.ts\";\n\nexport function detectLineEnding(content: string): \"\\r\\n\" | \"\\n\" {\n\tconst crlfIdx = content.indexOf(\"\\r\\n\");\n\tconst lfIdx = content.indexOf(\"\\n\");\n\tif (lfIdx === -1) return \"\\n\";\n\tif (crlfIdx === -1) return \"\\n\";\n\treturn crlfIdx < lfIdx ? \"\\r\\n\" : \"\\n\";\n}\n\nexport function normalizeToLF(text: string): string {\n\treturn text.replace(/\\r\\n/g, \"\\n\").replace(/\\r/g, \"\\n\");\n}\n\nexport function restoreLineEndings(text: string, ending: \"\\r\\n\" | \"\\n\"): string {\n\treturn ending === \"\\r\\n\" ? text.replace(/\\n/g, \"\\r\\n\") : text;\n}\n\n/**\n * Normalize text for fuzzy matching. Applies progressive transformations:\n * - Strip trailing whitespace from each line\n * - Normalize smart quotes to ASCII equivalents\n * - Normalize Unicode dashes/hyphens to ASCII hyphen\n * - Normalize special Unicode spaces to regular space\n */\nexport function normalizeForFuzzyMatch(text: string): string {\n\treturn (\n\t\ttext\n\t\t\t.normalize(\"NFKC\")\n\t\t\t// Strip trailing whitespace per line\n\t\t\t.split(\"\\n\")\n\t\t\t.map((line) => line.trimEnd())\n\t\t\t.join(\"\\n\")\n\t\t\t// Smart single quotes → '\n\t\t\t.replace(/[\\u2018\\u2019\\u201A\\u201B]/g, \"'\")\n\t\t\t// Smart double quotes → \"\n\t\t\t.replace(/[\\u201C\\u201D\\u201E\\u201F]/g, '\"')\n\t\t\t// Various dashes/hyphens → -\n\t\t\t// U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,\n\t\t\t// U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus\n\t\t\t.replace(/[\\u2010\\u2011\\u2012\\u2013\\u2014\\u2015\\u2212]/g, \"-\")\n\t\t\t// Special spaces → regular space\n\t\t\t// U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,\n\t\t\t// U+205F medium math space, U+3000 ideographic space\n\t\t\t.replace(/[\\u00A0\\u2002-\\u200A\\u202F\\u205F\\u3000]/g, \" \")\n\t);\n}\n\nfunction splitLinesWithEndings(content: string): string[] {\n\treturn content.match(/[^\\n]*\\n|[^\\n]+/g) ?? [];\n}\n\ninterface LineSpan {\n\tstart: number;\n\tend: number;\n}\n\ninterface MatchedEdit {\n\teditIndex: number;\n\tmatchIndex: number;\n\tmatchLength: number;\n\tnewText: string;\n}\n\ntype TextReplacement = Pick<MatchedEdit, \"matchIndex\" | \"matchLength\" | \"newText\">;\n\nfunction getLineSpans(content: string): LineSpan[] {\n\tlet offset = 0;\n\treturn splitLinesWithEndings(content).map((line) => {\n\t\tconst span = { start: offset, end: offset + line.length };\n\t\toffset = span.end;\n\t\treturn span;\n\t});\n}\n\nfunction getReplacementLineRange(lines: LineSpan[], replacement: TextReplacement) {\n\tconst replacementStart = replacement.matchIndex;\n\tconst replacementEnd = replacement.matchIndex + replacement.matchLength;\n\n\tlet startLine = -1;\n\tfor (let i = 0; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (replacementStart >= line.start && replacementStart < line.end) {\n\t\t\tstartLine = i;\n\t\t\tbreak;\n\t\t}\n\t}\n\tif (startLine === -1) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\tlet endLine = startLine;\n\twhile (endLine < lines.length && lines[endLine].end < replacementEnd) {\n\t\tendLine++;\n\t}\n\tif (endLine >= lines.length) {\n\t\tthrow new Error(\"Replacement range is outside the base content.\");\n\t}\n\n\treturn { startLine, endLine: endLine + 1 };\n}\n\nfunction applyReplacements(content: string, replacements: TextReplacement[], offset = 0): string {\n\tlet result = content;\n\tfor (let i = replacements.length - 1; i >= 0; i--) {\n\t\tconst replacement = replacements[i];\n\t\tconst matchIndex = replacement.matchIndex - offset;\n\t\tresult =\n\t\t\tresult.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);\n\t}\n\treturn result;\n}\n\n/**\n * Apply replacements matched against `baseContent` to `originalContent` while\n * preserving unchanged line blocks from the original.\n *\n * This is useful when `baseContent` is a normalized view of the original. Each\n * replacement is widened to the lines it actually touches, those touched lines\n * are rewritten from the normalized base, and all other lines are copied back\n * from `originalContent`. The actual replacement ranges drive preservation so\n * duplicate normalized lines cannot be aligned to the wrong occurrence.\n */\nexport function applyReplacementsPreservingUnchangedLines(\n\toriginalContent: string,\n\tbaseContent: string,\n\treplacements: TextReplacement[],\n): string {\n\tconst originalLines = splitLinesWithEndings(originalContent);\n\tconst baseLines = getLineSpans(baseContent);\n\tif (originalLines.length !== baseLines.length) {\n\t\tthrow new Error(\"Cannot preserve unchanged lines because the base content has a different line count.\");\n\t}\n\n\tconst groups: Array<{ startLine: number; endLine: number; replacements: TextReplacement[] }> = [];\n\tconst sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (const replacement of sortedReplacements) {\n\t\tconst range = getReplacementLineRange(baseLines, replacement);\n\t\tconst current = groups[groups.length - 1];\n\t\tif (current && range.startLine < current.endLine) {\n\t\t\tcurrent.endLine = Math.max(current.endLine, range.endLine);\n\t\t\tcurrent.replacements.push(replacement);\n\t\t\tcontinue;\n\t\t}\n\t\tgroups.push({ ...range, replacements: [replacement] });\n\t}\n\n\tlet originalLineIndex = 0;\n\tlet result = \"\";\n\tfor (const group of groups) {\n\t\tresult += originalLines.slice(originalLineIndex, group.startLine).join(\"\");\n\n\t\tconst groupStartOffset = baseLines[group.startLine].start;\n\t\tconst groupEndOffset = baseLines[group.endLine - 1].end;\n\t\tresult += applyReplacements(\n\t\t\tbaseContent.slice(groupStartOffset, groupEndOffset),\n\t\t\tgroup.replacements,\n\t\t\tgroupStartOffset,\n\t\t);\n\t\toriginalLineIndex = group.endLine;\n\t}\n\tresult += originalLines.slice(originalLineIndex).join(\"\");\n\n\treturn result;\n}\n\nexport interface FuzzyMatchResult {\n\t/** Whether a match was found */\n\tfound: boolean;\n\t/** The index where the match starts (in the content that should be used for replacement) */\n\tindex: number;\n\t/** Length of the matched text */\n\tmatchLength: number;\n\t/** Whether fuzzy matching was used (false = exact match) */\n\tusedFuzzyMatch: boolean;\n\t/**\n\t * The content to use for replacement operations.\n\t * When exact match: original content. When fuzzy match: normalized content.\n\t */\n\tcontentForReplacement: string;\n}\n\nexport interface Edit {\n\toldText: string;\n\tnewText: string;\n}\n\nexport interface AppliedEditsResult {\n\tbaseContent: string;\n\tnewContent: string;\n}\n\n/**\n * Find oldText in content, trying exact match first, then fuzzy match.\n * When fuzzy matching is used, the returned contentForReplacement is the\n * fuzzy-normalized version of the content (trailing whitespace stripped,\n * Unicode quotes/dashes normalized to ASCII).\n */\nexport function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult {\n\t// Try exact match first\n\tconst exactIndex = content.indexOf(oldText);\n\tif (exactIndex !== -1) {\n\t\treturn {\n\t\t\tfound: true,\n\t\t\tindex: exactIndex,\n\t\t\tmatchLength: oldText.length,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// Try fuzzy match - work entirely in normalized space\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\tconst fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);\n\n\tif (fuzzyIndex === -1) {\n\t\treturn {\n\t\t\tfound: false,\n\t\t\tindex: -1,\n\t\t\tmatchLength: 0,\n\t\t\tusedFuzzyMatch: false,\n\t\t\tcontentForReplacement: content,\n\t\t};\n\t}\n\n\t// When fuzzy matching, return offsets in normalized space. Callers can use\n\t// the normalized content to compute replacements, then decide how much of\n\t// that normalized output should be written back.\n\treturn {\n\t\tfound: true,\n\t\tindex: fuzzyIndex,\n\t\tmatchLength: fuzzyOldText.length,\n\t\tusedFuzzyMatch: true,\n\t\tcontentForReplacement: fuzzyContent,\n\t};\n}\n\nfunction countOccurrences(content: string, oldText: string): number {\n\tconst fuzzyContent = normalizeForFuzzyMatch(content);\n\tconst fuzzyOldText = normalizeForFuzzyMatch(oldText);\n\treturn fuzzyContent.split(fuzzyOldText).length - 1;\n}\n\n/**\n * Explicit budgets for the advisory edit-failure diagnostics below. Diagnostics\n * are a best-effort hint, never an apply path, so every dimension of the scan\n * is bounded and the ordinary failure is returned untouched when a bound is\n * exceeded (spec 2026-09-01-tool-reliability-and-execution-budgets.md § 2).\n */\nexport const EDIT_DIAGNOSTIC_MAX_FILE_BYTES = 1_048_576;\nexport const EDIT_DIAGNOSTIC_MAX_TARGET_BYTES = 65_536;\nexport const EDIT_DIAGNOSTIC_MAX_CANDIDATES = 3;\nexport const EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS = 20_000;\nexport const EDIT_DIAGNOSTIC_MAX_OCCURRENCES = 5;\nexport const EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS = 160;\n\nconst EDIT_DIAGNOSTIC_MIN_SIMILARITY = 0.2;\nconst EDIT_DIAGNOSTIC_SCAN_BUDGET_MS = 50;\nconst EDIT_DIAGNOSTIC_MAX_OCCURRENCE_STEPS = 10_000;\n\nexport interface EditCandidateLocation {\n\t/** 1-based, inclusive. */\n\tstartLine: number;\n\t/** 1-based, inclusive. */\n\tendLine: number;\n\t/** Bigram Dice similarity against the failed target, rounded to two decimals. */\n\tsimilarity: number;\n\t/** Bounded snippet of the candidate source lines, each line-numbered. */\n\tsnippet: string;\n}\n\n/**\n * Advisory diagnostics attached to a failed edit match. These describe where a\n * target almost matched or where duplicates live; they are never a replacement\n * location and must never be applied.\n */\nexport interface EditFailureDiagnostics {\n\tkind: \"missing-match\" | \"duplicate-match\";\n\tcandidates: EditCandidateLocation[];\n\t/** 1-based source lines of up to EDIT_DIAGNOSTIC_MAX_OCCURRENCES duplicates. */\n\toccurrenceLines: number[];\n\tomittedOccurrences: number;\n\t/** True when the scan stopped at a work or time bound before finishing. */\n\tscanTruncated: boolean;\n\t/** Set when scanning was unsafe or oversized; no candidates are reported. */\n\tunavailableReason?: string;\n}\n\nfunction unavailableDiagnostics(kind: EditFailureDiagnostics[\"kind\"], reason: string): EditFailureDiagnostics {\n\treturn {\n\t\tkind,\n\t\tcandidates: [],\n\t\toccurrenceLines: [],\n\t\tomittedOccurrences: 0,\n\t\tscanTruncated: false,\n\t\tunavailableReason: reason,\n\t};\n}\n\nfunction isDiagnosticScannable(\n\tkind: EditFailureDiagnostics[\"kind\"],\n\tcontent: string,\n\ttarget: string,\n): EditFailureDiagnostics | undefined {\n\tif (Buffer.byteLength(content, \"utf-8\") > EDIT_DIAGNOSTIC_MAX_FILE_BYTES) {\n\t\treturn unavailableDiagnostics(\n\t\t\tkind,\n\t\t\t`advisory diagnostic scan skipped: file exceeds the ${EDIT_DIAGNOSTIC_MAX_FILE_BYTES}-byte diagnostic budget`,\n\t\t);\n\t}\n\tif (Buffer.byteLength(target, \"utf-8\") > EDIT_DIAGNOSTIC_MAX_TARGET_BYTES) {\n\t\treturn unavailableDiagnostics(\n\t\t\tkind,\n\t\t\t`advisory diagnostic scan skipped: oldText exceeds the ${EDIT_DIAGNOSTIC_MAX_TARGET_BYTES}-byte diagnostic budget`,\n\t\t);\n\t}\n\treturn undefined;\n}\n\nfunction bigrams(text: string): Set<string> {\n\tconst result = new Set<string>();\n\tfor (let i = 0; i < text.length - 1; i++) {\n\t\tresult.add(text.slice(i, i + 2));\n\t}\n\treturn result;\n}\n\nfunction diceSimilarity(a: Set<string>, b: Set<string>): number {\n\tif (a.size === 0 && b.size === 0) return 1;\n\tif (a.size === 0 || b.size === 0) return 0;\n\tlet intersection = 0;\n\tfor (const gram of a) {\n\t\tif (b.has(gram)) intersection++;\n\t}\n\treturn (2 * intersection) / (a.size + b.size);\n}\n\nfunction truncateSnippetLine(line: string): string {\n\tif (line.length <= EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS) return line;\n\treturn `${line.slice(0, EDIT_DIAGNOSTIC_SNIPPET_LINE_CHARS)}…`;\n}\n\nfunction buildSnippet(lines: string[], startLine: number, lineCount: number): string {\n\tconst shown = Math.min(lineCount, 5);\n\tconst parts: string[] = [];\n\tfor (let i = 0; i < shown; i++) {\n\t\tparts.push(`${startLine + i + 1} | ${truncateSnippetLine(lines[startLine + i] ?? \"\")}`);\n\t}\n\treturn parts.join(\"\\n\");\n}\n\n/**\n * Find the closest line windows to a failed target. Purely advisory: the result\n * names locations so the caller can retry with better context, and is never a\n * replacement specification.\n */\nfunction scanMissingMatchCandidates(content: string, target: string): EditFailureDiagnostics {\n\tconst blocked = isDiagnosticScannable(\"missing-match\", content, target);\n\tif (blocked) return blocked;\n\n\tconst lines = content.split(\"\\n\");\n\tconst windowSize = Math.max(1, target.split(\"\\n\").length);\n\tconst windowCount = lines.length - windowSize + 1;\n\tconst deadline = Date.now() + EDIT_DIAGNOSTIC_SCAN_BUDGET_MS;\n\tconst targetGrams = bigrams(target);\n\n\tconst best: Array<{ startLine: number; similarity: number }> = [];\n\tlet windowsScanned = 0;\n\tlet scanTruncated = false;\n\tfor (let start = 0; start < windowCount; start++) {\n\t\tif (windowsScanned >= EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS || (start % 512 === 0 && Date.now() > deadline)) {\n\t\t\tscanTruncated = true;\n\t\t\tbreak;\n\t\t}\n\t\twindowsScanned++;\n\t\tconst windowGrams = bigrams(lines.slice(start, start + windowSize).join(\"\\n\"));\n\t\tconst similarity = diceSimilarity(targetGrams, windowGrams);\n\t\tif (similarity < EDIT_DIAGNOSTIC_MIN_SIMILARITY) continue;\n\t\tif (best.length < EDIT_DIAGNOSTIC_MAX_CANDIDATES || similarity > best[best.length - 1].similarity) {\n\t\t\tbest.push({ startLine: start, similarity });\n\t\t\tbest.sort((a, b) => b.similarity - a.similarity);\n\t\t\tif (best.length > EDIT_DIAGNOSTIC_MAX_CANDIDATES) best.pop();\n\t\t}\n\t}\n\n\treturn {\n\t\tkind: \"missing-match\",\n\t\tcandidates: best.map((entry) => ({\n\t\t\tstartLine: entry.startLine + 1,\n\t\t\tendLine: entry.startLine + windowSize,\n\t\t\tsimilarity: Math.round(entry.similarity * 100) / 100,\n\t\t\tsnippet: buildSnippet(lines, entry.startLine, windowSize),\n\t\t})),\n\t\toccurrenceLines: [],\n\t\tomittedOccurrences: 0,\n\t\tscanTruncated,\n\t};\n}\n\nfunction lineNumberForOffset(lineStarts: number[], offset: number): number {\n\tlet low = 0;\n\tlet high = lineStarts.length - 1;\n\twhile (low < high) {\n\t\tconst mid = Math.ceil((low + high) / 2);\n\t\tif (lineStarts[mid] <= offset) low = mid;\n\t\telse high = mid - 1;\n\t}\n\treturn low + 1;\n}\n\n/** List bounded 1-based source lines for duplicate occurrences. Advisory only. */\nfunction scanDuplicateOccurrences(content: string, target: string): EditFailureDiagnostics {\n\tconst blocked = isDiagnosticScannable(\"duplicate-match\", content, target);\n\tif (blocked) return blocked;\n\n\tconst lines = content.split(\"\\n\");\n\tconst lineStarts: number[] = [];\n\tlet offset = 0;\n\tfor (const line of lines) {\n\t\tlineStarts.push(offset);\n\t\toffset += line.length + 1;\n\t}\n\n\tconst occurrenceLines: number[] = [];\n\tlet total = 0;\n\tlet truncated = false;\n\tlet searchFrom = 0;\n\twhile (target.length > 0) {\n\t\tconst index = content.indexOf(target, searchFrom);\n\t\tif (index === -1) break;\n\t\ttotal++;\n\t\tif (occurrenceLines.length < EDIT_DIAGNOSTIC_MAX_OCCURRENCES) {\n\t\t\toccurrenceLines.push(lineNumberForOffset(lineStarts, index));\n\t\t}\n\t\tsearchFrom = index + target.length;\n\t\tif (total >= EDIT_DIAGNOSTIC_MAX_OCCURRENCE_STEPS) {\n\t\t\ttruncated = true;\n\t\t\tbreak;\n\t\t}\n\t}\n\n\treturn {\n\t\tkind: \"duplicate-match\",\n\t\tcandidates: [],\n\t\toccurrenceLines,\n\t\tomittedOccurrences: Math.max(0, total - occurrenceLines.length),\n\t\tscanTruncated: truncated,\n\t};\n}\n\n/** Render advisory diagnostics as an error-message appendix. Empty when there is nothing to say. */\nexport function formatEditFailureDiagnostics(diagnostics: EditFailureDiagnostics | undefined): string {\n\tif (!diagnostics) return \"\";\n\tif (diagnostics.unavailableReason) {\n\t\treturn `\\n\\n(${diagnostics.unavailableReason}.)`;\n\t}\n\tconst sections: string[] = [];\n\tif (diagnostics.kind === \"duplicate-match\" && diagnostics.occurrenceLines.length > 0) {\n\t\tconst more = diagnostics.omittedOccurrences > 0 ? ` (+${diagnostics.omittedOccurrences} more)` : \"\";\n\t\tsections.push(`Advisory occurrence lines (not applied): ${diagnostics.occurrenceLines.join(\", \")}${more}`);\n\t}\n\tif (diagnostics.kind === \"missing-match\" && diagnostics.candidates.length > 0) {\n\t\tconst parts = [\"Advisory closest matches (not applied):\"];\n\t\tfor (const candidate of diagnostics.candidates) {\n\t\t\tparts.push(\n\t\t\t\t`  lines ${candidate.startLine}-${candidate.endLine} (${Math.round(candidate.similarity * 100)}% similar)`,\n\t\t\t);\n\t\t\tfor (const line of candidate.snippet.split(\"\\n\")) {\n\t\t\t\tparts.push(`    ${line}`);\n\t\t\t}\n\t\t}\n\t\tsections.push(parts.join(\"\\n\"));\n\t}\n\tif (diagnostics.scanTruncated) {\n\t\tsections.push(\n\t\t\t`(Advisory location scan truncated after ${EDIT_DIAGNOSTIC_MAX_SCAN_WINDOWS} windows; remaining locations were not examined.)`,\n\t\t);\n\t}\n\treturn sections.length > 0 ? `\\n\\n${sections.join(\"\\n\")}` : \"\";\n}\n\nfunction appendEditDiagnostics(error: Error, diagnostics: EditFailureDiagnostics): Error {\n\terror.message += formatEditFailureDiagnostics(diagnostics);\n\treturn error;\n}\n\nfunction getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,\n\t);\n}\n\nfunction getDuplicateError(path: string, editIndex: number, totalEdits: number, occurrences: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`Found ${occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`,\n\t\t);\n\t}\n\treturn new Error(\n\t\t`Found ${occurrences} occurrences of edits[${editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`,\n\t);\n}\n\nfunction getEmptyOldTextError(path: string, editIndex: number, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(`oldText must not be empty in ${path}.`);\n\t}\n\treturn new Error(`edits[${editIndex}].oldText must not be empty in ${path}.`);\n}\n\nfunction getNoChangeError(path: string, totalEdits: number): Error {\n\tif (totalEdits === 1) {\n\t\treturn new Error(\n\t\t\t`No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,\n\t\t);\n\t}\n\treturn new Error(`No changes made to ${path}. The replacements produced identical content.`);\n}\n\n/**\n * Apply one or more exact-text replacements to LF-normalized content.\n *\n * All edits are matched against the same original content. Replacements are\n * then applied in reverse order so offsets remain stable. If any edit needs\n * fuzzy matching, the operation runs in fuzzy-normalized content space and then\n * overlays those line-level changes onto the original content so unchanged line\n * blocks keep their original bytes.\n */\nexport function applyEditsToNormalizedContent(\n\tnormalizedContent: string,\n\tedits: Edit[],\n\tpath: string,\n): AppliedEditsResult {\n\tconst normalizedEdits = edits.map((edit) => ({\n\t\toldText: normalizeToLF(edit.oldText),\n\t\tnewText: normalizeToLF(edit.newText),\n\t}));\n\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tif (normalizedEdits[i].oldText.length === 0) {\n\t\t\tthrow getEmptyOldTextError(path, i, normalizedEdits.length);\n\t\t}\n\t}\n\n\tconst initialMatches = normalizedEdits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));\n\tconst usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);\n\tconst replacementBaseContent = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;\n\n\tconst matchedEdits: MatchedEdit[] = [];\n\tfor (let i = 0; i < normalizedEdits.length; i++) {\n\t\tconst edit = normalizedEdits[i];\n\t\tconst matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);\n\t\tif (!matchResult.found) {\n\t\t\t// Advisory only: candidates name near-miss locations but never supply a\n\t\t\t// replacement. Matching above remains the only apply path.\n\t\t\tconst diagnosticTarget = usedFuzzyMatch ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText;\n\t\t\tthrow appendEditDiagnostics(\n\t\t\t\tgetNotFoundError(path, i, normalizedEdits.length),\n\t\t\t\tscanMissingMatchCandidates(replacementBaseContent, diagnosticTarget),\n\t\t\t);\n\t\t}\n\n\t\tconst occurrences = countOccurrences(replacementBaseContent, edit.oldText);\n\t\tif (occurrences > 1) {\n\t\t\tconst diagnosticTarget = usedFuzzyMatch ? normalizeForFuzzyMatch(edit.oldText) : edit.oldText;\n\t\t\tthrow appendEditDiagnostics(\n\t\t\t\tgetDuplicateError(path, i, normalizedEdits.length, occurrences),\n\t\t\t\tscanDuplicateOccurrences(replacementBaseContent, diagnosticTarget),\n\t\t\t);\n\t\t}\n\n\t\tmatchedEdits.push({\n\t\t\teditIndex: i,\n\t\t\tmatchIndex: matchResult.index,\n\t\t\tmatchLength: matchResult.matchLength,\n\t\t\tnewText: edit.newText,\n\t\t});\n\t}\n\n\tmatchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);\n\tfor (let i = 1; i < matchedEdits.length; i++) {\n\t\tconst previous = matchedEdits[i - 1];\n\t\tconst current = matchedEdits[i];\n\t\tif (previous.matchIndex + previous.matchLength > current.matchIndex) {\n\t\t\tthrow new Error(\n\t\t\t\t`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`,\n\t\t\t);\n\t\t}\n\t}\n\n\tconst baseContent = normalizedContent;\n\tconst newContent = usedFuzzyMatch\n\t\t? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)\n\t\t: applyReplacements(replacementBaseContent, matchedEdits);\n\n\tif (baseContent === newContent) {\n\t\tthrow getNoChangeError(path, normalizedEdits.length);\n\t}\n\n\treturn { baseContent, newContent };\n}\n\n/** Generate a standard unified patch. */\nexport function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines = 4): string {\n\treturn Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, {\n\t\tcontext: contextLines,\n\t\theaderOptions: Diff.FILE_HEADERS_ONLY,\n\t});\n}\n\n/**\n * Generate a display-oriented diff string with line numbers and context.\n * Returns both the diff string and the first changed line number (in the new file).\n */\nexport function generateDiffString(\n\toldContent: string,\n\tnewContent: string,\n\tcontextLines = 4,\n): { diff: string; firstChangedLine: number | undefined } {\n\tconst parts = Diff.diffLines(oldContent, newContent);\n\tconst output: string[] = [];\n\n\tconst oldLines = oldContent.split(\"\\n\");\n\tconst newLines = newContent.split(\"\\n\");\n\tconst maxLineNum = Math.max(oldLines.length, newLines.length);\n\tconst lineNumWidth = String(maxLineNum).length;\n\n\tlet oldLineNum = 1;\n\tlet newLineNum = 1;\n\tlet lastWasChange = false;\n\tlet firstChangedLine: number | undefined;\n\n\tfor (let i = 0; i < parts.length; i++) {\n\t\tconst part = parts[i];\n\t\tconst raw = part.value.split(\"\\n\");\n\t\tif (raw[raw.length - 1] === \"\") {\n\t\t\traw.pop();\n\t\t}\n\n\t\tif (part.added || part.removed) {\n\t\t\t// Capture the first changed line (in the new file)\n\t\t\tif (firstChangedLine === undefined) {\n\t\t\t\tfirstChangedLine = newLineNum;\n\t\t\t}\n\n\t\t\t// Show the change\n\t\t\tfor (const line of raw) {\n\t\t\t\tif (part.added) {\n\t\t\t\t\tconst lineNum = String(newLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`+${lineNum} ${line}`);\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t} else {\n\t\t\t\t\t// removed\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(`-${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t}\n\t\t\t}\n\t\t\tlastWasChange = true;\n\t\t} else {\n\t\t\t// Context lines - only show a few before/after changes\n\t\t\tconst nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);\n\t\t\tconst hasLeadingChange = lastWasChange;\n\t\t\tconst hasTrailingChange = nextPartIsChange;\n\n\t\t\tif (hasLeadingChange && hasTrailingChange) {\n\t\t\t\tif (raw.length <= contextLines * 2) {\n\t\t\t\t\tfor (const line of raw) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t} else {\n\t\t\t\t\tconst leadingLines = raw.slice(0, contextLines);\n\t\t\t\t\tconst trailingLines = raw.slice(raw.length - contextLines);\n\t\t\t\t\tconst skippedLines = raw.length - leadingLines.length - trailingLines.length;\n\n\t\t\t\t\tfor (const line of leadingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\n\t\t\t\t\tfor (const line of trailingLines) {\n\t\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\t\toldLineNum++;\n\t\t\t\t\t\tnewLineNum++;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else if (hasLeadingChange) {\n\t\t\t\tconst shownLines = raw.slice(0, contextLines);\n\t\t\t\tconst skippedLines = raw.length - shownLines.length;\n\n\t\t\t\tfor (const line of shownLines) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\t\t\t} else if (hasTrailingChange) {\n\t\t\t\tconst skippedLines = Math.max(0, raw.length - contextLines);\n\t\t\t\tif (skippedLines > 0) {\n\t\t\t\t\toutput.push(` ${\"\".padStart(lineNumWidth, \" \")} ...`);\n\t\t\t\t\toldLineNum += skippedLines;\n\t\t\t\t\tnewLineNum += skippedLines;\n\t\t\t\t}\n\n\t\t\t\tfor (const line of raw.slice(skippedLines)) {\n\t\t\t\t\tconst lineNum = String(oldLineNum).padStart(lineNumWidth, \" \");\n\t\t\t\t\toutput.push(` ${lineNum} ${line}`);\n\t\t\t\t\toldLineNum++;\n\t\t\t\t\tnewLineNum++;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// Skip these context lines entirely\n\t\t\t\toldLineNum += raw.length;\n\t\t\t\tnewLineNum += raw.length;\n\t\t\t}\n\n\t\t\tlastWasChange = false;\n\t\t}\n\t}\n\n\treturn { diff: output.join(\"\\n\"), firstChangedLine };\n}\n\nexport interface EditDiffResult {\n\tdiff: string;\n\tfirstChangedLine: number | undefined;\n}\n\nexport interface EditDiffError {\n\terror: string;\n}\n\n/**\n * Compute the diff for one or more edit operations without applying them.\n * Used for preview rendering in the TUI before the tool executes.\n */\nexport async function computeEditsDiff(\n\tpath: string,\n\tedits: Edit[],\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\tconst absolutePath = resolveToCwd(path, cwd);\n\n\ttry {\n\t\t// Check if file exists and is readable\n\t\ttry {\n\t\t\tawait access(absolutePath, constants.R_OK);\n\t\t} catch (error: unknown) {\n\t\t\tconst errorMessage = error instanceof Error && \"code\" in error ? `Error code: ${error.code}` : String(error);\n\t\t\treturn { error: `Could not edit file: ${path}. ${errorMessage}.` };\n\t\t}\n\n\t\t// Read the file\n\t\tconst rawContent = await readFile(absolutePath, \"utf-8\");\n\t\treturn computeEditsDiffFromContent(path, rawContent, edits);\n\t} catch (err) {\n\t\treturn { error: err instanceof Error ? err.message : String(err) };\n\t}\n}\n\n/**\n * The half of `computeEditsDiff` that does not choose which bytes to read.\n *\n * The permission preview must describe the operation the gate authorized rather\n * than whatever the pathname resolves to a second time, so it supplies content\n * read through the prepared operation and calls this (ADR 0029).\n */\nexport function computeEditsDiffFromContent(\n\tpath: string,\n\trawContent: string,\n\tedits: Edit[],\n): EditDiffResult | EditDiffError {\n\ttry {\n\t\t// Strip BOM before matching (LLM won't include invisible BOM in oldText)\n\t\tconst { text: content } = splitBom(rawContent);\n\t\tconst normalizedContent = normalizeToLF(content);\n\t\tconst { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);\n\t\treturn generateDiffString(baseContent, newContent);\n\t} catch (err) {\n\t\treturn { error: err instanceof Error ? err.message : String(err) };\n\t}\n}\n\n/**\n * Compute the diff for a single edit operation without applying it.\n * Kept as a convenience wrapper for single-edit callers.\n */\nexport async function computeEditDiff(\n\tpath: string,\n\toldText: string,\n\tnewText: string,\n\tcwd: string,\n): Promise<EditDiffResult | EditDiffError> {\n\treturn computeEditsDiff(path, [{ oldText, newText }], cwd);\n}\n"]}