atom-agent 1.2.0 → 1.3.0

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/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 };
+}

package/dist/tools/overrides.js

@@ -0,0 +1,105 @@
+export function isToolExecutionMode(value) {
+    return value === "sequential" || value === "parallel";
+}
+const overrides = new Map();
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * Validate an override shape. Throws Error on any problem (bad name,
+ * non-function execute, bad executionMode). Builtin-existence and duplicate
+ * checks live in the registry wrapper (registerExtensionToolOverride), which
+ * knows the builtin names.
+ */
+export function validateExtensionToolOverrideDef(def) {
+    if (!isRecord(def))
+        throw new Error("extension tool override definition must be an object");
+    if (typeof def.name !== "string" || !NAME_RE.test(def.name)) {
+        throw new Error(`extension tool override has an invalid name ${JSON.stringify(def.name)} (want 1-64 chars of A-Za-z0-9_-)`);
+    }
+    if (typeof def.execute !== "function") {
+        throw new Error(`extension tool override "${def.name}" needs an execute function`);
+    }
+    if (def.executionMode !== undefined && !isToolExecutionMode(def.executionMode)) {
+        throw new Error(`extension tool override "${def.name}" field "executionMode" must be "sequential" or "parallel"`);
+    }
+}
+/** Register a validated override. Throws on duplicate names. */
+export function registerToolOverride(def, owner = "(unknown)") {
+    validateExtensionToolOverrideDef(def);
+    if (overrides.has(def.name)) {
+        throw new Error(`extension tool override "${def.name}" is already registered`);
+    }
+    const rec = {
+        name: def.name,
+        execute: def.execute,
+        executionMode: def.executionMode,
+        owner,
+    };
+    overrides.set(def.name, rec);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        if (overrides.get(def.name) === rec)
+            overrides.delete(def.name);
+    };
+}
+export function unregisterToolOverride(name) {
+    return overrides.delete(name);
+}
+export function getToolOverride(name) {
+    return overrides.get(name);
+}
+export function isToolOverridden(name) {
+    return overrides.has(name);
+}
+/** Snapshot of live overrides in registration order (audit surface). */
+export function listToolOverrides() {
+    return [...overrides.values()];
+}
+/** Test seam: drop every tool override. */
+export function clearToolOverrides() {
+    overrides.clear();
+}
+// ---- Extension prompt hints (same ticket, same audit posture) ----
+// Short model-facing guidance strings ("prefer X with tool Y") contributed by
+// extensions. They reach the model only through the existing prompt assembly
+// (zen buildSystemPrompt appends them under an "Extension hints" section) —
+// no parallel prompt pipeline is ever introduced. Registration order is kept.
+export const MAX_PROMPT_HINT_CHARS = 2000;
+const promptHints = [];
+/** Validate a prompt hint shape. Throws Error on any problem. */
+export function validateExtensionPromptHint(hint) {
+    if (typeof hint !== "string" || hint.trim().length === 0) {
+        throw new Error("extension prompt hint must be a non-empty string");
+    }
+    if (hint.length > MAX_PROMPT_HINT_CHARS) {
+        throw new Error(`extension prompt hint exceeds ${MAX_PROMPT_HINT_CHARS} chars (got ${hint.length})`);
+    }
+}
+/** Register a prompt hint. Returns an unregister function. */
+export function registerExtensionPromptHint(hint, owner = "(unknown)") {
+    validateExtensionPromptHint(hint);
+    const record = { text: hint, owner };
+    promptHints.push(record);
+    let live = true;
+    return () => {
+        if (!live)
+            return;
+        live = false;
+        const idx = promptHints.indexOf(record);
+        if (idx >= 0)
+            promptHints.splice(idx, 1);
+    };
+}
+/** Hint texts in registration order (what the prompt assembly appends). */
+export function getExtensionPromptHints() {
+    return promptHints.map((h) => h.text);
+}
+/** Test seam: drop every prompt hint. */
+export function clearExtensionPromptHints() {
+    promptHints.length = 0;
+}