agent-sh 0.15.0 → 0.15.2

package/src/agent/tools/list-skills.ts

@@ -0,0 +1,37 @@
+import type { ToolDefinition } from "../types.js";
+import { discoverSkills } from "../skills.js";
+
+export function createListSkillsTool(getCwd: () => string): ToolDefinition {
+  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/src/agent/tools/ls.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { contentText, type ToolDefinition } from "../types.js";
+import { expandHome } from "./expand-home.js";
+
+function formatSize(bytes: number): string {
+  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: () => string): ToolDefinition {
+  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 as string }]
+        : [],
+    }),
+
+    formatResult: (_args, result) => {
+      const text = contentText(result.content);
+      if (result.isError || text === "(empty directory)") return { summary: "0 entries" };
+      const lines = text.split("\n").filter(Boolean);
+      return { summary: `${lines.length} entries` };
+    },
+
+    async execute(args) {
+      const dirPath = expandHome((args.path as string) ?? ".");
+      const absPath = path.resolve(getCwd(), dirPath);
+
+      try {
+        const entries = await fs.readdir(absPath, {
+          withFileTypes: true,
+        });
+
+        const items = await Promise.all(
+          entries.map(async (e) => {
+            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", " ");
+              return `${mtime}  ${size.padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`;
+            } catch {
+              return `${"?".padStart(16)}  ${"?".padStart(8)}  ${e.isDirectory() ? e.name + "/" : e.name}`;
+            }
+          }),
+        );
+
+        return {
+          content: items.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/src/agent/tools/pwsh.ts

@@ -0,0 +1,140 @@
+import { spawnSync } from "node:child_process";
+import { executeArgv, killSession } from "../../utils/executor.js";
+import type { EventBus } from "../../core/event-bus.js";
+import type { ToolDefinition } from "../types.js";
+
+let cachedPwshPath: string | null | undefined;
+
+/** Resolve a usable PowerShell binary, or null if none is on PATH.
+ *  Prefers PowerShell 7+ (`pwsh`), falls back to Windows PowerShell (`powershell`). */
+function findPwsh(): string | null {
+  if (cachedPwshPath !== undefined) return cachedPwshPath;
+
+  // Prefer PowerShell 7 (pwsh)
+  const pwsh = spawnSync("where", ["pwsh"], { encoding: "utf-8" });
+  if (pwsh.status === 0) {
+    cachedPwshPath = pwsh.stdout.split(/\r?\n/)[0]!.trim() || null;
+    if (cachedPwshPath) return cachedPwshPath;
+  }
+
+  // Fallback to Windows PowerShell (powershell.exe)
+  const ps = spawnSync("where", ["powershell"], { encoding: "utf-8" });
+  cachedPwshPath = ps.status === 0 ? ps.stdout.split(/\r?\n/)[0]!.trim() || null : null;
+  return cachedPwshPath;
+}
+
+/** Return the PowerShell executable name for display purposes. */
+function getPwshDisplayName(): string {
+  const path = findPwsh();
+  if (!path) return "PowerShell";
+  return path.toLowerCase().includes("pwsh") ? "pwsh" : "powershell";
+}
+
+export function createPwshTool(opts: {
+  getCwd: () => string;
+  getEnv: () => Record<string, string>;
+  bus: EventBus;
+}): ToolDefinition {
+  return {
+    name: "pwsh",
+    description:
+      "Execute a PowerShell command in an isolated subprocess. " +
+      "Use this on Windows when the `bash` tool fails (no /bin/bash available). " +
+      "Use PowerShell syntax — e.g. `Get-ChildItem`, `Select-String`, `$env:HOME`. " +
+      "Does not affect the user's shell state. " +
+      "cwd is set to the working directory from the shell context. " +
+      "Do NOT use pwsh for file searching — use grep/glob instead. " +
+      "Do NOT use pwsh for reading files — use read_file instead.",
+    input_schema: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: "The PowerShell command to execute",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in seconds (default: 60)",
+        },
+        description: {
+          type: "string",
+          description:
+            "Short description of what this command does (e.g., 'Install dependencies', 'Run test suite')",
+        },
+      },
+      required: ["command"],
+    },
+
+    showOutput: true,
+    modifiesFiles: true,
+
+    getDisplayInfo: () => ({
+      kind: "execute",
+      icon: "▶",
+      locations: [],
+    }),
+
+    async execute(args, onChunk, ctx) {
+      const command = args.command as string;
+      const timeout = ((args.timeout as number) ?? 60) * 1000;
+
+      const intercepted = opts.bus.emitPipe("agent:terminal-intercept", {
+        command,
+        cwd: opts.getCwd(),
+        intercepted: false,
+        output: "",
+      });
+      if (intercepted.intercepted) {
+        return {
+          content: intercepted.output,
+          exitCode: 0,
+          isError: false,
+        };
+      }
+
+      const pwshPath = findPwsh();
+      if (!pwshPath) {
+        return {
+          content: "PowerShell not found on PATH. Neither pwsh (PowerShell 7+) nor powershell (Windows PowerShell) is available.",
+          exitCode: 1,
+          isError: true,
+        };
+      }
+
+      const { session, done } = executeArgv({
+        file: pwshPath,
+        args: ["-NoProfile", "-NonInteractive", "-Command", command],
+        cwd: opts.getCwd(),
+        env: opts.getEnv(),
+        timeout,
+        onOutput: onChunk,
+      });
+
+      const onAbort = () => killSession(session);
+      ctx?.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        await done;
+      } finally {
+        ctx?.signal?.removeEventListener("abort", onAbort);
+      }
+
+      if (session.spawnFailed) {
+        return {
+          content: `${getPwshDisplayName()} not found on PATH. Install PowerShell 7: winget install Microsoft.PowerShell.`,
+          exitCode: 1,
+          isError: true,
+        };
+      }
+
+      const content = session.truncated
+        ? `[output truncated, showing last portion]\n${session.output}`
+        : session.output;
+
+      return {
+        content: content || "(no output)",
+        exitCode: session.exitCode,
+        isError: session.exitCode !== 0,
+      };
+    },
+  };
+}

package/src/agent/tools/read-file.ts

@@ -0,0 +1,164 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { contentText, type ImageContent, type ToolDefinition } from "../types.js";
+import { expandHome } from "./expand-home.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>;
+
+const IMAGE_MIME_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+export function createReadFileTool(
+  getCwd: () => string,
+  cache?: FileReadCache,
+): ToolDefinition {
+  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 as string }],
+    }),
+
+    formatResult: (_args, result) => {
+      const text = contentText(result.content);
+      if (result.isError) return {};
+      if (text.startsWith("File unchanged")) return { summary: "cached" };
+      const lines = text.split("\n").filter(l => !l.startsWith("["));
+      return { summary: `${lines.length} lines` };
+    },
+
+    async execute(args) {
+      const filePath = expandHome(args.path as string);
+      const absPath = path.resolve(getCwd(), filePath);
+      const reqOffset = (args.offset as number) ?? 1;
+      const reqLimit = args.limit as number | undefined;
+
+      try {
+        const stat = await fs.stat(absPath);
+
+        // Deduplication: if the file hasn't changed and same range, return stub.
+        // bypass_cache lets in-process callers consume content as a value
+        // rather than a tool_result, where the dedup stub would be meaningless.
+        if (cache && !args.bypass_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 ext = path.extname(absPath).toLowerCase();
+        const mimeType = IMAGE_MIME_TYPES[ext];
+        if (mimeType) {
+          const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5MB — base64 adds ~33%
+          if (stat.size > MAX_IMAGE_BYTES) {
+            return {
+              content: `Image is ${(stat.size / (1024 * 1024)).toFixed(1)}MB — too large. Images are capped at 5MB.`,
+              exitCode: 1,
+              isError: true,
+            };
+          }
+          const buf = await fs.readFile(absPath);
+          const data = buf.toString("base64");
+          return {
+            content: [{ type: "image", data, mimeType }],
+            exitCode: 0,
+            isError: false,
+          };
+        }
+
+        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]`
+          : "";
+
+        // Skip cache write for in-process callers — they shouldn't poison
+        // the LLM-facing dedup state.
+        if (cache && !args.bypass_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/src/agent/tools/write-file.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ToolDefinition } from "../types.js";
+import { computeDiff } from "../../utils/diff.js";
+import { expandHome } from "./expand-home.js";
+
+export function createWriteFileTool(getCwd: () => string): ToolDefinition {
+  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,
+
+    getDisplayInfo: (args) => ({
+      kind: "write",
+      icon: "✎",
+      locations: [{ path: args.path as string }],
+    }),
+
+    async execute(args) {
+      const filePath = expandHome(args.path as string);
+      const content = args.content as string;
+      const absPath = path.resolve(getCwd(), filePath);
+
+      try {
+        let oldContent: string | null = 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);
+
+        const diff = computeDiff(oldContent, content);
+        const stats = diff.isNewFile ? `+${diff.added}` : `+${diff.added} -${diff.removed}`;
+        return {
+          content: oldContent === null
+            ? `Created ${absPath} (${stats})`
+            : `Wrote ${absPath} (${stats})`,
+          exitCode: 0,
+          isError: false,
+          display: {
+            summary: stats,
+            body: { kind: "diff", diff, filePath: absPath },
+          },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: `Error: ${msg}`, exitCode: 1, isError: true };
+      }
+    },
+  };
+}

package/src/agent/types.ts

@@ -0,0 +1,149 @@
+import type { EventBus } from "../core/event-bus.js";
+
+/**
+ * Minimal agent backend interface — bus-driven.
+ *
+ * Backends self-wire to bus events in their constructor:
+ *   - agent:submit → handle queries
+ *   - agent:cancel-request → handle cancellation
+ *
+ * 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;
+}
+
+/** Image content block for multimodal tool results. */
+export interface ImageContent {
+  type: "image";
+  /** Base64-encoded image data (no data: URL prefix). */
+  data: string;
+  /** MIME type (e.g. "image/png", "image/jpeg"). */
+  mimeType: string;
+}
+
+/** Extract the text portion of a tool result's content. Returns "" for image-only results. */
+export function contentText(content: string | ImageContent[]): string {
+  if (typeof content === "string") return content;
+  return content.map(c => `[image: ${c.mimeType}]`).join("\n");
+}
+
+export interface ToolResult {
+  content: string | ImageContent[];
+  exitCode: number | null;
+  isError: boolean;
+  /** When set, takes precedence over `tool.formatResult()`. */
+  display?: ToolResultDisplay;
+}
+
+/** 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";
+  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;
+  /** highlight.js-style language identifier ("scheme", "python", …) for
+   *  renderers that syntax-highlight tool source. Omit for plain text. */
+  sourceLanguage?: string;
+}
+
+/** Interactive UI session — imperative control over rendering + input. */
+export interface InteractiveSession<T> {
+  /** Return lines to render. Called on mount and after each input. */
+  render(width: number): string[];
+  /** Handle raw input. Call done(result) to finish the session. */
+  handleInput(data: string, done: (result: T) => void): void;
+  /** done() lets the session resolve itself from outside handleInput. */
+  onMount?(invalidate: () => void, done: (result: T) => void): void;
+  /** Called when session ends (cleanup). */
+  onUnmount?(): void;
+}
+
+/** Interactive UI capability passed to tools during execution. */
+export interface ToolUI {
+  /** Present a custom interactive UI and wait for the user's response. */
+  custom<T>(session: InteractiveSession<T>): Promise<T>;
+}
+
+/** Context passed to tool execute() as optional third parameter. */
+export interface ToolExecutionContext {
+  ui?: ToolUI;
+  /** Aborted on Ctrl-C — tools with subprocess work should listen and clean up. */
+  signal?: AbortSignal;
+}
+
+/** LLM-facing view of a tool — what `adviseToolSchema` advisors return. */
+export interface ToolSchemaView {
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+/** LLM-facing view of a skill — what `adviseSkill` advisors return. */
+export interface SkillView {
+  description: string;
+  filePath: 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,
+    ctx?: ToolExecutionContext,
+  ): 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;
+
+  /** Results are re-fetchable; nuclear compaction drops the tool_result
+   *  body on eviction (like the builtin read_file/grep/ls). Default: false. */
+  readOnly?: 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;
+
+  /** Override the agent-loop's per-tool-result truncation cap (default 16 KB).
+   *  Use for tools that bundle multiple operations and legitimately produce
+   *  larger output (interpreter substrates etc.). */
+  maxResultBytes?: number;
+}