@meowlynxsea/koi 0.1.0

package/src/skills/substitution.ts

@@ -0,0 +1,169 @@
+/**
+ * Argument Substitution for Skills
+ *
+ * Handles {{skill.args}} and <arg> placeholders in skill prompts.
+ */
+
+import type { ToolUseContext } from "./types.js";
+
+/**
+ * Substitute arguments in skill content
+ * Supports {{skill.args}}, {{skill.arg.name}}, and <name> placeholders
+ */
+export function substituteArguments(
+  content: string,
+  args: string,
+  strict: boolean,
+  argNames?: string[]
+): string {
+  let result = content;
+
+  // Replace {{skill.args}} with the full argument string
+  result = result.replace(/\{\{skill\.args\}\}/g, args);
+
+  // If argNames are provided, try to parse named arguments
+  if (argNames && argNames.length > 0) {
+    const parsedArgs = parseNamedArguments(args, argNames);
+    
+    // Replace {{skill.arg.name}} patterns
+    result = result.replace(/\{\{skill\.arg\.(\w+)\}\}/g, (match, name) => {
+      const value = parsedArgs[name as keyof typeof parsedArgs];
+      return value ?? (strict ? match : "");
+    });
+
+    // Replace <name> patterns with values
+    for (const [name, value] of Object.entries(parsedArgs)) {
+      result = result.replace(new RegExp(`<${name}>`, "g"), value);
+    }
+  }
+
+  // Replace remaining <...> placeholders with args (for backward compatibility)
+  result = result.replace(/<[^>]+>/g, (match) => {
+    if (match === args) return args; // If the whole thing is the args, keep it
+    return match; // Leave other placeholders as-is
+  });
+
+  return result;
+}
+
+/**
+ * Parse named arguments from a string
+ * e.g., "file.ts --flag value" with argNames ["file", "flag"]
+ * -> { file: "file.ts", flag: "value" }
+ */
+export function parseNamedArguments(args: string, argNames: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+
+  let partIndex = 0;
+  for (const name of argNames) {
+    if (partIndex >= parts.length) {
+      result[name] = "";
+      continue;
+    }
+
+    const part = parts[partIndex]!;
+
+    // Check if this part looks like a named argument (--name or --name=value)
+    if (part.startsWith("--")) {
+      const eqIdx = part.indexOf("=");
+      if (eqIdx !== -1) {
+        // --name=value format
+        const argName = part.slice(2, eqIdx);
+        const argValue = part.slice(eqIdx + 1);
+        result[argName] = argValue;
+        partIndex++;
+      } else {
+        // --name value format
+        result[name] = parts[partIndex + 1] ?? "";
+        partIndex += 2;
+      }
+    } else if (part.startsWith("-")) {
+      // Single dash flag
+      result[name] = part;
+      partIndex++;
+    } else {
+      // Positional argument
+      result[name] = part;
+      partIndex++;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse argument names from arguments frontmatter
+ * e.g., "<file> <target>" -> ["file", "target"]
+ */
+export function parseArgumentNames(argumentsFrontmatter?: string | string[]): string[] {
+  if (!argumentsFrontmatter) return [];
+
+  const args = Array.isArray(argumentsFrontmatter) 
+    ? argumentsFrontmatter 
+    : argumentsFrontmatter.split(/\s+/);
+
+  return args.map(arg => arg.replace(/[<>]/g, "").trim()).filter(Boolean);
+}
+
+/**
+ * Execute shell commands in skill prompt
+ * Supports !`command` and ```! ... ``` syntax
+ */
+export async function executeShellCommandsInPrompt(
+  content: string,
+  _ctx: ToolUseContext,
+  skillName: string
+): Promise<string> {
+  // For now, we'll just strip shell commands as execution requires careful handling
+  // This is a simplified version - full implementation would execute and replace
+  
+  let result = content;
+
+  // Remove inline shell commands: !`command`
+  result = result.replace(/!`([^`]+)`/g, (_, cmd) => {
+    // In a full implementation, this would execute the command
+    // and replace the !`...` with the output
+    console.log(`[skill:${skillName}] Would execute: ${cmd}`);
+    return `[shell output placeholder: ${cmd}]`;
+  });
+
+  // Remove block shell commands: ```! ... ```
+  result = result.replace(/```!([\s\S]*?)```/g, (_, cmd: string) => {
+    const trimmedCmd = cmd.trim();
+    console.log(`[skill:${skillName}] Would execute block: ${trimmedCmd}`);
+    return `[shell output placeholder]`;
+  });
+
+  return result;
+}
+
+/**
+ * Substitute environment variables in content
+ */
+export function substituteEnvVariables(
+  content: string,
+  env: Record<string, unknown>,
+  sessionId?: string,
+  skillDir?: string
+): string {
+  let result = content;
+
+  // Replace ${CLAUDE_SKILL_DIR}
+  if (skillDir) {
+    result = result.replace(/\$\{CLAUDE_SKILL_DIR\}/g, skillDir);
+  }
+
+  // Replace ${CLAUDE_SESSION_ID}
+  if (sessionId) {
+    result = result.replace(/\$\{CLAUDE_SESSION_ID\}/g, sessionId);
+  }
+
+  // Replace ${ENV:VAR_NAME}
+  result = result.replace(/\$\{ENV:(\w+)\}/g, (_, varName) => {
+    const value = env[varName as keyof typeof env];
+    return value !== undefined ? String(value) : "";
+  });
+
+  return result;
+}

package/src/skills/types.ts

@@ -0,0 +1,201 @@
+/**
+ * Skills System Type Definitions
+ *
+ * Defines the core types for Koi's Skills functionality.
+ * Skills are reusable prompt templates with metadata that can be invoked
+ * via slash commands (e.g., /review, /test).
+ */
+
+/**
+ * Content block type for skill prompts.
+ * Simplified version of the AI SDK's ContentBlockParam type.
+ */
+export type ContentBlockParam = 
+  | { type: "text"; text: string }
+  | { type: "image"; image: string | Uint8Array }
+  | { type: "tool_result"; toolResultId: string; content: string }
+  | { type: "tool_use"; tool: string; args: Record<string, unknown> };
+
+/**
+ * Hooks configuration for skills
+ */
+export interface HooksSettings {
+  "pre-task"?: string[];
+  "post-task"?: string[];
+}
+
+/**
+ * Frontmatter shell configuration
+ */
+export interface FrontmatterShell {
+  name?: string;
+  command?: string;
+  env?: Record<string, string>;
+}
+
+/**
+ * Context passed to skill prompt generators
+ */
+export interface ToolUseContext {
+  tools: Record<string, (...args: unknown[]) => unknown>;
+  env: Record<string, unknown>;
+  cwd: string;
+}
+
+/**
+ * Skill loaded from source
+ */
+export type SkillLoadedFrom = 
+  | "skills"      // Loaded from skills directory
+  | "commands"     // Loaded from commands directory (legacy)
+  | "plugin"       // From a plugin
+  | "bundled"      // Built-in bundled skill
+  | "mcp";         // From MCP server
+
+/**
+ * Skill configuration source
+ */
+export type SkillSource = 
+  | "userSettings"      // User's global skills (~/.config/koi/skills)
+  | "projectSettings"   // Project-level skills (.claude/skills)
+  | "policySettings"    // Policy-defined skills
+  | "plugin"            // From a plugin
+  | "bundled"           // Built-in bundled skill
+  | "mcp";              // From MCP server
+
+/**
+ * Parsed frontmatter fields from SKILL.md
+ */
+export interface ParsedFields {
+  name?: string;
+  description?: string | string[];
+  when_to_use?: string;
+  argument_hint?: string;
+  arguments?: string | string[];
+  allowed_tools?: string | string[];
+  model?: string;
+  disable_model_invocation?: boolean;
+  user_invocable?: boolean;
+  hooks?: HooksSettings;
+  context?: "fork" | "inline";
+  agent?: string;
+  effort?: string;
+  paths?: string | string[];
+  shell?: FrontmatterShell;
+  version?: string;
+}
+
+/**
+ * A skill command that can be invoked
+ */
+export interface SkillCommand {
+  type: "prompt";
+  name: string;
+  description: string;
+  hasUserSpecifiedDescription: boolean;
+  allowedTools: string[];
+  argumentHint?: string;
+  argNames?: string[];
+  whenToUse?: string;
+  version?: string;
+  model?: string;
+  disableModelInvocation: boolean;
+  userInvocable: boolean;
+  context?: "fork" | "inline";
+  agent?: string;
+  effort?: string;
+  paths?: string[];
+  contentLength: number;
+  isHidden: boolean;
+  progressMessage: string;
+  source: SkillSource;
+  loadedFrom: SkillLoadedFrom;
+  hooks?: HooksSettings;
+  skillRoot?: string;
+  /**
+   * Generate the prompt content for this skill with given arguments
+   */
+  getPromptForCommand: (args: string, ctx: ToolUseContext) => Promise<ContentBlockParam[]>;
+}
+
+/**
+ * A skill with its source file path
+ */
+export interface SkillWithPath {
+  skill: SkillCommand;
+  filePath: string;
+}
+
+/**
+ * Bundled skill definition (used for registration)
+ */
+export interface BundledSkillDefinition {
+  name: string;
+  description: string;
+  aliases?: string[];
+  whenToUse?: string;
+  argumentHint?: string;
+  allowedTools?: string[];
+  model?: string;
+  disableModelInvocation?: boolean;
+  userInvocable?: boolean;
+  isEnabled?: () => boolean;
+  hooks?: HooksSettings;
+  context?: "inline" | "fork";
+  agent?: string;
+  effort?: string;
+  template?: string;
+  files?: Record<string, string>;
+  getPromptForCommand: (args: string, ctx: ToolUseContext) => Promise<ContentBlockParam[]>;
+}
+
+/**
+ * Skill invocation result
+ */
+export interface SkillInvocationResult {
+  success: boolean;
+  content?: ContentBlockParam[];
+  error?: string;
+}
+
+/**
+ * Frontmatter parsed from a SKILL.md file
+ */
+export interface SkillFrontmatter {
+  name?: string;
+  description?: string | string[];
+  when_to_use?: string;
+  "argument-hint"?: string;
+  arguments?: string | string[];
+  "allowed-tools"?: string | string[];
+  model?: string;
+  "disable-model-invocation"?: boolean;
+  "user-invocable"?: boolean;
+  hooks?: HooksSettings;
+  context?: "fork" | "inline";
+  agent?: string;
+  effort?: string;
+  paths?: string | string[];
+  shell?: FrontmatterShell;
+  version?: string;
+}
+
+/**
+ * Skill file info for discovery
+ */
+export interface SkillFileInfo {
+  path: string;
+  name: string;
+  root: string;
+  source: SkillSource;
+  loadedFrom: SkillLoadedFrom;
+}
+
+/**
+ * Dynamic skill loading event
+ */
+export interface SkillsLoadedEvent {
+  skills: SkillCommand[];
+  source: SkillSource;
+  timestamp: number;
+}

package/src/tools/agent.ts

@@ -0,0 +1,143 @@
+/**
+ * Agent Tool — Spawn a subagent to perform a focused task.
+ *
+ * Implements Claude Code's AgentTool semantics on top of Pi's agent framework:
+ *   • Built-in types: "explore" (read-only), "plan" (read-only + tasks)
+ *   • Synchronous mode: wait for completion, return result text
+ *   • Asynchronous mode: fire-and-forget, return agentId immediately
+ *
+ * Subagents are intentionally isolated:
+ *   • Fresh message history (only the prompt)
+ *   • Filtered tool set (no nested agents, no user questions, no plan-mode exit)
+ *   • Max turn limit to prevent runaway token consumption
+ */
+
+import { Type } from "typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { ToolResultWithError } from "./types.js";
+import { activeSessionRef } from "../agent/hooks.js";
+import { runSubagent, type SubagentConfig } from "../agent/subagent.js";
+import { subagentRegistry } from "../agent/subagent-registry.js";
+
+// ─── Schema ──────────────────────────────────────────────────────────────────
+
+export const agentSchema = Type.Object({
+  description: Type.String({
+    description: "A short (3-5 word) description of the task",
+    maxLength: 60,
+  }),
+  prompt: Type.String({
+    description: "The complete task description for the subagent",
+  }),
+  subagent_type: Type.Optional(
+    Type.Union(
+      [Type.Literal("explore"), Type.Literal("plan")],
+      { description: "Built-in agent type: 'explore' = read-only, 'plan' = planning mode. Defaults to 'explore' if omitted." }
+    )
+  ),
+  model: Type.Optional(
+    Type.String({
+      description: "Model override (optional, not yet implemented)",
+    })
+  ),
+  run_in_background: Type.Optional(
+    Type.Boolean({
+      description: "Run asynchronously in the background. A <task-notification> will be injected into your context when it completes. The user does not see this notification.",
+    })
+  ),
+});
+
+export type AgentToolInput = {
+  description: string;
+  prompt: string;
+  subagent_type?: "explore" | "plan";
+  model?: string;
+  run_in_background?: boolean;
+};
+
+// ─── Execute ─────────────────────────────────────────────────────────────────
+
+export async function executeAgent(
+  _toolCallId: string,
+  params: AgentToolInput
+): Promise<ToolResultWithError<{ result?: string; agentId?: string; status: string }>> {
+  if (!activeSessionRef.current) {
+    return {
+      content: [{ type: "text", text: "Error: No active session available to spawn subagent." }],
+      details: { status: "error" },
+      isError: true,
+    } as ToolResultWithError<{ result?: string; agentId?: string; status: string }>;
+  }
+
+  const config: SubagentConfig = {
+    description: params.description,
+    prompt: params.prompt,
+    subagentType: params.subagent_type ?? "explore",
+    runInBackground: params.run_in_background,
+  };
+
+  if (params.run_in_background) {
+    const agentId = await subagentRegistry.launch(config);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Launched background agent ${agentId}: ${params.description}\n\nThe agent is running asynchronously. A <task-notification> will be injected into your context when it completes. The user does not see this notification.`,
+        },
+      ],
+      details: { status: "async_launched", agentId },
+    };
+  }
+
+  try {
+    const result = await runSubagent(config);
+    return {
+      content: [
+        { type: "text", text: result || "[Agent completed with empty output]" },
+      ],
+      details: { status: "completed", result },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Subagent failed: ${message}` }],
+      details: { status: "failed" },
+      isError: true,
+    } as ToolResultWithError<{ result?: string; agentId?: string; status: string }>;
+  }
+}
+
+// ─── Tool Definition ─────────────────────────────────────────────────────────
+
+export function createAgentToolDefinition(): ToolDefinition<
+  typeof agentSchema,
+  { result?: string; agentId?: string; status: string }
+> {
+  return {
+    name: "agent",
+    label: "Agent",
+    description:
+      "Spawn a focused subagent to perform a specific task in isolation.\n\n" +
+      "Use this tool to delegate parallelizable work (e.g., exploring a directory, " +
+      "researching a file, drafting a plan) while you continue with other tasks.\n\n" +
+      "Built-in types:\n" +
+      "  • explore — read-only tools only; safe for research and discovery (default)\n" +
+      "  • plan    — read-only + task tools; for formulating implementation plans\n\n" +
+      "If subagent_type is omitted, it defaults to 'explore' for safety.\n" +
+      "Set run_in_background to true for fire-and-forget execution. " +
+      "You will receive a <task-notification> when the background agent completes.",
+    promptSnippet: "Agent: spawn a focused subagent to perform a task",
+    promptGuidelines: [
+      "Use Agent to delegate independent, parallelizable tasks.",
+      "Provide a concise description (3-5 words) and a detailed prompt.",
+      "Choose 'explore' for read-only research, 'plan' for drafting plans.",
+      "Set run_in_background when you don't need the result immediately.",
+      "Subagents cannot spawn other subagents or ask the user questions.",
+    ],
+    parameters: agentSchema,
+    executionMode: "parallel",
+    async execute(toolCallId, params, _signal, _onUpdate) {
+      return executeAgent(toolCallId, params);
+    },
+  };
+}

package/src/tools/ask-user-question.ts

@@ -0,0 +1,46 @@
+/**
+ * AskUserQuestion Tool
+ *
+ * Allows the agent to ask the user a multiple-choice question.
+ * The question is shown in a modal dialog; the user's answer is returned.
+ * An "Other (custom)" option is always appended automatically.
+ */
+
+import { Type } from "typebox";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import { askUserQuestion } from "../agent/question-ui.js";
+
+export const askUserQuestionSchema = Type.Object({
+  question: Type.String({ description: "The question to ask the user" }),
+  options: Type.Array(Type.String(), {
+    description: "List of answer options for the user to choose from",
+  }),
+});
+
+export type AskUserQuestionToolInput = {
+  question: string;
+  options: string[];
+};
+
+export function createAskUserQuestionToolDefinition(): ToolDefinition {
+  return {
+    name: "askUserQuestion",
+    label: "Ask User Question",
+    description:
+      "Ask the user a multiple-choice question to clarify requirements or collect preferences. " +
+      "An additional 'Other (custom)' option is always provided automatically.",
+    parameters: askUserQuestionSchema,
+    executionMode: "parallel",
+    async execute(_toolCallId, params, _signal, _onUpdate) {
+      const input = params as AskUserQuestionToolInput;
+      const answer = await askUserQuestion({
+        question: input.question,
+        options: input.options,
+      });
+      return {
+        content: [{ type: "text", text: answer }],
+        details: { answer },
+      };
+    },
+  } as ToolDefinition;
+}