agent-sh 0.7.0 → 0.9.0

package/dist/utils/message-utils.js

@@ -0,0 +1,75 @@
+/**
+ * Utilities for manipulating OpenAI-format message arrays.
+ *
+ * Used by extensions advising `conversation:prepare` to transform
+ * the message array before it's sent to the LLM.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Find tool call IDs matching a tool name and optional argument filter.
+ *
+ * Scans assistant messages for tool_calls where `function.name` matches
+ * and parsed arguments satisfy the filter (shallow key/value match).
+ *
+ * Returns call IDs in message order (earliest first).
+ */
+export function findToolCallIds(messages, toolName, argFilter) {
+    const ids = [];
+    for (const msg of messages) {
+        if (msg.role !== "assistant" || !msg.tool_calls)
+            continue;
+        for (const tc of msg.tool_calls) {
+            const fn = tc.function ?? tc.fn;
+            if (!fn || fn.name !== toolName)
+                continue;
+            if (argFilter) {
+                let args;
+                try {
+                    args = JSON.parse(fn.arguments);
+                }
+                catch {
+                    continue;
+                }
+                const match = Object.entries(argFilter).every(([k, v]) => args[k] === v);
+                if (!match)
+                    continue;
+            }
+            ids.push(tc.id);
+        }
+    }
+    return ids;
+}
+/**
+ * Replace tool result content for specific call IDs.
+ *
+ * Returns a new array (shallow copy) with matching tool messages
+ * replaced. Non-matching messages are passed through by reference.
+ */
+export function stubToolResults(messages, callIds, stub) {
+    return messages.map((msg) => {
+        if (msg.role === "tool" && callIds.has(msg.tool_call_id)) {
+            return { ...msg, content: stub };
+        }
+        return msg;
+    });
+}
+/**
+ * Deduplicate tool results: keep only the latest result for a given
+ * tool name + argument filter, replace all older results with a stub.
+ *
+ * Common use case: a file that's read repeatedly (e.g. a live transcript)
+ * — only the most recent read matters.
+ *
+ * Example:
+ *   dedupeToolResults(messages, "read_file",
+ *     { path: "/path/to/transcript.txt" },
+ *     "[stale — superseded by later read]")
+ */
+export function dedupeToolResults(messages, toolName, argFilter, stub = "[superseded by later call]") {
+    const callIds = findToolCallIds(messages, toolName, argFilter);
+    if (callIds.length <= 1)
+        return messages;
+    // Keep the last one, stub the rest
+    const staleIds = new Set(callIds.slice(0, -1));
+    return stubToolResults(messages, staleIds, stub);
+}

package/dist/utils/terminal-buffer.d.ts

@@ -28,6 +28,8 @@ export declare function formatScreenContext(screen: ScreenSnapshot, maxLines?: n
 export declare class TerminalBuffer {
     private readonly term;
     private readonly serializeAddon;
+    /** Flush pending drip-feed data (set by createWired). */
+    _flushPending: (() => void) | null;
     private constructor();
     /**
      * Create a new TerminalBuffer. Returns null if xterm is not installed.
@@ -38,12 +40,16 @@ export declare class TerminalBuffer {
      * Returns null if xterm is not installed.
      */
     static createWired(bus: EventBus, config?: TerminalBufferConfig): TerminalBuffer | null;
+    /** Flush any pending drip-feed data into the virtual terminal. */
+    flush(): void;
     /** Write raw data into the virtual terminal. */
     write(data: string): void;
     /** Get the raw serialized terminal output (includes ANSI sequences). */
     serialize(): string;
     /** Read clean screen text with metadata. */
-    readScreen(): ScreenSnapshot;
+    readScreen(opts?: {
+        includeScrollback?: boolean;
+    }): ScreenSnapshot;
     /**
      * Get terminal screen as lines, padded/trimmed to exactly `rows` lines.
      * Clean text only (ANSI stripped).  Reads from the active buffer's
@@ -53,6 +59,8 @@ export declare class TerminalBuffer {
     getScreenLines(rows?: number): string[];
     /** Read visible viewport lines from a buffer. */
     private readViewportLines;
+    /** Read all lines including scrollback from a buffer. */
+    private readAllLines;
     /** Get cursor position. */
     getCursor(): {
         x: number;

package/dist/utils/terminal-buffer.js

@@ -65,6 +65,8 @@ export function formatScreenContext(screen, maxLines = 80, baseContext) {
 export class TerminalBuffer {
     term;
     serializeAddon;
+    /** Flush pending drip-feed data (set by createWired). */
+    _flushPending = null;
     constructor(term, serialize) {
         this.term = term;
         this.serializeAddon = serialize;
@@ -103,11 +105,22 @@ export class TerminalBuffer {
                 tb.write(d);
             }
         }, 50);
+        tb._flushPending = () => {
+            if (pending) {
+                const d = pending;
+                pending = "";
+                tb.write(d);
+            }
+        };
         process.stdout.on("resize", () => {
             tb.resize(process.stdout.columns || 80, process.stdout.rows || 24);
         });
         return tb;
     }
+    /** Flush any pending drip-feed data into the virtual terminal. */
+    flush() {
+        this._flushPending?.();
+    }
     /** Write raw data into the virtual terminal. */
     write(data) {
         this.term.write(data);
@@ -117,9 +130,11 @@ export class TerminalBuffer {
         return this.serializeAddon.serialize();
     }
     /** Read clean screen text with metadata. */
-    readScreen() {
+    readScreen(opts) {
         const buf = this.term.buffer.active;
-        const lines = this.readViewportLines(buf);
+        const lines = opts?.includeScrollback
+            ? this.readAllLines(buf)
+            : this.readViewportLines(buf);
         return {
             text: lines.join("\n"),
             altScreen: buf.type === "alternate",
@@ -148,6 +163,20 @@ export class TerminalBuffer {
         }
         return lines;
     }
+    /** Read all lines including scrollback from a buffer. */
+    readAllLines(buf) {
+        const total = (buf.baseY ?? 0) + buf.length;
+        const lines = [];
+        for (let y = 0; y < total; y++) {
+            const line = buf.getLine(y);
+            lines.push(line ? line.translateToString(true) : "");
+        }
+        // Trim trailing empty lines
+        while (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines.pop();
+        }
+        return lines;
+    }
     /** Get cursor position. */
     getCursor() {
         return {

package/dist/utils/tool-display.d.ts

@@ -30,6 +30,7 @@ export declare function selectToolDisplayMode(width: number): ToolDisplayMode;
 export declare function renderToolCall(tool: ToolCallRender, width: number): string[];
 export declare function renderToolResult(result: ToolResultRender, width: number): string[];
 export declare function formatElapsed(ms: number): string;
+export declare const SPINNER_FRAMES: string[];
 export interface SpinnerState {
     frame: number;
     startTime: number;

package/dist/utils/tool-display.js

@@ -205,7 +205,7 @@ export function formatElapsed(ms) {
     return rm > 0 ? `${h}h ${rm}m` : `${h}h`;
 }
 // ── Spinner with elapsed timer ───────────────────────────────────
-const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 export function createSpinner(opts) {
     return { frame: 0, startTime: opts?.startTime || Date.now() };
 }

package/dist/utils/tool-interactive.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Interactive UI primitive for tools.
+ *
+ * Gives a tool imperative control over rendering and input on the active
+ * surface. The tool provides render() + handleInput(), the primitive
+ * handles surface writing, input interception, shell pause/unpause,
+ * and cleanup.
+ */
+import type { EventBus } from "../event-bus.js";
+import type { RenderSurface } from "./compositor.js";
+import type { ToolUI } from "../agent/types.js";
+export declare function createToolUI(bus: EventBus, surface: RenderSurface): ToolUI;

package/dist/utils/tool-interactive.js

@@ -0,0 +1,53 @@
+/** Clear N lines above the cursor. */
+function clearLines(surface, count) {
+    for (let i = 0; i < count; i++) {
+        surface.write("\x1b[A\x1b[2K");
+    }
+}
+export function createToolUI(bus, surface) {
+    return {
+        custom(session) {
+            return new Promise((resolve) => {
+                let prevLineCount = 0;
+                let finished = false;
+                const done = (result) => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    clearLines(surface, prevLineCount);
+                    bus.offPipe("input:intercept", interceptor);
+                    bus.emit("shell:stdout-hide", {});
+                    bus.emit("tool:interactive-end", {});
+                    session.onUnmount?.();
+                    resolve(result);
+                };
+                const render = () => {
+                    if (finished)
+                        return;
+                    clearLines(surface, prevLineCount);
+                    const lines = session.render(surface.columns);
+                    for (const line of lines) {
+                        surface.writeLine(line);
+                    }
+                    prevLineCount = lines.length;
+                };
+                const interceptor = (payload) => {
+                    if (finished)
+                        return payload;
+                    // Let Ctrl+C through for agent cancellation
+                    if (payload.data === "\x03")
+                        return payload;
+                    session.handleInput(payload.data, done);
+                    render();
+                    return { ...payload, consumed: true };
+                };
+                // Setup
+                bus.emit("tool:interactive-start", {});
+                bus.emit("shell:stdout-show", {});
+                bus.onPipe("input:intercept", interceptor);
+                session.onMount?.(() => render());
+                render();
+            });
+        },
+    };
+}

package/examples/extensions/ash-acp-bridge/README.md

@@ -0,0 +1,39 @@
+# ash-acp-bridge
+
+ACP (Agent Client Protocol) server that wraps agent-sh's headless core, allowing any ACP-compatible client to use ash as a backend.
+
+## Setup
+
+```bash
+cd ash-acp-bridge
+npm install
+npm run build    # or use `npx tsx src/index.ts` for dev
+```
+
+## Usage
+
+```bash
+ash-acp-bridge                          # use ~/.agent-sh/settings.json defaults
+ash-acp-bridge --model gpt-4o           # override model
+ash-acp-bridge --provider anthropic     # override provider
+```
+
+## How it works
+
+```
+ACP client
+    ↕ JSON-RPC over stdin/stdout (ACP)
+ash-acp-bridge
+    ↕ EventBus
+agent-sh core (headless)
+    ↕ OpenAI-compatible API
+LLM provider
+```
+
+The adapter translates between ACP methods and agent-sh's event bus:
+
+- `initialize` → return capabilities
+- `session/new` → create core, set cwd
+- `session/prompt` → `agent:submit` event
+- `session/update` notifications ← `agent:response-chunk`, `agent:tool-started`, etc.
+- `session/request_permission` ↔ `permission:request` async pipe

package/examples/extensions/ash-acp-bridge/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "ash-acp-bridge",
+  "version": "0.1.0",
+  "description": "ACP server that wraps agent-sh's headless core for any ACP-compatible client",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ash-acp-bridge": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "agent-sh": "file:../../..",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}