@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/tools/file-change-store.js

@@ -0,0 +1,57 @@
+/**
+ * The CLI-local side channel a `FilePatch` travels on (agent-activity-presentation
+ * §3.3.5 / D-8).
+ *
+ * The patch does NOT ride in the tool result: `ToolResult` has no metadata
+ * channel and `packages/core`'s surface is frozen by `public-api.test.ts`, and
+ * more importantly a richer display must not cost the model more tokens. So the
+ * tool records the patch here, keyed by its own tool-call id, and `reduceEvent`
+ * takes it out again when `tool_execution_end` arrives.
+ *
+ * Three properties, each load-bearing:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`. Only `'lead'` is ever
+ *    written this round (`team/**` is out of scope, so `buildSubagentTools`
+ *    passes no recorder), but subagents build their tools from the same factory
+ *    — so the day one gets a recorder, a child's tool-call id must not be able
+ *    to land on a lead's card. One string concatenation, spent now (D-13).
+ *  - **Take-once.** `tool_execution_end` fires exactly once per call, and a patch
+ *    not consumed there never will be. Removal on read is what keeps a long
+ *    session's store at constant size however many files are edited.
+ *  - **Bounded FIFO.** At `cap` entries the oldest key is evicted. The cap is a
+ *    RING, not a leak detector: nothing is retained longer than `cap` writes, so
+ *    a patch nobody consumes cannot accumulate.
+ */
+/** Entries retained before the oldest is evicted. */
+export const FILE_CHANGE_STORE_CAP = 64;
+export function createFileChangeStore(cap = FILE_CHANGE_STORE_CAP) {
+    // A `Map` iterates in insertion order, so the first key IS the oldest.
+    const entries = new Map();
+    const limit = Math.max(1, Math.floor(cap));
+    const keyOf = (owner, toolCallId) => `${owner}:${toolCallId}`;
+    return {
+        record(owner, toolCallId, patch) {
+            const key = keyOf(owner, toolCallId);
+            // Delete first so a re-record moves the key to the END of the ring rather
+            // than leaving it at its original age.
+            entries.delete(key);
+            entries.set(key, patch);
+            while (entries.size > limit) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+        },
+        take(owner, toolCallId) {
+            const key = keyOf(owner, toolCallId);
+            const patch = entries.get(key);
+            if (patch !== undefined)
+                entries.delete(key);
+            return patch;
+        },
+        size() {
+            return entries.size;
+        },
+    };
+}

package/dist/tools/fs-tools.d.ts

@@ -7,8 +7,34 @@
  * tools do not re-implement them.
  */
 import { type AgentTool } from '@aragon-agent/core';
+import { type FilePatch } from './patch.js';
 export interface ToolDeps {
     getCwd: () => string;
+    /**
+     * Hand a structured patch to the UI on the CLI-local side channel
+     * (agent-activity-presentation §3.3.5).
+     *
+     * PRE-BOUND TO ITS OWNER by whoever supplies it, so this module never learns
+     * what an owner is. OPTIONAL, and omitting it leaves both tools byte-identical
+     * to the pre-feature build — including the extra `write_file` stat/read, which
+     * is skipped entirely when there is nobody to record for.
+     */
+    recordChange?: (toolCallId: string, patch: FilePatch) => void;
+    /**
+     * Hand a raw output chunk to the UI on the CLI-local side channel
+     * (agent-activity-presentation-live §3.1).
+     *
+     * PRE-BOUND TO ITS OWNER, exactly like `recordChange` above, so this module
+     * never learns what an owner is. OPTIONAL: omitting it leaves `bash`
+     * byte-identical to the pre-feature build -- not one extra allocation, not one
+     * extra call (AC-31).
+     *
+     * ONLY `bash` CALLS IT (D-32). Every other builtin is bounded local I/O that
+     * settles in milliseconds, so a progress channel for them would be machinery
+     * with no observer. The channel is keyed by tool-call id rather than by tool
+     * name, so a future long-running tool costs one call site.
+     */
+    recordOutput?: (toolCallId: string, chunk: string) => void;
 }
 export declare function makeReadFile(deps: ToolDeps): AgentTool;
 export declare function makeWriteFile(deps: ToolDeps): AgentTool;

package/dist/tools/fs-tools.js

@@ -10,6 +10,7 @@ import { promises as fs } from 'node:fs';
 import { isAbsolute, join, resolve, dirname } from 'node:path';
 import { defineTool, errorResult, textResult, } from '@aragon-agent/core';
 import { renderUnifiedDiff } from './diff.js';
+import { PATCH_LIMITS, buildPatch } from './patch.js';
 function resolvePath(cwd, p) {
     return isAbsolute(p) ? p : resolve(cwd, p);
 }
@@ -78,13 +79,20 @@ export function makeWriteFile(deps) {
             },
             required: ['path', 'content'],
         },
-        async execute(_id, rawParams) {
+        async execute(id, rawParams) {
             const params = rawParams;
             const target = resolvePath(deps.getCwd(), params.path);
             try {
+                // BEFORE the write, and only when somebody is listening. `readOldSide`
+                // swallows every failure itself, so a presentation feature can never
+                // prevent or delay the operation it presents (D-14 / R-6).
+                const oldSide = deps.recordChange ? await readOldSide(target) : null;
                 await fs.mkdir(dirname(target), { recursive: true });
                 await fs.writeFile(target, params.content, 'utf-8');
+                if (oldSide)
+                    recordFileChange(deps, id, oldSide, params.content, params.path);
                 const bytes = Buffer.byteLength(params.content, 'utf-8');
+                // BYTE-IDENTICAL model-facing text: the diff costs zero extra tokens.
                 return textResult(`Wrote ${bytes} bytes to ${params.path}`);
             }
             catch (err) {
@@ -116,7 +124,7 @@ export function makeEditFile(deps) {
             },
             required: ['path', 'old_string', 'new_string'],
         },
-        async execute(_id, rawParams) {
+        async execute(id, rawParams) {
             const params = rawParams;
             const target = resolvePath(deps.getCwd(), params.path);
             try {
@@ -138,6 +146,10 @@ export function makeEditFile(deps) {
                     ? original.split(params.old_string).join(params.new_string)
                     : original.replace(params.old_string, () => params.new_string);
                 await fs.writeFile(target, updated, 'utf-8');
+                // The same sentence, from the same data: the card's structured patch and
+                // the model's text are built from `original` / `updated` by one algorithm
+                // at two context widths (D-10 / D-20).
+                recordFileChange(deps, id, { text: original }, updated, params.path);
                 const diff = renderUnifiedDiff(original, updated, { path: params.path });
                 return textResult(`Applied edit to ${params.path}:\n${diff}`);
             }
@@ -189,9 +201,54 @@ export function makeListDir(deps) {
         },
     });
 }
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
+/**
+ * Best-effort read of the file `write_file` is about to overwrite.
+ *
+ * NEVER THROWS AND NEVER REPORTS AN ERROR TO THE MODEL. Every outcome is a
+ * `FilePatch` the card can render honestly:
+ *
+ *   ENOENT              -> null, no reason      -> a `create` diff
+ *   size > readMaxBytes -> null, `too-large`    -> an `update` we declined to read
+ *   binary sniff fails  -> null, `binary`       -> ditto
+ *   any other throw     -> null, `unreadable`   -> ditto
+ */
+async function readOldSide(target) {
+    try {
+        const stat = await fs.stat(target);
+        if (stat.size > PATCH_LIMITS.readMaxBytes)
+            return { text: null, degraded: 'too-large' };
+        const buf = await fs.readFile(target);
+        if (looksBinary(buf))
+            return { text: null, degraded: 'binary' };
+        return { text: buf.toString('utf-8') };
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { text: null };
+        return { text: null, degraded: 'unreadable' };
+    }
+}
+/**
+ * Build and hand over the patch, if anyone asked for one.
+ *
+ * WRAPPED, because `recordChange` is a caller-supplied closure and a display
+ * callback must not be able to fail a write that has already happened.
+ * `buildPatch` itself is total.
+ */
+function recordFileChange(deps, toolCallId, oldSide, newText, path) {
+    if (!deps.recordChange)
+        return;
+    try {
+        deps.recordChange(toolCallId, buildPatch(oldSide.text, newText, {
+            path,
+            context: PATCH_LIMITS.context,
+            ...(oldSide.degraded ? { degraded: oldSide.degraded } : {}),
+        }));
+    }
+    catch {
+        // Presentation only. The file is already on disk.
+    }
+}
 function countOccurrences(haystack, needle) {
     if (needle.length === 0)
         return 0;

package/dist/tools/index.d.ts

@@ -10,6 +10,7 @@
  */
 import { type AgentTool, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
+import type { FilePatch } from './patch.js';
 export interface ConfirmRequest {
     tool: string;
     summary: string;
@@ -29,6 +30,36 @@ export interface ConfirmRequest {
 }
 export interface BuiltinToolsOptions {
     getCwd: () => string;
+    /**
+     * Hand `write_file` / `edit_file` a place to leave a structured `FilePatch`
+     * (agent-activity-presentation §3.3.5), already bound to its owner.
+     *
+     * THE FIELD IS NEEDED IN TWO INTERFACES, NOT ONE. This bag is the factory's;
+     * `ToolDeps` is what the `make*` functions receive, and it is built below from
+     * exactly the fields named there. Adding it to `ToolDeps` alone type-checks and
+     * forwards nothing — the tools simply never record, and every card falls back
+     * to `ToolPreview` with no error anywhere (P1-3).
+     *
+     * Omitting it — every existing test, every headless run, and every subagent
+     * this round — leaves the tools byte-identical to today, which is the same
+     * opt-in shape `skillTools` / `planTools` / `todoTools` already use.
+     */
+    recordChange?: (toolCallId: string, patch: FilePatch) => void;
+    /**
+     * Hand `bash` a place to leave its raw output chunks
+     * (agent-activity-presentation-live §3.1.2), already bound to its owner.
+     *
+     * THE TWO-INTERFACE RULE ABOVE APPLIES VERBATIM (P1-1), and it applies because
+     * round 1 made this exact mistake once already with `recordChange`: adding the
+     * field to `ToolDeps` alone type-checks and forwards nothing, so `bash` never
+     * records, every running card stays the single `running` row it is today, and
+     * NOTHING ANYWHERE ERRORS.
+     *
+     * The conditional spread below is also what makes AC-31 true at this layer:
+     * with `liveToolOutput` off the controller passes no key, so no property is
+     * added and `deps` is the object it is today.
+     */
+    recordOutput?: (toolCallId: string, chunk: string) => void;
     /** When true (and `confirm` is provided), mutating tools are gated. */
     confirmTools?: boolean;
     /** Awaited before a mutating tool runs; resolve `false` to cancel. */

package/dist/tools/index.js

@@ -215,7 +215,13 @@ function withPlanModeGate(tool, getMode) {
     };
 }
 export function createBuiltinTools(options) {
-    const deps = { getCwd: options.getCwd };
+    const deps = {
+        getCwd: options.getCwd,
+        // The forward half of the two-interface note on `recordChange` above.
+        ...(options.recordChange ? { recordChange: options.recordChange } : {}),
+        // Added in the same shape and for the same reason (P1-1).
+        ...(options.recordOutput ? { recordOutput: options.recordOutput } : {}),
+    };
     let tools = [
         makeReadFile(deps),
         makeWriteFile(deps),

package/dist/tools/patch.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Structured file patches (agent-activity-presentation §3.3).
+ *
+ * PURE, NO I/O, NO REACT, ASCII-ONLY MARKERS. `glyphs.test.ts`'s static scan
+ * walks ALL of `src/` (skipping only `__tests__/` and two exempt files), so this
+ * module sits inside that guard rail directly rather than by analogy. The
+ * substantive reason is the one `reducer.ts` gives for `PREVIEW_TRUNCATION_MARK`:
+ * a string produced outside `src/ui/**` has no `TermCapabilities` in scope and
+ * must be safe on a legacy `cmd.exe`.
+ *
+ * The ladder is ANCHORED SPLIT -> BOUNDED LCS -> BLOCK REPLACE, and every
+ * recursion path terminates in one of three leaf returns. `blockReplace` is
+ * exactly what `renderUnifiedDiff` produced before this round — every old row as
+ * `del`, then every new row as `add` — kept as the explicit, bounded fallback so
+ * a pathological input degrades to today's behaviour rather than hanging.
+ *
+ * `buildPatch` is TOTAL: it never throws, for any pair of strings.
+ */
+export type PatchLineKind = 'ctx' | 'add' | 'del';
+export interface PatchLine {
+    kind: PatchLineKind;
+    /** 1-based line number in the OLD file; absent on an `add`. */
+    oldLine?: number;
+    /** 1-based line number in the NEW file; absent on a `del`. */
+    newLine?: number;
+    /** Rendered text. A trailing CR is stripped; long lines are truncated. */
+    text: string;
+}
+export interface PatchHunk {
+    oldStart: number;
+    oldCount: number;
+    newStart: number;
+    newCount: number;
+    lines: PatchLine[];
+}
+export interface FilePatch {
+    /** As the model wrote it — relative when the call was relative. */
+    path: string;
+    kind: 'create' | 'update';
+    added: number;
+    removed: number;
+    hunks: PatchHunk[];
+    /** Budget was hit; the tail of the change is not in `hunks`. */
+    truncated: boolean;
+    /**
+     * Total rendered rows across every hunk (summary and separators excluded).
+     *
+     * PRECOMPUTED so `entryRevision` stays O(1) (I-L3-1 forbids hashing, and
+     * summing `hunks[].lines.length` per entry per frame is exactly the cost the
+     * height cache exists to remove).
+     */
+    lineCount: number;
+    /** Set when the old side could not be read: too large, binary, or unreadable. */
+    degraded?: 'binary' | 'too-large' | 'unreadable';
+}
+export declare const PATCH_LIMITS: {
+    /**
+     * Context rows kept either side of a change, FOR THE UI.
+     *
+     * The text renderer does NOT use this (D-20): `renderUnifiedDiff` keeps its
+     * own `CONTEXT_LINES = 2` default so the model-facing diff does not silently
+     * widen by two rows on every single-region edit. One algorithm, two widths,
+     * chosen by the caller.
+     */
+    readonly context: 3;
+    /**
+     * Hunks separated by this many context rows or fewer are merged into one.
+     *
+     * MUST STAY `>= 2 * context` FOR EVERY CALLER'S CONTEXT WIDTH, or two adjacent
+     * hunks expanded by `context` would overlap and the same row would be rendered
+     * twice with two different line numbers. 6 covers both widths in use (3 and 2).
+     */
+    readonly mergeGap: 6;
+    /** Rendered rows a patch may carry, across all hunks. */
+    readonly maxLines: 200;
+    /** Total characters across all `PatchLine.text`. Mirrors STORED_PREVIEW_CHARS. */
+    readonly maxChars: 8000;
+    /** A single row is truncated past this, with `TRUNCATION_MARK`. */
+    readonly maxLineChars: 500;
+    /** Above this cell count the LCS leaf is refused; the segment becomes a block replace. */
+    readonly lcsCellBudget: 160000;
+    /** Recursion depth ceiling for the anchor split. */
+    readonly maxDepth: 32;
+    /** Old-side bytes above which `write_file` does not read for a diff. */
+    readonly readMaxBytes: number;
+    /** Model-facing diff text ceiling — a bound `edit_file` does not have today. */
+    readonly modelDiffMaxChars: 4000;
+};
+/**
+ * Appended to a row clipped at `maxLineChars`.
+ *
+ * SPELLED HERE RATHER THAN IMPORTED from `agent/reducer.ts`, so that `tools/`
+ * does not take a runtime dependency on the view model for one three-character
+ * string. `patch.test.ts` asserts the two spellings are equal, so the pair
+ * cannot drift silently — which is the property the import would have bought.
+ */
+export declare const TRUNCATION_MARK = "...";
+/** The note emitted when exactly one side ends with a newline. */
+export declare const NO_NEWLINE_NOTE = "(no newline at end of file)";
+export interface BuildPatchOptions {
+    /** As the model wrote it; carried onto the patch verbatim. */
+    path: string;
+    /** Context rows either side of a change. Defaults to `PATCH_LIMITS.context`. */
+    context?: number;
+    /**
+     * Why the old side is `null`.
+     *
+     * It also decides `kind`: a missing old side with no reason is a CREATE, and a
+     * missing old side WITH one is an UPDATE whose old half could not be read. The
+     * distinction matters because "created a file" and "overwrote a 5 MB file we
+     * declined to read" are different events and the card names them differently.
+     */
+    degraded?: FilePatch['degraded'];
+}
+export declare function buildPatch(oldText: string | null, newText: string, options: BuildPatchOptions): FilePatch;