@corvio/cli 0.1.0-beta.35 → 0.1.0-beta.36

package/README.md

@@ -12,9 +12,9 @@ corvio collaboration status --json --no-input
 corvio ask --prompt 'Summarize recurring launch risks' --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 --json
-corvio files operation <operation_id> --json
-corvio files resume <operation_id> --yes --json
+corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --wait-until-terminal --timeout-seconds 1200 --json
+corvio files operation <operation_id> --wait-until-terminal --timeout-seconds 1200 --json
+corvio files resume <operation_id> --yes --wait-until-terminal --timeout-seconds 1200 --json
 corvio docs read <workspace_id/document_id> --mode auto --json
 corvio docs patch <workspace_id/document_id> --input ./patch.json --operation-id <id> --yes --json
 corvio docs table-read <workspace_id/document_id> --limit 25 --json
@@ -47,7 +47,7 @@ Treat files as a value ladder, not one upload event. Upload/finalize preserves t
 
 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.
 
-File organization is asynchronous. A queued organization receipt is progress, not completion: continue from its stable operation ID with `corvio files operation <operation_id>`. Blocked operations expose their typed error and can be continued with `corvio files resume <operation_id> --yes`; queued/running/blocked operations can be stopped with `corvio files cancel <operation_id> --yes`. Report completion only after the terminal receipt exposes the output document, source reconciliation, Skill evaluation, and durable links. `skills_extraction_mode=always` requires the evaluation; `evaluated_no_qualifying_skill` is a valid terminal result and is preferable to a fabricated Skill.
+File organization is asynchronous. A queued organization receipt is progress, not completion. When this authenticated CLI is already the natural transport, `--wait-until-terminal` keeps deterministic status reads inside one foreground process; `--timeout-seconds` is a bounded local deadline, and expiry returns the latest non-terminal receipt with `transport_wait.status=deadline_reached`. Without that flag, `corvio files operation <operation_id>` remains one immediate read. Blocked operations expose their typed error and can be continued with `corvio files resume <operation_id> --yes`; queued/running/blocked operations can be stopped with `corvio files cancel <operation_id> --yes`. Report completion only after the terminal receipt exposes the output document, source reconciliation, Skill evaluation, and durable links. `skills_extraction_mode=always` requires the evaluation; `evaluated_no_qualifying_skill` is a valid terminal result and is preferable to a fabricated Skill.
 
 ## Project Agent collaboration
 

package/dist/cli.js

@@ -39,13 +39,16 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.35";
+const VERSION = "0.1.0-beta.36";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
 const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
 const MAX_SYNC_FILES = 2_000;
 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 CORVIO_SKILL_ARCHIVE = "https://corvio.ai/developers/skills/corvio-operate-workspace/corvio-operate-workspace.zip";
 const AGENT_SKILLS_INSTALLER_VERSION = "1.5.23";
 const GLOBAL_OPTIONS = Object.freeze([
@@ -126,13 +129,15 @@ const COMMAND_OPTIONS = Object.freeze({
   "files:upload": [
     "file", "mime-type", "organize", "instruction", "target-root-node-id", "additional-asset-ids",
     "processing-profile", "max-processing-profile", "scan-mode", "skills-extraction-mode", "caller-model",
+    "wait-until-terminal", "timeout-seconds",
   ],
   "files:organize": [
     "id", "additional-asset-ids", "instruction", "target-root-node-id",
     "processing-profile", "max-processing-profile", "scan-mode", "skills-extraction-mode", "caller-model",
+    "wait-until-terminal", "timeout-seconds",
   ],
-  "files:operation": ["id"],
-  "files:resume": ["id"],
+  "files:operation": ["id", "wait-until-terminal", "timeout-seconds"],
+  "files:resume": ["id", "wait-until-terminal", "timeout-seconds"],
   "files:cancel": ["id"],
   "files:open": ["id"],
   "sync:init": ["root-node-id", "dir", "name", "force"],
@@ -188,7 +193,7 @@ const COMMAND_HELP = Object.freeze({
   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.`,
   projects: `Usage:\n  corvio projects list [--limit <n>]\n  corvio projects create --title <title> [--idempotency-key <key>]\n\nProjects are durable root-level grouping owners in the Corvio Docs tree and cannot be nested under another Project. Reuse a matching Project instead of creating one ceremonial Project per file; use semantic branch Pages and leaves for deeper Work Models. 'corvio folders' is an alias.`,
-  files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id> [--content]\n  corvio files download <id> [--output <path>]\n  corvio files upload --file <path> [--mime-type <type>] [--organize --instruction <text> --additional-asset-ids <id,id> --yes]\n  corvio files organize <id> --instruction <text> --yes [--additional-asset-ids <id,id>] [--target-root-node-id <project-node-id>] [--processing-profile auto|economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off]\n  corvio files operation <operation-id>\n  corvio files resume <operation-id> --yes\n  corvio files cancel <operation-id> --yes\n  corvio files open <id>\n\nUse --content only when source facts are needed. It returns one bounded AI-safe projection with hash, completeness, and truncation receipts; it does not rewrite or materialize the original. Upload alone preserves the exact original, provenance, hash, policy, and stable Asset ID. Organization is a separate asynchronous value step: one coherent source set can produce reader-facing structure, source reconciliation, Memory candidates, and qualifying Project Skills. Pass --instruction a weak natural goal plus explicit user constraints and only authority facts needed to prevent wrong identity or scope. Keep source-derived facts in the source; do not precompute an outline, edit checklist, taxonomy, titles, artifact count, or sole leaf target from current visibility. A heterogeneous source may update several real Projects while its provenance carrier stays a standalone document; do not direct Corvio to make the source Page an umbrella Project. For a newly finalized Asset that should enter a Work Model or Skill evaluation, use one organize operation as the sole semantic owner; do not open ask before or after it for the same Asset set. --target-root-node-id is optional and accepts only a Project node_id returned by projects list, never a Page/document UUID or leaf node; omit it when the Project is not known. Use 'files operation' to reach terminal and inspect output_document plus skills_evaluation; always requires evaluation but may correctly return evaluated_no_qualifying_skill. Resume reuses the same durable operation after resolving its blocker; cancel is idempotent.`,
+  files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id> [--content]\n  corvio files download <id> [--output <path>]\n  corvio files upload --file <path> [--mime-type <type>] [--organize --instruction <text> --additional-asset-ids <id,id> --yes] [--wait-until-terminal] [--timeout-seconds <1-7200>]\n  corvio files organize <id> --instruction <text> --yes [--additional-asset-ids <id,id>] [--target-root-node-id <project-node-id>] [--processing-profile auto|economy|standard|deep] [--scan-mode auto|always|off] [--skills-extraction-mode auto|always|off] [--wait-until-terminal] [--timeout-seconds <1-7200>]\n  corvio files operation <operation-id> [--wait-until-terminal] [--timeout-seconds <1-7200>]\n  corvio files resume <operation-id> --yes [--wait-until-terminal] [--timeout-seconds <1-7200>]\n  corvio files cancel <operation-id> --yes\n  corvio files open <id>\n\nUse --content only when source facts are needed. It returns one bounded AI-safe projection with hash, completeness, and truncation receipts; it does not rewrite or materialize the original. Upload alone preserves the exact original, provenance, hash, policy, and stable Asset ID. Organization is a separate asynchronous value step: one coherent source set can produce reader-facing structure, source reconciliation, Memory candidates, and qualifying Project Skills. Pass --instruction a weak natural goal plus explicit user constraints and only authority facts needed to prevent wrong identity or scope. Keep source-derived facts in the source; do not precompute an outline, edit checklist, taxonomy, titles, artifact count, or sole leaf target from current visibility. A heterogeneous source may update several real Projects while its provenance carrier stays a standalone document; do not direct Corvio to make the source Page an umbrella Project. For a newly finalized Asset that should enter a Work Model or Skill evaluation, use one organize operation as the sole semantic owner; do not open ask before or after it for the same Asset set. --target-root-node-id is optional and accepts only a Project node_id returned by projects list, never a Page/document UUID or leaf node; omit it when the Project is not known. Use --wait-until-terminal when a filesystem-capable Host should keep deterministic polling inside this one foreground CLI invocation; --timeout-seconds is a local wait deadline, and reaching it returns the latest non-terminal receipt rather than claiming completion. Without that flag, 'files operation' remains an immediate read. Inspect terminal output_document plus skills_evaluation; evaluated_no_qualifying_skill is valid. Resume reuses the same durable operation after resolving its blocker; cancel is idempotent.`,
   sync: `Usage:\n  corvio sync init --root-node-id <id> [--dir <path>] [--name <name>]\n  corvio sync status|plan|pull [--dir <path>]\n  corvio sync push --yes [--dir <path>]\n  corvio sync resolve --conflict-id <id> --strategy use-remote|keep-local --yes [--dir <path>]`,
   update: `Usage: corvio update check [--json]\n\nCompare this executable with the reviewed API policy and the npm beta dist-tag.`,
 });
@@ -3456,7 +3461,77 @@ async function uploadWorkspaceFile(api, inputPath, mimeTypeOverride) {
   return result;
 }
 
+function fileOperationWaitTimeoutSeconds(options) {
+  if (!options["wait-until-terminal"]) {
+    if (options["timeout-seconds"] !== undefined) {
+      throw new CliError("--timeout-seconds requires --wait-until-terminal.", {
+        code: "file_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 fileOperationIsPending(result) {
+  return FILE_OPERATION_PENDING_STATUSES.has(String(result?.status || "").trim().toLowerCase());
+}
+
+function fileOperationDeadlineReceipt(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 files operation command with --wait-until-terminal; do not start a replacement operation.",
+    },
+  };
+}
+
+async function waitForFileOperation(api, operationId, { initialResult = null, timeoutSeconds }) {
+  const startedAtMs = Date.now();
+  const deadlineAtMs = startedAtMs + timeoutSeconds * 1000;
+  let result = initialResult;
+  let operationReadCount = 0;
+  while (true) {
+    if (!result) {
+      result = await api.request(`/file-operations/${resourcePath(operationId)}`);
+      operationReadCount += 1;
+    }
+    if (!fileOperationIsPending(result)) return result;
+
+    const remainingMs = deadlineAtMs - Date.now();
+    if (remainingMs <= 0) {
+      return fileOperationDeadlineReceipt(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(remainingMs, Math.max(50, Math.min(30_000, requestedDelayMs))));
+    result = null;
+  }
+}
+
 async function files(options, action, id) {
+  const waitTimeoutSeconds = fileOperationWaitTimeoutSeconds(options);
+  if (action === "upload" && waitTimeoutSeconds !== null && !options.organize) {
+    throw new CliError("--wait-until-terminal requires --organize for files upload.", {
+      code: "file_operation_wait_requires_organize",
+    });
+  }
   const { api } = await executionClient(options);
   const assetId = id || options.id;
   let result;
@@ -3492,27 +3567,50 @@ async function files(options, action, id) {
         headers: options["caller-model"] ? { "x-corvio-caller-model": String(options["caller-model"]) } : {},
         body: fileOrganizationBody(options),
       });
-      result = { file: result, organization };
+      result = {
+        file: result,
+        organization: waitTimeoutSeconds === null
+          ? organization
+          : await waitForFileOperation(api, organization.operation_id, {
+            initialResult: organization,
+            timeoutSeconds: waitTimeoutSeconds,
+          }),
+      };
     }
   } else if (action === "organize") {
     requireConfirmation(options, "Starting a file organization run");
-    result = await api.request(`/files/${resourcePath(assetId || option(options, "id", { required: true }))}:organize`, {
+    const organization = await api.request(`/files/${resourcePath(assetId || option(options, "id", { required: true }))}:organize`, {
       method: "POST",
       headers: options["caller-model"] ? { "x-corvio-caller-model": String(options["caller-model"]) } : {},
       body: fileOrganizationBody(options),
     });
+    result = waitTimeoutSeconds === null
+      ? organization
+      : await waitForFileOperation(api, organization.operation_id, {
+        initialResult: organization,
+        timeoutSeconds: waitTimeoutSeconds,
+      });
   } else if (action === "operation") {
-    result = await api.request(`/file-operations/${resourcePath(assetId || option(options, "id", { required: true }))}`);
+    const operationId = assetId || option(options, "id", { required: true });
+    result = waitTimeoutSeconds === null
+      ? await api.request(`/file-operations/${resourcePath(operationId)}`)
+      : await waitForFileOperation(api, operationId, { timeoutSeconds: waitTimeoutSeconds });
   } else if (action === "resume" || action === "cancel") {
     const operationId = assetId || option(options, "id", { required: true });
     requireConfirmation(
       options,
       `${action === "resume" ? "Resuming" : "Cancelling"} this file organization operation`,
     );
-    result = await api.request(`/file-operations/${resourcePath(operationId)}:${action}`, {
+    const operation = await api.request(`/file-operations/${resourcePath(operationId)}:${action}`, {
       method: "POST",
       retrySafe: true,
     });
+    result = action === "resume" && waitTimeoutSeconds !== null
+      ? await waitForFileOperation(api, operationId, {
+        initialResult: operation,
+        timeoutSeconds: waitTimeoutSeconds,
+      })
+      : operation;
   } else if (action === "open") {
     const targetId = assetId || option(options, "id", { required: true });
     const target = `${String(process.env.CORVIO_APP_BASE || DEFAULT_APP_BASE).replace(/\/+$/, "")}/app/a/${resourcePath(targetId)}`;

package/dist/core.js

@@ -102,6 +102,7 @@ export function parseArgv(argv) {
     "recover-credential",
     "no-listen",
     "start-new-chain",
+    "wait-until-terminal",
     "help",
     "version",
   ]);

package/package.json

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