@meowlynxsea/koi 0.1.0

package/src/tools/read.ts

@@ -0,0 +1,137 @@
+/**
+ * FileReadTool — 多格式文件阅读器
+ *
+ * Supports plain text files with line-range reading.
+ * Image / PDF / Notebook support can be added in future iterations.
+ */
+
+import { Type } from "typebox";
+import { readFileSync, 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";
+import { getErrorMessage } from "./types.js";
+
+export const readSchema = Type.Object({
+  path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+  offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+  limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+
+export type ReadToolInput = {
+  path: string;
+  offset?: number;
+  limit?: number;
+};
+
+const BLOCKED_PATHS = [
+  "/dev/zero",
+  "/dev/random",
+  "/dev/urandom",
+  "/dev/full",
+  "/dev/stdin",
+  "/dev/tty",
+  "/dev/console",
+  "/dev/stdout",
+  "/dev/stderr",
+];
+
+/** 可配置的文件大小上限（默认 256 MiB） */
+const MAX_FILE_SIZE_BYTES = 256 * 1024 * 1024;
+
+function isBlockedPath(p: string): boolean {
+  const normalized = p.toLowerCase().replace(/\\/g, "/");
+  return BLOCKED_PATHS.some((bp) => normalized.startsWith(bp.toLowerCase()));
+}
+
+function readFileInRange(filePath: string, offset?: number, limit?: number): { content: string; totalLines: number } {
+  const buf = readFileSync(filePath, "utf-8");
+  const allLines = buf.split("\n");
+  const totalLines = allLines.length;
+
+  const start = offset ? Math.max(0, offset - 1) : 0;
+  const end = limit !== undefined ? start + limit : allLines.length;
+  const sliced = allLines.slice(start, end);
+
+  return { content: sliced.join("\n"), totalLines };
+}
+
+export async function executeRead(
+  _toolCallId: string,
+  params: ReadToolInput
+): Promise<{ content: TextContent[]; details: { path: string; totalLines: number; readLines: number } }> {
+  const filePath = resolve(params.path);
+
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${params.path}`);
+  }
+
+  if (isBlockedPath(filePath)) {
+    throw new Error(`Reading from device/special paths is not allowed: ${params.path}`);
+  }
+
+  let stats: ReturnType<typeof statSync>;
+  try {
+    stats = statSync(filePath);
+  } catch (err: unknown) {
+    throw new Error(`Unable to read file metadata: ${params.path} (${getErrorMessage(err)})`);
+  }
+
+  if (stats.isDirectory()) {
+    throw new Error(`Path is a directory, not a file: ${params.path}`);
+  }
+
+  if (stats.size > MAX_FILE_SIZE_BYTES) {
+    throw new Error(`File too large (${(stats.size / 1024 / 1024).toFixed(1)} MiB). Use a more targeted approach.`);
+  }
+
+  const { content, totalLines } = readFileInRange(filePath, params.offset, params.limit);
+  const readLines = content.split("\n").length;
+
+  return {
+    content: [{ type: "text", text: content }],
+    details: { path: filePath, totalLines, readLines },
+  };
+}
+
+export function createReadToolDefinition(_cwd: string): ToolDefinition<typeof readSchema, { path: string; totalLines: number; readLines: number }> {
+  return {
+    name: "read",
+    label: "Read",
+    description: "Reads a file from the local filesystem.",
+    promptSnippet: "Read: reads files (text, images, PDFs, notebooks). Use absolute paths.",
+    promptGuidelines: [
+      "The file_path parameter must be an absolute path",
+      "By default, reads up to 2000 lines from the beginning",
+      "If you read a file that exists but has empty contents you will receive a system reminder warning",
+    ],
+    parameters: readSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      const perm = checkPermission("read", params);
+      if (perm.decision === "deny") {
+        const result: ToolResultWithError<{ path: string; totalLines: number; readLines: number }> = {
+          content: [{ type: "text", text: `Permission denied: ${perm.reason ?? "read operation blocked"}` }],
+          details: { path: params.path, totalLines: 0, readLines: 0 },
+          isError: true,
+        };
+        return result;
+      }
+      if (perm.decision === "ask") {
+        const allowed = await requestPermission({ toolName: "read", args: params, reason: perm.reason ?? "Confirm file read" });
+        if (!allowed) {
+          const result: ToolResultWithError<{ path: string; totalLines: number; readLines: number }> = {
+            content: [{ type: "text", text: "User denied permission to read the file." }],
+            details: { path: params.path, totalLines: 0, readLines: 0 },
+            isError: true,
+          };
+          return result;
+        }
+      }
+      return await executeRead(toolCallId, params);
+    },
+  };
+}

package/src/tools/skill.ts

@@ -0,0 +1,176 @@
+/**
+ * Skill Tool — Load and invoke Koi skills
+ *
+ * Provides the agent with a dedicated tool to:
+ * 1. List all available skills
+ * 2. Load and execute a skill's content with argument substitution
+ */
+
+import { Type } from "typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { ContentBlockParam } from "../skills/types.js";
+import { 
+  getAllSkills, 
+  getSkillByName, 
+  invokeSkill,
+  type SkillCommand,
+} from "../skills/index.js";
+
+// ─── Schemas ─────────────────────────────────────────────────────────────────
+
+export const skillSchema = Type.Object({
+  name: Type.Optional(
+    Type.String({ 
+      description: "Name of the skill to invoke (e.g., 'review', 'test')",
+    })
+  ),
+  args: Type.Optional(
+    Type.String({ 
+      description: "Arguments to pass to the skill (will substitute {{skill.args}} and <arg> placeholders)",
+    })
+  ),
+  list: Type.Optional(
+    Type.Boolean({ 
+      description: "If true, list all available skills without invoking any",
+    })
+  ),
+});
+
+export type SkillInput = {
+  name?: string;
+  args?: string;
+  list?: boolean;
+};
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+function formatSkillList(skills: SkillCommand[]): string {
+  if (skills.length === 0) {
+    return "No skills available.";
+  }
+
+  const lines: string[] = ["Available skills:\n"];
+  
+  for (const skill of skills) {
+    const usage = skill.argumentHint
+      ? `/${skill.name} ${skill.argumentHint}`
+      : `/${skill.name}`;
+    
+    lines.push(`## ${skill.name}`);
+    lines.push(`Usage: ${usage}`);
+    lines.push(`Description: ${skill.description}`);
+    
+    if (skill.source !== "bundled") {
+      lines.push(`Source: ${skill.source}`);
+    } else {
+      lines.push(`Source: bundled`);
+    }
+    lines.push("");
+  }
+  
+  return lines.join("\n");
+}
+
+function formatSkillResult(content: ContentBlockParam[]): string {
+  return content.map(c => {
+    if (c.type === "text") {
+      return c.text;
+    }
+    // For other content types, stringify them
+    return JSON.stringify(c);
+  }).join("\n");
+}
+
+// ─── Execute Function ─────────────────────────────────────────────────────────
+
+export async function executeSkill(
+  _toolCallId: string,
+  params: SkillInput
+) {
+  // List all skills
+  if (params.list === true || (!params.name && !params.args)) {
+    const allSkills = getAllSkills();
+    return {
+      content: [{ type: "text" as const, text: formatSkillList(allSkills) }],
+      details: { skills: allSkills },
+    };
+  }
+
+  // Require a skill name if not listing
+  if (!params.name) {
+    return {
+      content: [{ 
+        type: "text" as const, 
+        text: "Error: Skill name is required when not listing skills. Use Skill(list: true) to see available skills.",
+      }],
+      details: {},
+    };
+  }
+
+  // Find the skill
+  const skill = getSkillByName(params.name);
+  if (!skill) {
+    const allSkills = getAllSkills();
+    const suggestions = allSkills
+      .filter(s => s.name.toLowerCase().includes(params.name!.toLowerCase()))
+      .map(s => s.name);
+    
+    let message = `Skill not found: "${params.name}"`;
+    if (suggestions.length > 0) {
+      message += `\n\nDid you mean: ${suggestions.join(", ")}?`;
+    } else {
+      message += `\n\nUse Skill(list: true) to see all available skills.`;
+    }
+    
+    return {
+      content: [{ type: "text" as const, text: message }],
+      details: {},
+    };
+  }
+
+  // Invoke the skill
+  const args = params.args ?? "";
+  try {
+    const content = await invokeSkill(skill, args, null);
+    const text = formatSkillResult(content);
+    
+    return {
+      content: [{ type: "text" as const, text }],
+      details: { skill },
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text" as const, text: `Error invoking skill "${skill.name}": ${errorMessage}` }],
+      details: { skill },
+    };
+  }
+}
+
+// ─── Tool Definition Factory ──────────────────────────────────────────────────
+
+export function createSkillToolDefinition(): ToolDefinition {
+  return {
+    name: "skill",
+    label: "Skill",
+    description:
+      "Load and invoke a Koi skill.\n\n" +
+      "Skills are reusable prompt templates that provide specialized workflows " +
+      "for specific tasks (e.g., code review, testing, documentation).\n\n" +
+      "Use this tool to:\n" +
+      "- List all available skills (Skill(list: true))\n" +
+      "- Invoke a skill with arguments (Skill(name: 'review', args: 'src/'))\n\n" +
+      "When a skill matches the current task, use it to get specialized instructions.",
+    promptSnippet: "Skill: load and invoke a skill",
+    promptGuidelines: [
+      "Use Skill(list: true) to see all available skills.",
+      "When a task matches a skill's description, use Skill(name: '<skill>') to load specialized instructions.",
+      "Skills may accept arguments - check the skill's argument_hint for usage.",
+    ],
+    parameters: skillSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      return executeSkill(toolCallId, params as SkillInput);
+    },
+  };
+}

package/src/tools/task.ts

@@ -0,0 +1,349 @@
+/**
+ * Task Management Tools — Session-scoped task tracking with persistence
+ *
+ * Implements Claude Code's 4-tool task system:
+ *   TaskCreate  → create a new task
+ *   TaskGet     → retrieve a single task by ID
+ *   TaskList    → list all tasks (optionally filtered by status)
+ *   TaskUpdate  → update task fields, status, and dependency relationships
+ *
+ * Tasks are now isolated per session via SessionTaskManager and persisted
+ * to ~/.config/koi/sessions/<sessionId>/tasks.json.
+ */
+
+import { Type } from "typebox";
+import type { ToolDefinition, AgentToolResult } from "@mariozechner/pi-coding-agent";
+import type { TextContent, ImageContent } from "@mariozechner/pi-ai";
+import type { SessionTaskManager, Task } from "../agent/session-tasks.js";
+import type { ToolResultWithError } from "./types.js";
+
+// ─── Schemas ─────────────────────────────────────────────────────────────────
+
+export const taskCreateSchema = Type.Object({
+  content: Type.String({ 
+    description: "Task description / content (max 40 characters)",
+    maxLength: 40,
+  }),
+  priority: Type.Optional(
+    Type.Union(
+      [Type.Literal("high"), Type.Literal("medium"), Type.Literal("low")],
+      { description: "Task priority (default: medium)" }
+    )
+  ),
+  blockedBy: Type.Optional(
+    Type.Array(Type.String({ description: "Task ID that blocks this task" }), {
+      description: "IDs of tasks that must be completed before this one can start",
+    })
+  ),
+  blocks: Type.Optional(
+    Type.Array(Type.String({ description: "Task ID that this task blocks" }), {
+      description: "IDs of tasks that are blocked until this one is completed",
+    })
+  ),
+});
+
+export type TaskCreateInput = {
+  content: string;
+  priority?: "high" | "medium" | "low";
+  blockedBy?: string[];
+  blocks?: string[];
+};
+
+export const taskGetSchema = Type.Object({
+  taskId: Type.String({ description: "Unique task identifier" }),
+});
+
+export type TaskGetInput = {
+  taskId: string;
+};
+
+export const taskListSchema = Type.Object({
+  status: Type.Optional(
+    Type.Union(
+      [Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")],
+      { description: "Filter by status" }
+    )
+  ),
+});
+
+export type TaskListInput = {
+  status?: "pending" | "in_progress" | "completed";
+};
+
+export const taskUpdateSchema = Type.Object({
+  taskId: Type.String({ description: "Unique task identifier" }),
+  content: Type.Optional(Type.String({ 
+    description: "New task description (max 40 characters)",
+    maxLength: 40,
+  })),
+  status: Type.Optional(
+    Type.Union(
+      [Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")],
+      { description: "New task status" }
+    )
+  ),
+  priority: Type.Optional(
+    Type.Union(
+      [Type.Literal("high"), Type.Literal("medium"), Type.Literal("low")],
+      { description: "New task priority" }
+    )
+  ),
+  addBlockedBy: Type.Optional(
+    Type.Array(Type.String(), { description: "Task IDs to add to blockedBy" })
+  ),
+  removeBlockedBy: Type.Optional(
+    Type.Array(Type.String(), { description: "Task IDs to remove from blockedBy" })
+  ),
+  addBlocks: Type.Optional(
+    Type.Array(Type.String(), { description: "Task IDs to add to blocks" })
+  ),
+  removeBlocks: Type.Optional(
+    Type.Array(Type.String(), { description: "Task IDs to remove from blocks" })
+  ),
+});
+
+export type TaskUpdateInput = {
+  taskId: string;
+  content?: string;
+  status?: "pending" | "in_progress" | "completed";
+  priority?: "high" | "medium" | "low";
+  addBlockedBy?: string[];
+  removeBlockedBy?: string[];
+  addBlocks?: string[];
+  removeBlocks?: string[];
+};
+
+// ─── Formatting ──────────────────────────────────────────────────────────────
+
+function formatTaskList(taskArray: Task[]): string {
+  if (taskArray.length === 0) return "No tasks found.";
+
+  const lines: string[] = [];
+  for (const t of taskArray) {
+    const depInfo: string[] = [];
+    if (t.blockedBy.length > 0) depInfo.push(`blockedBy:[${t.blockedBy.join(", ")}]`);
+    if (t.blocks.length > 0) depInfo.push(`blocks:[${t.blocks.join(", ")}]`);
+    const depStr = depInfo.length > 0 ? ` {${depInfo.join(", ")}}` : "";
+    lines.push(`- [${t.status}] ${t.id} (${t.priority}): ${t.content}${depStr}`);
+  }
+  return lines.join("\n");
+}
+
+// ─── Execute Functions (injected with SessionTaskManager) ────────────────────
+
+export async function executeTaskCreate(
+  taskManager: SessionTaskManager,
+  _toolCallId: string,
+  params: TaskCreateInput
+): Promise<AgentToolResult<{ task: Task }>> {
+  // Block overly long task content to prevent AI misuse of todo list
+  if (params.content.length > 40) {
+    return {
+      content: [{ 
+        type: "text", 
+        text: `Error: Task content exceeds 40 characters (${params.content.length} chars). Please shorten the description to 40 characters or less. Example: "Fix login bug" instead of "Fix the login bug where users cannot authenticate with SSO"`,
+      }],
+      details: { task: null! },
+    };
+  }
+
+  const task = taskManager.createTask(
+    params.content,
+    params.priority ?? "medium",
+    params.blockedBy,
+    params.blocks
+  );
+
+  return {
+    content: [{ type: "text", text: `Created task ${task.id}: ${task.content}` }],
+    details: { task },
+  };
+}
+
+export async function executeTaskGet(
+  taskManager: SessionTaskManager,
+  _toolCallId: string,
+  params: TaskGetInput
+): Promise<{ content: (TextContent | ImageContent)[]; details: { task: Task | null } }> {
+  const task = taskManager.getTask(params.taskId);
+
+  if (!task) {
+    const result: ToolResultWithError<{ task: Task | null }> = {
+      content: [{ type: "text", text: `Task not found: ${params.taskId}` }],
+      details: { task: null },
+      isError: true,
+    };
+    return result;
+  }
+
+  const lines = [
+    `id: ${task.id}`,
+    `content: ${task.content}`,
+    `status: ${task.status}`,
+    `priority: ${task.priority}`,
+    `blockedBy: [${task.blockedBy.join(", ") || "none"}]`,
+    `blocks: [${task.blocks.join(", ") || "none"}]`,
+  ];
+
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    details: { task },
+  };
+}
+
+export async function executeTaskList(
+  taskManager: SessionTaskManager,
+  _toolCallId: string,
+  params: TaskListInput
+): Promise<{ content: TextContent[]; details: { tasks: Task[]; count: number } }> {
+  const all = taskManager.listTasks(params.status);
+  const text = formatTaskList(all);
+
+  return {
+    content: [{ type: "text", text }],
+    details: { tasks: all, count: all.length },
+  };
+}
+
+export async function executeTaskUpdate(
+  taskManager: SessionTaskManager,
+  _toolCallId: string,
+  params: TaskUpdateInput
+): Promise<AgentToolResult<{ task: Task | null }>> {
+  // Block overly long task content to prevent AI misuse of todo list
+  if (params.content !== undefined && params.content.length > 40) {
+    return {
+      content: [{ 
+        type: "text", 
+        text: `Error: Task content exceeds 40 characters (${params.content.length} chars). Please shorten the description to 40 characters or less.`,
+      }],
+      details: { task: null },
+    };
+  }
+
+  const task = taskManager.updateTask(params.taskId, {
+    content: params.content,
+    status: params.status,
+    priority: params.priority,
+    addBlockedBy: params.addBlockedBy,
+    removeBlockedBy: params.removeBlockedBy,
+    addBlocks: params.addBlocks,
+    removeBlocks: params.removeBlocks,
+  });
+
+  if (!task) {
+    return {
+      content: [{ type: "text", text: `Task not found: ${params.taskId}` }],
+      details: { task: null },
+    };
+  }
+
+  return {
+    content: [{ type: "text", text: `Updated task ${task.id}: ${task.content} [${task.status}]` }],
+    details: { task },
+  };
+}
+
+// ─── Tool Definition Factories ───────────────────────────────────────────────
+
+export function createTaskCreateToolDefinition(
+  _cwd: string,
+  taskManager: SessionTaskManager
+): ToolDefinition<typeof taskCreateSchema, { task: Task }> {
+  return {
+    name: "taskCreate",
+    label: "TaskCreate",
+    description:
+      "Create a new task in the session todo list.\n\n" +
+      "Use VERY frequently to break down complex tasks into atomic steps. " +
+      "ALWAYS create a todo list before starting multi-step work. " +
+      "If you do not use this tool when planning, you may forget important tasks.",
+    promptSnippet: "TaskCreate: create a new task in the session todo list",
+    promptGuidelines: [
+      "Use TaskCreate VERY frequently to track and plan tasks.",
+      "ALWAYS create a todo list before starting multi-step or non-trivial work.",
+      "Break large complex tasks into smaller atomic steps.",
+      "⚠️ Task content MUST be 40 characters or less. Use concise, brief descriptions.",
+      "Set priority to 'high' for critical path items, 'low' for nice-to-haves.",
+      "Use blockedBy/blocks to express dependency relationships between tasks.",
+    ],
+    parameters: taskCreateSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      return executeTaskCreate(taskManager, toolCallId, params);
+    },
+  };
+}
+
+export function createTaskGetToolDefinition(
+  _cwd: string,
+  taskManager: SessionTaskManager
+): ToolDefinition<typeof taskGetSchema, { task: Task | null }> {
+  return {
+    name: "taskGet",
+    label: "TaskGet",
+    description: "Retrieve the full details of a single task by its ID.",
+    promptSnippet: "TaskGet: retrieve details of a specific task by ID",
+    promptGuidelines: [
+      "Use TaskGet when you need to inspect a task's dependencies or full state.",
+    ],
+    parameters: taskGetSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      return executeTaskGet(taskManager, toolCallId, params);
+    },
+  };
+}
+
+export function createTaskListToolDefinition(
+  _cwd: string,
+  taskManager: SessionTaskManager
+): ToolDefinition<typeof taskListSchema, { tasks: Task[]; count: number }> {
+  return {
+    name: "taskList",
+    label: "TaskList",
+    description:
+      "List all tasks in the session todo list, optionally filtered by status.\n\n" +
+      "Check your progress regularly — at the start of each turn, after completing a step, " +
+      "and whenever you're unsure what to do next.",
+    promptSnippet: "TaskList: list all tasks (optionally filter by status)",
+    promptGuidelines: [
+      "Call TaskList at the start of each conversation turn to review progress.",
+      "Call TaskList after completing any task to verify next steps.",
+      "Call TaskList whenever you are unsure what to do next.",
+    ],
+    parameters: taskListSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      return executeTaskList(taskManager, toolCallId, params);
+    },
+  };
+}
+
+export function createTaskUpdateToolDefinition(
+  _cwd: string,
+  taskManager: SessionTaskManager
+): ToolDefinition<typeof taskUpdateSchema, { task: Task | null }> {
+  return {
+    name: "taskUpdate",
+    label: "TaskUpdate",
+    description:
+      "Update an existing task's content, status, priority, or dependency relationships.\n\n" +
+      "Mark tasks as 'in_progress' BEFORE starting work on them. " +
+      "ONLY mark as 'completed' when FULLY done — tests passing, no errors, no partial implementations. " +
+      "If you encountered unresolved errors, do NOT mark the task as completed.",
+    promptSnippet: "TaskUpdate: update task status, content, priority, or dependencies",
+    promptGuidelines: [
+      "Mark a task as 'in_progress' before you begin working on it.",
+      "ONLY mark a task as 'completed' when you have FULLY accomplished it.",
+      "Never mark completed if: tests are failing, implementation is partial, unresolved errors exist.",
+      "Ideally you should only have one task as 'in_progress' at a time (single-threaded focus).",
+      "Update blockedBy / blocks to reflect changing dependency relationships.",
+    ],
+    parameters: taskUpdateSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      return executeTaskUpdate(taskManager, toolCallId, params);
+    },
+  };
+}