micode 0.7.0 → 0.7.2

package/src/tools/pty/manager.ts

@@ -0,0 +1,159 @@
+// src/tools/pty/manager.ts
+import { spawn, type IPty } from "bun-pty";
+import { RingBuffer } from "./buffer";
+import type { PTYSession, PTYSessionInfo, SpawnOptions, ReadResult, SearchResult } from "./types";
+
+function generateId(): string {
+  const hex = Array.from(crypto.getRandomValues(new Uint8Array(4)))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `pty_${hex}`;
+}
+
+export class PTYManager {
+  private sessions: Map<string, PTYSession> = new Map();
+
+  spawn(opts: SpawnOptions): PTYSessionInfo {
+    const id = generateId();
+    const args = opts.args ?? [];
+    const workdir = opts.workdir ?? process.cwd();
+    const env = { ...process.env, ...opts.env } as Record<string, string>;
+    const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
+
+    const ptyProcess: IPty = spawn(opts.command, args, {
+      name: "xterm-256color",
+      cols: 120,
+      rows: 40,
+      cwd: workdir,
+      env,
+    });
+
+    const buffer = new RingBuffer();
+    const session: PTYSession = {
+      id,
+      title,
+      command: opts.command,
+      args,
+      workdir,
+      env: opts.env,
+      status: "running",
+      pid: ptyProcess.pid,
+      createdAt: new Date(),
+      parentSessionId: opts.parentSessionId,
+      buffer,
+      process: ptyProcess,
+    };
+
+    this.sessions.set(id, session);
+
+    ptyProcess.onData((data: string) => {
+      buffer.append(data);
+    });
+
+    ptyProcess.onExit(({ exitCode }: { exitCode: number }) => {
+      if (session.status === "running") {
+        session.status = "exited";
+        session.exitCode = exitCode;
+      }
+    });
+
+    return this.toInfo(session);
+  }
+
+  write(id: string, data: string): boolean {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status !== "running") {
+      return false;
+    }
+    session.process.write(data);
+    return true;
+  }
+
+  read(id: string, offset: number = 0, limit?: number): ReadResult | null {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const lines = session.buffer.read(offset, limit);
+    const totalLines = session.buffer.length;
+    const hasMore = offset + lines.length < totalLines;
+    return { lines, totalLines, offset, hasMore };
+  }
+
+  search(id: string, pattern: RegExp, offset: number = 0, limit?: number): SearchResult | null {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const allMatches = session.buffer.search(pattern);
+    const totalMatches = allMatches.length;
+    const totalLines = session.buffer.length;
+    const paginatedMatches = limit !== undefined ? allMatches.slice(offset, offset + limit) : allMatches.slice(offset);
+    const hasMore = offset + paginatedMatches.length < totalMatches;
+    return { matches: paginatedMatches, totalMatches, totalLines, offset, hasMore };
+  }
+
+  list(): PTYSessionInfo[] {
+    return Array.from(this.sessions.values()).map((s) => this.toInfo(s));
+  }
+
+  get(id: string): PTYSessionInfo | null {
+    const session = this.sessions.get(id);
+    return session ? this.toInfo(session) : null;
+  }
+
+  kill(id: string, cleanup: boolean = false): boolean {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+
+    if (session.status === "running") {
+      try {
+        session.process.kill();
+      } catch {
+        // Process may already be dead
+      }
+      session.status = "killed";
+    }
+
+    if (cleanup) {
+      session.buffer.clear();
+      this.sessions.delete(id);
+    }
+
+    return true;
+  }
+
+  cleanupBySession(parentSessionId: string): void {
+    for (const [id, session] of this.sessions) {
+      if (session.parentSessionId === parentSessionId) {
+        this.kill(id, true);
+      }
+    }
+  }
+
+  cleanupAll(): void {
+    for (const id of this.sessions.keys()) {
+      this.kill(id, true);
+    }
+  }
+
+  private toInfo(session: PTYSession): PTYSessionInfo {
+    return {
+      id: session.id,
+      title: session.title,
+      command: session.command,
+      args: session.args,
+      workdir: session.workdir,
+      status: session.status,
+      exitCode: session.exitCode,
+      pid: session.pid,
+      createdAt: session.createdAt,
+      lineCount: session.buffer.length,
+    };
+  }
+}

package/src/tools/pty/tools/kill.ts

@@ -0,0 +1,68 @@
+// src/tools/pty/tools/kill.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Terminates a PTY session and optionally cleans up its buffer.
+
+Use this tool to:
+- Stop a running process (sends SIGTERM)
+- Clean up an exited session to free memory
+- Remove a session from the list
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`cleanup\`: If true, removes the session and frees the buffer (default: false)
+
+Behavior:
+- If the session is running, it will be killed (status becomes "killed")
+- If cleanup=false (default), the session remains in the list with its output buffer intact
+- If cleanup=true, the session is removed entirely and the buffer is freed
+- Keeping sessions without cleanup allows you to compare logs between runs
+
+Tips:
+- Use cleanup=false if you might want to read the output later
+- Use cleanup=true when you're done with the session entirely
+- To send Ctrl+C instead of killing, use pty_write with data="\\x03"
+
+Examples:
+- Kill but keep logs: cleanup=false (or omit)
+- Kill and remove: cleanup=true`;
+
+export function createPtyKillTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      cleanup: tool.schema
+        .boolean()
+        .optional()
+        .describe("If true, removes the session and frees the buffer (default: false)"),
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+
+      const wasRunning = session.status === "running";
+      const cleanup = args.cleanup ?? false;
+      const success = manager.kill(args.id, cleanup);
+
+      if (!success) {
+        throw new Error(`Failed to kill PTY session '${args.id}'.`);
+      }
+
+      const action = wasRunning ? "Killed" : "Cleaned up";
+      const cleanupNote = cleanup ? " (session removed)" : " (session retained for log access)";
+
+      return [
+        `<pty_killed>`,
+        `${action}: ${args.id}${cleanupNote}`,
+        `Title: ${session.title}`,
+        `Command: ${session.command} ${session.args.join(" ")}`,
+        `Final line count: ${session.lineCount}`,
+        `</pty_killed>`,
+      ].join("\n");
+    },
+  });
+}

package/src/tools/pty/tools/list.ts

@@ -0,0 +1,55 @@
+// src/tools/pty/tools/list.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Lists all PTY sessions (active and exited).
+
+Use this tool to:
+- See all running and exited PTY sessions
+- Get session IDs for use with other pty_* tools
+- Check the status and output line count of each session
+- Monitor which processes are still running
+
+Returns for each session:
+- \`id\`: Unique identifier for use with other tools
+- \`title\`: Human-readable name
+- \`command\`: The command that was executed
+- \`status\`: Current status (running, exited, killed)
+- \`exitCode\`: Exit code (if exited/killed)
+- \`pid\`: Process ID
+- \`lineCount\`: Number of lines in the output buffer
+- \`createdAt\`: When the session was created
+
+Tips:
+- Use the session ID with pty_read, pty_write, or pty_kill
+- Sessions remain in the list after exit until explicitly cleaned up with pty_kill
+- This allows you to compare output from multiple sessions`;
+
+export function createPtyListTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {},
+    execute: async () => {
+      const sessions = manager.list();
+
+      if (sessions.length === 0) {
+        return "<pty_list>\nNo active PTY sessions.\n</pty_list>";
+      }
+
+      const lines = ["<pty_list>"];
+      for (const session of sessions) {
+        const exitInfo = session.exitCode !== undefined ? ` (exit: ${session.exitCode})` : "";
+        lines.push(`[${session.id}] ${session.title}`);
+        lines.push(`  Command: ${session.command} ${session.args.join(" ")}`);
+        lines.push(`  Status: ${session.status}${exitInfo}`);
+        lines.push(`  PID: ${session.pid} | Lines: ${session.lineCount} | Workdir: ${session.workdir}`);
+        lines.push(`  Created: ${session.createdAt.toISOString()}`);
+        lines.push("");
+      }
+      lines.push(`Total: ${sessions.length} session(s)`);
+      lines.push("</pty_list>");
+
+      return lines.join("\n");
+    },
+  });
+}

package/src/tools/pty/tools/read.ts

@@ -0,0 +1,152 @@
+// src/tools/pty/tools/read.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Reads output from a PTY session's buffer.
+
+The PTY maintains a rolling buffer of output lines. Use offset and limit to paginate through the output, similar to reading a file.
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`offset\`: Line number to start reading from (0-based, defaults to 0)
+- \`limit\`: Number of lines to read (defaults to 500)
+- \`pattern\`: Regex pattern to filter lines (optional)
+- \`ignoreCase\`: Case-insensitive pattern matching (default: false)
+
+Returns:
+- Numbered lines of output (similar to cat -n format)
+- Total line count in the buffer
+- Indicator if more lines are available
+
+The buffer stores up to PTY_MAX_BUFFER_LINES (default: 50000) lines. Older lines are discarded when the limit is reached.
+
+Pattern Filtering:
+- When \`pattern\` is set, lines are FILTERED FIRST using the regex, then offset/limit apply to the MATCHES
+- Original line numbers are preserved so you can see where matches occurred in the buffer
+- Supports full regex syntax (e.g., "error", "ERROR|WARN", "failed.*connection", etc.)
+- If the pattern is invalid, an error message is returned explaining the issue
+- If no lines match the pattern, a clear message indicates zero matches
+
+Tips:
+- To see the latest output, use a high offset or omit offset to read from the start
+- To tail recent output, calculate offset as (totalLines - N) where N is how many recent lines you want
+- Lines longer than 2000 characters are truncated
+- Empty output may mean the process hasn't produced output yet
+
+Examples:
+- Read first 100 lines: offset=0, limit=100
+- Read lines 500-600: offset=500, limit=100
+- Read all available: omit both parameters
+- Find errors: pattern="error", ignoreCase=true
+- Find specific log levels: pattern="ERROR|WARN|FATAL"
+- First 10 matches only: pattern="error", limit=10`;
+
+const DEFAULT_LIMIT = 500;
+const MAX_LINE_LENGTH = 2000;
+
+export function createPtyReadTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      offset: tool.schema.number().optional().describe("Line number to start reading from (0-based, defaults to 0)"),
+      limit: tool.schema.number().optional().describe("Number of lines to read (defaults to 500)"),
+      pattern: tool.schema.string().optional().describe("Regex pattern to filter lines"),
+      ignoreCase: tool.schema.boolean().optional().describe("Case-insensitive pattern matching (default: false)"),
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+
+      const offset = Math.max(0, args.offset ?? 0);
+      const limit = args.limit ?? DEFAULT_LIMIT;
+
+      if (args.pattern) {
+        let regex: RegExp;
+        try {
+          regex = new RegExp(args.pattern, args.ignoreCase ? "i" : "");
+        } catch (e) {
+          const error = e instanceof Error ? e.message : String(e);
+          throw new Error(`Invalid regex pattern '${args.pattern}': ${error}`);
+        }
+
+        const result = manager.search(args.id, regex, offset, limit);
+        if (!result) {
+          throw new Error(`PTY session '${args.id}' not found.`);
+        }
+
+        if (result.matches.length === 0) {
+          return [
+            `<pty_output id="${args.id}" status="${session.status}" pattern="${args.pattern}">`,
+            `No lines matched the pattern '${args.pattern}'.`,
+            `Total lines in buffer: ${result.totalLines}`,
+            `</pty_output>`,
+          ].join("\n");
+        }
+
+        const formattedLines = result.matches.map((match) => {
+          const lineNum = match.lineNumber.toString().padStart(5, "0");
+          const truncatedLine =
+            match.text.length > MAX_LINE_LENGTH ? `${match.text.slice(0, MAX_LINE_LENGTH)}...` : match.text;
+          return `${lineNum}| ${truncatedLine}`;
+        });
+
+        const output = [
+          `<pty_output id="${args.id}" status="${session.status}" pattern="${args.pattern}">`,
+          ...formattedLines,
+          "",
+        ];
+
+        if (result.hasMore) {
+          output.push(
+            `(${result.matches.length} of ${result.totalMatches} matches shown. Use offset=${offset + result.matches.length} to see more.)`,
+          );
+        } else {
+          output.push(
+            `(${result.totalMatches} match${result.totalMatches === 1 ? "" : "es"} from ${result.totalLines} total lines)`,
+          );
+        }
+        output.push(`</pty_output>`);
+
+        return output.join("\n");
+      }
+
+      const result = manager.read(args.id, offset, limit);
+      if (!result) {
+        throw new Error(`PTY session '${args.id}' not found.`);
+      }
+
+      if (result.lines.length === 0) {
+        return [
+          `<pty_output id="${args.id}" status="${session.status}">`,
+          `(No output available - buffer is empty)`,
+          `Total lines: ${result.totalLines}`,
+          `</pty_output>`,
+        ].join("\n");
+      }
+
+      const formattedLines = result.lines.map((line, index) => {
+        const lineNum = (result.offset + index + 1).toString().padStart(5, "0");
+        const truncatedLine = line.length > MAX_LINE_LENGTH ? `${line.slice(0, MAX_LINE_LENGTH)}...` : line;
+        return `${lineNum}| ${truncatedLine}`;
+      });
+
+      const output = [`<pty_output id="${args.id}" status="${session.status}">`, ...formattedLines];
+
+      if (result.hasMore) {
+        output.push("");
+        output.push(
+          `(Buffer has more lines. Use offset=${result.offset + result.lines.length} to read beyond line ${result.offset + result.lines.length})`,
+        );
+      } else {
+        output.push("");
+        output.push(`(End of buffer - total ${result.totalLines} lines)`);
+      }
+      output.push(`</pty_output>`);
+
+      return output.join("\n");
+    },
+  });
+}

package/src/tools/pty/tools/spawn.ts

@@ -0,0 +1,78 @@
+// src/tools/pty/tools/spawn.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Spawns a new interactive PTY (pseudo-terminal) session that runs in the background.
+
+Unlike the built-in bash tool which runs commands synchronously and waits for completion, PTY sessions persist and allow you to:
+- Run long-running processes (dev servers, watch modes, etc.)
+- Send interactive input (including Ctrl+C, arrow keys, etc.)
+- Read output at any time
+- Manage multiple concurrent terminal sessions
+
+Usage:
+- The \`command\` parameter is required (e.g., "npm", "python", "bash")
+- Use \`args\` to pass arguments to the command (e.g., ["run", "dev"])
+- Use \`workdir\` to set the working directory (defaults to project root)
+- Use \`env\` to set additional environment variables
+- Use \`title\` to give the session a human-readable name
+- Use \`description\` for a clear, concise 5-10 word description (optional)
+
+Returns the session info including:
+- \`id\`: Unique identifier (pty_XXXXXXXX) for use with other pty_* tools
+- \`pid\`: Process ID
+- \`status\`: Current status ("running")
+
+After spawning, use:
+- \`pty_write\` to send input to the PTY
+- \`pty_read\` to read output from the PTY
+- \`pty_list\` to see all active PTY sessions
+- \`pty_kill\` to terminate the PTY
+
+Examples:
+- Start a dev server: command="npm", args=["run", "dev"], title="Dev Server"
+- Start a Python REPL: command="python3", title="Python REPL"
+- Run tests in watch mode: command="npm", args=["test", "--", "--watch"]`;
+
+export function createPtySpawnTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      command: tool.schema.string().describe("The command/executable to run"),
+      args: tool.schema.array(tool.schema.string()).optional().describe("Arguments to pass to the command"),
+      workdir: tool.schema.string().optional().describe("Working directory for the PTY session"),
+      env: tool.schema
+        .record(tool.schema.string(), tool.schema.string())
+        .optional()
+        .describe("Additional environment variables"),
+      title: tool.schema.string().optional().describe("Human-readable title for the session"),
+      description: tool.schema
+        .string()
+        .optional()
+        .describe("Clear, concise description of what this PTY session is for in 5-10 words"),
+    },
+    execute: async (args, ctx) => {
+      const info = manager.spawn({
+        command: args.command,
+        args: args.args,
+        workdir: args.workdir,
+        env: args.env,
+        title: args.title,
+        parentSessionId: ctx.sessionID,
+      });
+
+      const output = [
+        `<pty_spawned>`,
+        `ID: ${info.id}`,
+        `Title: ${info.title}`,
+        `Command: ${info.command} ${info.args.join(" ")}`,
+        `Workdir: ${info.workdir}`,
+        `PID: ${info.pid}`,
+        `Status: ${info.status}`,
+        `</pty_spawned>`,
+      ].join("\n");
+
+      return output;
+    },
+  });
+}

package/src/tools/pty/tools/write.ts

@@ -0,0 +1,97 @@
+// src/tools/pty/tools/write.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Sends input data to an active PTY session.
+
+Use this tool to:
+- Type commands or text into an interactive terminal
+- Send special key sequences (Ctrl+C, Enter, arrow keys, etc.)
+- Respond to prompts in interactive programs
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`data\`: The input to send (text, commands, or escape sequences)
+
+Common escape sequences:
+- Enter/newline: "\\n" or "\\r"
+- Ctrl+C (interrupt): "\\x03"
+- Ctrl+D (EOF): "\\x04"
+- Ctrl+Z (suspend): "\\x1a"
+- Tab: "\\t"
+- Arrow Up: "\\x1b[A"
+- Arrow Down: "\\x1b[B"
+- Arrow Right: "\\x1b[C"
+- Arrow Left: "\\x1b[D"
+
+Returns success or error message.
+
+Examples:
+- Send a command: data="ls -la\\n"
+- Interrupt a process: data="\\x03"
+- Answer a prompt: data="yes\\n"`;
+
+/**
+ * Parse escape sequences in a string to their actual byte values.
+ * Handles: \n, \r, \t, \xNN (hex), \uNNNN (unicode), \\
+ */
+function parseEscapeSequences(input: string): string {
+  return input.replace(/\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|[nrt0\\])/g, (match, seq: string) => {
+    if (seq.startsWith("x")) {
+      return String.fromCharCode(parseInt(seq.slice(1), 16));
+    }
+    if (seq.startsWith("u")) {
+      return String.fromCharCode(parseInt(seq.slice(1), 16));
+    }
+    switch (seq) {
+      case "n":
+        return "\n";
+      case "r":
+        return "\r";
+      case "t":
+        return "\t";
+      case "0":
+        return "\0";
+      case "\\":
+        return "\\";
+      default:
+        return match;
+    }
+  });
+}
+
+export function createPtyWriteTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      data: tool.schema.string().describe("The input data to send to the PTY"),
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+
+      if (session.status !== "running") {
+        throw new Error(`Cannot write to PTY '${args.id}' - session status is '${session.status}'.`);
+      }
+
+      // Parse escape sequences to actual bytes
+      const parsedData = parseEscapeSequences(args.data);
+
+      const success = manager.write(args.id, parsedData);
+      if (!success) {
+        throw new Error(`Failed to write to PTY '${args.id}'.`);
+      }
+
+      const preview = args.data.length > 50 ? `${args.data.slice(0, 50)}...` : args.data;
+      const displayPreview = preview
+        .replace(/\x03/g, "^C")
+        .replace(/\x04/g, "^D")
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r");
+      return `Sent ${parsedData.length} bytes to ${args.id}: "${displayPreview}"`;
+    },
+  });
+}

package/src/tools/pty/types.ts

@@ -0,0 +1,62 @@
+// src/tools/pty/types.ts
+import type { RingBuffer } from "./buffer";
+
+export type PTYStatus = "running" | "exited" | "killed";
+
+export interface PTYSession {
+  id: string;
+  title: string;
+  command: string;
+  args: string[];
+  workdir: string;
+  env?: Record<string, string>;
+  status: PTYStatus;
+  exitCode?: number;
+  pid: number;
+  createdAt: Date;
+  parentSessionId: string;
+  buffer: RingBuffer;
+  process: import("bun-pty").IPty;
+}
+
+export interface PTYSessionInfo {
+  id: string;
+  title: string;
+  command: string;
+  args: string[];
+  workdir: string;
+  status: PTYStatus;
+  exitCode?: number;
+  pid: number;
+  createdAt: Date;
+  lineCount: number;
+}
+
+export interface SpawnOptions {
+  command: string;
+  args?: string[];
+  workdir?: string;
+  env?: Record<string, string>;
+  title?: string;
+  parentSessionId: string;
+}
+
+export interface ReadResult {
+  lines: string[];
+  totalLines: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+export interface SearchMatch {
+  lineNumber: number;
+  text: string;
+}
+
+export interface SearchResult {
+  matches: SearchMatch[];
+  totalMatches: number;
+  totalLines: number;
+  offset: number;
+  hasMore: boolean;
+}