@corvio/cli 0.1.0-beta.37 → 0.1.0-beta.38

package/README.md

@@ -10,6 +10,9 @@ corvio auth status
 corvio agents connect --provider codex --project . --json
 corvio collaboration status --json --no-input
 corvio ask --prompt 'Summarize recurring launch risks' --json
+corvio ask --background --prompt 'Reconcile the current launch evidence' --json
+corvio questions operation <operation_id> --after-cursor <progress_cursor> --wait-until-terminal --json
+corvio questions cancel <operation_id> --yes --json
 corvio files upload --file ./research.pdf --json
 corvio files get <asset_id> --content --json
 corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --wait-until-terminal --timeout-seconds 1200 --json
@@ -54,6 +57,13 @@ Read the terminal Question receipt and use `artifact.url` or
 `links.primary_artifact` verbatim; `reader_output` artifacts are deliverables, `structure_container` artifacts are hierarchy, and
 `node_id` is never a document URL.
 
+For a Question that may outlive one host turn, add `--background`. The command returns one durable `operation_id` immediately. Continue
+that same operation with `corvio questions operation`; `--wait-until-terminal` keeps the status loop inside the CLI, while
+`--after-cursor` returns only later user-visible milestones. A local deadline is not remote cancellation. Use
+`corvio questions cancel <operation_id> --yes` to request a stop, and do not report success until the returned state is actually
+`cancelled`. Progress is a bounded phase summary, never hidden reasoning or a provisional final answer. To correct the objective, finish
+or cancel the current operation and start a successor `corvio ask --conversation-id <conversation_id>` rather than silently replacing it.
+
 Treat files as a value ladder, not one upload event. Upload/finalize preserves the exact original, provenance, hash, policy, and stable Asset ID. A selected Markdown file can become an editable Page through `corvio docs create --file`; for other formats or a coherent source set, use `corvio files organize` or `corvio ask --allow-actions` to produce the reader-facing Page, Spreadsheet, Presentation, Code, HTML Artifact, or reading layer that fits the task. Stable facts/preferences may enter Memory; only an evidence-backed reusable method, configuration, constraint, or quality bar should become a Project Skill.
 
 Use `corvio files get <asset_id> --content` when the task needs only bounded facts from one retained source. The response preserves the immutable original as authority, reports its source hash and whether the projection is complete or truncated, and does not create a Question or materialize another document. Never infer unseen workbook rows/sheets or document sections.

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.37";
+const VERSION = "0.1.0-beta.38";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -49,6 +49,7 @@ const MAX_MARKDOWN_CHARACTERS = 120_000;
 const DEFAULT_FILE_OPERATION_WAIT_TIMEOUT_SECONDS = 1_200;
 const MAX_FILE_OPERATION_WAIT_TIMEOUT_SECONDS = 7_200;
 const FILE_OPERATION_PENDING_STATUSES = new Set(["accepted", "pending", "prepared", "queued", "running"]);
+const QUESTION_OPERATION_PENDING_STATUSES = new Set(["queued", "running"]);
 const READ_ONLY_LOCAL_STATE_ERROR_CODES = new Set(["EACCES", "EPERM", "EROFS"]);
 const CORVIO_SKILL_ARCHIVE = "https://corvio.ai/developers/skills/corvio-operate-workspace/corvio-operate-workspace.zip";
 const AGENT_SKILLS_INSTALLER_VERSION = "1.5.23";
@@ -88,7 +89,7 @@ const COMMAND_OPTIONS = Object.freeze({
   "ask:": [
     "prompt", "conversation-id", "sources", "allow-actions", "context-file", "idempotency-key",
     "processing-profile", "max-processing-profile", "scan-mode", "skills-extraction-mode", "caller-model",
-    "file", "asset-ids", "mime-type",
+    "file", "asset-ids", "mime-type", "background",
   ],
   "agents:list": ["include-revoked"],
   "agents:connect": [
@@ -114,6 +115,8 @@ const COMMAND_OPTIONS = Object.freeze({
   ],
   "questions:list": ["limit", "cursor", "conversation-id"],
   "questions:get": ["id"],
+  "questions:operation": ["id", "after-cursor", "wait-until-terminal", "timeout-seconds"],
+  "questions:cancel": ["id"],
   "conversations:list": ["limit", "cursor"],
   "conversations:get": ["id"],
   "search:": ["query", "limit", "page-id", "node-id"],
@@ -171,7 +174,7 @@ Usage:
   corvio ask --prompt <text> [--file <path>] [--asset-ids <id,id>] [--conversation-id <id>] [--allow-actions] [--processing-profile auto|economy|standard|deep]
   corvio agents list|connect|create|update|rotate [id]
   corvio agent claim|renew|complete|fail|comments|comment|reply|status|closeout|run [id]
-  corvio questions list|get [id]
+  corvio questions list|get|operation|cancel [id]
   corvio conversations list|get [id]
   corvio search <query>
   corvio docs list|get|read|patch|table-read|table-mutate|create|update|move|archive|restore|share|open [id]
@@ -197,10 +200,10 @@ const COMMAND_HELP = Object.freeze({
   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.`,
   collaboration: `Usage:\n  corvio collaboration status [--project <path>] [--provider codex|claude_code|copilot|workbuddy]\n\nCheck local Corvio prerequisites and every discoverable Corvio Skill copy. Current copies stay quiet; non-current receipts include one compact Agent notice and a source-aware next action. Standalone refresh commands pin the verified installer, select exactly one provider, and preserve project/global scope. WorkBuddy inspection is read-only and never changes ~/.workbuddy. The CLI cannot prove that the current host task loaded a particular copy, or whether remote MCP or host memory is active.`,
-  ask: `Usage: corvio ask --prompt <text> [--file <path>] [--asset-ids <id,id>] [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--processing-profile auto|economy|standard|deep] [--max-processing-profile economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off] [--caller-model <host-model>] [--context-file <json>] [--idempotency-key <key>]\n\nAnswer-only is the default: omit --allow-actions; there is no --mode option. Keep the user's natural question unchanged, then append the smallest complete decision-relevant context or stable handles as a separate clause. A carried Project handle normally bounds a cross-branch question without enumerating all descendants. Handles are evidence addresses: do not invent a comparison rubric, prescribe reasoning steps, substitute another user objective, or turn current Tree labels into a detailed task plan. Unless the user chose them, do not invent taxonomy, titles, artifact count, or Corvio's internal plan; Corvio chooses the cognitive structure and carriers. In a bounded read-only continuation, start this foreground command exactly once when a trusted current-task or prior receipt already proves this authenticated CLI and exact Workspace; do not launch an identical Question concurrently or retry before terminal exit. If the host shell yields a running-session handle, wait on that exact handle until the CLI exits instead of answering from prior context. It returns the terminal Question without model-visible polling. Transport continuity does not prove a cheaper processing profile; leave processing on auto unless the remaining transformation independently justifies another profile. Do not install, probe, or switch to the CLI only for that optimization, and do not extend it to an unbound Workspace. --file retains the selected local file, verifies its hash, and attaches the finalized Asset to this exact question. --asset-ids attaches already-retained Corvio Assets. Use --allow-actions when Corvio should create the Page, Spreadsheet, Presentation, Code, HTML Artifact, Memory, or qualifying Project Skill that best serves the result. A continuation handle is subject evidence, not necessarily the durable write destination: for a reusable pattern or method, resolve the fitting same-scope Memory or Skill owner before admitting or merging it. Read the terminal Question receipt and use artifact.url or links.primary_artifact verbatim; reader_output artifacts are deliverables, structure_container artifacts are hierarchy, and node_id is never a document URL. Upload alone is not evidence of interpretation. Skill extraction mode always requires --allow-actions and an evidence-backed decision, not forced Skill creation; answer-only questions may use auto or off.`,
+  ask: `Usage: corvio ask --prompt <text> [--file <path>] [--asset-ids <id,id>] [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--background] [--processing-profile auto|economy|standard|deep] [--max-processing-profile economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off] [--caller-model <host-model>] [--context-file <json>] [--idempotency-key <key>]\n\nAnswer-only is the default: omit --allow-actions; there is no --mode option. Keep the user's natural question unchanged, then append the smallest complete decision-relevant context or stable handles as a separate clause. A carried Project handle normally bounds a cross-branch question without enumerating all descendants. Handles are evidence addresses: do not invent a comparison rubric, prescribe reasoning steps, substitute another user objective, or turn current Tree labels into a detailed task plan. Unless the user chose them, do not invent taxonomy, titles, artifact count, or Corvio's internal plan; Corvio chooses the cognitive structure and carriers. In a bounded read-only continuation, start this foreground command exactly once when a trusted current-task or prior receipt already proves this authenticated CLI and exact Workspace; do not launch an identical Question concurrently or retry before terminal exit. If the shell tool yields a running-session handle, wait on that exact handle until the CLI exits instead of answering from prior context. It returns the terminal Question without model-visible polling. Use --background for work that should outlive the current shell; it returns one durable operation immediately. Inspect it with questions operation, stop it with questions cancel, and use the terminal conversation_id for a corrected follow-up instead of silently changing an in-flight objective. Transport continuity does not prove a cheaper processing profile; leave processing on auto unless the remaining transformation independently justifies another profile. Do not install, probe, or switch to the CLI only to avoid MCP polling, and do not extend it to an unbound Workspace. --file retains the selected local file, verifies its hash, and attaches the finalized Asset to this exact question. --asset-ids attaches already-retained Corvio Assets. Use --allow-actions when Corvio should create the Page, Spreadsheet, Presentation, Code, HTML Artifact, Memory, or qualifying Project Skill that best serves the result. A continuation handle is subject evidence, not necessarily the durable write destination: for a reusable pattern or method, resolve the fitting same-scope Memory or Skill owner before admitting or merging it. Read the terminal Question receipt and use artifact.url or links.primary_artifact verbatim; reader_output artifacts are deliverables, structure_container artifacts are hierarchy, and node_id is never a document URL. Upload alone is not evidence of interpretation. Skill extraction mode always requires --allow-actions and an evidence-backed decision, not forced Skill creation; answer-only questions may use auto or off.`,
   agents: `Usage:\n  corvio agents list\n  corvio agents connect [--provider codex|claude_code|copilot] [--project <path>] [--permission-profile read_only|workspace_write|danger_full_access] [--trigger-policy owner_only|workspace_members] [--display-name <name>] [--recover-credential] [--no-listen]\n  corvio agents create --handle <handle> --display-name <name> [--provider codex|claude_code|copilot|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' binds the current Git project (or --project path) to one stable personal Agent. Repeating it is idempotent; another project creates another Agent. It reports provider/CLI, listener, and local Skill prerequisites separately; run corvio collaboration status after installing or refreshing the Skill. The CLI cannot prove that the current host task loaded those surfaces. The default workspace_write profile is limited by the provider's native sandbox. owner_only is the safe trigger default. Secrets and absolute project paths stay local.`,
   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 mentions --document-id <id> [--query <name>]\n  corvio agent comments --document-id <id>\n  corvio agent comment --document-id <id> --body <text> [--selection-file <json>] [--start-new-chain] [--idempotency-key <key>]\n  corvio agent reply <thread-id> --document-id <id> --body <text> [--source-event-id <id> --source-event-lease-token <token>|--start-new-chain] [--idempotency-key <key>]\n  corvio agent status <thread-id> --document-id <id> --status open|resolved\n  corvio agent closeout --document-id <id> [--thread-id <id>] --body <verified-result> [--status open|resolved] [--idempotency-key <key>]\n  corvio agent run [--provider codex|claude_code|copilot|custom] [--handler <executable>] [--agent <id>] [--once] [--processing-profile auto|economy|standard|deep] [--max-processing-profile economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off] [--caller-model <host-model>]\n\nUse mentions before commenting when the target is uncertain; aliases resolve to stable user or Agent IDs and ambiguity fails closed. Use closeout when a Corvio document or comment owned the task: it returns the verified result to that surface and reads document/comments back. Agent-to-Agent comments require either a claimed source event or explicit --start-new-chain. The runner iteratively exchanges origin-scoped evidence with Corvio Query/Writer, then invokes the bound provider inside its local project. Local code changes use the recorded provider permission profile; complex Corvio document changes belong to Query/Writer. Provider children never receive Corvio credentials.`,
-  questions: `Usage:\n  corvio questions list [--limit <n>] [--cursor <cursor>] [--conversation-id <id>]\n  corvio questions get <question-id>`,
+  questions: `Usage:\n  corvio questions list [--limit <n>] [--cursor <cursor>] [--conversation-id <id>]\n  corvio questions get <question-id>\n  corvio questions operation <operation-id> [--after-cursor <n>] [--wait-until-terminal] [--timeout-seconds <1-7200>]\n  corvio questions cancel <operation-id> --yes\n\nA Question operation is the durable owner for background work. operation returns only new user-visible milestones after --after-cursor and never exposes hidden reasoning or provisional answer text. --wait-until-terminal keeps deterministic polling in this process and returns a typed deadline receipt if the local deadline expires. cancel is idempotent; treat cancellation_requested as non-terminal and verify cancelled before telling the user the task stopped. Cancellation does not roll back effects that already settled. To correct the objective, stop or finish the current operation, then use corvio ask --conversation-id <conversation_id> so the new Question is an explicit successor.`,
   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>]`,
   docs: `Usage:\n  corvio docs list [--limit <n>] [--cursor <cursor>] [--lifecycle active|archived]\n  corvio docs get <id> [--output <path>]\n  corvio docs read <id> [--mode auto|overview|line-range|section|search|full] [--start-line <n> --end-line <n>|--section-ref <S#>|--query <text>] [--max-chars <n>]\n  corvio docs patch <id> --input <json> --yes [--operation-id <id>] [--change-summary <text>]\n  corvio docs table-read <id> [--table-id <id>] [--after-row-id <id>] [--limit <1-100>]\n  corvio docs table-mutate <id> --input <json> --yes [--operation-id <id>] [--change-summary <text>]\n  corvio docs create --title <title> [--file <path>|--markdown <text>] [--parent-node-id <id>] [--idempotency-key <key>]\n  corvio docs update <id> [--title <title>] [--file <path>|--markdown <text>] [--expected-revision <n>] [--change-summary <text>]\n  corvio docs move <id> --parent-node-id <id>\n  corvio docs archive <id> --yes\n  corvio docs restore <id> --yes\n  corvio docs share <id> --yes [--display-name <name>]\n  corvio docs open <id>\n\nUse \`docs read --mode auto\` first for a small full body or a large-document overview, then read an exact section or line range. Use \`docs patch\` when the host already knows 1-20 exact L# replacements; it preserves untouched lines and returns a compact verified delta. A selected Markdown file can become an editable Page without resending the body through the model. Use \`docs update\` only when whole-body replacement is the smallest faithful change. Delegate document-wide judgment, cross-source synthesis, structure/formatting interpretation, and typed Spreadsheet, Presentation, Code, or HTML work to \`corvio ask --allow-actions\`. A Project is a structure container; body writes fail with project_structure_container_body_write_disabled, while a title-only Project rename remains valid. Projects stay at the Workspace root and cannot be nested; use \`files organize\` or \`ask --allow-actions\` for Work Model maintenance. Use table-read plus table-mutate for bounded stable-ID cell updates or row appends. Agent-authenticated document changes require --change-summary and create a visible document-level comment after the guarded update. When a document/comment is the task owner, use \`corvio agent closeout\` to return verified work to that same collaboration surface and read it back.`,
@@ -258,6 +261,8 @@ function validateInvocation(options, positionals) {
     const actionsWithId = new Set([
       "workspaces:use",
       "questions:get",
+      "questions:operation",
+      "questions:cancel",
       "conversations:get",
       "docs:get",
       "docs:read",
@@ -1274,7 +1279,7 @@ async function ask(options, positionals) {
   const uniqueAssetIds = [...new Set(assetIds.map((value) => String(value).trim()).filter(Boolean))];
   let result;
   try {
-    result = await api.request("/questions", {
+    result = await api.request(options.background ? "/question-operations" : "/questions", {
       method: "POST",
       headers: {
         "idempotency-key": idempotencyKey(options),
@@ -1292,7 +1297,7 @@ async function ask(options, positionals) {
         skills_extraction_mode: skillsExtractionMode,
         context,
       },
-      timeoutMs: 330_000,
+      timeoutMs: options.background ? 30_000 : 330_000,
     });
   } catch (error) {
     if (attachedAssets.length > 0) {
@@ -2952,12 +2957,114 @@ function pageQuery(options) {
 
 async function questions(options, action, id) {
   const { api } = await executionClient(options, { continuityId: options["conversation-id"] || null });
-  const result = action === "list"
-    ? await api.request("/questions", { query: pageQuery(options) })
-    : await api.request(`/questions/${resourcePath(id || option(options, "id", { required: true }))}`);
+  let result;
+  if (action === "list") {
+    result = await api.request("/questions", { query: pageQuery(options) });
+  } else if (action === "get") {
+    result = await api.request(`/questions/${resourcePath(id || option(options, "id", { required: true }))}`);
+  } else if (action === "operation") {
+    const operationId = id || option(options, "id", { required: true });
+    const afterCursor = numberOption(options, "after-cursor", 0, { minimum: 0 });
+    const timeoutSeconds = questionOperationWaitTimeoutSeconds(options);
+    result = timeoutSeconds === null
+      ? await api.request(`/question-operations/${resourcePath(operationId)}`, {
+        query: { after_cursor: afterCursor },
+      })
+      : await waitForQuestionOperation(api, operationId, {
+        afterCursor,
+        timeoutSeconds,
+      });
+  } else if (action === "cancel") {
+    const operationId = id || option(options, "id", { required: true });
+    requireConfirmation(options, `Cancelling Question operation ${operationId}`);
+    result = await api.request(`/question-operations/${resourcePath(operationId)}/cancel`, {
+      method: "POST",
+      retrySafe: true,
+    });
+  } else {
+    throw new CliError("questions action must be list, get, operation, or cancel.");
+  }
   writeResult(result, { json: options.json });
 }
 
+function questionOperationWaitTimeoutSeconds(options) {
+  if (!options["wait-until-terminal"]) {
+    if (options["timeout-seconds"] !== undefined) {
+      throw new CliError("--timeout-seconds requires --wait-until-terminal.", {
+        code: "question_operation_wait_required",
+      });
+    }
+    return null;
+  }
+  return numberOption(
+    options,
+    "timeout-seconds",
+    DEFAULT_FILE_OPERATION_WAIT_TIMEOUT_SECONDS,
+    { minimum: 1, maximum: MAX_FILE_OPERATION_WAIT_TIMEOUT_SECONDS },
+  );
+}
+
+function questionOperationIsPending(result) {
+  return QUESTION_OPERATION_PENDING_STATUSES.has(String(result?.status || "").trim().toLowerCase());
+}
+
+function questionOperationDeadlineReceipt(result, { timeoutSeconds, startedAtMs, operationReadCount }) {
+  return {
+    ...result,
+    transport_wait: {
+      status: "deadline_reached",
+      terminal: false,
+      timeout_seconds: timeoutSeconds,
+      elapsed_seconds: Math.max(0, Math.round((Date.now() - startedAtMs) / 1000)),
+      operation_read_count: operationReadCount,
+      continuation: "Run the same questions operation command with --wait-until-terminal; do not start a replacement Question.",
+    },
+  };
+}
+
+async function waitForQuestionOperation(api, operationId, { afterCursor, timeoutSeconds }) {
+  const startedAtMs = Date.now();
+  const deadlineAtMs = startedAtMs + timeoutSeconds * 1000;
+  let cursor = Math.max(0, Number(afterCursor) || 0);
+  let result = null;
+  let operationReadCount = 0;
+  while (true) {
+    const remainingMs = deadlineAtMs - Date.now();
+    if (remainingMs <= 0 && result) {
+      return questionOperationDeadlineReceipt(result, {
+        timeoutSeconds,
+        startedAtMs,
+        operationReadCount,
+      });
+    }
+    result = await api.request(`/question-operations/${resourcePath(operationId)}`, {
+      query: {
+        after_cursor: cursor,
+        wait_seconds: Math.max(0, Math.min(30, Math.ceil(remainingMs / 1000))),
+      },
+      timeoutMs: Math.max(35_000, Math.min(remainingMs + 5_000, 40_000)),
+    });
+    operationReadCount += 1;
+    if (Number.isFinite(Number(result.progress_cursor))) {
+      cursor = Math.max(cursor, Number(result.progress_cursor));
+    }
+    if (!questionOperationIsPending(result)) return result;
+    const nextRemainingMs = deadlineAtMs - Date.now();
+    if (nextRemainingMs <= 0) {
+      return questionOperationDeadlineReceipt(result, {
+        timeoutSeconds,
+        startedAtMs,
+        operationReadCount,
+      });
+    }
+    const retryAfterSeconds = Number(result.retry_after_seconds);
+    const requestedDelayMs = Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0
+      ? retryAfterSeconds * 1000
+      : 5_000;
+    await sleep(Math.min(nextRemainingMs, Math.max(50, Math.min(30_000, requestedDelayMs))));
+  }
+}
+
 async function conversations(options, action, id) {
   const conversationId = action === "get" ? id || options.id || null : null;
   const { api } = await executionClient(options, { continuityId: conversationId });

package/dist/core.js

@@ -93,6 +93,7 @@ export function parseArgv(argv) {
     "no-input",
     "yes",
     "allow-actions",
+    "background",
     "content",
     "organize",
     "private-link",

package/package.json

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