@corvio/cli 0.1.0-beta.5 → 0.1.0-beta.7

package/README.md

@@ -17,3 +17,35 @@ corvio update check --json
 When no environment key is configured, run `corvio auth login`. Login creates one user-level `cvu_` credential; it does not freeze the browser's current Workspace. Select each operation's Workspace with `corvio workspaces use`, `--workspace`, or `CORVIO_WORKSPACE_ID`. Legacy Workspace-bound `cvk_` keys remain supported and cannot be widened to another Workspace. The environment key always takes precedence. Local sync stores only credential-free handles and revision/hash baselines in `.corvio/state.json`; Markdown lives below `corvio_docs/`, and conflicts require explicit resolution. Update checks compare npm's published `beta` tag with the API compatibility policy but never self-install. See [the Corvio CLI guide](https://corvio.ai/developers/cli) for the full command and receipt contract.
 
 The CLI rejects unknown/duplicate options and malformed integer bounds before network access. Normal API calls have a bounded timeout (`CORVIO_REQUEST_TIMEOUT_MS`, maximum ten minutes); only reads, explicit idempotency contracts, revision guards, and other owner-declared safe operations retry automatically. Document updates preflight the current revision when `--expected-revision` is omitted. Downloads, uploads, and Markdown pulls verify SHA-256 receipts before replacing local files; local writes are atomic, remote default filenames cannot escape the current directory, and Sync refuses symbolic-link traversal while checkpointing each successful push.
+
+## External Agent collaboration
+
+Create and manage an Agent with the user credential, then run it with the one-time `cvg_` secret. User and Agent credentials are deliberately separate:
+
+```bash
+corvio agents create \
+  --handle reviewer-a \
+  --display-name "Reviewer A" \
+  --provider codex \
+  --permissions read,comment,edit \
+  --json
+
+export CORVIO_AGENT_API_KEY='cvg_...'
+corvio agent claim --wait-seconds 30 --json
+corvio agent run --handler ./my-agent-handler --once --json
+```
+
+The handler reads one Agent event JSON object from stdin and prints one JSON object:
+
+```json
+{"instruction":"Inspect the mentioned section and correct unsupported claims.","reply":"Reviewed and updated the section."}
+```
+
+The Runner renews the mailbox lease, sends the instruction and structured event context to Corvio Query, posts the reply under the Agent's own name/avatar, and completes only with durable Query/comment/artifact receipts. Query owns detailed document edits; the handler should decide intent, not implement a second line editor. `CORVIO_API_KEY` is not passed to the handler and Agent runtime commands never fall back to it.
+
+Runner replies are causally bound to the claimed event and are idempotent across network retries. Corvio stops repeated Agent routes
+and enforces bounded hop, chain-event, and per-comment target budgets; a stopped handoff remains visible as “Needs attention” but is
+not claimable. For a deliberate standalone Agent-to-Agent request, use `corvio agent comment ... --start-new-chain`. Manual replies
+may instead pass `--source-event-id` with `--source-event-lease-token`; source and new-chain modes must not be mixed.
+
+If a laptop sleeps, loses network, or stops the Runner, events remain pending or become reclaimable after lease expiry. Corvio does not claim to power on an offline device. Use a process supervisor for an always-on Runner; pause or revoke the Agent when it should stop receiving new mentions.

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { lstat, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -20,6 +21,7 @@ import {
   openBrowser,
   option,
   readTextFile,
+  readAgentCredential,
   readWorkspaceContext,
   readWorkspaceCredential,
   requireConfirmation,
@@ -33,7 +35,7 @@ import {
   writeTextFile,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.5";
+const VERSION = "0.1.0-beta.7";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -60,7 +62,21 @@ const COMMAND_OPTIONS = Object.freeze({
   "workspaces:use": ["id"],
   "workspaces:create": ["name", "kind", "description", "idempotency-key"],
   "capabilities:": [],
-  "ask:": ["prompt", "conversation-id", "sources", "allow-actions", "idempotency-key"],
+  "ask:": ["prompt", "conversation-id", "sources", "allow-actions", "context-file", "idempotency-key"],
+  "agents:list": ["include-revoked"],
+  "agents:connect": ["handle", "avatar-url", "provider", "permissions"],
+  "agents:create": ["handle", "display-name", "avatar-url", "provider", "permissions"],
+  "agents:update": ["id", "display-name", "avatar-url", "status", "permissions"],
+  "agents:rotate": ["id"],
+  "agent:claim": ["worker-id", "lease-seconds", "wait-seconds"],
+  "agent:complete": ["id", "lease-token", "result-file", "question-id", "comment-entry-id", "no-change-reason"],
+  "agent:renew": ["id", "lease-token", "lease-seconds"],
+  "agent:fail": ["id", "lease-token", "error", "retryable"],
+  "agent:comments": ["document-id"],
+  "agent:comment": ["document-id", "body", "selection-file", "start-new-chain"],
+  "agent:reply": ["document-id", "id", "body", "source-event-id", "source-event-lease-token", "start-new-chain"],
+  "agent:status": ["document-id", "id", "status"],
+  "agent:run": ["once", "handler", "worker-id", "lease-seconds", "wait-seconds", "sources"],
   "questions:list": ["limit", "cursor", "conversation-id"],
   "questions:get": ["id"],
   "conversations:list": ["limit", "cursor"],
@@ -97,6 +113,8 @@ Usage:
   corvio workspaces list|use|current|create [id]
   corvio capabilities
   corvio ask --prompt <text> [--conversation-id <id>] [--allow-actions]
+  corvio agents list|connect|create|update|rotate [id]
+  corvio agent claim|renew|complete|fail|comments|comment|reply|status|run [id]
   corvio questions list|get [id]
   corvio conversations list|get [id]
   corvio search <query>
@@ -112,6 +130,7 @@ Global options:
 Authentication:
   CORVIO_API_KEY=cvu_... takes precedence over the stored device-link login.
   Legacy Workspace-bound cvk_ keys remain supported.
+  Agent runtime commands use CORVIO_AGENT_API_KEY=cvg_... and never borrow the user's credential.
   Select the target with 'corvio workspaces use <id>', --workspace, or CORVIO_WORKSPACE_ID.
   Run 'corvio auth login' when no environment key is configured.
 `;
@@ -120,7 +139,9 @@ const COMMAND_HELP = Object.freeze({
   auth: `Usage: corvio auth login|status|logout\n\nAuthenticate with a user-level device link, inspect the current principal, or revoke the stored credential.`,
   workspaces: `Usage:\n  corvio workspaces list\n  corvio workspaces use <workspace-id>\n  corvio workspaces current\n  corvio workspaces create --name <name> [--kind personal|team]\n\nWorkspace status and blocked capability reasons are returned with each item.`,
   capabilities: `Usage: corvio capabilities [--json]\n\nShow live API resources, principal scopes, selected Workspace status, and CLI compatibility.`,
-  ask: `Usage: corvio ask --prompt <text> [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--idempotency-key <key>]`,
+  ask: `Usage: corvio ask --prompt <text> [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--context-file <json>] [--idempotency-key <key>]`,
+  agents: `Usage:\n  corvio agents list\n  corvio agents connect --handle <handle> [--provider codex|claude_code|custom] [--permissions read,comment,edit]\n  corvio agents create --handle <handle> --display-name <name> [--provider codex|claude_code|custom] [--permissions read,comment,edit]\n  corvio agents update <id> [--display-name <name>] [--status active|paused|revoked] [--permissions <list>]\n  corvio agents rotate <id>\n\n'connect' explicitly creates a separate cvg_ Agent principal after user authentication and leaves naming pending in Workspace. It never converts the human cvu_ login into an Agent. Creation and rotation print the cvg_ secret once.`,
+  agent: `Usage:\n  corvio agent claim [--worker-id <id>] [--wait-seconds <0-30>]\n  corvio agent renew <event-id> --lease-token <token> [--lease-seconds <30-900>]\n  corvio agent complete <event-id> --lease-token <token> [--result-file <json>]\n  corvio agent fail <event-id> --lease-token <token> --error <message>\n  corvio agent comments --document-id <id>\n  corvio agent comment --document-id <id> --body <text> [--selection-file <json>]\n  corvio agent reply <thread-id> --document-id <id> --body <text>\n  corvio agent status <thread-id> --document-id <id> --status open|resolved\n  corvio agent run --handler <executable> [--once]\n\nThe runner leases durable events and renews its lease while work is active. The handler reads event JSON from stdin and returns {"instruction":"...","reply":"..."}; Corvio Query owns document changes and returns the durable receipt.`,
   questions: `Usage:\n  corvio questions list [--limit <n>] [--cursor <cursor>] [--conversation-id <id>]\n  corvio questions get <question-id>`,
   conversations: `Usage:\n  corvio conversations list [--limit <n>] [--cursor <cursor>]\n  corvio conversations get <conversation-id>`,
   search: `Usage: corvio search <query> [--limit <n>] [--page-id <id>] [--node-id <id>]`,
@@ -151,6 +172,8 @@ function normalizeInvocation(command, action) {
     docs: "list",
     projects: "create",
     files: "list",
+    agents: "list",
+    agent: "claim",
     sync: "status",
     update: "check",
   };
@@ -184,6 +207,13 @@ function validateInvocation(options, positionals) {
       "files:download",
       "files:organize",
       "files:open",
+      "agents:update",
+      "agents:rotate",
+      "agent:complete",
+      "agent:renew",
+      "agent:fail",
+      "agent:reply",
+      "agent:status",
     ]);
     assertPositionalCount(positionals, actionsWithId.has(`${command}:${action}`) ? 3 : command === "capabilities" ? 1 : 2);
   }
@@ -256,6 +286,30 @@ async function client(options, { auth = true, workspace = "required" } = {}) {
   };
 }
 
+function agentClient(options) {
+  const credential = readAgentCredential();
+  return new ApiClient({
+    baseUrl: baseUrl(options),
+    credential: credential.key,
+    userAgent: USER_AGENT,
+  });
+}
+
+async function readJsonObject(path, label) {
+  let value;
+  try {
+    value = JSON.parse(await readFile(resolve(String(path)), "utf8"));
+  } catch (error) {
+    throw new CliError(`${label} must be a readable JSON file: ${error instanceof Error ? error.message : String(error)}`, {
+      code: "invalid_json_file",
+    });
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new CliError(`${label} must contain one JSON object.`, { code: "invalid_json_file" });
+  }
+  return value;
+}
+
 async function authLogin(options) {
   const current = await readWorkspaceCredential();
   if (current?.source === "environment" && !options.force) {
@@ -474,6 +528,9 @@ async function ask(options, positionals) {
   const prompt = String(options.prompt || positionals.join(" ")).trim();
   if (!prompt) throw new CliError("Provide --prompt <text> or a positional prompt.");
   const { api } = await client(options);
+  const context = options["context-file"]
+    ? await readJsonObject(options["context-file"], "--context-file")
+    : null;
   const result = await api.request("/questions", {
     method: "POST",
     headers: { "idempotency-key": idempotencyKey(options) },
@@ -482,12 +539,368 @@ async function ask(options, positionals) {
       conversation_id: options["conversation-id"] || null,
       mode: options["allow-actions"] ? "allow_actions" : "answer_only",
       sources: listOption(options, "sources", ["workspace", "web", "memory"]),
+      context,
     },
     timeoutMs: 330_000,
   });
   writeResult(result, { json: options.json });
 }
 
+async function agents(options, action, id) {
+  const { api } = await client(options);
+  let result;
+  if (action === "list") {
+    result = await api.request("/agents", { query: { include_revoked: options["include-revoked"] || undefined } });
+  } else if (action === "connect") {
+    result = await api.request("/agents", {
+      method: "POST",
+      body: {
+        handle: option(options, "handle", { required: true }),
+        avatar_url: options["avatar-url"] || null,
+        provider: options.provider || "custom",
+        permissions: listOption(options, "permissions", ["read", "comment"]),
+        pending_naming: true,
+      },
+    });
+  } else if (action === "create") {
+    result = await api.request("/agents", {
+      method: "POST",
+      body: {
+        handle: option(options, "handle", { required: true }),
+        display_name: option(options, "display-name", { required: true }),
+        avatar_url: options["avatar-url"] || null,
+        provider: options.provider || "custom",
+        permissions: listOption(options, "permissions", ["read", "comment"]),
+      },
+    });
+  } else if (action === "update") {
+    const agentId = id || option(options, "id", { required: true });
+    const body = {};
+    if (options["display-name"] !== undefined) body.display_name = options["display-name"];
+    if (options["avatar-url"] !== undefined) body.avatar_url = options["avatar-url"];
+    if (options.status !== undefined) body.status = options.status;
+    if (options.permissions !== undefined) body.permissions = listOption(options, "permissions");
+    if (Object.keys(body).length === 0) throw new CliError("Provide an Agent field to update.", { code: "agent_update_required" });
+    result = await api.request(`/agents/${resourcePath(agentId)}`, { method: "PATCH", body });
+  } else if (action === "rotate") {
+    const agentId = id || option(options, "id", { required: true });
+    result = await api.request(`/agents/${resourcePath(agentId)}/credentials:rotate`, { method: "POST" });
+  } else {
+    throw new CliError("agents action must be list, connect, create, update, or rotate.");
+  }
+  writeResult(result, { json: options.json });
+}
+
+async function claimAgentEvent(api, options, waitFallback = 0) {
+  return api.request("/agent-events:claim", {
+    method: "POST",
+    body: {
+      worker_id: options["worker-id"] || `corvio-cli-${process.pid}`,
+      lease_seconds: numberOption(options, "lease-seconds", 300, { minimum: 30, maximum: 900 }),
+      wait_seconds: numberOption(options, "wait-seconds", waitFallback, { minimum: 0, maximum: 30 }),
+    },
+    timeoutMs: 45_000,
+  });
+}
+
+function runAgentHandler(executable, event) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const handlerEvent = { ...event, delivery: { ...(event?.delivery || {}) } };
+    delete handlerEvent.delivery.lease_token;
+    const handlerEnv = { ...process.env, CORVIO_AGENT_EVENT_ID: String(event.id || "") };
+    delete handlerEnv.CORVIO_API_KEY;
+    const child = spawn(String(executable), [], {
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: handlerEnv,
+    });
+    let stdout = "";
+    let stderr = "";
+    const maximumBytes = 1024 * 1024;
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      if (Buffer.byteLength(stdout) > maximumBytes) child.kill("SIGTERM");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-20_000);
+    });
+    child.on("error", (error) => rejectPromise(new CliError(`Agent handler could not start: ${error.message}`, { code: "agent_handler_failed" })));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        rejectPromise(new CliError(`Agent handler exited with ${code}: ${stderr.trim() || "no error output"}`, { code: "agent_handler_failed" }));
+        return;
+      }
+      let decision;
+      try {
+        decision = JSON.parse(stdout.trim());
+      } catch {
+        rejectPromise(new CliError("Agent handler must print one JSON object.", { code: "agent_handler_result_invalid" }));
+        return;
+      }
+      const instruction = String(decision?.instruction || "").trim();
+      if (!instruction) {
+        rejectPromise(new CliError("Agent handler result requires a non-empty instruction.", { code: "agent_handler_result_invalid" }));
+        return;
+      }
+      resolvePromise({ instruction, reply: String(decision?.reply || "").trim() || null });
+    });
+    child.stdin.end(`${JSON.stringify(handlerEvent)}\n`);
+  });
+}
+
+async function startAgentLeaseHeartbeat(api, event, leaseToken, leaseSeconds) {
+  let stopped = false;
+  let timer = null;
+  let inFlight = null;
+  let failure = null;
+  const intervalMs = Math.max(10_000, Math.min(60_000, Math.floor(leaseSeconds * 1_000 / 3)));
+  const renew = async () => {
+    if (stopped || failure) return;
+    try {
+      await api.request(`/agent-events/${resourcePath(event.id)}:renew`, {
+        method: "POST",
+        body: { lease_token: leaseToken, lease_seconds: leaseSeconds },
+      });
+    } catch (error) {
+      failure = error;
+      return;
+    }
+    if (!stopped) timer = setTimeout(() => { inFlight = renew(); }, intervalMs);
+  };
+  inFlight = renew();
+  await inFlight;
+  if (failure) throw failure;
+  return {
+    async stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      if (inFlight) await inFlight;
+    },
+    assertHealthy() {
+      if (failure) throw failure;
+    },
+  };
+}
+
+async function processClaimedAgentEvent(api, event, options) {
+  const leaseToken = String(event?.delivery?.lease_token || "");
+  if (!event?.id || !leaseToken) throw new CliError("Claimed event is missing its lease receipt.", { code: "agent_event_invalid" });
+  const leaseSeconds = numberOption(options, "lease-seconds", 300, { minimum: 30, maximum: 900 });
+  let heartbeat = null;
+  try {
+    heartbeat = await startAgentLeaseHeartbeat(api, event, leaseToken, leaseSeconds);
+    const decision = await runAgentHandler(option(options, "handler", { required: true }), event);
+    const question = await api.request("/questions", {
+      method: "POST",
+      headers: { "idempotency-key": `agent-event:${event.id}:query` },
+      body: {
+        prompt: decision.instruction,
+        mode: "allow_actions",
+        sources: listOption(options, "sources", ["workspace", "web", "memory"]),
+        context: {
+          agent_event: {
+            id: event.id,
+            kind: event.kind,
+            object_kind: event.object_kind,
+            object_id: event.object_id,
+            actor_user_id: event.actor_user_id,
+            actor_agent_id: event.actor_agent_id,
+            lineage: event.lineage,
+          },
+          collaboration: event.context,
+        },
+      },
+      timeoutMs: 330_000,
+    });
+    if (String(question.status || "") !== "completed") {
+      throw new CliError(`Corvio Query did not complete durably (status: ${question.status || "unknown"}).`, {
+        code: "agent_query_not_completed",
+      });
+    }
+    const documentId = String(event?.context?.document?.document_id || "");
+    const threadId = String(event?.context?.comment?.thread_id || "");
+    let commentEntryId = null;
+    if (documentId && threadId) {
+      const reply = String(decision.reply || question.answer || "Completed the requested review.").trim().slice(0, 12_000);
+      const mentionTargets = await resolveAgentMentionTargets(api, documentId, reply);
+      const thread = await api.request(`/documents/${resourcePath(documentId)}/comments/${resourcePath(threadId)}/replies`, {
+        method: "POST",
+        body: {
+          body: reply,
+          mention_targets: mentionTargets,
+          entry_point: "external_agent_runner",
+          source_event_id: event.id,
+          source_event_lease_token: leaseToken,
+        },
+      });
+      const entries = Array.isArray(thread?.entries) ? thread.entries : [];
+      commentEntryId = entries.at(-1)?.id || null;
+    }
+    await heartbeat.stop();
+    heartbeat.assertHealthy();
+    const completed = await api.request(`/agent-events/${resourcePath(event.id)}:complete`, {
+      method: "POST",
+      body: {
+        lease_token: leaseToken,
+        result: {
+          question_id: question.id,
+          ...(commentEntryId ? { comment_entry_id: commentEntryId } : {}),
+          status: question.status,
+          artifact_ids: Array.isArray(question.artifacts) ? question.artifacts.map((item) => item.document_id).filter(Boolean) : [],
+        },
+      },
+    });
+    return { event: completed, question, comment_entry_id: commentEntryId };
+  } catch (error) {
+    if (heartbeat) {
+      try {
+        await heartbeat.stop();
+      } catch {
+        // The original execution error remains the failure authority.
+      }
+    }
+    try {
+      await api.request(`/agent-events/${resourcePath(event.id)}:fail`, {
+        method: "POST",
+        body: { lease_token: leaseToken, error: error instanceof Error ? error.message : String(error), retryable: true },
+      });
+    } catch {
+      // Preserve the original execution failure; the expired lease remains reclaimable.
+    }
+    throw error;
+  }
+}
+
+async function runAgent(options) {
+  const api = agentClient(options);
+  while (true) {
+    const claimed = await claimAgentEvent(api, options, options.once ? 0 : 30);
+    if (!claimed.event) {
+      if (options.once) return writeResult({ processed: false, reason: "no_event", retry_after_seconds: claimed.retry_after_seconds }, { json: options.json });
+      continue;
+    }
+    const receipt = await processClaimedAgentEvent(api, claimed.event, options);
+    if (options.once) return writeResult({ processed: true, ...receipt }, { json: options.json });
+    process.stdout.write(`${JSON.stringify({ processed: true, ...receipt })}\n`);
+  }
+}
+
+async function resolveAgentMentionTargets(api, documentId, body) {
+  const aliases = Array.from(String(body || "").matchAll(/(?:^|\s)@([a-z0-9][a-z0-9._-]{0,63})/gi))
+    .map((match) => String(match[1] || "").toLowerCase());
+  if (!aliases.length) return [];
+  const response = await api.request(`/documents/${resourcePath(documentId)}/mention-candidates`);
+  const byHandle = new Map((Array.isArray(response?.data) ? response.data : []).map((candidate) => [
+    String(candidate.handle || "").toLowerCase(),
+    candidate,
+  ]));
+  const seen = new Set();
+  return aliases.flatMap((alias) => {
+    const candidate = byHandle.get(alias);
+    if (!candidate?.id || seen.has(candidate.id)) return [];
+    seen.add(candidate.id);
+    return [{ kind: "agent", principal_id: candidate.id, alias: candidate.handle }];
+  });
+}
+
+async function agentCommand(options, action, id) {
+  if (action === "run") return runAgent(options);
+  const api = agentClient(options);
+  let result;
+  if (action === "claim") {
+    result = await claimAgentEvent(api, options);
+  } else if (action === "renew") {
+    const eventId = id || option(options, "id", { required: true });
+    result = await api.request(`/agent-events/${resourcePath(eventId)}:renew`, {
+      method: "POST",
+      body: {
+        lease_token: option(options, "lease-token", { required: true }),
+        lease_seconds: numberOption(options, "lease-seconds", 300, { minimum: 30, maximum: 900 }),
+      },
+    });
+  } else if (action === "complete") {
+    const eventId = id || option(options, "id", { required: true });
+    const receipt = options["result-file"]
+      ? await readJsonObject(options["result-file"], "--result-file")
+      : {
+          ...(options["question-id"] ? { question_id: options["question-id"] } : {}),
+          ...(options["comment-entry-id"] ? { comment_entry_id: options["comment-entry-id"] } : {}),
+          ...(options["no-change-reason"] ? { no_change_reason: options["no-change-reason"] } : {}),
+        };
+    if (Object.keys(receipt).length === 0) throw new CliError("Provide a durable completion receipt.", { code: "agent_event_receipt_required" });
+    result = await api.request(`/agent-events/${resourcePath(eventId)}:complete`, {
+      method: "POST",
+      body: { lease_token: option(options, "lease-token", { required: true }), result: receipt },
+    });
+  } else if (action === "fail") {
+    const eventId = id || option(options, "id", { required: true });
+    result = await api.request(`/agent-events/${resourcePath(eventId)}:fail`, {
+      method: "POST",
+      body: {
+        lease_token: option(options, "lease-token", { required: true }),
+        error: option(options, "error", { required: true }),
+        retryable: String(options.retryable ?? "true").toLowerCase() !== "false",
+      },
+    });
+  } else if (action === "comments") {
+    result = await api.request(`/documents/${resourcePath(option(options, "document-id", { required: true }))}/comments`);
+  } else if (action === "comment") {
+    const documentId = option(options, "document-id", { required: true });
+    const body = option(options, "body", { required: true });
+    const selection = options["selection-file"]
+      ? await readJsonObject(options["selection-file"], "--selection-file")
+      : { target_scope: "document" };
+    result = await api.request(`/documents/${resourcePath(documentId)}/comments`, {
+      method: "POST",
+      body: {
+        body,
+        mention_targets: await resolveAgentMentionTargets(api, documentId, body),
+        selection,
+        entry_point: "external_agent_cli",
+        start_new_chain: Boolean(options["start-new-chain"]),
+      },
+    });
+  } else if (action === "reply") {
+    const threadId = id || option(options, "id", { required: true });
+    const documentId = option(options, "document-id", { required: true });
+    const bodyText = option(options, "body", { required: true });
+    const hasSourceEventId = Boolean(options["source-event-id"]);
+    const hasSourceEventLease = Boolean(options["source-event-lease-token"]);
+    if (hasSourceEventId !== hasSourceEventLease) {
+      throw new CliError("Provide --source-event-id and --source-event-lease-token together.", {
+        code: "agent_reply_source_incomplete",
+      });
+    }
+    if (hasSourceEventId && options["start-new-chain"]) {
+      throw new CliError("A source event reply cannot also start a new chain.", {
+        code: "agent_reply_source_conflict",
+      });
+    }
+    result = await api.request(`/documents/${resourcePath(documentId)}/comments/${resourcePath(threadId)}/replies`, {
+      method: "POST",
+      body: {
+        body: bodyText,
+        mention_targets: await resolveAgentMentionTargets(api, documentId, bodyText),
+        entry_point: "external_agent_cli_reply",
+        ...(options["source-event-id"] ? { source_event_id: options["source-event-id"] } : {}),
+        ...(options["source-event-lease-token"] ? { source_event_lease_token: options["source-event-lease-token"] } : {}),
+        start_new_chain: Boolean(options["start-new-chain"]),
+      },
+    });
+  } else if (action === "status") {
+    const threadId = id || option(options, "id", { required: true });
+    result = await api.request(`/documents/${resourcePath(option(options, "document-id", { required: true }))}/comments/${resourcePath(threadId)}/status`, {
+      method: "POST",
+      body: { status: option(options, "status", { required: true }), entry_point: "external_agent_cli_status" },
+    });
+  } else {
+    throw new CliError("Unknown agent runtime action.");
+  }
+  writeResult(result, { json: options.json });
+}
+
 function pageQuery(options) {
   return {
     limit: numberOption(options, "limit", 20, { maximum: 100 }),
@@ -1256,6 +1669,8 @@ async function main({ options, positionals }) {
   }
   if (command === "capabilities") return capabilities(options);
   if (command === "ask") return ask(options, [action, id, ...rest].filter(Boolean));
+  if (command === "agents") return agents(options, action || "list", id);
+  if (command === "agent") return agentCommand(options, action || "claim", id);
   if (command === "questions") return questions(options, action || "list", id);
   if (command === "conversations") return conversations(options, action || "list", id);
   if (command === "search") return search(options, [action, id, ...rest].filter(Boolean));

package/dist/core.js

@@ -95,6 +95,9 @@ export function parseArgv(argv) {
     "allow-actions",
     "private-link",
     "force",
+    "once",
+    "include-revoked",
+    "start-new-chain",
     "help",
     "version",
   ]);
@@ -585,6 +588,23 @@ export async function readWorkspaceCredential(env = process.env) {
   return { key, source: "device_link", profile: profileName, metadata };
 }
 
+export function readAgentCredential(env = process.env) {
+  const key = String(env.CORVIO_AGENT_API_KEY || "").trim();
+  if (!key) {
+    throw new CliError(
+      "No Agent credential found. Set CORVIO_AGENT_API_KEY to the cvg_ secret returned when the Agent was created.",
+      { code: "agent_auth_required", exitCode: EXIT.AUTH },
+    );
+  }
+  if (!key.startsWith("cvg_")) {
+    throw new CliError("CORVIO_AGENT_API_KEY must be an Agent cvg_ key.", {
+      code: "invalid_agent_key",
+      exitCode: EXIT.AUTH,
+    });
+  }
+  return { key, source: "environment", profile: null, metadata: null };
+}
+
 export async function storeWorkspaceCredential(payload, env = process.env) {
   const path = workspaceCredentialPath(env);
   const root = dirname(path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corvio/cli",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.7",
   "description": "Official Corvio Workspace CLI for questions, knowledge search, documents, and Agent workflows.",
   "type": "module",
   "bin": {