@controlvector/cv-agent 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,164 @@
+# CV-Agent
+
+**Remote task dispatch daemon for CV-Hub. Bridges Claude Code with CV-Hub's agentic task system.**
+
+CV-Agent (`cva`) runs as a daemon on your machine, polls CV-Hub for dispatched tasks, spawns Claude Code to execute them, and reports results back. It handles permission relay, git remote management, and executor heartbeats.
+
+[![npm](https://img.shields.io/npm/v/@controlvector/cv-agent)](https://www.npmjs.com/package/@controlvector/cv-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Installation
+
+```bash
+npm install -g @controlvector/cv-agent
+```
+
+Requires [Claude Code](https://docs.anthropic.com/en/docs/build-with-claude/claude-code) to be installed and on your PATH.
+
+---
+
+## Quick Start
+
+```bash
+# Authenticate with CV-Hub
+cva auth login
+
+# Add the CV-Hub remote to your repo
+cd your-project
+cva remote add
+
+# Start the agent daemon (auto-approves Claude Code tool permissions)
+cva agent --auto-approve
+```
+
+The agent will register as an executor with CV-Hub, poll for tasks, and execute them using Claude Code.
+
+---
+
+## Commands
+
+### `cva agent [options]`
+
+Start the agent daemon. Polls CV-Hub for pending tasks and executes them with Claude Code.
+
+```bash
+cva agent                  # Start with permission relay to CV-Hub
+cva agent --auto-approve   # Auto-approve all Claude Code permissions locally
+cva agent --dir /path      # Override working directory
+```
+
+Options:
+- `--auto-approve` — Auto-approve all tool permission prompts (no CV-Hub relay)
+- `--dir <path>` — Working directory for Claude Code sessions
+
+### `cva auth login`
+
+Authenticate with CV-Hub. Opens a browser for device auth flow, or accepts a token paste.
+
+```bash
+cva auth login
+```
+
+Token is stored in `~/.cva/config.json`.
+
+### `cva remote add [--name <n>]`
+
+Add or update the CV-Hub git remote for the current repository.
+
+```bash
+cva remote add                          # Auto-detects from CV-Hub
+cva remote add --name cvhub             # Custom remote name (default: cvhub)
+```
+
+### `cva remote setup <owner/repo>`
+
+Create a repo on CV-Hub and configure the local remote in one step.
+
+### `cva task list [--status <status>]`
+
+List tasks for the current executor.
+
+### `cva task logs <task-id>`
+
+Stream task logs and progress.
+
+### `cva status`
+
+Show executor registration status, active tasks, and recent completions.
+
+---
+
+## How It Works
+
+1. `cva agent` registers this machine as an **executor** with CV-Hub
+2. It polls CV-Hub every 5 seconds for pending tasks
+3. When a task is claimed, it spawns Claude Code with the task prompt
+4. **Permission handling**: Claude Code tool calls require approval:
+   - `--auto-approve`: writes `y` to stdin automatically
+   - Default: relays prompts to CV-Hub for remote approval (e.g., from Claude.ai)
+5. When Claude Code exits, the agent reports the result (files changed, commits, exit code) to CV-Hub
+6. Heartbeats are sent every 30 seconds to keep the executor registration alive
+
+### Git Remote Management
+
+Before each task, the agent ensures a `cvhub` remote exists pointing to the correct CV-Hub repo URL. Task prompts are prepended with instructions to push to `cvhub` instead of `origin`.
+
+---
+
+## Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | >= 20 | Runtime |
+| Claude Code | Latest | Must be on PATH as `claude` |
+| CV-Hub account | — | Sign up at [hub.controlvector.io](https://hub.controlvector.io) |
+
+---
+
+## Configuration
+
+Config file: `~/.cva/config.json`
+
+```json
+{
+  "hub": {
+    "api": "https://api.hub.controlvector.io",
+    "token": "cvh_xxxxxxxxxxxx"
+  },
+  "agent": {
+    "pollInterval": 5000,
+    "heartbeatInterval": 30000,
+    "autoApprove": false,
+    "maxConcurrentTasks": 1
+  },
+  "defaults": {
+    "remoteName": "cvhub"
+  }
+}
+```
+
+---
+
+## Why a Separate Binary?
+
+CV-Git (`cv`) and CV-Agent (`cva`) are separate packages to avoid a recursion trap: `cv agent` would spawn Claude Code, which might call `cv` commands, creating a circular dependency. By using `cva` as the agent binary, Claude Code sessions use standard `git` commands only.
+
+| Binary | Package | Responsibility |
+|--------|---------|---------------|
+| `cv` | `@controlvector/cv-git` | Git operations, knowledge graph, code analysis, local dev |
+| `cva` | `@controlvector/cv-agent` | Agent daemon, task dispatch, CV-Hub remote management |
+
+---
+
+## Related Projects
+
+- [CV-Git](https://www.npmjs.com/package/@controlvector/cv-git) (`cv`) — AI-native version control CLI
+- [CV-Hub](https://hub.controlvector.io) — AI-native Git platform (web app + API)
+
+---
+
+## License
+
+MIT

package/dist/bundle.cjs

@@ -3743,6 +3743,28 @@ async function getTaskLogs(creds, taskId) {
   const data = await res.json();
   return data.logs || [];
 }
+async function postTaskEvent(creds, taskId, event) {
+  const res = await apiCall(creds, "POST", `/api/v1/tasks/${taskId}/events`, event);
+  if (!res.ok) throw new Error(`Post event failed: ${res.status}`);
+  return await res.json();
+}
+async function getEventResponse(creds, taskId, eventId) {
+  const res = await apiCall(creds, "GET", `/api/v1/tasks/${taskId}/events?after_id=&limit=200`);
+  if (!res.ok) throw new Error(`Get events failed: ${res.status}`);
+  const events = await res.json();
+  const event = events.find((e) => e.id === eventId);
+  return {
+    response: event?.response ?? null,
+    responded_at: event?.respondedAt ?? event?.responded_at ?? null
+  };
+}
+async function getRedirects(creds, taskId, afterTimestamp) {
+  const qs = afterTimestamp ? `?after_timestamp=${encodeURIComponent(afterTimestamp)}` : "";
+  const res = await apiCall(creds, "GET", `/api/v1/tasks/${taskId}/events${qs}`);
+  if (!res.ok) return [];
+  const events = await res.json();
+  return events.filter((e) => (e.eventType ?? e.event_type) === "redirect").map((e) => ({ id: e.id, content: e.content }));
+}
 async function createRepo(creds, name, description) {
   const res = await apiCall(creds, "POST", "/api/v1/repos", {
     name,
@@ -3755,6 +3777,44 @@ async function createRepo(creds, name, description) {
   return await res.json();
 }
 
+// src/utils/output-parser.ts
+function parseClaudeCodeOutput(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  const thinkingMatch = trimmed.match(/^\[THINKING\]\s*(.+)/);
+  if (thinkingMatch) {
+    return { eventType: "thinking", content: thinkingMatch[1], needsResponse: false };
+  }
+  const decisionMatch = trimmed.match(/^\[DECISION\]\s*(.+)/);
+  if (decisionMatch) {
+    return { eventType: "decision", content: decisionMatch[1], needsResponse: false };
+  }
+  const questionMatch = trimmed.match(/^\[QUESTION\]\s*(.+)/);
+  if (questionMatch) {
+    return { eventType: "question", content: questionMatch[1], needsResponse: true };
+  }
+  const progressMatch = trimmed.match(/^\[PROGRESS\]\s*(.+)/);
+  if (progressMatch) {
+    return { eventType: "progress", content: progressMatch[1], needsResponse: false };
+  }
+  const fileChangeMatch = trimmed.match(
+    /(?:Created|Modified|Wrote to|Deleted)\s+(?:file:\s*)?(.+)/i
+  );
+  if (fileChangeMatch) {
+    const action = trimmed.split(/\s/)[0].toLowerCase();
+    return {
+      eventType: "file_change",
+      content: { path: fileChangeMatch[1].trim(), action },
+      needsResponse: false
+    };
+  }
+  const errorMatch = trimmed.match(/^(?:Error|FATAL|FAILED|panic|Traceback)/i);
+  if (errorMatch) {
+    return { eventType: "error", content: trimmed, needsResponse: false };
+  }
+  return null;
+}
+
 // src/commands/agent-git.ts
 var import_node_child_process = require("node:child_process");
 function gitExec(cmd, cwd) {
@@ -3996,7 +4056,7 @@ ${source_default.yellow("\u26A0")} ${label} failed, retrying in ${delay}s... (${
 // src/commands/agent.ts
 function buildClaudePrompt(task) {
   let prompt = "";
-  prompt += `You are executing a task dispatched from Claude.ai via CV-Hub.
+  prompt += `You are executing a task dispatched via CV-Hub.
 
 `;
   prompt += `## Task: ${task.title}
@@ -4042,23 +4102,38 @@ ${task.input.context}`;
 `;
     });
   }
-  if (task.owner && task.repo) {
-    prompt += `
+  prompt += `
 
-## Git Remote Instructions
+## Git & CV-Hub Instructions
+`;
+  prompt += `You have the \`cv\` CLI (@controlvector/cv-git) available for all CV-Hub git operations.
+`;
+  prompt += `Use \`cv\` instead of raw \`git\` commands when interacting with CV-Hub repositories:
 `;
-    prompt += `This repository has a \`cvhub\` remote pointing to CV-Hub.
+  prompt += `  cv push                          # push to CV-Hub
 `;
-    prompt += `When committing and pushing, push to the \`cvhub\` remote:
+  prompt += `  cv pr create --title "..."       # create pull request
 `;
-    prompt += `  git push cvhub <branch>
+  prompt += `  cv issue list                    # list issues
+`;
+  prompt += `  cv repo info                     # repo details
+`;
+  prompt += `
 `;
+  prompt += `For standard git operations (commit, branch, diff, log, status), use regular \`git\` commands.
+`;
+  if (task.owner && task.repo) {
     prompt += `
+Target repository: ${task.owner}/${task.repo}
 `;
-    prompt += `IMPORTANT: Use only standard \`git\` commands. Do NOT use \`cv\`, \`cva\`, or \`cv-git\` commands.
+    if (task.branch) prompt += `Target branch: ${task.branch}
 `;
   }
   prompt += `
+`;
+  prompt += `IMPORTANT: Do NOT run \`cva\` commands. The \`cva\` binary is the agent daemon that launched you \u2014 calling it would cause recursion.
+`;
+  prompt += `
 
 ---
 `;
@@ -4130,33 +4205,84 @@ var PERMISSION_PATTERNS = [
   /\? \(y\/n\)/
 ];
 async function launchAutoApproveMode(prompt, options) {
-  return new Promise((resolve, reject) => {
-    const args = ["-p", prompt, "--allowedTools", ...ALLOWED_TOOLS];
-    const child = (0, import_node_child_process2.spawn)("claude", args, {
-      cwd: options.cwd,
-      stdio: ["inherit", "inherit", "pipe"],
-      env: { ...process.env }
-    });
-    _activeChild = child;
-    let stderr = "";
-    child.stderr?.on("data", (data) => {
-      const text = data.toString();
-      stderr += text;
-      process.stderr.write(data);
+  const sessionId = options.taskId ? options.taskId.replace(/-/g, "").slice(0, 32).padEnd(32, "0").replace(/(.{8})(.{4})(.{4})(.{4})(.{12})/, "$1-$2-$3-$4-$5") : void 0;
+  const pendingQuestionIds = [];
+  const runOnce = (inputPrompt, isContinue) => {
+    return new Promise((resolve, reject) => {
+      const args = isContinue ? ["-p", inputPrompt, "--continue", "--allowedTools", ...ALLOWED_TOOLS] : ["-p", inputPrompt, "--allowedTools", ...ALLOWED_TOOLS];
+      if (sessionId && !isContinue) {
+        args.push("--session-id", sessionId);
+      }
+      const child = (0, import_node_child_process2.spawn)("claude", args, {
+        cwd: options.cwd,
+        stdio: ["inherit", "pipe", "pipe"],
+        env: { ...process.env }
+      });
+      _activeChild = child;
+      let stderr = "";
+      let lineBuffer = "";
+      child.stdout?.on("data", (data) => {
+        const text = data.toString();
+        process.stdout.write(data);
+        if (options.creds && options.taskId) {
+          lineBuffer += text;
+          const lines = lineBuffer.split("\n");
+          lineBuffer = lines.pop() ?? "";
+          for (const line of lines) {
+            const event = parseClaudeCodeOutput(line);
+            if (event) {
+              postTaskEvent(options.creds, options.taskId, {
+                event_type: event.eventType,
+                content: event.content,
+                needs_response: event.needsResponse
+              }).then((created) => {
+                if (event.needsResponse && created?.id) {
+                  pendingQuestionIds.push(created.id);
+                }
+              }).catch(() => {
+              });
+            }
+          }
+        }
+      });
+      child.stderr?.on("data", (data) => {
+        stderr += data.toString();
+        process.stderr.write(data);
+      });
+      child.on("close", (code, signal) => {
+        _activeChild = null;
+        resolve({ exitCode: signal === "SIGKILL" ? 137 : code ?? 1, stderr });
+      });
+      child.on("error", (err) => {
+        _activeChild = null;
+        reject(err);
+      });
     });
-    child.on("close", (code, signal) => {
-      _activeChild = null;
-      if (signal === "SIGKILL") {
-        resolve({ exitCode: 137, stderr });
+  };
+  let result = await runOnce(prompt, false);
+  if (options.creds && options.taskId && result.exitCode === 0) {
+    let followUps = 0;
+    while (pendingQuestionIds.length > 0 && followUps < 3) {
+      const questionId = pendingQuestionIds.shift();
+      console.log(source_default.gray(`  [auto-approve] Waiting for planner response to question...`));
+      const response = await pollForEventResponse(
+        options.creds,
+        options.taskId,
+        questionId,
+        3e5
+      );
+      if (response) {
+        const responseText = typeof response === "string" ? response : JSON.stringify(response);
+        console.log(source_default.gray(`  [auto-approve] Planner responded, continuing with --continue`));
+        result = await runOnce(responseText, true);
+        followUps++;
       } else {
-        resolve({ exitCode: code ?? 1, stderr });
+        console.log(source_default.yellow(`  [auto-approve] No response received, continuing without.`));
+        break;
       }
-    });
-    child.on("error", (err) => {
-      _activeChild = null;
-      reject(err);
-    });
-  });
+    }
+  }
+  return result;
 }
 async function launchRelayMode(prompt, options) {
   return new Promise((resolve, reject) => {
@@ -4169,10 +4295,65 @@ async function launchRelayMode(prompt, options) {
     let stderr = "";
     let stdoutBuffer = "";
     child.stdin?.write(prompt + "\n");
+    let lastRedirectCheck = Date.now();
+    let lineBuffer = "";
     child.stdout?.on("data", async (data) => {
       const text = data.toString();
       process.stdout.write(data);
       stdoutBuffer += text;
+      lineBuffer += text;
+      const lines = lineBuffer.split("\n");
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const event = parseClaudeCodeOutput(line);
+        if (event) {
+          try {
+            const created = await postTaskEvent(options.creds, options.taskId, {
+              event_type: event.eventType,
+              content: event.content,
+              needs_response: event.needsResponse
+            });
+            if (event.needsResponse && created?.id) {
+              console.log(source_default.gray(`  [stream] Question detected, waiting for planner response...`));
+              const response = await pollForEventResponse(
+                options.creds,
+                options.taskId,
+                created.id,
+                3e5
+              );
+              if (response) {
+                const responseText = typeof response === "string" ? response : JSON.stringify(response);
+                child.stdin?.write(responseText + "\n");
+                console.log(source_default.gray(`  [stream] Planner responded.`));
+              } else {
+                child.stdin?.write("[No response received within timeout. Continue with your best judgment.]\n");
+                console.log(source_default.yellow(`  [stream] Question timed out.`));
+              }
+            }
+          } catch {
+          }
+        }
+      }
+      if (Date.now() - lastRedirectCheck > 1e4) {
+        try {
+          const redirects = await getRedirects(
+            options.creds,
+            options.taskId,
+            new Date(lastRedirectCheck).toISOString()
+          );
+          for (const redirect of redirects) {
+            const instruction = redirect.content?.instruction;
+            if (instruction) {
+              child.stdin?.write(`
+[REDIRECT FROM PLANNER]: ${instruction}
+`);
+              console.log(source_default.gray(`  [stream] Redirect received from planner.`));
+            }
+          }
+        } catch {
+        }
+        lastRedirectCheck = Date.now();
+      }
       for (const pattern of PERMISSION_PATTERNS) {
         const match = stdoutBuffer.match(pattern);
         if (match) {
@@ -4195,6 +4376,12 @@ async function launchRelayMode(prompt, options) {
               "approval",
               ["y", "n"]
             );
+            postTaskEvent(options.creds, options.taskId, {
+              event_type: "approval_request",
+              content: { prompt_text: promptText },
+              needs_response: true
+            }).catch(() => {
+            });
             const timeoutMs = 5 * 60 * 1e3;
             const startPoll = Date.now();
             let answered = false;
@@ -4251,6 +4438,20 @@ async function launchRelayMode(prompt, options) {
     });
   });
 }
+async function pollForEventResponse(creds, taskId, eventId, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    await new Promise((r) => setTimeout(r, 3e3));
+    try {
+      const result = await getEventResponse(creds, taskId, eventId);
+      if (result.response !== null) {
+        return result.response;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
 async function runAgent(options) {
   const creds = await readCredentials();
   if (!creds.CV_HUB_API) {
@@ -4276,9 +4477,16 @@ async function runAgent(options) {
     console.log();
     process.exit(1);
   }
+  try {
+    (0, import_node_child_process2.execSync)("cv --version", { stdio: "pipe", timeout: 5e3 });
+  } catch {
+    console.log(source_default.yellow("!") + " cv-git CLI not found. Claude Code will fall back to raw git commands.");
+    console.log(`  Install it: ${source_default.cyan("npm install -g @controlvector/cv-git")}`);
+    console.log();
+  }
   const machineName = options.machine || await getMachineName();
   const pollInterval = Math.max(3, parseInt(options.pollInterval, 10)) * 1e3;
-  const workingDir = options.workingDir;
+  const workingDir = options.workingDir === "." ? process.cwd() : options.workingDir;
   if (!options.machine) {
     const credCheck = await readCredentials();
     if (!credCheck.CV_HUB_MACHINE_NAME) {
@@ -4398,7 +4606,11 @@ ${source_default.red("Timeout")} Task timed out after ${formatDuration(timeoutMs
     console.log(source_default.gray("-".repeat(60)));
     let result;
     if (options.autoApprove) {
-      result = await launchAutoApproveMode(prompt, { cwd: options.workingDir });
+      result = await launchAutoApproveMode(prompt, {
+        cwd: options.workingDir,
+        creds,
+        taskId: task.id
+      });
     } else {
       result = await launchRelayMode(prompt, {
         cwd: options.workingDir,
@@ -4416,6 +4628,15 @@ ${source_default.red("Timeout")} Task timed out after ${formatDuration(timeoutMs
       ...postGitState.filesModified,
       ...postGitState.filesDeleted
     ];
+    postTaskEvent(creds, task.id, {
+      event_type: "completed",
+      content: {
+        exit_code: result.exitCode,
+        duration_seconds: Math.round((Date.now() - startTime) / 1e3),
+        files_changed: allChangedFiles.length
+      }
+    }).catch(() => {
+    });
     if (result.exitCode === 0) {
       if (allChangedFiles.length > 0) {
         sendTaskLog(
@@ -4508,10 +4729,10 @@ ${source_default.red("!")} Task error: ${err.message}`);
 }
 function agentCommand() {
   const cmd = new Command("agent");
-  cmd.description("Listen for tasks dispatched from Claude.ai and execute them with Claude Code");
-  cmd.option("--machine <name>", "Machine name override");
-  cmd.option("--poll-interval <seconds>", "How often to check for tasks", "5");
-  cmd.option("--working-dir <path>", "Working directory for Claude Code", process.cwd());
+  cmd.description("Listen for tasks dispatched via CV-Hub and execute them with Claude Code");
+  cmd.option("--machine <name>", "Override auto-detected machine name");
+  cmd.option("--poll-interval <seconds>", "How often to check for tasks, minimum 3 (default: 5)", "5");
+  cmd.option("--working-dir <path>", "Working directory for Claude Code (default: current directory)", ".");
   cmd.option("--auto-approve", "Pre-approve all tool permissions (uses -p mode)", false);
   cmd.action(async (opts) => {
     await runAgent(opts);
@@ -4525,7 +4746,7 @@ async function authLogin(opts) {
   const apiUrl = opts.apiUrl || "https://api.hub.controlvector.io";
   console.log(source_default.gray("Validating token..."));
   try {
-    const res = await fetch(`${apiUrl}/api/v1/user/me`, {
+    const res = await fetch(`${apiUrl}/api/auth/me`, {
       headers: { "Authorization": `Bearer ${token}` }
     });
     if (!res.ok) {
@@ -4572,7 +4793,7 @@ async function authStatus() {
   console.log(`API:   ${source_default.cyan(apiUrl)}`);
   console.log(`Token: ${source_default.gray(maskedToken)}`);
   try {
-    const res = await fetch(`${apiUrl}/api/v1/user/me`, {
+    const res = await fetch(`${apiUrl}/api/auth/me`, {
       headers: { "Authorization": `Bearer ${creds.CV_HUB_PAT}` }
     });
     if (res.ok) {
@@ -4812,7 +5033,7 @@ function statusCommand() {
 
 // src/index.ts
 var program2 = new Command();
-program2.name("cva").description("CV-Hub Agent \u2014 bridges Claude Code with CV-Hub task dispatch").version("0.1.0");
+program2.name("cva").description("CV-Hub Agent \u2014 bridges Claude Code with CV-Hub task dispatch").version("1.0.0");
 program2.addCommand(agentCommand());
 program2.addCommand(authCommand());
 program2.addCommand(remoteCommand());