@meowlynxsea/koi 0.1.0

package/src/agent/mode.ts

@@ -0,0 +1,163 @@
+/**
+ * Agent Mode Manager
+ *
+ * Manages the three agent operating modes:
+ *   • build — full tool access (default)
+ *   • ask   — read-only tools only
+ *   • plan  — no write/edit/bash tools; planning tools allowed
+ *
+ * Also provides the active tool name allowlist for each mode,
+ * used with AgentSession.setActiveToolsByName().
+ */
+
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import { getAllMcpTools } from "../services/mcp/index.js";
+
+export type AgentMode = "build" | "ask" | "plan";
+
+let currentMode: AgentMode = "build";
+let listeners: (() => void)[] = [];
+
+function emit() {
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export function subscribeModeChanges(listener: () => void): () => void {
+  listeners.push(listener);
+  return () => {
+    listeners = listeners.filter((l) => l !== listener);
+  };
+}
+
+export function getAgentMode(): AgentMode {
+  return currentMode;
+}
+
+export function setAgentMode(mode: AgentMode): void {
+  if (currentMode === mode) return;
+  currentMode = mode;
+  emit();
+}
+
+export function cycleAgentMode(): AgentMode {
+  const order: AgentMode[] = ["build", "ask", "plan"];
+  const idx = order.indexOf(currentMode);
+  const next = order[(idx + 1) % order.length] ?? "build";
+  currentMode = next;
+  emit();
+  return next;
+}
+
+/**
+ * Inject mode awareness into the session's system prompt.
+ * Patches _baseSystemPrompt directly because Pi resets systemPrompt from it on every turn.
+ */
+export function injectModeIntoSystemPrompt(session: AgentSession, mode: AgentMode): void {
+  const modeNotice =
+    mode === "plan"
+      ? "\n\n[AGENT MODE: Plan Mode. Write/edit/bash tools are DISABLED. You must NOT modify any files. Your task is to research, analyze, and formulate a detailed step-by-step plan. Use read-only tools to gather information. Once your plan is ready, you MUST call exitPlanMode with the complete plan to return to Build Mode.]"
+      : mode === "ask"
+        ? "\n\n[AGENT MODE: Ask Mode. Only read-only tools are available. You cannot modify files or execute commands.]"
+        : "\n\n[AGENT MODE: Build Mode. All tools are available.]";
+
+  const basePrompt = (session as unknown as Record<string, string>)["_baseSystemPrompt"] ?? "";
+  const modePattern = /\n\n\[AGENT MODE:.*?\]/s;
+  const cleanPrompt = basePrompt.replace(modePattern, "");
+  const patchedPrompt = cleanPrompt + modeNotice;
+  (session as unknown as Record<string, string>)["_baseSystemPrompt"] = patchedPrompt;
+  session.state.systemPrompt = patchedPrompt;
+}
+
+
+
+const ALL_TOOLS = [
+  "read",
+  "grep",
+  "glob",
+  "ls",
+  "bash",
+  "edit",
+  "write",
+  "webfetch",
+  "taskCreate",
+  "taskGet",
+  "taskList",
+  "taskUpdate",
+  "askUserQuestion",
+  "enterPlanMode",
+  "exitPlanMode",
+  "agent",
+  "CreateMonitor",
+  "CancelMonitor",
+];
+
+const READONLY_TOOLS = [
+  "read",
+  "grep",
+  "glob",
+  "ls",
+  "webfetch",
+  "taskGet",
+  "taskList",
+];
+
+const PLAN_TOOLS = [
+  "read",
+  "grep",
+  "glob",
+  "ls",
+  "webfetch",
+  "taskGet",
+  "taskList",
+  "taskCreate",
+  "taskUpdate",
+  "askUserQuestion",
+  "enterPlanMode",
+  "exitPlanMode",
+];
+
+/**
+ * Get MCP tool names that should be included in the tool allowlist.
+ * MCP tools are included in all modes since they are user-configured and 
+ * the user should have control over them.
+ */
+function getMcpToolNames(): string[] {
+  try {
+    const mcpTools = getAllMcpTools();
+    // Filter to only return tools from connected servers
+    return mcpTools.map((tool) => tool.name);
+  } catch {
+    return [];
+  }
+}
+
+export function getActiveToolNamesForMode(mode: AgentMode): string[] {
+  // Get MCP tool names dynamically
+  const mcpToolNames = getMcpToolNames();
+  
+  switch (mode) {
+    case "build": {
+      // Build mode: all built-in tools + MCP tools
+      const baseTools = ALL_TOOLS.filter((t) => t !== "exitPlanMode");
+      return [...baseTools, ...mcpToolNames];
+    }
+    case "ask":
+      // Ask mode: readonly tools + MCP tools
+      return [...READONLY_TOOLS, ...mcpToolNames];
+    case "plan": {
+      // Plan mode: readonly + task management tools + MCP tools (for read-only MCP tools)
+      const planTools = PLAN_TOOLS.filter((t) => t !== "enterPlanMode");
+      return [...planTools, ...mcpToolNames];
+    }
+    default: {
+      const baseTools = ALL_TOOLS.filter((t) => t !== "exitPlanMode");
+      return [...baseTools, ...mcpToolNames];
+    }
+  }
+}

package/src/agent/monitor-registry.ts

@@ -0,0 +1,308 @@
+/**
+ * Monitor Registry — 后台监控任务管理器
+ *
+ * Manages background process monitors that watch command output and notify
+ * the main agent when changes occur.
+ *
+ * Notification delivery:
+ *   - Main agent busy → steer() to insert notification
+ *   - Main agent idle → prompt() to trigger a new run
+ */
+
+import { spawn, ChildProcess } from "child_process";
+import { EventEmitter } from "events";
+import { activeSessionRef } from "./hooks.js";
+
+export type MonitorStatus = "running" | "completed" | "killed" | "error";
+
+export interface MonitorEntry {
+  id: string;
+  sessionId: string;
+  description: string;
+  command: string;
+  status: MonitorStatus;
+  startTime: number;
+  endTime?: number;
+  exitCode?: number;
+  outputLines: string[];
+  lastOutput?: string;
+  error?: string;
+}
+
+type MonitorListener = (entries: MonitorEntry[]) => void;
+
+/**
+ * Creates a monitor notification XML tag for internal LLM communication.
+ * These tags are filtered out of the UI but visible to the agent.
+ */
+function createMonitorNotification(
+  monitorId: string,
+  type: "output" | "completed" | "error",
+  payload: string
+): string {
+  return `<monitor-notification>\n  <monitor-id>${monitorId}</monitor-id>\n  <type>${type}</type>\n  <payload>${escapeXml(payload)}</payload>\n</monitor-notification>`;
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Generate a unique monitor ID.
+ */
+function generateMonitorId(): string {
+  return `monitor-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+class MonitorRegistryImpl extends EventEmitter {
+  private monitors = new Map<string, MonitorEntry>();
+  private processes = new Map<string, ChildProcess>();
+
+  /**
+   * Launch a new background monitor.
+   * Returns the monitor ID.
+   */
+  launch(sessionId: string, command: string, description: string = ""): string {
+    const id = generateMonitorId();
+
+    const entry: MonitorEntry = {
+      id,
+      sessionId,
+      description: description || `Monitor: ${command.slice(0, 40)}${command.length > 40 ? "…" : ""}`,
+      command,
+      status: "running",
+      startTime: Date.now(),
+      outputLines: [],
+    };
+
+    this.monitors.set(id, entry);
+    this.emit("change", this.getAll());
+
+    // Spawn the background process
+    const child = spawn("bash", ["-c", command], {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false, // Keep in same process group so we can kill it
+    });
+
+    this.processes.set(id, child);
+
+    let stderrBuffer = "";
+
+    // Capture stdout line by line
+    child.stdout?.on("data", (chunk: Buffer) => {
+      const lines = chunk.toString().split("\n");
+      for (const line of lines) {
+        if (!line && lines.length === 1) continue; // Skip empty lines from partial chunks
+        const trimmed = line.trimEnd();
+        if (!trimmed) continue;
+
+        const monitor = this.monitors.get(id);
+        if (monitor) {
+          monitor.outputLines.push(trimmed);
+          monitor.lastOutput = trimmed;
+        }
+
+        const notification = createMonitorNotification(id, "output", trimmed);
+        this.notifyParent(notification);
+        this.emit("change", this.getAll());
+      }
+    });
+
+    // Capture stderr
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuffer += chunk.toString();
+    });
+
+    // Handle process exit
+    child.on("close", (code: number | null) => {
+      this.processes.delete(id);
+
+      const monitor = this.monitors.get(id);
+      if (!monitor) return;
+
+      if (stderrBuffer.trim()) {
+        monitor.error = stderrBuffer.trim();
+        const notification = createMonitorNotification(id, "error", stderrBuffer.trim());
+        this.notifyParent(notification);
+      }
+
+      if (monitor.status === "running") {
+        monitor.status = code === 0 ? "completed" : "error";
+        monitor.exitCode = code ?? undefined;
+        monitor.endTime = Date.now();
+
+        const notification = createMonitorNotification(
+          id,
+          "completed",
+          `Exited with code ${code ?? "unknown"}`
+        );
+        this.notifyParent(notification);
+      }
+
+      this.emit("change", this.getAll());
+    });
+
+    child.on("error", (err: Error) => {
+      this.processes.delete(id);
+
+      const monitor = this.monitors.get(id);
+      if (monitor) {
+        monitor.status = "error";
+        monitor.error = err.message;
+        monitor.endTime = Date.now();
+
+        const notification = createMonitorNotification(id, "error", err.message);
+        this.notifyParent(notification);
+      }
+
+      this.emit("change", this.getAll());
+    });
+
+    return id;
+  }
+
+  /**
+   * Cancel a running monitor by killing its process.
+   * Returns true if the monitor was found and killed.
+   */
+  kill(id: string): boolean {
+    const child = this.processes.get(id);
+    if (!child) return false;
+
+    try {
+      // Kill the process group to ensure child processes are also terminated
+      process.kill(child.pid!, "SIGTERM");
+
+      // Give it a moment to clean up gracefully
+      setTimeout(() => {
+        const monitor = this.monitors.get(id);
+        if (monitor && monitor.status === "running") {
+          try {
+            process.kill(child.pid!, 0); // Check if still alive
+          } catch {
+            // Process already dead, already handled by 'close' event
+            return;
+          }
+          // Force kill if still alive
+          try {
+            process.kill(child.pid!, "SIGKILL");
+          } catch {
+            // ignore
+          }
+        }
+      }, 500);
+    } catch {
+      // Process might have already exited
+    }
+
+    const monitor = this.monitors.get(id);
+    if (monitor) {
+      monitor.status = "killed";
+      monitor.endTime = Date.now();
+      this.emit("change", this.getAll());
+    }
+
+    return true;
+  }
+
+  /**
+   * Get a single monitor entry by ID.
+   */
+  get(id: string): MonitorEntry | undefined {
+    return this.monitors.get(id);
+  }
+
+  /**
+   * Get all monitor entries.
+   */
+  getAll(): MonitorEntry[] {
+    return Array.from(this.monitors.values());
+  }
+
+  /**
+   * Get monitor entries for a specific session.
+   */
+  getBySession(sessionId: string): MonitorEntry[] {
+    return this.getAll().filter((m) => m.sessionId === sessionId);
+  }
+
+  /**
+   * Get only running monitors.
+   */
+  getRunning(): MonitorEntry[] {
+    return this.getAll().filter((m) => m.status === "running");
+  }
+
+  /**
+   * Get only running monitors for a specific session.
+   */
+  getRunningBySession(sessionId: string): MonitorEntry[] {
+    return this.getBySession(sessionId).filter((m) => m.status === "running");
+  }
+
+  /**
+   * Subscribe to monitor registry changes.
+   */
+  subscribe(listener: MonitorListener): () => void {
+    this.on("change", listener);
+    return () => this.off("change", listener);
+  }
+
+  /**
+   * Remove a monitor from the registry.
+   * Does not kill the process if it's still running.
+   */
+  remove(id: string): boolean {
+    const existed = this.monitors.has(id);
+    this.monitors.delete(id);
+    if (existed) this.emit("change", this.getAll());
+    return existed;
+  }
+
+  /**
+   * Clear all monitors.
+   */
+  clear(): void {
+    for (const [id, child] of this.processes) {
+      try {
+        process.kill(child.pid!, "SIGTERM");
+      } catch {
+        // ignore
+      }
+      this.monitors.delete(id);
+    }
+    this.processes.clear();
+    this.monitors.clear();
+    this.emit("change", this.getAll());
+  }
+
+  /**
+   * Notify the parent agent session of a monitor event.
+   * Uses steer() if the agent is busy, prompt() if idle.
+   */
+  private notifyParent(notification: string): void {
+    const parent = activeSessionRef.current;
+    if (!parent) {
+      console.warn("[MonitorRegistry] No active session to notify");
+      return;
+    }
+
+    if (parent.isStreaming) {
+      parent.steer(notification).catch(() => {
+        // Silently ignore if the parent session is no longer available
+      });
+    } else {
+      parent.prompt(notification).catch(() => {
+        // Silently ignore if the parent session is no longer available
+      });
+    }
+  }
+}
+
+// Global singleton
+export const monitorRegistry = new MonitorRegistryImpl();

package/src/agent/permission-ui.ts

@@ -0,0 +1,71 @@
+/**
+ * Permission UI Bridge
+ *
+ * Provides a decoupled way for tool execute() functions to request
+ * user confirmation via the TUI layer without depending on ExtensionContext.
+ *
+ * Usage:
+ *   const result = await requestPermission({ toolName: "bash", args: { command: "rm -rf /" } });
+ *   // result is true if user allowed, false if denied
+ */
+
+export interface PermissionRequest {
+  id: string;
+  toolName: string;
+  args: unknown;
+  reason: string;
+  resolve: (allowed: boolean) => void;
+}
+
+let queue: PermissionRequest[] = [];
+let listeners: (() => void)[] = [];
+let yoloMode = false;
+
+export function isYoloMode(): boolean {
+  return yoloMode;
+}
+
+export function setYoloMode(enabled: boolean): void {
+  yoloMode = enabled;
+}
+
+function emit() {
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export function subscribePermissions(listener: () => void): () => void {
+  listeners.push(listener);
+  return () => {
+    listeners = listeners.filter((l) => l !== listener);
+  };
+}
+
+export function getPermissionQueue(): PermissionRequest[] {
+  return queue;
+}
+
+export function resolvePermission(id: string, allowed: boolean): void {
+  const request = queue.find((r) => r.id === id);
+  if (!request) return;
+  queue = queue.filter((r) => r.id !== id);
+  request.resolve(allowed);
+  emit();
+}
+
+export function requestPermission(params: {
+  toolName: string;
+  args: unknown;
+  reason: string;
+}): Promise<boolean> {
+  return new Promise((resolve) => {
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    queue.push({ id, toolName: params.toolName, args: params.args, reason: params.reason, resolve });
+    emit();
+  });
+}

package/src/agent/plan-ui.ts

@@ -0,0 +1,74 @@
+/**
+ * Plan Approval UI Bridge
+ *
+ * Decoupled way for the exitPlanMode tool to submit a plan for user approval
+ * via the TUI layer without depending on React context.
+ *
+ * Pattern mirrors permission-ui.ts.
+ */
+
+export interface PlanApprovalResult {
+  approved: boolean;
+  comment?: string;
+}
+
+export interface PlanApprovalRequest {
+  id: string;
+  plan: string;
+  resolve: (result: PlanApprovalResult) => void;
+}
+
+let queue: PlanApprovalRequest[] = [];
+let listeners: (() => void)[] = [];
+let currentPlanText = "";
+
+function emit() {
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export function subscribePlanApprovals(listener: () => void): () => void {
+  listeners.push(listener);
+  return () => {
+    listeners = listeners.filter((l) => l !== listener);
+  };
+}
+
+export function getPlanApprovalQueue(): PlanApprovalRequest[] {
+  return queue;
+}
+
+export function getCurrentPlanText(): string {
+  return currentPlanText;
+}
+
+export function setCurrentPlanText(text: string): void {
+  currentPlanText = text;
+}
+
+export function resolvePlanApproval(id: string, result: PlanApprovalResult): void {
+  const request = queue.find((r) => r.id === id);
+  if (!request) return;
+  queue = queue.filter((r) => r.id !== id);
+  request.resolve(result);
+  if (!result.approved) {
+    currentPlanText = "";
+  }
+  emit();
+}
+
+export function submitPlanForApproval(params: {
+  plan: string;
+}): Promise<PlanApprovalResult> {
+  return new Promise((resolve) => {
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    currentPlanText = params.plan;
+    queue.push({ id, plan: params.plan, resolve });
+    emit();
+  });
+}

package/src/agent/question-ui.ts

@@ -0,0 +1,58 @@
+/**
+ * Question UI Bridge
+ *
+ * Decoupled way for the askUserQuestion tool to request user input
+ * via the TUI layer without depending on React context.
+ *
+ * Pattern mirrors permission-ui.ts.
+ */
+
+export interface QuestionRequest {
+  id: string;
+  question: string;
+  options: string[];
+  resolve: (answer: string) => void;
+}
+
+let queue: QuestionRequest[] = [];
+let listeners: (() => void)[] = [];
+
+function emit() {
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+export function subscribeQuestions(listener: () => void): () => void {
+  listeners.push(listener);
+  return () => {
+    listeners = listeners.filter((l) => l !== listener);
+  };
+}
+
+export function getQuestionQueue(): QuestionRequest[] {
+  return queue;
+}
+
+export function resolveQuestion(id: string, answer: string): void {
+  const request = queue.find((r) => r.id === id);
+  if (!request) return;
+  queue = queue.filter((r) => r.id !== id);
+  request.resolve(answer);
+  emit();
+}
+
+export function askUserQuestion(params: {
+  question: string;
+  options: string[];
+}): Promise<string> {
+  return new Promise((resolve) => {
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    queue.push({ id, question: params.question, options: params.options, resolve });
+    emit();
+  });
+}