@corvio/cli 0.1.0-beta.15 → 0.1.0-beta.16

package/README.md

@@ -10,6 +10,8 @@ corvio agents connect --provider codex --project . --json
 corvio collaboration status --json --no-input
 corvio ask --prompt 'Summarize recurring launch risks' --json
 corvio files upload --file ./research.pdf --json
+corvio files organize <asset_id> --instruction 'Create a reusable decision brief' --yes --json
+corvio files operation <operation_id> --json
 corvio sync init --dir ./knowledge --root-node-id <node_id> --json
 corvio update check --json
 ```
@@ -18,6 +20,8 @@ When no environment key is configured, run `corvio auth login`. Login creates on
 
 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. When the executing principal is a connected Agent, `docs update` also requires `--change-summary`, creates a visible document-level comment after the guarded write, and returns its receipt; a comment failure is reported as a partial effect rather than silent success. When a Corvio document or comment supplied the task, use `corvio agent closeout` to return the verified outcome, optionally resolve the thread, and read both document and thread back. 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.
 
+File organization is asynchronous. A queued organization receipt is progress, not completion: continue from its stable operation ID with `corvio files operation <operation_id>` and only report completion after the terminal receipt exposes the resulting artifacts, Skill evaluation, and durable links.
+
 ## Project Agent collaboration
 
 Connect the current project with the user credential. User and Agent credentials stay deliberately separate, and the secret is never printed, written into the project, or passed to the provider:

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   agentCredentialPath,
 } from "./core.js";
 
-const VERSION = "0.1.0-beta.15";
+const VERSION = "0.1.0-beta.16";
 const DEFAULT_API_BASE = "https://api.corvio.ai/v1";
 const DEFAULT_APP_BASE = "https://corvio.ai";
 const USER_AGENT = `corvio-cli/${VERSION}`;
@@ -69,7 +69,10 @@ const COMMAND_OPTIONS = Object.freeze({
   "workspaces:create": ["name", "kind", "description", "idempotency-key"],
   "capabilities:": [],
   "collaboration:status": ["project", "provider"],
-  "ask:": ["prompt", "conversation-id", "sources", "allow-actions", "context-file", "idempotency-key"],
+  "ask:": [
+    "prompt", "conversation-id", "sources", "allow-actions", "context-file", "idempotency-key",
+    "processing-profile", "max-processing-profile", "scan-mode", "skills-extraction-mode", "caller-model",
+  ],
   "agents:list": ["include-revoked"],
   "agents:connect": [
     "handle", "display-name", "provider", "project", "permission-profile", "trigger-policy",
@@ -88,7 +91,10 @@ const COMMAND_OPTIONS = Object.freeze({
   "agent:reply": ["document-id", "id", "body", "source-event-id", "source-event-lease-token", "start-new-chain", "idempotency-key"],
   "agent:status": ["document-id", "id", "status"],
   "agent:closeout": ["document-id", "thread-id", "body", "status", "idempotency-key"],
-  "agent:run": ["once", "handler", "provider", "worker-id", "lease-seconds", "wait-seconds", "sources", "project"],
+  "agent:run": [
+    "once", "handler", "provider", "worker-id", "lease-seconds", "wait-seconds", "sources", "project",
+    "processing-profile", "max-processing-profile", "scan-mode", "skills-extraction-mode", "caller-model",
+  ],
   "questions:list": ["limit", "cursor", "conversation-id"],
   "questions:get": ["id"],
   "conversations:list": ["limit", "cursor"],
@@ -108,8 +114,15 @@ const COMMAND_OPTIONS = Object.freeze({
   "files:list": ["limit"],
   "files:get": ["id"],
   "files:download": ["id", "output"],
-  "files:upload": ["file", "mime-type"],
-  "files:organize": ["id", "instruction", "target-root-node-id"],
+  "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",
+  ],
+  "files:organize": [
+    "id", "additional-asset-ids", "instruction", "target-root-node-id",
+    "processing-profile", "max-processing-profile", "scan-mode", "skills-extraction-mode", "caller-model",
+  ],
+  "files:operation": ["id"],
   "files:open": ["id"],
   "sync:init": ["root-node-id", "dir", "name", "force"],
   "sync:status": ["dir"],
@@ -127,7 +140,7 @@ Usage:
   corvio workspaces list|use|current|create [id]
   corvio capabilities
   corvio collaboration status [--project <path>] [--provider codex|claude_code|copilot]
-  corvio ask --prompt <text> [--conversation-id <id>] [--allow-actions]
+  corvio ask --prompt <text> [--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]
@@ -135,7 +148,7 @@ Usage:
   corvio search <query>
   corvio docs list|get|create|update|move|archive|restore|share|open [id]
   corvio projects list|create
-  corvio files list|get|download|upload|organize|open [id]
+  corvio files list|get|download|upload|organize|operation|open [id]
   corvio sync init|status|plan|pull|push|resolve
   corvio update check
 
@@ -156,15 +169,15 @@ 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]\n\nVerify that the current project has a bound Corvio Agent, the official collaboration Skill is discoverable at the live contract version, and the inbound listener state is reported separately. This is the foreground work-loop readiness check; a listening process alone is not enough.`,
-  ask: `Usage: corvio ask --prompt <text> [--conversation-id <id>] [--sources workspace,web,memory] [--allow-actions] [--context-file <json>] [--idempotency-key <key>]`,
+  ask: `Usage: corvio ask --prompt <text> [--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\nSkill extraction mode always requires --allow-actions; 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 foreground Skill readiness separately; run corvio collaboration status after installing or refreshing the Skill. 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]\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.`,
+  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>`,
   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 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\nDirect document commands operate on canonical Page/Markdown. Use \`corvio ask --allow-actions\` for Spreadsheet, Presentation, Code, HTML Artifact, or semantic organization. Agent-authenticated document updates 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 grouping owners in the Corvio Docs tree. Reuse a matching Project instead of creating one ceremonial Project per file. 'corvio folders' is an alias.`,
-  files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id>\n  corvio files download <id> [--output <path>]\n  corvio files upload --file <path> [--mime-type <type>]\n  corvio files organize <id> --instruction <text> --yes [--target-root-node-id <id>]\n  corvio files open <id>`,
+  files: `Usage:\n  corvio files list [--limit <n>]\n  corvio files get <id>\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>] [--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 open <id>\n\nUpload alone preserves the original file. Organization is asynchronous: use 'files operation' to read its terminal result, derived artifacts, Skill evaluation, and links before claiming completion.`,
   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.`,
 });
@@ -225,6 +238,7 @@ function validateInvocation(options, positionals) {
       "files:get",
       "files:download",
       "files:organize",
+      "files:operation",
       "files:open",
       "agents:update",
       "agents:rotate",
@@ -883,14 +897,30 @@ async function ask(options, positionals) {
   const context = options["context-file"]
     ? await readJsonObject(options["context-file"], "--context-file")
     : null;
+  const processingProfile = enumOption(options, "processing-profile", ["auto", "economy", "standard", "deep"], "auto");
+  const maxProcessingProfile = optionalEnumOption(options, "max-processing-profile", ["economy", "standard", "deep"]);
+  const scanMode = enumOption(options, "scan-mode", ["auto", "always", "off"], "auto");
+  const skillsExtractionMode = enumOption(options, "skills-extraction-mode", ["auto", "always", "off"], "auto");
+  if (skillsExtractionMode === "always" && !options["allow-actions"]) {
+    throw new CliError("--skills-extraction-mode always requires --allow-actions.", {
+      code: "skills_extraction_requires_actions",
+    });
+  }
   const result = await api.request("/questions", {
     method: "POST",
-    headers: { "idempotency-key": idempotencyKey(options) },
+    headers: {
+      "idempotency-key": idempotencyKey(options),
+      ...(options["caller-model"] ? { "x-corvio-caller-model": String(options["caller-model"]) } : {}),
+    },
     body: {
       prompt,
       conversation_id: options["conversation-id"] || null,
       mode: options["allow-actions"] ? "allow_actions" : "answer_only",
       sources: listOption(options, "sources", ["workspace", "web", "memory"]),
+      processing_profile: processingProfile,
+      max_processing_profile: maxProcessingProfile,
+      scan_mode: scanMode,
+      skills_extraction_mode: skillsExtractionMode,
       context,
     },
     timeoutMs: 330_000,
@@ -907,6 +937,21 @@ async function ask(options, positionals) {
   writeResult({ ...result, routing: execution.routing }, { json: options.json });
 }
 
+function enumOption(options, name, allowed, fallback) {
+  const value = String(options[name] ?? fallback).trim().toLowerCase();
+  if (!allowed.includes(value)) {
+    throw new CliError(`--${name} must be one of: ${allowed.join(", ")}.`, {
+      code: `${name.replaceAll("-", "_")}_invalid`,
+    });
+  }
+  return value;
+}
+
+function optionalEnumOption(options, name, allowed) {
+  if (options[name] === undefined) return null;
+  return enumOption(options, name, allowed, null);
+}
+
 function providerChildEnvironment(extra = {}) {
   const allowedNames = new Set([
     "PATH", "HOME", "USER", "LOGNAME", "SHELL", "TERM", "TMPDIR",
@@ -1815,6 +1860,11 @@ async function requestAgentCorvioQuestion(workspaceApi, event, leaseToken, {
   round,
   conversationId = null,
   priorTurn = null,
+  processingProfile = "auto",
+  maxProcessingProfile = null,
+  scanMode = "auto",
+  skillsExtractionMode = "auto",
+  callerModel = null,
 }) {
   const question = await workspaceApi.request("/questions", {
     method: "POST",
@@ -1824,12 +1874,17 @@ async function requestAgentCorvioQuestion(workspaceApi, event, leaseToken, {
         : `agent-event:${event.id}:query:${round}`,
       "x-corvio-agent-event-id": event.id,
       "x-corvio-agent-event-lease-token": leaseToken,
+      ...(callerModel ? { "x-corvio-caller-model": callerModel } : {}),
     },
     body: {
       prompt: instruction,
       ...(conversationId ? { conversation_id: conversationId } : {}),
       mode,
       sources: [],
+      processing_profile: processingProfile,
+      max_processing_profile: maxProcessingProfile,
+      scan_mode: scanMode,
+      skills_extraction_mode: skillsExtractionMode,
       context: {
         agent_event: agentEventContext(event),
         collaboration: event.context,
@@ -1961,11 +2016,24 @@ async function processClaimedAgentEvent(api, event, options) {
     const decision = options.handler
       ? { execution_target: "corvio_document", ...(await runAgentHandler(options.handler, event)) }
       : await runProjectProviderPlan(event, provider, binding);
+    const questionExecution = {
+      processingProfile: enumOption(options, "processing-profile", ["auto", "economy", "standard", "deep"], "auto"),
+      maxProcessingProfile: optionalEnumOption(options, "max-processing-profile", ["economy", "standard", "deep"]),
+      scanMode: enumOption(options, "scan-mode", ["auto", "always", "off"], "auto"),
+      skillsExtractionMode: enumOption(options, "skills-extraction-mode", ["auto", "always", "off"], "auto"),
+      callerModel: String(options["caller-model"] || "").trim() || null,
+    };
+    const initialQuestionMode =
+      decision.execution_target === "corvio_document" ||
+      questionExecution.skillsExtractionMode === "always"
+        ? "allow_actions"
+        : "answer_only";
     const workspaceApi = await agentClient(options, String(event.workspace_id || ""));
     let question = await requestAgentCorvioQuestion(workspaceApi, event, leaseToken, {
       instruction: decision.instruction,
-      mode: decision.execution_target === "corvio_document" ? "allow_actions" : "answer_only",
+      mode: initialQuestionMode,
       round: 1,
+      ...questionExecution,
     });
     const questions = [question];
     const instructions = new Set([decision.instruction.trim().toLowerCase()]);
@@ -1990,7 +2058,7 @@ async function processClaimedAgentEvent(api, event, options) {
       round: 1,
       question_id: question.id || null,
       conversation_id: question.conversation_id || null,
-      requested_mode: decision.execution_target === "corvio_document" ? "allow_actions" : "answer_only",
+      requested_mode: initialQuestionMode,
       provider_outcome: providerExecution.outcome,
       next_action: providerExecution.next_action,
     }];
@@ -2026,13 +2094,17 @@ async function processClaimedAgentEvent(api, event, options) {
         break;
       }
       instructions.add(normalizedInstruction);
-      const requestedMode = providerExecution.corvio_mode;
+      const requestedMode =
+        questionExecution.skillsExtractionMode === "always"
+          ? "allow_actions"
+          : providerExecution.corvio_mode;
       question = await requestAgentCorvioQuestion(workspaceApi, event, leaseToken, {
         instruction: nextInstruction,
         mode: requestedMode,
         round: questions.length + 1,
         conversationId: question.conversation_id || null,
         priorTurn: providerExecution,
+        ...questionExecution,
       });
       questions.push(question);
       providerExecution = await runProjectProviderExecution(
@@ -2830,25 +2902,46 @@ async function files(options, action, id) {
         exitCode: EXIT.REMOTE,
       });
     }
+    if (options.organize) {
+      requireConfirmation(options, "Starting semantic organization for the uploaded file");
+      const organization = await api.request(`/files/${resourcePath(result.id)}:organize`, {
+        method: "POST",
+        headers: options["caller-model"] ? { "x-corvio-caller-model": String(options["caller-model"]) } : {},
+        body: fileOrganizationBody(options),
+      });
+      result = { file: result, organization };
+    }
   } else if (action === "organize") {
     requireConfirmation(options, "Starting a file organization run");
     result = await api.request(`/files/${resourcePath(assetId || option(options, "id", { required: true }))}:organize`, {
       method: "POST",
-      body: {
-        instruction: option(options, "instruction", { required: true }),
-        target_root_node_id: options["target-root-node-id"] || null,
-      },
+      headers: options["caller-model"] ? { "x-corvio-caller-model": String(options["caller-model"]) } : {},
+      body: fileOrganizationBody(options),
     });
+  } else if (action === "operation") {
+    result = await api.request(`/file-operations/${resourcePath(assetId || option(options, "id", { required: true }))}`);
   } 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)}`;
     result = { file_id: targetId, url: target, opened: options["no-input"] ? false : await openBrowser(target) };
   } else {
-    throw new CliError("files action must be list, get, download, upload, organize, or open.");
+    throw new CliError("files action must be list, get, download, upload, organize, operation, or open.");
   }
   writeResult(result, { json: options.json });
 }
 
+function fileOrganizationBody(options) {
+  return {
+    instruction: option(options, "instruction", { required: true }),
+    target_root_node_id: options["target-root-node-id"] || null,
+    additional_asset_ids: listOption(options, "additional-asset-ids", []),
+    processing_profile: enumOption(options, "processing-profile", ["auto", "economy", "standard", "deep"], "auto"),
+    max_processing_profile: optionalEnumOption(options, "max-processing-profile", ["economy", "standard", "deep"]),
+    scan_mode: enumOption(options, "scan-mode", ["auto", "always", "off"], "auto"),
+    skills_extraction_mode: enumOption(options, "skills-extraction-mode", ["auto", "always", "off"], "auto"),
+  };
+}
+
 function sha256(content) {
   return createHash("sha256").update(content).digest("hex");
 }

package/dist/core.js

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

package/package.json

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