@meowlynxsea/koi 0.1.0

package/src/tools/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Koi Custom Tool Registry
+ *
+ * Re-implements Pi's built-in tools with custom orchestration and permission checks.
+ * All tools are registered via createAgentSession({ customTools, noTools: 'builtin' }).
+ */
+
+import type { SessionTaskManager } from "../agent/session-tasks.js";
+import { createReadToolDefinition } from "./read.js";
+import { createGrepToolDefinition } from "./grep.js";
+import { createGlobToolDefinition } from "./glob.js";
+import { createLsToolDefinition } from "./ls.js";
+import { createBashToolDefinition } from "./bash.js";
+import { createEditToolDefinition } from "./edit.js";
+import { createWriteToolDefinition } from "./write.js";
+import { createWebFetchToolDefinition } from "./webfetch.js";
+import { createAskUserQuestionToolDefinition } from "./ask-user-question.js";
+import {
+  createEnterPlanModeToolDefinition,
+  createExitPlanModeToolDefinition,
+} from "./plan-mode.js";
+import { createAgentToolDefinition } from "./agent.js";
+import {
+  createTaskCreateToolDefinition,
+  createTaskGetToolDefinition,
+  createTaskListToolDefinition,
+  createTaskUpdateToolDefinition,
+} from "./task.js";
+import {
+  createMonitorToolDefinition,
+  createCancelMonitorToolDefinition,
+} from "./monitor.js";
+import { createSkillToolDefinition } from "./skill.js";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+
+export function createCodingToolDefinitions(
+  _cwd: string,
+  taskManager: SessionTaskManager
+): ToolDefinition[] {
+  return [
+    createReadToolDefinition(_cwd),
+    createGrepToolDefinition(_cwd),
+    createGlobToolDefinition(_cwd),
+    createLsToolDefinition(_cwd),
+    createBashToolDefinition(_cwd),
+    createEditToolDefinition(_cwd),
+    createWriteToolDefinition(_cwd),
+    createWebFetchToolDefinition(_cwd),
+    createAskUserQuestionToolDefinition(),
+    createEnterPlanModeToolDefinition(),
+    createExitPlanModeToolDefinition(),
+    createAgentToolDefinition(),
+    createTaskCreateToolDefinition(_cwd, taskManager),
+    createTaskGetToolDefinition(_cwd, taskManager),
+    createTaskListToolDefinition(_cwd, taskManager),
+    createTaskUpdateToolDefinition(_cwd, taskManager),
+    createMonitorToolDefinition(),
+    createCancelMonitorToolDefinition(),
+    createSkillToolDefinition(),
+  ] as ToolDefinition[];
+}
+
+export function createReadOnlyToolDefinitions(_cwd: string): ToolDefinition[] {
+  return [
+    createReadToolDefinition(_cwd),
+    createGrepToolDefinition(_cwd),
+    createGlobToolDefinition(_cwd),
+    createLsToolDefinition(_cwd),
+    createWebFetchToolDefinition(_cwd),
+  ] as ToolDefinition[];
+}
+
+export * from "./types.js";

package/src/tools/list-mcp-resources.ts

@@ -0,0 +1,74 @@
+/**
+ * List MCP Resources Tool
+ *
+ * Lists all available resources from connected MCP servers.
+ */
+
+import { getAllMcpResources } from "../services/mcp/index.js";
+
+export interface ListMcpResourcesResult {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}
+
+export interface ListMcpResourcesArgs {
+  server?: string;
+}
+
+export async function listMcpResources(args: ListMcpResourcesArgs): Promise<ListMcpResourcesResult> {
+  try {
+    const allResources = getAllMcpResources();
+    let resources = allResources;
+
+    // Filter by server if specified
+    if (args.server) {
+      resources = allResources.filter((r) => r.server === args.server);
+    }
+
+    if (resources.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: args.server
+              ? `No resources found on MCP server '${args.server}'`
+              : "No MCP resources available from any connected server",
+          },
+        ],
+      };
+    }
+
+    // Group resources by server
+    const byServer = new Map<string, typeof resources>();
+    for (const resource of resources) {
+      const existing = byServer.get(resource.server) ?? [];
+      existing.push(resource);
+      byServer.set(resource.server, existing);
+    }
+
+    const lines: string[] = [];
+    lines.push(`# MCP Resources (${resources.length} total)\n`);
+
+    for (const [serverName, serverResources] of byServer) {
+      lines.push(`## ${serverName} (${serverResources.length} resources)`);
+      for (const resource of serverResources) {
+        const name = resource.name ?? resource.uri;
+        const desc = resource.description
+          ? `\n   ${resource.description}`
+          : "";
+        const mime = resource.mimeType ? ` [${resource.mimeType}]` : "";
+        lines.push(`- \`${name}\`${mime}${desc}`);
+      }
+      lines.push("");
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error listing MCP resources: ${errorMessage}` }],
+      isError: true,
+    };
+  }
+}

package/src/tools/ls.ts

@@ -0,0 +1,85 @@
+/**
+ * LsTool — Directory listing
+ *
+ * Lists files and directories with basic metadata.
+ */
+
+import { Type } from "typebox";
+import { readdirSync, statSync, existsSync } from "fs";
+import { resolve } from "path";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { checkPermission } from "../agent/check-permissions.js";
+import { requestPermission } from "../agent/permission-ui.js";
+import type { ToolResultWithError } from "./types.js";
+
+export const lsSchema = Type.Object({
+  path: Type.Optional(Type.String({ description: "Directory to list (default: current directory)" })),
+});
+
+export type LsToolInput = {
+  path?: string;
+};
+
+export async function executeLs(params: LsToolInput): Promise<{ content: TextContent[]; details: { entryCount: number } }> {
+  const dirPath = params.path ? resolve(params.path) : process.cwd();
+
+  if (!existsSync(dirPath)) {
+    throw new Error(`Directory not found: ${params.path ?? "."}`);
+  }
+
+  const entries = readdirSync(dirPath);
+  const lines: string[] = [];
+
+  for (const name of entries) {
+    const full = resolve(dirPath, name);
+    try {
+      const s = statSync(full);
+      const type = s.isDirectory() ? "d" : s.isFile() ? "f" : "?";
+      const size = s.isFile() ? String(s.size) : "-";
+      lines.push(`${type}\t${size}\t${name}`);
+    } catch {
+      lines.push(`?\t-\t${name}`);
+    }
+  }
+
+  const text = lines.length ? lines.join("\n") : "(empty directory)";
+  return {
+    content: [{ type: "text", text }],
+    details: { entryCount: lines.length },
+  };
+}
+
+export function createLsToolDefinition(_cwd: string): ToolDefinition<typeof lsSchema, { entryCount: number }> {
+  return {
+    name: "ls",
+    label: "Ls",
+    description: "List files and directories in a given path.",
+    promptSnippet: "Ls: list directory contents",
+    parameters: lsSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const perm = checkPermission("ls", params);
+      if (perm.decision === "deny") {
+        const result: ToolResultWithError<{ entryCount: number }> = {
+          content: [{ type: "text", text: `Permission denied: ${perm.reason ?? "ls operation blocked"}` }],
+          details: { entryCount: 0 },
+          isError: true,
+        };
+        return result;
+      }
+      if (perm.decision === "ask") {
+        const allowed = await requestPermission({ toolName: "ls", args: params, reason: perm.reason ?? "Confirm directory listing" });
+        if (!allowed) {
+          const result: ToolResultWithError<{ entryCount: number }> = {
+            content: [{ type: "text", text: "User denied permission to list directory." }],
+            details: { entryCount: 0 },
+            isError: true,
+          };
+          return result;
+        }
+      }
+      return await executeLs(params);
+    },
+  };
+}

package/src/tools/mcp.ts

@@ -0,0 +1,76 @@
+/**
+ * MCP Tool Adapter
+ */
+
+import type { McpToolResult, SerializedTool } from "../services/mcp/types.js";
+import { getMcpConnection } from "../services/mcp/index.js";
+
+export interface KoiMcpTool {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  serverName: string;
+  originalToolName: string;
+}
+
+export function createMcpToolDefinition(tool: SerializedTool): KoiMcpTool {
+  const parts = tool.name.split("__");
+  if (parts.length !== 3 || parts[0] !== "mcp") {
+    throw new Error(`Invalid MCP tool name format: ${tool.name}`);
+  }
+
+  const serverName = parts[1] ?? "";
+  const originalToolName = parts[2] ?? "";
+
+  if (!originalToolName) throw new Error("Tool name is required");
+
+  return {
+    name: tool.name,
+    description: tool.description ?? `MCP tool from ${serverName}: ${originalToolName}`,
+    inputSchema: tool.inputSchema as Record<string, unknown> | undefined,
+    serverName,
+    originalToolName,
+  };
+}
+
+export async function executeMcpToolCall(toolName: string, args: Record<string, unknown>): Promise<McpToolResult> {
+  const parts = toolName.split("__");
+  if (parts.length !== 3 || parts[0] !== "mcp") {
+    return { success: false, error: `Invalid MCP tool name: ${toolName}`, isError: true };
+  }
+
+  const serverName = parts[1] ?? "";
+  const originalToolName = parts[2] ?? "";
+
+  if (!originalToolName) {
+    return { success: false, error: "Tool name is required", isError: true };
+  }
+
+  const connection = getMcpConnection(serverName);
+  if (!connection || connection.status !== "connected") {
+    return { success: false, error: `MCP server '${serverName}' is not connected`, isError: true };
+  }
+
+  try {
+    const result = await connection.client.callTool({ name: originalToolName, arguments: args });
+    return { success: true, content: result.content as Array<{ type: string; text?: string; [key: string]: unknown }> };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return { success: false, error: errorMessage, isError: true, content: [{ type: "text", text: errorMessage }] };
+  }
+}
+
+export function createMcpToolDefinitions(): KoiMcpTool[] {
+  const { getAllMcpTools } = require("../services/mcp/index.js") as { getAllMcpTools: () => SerializedTool[] };
+  const mcpTools = getAllMcpTools();
+  return mcpTools.map((tool: SerializedTool) => createMcpToolDefinition(tool));
+}
+
+export function formatMcpToolResult(result: McpToolResult): string {
+  if (!result.success) return `Error: ${result.error ?? "Unknown error"}`;
+  if (!result.content || result.content.length === 0) return "No content returned";
+  return result.content.map((block) => {
+    if (block.type === "text") return block.text ?? "";
+    return JSON.stringify(block);
+  }).join("\n");
+}

package/src/tools/monitor.ts

@@ -0,0 +1,159 @@
+/**
+ * Monitor Tool — Background Process Watcher
+ *
+ * Creates a background monitor that watches command output and notifies
+ * the main agent via steer() (when busy) or prompt() (when idle).
+ *
+ * Notifications are sent as internal XML tags filtered from UI but visible to LLM.
+ */
+
+import { Type } from "typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { TextContent } from "@mariozechner/pi-ai";
+import { checkPermission } from "../agent/check-permissions.js";
+import { requestPermission } from "../agent/permission-ui.js";
+import { monitorRegistry } from "../agent/monitor-registry.js";
+import { activeSessionRef } from "../agent/hooks.js";
+import type { ToolResultWithError } from "./types.js";
+
+// ─── CreateMonitor ────────────────────────────────────────────────────────────
+
+export const createMonitorSchema = Type.Object({
+  command: Type.String({
+    description:
+      "The bash command to run and monitor. " +
+      "The monitor will watch stdout/stderr and notify on each output line.",
+  }),
+  description: Type.Optional(
+    Type.String({
+      description: "Human-readable label for this monitor (shown in sidebar).",
+    })
+  ),
+});
+
+export type CreateMonitorInput = {
+  command: string;
+  description?: string;
+};
+
+// ─── CancelMonitor ────────────────────────────────────────────────────────────
+
+export const cancelMonitorSchema = Type.Object({
+  monitorId: Type.String({
+    description: "The ID of the monitor to cancel.",
+  }),
+});
+
+export type CancelMonitorInput = {
+  monitorId: string;
+};
+
+// ─── Tool Definitions ─────────────────────────────────────────────────────────
+
+export function createMonitorToolDefinition(): ToolDefinition<
+  typeof createMonitorSchema,
+  { monitorId: string }
+> {
+  return {
+    name: "CreateMonitor",
+    label: "CreateMonitor",
+    description:
+      "Start a background process monitor that watches command output. " +
+      "Each line of output is sent as a notification to the main agent. " +
+      "Use CancelMonitor to stop a running monitor. " +
+      "Useful for watching log files, CI/CD pipelines, long-running scripts, or directory changes.",
+    promptSnippet: "Monitor: watch background command output",
+    parameters: createMonitorSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params: CreateMonitorInput) {
+      // Permission check — same rules as bash
+      const perm = checkPermission("bash", { command: params.command });
+      if (perm.decision === "deny") {
+        const result: ToolResultWithError<{ monitorId: string }> = {
+          content: [
+            { type: "text", text: `Permission denied: ${perm.reason ?? "operation blocked"}` },
+          ],
+          details: { monitorId: "" },
+          isError: true,
+        };
+        return result;
+      }
+      if (perm.decision === "ask") {
+        const allowed = await requestPermission({
+          toolName: "bash",
+          args: { command: params.command },
+          reason: perm.reason ?? "Confirm background monitor command",
+        });
+        if (!allowed) {
+          const result: ToolResultWithError<{ monitorId: string }> = {
+            content: [{ type: "text", text: "User denied permission to start monitor." }],
+            details: { monitorId: "" },
+            isError: true,
+          };
+          return result;
+        }
+      }
+
+      const sessionId = activeSessionRef.current?.sessionId ?? "unknown";
+      const monitorId = monitorRegistry.launch(sessionId, params.command, params.description ?? "");
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Monitor started with ID: ${monitorId}\nCommand: ${params.command}`,
+          } satisfies TextContent,
+        ],
+        details: { monitorId },
+      };
+    },
+  };
+}
+
+export function createCancelMonitorToolDefinition(): ToolDefinition<
+  typeof cancelMonitorSchema,
+  { success: boolean; monitorId: string }
+> {
+  return {
+    name: "CancelMonitor",
+    label: "CancelMonitor",
+    description:
+      "Cancel a running background monitor. " +
+      "The monitored process will be terminated (SIGTERM, then SIGKILL).",
+    promptSnippet: "CancelMonitor: stop a background monitor",
+    parameters: cancelMonitorSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params: CancelMonitorInput) {
+      const existing = monitorRegistry.get(params.monitorId);
+      if (!existing) {
+        const result: ToolResultWithError<{ success: boolean; monitorId: string }> = {
+          content: [
+            {
+              type: "text",
+              text: `Monitor not found: ${params.monitorId}`,
+            } satisfies TextContent,
+          ],
+          details: { success: false, monitorId: params.monitorId },
+          isError: true,
+        };
+        return result;
+      }
+
+      const killed = monitorRegistry.kill(params.monitorId);
+
+      const content: TextContent[] = [
+        {
+          type: "text",
+          text: killed
+            ? `Monitor ${params.monitorId} cancelled.`
+            : `Monitor ${params.monitorId} could not be cancelled (process may have already exited).`,
+        },
+      ];
+
+      return {
+        content,
+        details: { success: killed, monitorId: params.monitorId },
+      };
+    },
+  };
+}

package/src/tools/plan-mode.ts

@@ -0,0 +1,134 @@
+/**
+ * Plan Mode Tools
+ *
+ * enterPlanMode — switches the agent into Plan mode (disables write/edit/bash).
+ * exitPlanMode  — submits a plan for user approval before switching back to Build mode.
+ */
+
+import { Type } from "typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import {
+  setAgentMode,
+  getAgentMode,
+  getActiveToolNamesForMode,
+  injectModeIntoSystemPrompt,
+} from "../agent/mode.js";
+import { activeSessionRef } from "../agent/hooks.js";
+import { submitPlanForApproval } from "../agent/plan-ui.js";
+
+export const enterPlanModeSchema = Type.Object({});
+
+export type EnterPlanModeToolInput = Record<string, never>;
+
+export const exitPlanModeSchema = Type.Object({
+  plan: Type.String({
+    description:
+      "The detailed plan to present for approval. Must include concrete steps before exiting Plan Mode.",
+  }),
+});
+
+export type ExitPlanModeToolInput = {
+  plan: string;
+};
+
+export function createEnterPlanModeToolDefinition(): ToolDefinition {
+  return {
+    name: "enterPlanMode",
+    label: "Enter Plan Mode",
+    description:
+      "Switch to Plan Mode. In Plan Mode, write/edit/bash tools are disabled so you can " +
+      "research and design a solution before making changes. Use exitPlanMode when ready.",
+    parameters: enterPlanModeSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, _params, _signal, _onUpdate) {
+      const before = getAgentMode();
+      if (before === "plan") {
+        return {
+          content: [{ type: "text", text: "Already in Plan Mode." }],
+          details: { mode: "plan" },
+        };
+      }
+      setAgentMode("plan");
+      const session = activeSessionRef.current;
+      if (session) {
+        session.setActiveToolsByName(getActiveToolNamesForMode("plan"));
+        injectModeIntoSystemPrompt(session, "plan");
+        setTimeout(() => {
+          void session.compact();
+        }, 0);
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "Entered Plan Mode. Write/edit/bash tools are now disabled. " +
+              "Research and design your solution, then call exitPlanMode with a detailed plan.",
+          },
+        ],
+        details: { mode: "plan" },
+      };
+    },
+  } as ToolDefinition;
+}
+
+export function createExitPlanModeToolDefinition(): ToolDefinition {
+  return {
+    name: "exitPlanMode",
+    label: "Exit Plan Mode",
+    description:
+      "Submit a plan and request approval to exit Plan Mode and return to Build Mode. " +
+      "If the user approves, Build Mode is restored. If rejected, stay in Plan Mode and revise.",
+    parameters: exitPlanModeSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const input = params as ExitPlanModeToolInput;
+      const before = getAgentMode();
+      if (before !== "plan") {
+        return {
+          content: [{ type: "text", text: "Not in Plan Mode. No action taken." }],
+          details: { approved: false },
+        };
+      }
+
+      const result = await submitPlanForApproval({ plan: input.plan });
+      if (result.approved) {
+        setAgentMode("build");
+        const session = activeSessionRef.current;
+        if (session) {
+          session.setActiveToolsByName(getActiveToolNamesForMode("build"));
+          injectModeIntoSystemPrompt(session, "build");
+          setTimeout(() => {
+            void session
+              .compact()
+              .catch(() => {})
+              .then(() => session.agent.continue());
+          }, 0);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Plan approved. Exited Plan Mode and returned to Build Mode.",
+            },
+          ],
+          details: { approved: true },
+        };
+      } else {
+        const commentText = result.comment ? ` Comment: ${result.comment}` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Plan was rejected by the user.${commentText} You are still in Plan Mode. ` +
+                "Please revise the plan based on user feedback and try exitPlanMode again.",
+            },
+          ],
+          details: { approved: false, comment: result.comment },
+          isError: true,
+        };
+      }
+    },
+  } as ToolDefinition;
+}

package/src/tools/read-mcp-resource.ts

@@ -0,0 +1,79 @@
+/**
+ * Read MCP Resource Tool
+ */
+
+import { getMcpConnection, getAllMcpResources } from "../services/mcp/index.js";
+
+export interface ReadMcpResourceResult {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+}
+
+export interface ReadMcpResourceArgs {
+  uri: string;
+  server?: string;
+}
+
+export async function readMcpResource(args: ReadMcpResourceArgs): Promise<ReadMcpResourceResult> {
+  const { uri, server: targetServer } = args;
+
+  try {
+    let resourceServer = targetServer;
+    let foundResource = false;
+
+    if (targetServer) {
+      const connection = getMcpConnection(targetServer);
+      if (!connection || connection.status !== "connected") {
+        return { content: [{ type: "text", text: `MCP server '${targetServer}' is not connected` }], isError: true };
+      }
+      const resources = getAllMcpResources().filter(r => r.server === targetServer);
+      foundResource = resources.some(r => r.uri === uri);
+    } else {
+      const allResources = getAllMcpResources();
+      const resource = allResources.find(r => r.uri === uri);
+      if (resource) {
+        resourceServer = resource.server;
+        foundResource = true;
+      }
+    }
+
+    if (!foundResource || !resourceServer) {
+      return { content: [{ type: "text", text: `Resource '${uri}' not found${targetServer ? ` on server '${targetServer}'` : ""}` }], isError: true };
+    }
+
+    const connection = getMcpConnection(resourceServer);
+    if (!connection || connection.status !== "connected") {
+      return { content: [{ type: "text", text: `Server '${resourceServer}' is not connected` }], isError: true };
+    }
+
+    const result = await connection.client.readResource({ uri });
+    if (!result.contents || result.contents.length === 0) {
+      return { content: [{ type: "text", text: "Resource is empty" }] };
+    }
+
+    const lines: string[] = [];
+    lines.push(`# Resource: ${uri}`);
+    lines.push(`Server: ${resourceServer}`);
+    lines.push("");
+
+    for (const content of result.contents) {
+      const c = content as { type?: string; text?: string; mimeType?: string; blob?: string };
+      if (c.type === "text") {
+        lines.push("```");
+        lines.push(c.text ?? "");
+        lines.push("```");
+      } else if (c.type === "image") {
+        lines.push(`[Image resource: ${c.mimeType ?? "unknown type"}]`);
+      } else if (c.type === "blob") {
+        lines.push(`[Binary resource: ${c.mimeType ?? "unknown type"}]`);
+      } else {
+        lines.push(JSON.stringify(content, null, 2));
+      }
+    }
+
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: `Error reading MCP resource: ${errorMessage}` }], isError: true };
+  }
+}