@meowlynxsea/koi 0.1.0

package/src/agent/session-tasks.ts

@@ -0,0 +1,305 @@
+/**
+ * Session Task Manager
+ *
+ * Replaces the global in-memory task Map with per-session isolated storage.
+ * Each session's tasks are persisted to ~/.config/koi/sessions/<id>/tasks.json.
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { randomUUID } from "crypto";
+
+const CONFIG_DIR = path.join(os.homedir(), ".config", "koi");
+const KOI_SESSIONS_DIR = path.join(CONFIG_DIR, "sessions");
+
+type TaskStatus = "pending" | "in_progress" | "completed";
+type TaskPriority = "high" | "medium" | "low";
+
+export interface Task {
+  id: string;
+  content: string;
+  status: TaskStatus;
+  priority: TaskPriority;
+  blockedBy: string[];
+  blocks: string[];
+  createdAt: number;
+  updatedAt: number;
+  /** Fork source task ID (null for original tasks) */
+  forkedFrom: string | null;
+  /** Timestamp when this task was forked */
+  forkedAt: number | null;
+}
+
+/**
+ * File System Helpers
+ *
+ * All fs operations are wrapped with silent error handling so a corrupted tasks.json
+ * or missing directory never crashes the agent loop.
+ */
+
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+}
+
+function getTasksPath(sessionId: string): string {
+  return path.join(KOI_SESSIONS_DIR, sessionId, "tasks.json");
+}
+
+function safeReadTasks(filePath: string): Task[] | null {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw) as Task[];
+  } catch {
+    return null;
+  }
+}
+
+function safeWriteTasks(filePath: string, tasks: Task[]): void {
+  try {
+    ensureDir(path.dirname(filePath));
+    fs.writeFileSync(filePath, JSON.stringify(tasks, null, 2) + "\n", { mode: 0o600 });
+  } catch {
+    // Silently ignore write errors
+  }
+}
+
+function safeDeleteFile(filePath: string): void {
+  try {
+    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Task Update Helpers
+ *
+ * updateStringArray applies add/remove delta operations on id arrays (blockedBy, blocks)
+ * without mutating the original reference until the final assignment.
+ */
+
+function updateStringArray(current: string[], add?: string[], remove?: string[]): string[] {
+  let result = [...current];
+  if (add) {
+    for (const id of add) {
+      if (!result.includes(id)) result.push(id);
+    }
+  }
+  if (remove) {
+    result = result.filter((id) => !remove.includes(id));
+  }
+  return result;
+}
+
+function applyTaskUpdates(
+  task: Task,
+  updates: Partial<Pick<Task, "content" | "status" | "priority">> & {
+    addBlockedBy?: string[];
+    removeBlockedBy?: string[];
+    addBlocks?: string[];
+    removeBlocks?: string[];
+  }
+): void {
+  if (updates.content !== undefined) task.content = updates.content;
+  if (updates.status !== undefined) task.status = updates.status;
+  if (updates.priority !== undefined) task.priority = updates.priority;
+
+  task.blockedBy = updateStringArray(task.blockedBy, updates.addBlockedBy, updates.removeBlockedBy);
+  task.blocks = updateStringArray(task.blocks, updates.addBlocks, updates.removeBlocks);
+}
+
+/**
+ * SessionTaskManager
+ *
+ * Per-session in-memory task storage with JSON persistence.
+ * When no session is active, tasks land in a transient "__transient__" store
+ * so the API surface never returns undefined/null unexpectedly.
+ */
+
+export class SessionTaskManager {
+  private stores = new Map<string, Map<string, Task>>();
+  private activeSessionId: string | null = null;
+
+  setActiveSession(sessionId: string): void {
+    this.activeSessionId = sessionId;
+    if (!this.stores.has(sessionId)) {
+      this.load(sessionId);
+    }
+  }
+
+  getCurrentSessionId(): string | null {
+    return this.activeSessionId;
+  }
+
+  private getStore(): Map<string, Task> {
+    if (!this.activeSessionId) {
+      const transientId = "__transient__";
+      if (!this.stores.has(transientId)) {
+        this.stores.set(transientId, new Map());
+      }
+      return this.stores.get(transientId)!;
+    }
+    if (!this.stores.has(this.activeSessionId)) {
+      this.stores.set(this.activeSessionId, new Map());
+    }
+    return this.stores.get(this.activeSessionId)!;
+  }
+
+  generateTaskId(): string {
+    return `task-${randomUUID()}`;
+  }
+
+  createTask(
+    content: string,
+    priority: TaskPriority = "medium",
+    blockedBy: string[] = [],
+    blocks: string[] = []
+  ): Task {
+    const id = this.generateTaskId();
+    const now = Date.now();
+    const task: Task = {
+      id,
+      content,
+      status: "pending",
+      priority,
+      blockedBy: [...blockedBy],
+      blocks: [...blocks],
+      createdAt: now,
+      updatedAt: now,
+      forkedFrom: null,
+      forkedAt: null,
+    };
+    this.getStore().set(id, task);
+    this.saveActive();
+    return task;
+  }
+
+  getTask(taskId: string): Task | undefined {
+    return this.getStore().get(taskId);
+  }
+
+  listTasks(status?: TaskStatus): Task[] {
+    let all = Array.from(this.getStore().values());
+    if (status) {
+      all = all.filter((t) => t.status === status);
+    }
+    const statusOrder = { in_progress: 0, pending: 1, completed: 2 };
+    const priorityOrder = { high: 0, medium: 1, low: 2 };
+    all.sort((a, b) => {
+      const s = statusOrder[a.status] - statusOrder[b.status];
+      if (s !== 0) return s;
+      return priorityOrder[a.priority] - priorityOrder[b.priority];
+    });
+    return all;
+  }
+
+  updateTask(
+    taskId: string,
+    updates: Parameters<typeof applyTaskUpdates>[1]
+  ): Task | null {
+    const task = this.getStore().get(taskId);
+    if (!task) return null;
+
+    applyTaskUpdates(task, updates);
+    task.updatedAt = Date.now();
+    this.saveActive();
+    return task;
+  }
+
+  deleteTask(taskId: string): boolean {
+    const ok = this.getStore().delete(taskId);
+    if (ok) this.saveActive();
+    return ok;
+  }
+
+  /**
+   * Replace all tasks in the active session store.
+   * Used when restoring from a snapshot.
+   */
+  setTasks(tasks: Task[]): void {
+    const store = this.getStore();
+    store.clear();
+    for (const task of tasks) {
+      store.set(task.id, task);
+    }
+    this.saveActive();
+  }
+
+  load(sessionId: string): void {
+    const tasksArray = safeReadTasks(getTasksPath(sessionId));
+    if (!tasksArray) {
+      this.stores.set(sessionId, new Map());
+      return;
+    }
+    const map = new Map<string, Task>();
+    for (const t of tasksArray) {
+      map.set(t.id, t);
+    }
+    this.stores.set(sessionId, map);
+  }
+
+  save(sessionId: string): void {
+    const store = this.stores.get(sessionId);
+    if (!store) return;
+    safeWriteTasks(getTasksPath(sessionId), Array.from(store.values()));
+  }
+
+  saveActive(): void {
+    if (this.activeSessionId) {
+      this.save(this.activeSessionId);
+    }
+  }
+
+  clearSession(sessionId: string): void {
+    this.stores.delete(sessionId);
+    safeDeleteFile(getTasksPath(sessionId));
+  }
+
+  /**
+   * Fork all tasks for a new session.
+   * Creates new task IDs and sets fork metadata to track the fork relationship.
+   * Returns a map of old task IDs to new task IDs for updating blockedBy/blocks references.
+   */
+  forkTasks(): Map<string, string> {
+    const currentStore = this.getStore();
+    const oldToNewIdMap = new Map<string, string>();
+    const now = Date.now();
+
+    // Collect existing tasks before mutating the store
+    const existingTasks = Array.from(currentStore.values());
+
+    // First pass: create new IDs
+    for (const task of existingTasks) {
+      oldToNewIdMap.set(task.id, this.generateTaskId());
+    }
+
+    // Clear the store so only forked tasks remain
+    currentStore.clear();
+
+    // Second pass: create forked tasks with updated references
+    for (const task of existingTasks) {
+      const newId = oldToNewIdMap.get(task.id)!;
+      const forkedTask: Task = {
+        ...task,
+        id: newId,
+        forkedFrom: task.id,
+        forkedAt: now,
+        // Update blockedBy references to new IDs
+        blockedBy: task.blockedBy.map(id => oldToNewIdMap.get(id) ?? id),
+        // Update blocks references to new IDs
+        blocks: task.blocks.map(id => oldToNewIdMap.get(id) ?? id),
+      };
+      currentStore.set(newId, forkedTask);
+    }
+
+    this.saveActive();
+    return oldToNewIdMap;
+  }
+}
+
+// Global singleton instance
+export const globalTaskManager = new SessionTaskManager();

package/src/agent/session.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent Session Utilities
+ *
+ * Helper functions for agent session management.
+ */
+
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Refresh MCP tools in the agent session.
+ * Call this after MCP connections change (connect/disconnect).
+ */
+export async function refreshMcpTools(session: AgentSession | null): Promise<void> {
+  if (!session) return;
+
+  // Re-initialize MCP connections
+  const { disconnectAllMcpServers, initializeMcpConnections } = await import("../services/mcp/index.js");
+  await disconnectAllMcpServers();
+  await initializeMcpConnections();
+
+  // Get current mode and update active tools
+  const { getAgentMode, getActiveToolNamesForMode } = await import("./mode.js");
+  const mode = getAgentMode();
+  const activeTools = getActiveToolNamesForMode(mode);
+
+  session.setActiveToolsByName(activeTools);
+}

package/src/agent/subagent-registry.ts

@@ -0,0 +1,176 @@
+/**
+ * Async Subagent Registry
+ *
+ * Manages background (fire-and-forget) subagents. Each async agent gets a
+ * unique ID, runs in the background, and notifies the parent session via
+ * followUp() when it completes.
+ */
+
+import type { Agent } from "@mariozechner/pi-agent-core";
+import { activeSessionRef } from "./hooks.js";
+import { runSubagent, type SubagentConfig } from "./subagent.js";
+
+export interface AsyncSubagentEntry {
+  id: string;
+  description: string;
+  status: "running" | "completed" | "failed" | "killed";
+  result?: string;
+  error?: string;
+  startTime: number;
+  endTime?: number;
+}
+
+class SubagentRegistry {
+  private entries = new Map<string, AsyncSubagentEntry>();
+  private runningAgents = new Map<string, Agent>();
+  private listeners: (() => void)[] = [];
+
+  private emit() {
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener);
+    };
+  }
+
+  get(id: string): AsyncSubagentEntry | undefined {
+    return this.entries.get(id);
+  }
+
+  getAll(): AsyncSubagentEntry[] {
+    return Array.from(this.entries.values()).sort(
+      (a, b) => b.startTime - a.startTime
+    );
+  }
+
+  /**
+   * Launch a subagent in the background and return its ID immediately.
+   */
+  async launch(config: SubagentConfig): Promise<string> {
+    const id = `agent-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+
+    const entry: AsyncSubagentEntry = {
+      id,
+      description: config.description,
+      status: "running",
+      startTime: Date.now(),
+    };
+    this.entries.set(id, entry);
+
+    // Fire-and-forget — do not await
+    void this.runInBackground(id, config);
+    this.emit();
+
+    return id;
+  }
+
+  private async runInBackground(
+    id: string,
+    config: SubagentConfig
+  ): Promise<void> {
+    const entry = this.entries.get(id);
+    if (!entry) return;
+
+    let agentRef: Agent | undefined;
+
+    try {
+      const result = await runSubagent(config, (agent) => {
+        agentRef = agent;
+        this.runningAgents.set(id, agent);
+      });
+      entry.status = "completed";
+      entry.result = result;
+      entry.endTime = Date.now();
+      this.emit();
+      this.notifyParent(id, "completed", result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      // If the agent was explicitly killed, override status
+      if (entry.status === "killed") {
+        entry.error = message;
+        entry.endTime = Date.now();
+        this.emit();
+        this.notifyParent(id, "killed", message);
+      } else {
+        entry.status = "failed";
+        entry.error = message;
+        entry.endTime = Date.now();
+        this.emit();
+        this.notifyParent(id, "failed", message);
+      }
+    } finally {
+      if (agentRef) {
+        this.runningAgents.delete(id);
+      }
+    }
+  }
+
+  private notifyParent(
+    agentId: string,
+    status: string,
+    summary: string
+  ): void {
+    const parent = activeSessionRef.current;
+    if (!parent) return;
+
+    const truncated =
+      summary.length > 500 ? summary.slice(0, 500) + "..." : summary;
+    const notification = [
+      `<task-notification>`,
+      `  <task-id>${agentId}</task-id>`,
+      `  <status>${status}</status>`,
+      `  <summary>${truncated}</summary>`,
+      `</task-notification>`,
+    ].join("\n");
+
+    // If the parent is still running, inject as steer so it gets processed
+    // at the end of the current turn. If idle, prompt immediately to trigger
+    // a new run right away.
+    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
+      });
+    }
+  }
+
+  /**
+   * Abort a running async subagent by ID.
+   * Returns true if the agent was found and aborted.
+   */
+  kill(id: string): boolean {
+    const agent = this.runningAgents.get(id);
+    if (!agent) {
+      // Agent may have finished already; mark as killed if still running in
+      // our record.
+      const entry = this.entries.get(id);
+      if (entry && entry.status === "running") {
+        entry.status = "killed";
+        entry.endTime = Date.now();
+        return true;
+      }
+      return false;
+    }
+    const entry = this.entries.get(id);
+    if (entry) {
+      entry.status = "killed";
+    }
+    agent.abort();
+    return true;
+  }
+}
+
+/** Global singleton registry for async subagents. */
+export const subagentRegistry = new SubagentRegistry();

package/src/agent/subagent.ts

@@ -0,0 +1,194 @@
+/**
+ * Subagent Runner
+ *
+ * Creates a lightweight child Agent by directly instantiating pi-agent-core's Agent
+ * class, copying the parent session's runtime config (streamFn, getApiKey, model,
+ * systemPrompt) but with an isolated message history and filtered tool set.
+ */
+
+import { Agent } from "@mariozechner/pi-agent-core";
+import type { AgentMessage, AgentTool } from "@mariozechner/pi-agent-core";
+import type { UserMessage, AssistantMessage } from "@mariozechner/pi-ai";
+import { activeSessionRef } from "./hooks.js";
+
+export type SubagentType = "explore" | "plan";
+
+export interface SubagentConfig {
+  description: string;
+  prompt: string;
+  subagentType?: SubagentType;
+  runInBackground?: boolean;
+  maxTurns?: number;
+}
+
+const DEFAULT_MAX_TURNS = 50;
+
+/** Tools that no subagent should ever see. */
+const DISALLOWED_TOOLS = new Set([
+  "agent",
+  "askUserQuestion",
+  "exitPlanMode",
+]);
+
+/** Read-only tool set for explore agents. */
+const READONLY_TOOL_NAMES = new Set([
+  "read",
+  "grep",
+  "glob",
+  "ls",
+  "webfetch",
+  "taskGet",
+  "taskList",
+]);
+
+/** Planning tool set for plan agents. */
+const PLAN_TOOL_NAMES = new Set([
+  "read",
+  "grep",
+  "glob",
+  "ls",
+  "webfetch",
+  "taskGet",
+  "taskList",
+  "taskCreate",
+  "taskUpdate",
+  "enterPlanMode",
+]);
+
+function filterTools(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parentTools: AgentTool<any>[],
+  subagentType?: SubagentType
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): AgentTool<any>[] {
+  let allowedNames: Set<string> | null = null;
+  if (subagentType === "explore") {
+    allowedNames = READONLY_TOOL_NAMES;
+  } else if (subagentType === "plan") {
+    allowedNames = PLAN_TOOL_NAMES;
+  }
+
+  return parentTools.filter((tool) => {
+    if (DISALLOWED_TOOLS.has(tool.name)) return false;
+    if (allowedNames && !allowedNames.has(tool.name)) return false;
+    return true;
+  });
+}
+
+function buildSystemPrompt(
+  parentSystemPrompt: string,
+  subagentType?: SubagentType
+): string {
+  if (subagentType === "explore") {
+    return (
+      parentSystemPrompt +
+      "\n\n[SUBAGENT MODE: Explore]\n" +
+      "You are a read-only exploration subagent. " +
+      "You cannot modify files or execute shell commands. " +
+      "Your sole purpose is to gather information and report findings concisely."
+    );
+  }
+  if (subagentType === "plan") {
+    return (
+      parentSystemPrompt +
+      "\n\n[SUBAGENT MODE: Plan]\n" +
+      "You are a planning subagent. " +
+      "You can use read-only tools and task management tools to research and formulate plans. " +
+      "You cannot modify files or execute shell commands. " +
+      "Your output should be a detailed, actionable step-by-step plan."
+    );
+  }
+  return parentSystemPrompt;
+}
+
+function extractResult(messages: AgentMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (
+      msg &&
+      typeof msg === "object" &&
+      "role" in msg &&
+      msg.role === "assistant"
+    ) {
+      const assistant = msg as AssistantMessage;
+      let text = "";
+      for (const block of assistant.content) {
+        if (block.type === "text") {
+          text += block.text;
+        }
+      }
+      return text.trim() || "[Agent completed with no text output]";
+    }
+  }
+  return "[Agent completed with no assistant message]";
+}
+
+/**
+ * Run a subagent synchronously and return its final text output.
+ *
+ * @param onAgentCreated Optional callback invoked immediately after the Agent
+ *   instance is created. Used by the async registry to hold a reference for
+ *   abort/kill operations.
+ */
+export async function runSubagent(
+  config: SubagentConfig,
+  onAgentCreated?: (agent: Agent) => void
+): Promise<string> {
+  const parentSession = activeSessionRef.current;
+  if (!parentSession) {
+    throw new Error("No active session available to spawn subagent");
+  }
+
+  const parentAgent = parentSession.agent;
+  const parentState = parentSession.state;
+
+  const tools = filterTools(parentState.tools, config.subagentType);
+  const systemPrompt = buildSystemPrompt(
+    parentState.systemPrompt,
+    config.subagentType
+  );
+
+  const userMessage: UserMessage = {
+    role: "user",
+    content: config.prompt,
+    timestamp: Date.now(),
+  };
+
+  const agent = new Agent({
+    streamFn: parentAgent.streamFn,
+    getApiKey: parentAgent.getApiKey,
+    convertToLlm: parentAgent.convertToLlm,
+    transformContext: parentAgent.transformContext,
+    thinkingBudgets: parentAgent.thinkingBudgets,
+    transport: parentAgent.transport,
+    toolExecution: parentAgent.toolExecution,
+    maxRetryDelayMs: parentAgent.maxRetryDelayMs,
+    initialState: {
+      systemPrompt,
+      model: parentState.model,
+      thinkingLevel: parentState.thinkingLevel,
+      tools,
+    },
+  });
+
+  onAgentCreated?.(agent);
+
+  let turnCount = 0;
+  const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+  const unsubscribe = agent.subscribe((event, _signal) => {
+    if (event.type === "turn_start") {
+      turnCount++;
+      if (turnCount > maxTurns) {
+        agent.abort();
+      }
+    }
+  });
+
+  try {
+    await agent.prompt(userMessage);
+    await agent.waitForIdle();
+    return extractResult(agent.state.messages);
+  } finally {
+    unsubscribe();
+  }
+}