capyai 0.3.3 → 0.3.5

package/AGENTS.md

@@ -0,0 +1,228 @@
+# Agent Setup
+
+You are an AI agent. Follow every step below to install and configure capyai. Do not skip steps. Run every command.
+
+## Step 1: Prerequisites
+
+```bash
+command -v bun >/dev/null 2>&1 || { curl -fsSL https://bun.sh/install | bash && export PATH="$HOME/.bun/bin:$PATH"; }
+command -v gh >/dev/null 2>&1 || echo "WARN: GitHub CLI (gh) not found. Quality gates need it. Install: https://cli.github.com"
+command -v jq >/dev/null 2>&1 || echo "WARN: jq not found. JSON parsing in shell needs it."
+```
+
+## Step 2: Install
+
+```bash
+bun i -g capyai
+```
+
+Verify: `capy --version` should print a version number.
+
+## Step 3: Configure
+
+Ask the user for their Capy API key (`capy_...`). They get it from https://capy.ai/settings/api-keys.
+
+Once you have the key, write the config:
+
+```bash
+mkdir -p ~/.capy
+
+# Fetch the user's project ID automatically
+export CAPY_API_KEY="<key from user>"
+PROJECT_ID=$(curl -s -H "Authorization: Bearer $CAPY_API_KEY" https://capy.ai/api/v1/projects | jq -r '.items[0].id')
+
+cat > ~/.capy/config.json << EOF
+{
+  "apiKey": "$CAPY_API_KEY",
+  "projectId": "$PROJECT_ID",
+  "server": "https://capy.ai/api/v1",
+  "defaultModel": "gpt-5.4",
+  "quality": {
+    "reviewProvider": "greptile",
+    "requireCI": true,
+    "requireTests": true
+  }
+}
+EOF
+```
+
+Verify: `capy status --json` should return `{ "threads": [...], "tasks": [...] }`.
+
+If it returns `{ "error": ... }`, the API key or project ID is wrong. Ask the user.
+
+## Step 4: Install skill
+
+```bash
+npx skills add yazcaleb/capy-cli
+```
+
+This adds the `capy` skill to your skills directory so you have the full command reference available in context.
+
+## Step 5: MCP server (if you support MCP)
+
+Add this to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "capy": {
+      "command": "capy-mcp",
+      "env": {
+        "CAPY_API_KEY": "<same key>",
+        "CAPY_PROJECT_ID": "<same project ID>"
+      }
+    }
+  }
+}
+```
+
+Config file locations:
+- Claude Code: `~/.claude.json` (global) or `.claude/settings.json` (project)
+- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+- Cursor: `.cursor/mcp.json`
+
+14 MCP tools with full CLI parity:
+
+| Tool | What it does | Annotations |
+|------|-------------|-------------|
+| `capy_captain` | Start Captain thread | openWorld |
+| `capy_build` | Start Build agent | openWorld |
+| `capy_wait` | Block until done | readOnly, idempotent |
+| `capy_review` | Run quality gates | readOnly |
+| `capy_approve` | Approve task | openWorld |
+| `capy_retry` | Retry with context | openWorld |
+| `capy_status` | Task/thread details or dashboard | readOnly, idempotent |
+| `capy_list` | List tasks (filterable) | readOnly, idempotent |
+| `capy_threads` | List threads | readOnly, idempotent |
+| `capy_diff` | View diff | readOnly |
+| `capy_msg` | Message task/thread | openWorld |
+| `capy_stop` | Stop task/thread | destructive |
+| `capy_pr` | Create PR | openWorld |
+| `capy_models` | List models | readOnly, idempotent |
+
+Tools with predictable outputs (`capy_captain`, `capy_build`, `capy_review`, `capy_approve`, `capy_retry`) declare `outputSchema` for typed structured content per the 2025-03-26 MCP spec.
+
+If you don't support MCP, skip this step. The CLI works everywhere.
+
+## Step 6: Verify everything
+
+Run all of these. Every one must succeed:
+
+```bash
+capy --version
+capy status --json
+capy models --json
+```
+
+You are now fully configured.
+
+---
+
+## How to use capyai
+
+### Delegate work
+
+```bash
+capy captain "Implement feature X. Files: src/foo.ts. Tests required." --json
+```
+
+Returns `{ "threadId": "...", "url": "..." }`. Save the `threadId`.
+
+### Wait for completion
+
+```bash
+capy wait <threadId> --timeout=600 --json
+```
+
+Blocks until the thread reaches a terminal state. Returns the full thread object with `tasks` array. Each task has an `identifier` (like `SCO-1`).
+
+### Review quality
+
+```bash
+capy review <taskId> --json
+```
+
+Returns `{ "task": "SCO-1", "quality": { "pass": true, "passed": 5, "total": 5, "gates": [...] } }`.
+
+Read `quality.pass`. If `true`, approve. If `false`, read `quality.gates` for what failed.
+
+### Approve or retry
+
+```bash
+# If quality.pass is true:
+capy approve <taskId> --json
+
+# If quality.pass is false:
+capy retry <taskId> --fix="describe what to fix" --json
+```
+
+`retry` returns `{ "newThread": "..." }`. Wait on that new thread ID, then review again.
+
+### The full loop
+
+```bash
+THREAD=$(capy captain "your prompt" --json | jq -r '.threadId')
+capy wait "$THREAD" --timeout=600 --json
+
+TASK=$(capy threads get "$THREAD" --json | jq -r '.tasks[0].identifier')
+QUALITY=$(capy review "$TASK" --json)
+PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
+
+while [ "$PASS" != "true" ]; do
+  GATES=$(echo "$QUALITY" | jq -r '.quality.gates[] | select(.pass == false) | .name + ": " + .detail')
+  NEW=$(capy retry "$TASK" --fix="Fix these failures: $GATES" --json | jq -r '.newThread')
+  capy wait "$NEW" --timeout=600 --json
+  TASK=$(capy threads get "$NEW" --json | jq -r '.tasks[0].identifier')
+  QUALITY=$(capy review "$TASK" --json)
+  PASS=$(echo "$QUALITY" | jq -r '.quality.pass')
+done
+
+capy approve "$TASK" --json
+```
+
+### Background monitoring
+
+For async fire-and-forget work. Sets a cron job that polls and runs your notification command when done.
+
+```bash
+capy watch <threadId>
+capy config notifyCommand "<your notification command> {text}"
+```
+
+`{text}` is replaced with a summary when the task completes. Examples:
+- `openclaw system event --text {text} --mode now`
+- `echo {text} >> ~/capy-notifications.log`
+
+List watches: `capy watches --json`. Remove: `capy unwatch <id>`.
+
+### All commands
+
+Every command supports `--json` for structured output. Errors always return `{ "error": { "code": "...", "message": "..." } }`.
+
+| Command | What it does |
+|---------|-------------|
+| `capy captain "<prompt>"` | Start Captain thread |
+| `capy build "<prompt>"` | Start Build agent (small isolated tasks) |
+| `capy wait <id> --timeout=N` | Block until terminal state |
+| `capy review <id>` | Run quality gates (pass/fail) |
+| `capy approve <id>` | Approve if gates pass |
+| `capy retry <id> --fix="..."` | Retry with context |
+| `capy status` | Dashboard |
+| `capy list [status]` | List tasks |
+| `capy get <id>` | Task or thread details |
+| `capy diff <id>` | View diff |
+| `capy pr <id>` | Create PR |
+| `capy watch <id>` | Cron poll + notify |
+| `capy threads list` | List threads |
+| `capy threads get <id>` | Thread details |
+| `capy threads msg <id> "<text>"` | Message a thread |
+| `capy config [key] [value]` | Get/set config |
+| `capy models` | List available models |
+
+### Prompting tips
+
+Bad: `"Fix the CI issue"`
+
+Good: `"Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading. Run changeset validation. Reference: PLW-201."`
+
+Always include: specific files, specific functions, acceptance criteria, references to related tasks/issues.

package/README.md

@@ -1,24 +1,19 @@
 # capyai
 
-Agent orchestrator with quality gates for [Capy.ai](https://capy.ai).
+Agent orchestrator with quality gates for [Capy.ai](https://capy.ai). Lets any AI agent delegate coding work to Capy agents, wait for completion, enforce quality, and approve or retry.
 
-Works with Claude Code, Codex, OpenClaw, Poke, or any AI agent that can run shell commands.
+Works with Claude Code, Codex, OpenClaw, Poke, or any agent that runs shell commands.
 
-## Install
-
-```bash
-npm i -g capyai
-capy init
-```
+**AI agent?** Read [AGENTS.md](AGENTS.md) and follow every step.
 
-Or set env vars directly:
+## Install
 
 ```bash
-export CAPY_API_KEY=capy_...
-export CAPY_PROJECT_ID=...
+npm i -g capyai    # or: bun i -g capyai
+capy init          # interactive setup
 ```
 
-Requires [Bun](https://bun.sh) runtime and GitHub CLI (`gh`) for quality gate checks.
+Requires [Bun](https://bun.sh) runtime and [GitHub CLI](https://cli.github.com) (`gh`) for quality gate checks.
 
 ## Usage
 
@@ -42,37 +37,25 @@ capy retry <task-id> --fix="fix the failing test"
 
 Every command supports `--json` for machine-readable output.
 
-## For Agents
-
-The core orchestration loop:
-
-```bash
-capy captain "precise prompt" --json        # start work
-capy wait <thread-id> --timeout=600 --json  # block until done
-capy review <task-id> --json                # check quality gates
-capy approve <task-id> --json               # approve if gates pass
-capy retry <task-id> --fix="..." --json     # or retry with context
-```
-
-### MCP Server
-
-For agents that prefer MCP (Cursor, some Codex configs):
-
-```json
-{
-  "mcpServers": {
-    "capy": {
-      "command": "capy-mcp"
-    }
-  }
-}
-```
-
-### Skills.sh
-
-```bash
-npx skills add yazcaleb/capy-cli
-```
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `capy captain "<prompt>"` | Start Captain thread (primary agent) |
+| `capy build "<prompt>"` | Start Build agent (isolated, small tasks) |
+| `capy wait <id>` | Block until task/thread reaches terminal state |
+| `capy review <id>` | Run quality gates |
+| `capy approve <id>` | Approve if all gates pass |
+| `capy retry <id> --fix="..."` | Retry with failure context |
+| `capy status` | Dashboard of threads and tasks |
+| `capy list [status]` | List tasks, optionally filtered |
+| `capy get <id>` | Task or thread details |
+| `capy diff <id>` | View diff |
+| `capy pr <id>` | Create PR for task |
+| `capy watch <id>` | Cron poll + notify on completion |
+| `capy threads [list\|get\|msg\|stop]` | Manage Captain threads |
+| `capy models` | List available models |
+| `capy config [key] [value]` | Get/set config |
 
 ## Quality Gates
 
@@ -88,7 +71,23 @@ npx skills add yazcaleb/capy-cli
 | `threads` | No unresolved review threads |
 | `tests` | Diff includes test files |
 
-Configure via `capy config quality.reviewProvider greptile|capy|both|none`.
+Configure with `capy config quality.reviewProvider greptile|capy|both|none`.
+
+## MCP Server
+
+For agents that prefer MCP over CLI:
+
+```json
+{
+  "mcpServers": {
+    "capy": {
+      "command": "capy-mcp"
+    }
+  }
+}
+```
+
+14 tools with full CLI parity: `capy_captain`, `capy_build`, `capy_wait`, `capy_review`, `capy_approve`, `capy_retry`, `capy_status`, `capy_list`, `capy_threads`, `capy_diff`, `capy_msg`, `capy_stop`, `capy_pr`, `capy_models`.
 
 ## Config
 
@@ -96,10 +95,19 @@ Configure via `capy config quality.reviewProvider greptile|capy|both|none`.
 capy config defaultModel gpt-5.4
 capy config quality.reviewProvider both
 capy config notifyCommand "notify-send {text}"
+capy config approveCommand "your-hook {task} {pr}"
 ```
 
 Env vars: `CAPY_API_KEY`, `CAPY_PROJECT_ID`, `CAPY_SERVER`, `CAPY_ENV_FILE`, `GREPTILE_API_KEY`.
 
+Config file: `~/.capy/config.json`.
+
+## Skills.sh
+
+```bash
+npx skills add yazcaleb/capy-cli
+```
+
 ## License
 
 MIT

package/bin/capy.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 
-import { defineCommand, runMain } from "citty";
+import { defineCommand, runCommand } from "citty";
 import { createRequire } from "node:module";
+import { CapyError } from "../src/api.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -40,4 +41,22 @@ const main = defineCommand({
   },
 });
 
-runMain(main);
+try {
+  const args = process.argv.slice(2);
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(version);
+    process.exit(0);
+  }
+  await runCommand(main, { rawArgs: args });
+} catch (e) {
+  if (e instanceof CapyError) {
+    if (process.argv.includes("--json")) {
+      console.log(JSON.stringify({ error: { code: e.code, message: e.message } }));
+    } else {
+      console.error(`capy: ${e.message}`);
+    }
+    process.exit(1);
+  }
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capyai",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "Unofficial Capy.ai CLI for agent orchestration with quality gates",
   "bin": {
@@ -13,7 +13,8 @@
   "files": [
     "bin/",
     "src/",
-    "skills/"
+    "skills/",
+    "AGENTS.md"
   ],
   "engines": {
     "node": ">=18"
@@ -35,7 +36,7 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "citty": "^0.2.2",
     "zod": "^3.24.0"
   }

package/skills/capy/SKILL.md

@@ -3,7 +3,7 @@ name: capy
 description: Orchestrate Capy.ai coding agents with quality gates. Delegate coding work, wait for completion, review quality, approve or retry.
 metadata:
   author: yazcaleb
-  version: "0.3.2"
+  version: "0.3.5"
 ---
 
 # capy

package/src/api.ts

@@ -1,14 +1,17 @@
 import * as config from "./config.js";
-import { IS_JSON } from "./output.js";
 import type { Task, Thread, ThreadMessage, DiffData, Model, ListResponse, PullRequestRef } from "./types.js";
 
-function fail(code: string, message: string): never {
-  if (IS_JSON) {
-    console.log(JSON.stringify({ error: { code, message } }));
-  } else {
-    console.error(`capy: ${message}`);
+export class CapyError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    this.name = "CapyError";
   }
-  process.exit(1);
+}
+
+function fail(code: string, message: string): never {
+  throw new CapyError(code, message);
 }
 
 async function rawRequest(apiKey: string, server: string, method: string, path: string, body?: unknown): Promise<any> {

package/src/commands/diff-pr.ts

@@ -29,7 +29,7 @@ export const pr = defineCommand({
   meta: { name: "pr", description: "Create a PR" },
   args: {
     id: { type: "positional", description: "Task ID", required: true },
-    title: { type: "positional", description: "PR title" },
+    title: { type: "positional", required: false, description: "PR title" },
     ...jsonArg,
   },
   async run({ args }) {

package/src/commands/monitoring.ts

@@ -99,7 +99,7 @@ export const _poll = defineCommand({
   meta: { name: "_poll", description: "Internal cron poll", hidden: true },
   args: {
     id: { type: "positional", description: "ID", required: true },
-    type: { type: "positional", description: "task or thread" },
+    type: { type: "positional", required: false, description: "task or thread" },
   },
   async run({ args }) {
     const api = await import("../api.js");

package/src/commands/setup.ts

@@ -102,8 +102,8 @@ export const init = defineCommand({
 export const config = defineCommand({
   meta: { name: "config", description: "Get/set config" },
   args: {
-    key: { type: "positional", description: "Config key (dot notation)" },
-    value: { type: "positional", description: "Value to set" },
+    key: { type: "positional", required: false, description: "Config key (dot notation)" },
+    value: { type: "positional", required: false, description: "Value to set" },
     ...jsonArg,
   },
   async run({ args }) {

package/src/commands/tasks.ts

@@ -4,7 +4,7 @@ import { modelArgs, jsonArg, resolveModel } from "./_shared.js";
 export const list = defineCommand({
   meta: { name: "list", description: "List tasks", alias: "ls" },
   args: {
-    status: { type: "positional", description: "Filter by status" },
+    status: { type: "positional", required: false, description: "Filter by status" },
     ...jsonArg,
   },
   async run({ args }) {
@@ -84,7 +84,7 @@ export const stop = defineCommand({
   meta: { name: "stop", description: "Stop a task", alias: "kill" },
   args: {
     id: { type: "positional", description: "Task ID", required: true },
-    reason: { type: "positional", description: "Stop reason" },
+    reason: { type: "positional", required: false, description: "Stop reason" },
     ...jsonArg,
   },
   async run({ args }) {

package/src/mcp.ts

@@ -3,133 +3,327 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { createRequire } from "node:module";
 import * as api from "./api.js";
+import { CapyError } from "./api.js";
 import * as config from "./config.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 
-const server = new McpServer({
-  name: "capy",
-  version,
-});
+const server = new McpServer({ name: "capy", version });
+
+function err(e: unknown) {
+  const error = e instanceof CapyError
+    ? { code: e.code, message: e.message }
+    : { code: "internal", message: e instanceof Error ? e.message : String(e) };
+  return { content: [{ type: "text" as const, text: JSON.stringify({ error }) }], isError: true as const };
+}
+
+function text(data: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(data) }] };
+}
+
+function structured(data: Record<string, unknown>) {
+  return { structuredContent: data, content: [{ type: "text" as const, text: JSON.stringify(data) }] };
+}
 
-server.tool("capy_captain", "Start a Captain thread to delegate coding work", {
-  prompt: z.string().describe("What the agent should do. Be specific: files, functions, acceptance criteria."),
-  model: z.string().optional().describe("Model ID override"),
+function isThreadId(id: string): boolean {
+  return id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
+}
+
+// --- Orchestration ---
+
+server.registerTool("capy_captain", {
+  description: "Start a Captain thread to delegate coding work to a Capy agent",
+  inputSchema: {
+    prompt: z.string().describe("What the agent should do. Be specific: files, functions, acceptance criteria."),
+    model: z.string().optional().describe("Model ID override (default: config defaultModel)"),
+  },
+  outputSchema: {
+    threadId: z.string(),
+    url: z.string(),
+  },
+  annotations: { openWorldHint: true },
 }, async ({ prompt, model }) => {
-  const cfg = config.load();
-  const data = await api.createThread(prompt, model);
-  return { content: [{ type: "text", text: JSON.stringify({ threadId: data.id, url: `https://capy.ai/project/${cfg.projectId}/captain/${data.id}` }) }] };
+  try {
+    const cfg = config.load();
+    const data = await api.createThread(prompt, model);
+    return structured({ threadId: data.id, url: `https://capy.ai/project/${cfg.projectId}/captain/${data.id}` });
+  } catch (e) { return err(e); }
 });
 
-server.tool("capy_status", "Get task or thread status, or full dashboard", {
-  id: z.string().optional().describe("Task or thread ID. Omit for dashboard."),
-}, async ({ id }) => {
-  if (id) {
-    const isThread = id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
-    const data: any = isThread ? await api.getThread(id) : await api.getTask(id);
-    // Capy API reports merged PRs as "closed". Cross-ref with GitHub for real state.
-    if (!isThread && data.pullRequest?.number && data.pullRequest.state === "closed") {
-      const { getPR } = await import("./github.js");
-      const cfg = config.load();
-      const repo = data.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
-      if (repo) {
-        const ghPR = getPR(repo, data.pullRequest.number);
-        if (ghPR) data.pullRequest.state = ghPR.state.toLowerCase();
-      }
+server.registerTool("capy_build", {
+  description: "Start a Build agent for small isolated tasks (single-file fixes, scripts)",
+  inputSchema: {
+    prompt: z.string().describe("What to build. Be specific."),
+    model: z.string().optional().describe("Model ID override"),
+    title: z.string().optional().describe("Short task title"),
+  },
+  outputSchema: {
+    id: z.string(),
+    identifier: z.string(),
+    status: z.string(),
+  },
+  annotations: { openWorldHint: true },
+}, async ({ prompt, model, title }) => {
+  try {
+    const data = await api.createTask(prompt, model, { title, start: true });
+    return structured({ id: data.id, identifier: data.identifier, status: data.status });
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_wait", {
+  description: "Block until a task or thread reaches terminal state (needs_review, completed, failed, idle, archived)",
+  inputSchema: {
+    id: z.string().describe("Task or thread ID"),
+    timeout: z.number().optional().describe("Timeout in seconds (default 300)"),
+    interval: z.number().optional().describe("Poll interval in seconds (default 10)"),
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async ({ id, timeout, interval }) => {
+  try {
+    const timeoutMs = (timeout || 300) * 1000;
+    const intervalMs = Math.max(5, Math.min(interval || 10, 60)) * 1000;
+    const isThread = isThreadId(id);
+    const terminal = isThread
+      ? new Set(["idle", "archived", "completed"])
+      : new Set(["needs_review", "archived", "completed", "failed"]);
+
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const data = isThread ? await api.getThread(id) : await api.getTask(id);
+      if (terminal.has(data.status)) return text(data);
+      await new Promise(r => setTimeout(r, intervalMs));
     }
-    return { content: [{ type: "text", text: JSON.stringify(data) }] };
-  }
-  const [threads, tasks] = await Promise.all([api.listThreads({ limit: 10 }), api.listTasks({ limit: 30 })]);
-  return { content: [{ type: "text", text: JSON.stringify({ threads: threads.items || [], tasks: tasks.items || [] }) }] };
+    return { content: [{ type: "text" as const, text: JSON.stringify({ error: { code: "timeout", message: `Timed out after ${timeout || 300}s` } }) }], isError: true as const };
+  } catch (e) { return err(e); }
 });
 
-server.tool("capy_review", "Run quality gates on a task", {
-  id: z.string().describe("Task ID"),
+server.registerTool("capy_review", {
+  description: "Run quality gates on a task (pr_exists, pr_open, ci, greptile, threads, tests)",
+  inputSchema: {
+    id: z.string().describe("Task ID"),
+  },
+  outputSchema: {
+    task: z.string(),
+    quality: z.object({
+      pass: z.boolean(),
+      passed: z.number(),
+      total: z.number(),
+      summary: z.string(),
+    }),
+  },
+  annotations: { readOnlyHint: true },
 }, async ({ id }) => {
-  const qualityEngine = await import("./quality-engine.js");
-  const task = await api.getTask(id);
-  if (!task.pullRequest?.number) {
-    return { content: [{ type: "text", text: JSON.stringify({ error: "no_pr", task: task.identifier }) }] };
-  }
-  const q = await qualityEngine.check(task);
-  return { content: [{ type: "text", text: JSON.stringify({ task: task.identifier, quality: q }) }] };
+  try {
+    const qualityEngine = await import("./quality-engine.js");
+    const task = await api.getTask(id);
+    if (!task.pullRequest?.number) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ error: { code: "no_pr", message: `Task ${task.identifier} has no PR` } }) }], isError: true as const };
+    }
+    const q = await qualityEngine.check(task);
+    return structured({ task: task.identifier, quality: q as unknown as Record<string, unknown> });
+  } catch (e) { return err(e); }
 });
 
-server.tool("capy_approve", "Approve a task if quality gates pass. Runs the configured approveCommand hook on success.", {
-  id: z.string().describe("Task ID"),
-  force: z.boolean().optional().describe("Override failing gates"),
+server.registerTool("capy_approve", {
+  description: "Approve a task if quality gates pass. Runs approveCommand hook on success.",
+  inputSchema: {
+    id: z.string().describe("Task ID"),
+    force: z.boolean().optional().describe("Override failing gates"),
+  },
+  outputSchema: {
+    task: z.string(),
+    approved: z.boolean(),
+  },
+  annotations: { openWorldHint: true },
 }, async ({ id, force }) => {
-  const qualityEngine = await import("./quality-engine.js");
-  const task = await api.getTask(id);
-  const cfg = config.load();
-  const q = await qualityEngine.check(task);
-  const approved = q.pass || !!force;
+  try {
+    const qualityEngine = await import("./quality-engine.js");
+    const task = await api.getTask(id);
+    const cfg = config.load();
+    const q = await qualityEngine.check(task);
+    const approved = q.pass || !!force;
+
+    if (approved && cfg.approveCommand) {
+      try {
+        const { execFileSync } = await import("node:child_process");
+        const parts = cfg.approveCommand
+          .replace("{task}", task.identifier || task.id)
+          .replace("{title}", task.title || "")
+          .replace("{pr}", String(task.pullRequest?.number || ""))
+          .split(/\s+/);
+        execFileSync(parts[0], parts.slice(1), { encoding: "utf8", timeout: 15000, stdio: "pipe" });
+      } catch {}
+    }
 
-  if (approved && cfg.approveCommand) {
+    return structured({ task: task.identifier, quality: q as unknown as Record<string, unknown>, approved });
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_retry", {
+  description: "Retry a failed task with context from previous attempt. Creates a new Captain thread.",
+  inputSchema: {
+    id: z.string().describe("Task ID to retry"),
+    fix: z.string().optional().describe("Specific fix instructions"),
+    model: z.string().optional().describe("Model ID override"),
+  },
+  outputSchema: {
+    originalTask: z.string(),
+    newThread: z.string(),
+    model: z.string(),
+  },
+  annotations: { openWorldHint: true },
+}, async ({ id, fix, model }) => {
+  try {
+    const task = await api.getTask(id);
+    const cfg = config.load();
+
+    let context = `Previous attempt: ${task.identifier} "${task.title}" [${task.status}]\n`;
     try {
-      const { execFileSync } = await import("node:child_process");
-      const parts = cfg.approveCommand
-        .replace("{task}", task.identifier || task.id)
-        .replace("{title}", task.title || "")
-        .replace("{pr}", String(task.pullRequest?.number || ""))
-        .split(/\s+/);
-      execFileSync(parts[0], parts.slice(1), { encoding: "utf8", timeout: 15000, stdio: "pipe" });
+      const d = await api.getDiff(id);
+      if (d.stats?.files && d.stats.files > 0) {
+        context += `\nPrevious diff: +${d.stats.additions} -${d.stats.deletions} in ${d.stats.files} files\n`;
+      }
     } catch {}
-  }
 
-  return { content: [{ type: "text", text: JSON.stringify({ task: task.identifier, quality: q, approved }) }] };
+    let retryPrompt = `RETRY: This is a retry of a previous attempt that had issues.\n\nOriginal task: ${task.prompt || task.title}\n\n--- CONTEXT ---\n${context}\n`;
+    if (fix) retryPrompt += `--- FIX ---\n${fix}\n\n`;
+    retryPrompt += `Fix the issues. Include tests. Run tests before completing.\n`;
+
+    if (task.status === "in_progress") {
+      await api.stopTask(id, "Retrying with fixes");
+    }
+
+    const m = model || cfg.defaultModel;
+    const data = await api.createThread(retryPrompt, m);
+    return structured({ originalTask: task.identifier, newThread: data.id, model: m });
+  } catch (e) { return err(e); }
 });
 
-server.tool("capy_retry", "Retry a failed task with context from previous attempt", {
-  id: z.string().describe("Task ID to retry"),
-  fix: z.string().optional().describe("Specific fix instructions"),
-  model: z.string().optional().describe("Model ID override"),
-}, async ({ id, fix, model }) => {
-  const task = await api.getTask(id);
-  const cfg = config.load();
+// --- Status & monitoring ---
 
-  let context = `Previous attempt: ${task.identifier} "${task.title}" [${task.status}]\n`;
+server.registerTool("capy_status", {
+  description: "Get task or thread details by ID, or full dashboard (omit ID for dashboard)",
+  inputSchema: {
+    id: z.string().optional().describe("Task or thread ID. Omit for dashboard."),
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async ({ id }) => {
   try {
-    const d = await api.getDiff(id);
-    if (d.stats?.files && d.stats.files > 0) {
-      context += `\nPrevious diff: +${d.stats.additions} -${d.stats.deletions} in ${d.stats.files} files\n`;
+    if (id) {
+      const isThread = isThreadId(id);
+      const data: any = isThread ? await api.getThread(id) : await api.getTask(id);
+      if (!isThread && data.pullRequest?.number && data.pullRequest.state === "closed") {
+        const { getPR } = await import("./github.js");
+        const cfg = config.load();
+        const repo = data.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
+        if (repo) {
+          const ghPR = getPR(repo, data.pullRequest.number);
+          if (ghPR) data.pullRequest.state = ghPR.state.toLowerCase();
+        }
+      }
+      return text(data);
     }
-  } catch {}
+    const [threads, tasks] = await Promise.all([api.listThreads({ limit: 10 }), api.listTasks({ limit: 30 })]);
+    return text({ threads: threads.items || [], tasks: tasks.items || [] });
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_list", {
+  description: "List tasks, optionally filtered by status (in_progress, needs_review, backlog, archived)",
+  inputSchema: {
+    status: z.string().optional().describe("Filter by status"),
+    limit: z.number().optional().describe("Max results (default 30)"),
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async ({ status, limit }) => {
+  try {
+    const data = await api.listTasks({ status, limit: limit || 30 });
+    return text(data.items || []);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_threads", {
+  description: "List Captain threads",
+  inputSchema: {
+    limit: z.number().optional().describe("Max results (default 10)"),
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async ({ limit }) => {
+  try {
+    const data = await api.listThreads({ limit: limit || 10 });
+    return text(data.items || []);
+  } catch (e) { return err(e); }
+});
 
-  let retryPrompt = `RETRY: This is a retry of a previous attempt that had issues.\n\nOriginal task: ${task.prompt || task.title}\n\n--- CONTEXT ---\n${context}\n`;
-  if (fix) retryPrompt += `--- FIX ---\n${fix}\n\n`;
-  retryPrompt += `Fix the issues. Include tests. Run tests before completing.\n`;
+server.registerTool("capy_diff", {
+  description: "View the diff (code changes) from a task",
+  inputSchema: {
+    id: z.string().describe("Task ID"),
+  },
+  annotations: { readOnlyHint: true },
+}, async ({ id }) => {
+  try {
+    const data = await api.getDiff(id);
+    return text(data);
+  } catch (e) { return err(e); }
+});
 
-  if (task.status === "in_progress") {
-    await api.stopTask(id, "Retrying with fixes");
-  }
+// --- Actions ---
 
-  const data = await api.createThread(retryPrompt, model || cfg.defaultModel);
-  return { content: [{ type: "text", text: JSON.stringify({ originalTask: task.identifier, newThread: data.id, model: model || cfg.defaultModel }) }] };
+server.registerTool("capy_msg", {
+  description: "Send a message to a running task or thread",
+  inputSchema: {
+    id: z.string().describe("Task or thread ID"),
+    text: z.string().describe("Message text"),
+  },
+  annotations: { openWorldHint: true },
+}, async ({ id, text: msg }) => {
+  try {
+    const isThread = isThreadId(id);
+    const result = isThread ? await api.messageThread(id, msg) : await api.messageTask(id, msg);
+    return text({ id, sent: true, type: isThread ? "thread" : "task", ...(result && typeof result === "object" ? result as Record<string, unknown> : {}) });
+  } catch (e) { return err(e); }
 });
 
-server.tool("capy_wait", "Poll until a task or thread reaches terminal state", {
-  id: z.string().describe("Task or thread ID"),
-  timeout: z.number().optional().describe("Timeout in seconds (default 300)"),
-  interval: z.number().optional().describe("Poll interval in seconds (default 10)"),
-}, async ({ id, timeout, interval }) => {
-  const timeoutMs = (timeout || 300) * 1000;
-  const intervalMs = Math.max(5, Math.min(interval || 10, 60)) * 1000;
-  const isThread = id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
-  const terminalTask = new Set(["needs_review", "archived", "completed", "failed"]);
-  const terminalThread = new Set(["idle", "archived", "completed"]);
-  const terminal = isThread ? terminalThread : terminalTask;
-
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    const data = isThread ? await api.getThread(id) : await api.getTask(id);
-    if (terminal.has(data.status)) {
-      return { content: [{ type: "text", text: JSON.stringify(data) }] };
-    }
-    await new Promise(r => setTimeout(r, intervalMs));
-  }
-  return { content: [{ type: "text", text: JSON.stringify({ error: { code: "timeout", message: `Timed out after ${timeout || 300}s` } }) }] };
+server.registerTool("capy_stop", {
+  description: "Stop a running task or thread",
+  inputSchema: {
+    id: z.string().describe("Task or thread ID"),
+    reason: z.string().optional().describe("Reason for stopping"),
+  },
+  annotations: { destructiveHint: true },
+}, async ({ id, reason }) => {
+  try {
+    const isThread = isThreadId(id);
+    const result = isThread ? await api.stopThread(id) : await api.stopTask(id, reason);
+    return text(result);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_pr", {
+  description: "Create a pull request for a completed task",
+  inputSchema: {
+    id: z.string().describe("Task ID"),
+    title: z.string().optional().describe("PR title override"),
+  },
+  annotations: { openWorldHint: true },
+}, async ({ id, title }) => {
+  try {
+    const data = await api.createPR(id, title ? { title } : {});
+    return text(data);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_models", {
+  description: "List available AI models",
+  inputSchema: {},
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async () => {
+  try {
+    const data = await api.listModels();
+    return text(data.models || []);
+  } catch (e) { return err(e); }
 });
 
 const transport = new StdioServerTransport();

package/src/watch.ts

@@ -18,7 +18,7 @@ export function add(id: string, type: string, intervalMin: number): boolean {
 
   const thisDir = path.dirname(new URL(import.meta.url).pathname);
   const binPath = path.resolve(thisDir, "..", "bin", "capy.ts");
-  const runtime = typeof Bun !== "undefined" ? "bun" : "node";
+  const runtime = process.execPath;
   const tag = `# capy-watch:${id}`;
   const cronLine = `*/${intervalMin} * * * * ${runtime} ${binPath} _poll ${id} ${type} ${tag}`;