agent-sh 0.3.1 → 0.5.0

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

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

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

@@ -0,0 +1,95 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { computeDiff } from "../../utils/diff.js";
+export function createEditFileTool(getCwd) {
+    return {
+        name: "edit_file",
+        description: "Edit a file by replacing an exact text match with new text. The old_text must appear exactly once in the file. Include enough context to make the match unique.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Absolute or relative file path",
+                },
+                old_text: {
+                    type: "string",
+                    description: "Exact text to find (must appear exactly once)",
+                },
+                new_text: {
+                    type: "string",
+                    description: "Replacement text",
+                },
+            },
+            required: ["path", "old_text", "new_text"],
+        },
+        showOutput: true,
+        modifiesFiles: true,
+        requiresPermission: true,
+        getDisplayInfo: (args) => ({
+            kind: "write",
+            locations: [{ path: args.path }],
+        }),
+        async execute(args, onChunk) {
+            const filePath = args.path;
+            const oldText = args.old_text;
+            const newText = args.new_text;
+            const absPath = path.resolve(getCwd(), filePath);
+            try {
+                const content = await fs.readFile(absPath, "utf-8");
+                // Normalize line endings for matching
+                const normalized = content.replace(/\r\n/g, "\n");
+                const normalizedOld = oldText.replace(/\r\n/g, "\n");
+                const occurrences = normalized.split(normalizedOld).length - 1;
+                if (occurrences === 0) {
+                    return {
+                        content: `Error: old_text not found in ${filePath}`,
+                        exitCode: 1,
+                        isError: true,
+                    };
+                }
+                if (occurrences > 1) {
+                    return {
+                        content: `Error: old_text found ${occurrences} times, must be unique. Add more surrounding context.`,
+                        exitCode: 1,
+                        isError: true,
+                    };
+                }
+                const normalizedNew = newText.replace(/\r\n/g, "\n");
+                const newContent = normalized.replace(normalizedOld, normalizedNew);
+                // Restore original line endings
+                const useCRLF = content.includes("\r\n");
+                const finalContent = useCRLF
+                    ? newContent.replace(/\n/g, "\r\n")
+                    : newContent;
+                await fs.writeFile(absPath, finalContent);
+                // Compute and stream diff for display
+                const diff = computeDiff(normalized, newContent);
+                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: `Edited ${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/tools/glob.d.ts

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

package/dist/agent/tools/glob.js

@@ -0,0 +1,55 @@
+import { executeCommand } from "../../executor.js";
+export function createGlobTool(getCwd) {
+    return {
+        name: "glob",
+        description: "Find files matching a glob pattern. Returns file paths sorted by modification time.",
+        input_schema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Glob pattern (e.g., 'src/**/*.ts', '*.json')",
+                },
+                path: {
+                    type: "string",
+                    description: "Base directory to search (default: cwd)",
+                },
+            },
+            required: ["pattern"],
+        },
+        showOutput: false,
+        getDisplayInfo: (args) => ({
+            kind: "search",
+            locations: args.path
+                ? [{ path: args.path }]
+                : [],
+        }),
+        async execute(args) {
+            const pattern = args.pattern;
+            const searchPath = args.path ?? ".";
+            // Use find + shell glob via bash, or rg --files --glob
+            const { session, done } = executeCommand({
+                command: `find ${JSON.stringify(searchPath)} -path ${JSON.stringify(pattern)} -type f 2>/dev/null | head -200`,
+                cwd: getCwd(),
+                timeout: 10_000,
+            });
+            await done;
+            if (!session.output.trim()) {
+                return {
+                    content: "No files matched.",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            const lines = session.output.trim().split("\n");
+            const suffix = lines.length >= 200
+                ? `\n[Results capped at 200 files]`
+                : "";
+            return {
+                content: session.output.trim() + suffix,
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

package/dist/agent/tools/grep.d.ts

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

package/dist/agent/tools/grep.js

@@ -0,0 +1,77 @@
+import { executeCommand } from "../../executor.js";
+export function createGrepTool(getCwd) {
+    return {
+        name: "grep",
+        description: "Search file contents using ripgrep (rg). Returns matching lines with file paths and line numbers.",
+        input_schema: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Regex pattern to search for",
+                },
+                path: {
+                    type: "string",
+                    description: "Directory or file to search (default: cwd)",
+                },
+                include: {
+                    type: "string",
+                    description: "Glob pattern for files to include (e.g., '*.ts')",
+                },
+            },
+            required: ["pattern"],
+        },
+        showOutput: false,
+        getDisplayInfo: (args) => ({
+            kind: "search",
+            locations: args.path
+                ? [{ path: args.path }]
+                : [],
+        }),
+        async execute(args) {
+            const pattern = args.pattern;
+            const searchPath = args.path ?? ".";
+            const include = args.include;
+            const parts = [
+                "rg",
+                "--line-number",
+                "--no-heading",
+                "--color=never",
+                "--max-count=200",
+            ];
+            if (include) {
+                parts.push("--glob", JSON.stringify(include));
+            }
+            parts.push(JSON.stringify(pattern), JSON.stringify(searchPath));
+            const { session, done } = executeCommand({
+                command: parts.join(" "),
+                cwd: getCwd(),
+                timeout: 10_000,
+                maxOutputBytes: 64 * 1024,
+            });
+            await done;
+            if (session.exitCode === 1 && !session.output.trim()) {
+                return {
+                    content: "No matches found.",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            // Truncate to ~100 lines
+            const lines = session.output.split("\n");
+            if (lines.length > 100) {
+                return {
+                    content: lines.slice(0, 100).join("\n") +
+                        `\n[${lines.length - 100} more lines truncated]`,
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            return {
+                content: session.output || "No matches found.",
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

package/dist/agent/tools/list-skills.d.ts

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

package/dist/agent/tools/list-skills.js

@@ -0,0 +1,28 @@
+import { discoverSkills } from "../skills.js";
+export function createListSkillsTool(getCwd) {
+    return {
+        name: "list_skills",
+        description: "List available skills. Use read_file on a skill's path to load its full instructions.",
+        input_schema: {
+            type: "object",
+            properties: {},
+        },
+        showOutput: false,
+        async execute() {
+            const skills = discoverSkills(getCwd());
+            if (skills.length === 0) {
+                return {
+                    content: "No skills found.",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            const lines = skills.map((s) => `${s.name}  ${s.filePath}\n  ${s.description}`);
+            return {
+                content: lines.join("\n\n"),
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

package/dist/agent/tools/ls.d.ts

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

package/dist/agent/tools/ls.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export function createLsTool(getCwd) {
+    return {
+        name: "ls",
+        description: "List files and directories in a given path.",
+        input_schema: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Directory to list (default: cwd)",
+                },
+            },
+        },
+        showOutput: false,
+        getDisplayInfo: (args) => ({
+            kind: "read",
+            locations: args.path
+                ? [{ path: args.path }]
+                : [],
+        }),
+        async execute(args) {
+            const dirPath = args.path ?? ".";
+            const absPath = path.resolve(getCwd(), dirPath);
+            try {
+                const entries = await fs.readdir(absPath, {
+                    withFileTypes: true,
+                });
+                const lines = entries.map((e) => 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,2 @@
+import type { ToolDefinition } from "../types.js";
+export declare function createReadFileTool(getCwd: () => string): ToolDefinition;

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

@@ -0,0 +1,55 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+export function createReadFileTool(getCwd) {
+    return {
+        name: "read_file",
+        description: "Read a file's contents with line numbers. Optionally specify offset and limit for large files.",
+        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",
+            locations: [{ path: args.path }],
+        }),
+        async execute(args) {
+            const filePath = args.path;
+            const absPath = path.resolve(getCwd(), filePath);
+            try {
+                const content = await fs.readFile(absPath, "utf-8");
+                const lines = content.split("\n");
+                const start = (args.offset ?? 1) - 1; // 1-indexed → 0-indexed
+                const end = args.limit ? start + args.limit : 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]`
+                    : "";
+                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,57 @@
+/**
+ * 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 in the user's live shell (visible in terminal). Output is returned to you by default. Use for cd, export, source, or commands the user wants to see. Set return_output=false for long-running or interactive commands.",
+        input_schema: {
+            type: "object",
+            properties: {
+                command: {
+                    type: "string",
+                    description: "Command to execute in user's shell",
+                },
+                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",
+            locations: [],
+        }),
+        async execute(args) {
+            const command = args.command;
+            const returnOutput = args.return_output ?? false;
+            // Execute via the shell-exec extension's async pipe
+            const result = await opts.bus.emitPipeAsync("shell:exec-request", {
+                command,
+                output: "",
+                cwd: opts.getCwd(),
+                done: false,
+            });
+            if (returnOutput) {
+                return {
+                    content: result.output || "(no output)",
+                    exitCode: 0,
+                    isError: false,
+                };
+            }
+            return {
+                content: "Command executed.",
+                exitCode: 0,
+                isError: false,
+            };
+        },
+    };
+}

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,74 @@
+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 or overwrite a file with the given content. Creates parent directories if needed. Prefer edit_file for modifying existing files.",
+        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",
+            locations: [{ path: args.path }],
+        }),
+        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,44 @@
+/**
+ * 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;
+}
+export interface ToolDisplayInfo {
+    kind: "read" | "write" | "execute" | "search";
+    locations?: {
+        path: string;
+        line?: number | null;
+    }[];
+}
+export interface ToolDefinition {
+    name: 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;
+}

package/dist/agent/types.js

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

package/dist/core.d.ts

@@ -1,41 +1,51 @@
 /**
  * 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, opts?: {
+        mode?: 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;