atom-agent 1.1.0 → 1.3.0

package/dist/telemetry-dashboard.js

@@ -243,6 +243,26 @@ function iterationTimeline(s) {
     });
     return `<div class="timeline">${rows.join("")}</div>`;
 }
+// Goal fragment for one turn (ticket 09): rendered only when the trace
+// carries a goal snapshot — absent or malformed reads as no-goal and renders
+// nothing (never a fake claim). Counters show only when reported.
+function goalFragment(t) {
+    const g = t.goal;
+    if (!g || typeof g.objective !== "string" || g.objective.length === 0)
+        return "";
+    const state = g.active === true ? "active" : "paused";
+    const bits = [];
+    if (typeof g.turns === "number")
+        bits.push(`${fmtCount(g.turns)} turn(s)`);
+    if (typeof g.requests === "number")
+        bits.push(`${fmtCount(g.requests)} request(s)`);
+    if (typeof g.tokens === "number")
+        bits.push(`${fmtCount(g.tokens)} tokens`);
+    if (typeof g.workMs === "number")
+        bits.push(fmtMs(g.workMs));
+    const counters = bits.length > 0 ? ` <span class="mute">(${bits.join(" · ")})</span>` : "";
+    return `<p><strong>Goal:</strong> <span class="mono">${escapeHtml(g.objective)}</span> <span class="pill">${state}</span>${counters}</p>`;
+}
 function turnBlock(t) {
     const outcomeCls = t.outcome === "completed" ? "ok" : t.outcome === "failed" ? "err" : "warn";
     const total = turnTokensTotal(t);
@@ -272,6 +292,7 @@ function turnBlock(t) {
     <summary><span class="mono">${escapeHtml(t.id)}</span> · ${fmtTime(t.startedAt)} · ${escapeHtml(t.provider)} · ${escapeHtml(t.model)} · ${head}</summary>
     <div class="turnbody">
       <p><strong>Input:</strong> <span class="mono">${escapeHtml(t.inputPreview)}</span> <span class="mute">(${fmtCount(t.inputChars)} chars)</span></p>
+      ${goalFragment(t)}
       ${t.error ? `<p><strong>Error:</strong> <span class="err">${escapeHtml(t.error)}</span></p>` : ""}
       ${t.replyPreview ? `<p><strong>Reply:</strong> <span class="mono">${escapeHtml(t.replyPreview)}</span></p>` : ""}
       <h5>Timeline</h5>
@@ -361,6 +382,12 @@ export function buildDashboardHtml(sessions, opts = {}) {
     const successRate = agg.toolSuccessRate !== null
         ? `${(agg.toolSuccessRate * 100).toFixed(1)}%`
         : `<span class="na" title="No tool calls recorded — a rate over zero calls would be fake.">n/a</span>`;
+    // Goal overview (ticket 09): present only when at least one stored turn
+    // carried a goal snapshot — zero goal turns omit the card entirely (same
+    // conditional-render precedent as the corrupt-file note above).
+    const goalCard = agg.goalTurns > 0
+        ? `<div class="card"><div class="k">Goal turns</div><div class="v">${fmtCount(agg.goalTurns)}</div></div>`
+        : "";
     const refreshSeconds = typeof opts.refreshSeconds === "number" && Number.isFinite(opts.refreshSeconds)
         ? Math.floor(opts.refreshSeconds)
         : 0;
@@ -504,6 +531,7 @@ ${corruptNote}
 <div class="card"><div class="k">Completion tokens (reported)</div><div class="v">${fmtTokens(agg.usage.completion_tokens, agg.usageReported, "No model call reported completion_tokens.")}</div></div>
 <div class="card"><div class="k">Cache read / write (reported)</div><div class="v">${fmtTokens(agg.usage.cacheReadTokens, agg.usageReported, "No provider reported cache-read counters.")} / ${fmtTokens(agg.usage.cacheWriteTokens, agg.usageReported, "No provider reported cache-write counters.")}</div></div>
 <div class="card"><div class="k">Retries</div><div class="v">${fmtCount(agg.retries)}</div></div>
+${goalCard}
 <div class="card"><div class="k">Read-cache hits (local)</div><div class="v">${fmtCount(agg.cacheHits)}</div></div>
 <div class="card"><div class="k">Loop-guard hits</div><div class="v">${fmtCount(agg.repetitionHits)}</div></div>
 <div class="card"><div class="k">Avg model latency</div><div class="v">${fmtMs(agg.avgModelLatencyMs)}</div></div>

package/dist/telemetry.js

@@ -111,6 +111,38 @@ export function cleanUsage(value) {
         ? out
         : undefined;
 }
+// Keep only a well-formed goal snapshot (tolerant reader/writer pair with
+// the dashboard: absent or malformed reads as no-goal, never a throw).
+// Returns undefined when no goal was live. The objective is capped so a
+// pasted paragraph cannot bloat the trace; counters copy finite values only.
+export function cleanGoalSnapshot(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const objective = o["objective"];
+    if (typeof objective !== "string" || objective.length === 0)
+        return undefined;
+    const snap = {
+        objective: objective.length > TELEMETRY_INPUT_PREVIEW_CHARS
+            ? objective.slice(0, TELEMETRY_INPUT_PREVIEW_CHARS)
+            : objective,
+        active: o["active"] === true,
+    };
+    const counter = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+    const turns = counter(o["turns"]);
+    if (turns !== undefined)
+        snap.turns = turns;
+    const requests = counter(o["requests"]);
+    if (requests !== undefined)
+        snap.requests = requests;
+    const tokens = counter(o["tokens"]);
+    if (tokens !== undefined)
+        snap.tokens = tokens;
+    const workMs = counter(o["workMs"]);
+    if (workMs !== undefined)
+        snap.workMs = workMs;
+    return snap;
+}
 export function addUsageInto(target, extra) {
     if (!extra)
         return false;
@@ -438,6 +470,7 @@ export function summarizeTelemetry(sessions) {
         retries: 0,
         cacheHits: 0,
         repetitionHits: 0,
+        goalTurns: 0,
         outcomes: emptyOutcomes(),
         byTool: [],
         avgModelLatencyMs: null,
@@ -462,6 +495,9 @@ export function summarizeTelemetry(sessions) {
                 agg.turns += 1;
                 if (t.outcome in agg.outcomes)
                     agg.outcomes[t.outcome] += 1;
+                if (t.goal && typeof t.goal.objective === "string" && t.goal.objective.length > 0) {
+                    agg.goalTurns += 1;
+                }
                 if (t.usageReported) {
                     if (addUsageInto(agg.usage, t.usage))
                         agg.usageReported = true;
@@ -657,6 +693,9 @@ export class TelemetryRecorder {
                 usageReported: false,
                 retryCount: 0,
             };
+            const goalSnap = cleanGoalSnapshot(meta.goal);
+            if (goalSnap)
+                turn.goal = goalSnap;
             this.session.turns.push(turn);
             this.openTurns.set(id, turn);
             this.pendingRetries = [];

package/dist/tools/compaction-hooks.js

@@ -0,0 +1,165 @@
+// Before-compaction hooks (ticket 09): extension interception over automatic
+// and manual compaction (cancel or custom summary).
+//
+// Dependency-free like intercept.ts and provider-hooks.ts (type-only imports)
+// so the extension host, the compaction caller (App.tsx), and the tests can
+// all share it with no cycle: extensions register here, doCompact applies
+// here, nobody imports the other.
+//
+// Semantics (fail-open vs fail-closed):
+// - Cancel (fail CLOSED on explicit veto, fail OPEN on throws): handlers run
+//   in registration order BEFORE any snapshot/persist/mutate step with the
+//   reason and the pending head/tail split. Only an explicit cancel vetoes —
+//   true (default reason naming the extension), a non-empty string (that
+//   reason), or { cancel: true | "reason" }. Everything else
+//   (void/null/false/{cancel:false}/foreign shapes) allows. The first cancel
+//   wins: later handlers never run. A throwing handler is recorded and fails
+//   OPEN (degrades to the builtin summary with a visible error) — a buggy
+//   extension must never hold compaction hostage or half-compact a session
+//   (same rationale as the before_switch fail-open gate).
+// - Custom summary (fail OPEN): a handler may return { summary: "text" } to
+//   replace the builtin summarizer output. The text must be a non-empty
+//   string after trimming — anything else is ignored. The first valid
+//   summary wins: later handlers never run. The winning text enters the SAME
+//   post-processing as builtin output (touched-files append/fit, boundary
+//   marker, atomic swap, save, snapshot clearing) at the single injection
+//   point in doCompact — never a parallel pipeline. A bare string return is
+//   a cancel reason (the before_switch convention), never a summary, so the
+//   two decisions can never be confused.
+// - Read-only split: handlers observe deep copies (per-handler fresh clones
+//   of a pristine snapshot), never the live split arrays — an in-place
+//   mutation by a handler must not corrupt planning (the provider-hooks
+//   deep-copy precedent). The apply entry point never mutates its inputs.
+//
+// Coverage: doCompact in App.tsx is the single compaction funnel (manual
+// /compact via runCompactCommand, pending drains, and auto via
+// maybeAutoCompact all route through it), so one gate covers every reason —
+// auto, manual, and the overflow domain the type reserves for future callers.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e ?? "unknown error");
+}
+function cloneMessages(messages) {
+    try {
+        return structuredClone(messages);
+    }
+    catch {
+        try {
+            return JSON.parse(JSON.stringify(messages));
+        }
+        catch {
+            return messages.map((m) => ({ ...m }));
+        }
+    }
+}
+// Cancel interpretation (single rule, mirrors the before_switch gate): only
+// an explicit veto cancels — true (default reason), a string (that reason,
+// empty falls back to the default), or { cancel: true | "reason" }.
+// Everything else (void/null/false/{cancel:false}/foreign shapes) allows.
+function cancelReasonOf(decision, owner) {
+    if (decision === true)
+        return `extension "${owner}" cancelled compaction`;
+    if (typeof decision === "string") {
+        return decision.length > 0 ? decision : `extension "${owner}" cancelled compaction`;
+    }
+    if (isRecord(decision)) {
+        const cancel = decision.cancel;
+        if (cancel === true)
+            return `extension "${owner}" cancelled compaction`;
+        if (typeof cancel === "string") {
+            return cancel.length > 0 ? cancel : `extension "${owner}" cancelled compaction`;
+        }
+    }
+    return null;
+}
+// Custom-summary interpretation (single rule): only { summary } with a
+// non-empty-after-trim string supplies — void/null/false/bare strings (a
+// bare string is a cancel reason above, never a summary)/foreign shapes pass
+// through to the builtin summarizer.
+function summaryOf(decision) {
+    if (!isRecord(decision))
+        return null;
+    const summary = decision.summary;
+    if (typeof summary !== "string" || summary.trim().length === 0)
+        return null;
+    return summary;
+}
+const beforeCompactHandlers = [];
+/** Register a before-compaction hook. Returns an unregister function. */
+export function registerBeforeCompact(handler, owner = "(unknown)") {
+    if (typeof handler !== "function") {
+        throw new Error("before-compact handler must be a function");
+    }
+    const record = { owner, handler };
+    beforeCompactHandlers.push(record);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        const idx = beforeCompactHandlers.indexOf(record);
+        if (idx >= 0)
+            beforeCompactHandlers.splice(idx, 1);
+    };
+}
+/** Snapshot of live before-compaction handlers in registration order (deterministic composition). */
+export function beforeCompactInterceptors() {
+    return [...beforeCompactHandlers];
+}
+/** Test seam: drop every compaction hook. */
+export function clearCompactionHooks() {
+    beforeCompactHandlers.length = 0;
+}
+// Apply before-compaction handlers sequentially in registration order. Never
+// throws and never mutates its inputs: each handler receives fresh deep
+// copies of a pristine snapshot, a throwing handler is recorded fail-open
+// (its veto/summary dropped, the chain continues), and the first explicit
+// cancel — or the first valid custom summary — wins with later handlers
+// never running (the before_switch first-wins precedent).
+export async function applyBeforeCompact(handlers, info) {
+    const out = {
+        cancelled: false,
+        cancelReason: null,
+        cancelOwner: null,
+        summary: null,
+        summaryOwner: null,
+        errors: [],
+    };
+    // Pristine snapshot first (never the caller's live arrays): per-handler
+    // clones below mean a mutating hook corrupts neither planning nor the
+    // next handler's view.
+    const pristineHead = cloneMessages(info.head);
+    const pristineTail = cloneMessages(info.tail);
+    for (const record of handlers) {
+        let decision;
+        try {
+            decision = await record.handler({
+                reason: info.reason,
+                focusText: info.focusText,
+                head: cloneMessages(pristineHead),
+                tail: cloneMessages(pristineTail),
+                olderTurnCount: info.olderTurnCount,
+            });
+        }
+        catch (e) {
+            out.errors.push(`${record.owner}: ${errorText(e)}`);
+            continue;
+        }
+        const reason = cancelReasonOf(decision, record.owner);
+        if (reason !== null) {
+            out.cancelled = true;
+            out.cancelReason = reason;
+            out.cancelOwner = record.owner;
+            return out;
+        }
+        const summary = summaryOf(decision);
+        if (summary !== null) {
+            out.summary = summary;
+            out.summaryOwner = record.owner;
+            return out;
+        }
+    }
+    return out;
+}

package/dist/tools/custom.js

@@ -0,0 +1,189 @@
+// Extension-registered model-callable tools (ticket 02): the runtime store
+// behind ExtensionAPI.registerTool. This module stays dependency-free apart
+// from the sibling overrides store (which itself imports nothing), so the
+// registry and the scheduler can still consult it without a runtime cycle.
+import { isToolExecutionMode } from "./overrides.js";
+const NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const store = new Map();
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function shapeSummary(parameters) {
+    // Compact `{field: type}` hint for error details; falls back to raw JSON.
+    try {
+        const props = parameters["properties"];
+        if (isRecord(props)) {
+            const parts = [];
+            for (const [k, v] of Object.entries(props)) {
+                const t = isRecord(v) && typeof v["type"] === "string" ? v["type"] : "any";
+                parts.push(`"${k}": ${t}`);
+            }
+            const required = Array.isArray(parameters["required"])
+                ? ` (required: ${parameters["required"].map((r) => JSON.stringify(r)).join(", ")})`
+                : "";
+            return `{${parts.join(", ")}}${required}`;
+        }
+        const raw = JSON.stringify(parameters);
+        return raw.length > 200 ? `${raw.slice(0, 200)}…` : raw;
+    }
+    catch {
+        return "{}";
+    }
+}
+/**
+ * Validate a registration shape. Throws Error on any problem (bad name,
+ * empty description, non-object schema, non-function execute). Duplicate
+ * and builtin-collision checks live in the registry wrapper
+ * (registerExtensionTool), which knows the builtin names.
+ */
+export function validateExtensionToolDef(def) {
+    if (!isRecord(def))
+        throw new Error("extension tool definition must be an object");
+    if (typeof def.name !== "string" || !NAME_RE.test(def.name)) {
+        throw new Error(`extension tool has an invalid name ${JSON.stringify(def.name)} (want 1-64 chars of A-Za-z0-9_-)`);
+    }
+    if (typeof def.description !== "string" || def.description.trim().length === 0) {
+        throw new Error(`extension tool "${def.name}" needs a non-empty description`);
+    }
+    if (!isRecord(def.parameters) || def.parameters["type"] !== "object") {
+        throw new Error(`extension tool "${def.name}" needs a parameters schema object with type "object"`);
+    }
+    if (typeof def.execute !== "function") {
+        throw new Error(`extension tool "${def.name}" needs an execute function`);
+    }
+    if (def.requireApproval !== undefined && typeof def.requireApproval !== "boolean") {
+        throw new Error(`extension tool "${def.name}" field "requireApproval" must be a boolean`);
+    }
+    if (def.oneLiner !== undefined && typeof def.oneLiner !== "string") {
+        throw new Error(`extension tool "${def.name}" field "oneLiner" must be a string`);
+    }
+    if (def.executionMode !== undefined && !isToolExecutionMode(def.executionMode)) {
+        throw new Error(`extension tool "${def.name}" field "executionMode" must be "sequential" or "parallel"`);
+    }
+}
+function typeLabel(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    return typeof v;
+}
+function schemaTypeMatches(schema, value) {
+    const t = schema["type"];
+    if (typeof t !== "string")
+        return true; // untyped property: anything goes
+    switch (t) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+        case "null":
+            return value === null;
+        default:
+            return true; // unknown type keyword: do not reject
+    }
+}
+// Validate parsed args against the tool's parameters schema. Returns a
+// detail string (without prefix) when malformed, or null when valid — the
+// caller frames it with invalidCall so failures surface as inline
+// model-visible errors and the tool never runs.
+export function validateCustomToolArgs(name, args) {
+    const rec = store.get(name);
+    if (!rec)
+        return null;
+    if (!isRecord(args)) {
+        return `arguments for tool "${name}" must be an object. Expected ${shapeSummary(rec.parameters)}`;
+    }
+    const exp = shapeSummary(rec.parameters);
+    const schema = rec.parameters;
+    const required = schema["required"];
+    if (Array.isArray(required)) {
+        for (const key of required) {
+            if (typeof key !== "string")
+                continue;
+            if (args[key] === undefined) {
+                return `missing required field "${key}" for tool "${name}". Expected ${exp}`;
+            }
+        }
+    }
+    const props = schema["properties"];
+    if (isRecord(props)) {
+        for (const [key, propSchema] of Object.entries(props)) {
+            const value = args[key];
+            if (value === undefined)
+                continue;
+            if (!isRecord(propSchema))
+                continue;
+            if (!schemaTypeMatches(propSchema, value)) {
+                const want = typeof propSchema["type"] === "string" ? propSchema["type"] : "matching value";
+                return `field "${key}" for tool "${name}" must be a ${want} (got ${typeLabel(value)}). Expected ${exp}`;
+            }
+            const en = propSchema["enum"];
+            if (Array.isArray(en) && !en.includes(value)) {
+                return `field "${key}" for tool "${name}" must be one of ${JSON.stringify(en)} (got ${JSON.stringify(value)}). Expected ${exp}`;
+            }
+        }
+    }
+    if (schema["additionalProperties"] === false && isRecord(props)) {
+        for (const key of Object.keys(args)) {
+            if (!(key in props)) {
+                return `unknown field "${key}" for tool "${name}". Expected ${exp}`;
+            }
+        }
+    }
+    return null;
+}
+/** Register a validated custom tool. Throws on duplicate names. */
+export function registerCustomTool(def) {
+    validateExtensionToolDef(def);
+    if (store.has(def.name)) {
+        throw new Error(`extension tool "${def.name}" is already registered`);
+    }
+    const rec = {
+        name: def.name,
+        description: def.description,
+        parameters: def.parameters,
+        execute: def.execute,
+        requireApproval: def.requireApproval ?? true,
+        executionMode: def.executionMode,
+        oneLiner: typeof def.oneLiner === "string" && def.oneLiner.length > 0
+            ? def.oneLiner
+            : def.description.split("\n")[0].slice(0, 120),
+    };
+    store.set(def.name, rec);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        if (store.get(def.name) === rec)
+            store.delete(def.name);
+    };
+}
+export function unregisterCustomTool(name) {
+    return store.delete(name);
+}
+export function getCustomTool(name) {
+    return store.get(name);
+}
+export function isCustomTool(name) {
+    return store.has(name);
+}
+export function customToolNames() {
+    return [...store.keys()];
+}
+export function listCustomTools() {
+    return [...store.values()];
+}
+/** Test seam: drop every custom tool (callers restore one-liners separately). */
+export function clearCustomTools() {
+    store.clear();
+}

package/dist/tools/dir-cache.js

@@ -76,6 +76,13 @@ function toCwdRel(absDir, cwd, dirRel) {
         return dirRel;
     return `${prefix}/${dirRel}`;
 }
+// Public for the ripgrep adapter: rg emits dir-relative paths, but the
+// enumerated contract (and therefore outputs) is cwd-relative — which may
+// climb out of the tree (`../../..`) when the search dir sits outside cwd.
+// Exported so both paths share the one mapping (never duplicated logic).
+export function rgRelToCwdRel(absDir, cwd, dirRel) {
+    return toCwdRel(absDir, cwd, dirRel);
+}
 function filterSkipped(relPaths) {
     return relPaths.filter((rel) => {
         if (!rel)

package/dist/tools/filesystem.js

@@ -7,7 +7,7 @@ import { contentHash, fingerprintKey, readFingerprints } from "./fingerprints.js
 import { appendOverflow } from "./overflow.js";
 import { getCachedRead, invalidatePath, normalizeReadWindow, setCachedRead } from "./read-cache.js";
 import { invalidateListingsForFile } from "./dir-cache.js";
-import { err, invalidCall, READ_CHAR_CAP, resolveSandbox } from "./shared.js";
+import { err, invalidCall, READ_CHAR_CAP, resolveSandbox, truncateHead } from "./shared.js";
 // offset/limit are 1-based line numbers. Output capped at ~64KB.
 export async function readTool(args, cwd = process.cwd()) {
     try {
@@ -58,7 +58,8 @@ export async function readTool(args, cwd = process.cwd()) {
         let out = window.map((line, i) => `${offset + i}: ${line}`).join("\n");
         if (out.length > READ_CHAR_CAP) {
             const full = out;
-            out = appendOverflow(full.slice(0, READ_CHAR_CAP), "\n[truncated: output exceeded 64KB]", "file output", full);
+            const t = truncateHead(full, READ_CHAR_CAP, "\n[truncated: output exceeded 64KB]");
+            out = appendOverflow(t.head, t.note, "file output", full);
         }
         try {
             const statInfo = { mtimeMs: st.mtimeMs ?? 0, size: st.size ?? 0 };

package/dist/tools/intercept.js

@@ -0,0 +1,145 @@
+// Tool-call interception store (ticket 03): extension pre/post hooks over
+// every loop-executed tool call (builtins and custom tools alike).
+//
+// Dependency-free like custom.ts (no imports) so the extension host, the
+// registry barrel, and the agentic loop can all share it with no cycle:
+// extensions register here, the loop applies here, nobody imports the other.
+//
+// Semantics:
+// - Before handlers run in registration order and see each call pre-
+//   validation and pre-approval. Each may return { args } to rewrite the
+//   arguments (later handlers see the rewrite) or { block: reason } / a
+//   reason string / { block: true } to veto the execution. The first block
+//   wins: later handlers never run for a blocked call, approval is skipped
+//   entirely, and the reason commits as a normal model-visible result.
+// - A throwing (or rejecting) before handler fails CLOSED: the call is
+//   blocked with a handler-failed reason and the turn continues. Unknown
+//   behavior never executes blindly.
+// - After handlers run in registration order inside the commit funnel, so
+//   they observe every committed result (executions, blocks, denials,
+//   validation errors). Each may return a string or { content } to patch
+//   what the model sees. A throwing after handler fails OPEN to the
+//   original result — a patch must never break the turn or the
+//   tool_call_id re-pairing/commit order around it.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorText(e) {
+    return e instanceof Error ? e.message : String(e ?? "unknown error");
+}
+const beforeHandlers = [];
+const afterHandlers = [];
+/** Register a pre-execution interceptor. Returns an unregister function. */
+export function registerBeforeToolCall(handler, owner = "(unknown)") {
+    if (typeof handler !== "function") {
+        throw new Error("before-tool-call handler must be a function");
+    }
+    const record = { owner, handler };
+    beforeHandlers.push(record);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        const idx = beforeHandlers.indexOf(record);
+        if (idx >= 0)
+            beforeHandlers.splice(idx, 1);
+    };
+}
+/** Register a post-execution result patcher. Returns an unregister function. */
+export function registerAfterToolCall(handler, owner = "(unknown)") {
+    if (typeof handler !== "function") {
+        throw new Error("after-tool-call handler must be a function");
+    }
+    const record = { owner, handler };
+    afterHandlers.push(record);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        const idx = afterHandlers.indexOf(record);
+        if (idx >= 0)
+            afterHandlers.splice(idx, 1);
+    };
+}
+/** Snapshot of live before handlers in registration order (deterministic composition). */
+export function beforeToolInterceptors() {
+    return [...beforeHandlers];
+}
+/** Snapshot of live after handlers in registration order. */
+export function afterToolInterceptors() {
+    return [...afterHandlers];
+}
+/** Test seam: drop every interceptor. */
+export function clearToolInterceptors() {
+    beforeHandlers.length = 0;
+    afterHandlers.length = 0;
+}
+/** Model-visible result for a blocked call (an `Error:` result, committed normally — the turn continues). */
+export function blockedToolResult(name, owner, reason) {
+    const trimmed = reason.trim();
+    const by = owner.length > 0 ? `extension "${owner}"` : "extension";
+    return trimmed.length > 0
+        ? `Error: blocked by ${by}: ${trimmed}`
+        : `Error: blocked by ${by}: tool "${name}" was blocked`;
+}
+// Apply before handlers sequentially in registration order. Never throws:
+// a throwing handler fails closed to a blocked outcome carrying the cause.
+export async function applyBeforeInterceptors(handlers, name, args) {
+    let current = args;
+    for (const record of handlers) {
+        let decision;
+        try {
+            decision = await record.handler({ name, args: current });
+        }
+        catch (e) {
+            return {
+                args: current,
+                blocked: blockedToolResult(name, record.owner, `handler failed: ${errorText(e)}`),
+            };
+        }
+        if (typeof decision === "string") {
+            // Convenience form: a returned string is a block reason.
+            return { args: current, blocked: blockedToolResult(name, record.owner, decision) };
+        }
+        if (!isRecord(decision))
+            continue;
+        const next = decision;
+        if (isRecord(next["args"]))
+            current = next["args"];
+        const block = next["block"];
+        if (block === true) {
+            return { args: current, blocked: blockedToolResult(name, record.owner, "") };
+        }
+        if (typeof block === "string" && block.trim().length > 0) {
+            return { args: current, blocked: blockedToolResult(name, record.owner, block) };
+        }
+    }
+    return { args: current, blocked: null };
+}
+// Apply after handlers sequentially; each sees the previous patch. Never
+// throws: a throwing handler fails open to the content so far.
+export async function applyAfterInterceptors(handlers, input) {
+    let content = input.result;
+    const isError = input.isError;
+    for (const record of handlers) {
+        let decision;
+        try {
+            decision = await record.handler({ name: input.name, args: input.args, result: content, isError });
+        }
+        catch {
+            continue;
+        }
+        if (typeof decision === "string") {
+            content = decision;
+            continue;
+        }
+        if (!isRecord(decision))
+            continue;
+        const patch = decision["content"];
+        if (typeof patch === "string")
+            content = patch;
+    }
+    return { content, isError };
+}