agent-sh 0.4.0 → 0.6.0

package/dist/agent/tools/ls.js

@@ -0,0 +1,72 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}K`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
+}
+export function createLsTool(getCwd) {
+    return {
+        name: "ls",
+        description: "List files and directories with timestamps and sizes. " +
+            "Use for exploring a single directory. Use glob for recursive file search by pattern.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Directory to list (default: cwd)",
+                },
+            },
+        },
+        showOutput: false,
+        getDisplayInfo: (args) => ({
+            kind: "read",
+            icon: "◆",
+            locations: args.path
+                ? [{ path: args.path }]
+                : [],
+        }),
+        formatResult: (_args, result) => {
+            if (result.isError || result.content === "(empty directory)")
+                return { summary: "0 entries" };
+            const lines = result.content.split("\n").filter(Boolean);
+            return { summary: `${lines.length} entries` };
+        },
+        async execute(args) {
+            const dirPath = args.path ?? ".";
+            const absPath = path.resolve(getCwd(), dirPath);
+            try {
+                const entries = await fs.readdir(absPath, {
+                    withFileTypes: true,
+                });
+                const lines = [];
+                for (const e of entries) {
+                    const fullPath = path.join(absPath, e.name);
+                    try {
+                        const stat = await fs.stat(fullPath);
+                        const size = e.isDirectory() ? "-" : formatSize(stat.size);
+                        const mtime = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
+                        lines.push(`${mtime}  ${size.padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`);
+                    }
+                    catch {
+                        lines.push(`${"?".padStart(16)}  ${"?".padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`);
+                    }
+                }
+                return {
+                    content: lines.join("\n") || "(empty directory)",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: `Error: ${msg}`, exitCode: 1, isError: true };
+            }
+        },
+    };
+}

package/dist/agent/tools/read-file.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDefinition } from "../types.js";
+/** Tracks the last-read state of a file for deduplication. */
+export interface FileReadState {
+    mtimeMs: number;
+    offset: number;
+    limit: number | undefined;
+}
+/** Shared cache — keyed by absolute path. */
+export type FileReadCache = Map<string, FileReadState>;
+export declare function createReadFileTool(getCwd: () => string, cache?: FileReadCache): ToolDefinition;

package/dist/agent/tools/read-file.js

@@ -0,0 +1,101 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export function createReadFileTool(getCwd, cache) {
+    return {
+        name: "read_file",
+        description: "Read a file's contents with line numbers. Use offset and limit for large files. " +
+            "Always read a file before editing it. " +
+            "If the file hasn't changed since last read, returns a stub to save context.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute or relative file path",
+                },
+                offset: {
+                    type: "number",
+                    description: "Starting line number (1-indexed)",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max lines to read",
+                },
+            },
+            required: ["path"],
+        },
+        showOutput: false,
+        getDisplayInfo: (args) => ({
+            kind: "read",
+            icon: "◆",
+            locations: [{ path: args.path }],
+        }),
+        formatResult: (_args, result) => {
+            if (result.isError)
+                return {};
+            if (result.content.startsWith("File unchanged"))
+                return { summary: "cached" };
+            const lines = result.content.split("\n").filter(l => !l.startsWith("["));
+            return { summary: `${lines.length} lines` };
+        },
+        async execute(args) {
+            const filePath = args.path;
+            const absPath = path.resolve(getCwd(), filePath);
+            const reqOffset = args.offset ?? 1;
+            const reqLimit = args.limit;
+            try {
+                const stat = await fs.stat(absPath);
+                // Deduplication: if the file hasn't changed and same range, return stub
+                if (cache) {
+                    const prev = cache.get(absPath);
+                    if (prev &&
+                        prev.mtimeMs === stat.mtimeMs &&
+                        prev.offset === reqOffset &&
+                        prev.limit === reqLimit) {
+                        return {
+                            content: "File unchanged since last read. The content from the earlier read_file result in this conversation is still current — refer to that instead of re-reading.",
+                            exitCode: 0,
+                            isError: false,
+                        };
+                    }
+                }
+                // Check file size before reading to avoid OOM on huge files
+                const MAX_FILE_SIZE = 2 * 1024 * 1024; // 2MB
+                if (stat.size > MAX_FILE_SIZE && !args.offset && !args.limit) {
+                    const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+                    return {
+                        content: `File is ${sizeMB}MB (${stat.size} bytes) — too large to read in full. Use offset and limit to read specific sections, e.g. offset=1 limit=200.`,
+                        exitCode: 1,
+                        isError: true,
+                    };
+                }
+                const content = await fs.readFile(absPath, "utf-8");
+                const lines = content.split("\n");
+                const start = reqOffset - 1; // 1-indexed → 0-indexed
+                const end = reqLimit ? start + reqLimit : lines.length;
+                const slice = lines.slice(start, end);
+                // Add line numbers (1-indexed)
+                const numbered = slice
+                    .map((line, i) => `${start + i + 1}\t${line}`)
+                    .join("\n");
+                const truncated = end < lines.length;
+                const suffix = truncated
+                    ? `\n[${lines.length - end} more lines, use offset=${end + 1} to continue]`
+                    : "";
+                // Update cache on successful read
+                if (cache) {
+                    cache.set(absPath, {
+                        mtimeMs: stat.mtimeMs,
+                        offset: reqOffset,
+                        limit: reqLimit,
+                    });
+                }
+                return { content: numbered + suffix, exitCode: 0, isError: false };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: `Error: ${msg}`, exitCode: 1, isError: true };
+            }
+        },
+    };
+}

package/dist/agent/tools/user-shell.d.ts

@@ -0,0 +1,13 @@
+import type { EventBus } from "../../event-bus.js";
+import type { ToolDefinition } from "../types.js";
+/**
+ * user_shell — runs commands in the user's live PTY shell.
+ *
+ * Unlike bash, this affects the user's shell state (cd, export, source).
+ * Output is shown directly in the terminal. By default, the agent doesn't
+ * see the output (return_output=false) to save tokens.
+ */
+export declare function createUserShellTool(opts: {
+    getCwd: () => string;
+    bus: EventBus;
+}): ToolDefinition;

package/dist/agent/tools/user-shell.js

@@ -0,0 +1,84 @@
+/**
+ * user_shell — runs commands in the user's live PTY shell.
+ *
+ * Unlike bash, this affects the user's shell state (cd, export, source).
+ * Output is shown directly in the terminal. By default, the agent doesn't
+ * see the output (return_output=false) to save tokens.
+ */
+export function createUserShellTool(opts) {
+    return {
+        name: "user_shell",
+        description: "Run a command with lasting effects in the user's live shell (cd, export, install packages, start servers, apply changes). Output is shown directly to the user but NOT returned to you by default — set return_output=true if you need to inspect the result.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "Command to execute in user's shell",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in seconds (default: 30)",
+                },
+                return_output: {
+                    type: "boolean",
+                    default: false,
+                    description: "Whether to return the command output to you. Default false — output is shown directly to the user. Set true only if you need to inspect the result to answer a question.",
+                },
+            },
+            required: ["command"],
+        },
+        showOutput: false,
+        modifiesFiles: true,
+        getDisplayInfo: () => ({
+            kind: "execute",
+            icon: "▷",
+            locations: [],
+        }),
+        async execute(args) {
+            const command = args.command;
+            const timeoutSec = args.timeout ?? 30;
+            const returnOutput = args.return_output ?? false;
+            // Execute via the shell-exec extension's async pipe with timeout
+            let result;
+            try {
+                const execPromise = opts.bus.emitPipeAsync("shell:exec-request", {
+                    command,
+                    output: "",
+                    cwd: opts.getCwd(),
+                    exitCode: null,
+                    done: false,
+                });
+                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), timeoutSec * 1000));
+                result = await Promise.race([execPromise, timeoutPromise]);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg === "timeout") {
+                    return {
+                        content: `Command timed out after ${timeoutSec}s.`,
+                        exitCode: -1,
+                        isError: true,
+                    };
+                }
+                return { content: `Error: ${msg}`, exitCode: -1, isError: true };
+            }
+            const exitCode = result.exitCode ?? 0;
+            const isError = exitCode !== 0 && exitCode !== null;
+            if (returnOutput) {
+                return {
+                    content: result.output || "(no output)",
+                    exitCode,
+                    isError,
+                };
+            }
+            return {
+                content: isError
+                    ? `Command failed with exit code ${exitCode}.`
+                    : "Command executed.",
+                exitCode,
+                isError,
+            };
+        },
+    };
+}

package/dist/agent/tools/write-file.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createWriteFileTool(getCwd: () => string): ToolDefinition;

package/dist/agent/tools/write-file.js

@@ -0,0 +1,82 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { computeDiff } from "../../utils/diff.js";
+export function createWriteFileTool(getCwd) {
+    return {
+        name: "write_file",
+        description: "Create a new file or completely overwrite an existing one. Creates parent directories if needed. " +
+            "ALWAYS prefer edit_file for modifying existing files — only use write_file for new files or complete rewrites.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute or relative file path",
+                },
+                content: {
+                    type: "string",
+                    description: "File content to write",
+                },
+            },
+            required: ["path", "content"],
+        },
+        showOutput: true,
+        modifiesFiles: true,
+        requiresPermission: true,
+        getDisplayInfo: (args) => ({
+            kind: "write",
+            icon: "✎",
+            locations: [{ path: args.path }],
+        }),
+        formatResult: (_args, result) => {
+            if (result.isError)
+                return {};
+            const m = result.content.match(/\((\+\d+(?:\s-\d+)?)\)/);
+            return m ? { summary: m[1] } : {};
+        },
+        async execute(args, onChunk) {
+            const filePath = args.path;
+            const content = args.content;
+            const absPath = path.resolve(getCwd(), filePath);
+            try {
+                let oldContent = null;
+                try {
+                    oldContent = await fs.readFile(absPath, "utf-8");
+                }
+                catch {
+                    // New file
+                }
+                await fs.mkdir(path.dirname(absPath), { recursive: true });
+                await fs.writeFile(absPath, content);
+                // Compute and stream diff for display
+                const diff = computeDiff(oldContent, content);
+                if (onChunk && diff.hunks.length > 0) {
+                    for (const hunk of diff.hunks) {
+                        for (const line of hunk.lines) {
+                            if (line.type === "added")
+                                onChunk(`+${line.text}\n`);
+                            else if (line.type === "removed")
+                                onChunk(`-${line.text}\n`);
+                            else
+                                onChunk(` ${line.text}\n`);
+                        }
+                    }
+                }
+                const stats = diff.isNewFile
+                    ? `+${diff.added}`
+                    : `+${diff.added} -${diff.removed}`;
+                return {
+                    content: oldContent === null
+                        ? `Created ${absPath} (${stats})`
+                        : `Wrote ${absPath} (${stats})`,
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { content: `Error: ${msg}`, exitCode: 1, isError: true };
+            }
+        },
+    };
+}

package/dist/agent/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimal agent backend interface — bus-driven.
+ *
+ * Backends self-wire to bus events in their constructor:
+ *   - agent:submit → handle queries
+ *   - agent:cancel-request → handle cancellation
+ *   - config:cycle → handle mode switching
+ *
+ * They emit bus events for results:
+ *   - agent:response-chunk, agent:tool-started, agent:tool-completed, etc.
+ *
+ * The only imperative method is kill() for lifecycle cleanup.
+ */
+export interface AgentBackend {
+    /** Async startup (e.g. spawn subprocess). No-op if not needed. */
+    start?(): Promise<void>;
+    kill(): void;
+}
+export interface ToolResult {
+    content: string;
+    exitCode: number | null;
+    isError: boolean;
+}
+/** Structured result display — returned by formatResult or computed by defaults. */
+export interface ToolResultDisplay {
+    /** One-line summary shown next to ✓/✗ (e.g. "42 papers found", "+3/-1"). */
+    summary?: string;
+    /** Structured content to render below the status line. */
+    body?: ToolResultBody;
+}
+export type ToolResultBody = {
+    kind: "diff";
+    diff: unknown;
+    filePath: string;
+} | {
+    kind: "lines";
+    lines: string[];
+    maxLines?: number;
+};
+export interface ToolDisplayInfo {
+    kind: "read" | "write" | "execute" | "search" | "display";
+    locations?: {
+        path: string;
+        line?: number | null;
+    }[];
+    /** Custom icon character for TUI display (e.g., "◆", "⌕"). When set, the TUI shows
+     *  icon + detail only. When absent, the tool name is shown alongside the detail. */
+    icon?: string;
+}
+export interface ToolDefinition {
+    name: string;
+    /** Short label for TUI display (e.g. "search" instead of "ads_search"). Defaults to name. */
+    displayName?: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    execute(args: Record<string, unknown>, onChunk?: (chunk: string) => void): Promise<ToolResult>;
+    /** Whether to stream tool output to the TUI (default: true). */
+    showOutput?: boolean;
+    /** Whether this tool may modify files — triggers file watcher (default: false). */
+    modifiesFiles?: boolean;
+    /** Whether to gate execution via permission:request (default: false). */
+    requiresPermission?: boolean;
+    /** Derive display metadata (icon kind, file paths) for the TUI. */
+    getDisplayInfo?: (args: Record<string, unknown>) => ToolDisplayInfo;
+    /**
+     * Format a short display string for the TUI when this tool is called.
+     * Return a concise summary of the args (e.g. the query, the file path).
+     * When absent, the TUI derives the detail from common arg fields (command, path, pattern).
+     */
+    formatCall?: (args: Record<string, unknown>) => string;
+    /**
+     * Format result display for the TUI after execution completes.
+     * Return a summary string and/or structured body to render.
+     * When absent, defaults are computed based on tool kind.
+     * Extensions can further override via bus.onPipe("agent:tool-completed", ...).
+     */
+    formatResult?: (args: Record<string, unknown>, result: ToolResult) => ToolResultDisplay;
+}

package/dist/agent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core.d.ts

@@ -1,41 +1,49 @@
 /**
  * Core kernel — the minimum viable agent-sh.
  *
- * Wires up EventBus + ContextManager + AcpClient without any frontend.
+ * Wires up EventBus + ContextManager + AgentBackend without any frontend.
  * Consumers attach their own I/O (Shell, WebSocket, REST, tests) by
- * subscribing to bus events and calling client methods.
+ * subscribing to bus events.
  *
- * The core listens for `agent:submit` and `agent:cancel-request` events
- * from any frontend, routing them to the AcpClient. This means frontends
- * never need a direct reference to AcpClient — they just emit events.
+ * The default backend (AgentLoop) is created eagerly but wired lazily —
+ * extensions can register alternative backends via agent:register-backend
+ * before activateBackend() is called.
  *
  * Usage:
  *   import { createCore } from "agent-sh";
- *   const core = createCore({ agentCommand: "pi-acp" });
- *   core.bus.on("agent:response-chunk", ({ text }) => ws.send(text));
- *   await core.start();
- *   core.bus.emit("agent:submit", { query: "hello" });
+ *   const core = createCore({ apiKey: "...", model: "gpt-4o" });
+ *   core.bus.on("agent:response-chunk", ({ blocks }) => { ... });
+ *   core.activateBackend();
+ *   const response = await core.query("hello");
  */
 import { EventBus } from "./event-bus.js";
 import { ContextManager } from "./context-manager.js";
-import { AcpClient } from "./acp-client.js";
+import { LlmClient } from "./utils/llm-client.js";
 import type { AgentShellConfig, ExtensionContext } from "./types.js";
 export { EventBus } from "./event-bus.js";
 export type { ShellEvents } from "./event-bus.js";
 export type { AgentShellConfig, ExtensionContext } from "./types.js";
 export { palette, setPalette, resetPalette } from "./utils/palette.js";
 export type { ColorPalette } from "./utils/palette.js";
+export type { AgentBackend, ToolDefinition } from "./agent/types.js";
+export { runSubagent, type SubagentOptions } from "./agent/subagent.js";
+export { LlmClient } from "./utils/llm-client.js";
 export interface AgentShellCore {
     bus: EventBus;
     contextManager: ContextManager;
-    client: AcpClient;
-    /** Connect to the agent subprocess. Call after wiring up bus listeners. */
-    start(): Promise<void>;
+    /** LLM client for fast-path features (null when no provider configured). */
+    llmClient: LlmClient | null;
+    /** Activate the agent backend (call after extensions load). */
+    activateBackend(): void;
+    /** Convenience: emit agent:submit and await the response. */
+    query(text: string): Promise<string>;
+    /** Convenience: emit agent:cancel-request. */
+    cancel(): void;
     /** Build an ExtensionContext for loading extensions against this core. */
     extensionContext(opts: {
         quit: () => void;
     }): ExtensionContext;
-    /** Tear down the agent process and clean up. */
+    /** Tear down the agent and clean up. */
     kill(): void;
 }
 export declare function createCore(config: AgentShellConfig): AgentShellCore;