@meowlynxsea/koi 0.1.0

package/src/skills/SkillsMenu.tsx

@@ -0,0 +1,370 @@
+/**
+ * SkillsMenu Component
+ *
+ * A modal dialog that displays available skills grouped by source,
+ * with search filtering and detailed skill information.
+ */
+
+import { useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useKeyboard, useTerminalDimensions } from "@opentui/react";
+import { createTextAttributes } from "@opentui/core";
+import type { TextareaRenderable } from "@opentui/core";
+import type { SkillCommand, SkillSource } from "./types.js";
+
+interface SkillsMenuProps {
+  isActive: boolean;
+  onClose: () => void;
+  skills: SkillCommand[];
+  onInvokeSkill?: (skill: SkillCommand, args: string) => void;
+}
+
+interface SkillGroup {
+  source: SkillSource;
+  label: string;
+  skills: SkillCommand[];
+}
+
+const SOURCE_LABELS: Record<SkillSource, string> = {
+  userSettings: "User Skills",
+  projectSettings: "Project Skills",
+  policySettings: "Policy Skills",
+  plugin: "Plugin Skills",
+  bundled: "Built-in Skills",
+  mcp: "MCP Skills",
+};
+
+/**
+ * SkillsMenu component
+ */
+export function SkillsMenu({ isActive, onClose, skills, onInvokeSkill }: SkillsMenuProps) {
+  const { width, height } = useTerminalDimensions();
+  const inputRef = useRef<TextareaRenderable>(null);
+  const [filterText, setFilterText] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const [showDetails, setShowDetails] = useState(false);
+  const scrollOffsetRef = useRef(0);
+
+  const panelWidth = Math.min(80, Math.max(50, Math.floor(width * 0.8)));
+  const panelHeight = Math.min(height - 4, 25);
+  const inputHeight = 1;
+  const separatorHeight = 1;
+  const detailsHeight = showDetails ? 8 : 0;
+  const listHeight = panelHeight - inputHeight - separatorHeight - detailsHeight - 2;
+
+  // Group skills by source
+  const skillGroups = useMemo<SkillGroup[]>(() => {
+    const groups: Map<SkillSource, SkillCommand[]> = new Map();
+
+    for (const skill of skills) {
+      const existing = groups.get(skill.source) ?? [];
+      existing.push(skill);
+      groups.set(skill.source, existing);
+    }
+
+    return Array.from(groups.entries())
+      .filter(([_, groupSkills]) => groupSkills.length > 0)
+      .map(([source, groupSkills]) => ({
+        source,
+        label: SOURCE_LABELS[source] ?? source,
+        skills: groupSkills,
+      }));
+  }, [skills]);
+
+  // Flatten skills with filtering
+  const { flatItems, totalSkills } = useMemo(() => {
+    const query = filterText.toLowerCase().trim();
+    
+    const filteredGroups = skillGroups
+      .map((group) => ({
+        ...group,
+        skills: group.skills.filter(
+          (skill) =>
+            !query ||
+            skill.name.toLowerCase().includes(query) ||
+            skill.description.toLowerCase().includes(query) ||
+            skill.whenToUse?.toLowerCase().includes(query)
+        ),
+      }))
+      .filter((group) => group.skills.length > 0);
+
+    const items: Array<{ type: "header" | "skill"; group?: SkillGroup; skill?: SkillCommand }> = [];
+    for (const group of filteredGroups) {
+      items.push({ type: "header", group });
+      for (const skill of group.skills) {
+        items.push({ type: "skill", group, skill });
+      }
+    }
+
+    const total = skills.length;
+    return { flatItems: items, totalSkills: total };
+  }, [skillGroups, filterText, skills.length]);
+
+  // Reset when opened
+  useLayoutEffect(() => {
+    if (isActive) {
+      setFilterText("");
+      setSelectedIndex(0);
+      setShowDetails(false);
+      scrollOffsetRef.current = 0;
+      const ta = inputRef.current;
+      if (ta) {
+        ta.editBuffer.replaceText("");
+        ta.focus();
+      }
+    }
+  }, [isActive]);
+
+  // Get selected skill
+  const selectedItem = flatItems[selectedIndex];
+  const selectedSkill = selectedItem?.type === "skill" ? selectedItem.skill : null;
+
+  // Keyboard handling
+  useKeyboard((key) => {
+    if (!isActive) return;
+
+    if (key.ctrl && key.name === "p") {
+      key.preventDefault();
+      key.stopPropagation();
+      onClose();
+      return;
+    }
+
+    if (key.name === "escape") {
+      key.preventDefault();
+      key.stopPropagation();
+      onClose();
+      return;
+    }
+
+    if (key.name === "up" || key.name === "down") {
+      key.preventDefault();
+      key.stopPropagation();
+
+      const newIndex = key.name === "up"
+        ? Math.max(0, selectedIndex - 1)
+        : Math.min(flatItems.length - 1, selectedIndex + 1);
+
+      const newItem = flatItems[newIndex];
+      // Skip headers when navigating
+      if (newItem?.type === "header") {
+        setSelectedIndex(key.name === "up" ? Math.max(0, newIndex - 1) : Math.min(flatItems.length - 1, newIndex + 1));
+      } else {
+        setSelectedIndex(newIndex);
+      }
+
+      // Scroll handling
+      const currentScroll = scrollOffsetRef.current;
+      const newFlatIndex = flatItems.findIndex((item, idx) => idx === newIndex && item.type === "skill");
+      if (newFlatIndex !== -1) {
+        if (newFlatIndex < currentScroll) {
+          scrollOffsetRef.current = newFlatIndex;
+        } else if (newFlatIndex > currentScroll + listHeight - 1) {
+          scrollOffsetRef.current = newFlatIndex - listHeight + 1;
+        }
+      }
+      return;
+    }
+
+    if (key.name === "return" || key.name === "enter") {
+      key.preventDefault();
+      key.stopPropagation();
+      
+      if (selectedSkill) {
+        if (onInvokeSkill && selectedSkill.argumentHint) {
+          // Show details and allow typing arguments
+          setShowDetails(true);
+        } else if (onInvokeSkill) {
+          onInvokeSkill(selectedSkill, "");
+          onClose();
+        } else {
+          // Just close and show the skill was selected
+          onClose();
+        }
+      }
+      return;
+    }
+
+    if (key.name === "tab") {
+      key.preventDefault();
+      key.stopPropagation();
+      setShowDetails((prev) => !prev);
+      return;
+    }
+
+    if (key.name === "right") {
+      key.preventDefault();
+      key.stopPropagation();
+      if (selectedSkill) {
+        setShowDetails(true);
+      }
+      return;
+    }
+  });
+
+  const handleContentChange = () => {
+    const text = inputRef.current?.editBuffer.getText() ?? "";
+    setFilterText(text);
+    setSelectedIndex(0);
+    scrollOffsetRef.current = 0;
+  };
+
+  if (!isActive) return null;
+
+  const effectiveScrollOffset = scrollOffsetRef.current;
+  const visibleItems = flatItems.slice(effectiveScrollOffset, effectiveScrollOffset + listHeight);
+
+  // Render details panel
+  const renderDetails = () => {
+    if (!showDetails || !selectedSkill) return null;
+
+    const details = [
+      selectedSkill.description && `Description: ${selectedSkill.description}`,
+      selectedSkill.whenToUse && `When to use: ${selectedSkill.whenToUse}`,
+      selectedSkill.argumentHint && `Arguments: ${selectedSkill.argumentHint}`,
+      selectedSkill.allowedTools.length > 0 && `Allowed tools: ${selectedSkill.allowedTools.join(", ")}`,
+      selectedSkill.context && `Context: ${selectedSkill.context}`,
+    ].filter(Boolean);
+
+    return (
+      <box height={detailsHeight} flexDirection="column" marginTop={1}>
+        <box height={1}>
+          <text fg="#6272a4">
+            {"─".repeat(panelWidth - 4)}
+          </text>
+        </box>
+        {details.map((line, idx) => (
+          <box key={idx} height={1}>
+            <text fg="#8be9fd" wrapMode="none">{line}</text>
+          </box>
+        ))}
+      </box>
+    );
+  };
+
+  return (
+    <box
+      position="absolute"
+      top={0}
+      left={0}
+      width="100%"
+      height="100%"
+      backgroundColor="#00000080"
+      alignItems="center"
+      justifyContent="center"
+    >
+      <box
+        width={panelWidth}
+        height={panelHeight}
+        flexDirection="column"
+        borderStyle="rounded"
+        borderColor="#6272a4"
+        backgroundColor="#282a36"
+        paddingX={1}
+        paddingY={1}
+      >
+        {/* Header */}
+        <box height={1} flexDirection="row" justifyContent="space-between">
+          <text fg="#ff79c6" attributes={createTextAttributes({ bold: true })}>
+            Skills ({totalSkills})
+          </text>
+          <text fg="#6272a4">
+            ↑↓ navigate · Enter select · Tab details · Esc close
+          </text>
+        </box>
+
+        {/* Filter input */}
+        <box height={inputHeight} marginTop={1}>
+          <text fg="#6272a4">Filter: </text>
+          <textarea
+            ref={inputRef}
+            initialValue=""
+            focused={isActive}
+            showCursor
+            height={1}
+            wrapMode="none"
+            width={panelWidth - 10}
+            textColor="#f8f8f2"
+            backgroundColor="#44475a"
+            onContentChange={handleContentChange}
+          />
+        </box>
+
+        {/* Separator */}
+        <box height={separatorHeight} marginTop={1}>
+          <text fg="#6272a4">
+            {"─".repeat(panelWidth - 2)}
+          </text>
+        </box>
+
+        {/* Skill list */}
+        <box height={listHeight} flexDirection="column" overflow="hidden">
+          {visibleItems.map((item, idx) => {
+            const flatIndex = effectiveScrollOffset + idx;
+
+            if (item.type === "header") {
+              return (
+                <box key={`h-${item.group?.source}-${flatIndex}`} height={1}>
+                  <text
+                    fg="#bd93f9"
+                    attributes={createTextAttributes({ bold: true })}
+                  >
+                    {item.group?.label}
+                  </text>
+                </box>
+              );
+            }
+
+            if (item.type === "skill" && item.skill) {
+              const isSelected = flatIndex === selectedIndex;
+              const safeDescription = (item.skill.description ?? "").slice(0, 50);
+              return (
+                <box
+                  key={`s-${item.skill.name}-${flatIndex}`}
+                  height={1}
+                  backgroundColor={isSelected ? "#44475a" : undefined}
+                  paddingLeft={2}
+                  flexDirection="row"
+                >
+                  <text fg="#ffb86c">/{item.skill.name}</text>
+                  <text fg="#6272a4">  {safeDescription}{item.skill.description && item.skill.description.length > 50 ? "..." : ""}</text>
+                </box>
+              );
+            }
+
+            return null;
+          })}
+          {flatItems.length === 0 && (
+            <box height={listHeight} alignItems="center" justifyContent="center">
+              <text fg="#6272a4">No skills found</text>
+            </box>
+          )}
+        </box>
+
+        {/* Details panel */}
+        {renderDetails()}
+      </box>
+    </box>
+  );
+}
+
+/**
+ * SkillsMenuStandalone - A standalone modal version that doesn't need isActive prop
+ */
+export function SkillsMenuStandalone({
+  skills,
+  onClose,
+  onInvokeSkill,
+}: {
+  skills: SkillCommand[];
+  onClose: () => void;
+  onInvokeSkill?: (skill: SkillCommand, args: string) => void;
+}) {
+  return (
+    <SkillsMenu
+      isActive={true}
+      onClose={onClose}
+      skills={skills}
+      onInvokeSkill={onInvokeSkill}
+    />
+  );
+}

package/src/skills/bundled/batch.ts

@@ -0,0 +1,106 @@
+/**
+ * Batch Skill
+ * 
+ * Orchestrate large-scale changes across multiple parallel agents.
+ * Adapted from Claude Code's batch skill.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const MIN_AGENTS = 3;
+const MAX_AGENTS = 20;
+
+const WORKER_INSTRUCTIONS = `After implementing the change:
+1. **Review** — Use /simplify to review and clean up changes
+2. **Test** — Run the project's test suite
+3. **Commit** — Commit changes with a clear message
+4. **Report** — End with a summary of what was done`;
+
+const NOT_A_GIT_REPO_MESSAGE = `This is not a git repository. The \`/batch\` command requires a git repo. Initialize a repo first, or run this from inside an existing one.`;
+
+const MISSING_INSTRUCTION_MESSAGE = `Provide an instruction describing the batch change you want to make.
+
+Examples:
+  /batch add TypeScript to all JavaScript files
+  /batch replace lodash with native equivalents
+  /batch add error handling to all API routes`;
+
+export function registerBatchSkill(): void {
+  registerBundledSkill({
+    name: "batch",
+    description:
+      "Plan and execute a large-scale change across multiple parallel agents.",
+    whenToUse:
+      "Use when making sweeping changes across many files that can be decomposed into independent parallel units.",
+    argumentHint: "<instruction>",
+    userInvocable: true,
+    disableModelInvocation: true,
+    async getPromptForCommand(args) {
+      const instruction = args.trim();
+      if (!instruction) {
+        return [{ type: "text", text: MISSING_INSTRUCTION_MESSAGE }];
+      }
+
+      const prompt = `# Batch: Parallel Work Orchestration
+
+You are orchestrating a large, parallelizable change across this codebase.
+
+## User Instruction
+
+${instruction}
+
+## Phase 1: Research and Plan
+
+1. **Understand the scope.** Research what files, patterns, and locations need to change.
+2. **Decompose into units.** Break the work into ${MIN_AGENTS}–${MAX_AGENTS} self-contained units. Each unit must:
+   - Be independently implementable
+   - Be mergeable without depending on another unit
+   - Be roughly uniform in size
+
+   Scale the count to the actual work: few files → closer to ${MIN_AGENTS}; many files → closer to ${MAX_AGENTS}.
+
+3. **Determine verification.** Figure out how to verify each change works:
+   - Run tests
+   - Check for linting errors
+   - Verify the change visually if applicable
+
+4. **Write the plan.** Include:
+   - Summary of scope
+   - Numbered list of work units with file lists
+   - Verification approach for each unit
+
+## Phase 2: Execute in Parallel
+
+Spawn one agent per work unit. Each agent should:
+- Have the full context of what to do
+- Know the files to modify
+- Understand the verification approach
+- Follow these instructions:
+
+\`\`\`
+${WORKER_INSTRUCTIONS}
+\`\`\`
+
+## Phase 3: Track Progress
+
+Track progress with a status table:
+
+| # | Unit | Status |
+|---|------|--------|
+| 1 | <title> | running |
+| 2 | <title> | done |
+
+As agents complete, update the status and summarize results.
+
+## Final Summary
+
+When all agents finish, provide a summary of:
+- How many units completed successfully
+- Any failures or issues encountered
+- Overall impact of the changes
+`;
+
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled/debug.ts

@@ -0,0 +1,86 @@
+/**
+ * Debug Skill
+ * 
+ * Enable debug logging and help diagnose issues in Koi.
+ * Adapted from Claude Code's debug skill.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+const DEFAULT_DEBUG_LINES_READ = 30;
+
+export function registerDebugSkill(): void {
+  registerBundledSkill({
+    name: "debug",
+    description:
+      "Enable debug logging for this session and help diagnose issues. Read debug logs and provide diagnostic information.",
+    allowedTools: ["Read", "Grep", "Glob"],
+    argumentHint: "[issue description]",
+    disableModelInvocation: true,
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      const prompt = `# Debug Skill
+
+Help the user debug an issue they're encountering in this Koi session.
+
+## Session Context
+
+Working directory: \`{{cwd}}\`
+Current time: {{timestamp}}
+
+## Issue Description
+
+${args || "The user did not describe a specific issue. Ask clarifying questions to understand what problem they are experiencing."}
+
+## Diagnostic Steps
+
+### 1. Gather Information
+Ask the user to describe:
+- What were you trying to do?
+- What happened instead?
+- When did this start happening?
+- What changed recently?
+
+### 2. Check Common Issues
+
+**Connection Issues:**
+- Is the API provider configured correctly?
+- Is the API key valid?
+- Is there a network connectivity issue?
+
+**Model Issues:**
+- Is the model ID correct?
+- Is the model available for this provider?
+- Are there rate limit errors?
+
+**Tool Issues:**
+- Are the required tools available?
+- Is there a permission issue?
+- Are there file system errors?
+
+### 3. Suggest Next Steps
+
+Based on the issue, suggest:
+- Configuration fixes
+- Alternative approaches
+- Commands to run for more diagnostics
+- Settings to check
+
+## Settings Files to Check
+
+- Koi Settings: \`~/.config/koi/settings.json\`
+- Pi Settings: \`~/.config/koi/pi/settings.json\`
+
+## Instructions
+
+1. Ask clarifying questions if the issue is unclear
+2. Read relevant configuration files
+3. Identify the root cause
+4. Provide specific, actionable fixes
+5. Explain what went wrong in plain language
+`;
+
+      return [{ type: "text", text: prompt }];
+    },
+  });
+}

package/src/skills/bundled/loremIpsum.ts

@@ -0,0 +1,101 @@
+/**
+ * Lorem Ipsum Skill
+ * 
+ * Generate filler text for testing long context handling.
+ */
+
+import { registerBundledSkill } from "../bundled.js";
+
+// Verified 1-token words (common English words)
+const ONE_TOKEN_WORDS = [
+  "the", "a", "an", "I", "you", "he", "she", "it", "we", "they",
+  "me", "him", "her", "us", "them", "my", "your", "his", "its", "our",
+  "this", "that", "what", "who", "is", "are", "was", "were", "be",
+  "been", "have", "has", "had", "do", "does", "did", "will", "would",
+  "can", "could", "may", "might", "must", "shall", "should", "make",
+  "made", "get", "got", "go", "went", "come", "came", "see", "saw",
+  "know", "take", "think", "look", "want", "use", "find", "give",
+  "tell", "work", "call", "try", "ask", "need", "feel", "seem",
+  "leave", "put", "time", "year", "day", "way", "man", "thing",
+  "life", "hand", "part", "place", "case", "point", "fact", "good",
+  "new", "first", "last", "long", "great", "little", "own", "other",
+  "old", "right", "big", "high", "small", "large", "next", "early",
+  "young", "few", "public", "bad", "same", "able", "in", "on", "at",
+  "to", "for", "of", "with", "from", "by", "about", "like", "through",
+  "over", "before", "between", "under", "since", "without", "and", "or",
+  "but", "if", "than", "because", "as", "until", "while", "so",
+  "though", "both", "each", "when", "where", "why", "how", "not",
+  "now", "just", "more", "also", "here", "there", "then", "only",
+  "very", "well", "back", "still", "even", "much", "too", "such",
+  "never", "again", "most", "once", "off", "away", "down", "out",
+  "up", "test", "code", "data", "file", "line", "text", "word",
+  "number", "system", "program", "set", "run", "value", "name",
+  "type", "state", "end", "start"
+];
+
+function generateLoremIpsum(targetTokens: number): string {
+  let tokens = 0;
+  let result = "";
+
+  while (tokens < targetTokens) {
+    const sentenceLength = 10 + Math.floor(Math.random() * 11);
+    let wordsInSentence = 0;
+
+    for (let i = 0; i < sentenceLength && tokens < targetTokens; i++) {
+      const word = ONE_TOKEN_WORDS[Math.floor(Math.random() * ONE_TOKEN_WORDS.length)];
+      result += word;
+      tokens++;
+      wordsInSentence++;
+
+      if (i === sentenceLength - 1 || tokens >= targetTokens) {
+        result += ". ";
+      } else {
+        result += " ";
+      }
+    }
+
+    // Paragraph break every 5-8 sentences
+    if (wordsInSentence > 0 && Math.random() < 0.2 && tokens < targetTokens) {
+      result += "\n\n";
+    }
+  }
+
+  return result.trim();
+}
+
+export function registerLoremIpsumSkill(): void {
+  registerBundledSkill({
+    name: "lorem-ipsum",
+    description:
+      "Generate filler text for long context testing. Specify token count as argument (e.g., /lorem-ipsum 50000).",
+    argumentHint: "[token_count]",
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      const parsed = parseInt(args);
+
+      if (args && (isNaN(parsed) || parsed <= 0)) {
+        return [
+          {
+            type: "text",
+            text: "Invalid token count. Please provide a positive number (e.g., /lorem-ipsum 10000).",
+          },
+        ];
+      }
+
+      const targetTokens = parsed || 10000;
+      const cappedTokens = Math.min(targetTokens, 500_000);
+
+      if (cappedTokens < targetTokens) {
+        return [
+          {
+            type: "text",
+            text: `Requested ${targetTokens} tokens, but capped at 500,000 for safety.\n\n${generateLoremIpsum(cappedTokens)}`,
+          },
+        ];
+      }
+
+      const loremText = generateLoremIpsum(cappedTokens);
+      return [{ type: "text", text: loremText }];
+    },
+  });
+}