capyai 0.3.6 → 0.4.0

package/AGENTS.md

@@ -81,7 +81,7 @@ Config file locations:
 - Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 - Cursor: `.cursor/mcp.json`
 
-17 MCP tools with full CLI parity:
+21 MCP tools with full API parity:
 
 | Tool | What it does | Annotations |
 |------|-------------|-------------|
@@ -98,10 +98,14 @@ Config file locations:
 | `capy_threads` | List threads (paginated) | readOnly, idempotent |
 | `capy_thread_messages` | Read thread conversation history | readOnly, idempotent |
 | `capy_diff` | View diff | readOnly |
-| `capy_msg` | Message task/thread | openWorld |
+| `capy_msg` | Message task/thread (supports attachments, model switch) | openWorld |
 | `capy_stop` | Stop task/thread | destructive |
-| `capy_pr` | Create PR | openWorld |
+| `capy_pr` | Create PR (title, description, draft) | openWorld |
 | `capy_models` | List models | readOnly, idempotent |
+| `capy_pool_status` | Warm pool config + VM status | readOnly, idempotent |
+| `capy_pool_update` | Update warm pool config | openWorld |
+| `capy_pool_instances` | List warm pool VMs | readOnly, idempotent |
+| `capy_pool_clear` | Clear/refresh warm pool | destructive |
 
 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.
 
@@ -227,6 +231,12 @@ Every command supports `--json` for structured output. Errors always return `{ "
 | `capy threads msg <id> "<text>"` | Message a thread |
 | `capy threads stop <id>` | Stop a thread |
 | `capy threads messages <id>` | Read thread conversation history |
+| `capy pool` | Warm pool status |
+| `capy pool set --size=N --age=M` | Update warm pool config |
+| `capy pool test` | Test VM boot |
+| `capy pool instances [status]` | List pool VMs |
+| `capy pool instance <id>` | VM detail + logs |
+| `capy pool clear [--replenish]` | Clear/refresh pool |
 | `capy config [key] [value]` | Get/set config |
 | `capy models` | List available models |
 | `capy tools` | Show all commands + env vars |

package/README.md

@@ -53,7 +53,8 @@ Every command supports `--json` for machine-readable output.
 | `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 threads [list\|get\|msg\|stop\|messages]` | Manage Captain threads |
+| `capy pool [status\|set\|test\|instances\|clear]` | Manage warm pool VMs |
 | `capy models` | List available models |
 | `capy config [key] [value]` | Get/set config |
 
@@ -87,7 +88,7 @@ For agents that prefer MCP over CLI:
 }
 ```
 
-17 tools with full CLI parity: `capy_captain`, `capy_build`, `capy_start`, `capy_wait`, `capy_review`, `capy_approve`, `capy_retry`, `capy_re_review`, `capy_status`, `capy_list`, `capy_threads`, `capy_thread_messages`, `capy_diff`, `capy_msg`, `capy_stop`, `capy_pr`, `capy_models`.
+21 tools with full API parity, including warm pool management.
 
 ## Config
 

package/bin/capy.ts

@@ -36,6 +36,7 @@ const main = defineCommand({
     watches:     () => import("../src/commands/monitoring.js").then(m => m.watches),
     wait:        () => import("../src/commands/monitoring.js").then(m => m.wait),
     _poll:       () => import("../src/commands/monitoring.js").then(m => m._poll),
+    pool:        () => import("../src/commands/pool.js").then(m => m.default),
     init:        () => import("../src/commands/setup.js").then(m => m.init),
     config:      () => import("../src/commands/setup.js").then(m => m.config),
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capyai",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "type": "module",
   "description": "Unofficial Capy.ai CLI for agent orchestration with quality gates",
   "bin": {

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.6"
+  version: "0.4.0"
 ---
 
 # capy

package/src/api.ts

@@ -34,15 +34,16 @@ async function rawRequest(apiKey: string, server: string, method: string, path:
   }
 
   const text = await res.text();
+  let data: any;
   try {
-    const data = JSON.parse(text);
-    if (data.error) {
-      fail("api_error", `API error — ${data.error.message || data.error.code}`);
-    }
-    return data;
+    data = JSON.parse(text);
   } catch {
     fail("bad_response", `bad API response: ${text.slice(0, 200)}`);
   }
+  if (data.error) {
+    fail(data.error.code || "api_error", data.error.message || "unknown API error");
+  }
+  return data;
 }
 
 async function request(method: string, path: string, body?: unknown): Promise<any> {
@@ -78,21 +79,24 @@ export async function getProject(id?: string): Promise<Project & { createdAt?: s
 }
 
 // --- Threads ---
-export async function createThread(prompt: string, model?: string, repos?: unknown[]): Promise<Thread> {
+export async function createThread(prompt: string, model?: string, opts: { repos?: unknown[]; attachmentUrls?: string[] } = {}): Promise<Thread> {
   const cfg = config.load();
   return request("POST", "/threads", {
     projectId: cfg.projectId,
     prompt,
     model: model || cfg.defaultModel,
-    repos: repos || cfg.repos,
+    repos: opts.repos || cfg.repos,
+    ...(opts.attachmentUrls?.length ? { attachmentUrls: opts.attachmentUrls } : {}),
   });
 }
 
-export async function listThreads(opts: { limit?: number; status?: string; cursor?: string } = {}): Promise<ListResponse<Thread>> {
+export async function listThreads(opts: { limit?: number; status?: string; cursor?: string; prNumber?: number; branch?: string } = {}): Promise<ListResponse<Thread>> {
   const cfg = config.load();
   const p = new URLSearchParams({ projectId: cfg.projectId, limit: String(opts.limit || 10) });
   if (opts.status) p.set("status", opts.status);
   if (opts.cursor) p.set("cursor", opts.cursor);
+  if (opts.prNumber) p.set("prNumber", String(opts.prNumber));
+  if (opts.branch) p.set("branch", opts.branch);
   return request("GET", `/threads?${p}`);
 }
 
@@ -100,8 +104,12 @@ export async function getThread(id: string): Promise<Thread> {
   return request("GET", `/threads/${id}`);
 }
 
-export async function messageThread(id: string, msg: string): Promise<unknown> {
-  return request("POST", `/threads/${id}/message`, { message: msg });
+export async function messageThread(id: string, msg: string, opts: { model?: string; attachmentUrls?: string[] } = {}): Promise<unknown> {
+  return request("POST", `/threads/${id}/message`, {
+    message: msg,
+    ...(opts.model ? { model: opts.model } : {}),
+    ...(opts.attachmentUrls?.length ? { attachmentUrls: opts.attachmentUrls } : {}),
+  });
 }
 
 export async function stopThread(id: string): Promise<unknown> {
@@ -114,7 +122,7 @@ export async function getThreadMessages(id: string, opts: { limit?: number } = {
 }
 
 // --- Tasks ---
-export async function createTask(prompt: string, model?: string, opts: { title?: string; start?: boolean; labels?: string[] } = {}): Promise<Task> {
+export async function createTask(prompt: string, model?: string, opts: { title?: string; start?: boolean; labels?: string[]; attachmentUrls?: string[] } = {}): Promise<Task> {
   const cfg = config.load();
   return request("POST", "/tasks", {
     projectId: cfg.projectId,
@@ -124,14 +132,17 @@ export async function createTask(prompt: string, model?: string, opts: { title?:
     model: model || cfg.defaultModel,
     start: opts.start !== false,
     ...(opts.labels ? { labels: opts.labels } : {}),
+    ...(opts.attachmentUrls?.length ? { attachmentUrls: opts.attachmentUrls } : {}),
   });
 }
 
-export async function listTasks(opts: { limit?: number; status?: string; cursor?: string } = {}): Promise<ListResponse<Task>> {
+export async function listTasks(opts: { limit?: number; status?: string; cursor?: string; prNumber?: number; branch?: string } = {}): Promise<ListResponse<Task>> {
   const cfg = config.load();
   const p = new URLSearchParams({ projectId: cfg.projectId, limit: String(opts.limit || 30) });
   if (opts.status) p.set("status", opts.status);
   if (opts.cursor) p.set("cursor", opts.cursor);
+  if (opts.prNumber) p.set("prNumber", String(opts.prNumber));
+  if (opts.branch) p.set("branch", opts.branch);
   return request("GET", `/tasks?${p}`);
 }
 
@@ -147,8 +158,11 @@ export async function stopTask(id: string, reason?: string): Promise<Task> {
   return request("POST", `/tasks/${id}/stop`, reason ? { reason } : {});
 }
 
-export async function messageTask(id: string, msg: string): Promise<unknown> {
-  return request("POST", `/tasks/${id}/message`, { message: msg });
+export async function messageTask(id: string, msg: string, opts: { attachmentUrls?: string[] } = {}): Promise<unknown> {
+  return request("POST", `/tasks/${id}/message`, {
+    message: msg,
+    ...(opts.attachmentUrls?.length ? { attachmentUrls: opts.attachmentUrls } : {}),
+  });
 }
 
 export async function createPR(id: string, opts: Record<string, unknown> = {}): Promise<PullRequestRef & { url?: string; number?: number; title?: string; headRef?: string; baseRef?: string }> {
@@ -162,3 +176,55 @@ export async function getDiff(id: string, mode = "run"): Promise<DiffData> {
 export async function listModels(): Promise<{ models?: Model[] }> {
   return request("GET", "/models");
 }
+
+// --- Warm Pool ---
+export interface WarmPoolConfig {
+  enabled: boolean;
+  targetSize: number;
+  maxAgeMinutes: number;
+  branch?: string;
+  setupCommands?: string[];
+  instances?: WarmPoolInstance[];
+}
+
+export interface WarmPoolInstance {
+  id: string;
+  status: string;
+  createdAt?: string;
+  claimedAt?: string;
+  logs?: string;
+}
+
+export async function getWarmPool(projectId?: string): Promise<WarmPoolConfig> {
+  const pid = projectId || config.load().projectId;
+  return request("GET", `/projects/${pid}/warm-pool`);
+}
+
+export async function updateWarmPool(update: { enabled?: boolean; targetSize?: number; maxAgeMinutes?: number; branch?: string; setupCommands?: string[] }, projectId?: string): Promise<WarmPoolConfig> {
+  const pid = projectId || config.load().projectId;
+  return request("PATCH", `/projects/${pid}/warm-pool`, update);
+}
+
+export async function testWarmPool(projectId?: string): Promise<{ instanceId: string; status: string }> {
+  const pid = projectId || config.load().projectId;
+  return request("POST", `/projects/${pid}/warm-pool/test`);
+}
+
+export async function listWarmPoolInstances(opts: { status?: string } = {}, projectId?: string): Promise<WarmPoolInstance[]> {
+  const pid = projectId || config.load().projectId;
+  const p = new URLSearchParams();
+  if (opts.status) p.set("status", opts.status);
+  const qs = p.toString();
+  const data = await request("GET", `/projects/${pid}/warm-pool/instances${qs ? `?${qs}` : ""}`);
+  return Array.isArray(data) ? data : data.instances || data.items || [];
+}
+
+export async function getWarmPoolInstance(instanceId: string, projectId?: string): Promise<WarmPoolInstance> {
+  const pid = projectId || config.load().projectId;
+  return request("GET", `/projects/${pid}/warm-pool/instances/${instanceId}`);
+}
+
+export async function clearWarmPool(opts: { replenish?: boolean } = {}, projectId?: string): Promise<unknown> {
+  const pid = projectId || config.load().projectId;
+  return request("POST", `/projects/${pid}/warm-pool/clear`, opts.replenish != null ? { replenish: opts.replenish } : {});
+}

package/src/commands/pool.ts

@@ -0,0 +1,128 @@
+import { defineCommand } from "citty";
+import { jsonArg } from "./_shared.js";
+
+const status = defineCommand({
+  meta: { name: "status", description: "Warm pool config and status" },
+  args: { ...jsonArg },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+    const { log } = await import("@clack/prompts");
+
+    const pool = await api.getWarmPool();
+    if (args.json) { fmt.out(pool); return; }
+
+    log.info(`Warm pool: ${pool.enabled ? "enabled" : "disabled"}`);
+    console.log(`  Target size:  ${pool.targetSize}`);
+    console.log(`  Max age:      ${pool.maxAgeMinutes}min`);
+    if (pool.branch) console.log(`  Branch:       ${pool.branch}`);
+    if (pool.setupCommands?.length) {
+      console.log(`  Setup:        ${pool.setupCommands.length} commands`);
+      pool.setupCommands.forEach(c => console.log(`    $ ${c}`));
+    }
+  },
+});
+
+const set = defineCommand({
+  meta: { name: "set", description: "Update warm pool config" },
+  args: {
+    enabled: { type: "boolean", description: "Enable/disable" },
+    size: { type: "string", description: "Target pool size" },
+    age: { type: "string", description: "Max VM age in minutes" },
+    branch: { type: "string", description: "Branch for pool VMs" },
+    ...jsonArg,
+  },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+    const { log } = await import("@clack/prompts");
+
+    const update: Record<string, unknown> = {};
+    if (args.enabled !== undefined) update.enabled = args.enabled;
+    if (args.size) update.targetSize = parseInt(args.size);
+    if (args.age) update.maxAgeMinutes = parseInt(args.age);
+    if (args.branch) update.branch = args.branch;
+
+    const pool = await api.updateWarmPool(update as any);
+    if (args.json) { fmt.out(pool); return; }
+    log.success(`Updated: size=${pool.targetSize}, age=${pool.maxAgeMinutes}min, enabled=${pool.enabled}`);
+  },
+});
+
+const test = defineCommand({
+  meta: { name: "test", description: "Test VM boot with setup commands" },
+  args: { ...jsonArg },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+    const { log } = await import("@clack/prompts");
+
+    const result = await api.testWarmPool();
+    if (args.json) { fmt.out(result); return; }
+    log.success(`Test VM started: ${result.instanceId} [${result.status}]`);
+    log.info(`Check status: capy pool instance ${result.instanceId}`);
+  },
+});
+
+const instances = defineCommand({
+  meta: { name: "instances", description: "List warm pool VMs", alias: "ls" },
+  args: {
+    status: { type: "positional", required: false, description: "Filter: ready, provisioning, failed, claimed" },
+    ...jsonArg,
+  },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+
+    const list = await api.listWarmPoolInstances({ status: args.status });
+    if (args.json) { fmt.out(list); return; }
+    if (!list.length) { console.log("No instances."); return; }
+    fmt.table(["ID", "STATUS", "CREATED"], list.map(i => [
+      i.id.slice(0, 16), i.status, i.createdAt || "?",
+    ]));
+  },
+});
+
+const instance = defineCommand({
+  meta: { name: "instance", description: "VM instance detail + logs" },
+  args: {
+    id: { type: "positional", description: "Instance ID", required: true },
+    ...jsonArg,
+  },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+    const { log } = await import("@clack/prompts");
+
+    const data = await api.getWarmPoolInstance(args.id);
+    if (args.json) { fmt.out(data); return; }
+    log.info(`Instance: ${data.id}\nStatus:   ${data.status}\nCreated:  ${data.createdAt || "?"}`);
+    if (data.claimedAt) console.log(`Claimed:  ${data.claimedAt}`);
+    if (data.logs) {
+      console.log(`\nLogs:\n${data.logs}`);
+    }
+  },
+});
+
+const clear = defineCommand({
+  meta: { name: "clear", description: "Clear all warm pool VMs" },
+  args: {
+    replenish: { type: "boolean", description: "Replenish after clearing", default: false },
+    ...jsonArg,
+  },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+    const { log } = await import("@clack/prompts");
+
+    const result = await api.clearWarmPool({ replenish: args.replenish });
+    if (args.json) { fmt.out(result); return; }
+    log.success(`Pool cleared.${args.replenish ? " Replenishing..." : ""}`);
+  },
+});
+
+export default defineCommand({
+  meta: { name: "pool", description: "Manage warm pool VMs" },
+  default: "status",
+  subCommands: { status, set, test, instances, instance, clear },
+});

package/src/commands/setup.ts

@@ -178,6 +178,7 @@ export const tools = defineCommand({
       watch:      { args: "<id>",                  desc: "Poll + notify on completion" },
       unwatch:    { args: "<id>",                  desc: "Stop watching" },
       watches:    { args: "",                      desc: "List watches" },
+      pool:       { args: "[status|set|test|...]", desc: "Manage warm pool VMs" },
       models:     { args: "",                      desc: "List models" },
       tools:      { args: "",                      desc: "This list" },
       config:     { args: "[key] [value]",         desc: "Get/set config" },

package/src/mcp.ts

@@ -278,12 +278,16 @@ server.registerTool("capy_msg", {
   inputSchema: {
     id: z.string().describe("Task or thread ID"),
     text: z.string().describe("Message text"),
+    model: z.string().optional().describe("Switch model mid-conversation (threads only)"),
+    attachmentUrls: z.array(z.string()).optional().describe("URLs to attach"),
   },
   annotations: { openWorldHint: true },
-}, async ({ id, text: msg }) => {
+}, async ({ id, text: msg, model, attachmentUrls }) => {
   try {
     const isThread = isThreadId(id);
-    const result = isThread ? await api.messageThread(id, msg) : await api.messageTask(id, msg);
+    const result = isThread
+      ? await api.messageThread(id, msg, { model, attachmentUrls })
+      : await api.messageTask(id, msg, { attachmentUrls });
     return text({ id, sent: true, type: isThread ? "thread" : "task", ...(result && typeof result === "object" ? result as Record<string, unknown> : {}) });
   } catch (e) { return err(e); }
 });
@@ -308,11 +312,17 @@ server.registerTool("capy_pr", {
   inputSchema: {
     id: z.string().describe("Task ID"),
     title: z.string().optional().describe("PR title override"),
+    description: z.string().optional().describe("PR body/description"),
+    draft: z.boolean().optional().describe("Create as draft PR"),
   },
   annotations: { openWorldHint: true },
-}, async ({ id, title }) => {
+}, async ({ id, title, description, draft }) => {
   try {
-    const data = await api.createPR(id, title ? { title } : {});
+    const opts: Record<string, unknown> = {};
+    if (title) opts.title = title;
+    if (description) opts.description = description;
+    if (draft != null) opts.draft = draft;
+    const data = await api.createPR(id, opts);
     return text(data);
   } catch (e) { return err(e); }
 });
@@ -383,5 +393,61 @@ server.registerTool("capy_models", {
   } catch (e) { return err(e); }
 });
 
+// --- Warm Pool ---
+
+server.registerTool("capy_pool_status", {
+  description: "Get warm pool config and VM status",
+  inputSchema: {},
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async () => {
+  try {
+    const pool = await api.getWarmPool();
+    return text(pool);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_pool_update", {
+  description: "Update warm pool configuration (VM pre-warming)",
+  inputSchema: {
+    enabled: z.boolean().optional().describe("Enable/disable warm pool"),
+    targetSize: z.number().optional().describe("Number of VMs to keep warm"),
+    maxAgeMinutes: z.number().optional().describe("Max VM age before recycling"),
+    branch: z.string().optional().describe("Branch for pool VMs"),
+    setupCommands: z.array(z.string()).optional().describe("Commands to run on VM boot"),
+  },
+  annotations: { openWorldHint: true },
+}, async (params) => {
+  try {
+    const data = await api.updateWarmPool(params);
+    return text(data);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_pool_instances", {
+  description: "List warm pool VM instances",
+  inputSchema: {
+    status: z.string().optional().describe("Filter: ready, provisioning, failed, claimed"),
+  },
+  annotations: { readOnlyHint: true, idempotentHint: true },
+}, async ({ status }) => {
+  try {
+    const data = await api.listWarmPoolInstances({ status });
+    return text(data);
+  } catch (e) { return err(e); }
+});
+
+server.registerTool("capy_pool_clear", {
+  description: "Clear all warm pool VMs",
+  inputSchema: {
+    replenish: z.boolean().optional().describe("Replenish pool after clearing"),
+  },
+  annotations: { destructiveHint: true },
+}, async ({ replenish }) => {
+  try {
+    const data = await api.clearWarmPool({ replenish });
+    return text(data);
+  } catch (e) { return err(e); }
+});
+
 const transport = new StdioServerTransport();
 await server.connect(transport);