@meowlynxsea/koi 0.1.2 → 0.1.3

package/src/tools/bash.ts

@@ -1,19 +1,22 @@
 /**
- * BashTool — Shell execution with safety controls
+ * BashTool — Shell execution with PTY isolation
  *
  * Features:
- * - Timeout with SIGTERM → SIGKILL escalation
- * - Output size limit (capped to prevent context overflow)
- * - Dangerous command warnings (displayed but not blocking)
+ * - PTY-based execution (full terminal isolation)
+ * - No I/O leakage to outer environment
+ * - Timeout handling: transfer to monitor instead of killing
+ * - Support for interactive commands (sudo, vim, etc.)
  */
 
 import { Type } from "typebox";
-import { spawn } from "child_process";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 import type { TextContent } from "@mariozechner/pi-ai";
 import { checkPermission, isDangerousBashCommand } from "../agent/check-permissions.js";
 import { requestPermission } from "../agent/permission-ui.js";
 import { withWriteLock } from "../agent/tool-orchestration.js";
+import { monitorRegistry } from "../agent/monitor-registry.js";
+import { spawnPty, PtySession, generatePtyId } from "./pty.js";
+import { activeSessionRef } from "../agent/hooks.js";
 import type { ToolResultWithError } from "./types.js";
 
 export const bashSchema = Type.Object({
@@ -28,102 +31,207 @@ export type BashToolInput = {
 
 const MAX_OUTPUT_CHARS = 200_000;
 
-function execBash(command: string, timeoutSec?: number): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
-  return new Promise((resolve, reject) => {
-    const shell = process.platform === "win32" ? "cmd" : "bash";
-    const shellFlag = process.platform === "win32" ? "/c" : "-c";
-    const child = spawn(shell, [shellFlag, command], {
-      cwd: process.cwd(),
-      env: { ...process.env, CLAUDECODE: "1", GIT_EDITOR: "true" },
-      stdio: ["ignore", "pipe", "pipe"],
-    });
+export interface BashResult {
+  content: TextContent[];
+  details: {
+    exitCode?: number;
+    timedOut: boolean;
+    monitorId?: string;
+  };
+}
 
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-
-    const effectiveTimeout = timeoutSec ?? 60;
-    if (effectiveTimeout > 0) {
-      timeoutHandle = setTimeout(() => {
-        timedOut = true;
-        child.kill("SIGTERM");
-        setTimeout(() => {
-          if (!child.killed) child.kill("SIGKILL");
-        }, 5000);
-      }, effectiveTimeout * 1000);
-    }
+/**
+ * Execute bash command with PTY and timeout handling.
+ * 
+ * If timeout occurs:
+ *   - Does NOT kill the process
+ *   - Transfers the PTY to a new monitor
+ *   - Returns the monitor ID for the agent to continue
+ * 
+ * This ensures complete I/O isolation - no password prompts or
+ * interactive input/output can leak to the outer environment.
+ */
+async function execBashWithPty(
+  command: string,
+  timeoutSec: number = 60,
+  onData?: (data: string) => void,
+  signal?: AbortSignal,
+  onTimeout?: (monitorId: string) => void
+): Promise<{
+  exitCode?: number;
+  output: string;
+  timedOut: boolean;
+  transferredMonitorId?: string;
+  session?: PtySession;
+}> {
+  type ExecBashResult = {
+    exitCode?: number;
+    output: string;
+    timedOut: boolean;
+    transferredMonitorId?: string;
+    session?: PtySession;
+  };
+  const sessionId = activeSessionRef.current?.sessionId ?? "unknown";
+  const ptyId = generatePtyId();
 
-    child.stdout?.on("data", (chunk: Buffer) => {
-      stdout += chunk.toString("utf-8");
-      if (stdout.length + stderr.length > MAX_OUTPUT_CHARS * 2) {
-        child.kill("SIGKILL");
-      }
-    });
-    child.stderr?.on("data", (chunk: Buffer) => {
-      stderr += chunk.toString("utf-8");
-      if (stdout.length + stderr.length > MAX_OUTPUT_CHARS * 2) {
-        child.kill("SIGKILL");
-      }
-    });
+  let output = "";
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  let ptySession: PtySession | undefined;
+  let resolvePromise: ((value: ExecBashResult) => void) | undefined;
 
-    child.on("error", (err) => {
-      if (timeoutHandle) clearTimeout(timeoutHandle);
-      reject(err);
-    });
+  // Create PTY
+  const ptyProcess = spawnPty({
+    command: "bash",
+    args: ["-c", command],
+  });
+
+  // Collect output directly from PTY (no PtySession wrapper)
+  ptyProcess.onData((data: string) => {
+    output += data;
+    onData?.(data);
+  });
+
+  ptySession = new PtySession(ptyId, ptyProcess, command);
+
+  // Set up timeout
+  if (timeoutSec > 0) {
+    timeoutHandle = setTimeout(() => {
+      timedOut = true;
+
+      // DO NOT kill the process - transfer to monitor instead
+      const monitorId = monitorRegistry.adopt(
+        ptySession!,
+        sessionId,
+        command,
+        `Bash timeout transfer: ${command.slice(0, 50)}${command.length > 50 ? "…" : ""}`
+      );
+      
+      // Clean up the old session's listeners so only monitor receives events
+      ptySession!.cleanup();
 
-    child.on("close", (code) => {
+      // Notify caller about the timeout
+      onTimeout?.(monitorId);
+
+      // Notify via signal if available
+      signal?.removeEventListener("abort", onAbort);
+
+      // Resolve the promise now
+      resolvePromise?.({
+        exitCode: undefined,
+        output,
+        timedOut: true,
+        transferredMonitorId: monitorId,
+        session: undefined,
+      });
+    }, timeoutSec * 1000);
+  }
+
+  // Handle abort signal
+  const onAbort = () => {
+    if (!timedOut) {
+      ptySession?.kill("SIGTERM");
+    }
+  };
+  signal?.addEventListener("abort", onAbort);
+
+  // Wait for PTY exit
+  return new Promise((resolve) => {
+    resolvePromise = resolve;
+    ptyProcess.onExit(({ exitCode }) => {
       if (timeoutHandle) clearTimeout(timeoutHandle);
-      resolve({ stdout, stderr, exitCode: code ?? 0, timedOut });
+      signal?.removeEventListener("abort", onAbort);
+
+      resolve({
+        exitCode: exitCode ?? 0,
+        output,
+        timedOut: false,
+        transferredMonitorId: undefined,
+        session: undefined,
+      });
     });
   });
 }
 
-export async function executeBash(params: BashToolInput): Promise<{ content: TextContent[]; details: { exitCode: number; timedOut: boolean } }> {
-  const { stdout, stderr, exitCode, timedOut } = await execBash(params.command, params.timeout);
-
-  let output = stdout;
-  if (stderr) {
-    output += (output ? "\n\n" : "") + `[stderr]\n${stderr}`;
-  }
-  if (timedOut) {
-    output += "\n\n[Command timed out and was terminated]";
+export async function executeBash(params: BashToolInput): Promise<BashResult> {
+  let monitorId: string | undefined;
+  
+  const { exitCode, output, timedOut, transferredMonitorId } = await execBashWithPty(
+    params.command,
+    params.timeout,
+    undefined,
+    undefined,
+    (id) => { monitorId = id; }
+  );
+  
+  // Use the monitorId from callback if available
+  if (timedOut && !monitorId) {
+    monitorId = transferredMonitorId;
   }
-  if (output.length > MAX_OUTPUT_CHARS) {
-    output = output.slice(0, MAX_OUTPUT_CHARS) + `\n\n[Output truncated: ${output.length} chars total, limit: ${MAX_OUTPUT_CHARS}]`;
+
+  let displayOutput = output;
+
+  // Truncate if needed
+  if (displayOutput.length > MAX_OUTPUT_CHARS) {
+    displayOutput =
+      displayOutput.slice(0, MAX_OUTPUT_CHARS) +
+      `\n\n[Output truncated: ${output.length} chars total, limit: ${MAX_OUTPUT_CHARS}]`;
   }
 
+  // Warning for dangerous commands
   const warning = isDangerousBashCommand(params.command)
     ? "\n\n[Warning: This command may be destructive. Proceed with caution.]"
     : "";
 
+  if (timedOut && monitorId) {
+    // Timeout occurred - process transferred to monitor
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Command timed out after ${params.timeout}s.\n\n` +
+            `The process has been transferred to a background monitor.\n\n` +
+            `Monitor ID: ${monitorId}\n` +
+            `Use SendToMonitor to provide input (e.g., passwords) or InterruptMonitor to stop it.\n\n` +
+            `Latest output:\n${displayOutput.slice(-2000)}${warning}`,
+        } satisfies TextContent,
+      ],
+      details: { exitCode: undefined, timedOut: true, monitorId },
+    };
+  }
+
+  // Normal completion
   return {
-    content: [{ type: "text", text: output + warning }],
-    details: { exitCode, timedOut },
+    content: [{ type: "text", text: displayOutput + warning }],
+    details: { exitCode, timedOut: false },
   };
 }
 
-export function createBashToolDefinition(_cwd: string): ToolDefinition<typeof bashSchema, { exitCode: number; timedOut: boolean }> {
+export function createBashToolDefinition(_cwd: string): ToolDefinition<typeof bashSchema, { exitCode?: number; timedOut: boolean; monitorId?: string }> {
   return {
     name: "bash",
     label: "Bash",
     description:
-      "Execute a bash command in the environment.\n\n" +
+      "Execute a bash command in the environment with full PTY isolation.\n\n" +
       "IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands. " +
       "Instead, use the appropriate dedicated tool.\n\n" +
       "Git Safety Protocol:\n" +
       "- NEVER update the git config\n" +
       "- NEVER run destructive git commands (push --force, reset --hard, checkout .) unless explicitly requested\n" +
       "- NEVER use git commands with the -i flag (interactive)\n" +
-      "- NEVER skip hooks (--no-verify, --no-gpg-sign) unless explicitly asked",
-    promptSnippet: "Bash: execute shell commands (last resort — prefer dedicated tools)",
+      "- NEVER skip hooks (--no-verify, --no-gpg-sign) unless explicitly asked\n\n" +
+      "Timeout Handling:\n" +
+      "If the command times out, it will be transferred to a background monitor instead of being killed. " +
+      "Use SendToMonitor to interact with the process (e.g., enter sudo passwords).",
+    promptSnippet: "Bash: execute shell commands with PTY isolation (last resort — prefer dedicated tools)",
     parameters: bashSchema,
     executionMode: "parallel",
     async execute(_toolCallId, params, _signal, _onUpdate) {
       return withWriteLock(async () => {
         const perm = checkPermission("bash", params);
         if (perm.decision === "deny") {
-          const result: ToolResultWithError<{ exitCode: number; timedOut: boolean }> = {
+          const result: ToolResultWithError<{ exitCode?: number; timedOut: boolean; monitorId?: string }> = {
             content: [{ type: "text", text: `Permission denied: ${perm.reason ?? "bash operation blocked"}` }],
             details: { exitCode: 1, timedOut: false },
             isError: true,
@@ -133,7 +241,7 @@ export function createBashToolDefinition(_cwd: string): ToolDefinition<typeof ba
         if (perm.decision === "ask") {
           const allowed = await requestPermission({ toolName: "bash", args: params, reason: perm.reason ?? "Confirm shell command" });
           if (!allowed) {
-            const result: ToolResultWithError<{ exitCode: number; timedOut: boolean }> = {
+            const result: ToolResultWithError<{ exitCode?: number; timedOut: boolean; monitorId?: string }> = {
               content: [{ type: "text", text: "User denied permission to execute command." }],
               details: { exitCode: 1, timedOut: false },
               isError: true,

package/src/tools/index.ts

@@ -30,6 +30,7 @@ import {
   createMonitorToolDefinition,
   createCancelMonitorToolDefinition,
 } from "./monitor.js";
+import { createSendToMonitorToolDefinition } from "./send-to-monitor.js";
 import { createSkillToolDefinition } from "./skill.js";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
 
@@ -56,6 +57,7 @@ export function createCodingToolDefinitions(
     createTaskUpdateToolDefinition(_cwd, taskManager),
     createMonitorToolDefinition(),
     createCancelMonitorToolDefinition(),
+    createSendToMonitorToolDefinition(),
     createSkillToolDefinition(),
   ] as ToolDefinition[];
 }

package/src/tools/pty.ts

@@ -0,0 +1,285 @@
+/**
+ * PTY Utilities — Bun.spawn terminal 封装
+ *
+ * 提供跨平台 PTY (Pseudo-Terminal) 功能，用于:
+ * - 完全隔离输入输出流
+ * - 支持交互式命令（如 sudo、vim）
+ * - 支持 monitor 内的进程输入
+ */
+
+import { EventEmitter } from "events";
+
+export interface PtyOptions {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  cols?: number;
+  rows?: number;
+  name?: string;
+}
+
+export interface PtyData {
+  type: "data" | "exit" | "error";
+  data?: string;
+  exitCode?: number;
+  error?: string;
+}
+
+export type PtyDataCallback = (data: PtyData) => void;
+
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 30;
+
+/**
+ * IPty 兼容接口 — 与 node-pty 的 IPty 保持一致
+ */
+export interface IPty {
+  pid: number;
+  onData(handler: (data: string) => void): void;
+  onExit(handler: (exit: { exitCode: number; signal: string }) => void): void;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+/**
+ * Bun PTY 适配器 — 使用 Bun.spawn 的 terminal 选项
+ */
+class BunPty extends EventEmitter implements IPty {
+  readonly pid: number;
+  private proc: ReturnType<typeof Bun.spawn>;
+  private textDecoder = new TextDecoder();
+
+  constructor(options: PtyOptions) {
+    super();
+    const shell = process.platform === "win32" ? "powershell.exe" : "bash";
+    const args = process.platform === "win32" ? [] : ["--login"];
+
+    const command = options.command ?? shell;
+    const commandArgs = options.args ?? args;
+
+    const self = this;
+
+    this.proc = Bun.spawn([command, ...commandArgs], {
+      cwd: options.cwd ?? process.cwd(),
+      env: {
+        ...process.env,
+        ...options.env,
+        CLAUDECODE: "1",
+        TERM: "xterm-256color",
+      } as Record<string, string>,
+      terminal: {
+        name: options.name ?? "xterm-256color",
+        cols: options.cols ?? DEFAULT_COLS,
+        rows: options.rows ?? DEFAULT_ROWS,
+        data(_terminal, data) {
+          self.emit("data", self.textDecoder.decode(data));
+        },
+      },
+      onExit(_subprocess, exitCode, signalCode) {
+        self.emit("exit", { exitCode: exitCode ?? 0, signal: signalCode ?? "" });
+      },
+    });
+
+    this.pid = this.proc.pid;
+  }
+
+  onData(handler: (data: string) => void): void {
+    this.on("data", handler);
+  }
+
+  onExit(handler: (exit: { exitCode: number; signal: string }) => void): void {
+    this.on("exit", handler);
+  }
+
+  write(data: string): void {
+    this.proc.terminal?.write(data);
+  }
+
+  resize(cols: number, rows: number): void {
+    try {
+      this.proc.terminal?.resize(cols, rows);
+    } catch {
+      // 忽略调整大小失败
+    }
+  }
+
+  kill(signal?: string): void {
+    try {
+      this.proc.kill(signal as number | NodeJS.Signals);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/**
+ * 创建并启动一个 PTY 进程
+ * 注意：这个函数不设置任何监听器。调用者应该：
+ * 1. 直接使用 pty.onData/pty.onExit 设置监听器
+ * 2. 或者用 PtySession 包装（它会自动设置监听器）
+ */
+export function spawnPty(options: PtyOptions): IPty {
+  return new BunPty(options);
+}
+
+/**
+ * PtySession 类 — 封装一个 PTY 会话
+ * 支持发送输入、调整大小、获取输出等
+ */
+export class PtySession extends EventEmitter {
+  readonly id: string;
+  readonly command: string;
+  readonly startTime: number;
+
+  /** 暴露底层 PTY 对象，用于清理监听器 */
+  readonly pty: IPty;
+
+  private outputBuffer: string[] = [];
+  private lastOutput: string = "";
+  private _exitCode?: number;
+  private _isRunning: boolean = true;
+  private _dataHandler: (data: string) => void;
+  private _exitHandler: (exit: { exitCode: number; signal: string }) => void;
+
+  constructor(id: string, pty: IPty, command: string) {
+    super();
+    this.id = id;
+    this.pty = pty;
+    this.command = command;
+    this.startTime = Date.now();
+
+    this._dataHandler = (data: string) => {
+      this.lastOutput = data;
+      this.outputBuffer.push(data);
+      this.emit("data", data);
+    };
+
+    this._exitHandler = ({ exitCode, signal }) => {
+      this._isRunning = false;
+      this._exitCode = exitCode;
+      this.emit("exit", { exitCode, signal });
+    };
+
+    pty.onData(this._dataHandler);
+    pty.onExit(this._exitHandler);
+  }
+
+  /**
+   * 向 PTY 进程发送输入
+   */
+  write(data: string): void {
+    if (this._isRunning) {
+      this.pty.write(data);
+    }
+  }
+
+  /**
+   * 发送带换行的输入
+   */
+  sendLine(line: string): void {
+    this.write(line + "\n");
+  }
+
+  /**
+   * 发送 Ctrl+C
+   */
+  sendInterrupt(): void {
+    this.write("\x03"); // Ctrl+C
+  }
+
+  /**
+   * 调整 PTY 大小
+   */
+  resize(cols: number, rows: number): void {
+    try {
+      this.pty.resize(cols, rows);
+    } catch (e) {
+      // 忽略调整大小失败
+    }
+  }
+
+  /**
+   * 获取当前是否在运行
+   */
+  get isRunning(): boolean {
+    return this._isRunning;
+  }
+
+  /**
+   * 获取退出码
+   */
+  get exitCode(): number | undefined {
+    return this._exitCode;
+  }
+
+  /**
+   * 获取最后输出
+   */
+  get currentOutput(): string {
+    return this.lastOutput;
+  }
+
+  /**
+   * 获取所有输出（合并后的字符串）
+   */
+  getAllOutput(): string {
+    return this.outputBuffer.join("");
+  }
+
+  /**
+   * 获取所有输出（按行分割）
+   */
+  getOutputLines(): string[] {
+    const all = this.getAllOutput();
+    return all.split("\n").filter((line) => line.length > 0);
+  }
+
+  /**
+   * 清理 PTY 监听器（用于 adopt 场景）
+   * 调用后此 PtySession 将不再接收 PTY 事件
+   */
+  cleanup(): void {
+    // BunPty extends EventEmitter, so removeListener works
+    try {
+      const ptyAsEmitter = this.pty as unknown as EventEmitter;
+      if (typeof ptyAsEmitter.removeListener === "function") {
+        ptyAsEmitter.removeListener("data", this._dataHandler);
+        ptyAsEmitter.removeListener("exit", this._exitHandler);
+      }
+    } catch {
+      // ignore if removeListener fails
+    }
+    // 清理 PtySession 自身的事件监听器
+    this.removeAllListeners();
+    this._isRunning = false;
+  }
+
+  /**
+   * 关闭 PTY（不杀进程）- 已废弃，请使用 cleanup()
+   * @deprecated 使用 cleanup() 代替
+   */
+  detach(): void {
+    this.cleanup();
+  }
+
+  /**
+   * 终止 PTY 进程
+   */
+  kill(signal: "SIGTERM" | "SIGKILL" = "SIGTERM"): void {
+    try {
+      this.pty.kill(signal);
+    } catch {
+      // ignore
+    }
+    this._isRunning = false;
+  }
+}
+
+/**
+ * 生成唯一的 PtySession ID
+ */
+export function generatePtyId(): string {
+  return `pty-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}