micode 0.6.0 → 0.7.0

package/dist/index.js

@@ -9,6 +9,7 @@ var __export = (target, all) => {
       set: (newValue) => all[name] = () => newValue
     });
 };
+var __require = import.meta.require;
 
 // src/agents/brainstormer.ts
 var brainstormerAgent = {
@@ -63,10 +64,10 @@ This is DESIGN ONLY. The planner agent handles detailed implementation plans.
     background_task(agent="pattern-finder", prompt="Find patterns for [similar functionality]", description="Find patterns")
   </fire-example>
   <poll>
-    background_list()  // repeat until all show "completed"
+    background_list()  // repeat until all show "completed" or "error"
   </poll>
   <collect>
-    background_output(task_id=...) for each completed task
+    background_output(task_id=...) for each completed task (skip errored tasks)
   </collect>
   <focus>purpose, constraints, success criteria</focus>
 </phase>
@@ -454,8 +455,8 @@ All research must serve the design - never second-guess design decisions.
     - btca_ask for library internals when needed
   </fire-phase>
   <collect-phase description="Poll until all complete, then collect">
-    - Poll with background_list until all tasks show completed
-    - Call background_output(task_id=...) for each completed task
+    - Poll with background_list until all tasks show completed or error
+    - Call background_output(task_id=...) for each completed task (skip errored)
     - Combine all results for planning phase
   </collect-phase>
   <rule>Only research what's needed to implement the design</rule>
@@ -627,6 +628,13 @@ Execute the plan. Write code. Verify.
 <step>Report results</step>
 </process>
 
+<terminal-tools>
+<bash>Use for synchronous commands that complete (npm install, git, builds)</bash>
+<pty>Use for background processes (dev servers, watch modes, REPLs)</pty>
+<rule>If plan says "start dev server" or "run in background", use pty_spawn</rule>
+<rule>If plan says "run command" or "install", use bash</rule>
+</terminal-tools>
+
 <before-each-change>
 <check>Verify file exists where expected</check>
 <check>Verify code structure matches plan assumptions</check>
@@ -753,6 +761,12 @@ Check correctness and style. Be specific. Run code, don't just read.
 <step>Report with precise references</step>
 </process>
 
+<terminal-verification>
+<rule>If implementation includes PTY usage, verify sessions are properly cleaned up</rule>
+<rule>If tests require a running server, check that pty_spawn was used appropriately</rule>
+<rule>Check that long-running processes use PTY, not blocking bash</rule>
+</terminal-verification>
+
 <output-format>
 <template>
 ## Review: [Component]
@@ -802,6 +816,24 @@ You have access to background task management tools:
 - background_list: List all background tasks and their status
 </background-tools>
 
+<pty-tools description="For background bash processes">
+PTY tools manage background terminal sessions (different from background_task which runs subagents):
+- pty_spawn: Start a background process (dev server, watch mode, REPL)
+- pty_write: Send input to a PTY (commands, Ctrl+C, etc.)
+- pty_read: Read output from a PTY buffer
+- pty_list: List all PTY sessions
+- pty_kill: Terminate a PTY session
+
+Use PTY when:
+- Plan requires starting a dev server before running tests
+- Plan requires a watch mode process running during implementation
+- Plan requires interactive terminal input
+
+Do NOT use PTY for:
+- Quick commands (use bash)
+- Subagent tasks (use background_task)
+</pty-tools>
+
 <workflow pattern="fire-and-check">
 <step>Parse plan to extract individual tasks</step>
 <step>Analyze task dependencies to build execution graph</step>
@@ -1052,7 +1084,7 @@ Just do it - including obvious follow-up actions.
 </phase>
 
 <phase name="ledger" trigger="context getting full or session ending">
-<action>System auto-updates ledger at 80% context usage</action>
+<action>System auto-updates ledger at 60% context usage</action>
 <output>thoughts/ledgers/CONTINUITY_{session-name}.md</output>
 </phase>
 </workflow>
@@ -1080,6 +1112,23 @@ Just do it - including obvious follow-up actions.
 </when-to-use>
 </library-research>
 
+<terminal-tools description="Choose the right terminal tool">
+<tool name="bash">Synchronous commands. Use for: npm install, git, builds, quick commands that complete.</tool>
+<tool name="pty_spawn">Background PTY sessions. Use for: dev servers, watch modes, REPLs, long-running processes.</tool>
+<when-to-use>
+<use tool="bash">Command completes quickly (npm install, git status, mkdir)</use>
+<use tool="pty_spawn">Process runs indefinitely (npm run dev, pytest --watch, python REPL)</use>
+<use tool="pty_spawn">Need to send interactive input (Ctrl+C, responding to prompts)</use>
+<use tool="pty_spawn">Want to check output later without blocking</use>
+</when-to-use>
+<pty-workflow>
+<step>pty_spawn to start the process</step>
+<step>pty_read to check output (use pattern to filter)</step>
+<step>pty_write to send input (\\n for Enter, \\x03 for Ctrl+C)</step>
+<step>pty_kill when done (cleanup=true to remove)</step>
+</pty-workflow>
+</terminal-tools>
+
 <tracking>
 <rule>Use TodoWrite to track what you're doing</rule>
 <rule>Never discard tasks without explicit approval</rule>
@@ -1160,8 +1209,8 @@ var PROMPT2 = `
 
     <phase name="2-collect" description="Poll and collect all results">
       <description>Poll background_list until all tasks complete, then collect with background_output</description>
-      <action>Poll background_list until all tasks show "completed"</action>
-      <action>Call background_output for each completed task</action>
+      <action>Poll background_list until all tasks show "completed" or "error"</action>
+      <action>Call background_output for each completed task (skip errored)</action>
       <action>Process tool results from phase 1</action>
     </phase>
 
@@ -1329,8 +1378,8 @@ var PROMPT2 = `
 
     <step description="COLLECT: Poll and gather all results">
       First poll until all tasks complete:
-      - background_list()  // repeat until all show "completed"
-      Then collect ALL results:
+      - background_list()  // repeat until all show "completed" or "error"
+      Then collect results (skip errored tasks):
       - background_output(task_id=task_id_1)
       - background_output(task_id=task_id_2)
       - background_output(task_id=task_id_3)
@@ -15411,7 +15460,7 @@ function createFileOpsTrackerHook(_ctx) {
 }
 
 // src/hooks/auto-clear-ledger.ts
-var DEFAULT_THRESHOLD = 0.8;
+var DEFAULT_THRESHOLD = 0.6;
 var MIN_TOKENS_FOR_CLEAR = 50000;
 var CLEAR_COOLDOWN_MS = 60000;
 function createAutoClearLedgerHook(ctx) {
@@ -16063,20 +16112,789 @@ ${result}
     background_list
   };
 }
+// node_modules/bun-pty/src/terminal.ts
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { Buffer } from "buffer";
+
+// node_modules/bun-pty/src/interfaces.ts
+class EventEmitter {
+  listeners = [];
+  event = (listener) => {
+    this.listeners.push(listener);
+    return {
+      dispose: () => {
+        const i = this.listeners.indexOf(listener);
+        if (i !== -1) {
+          this.listeners.splice(i, 1);
+        }
+      }
+    };
+  };
+  fire(data) {
+    for (const listener of this.listeners) {
+      listener(data);
+    }
+  }
+}
+
+// node_modules/bun-pty/src/terminal.ts
+import { join as join4, dirname as dirname3, basename as basename2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+var DEFAULT_COLS = 80;
+var DEFAULT_ROWS = 24;
+var DEFAULT_FILE = "sh";
+var DEFAULT_NAME = "xterm";
+function shQuote(s) {
+  if (s.length === 0)
+    return "''";
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function resolveLibPath() {
+  const env = process.env.BUN_PTY_LIB;
+  if (env && existsSync2(env))
+    return env;
+  try {
+    const embeddedPath = __require(`../rust-pty/target/release/${process.platform === "win32" ? "rust_pty.dll" : process.platform === "darwin" ? process.arch === "arm64" ? "librust_pty_arm64.dylib" : "librust_pty.dylib" : process.arch === "arm64" ? "librust_pty_arm64.so" : "librust_pty.so"}`);
+    if (embeddedPath)
+      return embeddedPath;
+  } catch {}
+  const platform = process.platform;
+  const arch = process.arch;
+  const filenames = platform === "darwin" ? arch === "arm64" ? ["librust_pty_arm64.dylib", "librust_pty.dylib"] : ["librust_pty.dylib"] : platform === "win32" ? ["rust_pty.dll"] : arch === "arm64" ? ["librust_pty_arm64.so", "librust_pty.so"] : ["librust_pty.so"];
+  const base = Bun.fileURLToPath(import.meta.url);
+  const fileDir = dirname3(base);
+  const dirName = basename2(fileDir);
+  const here = dirName === "src" || dirName === "dist" ? dirname3(fileDir) : fileDir;
+  const basePaths = [
+    join4(here, "rust-pty", "target", "release"),
+    join4(here, "..", "bun-pty", "rust-pty", "target", "release"),
+    join4(process.cwd(), "node_modules", "bun-pty", "rust-pty", "target", "release")
+  ];
+  const fallbackPaths = [];
+  for (const basePath of basePaths) {
+    for (const filename of filenames) {
+      fallbackPaths.push(join4(basePath, filename));
+    }
+  }
+  for (const path of fallbackPaths) {
+    if (existsSync2(path))
+      return path;
+  }
+  throw new Error(`librust_pty shared library not found.
+Checked:
+  - BUN_PTY_LIB=${env ?? "<unset>"}
+  - ${fallbackPaths.join(`
+  - `)}
+
+Set BUN_PTY_LIB or ensure one of these paths contains the file.`);
+}
+var libPath = resolveLibPath();
+var lib;
+try {
+  lib = dlopen(libPath, {
+    bun_pty_spawn: {
+      args: [FFIType.cstring, FFIType.cstring, FFIType.cstring, FFIType.i32, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_write: {
+      args: [FFIType.i32, FFIType.pointer, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_read: {
+      args: [FFIType.i32, FFIType.pointer, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_resize: {
+      args: [FFIType.i32, FFIType.i32, FFIType.i32],
+      returns: FFIType.i32
+    },
+    bun_pty_kill: { args: [FFIType.i32], returns: FFIType.i32 },
+    bun_pty_get_pid: { args: [FFIType.i32], returns: FFIType.i32 },
+    bun_pty_get_exit_code: { args: [FFIType.i32], returns: FFIType.i32 },
+    bun_pty_close: { args: [FFIType.i32], returns: FFIType.void }
+  });
+} catch (error45) {
+  console.error("Failed to load lib", error45);
+}
+
+class Terminal {
+  handle = -1;
+  _pid = -1;
+  _cols = DEFAULT_COLS;
+  _rows = DEFAULT_ROWS;
+  _name = DEFAULT_NAME;
+  _readLoop = false;
+  _closing = false;
+  _onData = new EventEmitter;
+  _onExit = new EventEmitter;
+  constructor(file2 = DEFAULT_FILE, args = [], opts = { name: DEFAULT_NAME }) {
+    this._cols = opts.cols ?? DEFAULT_COLS;
+    this._rows = opts.rows ?? DEFAULT_ROWS;
+    const cwd = opts.cwd ?? process.cwd();
+    const cmdline = [shQuote(file2), ...args.map(shQuote)].join(" ");
+    let envStr = "";
+    if (opts.env) {
+      const envPairs = Object.entries(opts.env).map(([k, v]) => `${k}=${v}`);
+      envStr = envPairs.join("\x00") + "\x00";
+    }
+    this.handle = lib.symbols.bun_pty_spawn(Buffer.from(`${cmdline}\x00`, "utf8"), Buffer.from(`${cwd}\x00`, "utf8"), Buffer.from(`${envStr}\x00`, "utf8"), this._cols, this._rows);
+    if (this.handle < 0)
+      throw new Error("PTY spawn failed");
+    this._pid = lib.symbols.bun_pty_get_pid(this.handle);
+    this._startReadLoop();
+  }
+  get pid() {
+    return this._pid;
+  }
+  get cols() {
+    return this._cols;
+  }
+  get rows() {
+    return this._rows;
+  }
+  get process() {
+    return "shell";
+  }
+  get onData() {
+    return this._onData.event;
+  }
+  get onExit() {
+    return this._onExit.event;
+  }
+  write(data) {
+    if (this._closing)
+      return;
+    const buf = Buffer.from(data, "utf8");
+    lib.symbols.bun_pty_write(this.handle, ptr(buf), buf.length);
+  }
+  resize(cols, rows) {
+    if (this._closing)
+      return;
+    this._cols = cols;
+    this._rows = rows;
+    lib.symbols.bun_pty_resize(this.handle, cols, rows);
+  }
+  kill(signal = "SIGTERM") {
+    if (this._closing)
+      return;
+    this._closing = true;
+    lib.symbols.bun_pty_kill(this.handle);
+    lib.symbols.bun_pty_close(this.handle);
+    this._onExit.fire({ exitCode: 0, signal });
+  }
+  async _startReadLoop() {
+    if (this._readLoop)
+      return;
+    this._readLoop = true;
+    const buf = Buffer.allocUnsafe(4096);
+    while (this._readLoop && !this._closing) {
+      const n = lib.symbols.bun_pty_read(this.handle, ptr(buf), buf.length);
+      if (n > 0) {
+        this._onData.fire(buf.subarray(0, n).toString("utf8"));
+      } else if (n === -2) {
+        const exitCode = lib.symbols.bun_pty_get_exit_code(this.handle);
+        this._onExit.fire({ exitCode });
+        break;
+      } else if (n < 0) {
+        break;
+      } else {
+        await new Promise((r) => setTimeout(r, 8));
+      }
+    }
+  }
+}
+
+// node_modules/bun-pty/src/index.ts
+function spawn3(file2, args, options) {
+  return new Terminal(file2, args, options);
+}
+
+// src/tools/pty/buffer.ts
+var parsed = parseInt(process.env.PTY_MAX_BUFFER_LINES || "50000", 10);
+var DEFAULT_MAX_LINES = isNaN(parsed) ? 50000 : parsed;
+
+class RingBuffer {
+  lines = [];
+  maxLines;
+  constructor(maxLines = DEFAULT_MAX_LINES) {
+    this.maxLines = maxLines;
+  }
+  append(data) {
+    const newLines = data.split(`
+`);
+    for (const line of newLines) {
+      this.lines.push(line);
+      if (this.lines.length > this.maxLines) {
+        this.lines.shift();
+      }
+    }
+  }
+  read(offset = 0, limit) {
+    const start = Math.max(0, offset);
+    const end = limit !== undefined ? start + limit : this.lines.length;
+    return this.lines.slice(start, end);
+  }
+  search(pattern) {
+    const matches = [];
+    for (let i = 0;i < this.lines.length; i++) {
+      const line = this.lines[i];
+      if (line !== undefined && pattern.test(line)) {
+        matches.push({ lineNumber: i + 1, text: line });
+      }
+    }
+    return matches;
+  }
+  get length() {
+    return this.lines.length;
+  }
+  clear() {
+    this.lines = [];
+  }
+}
+
+// src/tools/pty/manager.ts
+function generateId() {
+  const hex3 = Array.from(crypto.getRandomValues(new Uint8Array(4))).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `pty_${hex3}`;
+}
+
+class PTYManager {
+  sessions = new Map;
+  spawn(opts) {
+    const id = generateId();
+    const args = opts.args ?? [];
+    const workdir = opts.workdir ?? process.cwd();
+    const env = { ...process.env, ...opts.env };
+    const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
+    const ptyProcess = spawn3(opts.command, args, {
+      name: "xterm-256color",
+      cols: 120,
+      rows: 40,
+      cwd: workdir,
+      env
+    });
+    const buffer = new RingBuffer;
+    const session = {
+      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) => {
+      buffer.append(data);
+    });
+    ptyProcess.onExit(({ exitCode }) => {
+      if (session.status === "running") {
+        session.status = "exited";
+        session.exitCode = exitCode;
+      }
+    });
+    return this.toInfo(session);
+  }
+  write(id, data) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status !== "running") {
+      return false;
+    }
+    session.process.write(data);
+    return true;
+  }
+  read(id, offset = 0, limit) {
+    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, pattern, offset = 0, limit) {
+    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() {
+    return Array.from(this.sessions.values()).map((s) => this.toInfo(s));
+  }
+  get(id) {
+    const session = this.sessions.get(id);
+    return session ? this.toInfo(session) : null;
+  }
+  kill(id, cleanup = false) {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status === "running") {
+      try {
+        session.process.kill();
+      } catch {}
+      session.status = "killed";
+    }
+    if (cleanup) {
+      session.buffer.clear();
+      this.sessions.delete(id);
+    }
+    return true;
+  }
+  cleanupBySession(parentSessionId) {
+    for (const [id, session] of this.sessions) {
+      if (session.parentSessionId === parentSessionId) {
+        this.kill(id, true);
+      }
+    }
+  }
+  cleanupAll() {
+    for (const id of this.sessions.keys()) {
+      this.kill(id, true);
+    }
+  }
+  toInfo(session) {
+    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
+    };
+  }
+}
+// src/tools/pty/tools/spawn.ts
+var 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"]`;
+function createPtySpawnTool(manager) {
+  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(`
+`);
+      return output;
+    }
+  });
+}
+// src/tools/pty/tools/write.ts
+var DESCRIPTION2 = `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"`;
+function parseEscapeSequences(input) {
+  return input.replace(/\\(x[0-9A-Fa-f]{2}|u[0-9A-Fa-f]{4}|[nrt0\\])/g, (match, seq) => {
+    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 `
+`;
+      case "r":
+        return "\r";
+      case "t":
+        return "\t";
+      case "0":
+        return "\x00";
+      case "\\":
+        return "\\";
+      default:
+        return match;
+    }
+  });
+}
+function createPtyWriteTool(manager) {
+  return tool({
+    description: DESCRIPTION2,
+    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}'.`);
+      }
+      const parsedData = parseEscapeSequences(args.data);
+      const success2 = manager.write(args.id, parsedData);
+      if (!success2) {
+        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}"`;
+    }
+  });
+}
+// src/tools/pty/tools/read.ts
+var DESCRIPTION3 = `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`;
+var DEFAULT_LIMIT = 500;
+var MAX_LINE_LENGTH = 2000;
+function createPtyReadTool(manager) {
+  return tool({
+    description: DESCRIPTION3,
+    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;
+        try {
+          regex = new RegExp(args.pattern, args.ignoreCase ? "i" : "");
+        } catch (e) {
+          const error45 = e instanceof Error ? e.message : String(e);
+          throw new Error(`Invalid regex pattern '${args.pattern}': ${error45}`);
+        }
+        const result2 = manager.search(args.id, regex, offset, limit);
+        if (!result2) {
+          throw new Error(`PTY session '${args.id}' not found.`);
+        }
+        if (result2.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: ${result2.totalLines}`,
+            `</pty_output>`
+          ].join(`
+`);
+        }
+        const formattedLines2 = result2.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 output2 = [
+          `<pty_output id="${args.id}" status="${session.status}" pattern="${args.pattern}">`,
+          ...formattedLines2,
+          ""
+        ];
+        if (result2.hasMore) {
+          output2.push(`(${result2.matches.length} of ${result2.totalMatches} matches shown. Use offset=${offset + result2.matches.length} to see more.)`);
+        } else {
+          output2.push(`(${result2.totalMatches} match${result2.totalMatches === 1 ? "" : "es"} from ${result2.totalLines} total lines)`);
+        }
+        output2.push(`</pty_output>`);
+        return output2.join(`
+`);
+      }
+      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(`
+`);
+      }
+      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(`
+`);
+    }
+  });
+}
+// src/tools/pty/tools/list.ts
+var DESCRIPTION4 = `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`;
+function createPtyListTool(manager) {
+  return tool({
+    description: DESCRIPTION4,
+    args: {},
+    execute: async () => {
+      const sessions = manager.list();
+      if (sessions.length === 0) {
+        return `<pty_list>
+No active PTY sessions.
+</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(`
+`);
+    }
+  });
+}
+// src/tools/pty/tools/kill.ts
+var DESCRIPTION5 = `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`;
+function createPtyKillTool(manager) {
+  return tool({
+    description: DESCRIPTION5,
+    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 success2 = manager.kill(args.id, cleanup);
+      if (!success2) {
+        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(`
+`);
+    }
+  });
+}
+// src/tools/pty/index.ts
+function createPtyTools(manager) {
+  return {
+    pty_spawn: createPtySpawnTool(manager),
+    pty_write: createPtyWriteTool(manager),
+    pty_read: createPtyReadTool(manager),
+    pty_list: createPtyListTool(manager),
+    pty_kill: createPtyKillTool(manager)
+  };
+}
+
 // src/config-loader.ts
 import { readFile as readFile3 } from "fs/promises";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { homedir as homedir2 } from "os";
 var SAFE_AGENT_PROPERTIES = ["model", "temperature", "maxTokens"];
 async function loadMicodeConfig(configDir) {
-  const baseDir = configDir ?? join4(homedir2(), ".config", "opencode");
-  const configPath = join4(baseDir, "micode.json");
+  const baseDir = configDir ?? join5(homedir2(), ".config", "opencode");
+  const configPath = join5(baseDir, "micode.json");
   try {
     const content = await readFile3(configPath, "utf-8");
-    const parsed = JSON.parse(content);
-    if (parsed.agents && typeof parsed.agents === "object") {
+    const parsed2 = JSON.parse(content);
+    if (parsed2.agents && typeof parsed2.agents === "object") {
       const sanitizedAgents = {};
-      for (const [agentName, agentConfig] of Object.entries(parsed.agents)) {
+      for (const [agentName, agentConfig] of Object.entries(parsed2.agents)) {
         if (agentConfig && typeof agentConfig === "object") {
           const sanitized = {};
           const config2 = agentConfig;
@@ -16090,7 +16908,7 @@ async function loadMicodeConfig(configDir) {
       }
       return { agents: sanitizedAgents };
     }
-    return parsed;
+    return parsed2;
   } catch {
     return null;
   }
@@ -16168,6 +16986,8 @@ var OpenCodeConfigPlugin = async (ctx) => {
   const fileOpsTrackerHook = createFileOpsTrackerHook(ctx);
   const backgroundTaskManager = new BackgroundTaskManager(ctx);
   const backgroundTaskTools = createBackgroundTaskTools(backgroundTaskManager);
+  const ptyManager = new PTYManager;
+  const ptyTools = createPtyTools(ptyManager);
   return {
     tool: {
       ast_grep_search,
@@ -16175,7 +16995,8 @@ var OpenCodeConfigPlugin = async (ctx) => {
       btca_ask,
       look_at,
       artifact_search,
-      ...backgroundTaskTools
+      ...backgroundTaskTools,
+      ...ptyTools
     },
     config: async (config2) => {
       config2.permission = {
@@ -16249,6 +17070,7 @@ var OpenCodeConfigPlugin = async (ctx) => {
         const props = event.properties;
         if (props?.info?.id) {
           thinkModeState.delete(props.info.id);
+          ptyManager.cleanupBySession(props.info.id);
         }
       }
       await autoCompactHook.event({ event });