@arbidocs/cli 0.4.74 → 0.4.76

package/dist/index.js

@@ -13,6 +13,7 @@ var client = require('@arbidocs/client');
 var url = require('url');
 var crypto = require('crypto');
 var module$1 = require('module');
+var yaml = require('yaml');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -3694,7 +3695,7 @@ function getLatestVersion(skipCache = false) {
   }
 }
 function getCurrentVersion() {
-  return "0.4.74";
+  return "0.4.76";
 }
 function readChangelog(fromVersion, toVersion) {
   try {
@@ -3747,17 +3748,17 @@ function showChangelog(fromVersion, toVersion) {
 async function checkForUpdates(autoUpdate) {
   try {
     const latest = getLatestVersion();
-    if (!latest || latest === "0.4.74") return;
+    if (!latest || latest === "0.4.76") return;
     if (autoUpdate) {
       warn(`
-Your arbi version is out of date (${"0.4.74"} \u2192 ${latest}). Updating...`);
+Your arbi version is out of date (${"0.4.76"} \u2192 ${latest}). Updating...`);
       child_process.execSync("npm install -g @arbidocs/cli@latest", { stdio: "inherit" });
-      showChangelog("0.4.74", latest);
+      showChangelog("0.4.76", latest);
       console.log(`Updated to ${latest}.`);
     } else {
       warn(
         `
-Your arbi version is out of date (${"0.4.74"} \u2192 ${latest}).
+Your arbi version is out of date (${"0.4.76"} \u2192 ${latest}).
 Run "arbi update" to upgrade, or "arbi update auto" to always stay up to date.`
       );
     }
@@ -3789,10 +3790,10 @@ function markNagShown(latest) {
 function hintUpdateOnError() {
   try {
     const cached = readCache();
-    if (!cached || cached.latest === "0.4.74") return;
+    if (!cached || cached.latest === "0.4.76") return;
     if (!shouldShowNag(cached.latest)) return;
     warn(
-      `Your arbi version is out of date (${"0.4.74"} \u2192 ${cached.latest}). Run "arbi update".`
+      `Your arbi version is out of date (${"0.4.76"} \u2192 ${cached.latest}). Run "arbi update".`
     );
     markNagShown(cached.latest);
   } catch {
@@ -6322,10 +6323,10 @@ function registerDocsCommand(program2) {
       if (!opts.quiet && statusIntervalMs > 0) {
         statusTimer = setInterval(() => printStatus("  "), statusIntervalMs);
       }
-      const sleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
+      const sleep2 = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
       const backoff = async (attempt) => {
         const delayMs = Math.min(1e3 * Math.pow(2, attempt), 3e4);
-        await sleep(delayMs);
+        await sleep2(delayMs);
       };
       const submitBatch = async (batchIds) => {
         const updates = batchIds.map((id) => ({
@@ -6437,12 +6438,12 @@ function registerDocsCommand(program2) {
               }
               submitted += 1;
               if (intervalMs > 0 && j < batch.length - 1) {
-                await sleep(intervalMs);
+                await sleep2(intervalMs);
               }
             }
           }
           if (intervalMs > 0 && i + batchSize < docIds.length) {
-            await sleep(intervalMs);
+            await sleep2(intervalMs);
           }
         }
       } finally {
@@ -6520,19 +6521,19 @@ Processing complete: completed=${procCompleted} failed=0  elapsed=${totalElapsed
 }
 
 // src/commands/upload-shared.ts
-function printSummary(summary) {
+function printSummary(summary2) {
   console.log("");
   console.log("Upload summary:");
-  console.log(`  Files found:  ${summary.totalFiles}`);
-  success(`  Uploaded:     ${summary.uploaded}`);
-  if (summary.skipped > 0) {
-    warn(`  Skipped:      ${summary.skipped}`);
+  console.log(`  Files found:  ${summary2.totalFiles}`);
+  success(`  Uploaded:     ${summary2.uploaded}`);
+  if (summary2.skipped > 0) {
+    warn(`  Skipped:      ${summary2.skipped}`);
   }
-  console.log(`  Folders:      ${summary.folders}`);
-  if (summary.skippedDetails.length > 0) {
+  console.log(`  Folders:      ${summary2.folders}`);
+  if (summary2.skippedDetails.length > 0) {
     console.log("");
     warn("Skipped files:");
-    for (const s of summary.skippedDetails) {
+    for (const s of summary2.skippedDetails) {
       warn(`  ${s.file_name}: ${s.reason}`);
     }
   }
@@ -6550,10 +6551,10 @@ function countSupportedFiles(dirPath) {
   }
   return count;
 }
-function mergeBatchResult(summary, uploadedDocs, result, sourceLabel, opts) {
+function mergeBatchResult(summary2, uploadedDocs, result, sourceLabel, opts) {
   for (const [folder, info] of result.folders) {
-    summary.folders += 1;
-    summary.totalFiles += info.fileCount;
+    summary2.folders += 1;
+    summary2.totalFiles += info.fileCount;
     if (!opts.json) {
       success(
         `  ${folder || "<root>"}: ${info.fileCount} file(s) \u2192 ${info.doc_ext_ids.length} uploaded`
@@ -6564,10 +6565,10 @@ function mergeBatchResult(summary, uploadedDocs, result, sourceLabel, opts) {
     }
     for (const docId of info.doc_ext_ids) uploadedDocs.set(docId, sourceLabel);
   }
-  summary.uploaded += result.doc_ext_ids.length;
-  summary.skipped += result.skipped.length;
-  summary.docIds.push(...result.doc_ext_ids);
-  summary.skippedDetails.push(...result.skipped);
+  summary2.uploaded += result.doc_ext_ids.length;
+  summary2.skipped += result.skipped.length;
+  summary2.docIds.push(...result.doc_ext_ids);
+  summary2.skippedDetails.push(...result.skipped);
 }
 function classifyDirectInputs(inputPaths) {
   const out = [];
@@ -6632,7 +6633,7 @@ async function runDirectUploadMode(inputPaths, opts) {
   });
   const creds = store.requireCredentials();
   const workspaceKey = await sdk.getRawWorkspaceKey(arbi, workspaceId, creds.signingPrivateKeyBase64);
-  const summary = {
+  const summary2 = {
     totalFiles: 0,
     uploaded: 0,
     skipped: 0,
@@ -6669,7 +6670,7 @@ async function runDirectUploadMode(inputPaths, opts) {
         warn(`No supported files found in directory: ${inp.originalPath}`);
         continue;
       }
-      mergeBatchResult(summary, uploadedDocs, result2, inp.originalPath, opts);
+      mergeBatchResult(summary2, uploadedDocs, result2, inp.originalPath, opts);
       if (!opts.json) {
         success(
           `Uploaded directory: ${inp.originalPath} (${result2.doc_ext_ids.length} document(s) total)`
@@ -6688,7 +6689,7 @@ async function runDirectUploadMode(inputPaths, opts) {
         warn(`No supported files found in zip: ${inp.originalPath}`);
         continue;
       }
-      mergeBatchResult(summary, uploadedDocs, result2, inp.originalPath, opts);
+      mergeBatchResult(summary2, uploadedDocs, result2, inp.originalPath, opts);
       if (!opts.json) {
         success(
           `Uploaded zip: ${inp.originalPath} (${result2.doc_ext_ids.length} document(s) total)`
@@ -6706,7 +6707,7 @@ async function runDirectUploadMode(inputPaths, opts) {
       warn(`No supported files found in archive: ${inp.originalPath}`);
       continue;
     }
-    mergeBatchResult(summary, uploadedDocs, result, inp.originalPath, opts);
+    mergeBatchResult(summary2, uploadedDocs, result, inp.originalPath, opts);
     if (!opts.json) {
       success(
         `Uploaded archive: ${inp.originalPath} (${result.doc_ext_ids.length} document(s) total)`
@@ -6723,11 +6724,11 @@ async function runDirectUploadMode(inputPaths, opts) {
       folder: opts.folder,
       configExtId: opts.config
     });
-    summary.totalFiles += plainFiles.length;
-    summary.uploaded += result.doc_ext_ids.length;
-    summary.skipped += result.skipped.length;
-    summary.docIds.push(...result.doc_ext_ids);
-    summary.skippedDetails.push(...result.skipped);
+    summary2.totalFiles += plainFiles.length;
+    summary2.uploaded += result.doc_ext_ids.length;
+    summary2.skipped += result.skipped.length;
+    summary2.docIds.push(...result.doc_ext_ids);
+    summary2.skippedDetails.push(...result.skipped);
     for (let i = 0; i < result.doc_ext_ids.length && i < plainFiles.length; i++) {
       uploadedDocs.set(result.doc_ext_ids[i], path6__default.default.basename(plainFiles[i]));
     }
@@ -6738,9 +6739,9 @@ async function runDirectUploadMode(inputPaths, opts) {
     }
   }
   if (opts.json) {
-    console.log(JSON.stringify(summary));
+    console.log(JSON.stringify(summary2));
   } else {
-    printSummary(summary);
+    printSummary(summary2);
   }
   if (willWatch && uploadedDocs.size > 0) {
     const pending = new Set(uploadedDocs.keys());
@@ -6849,7 +6850,7 @@ function registerUploadCommand(program2) {
       });
       const uploadedDocs = /* @__PURE__ */ new Map();
       const auth = { baseUrl: config.baseUrl, accessToken };
-      const summary = {
+      const summary2 = {
         totalFiles: 0,
         uploaded: 0,
         skipped: 0,
@@ -6883,7 +6884,7 @@ function registerUploadCommand(program2) {
           if (opts.dryRun) {
             const count = countSupportedFiles2(filePath);
             console.log(`${filePath}: ${count} supported file(s) would be uploaded`);
-            summary.totalFiles += count;
+            summary2.totalFiles += count;
             continue;
           }
           const result = await sdk.documentsNode.uploadDirectory(auth, filePath, progressCallbacks);
@@ -6906,7 +6907,7 @@ function registerUploadCommand(program2) {
               `Uploaded directory: ${filePath} (${result.doc_ext_ids.length} document(s) total)`
             );
           }
-          updateSummary(summary, result);
+          updateSummary(summary2, result);
           for (const id of result.doc_ext_ids) uploadedDocs.set(id, filePath);
         } else if (filePath.toLowerCase().endsWith(".zip")) {
           if (opts.dryRun) {
@@ -6931,7 +6932,7 @@ function registerUploadCommand(program2) {
             }
             success(`Uploaded zip: ${filePath} (${result.doc_ext_ids.length} document(s) total)`);
           }
-          updateSummary(summary, result);
+          updateSummary(summary2, result);
           for (const id of result.doc_ext_ids) uploadedDocs.set(id, filePath);
         } else if (sdk.documentsNode.ARCHIVE_EXTENSIONS.has(
           filePath.slice(filePath.lastIndexOf(".")).toLowerCase()
@@ -6960,12 +6961,12 @@ function registerUploadCommand(program2) {
               `Uploaded archive: ${filePath} (${result.doc_ext_ids.length} document(s) total)`
             );
           }
-          updateSummary(summary, result);
+          updateSummary(summary2, result);
           for (const id of result.doc_ext_ids) uploadedDocs.set(id, filePath);
         } else {
           if (opts.dryRun) {
             console.log(`${filePath}: single file would be uploaded`);
-            summary.totalFiles += 1;
+            summary2.totalFiles += 1;
             continue;
           }
           const result = await sdk.documentsNode.uploadLocalFile(auth, filePath, {
@@ -6981,12 +6982,12 @@ function registerUploadCommand(program2) {
               );
             }
           }
-          summary.totalFiles += 1;
-          summary.uploaded += result.doc_ext_ids?.length ?? 0;
-          summary.docIds.push(...result.doc_ext_ids ?? []);
+          summary2.totalFiles += 1;
+          summary2.uploaded += result.doc_ext_ids?.length ?? 0;
+          summary2.docIds.push(...result.doc_ext_ids ?? []);
           if (result.skipped) {
-            summary.skipped += result.skipped.length;
-            summary.skippedDetails.push(...result.skipped);
+            summary2.skipped += result.skipped.length;
+            summary2.skippedDetails.push(...result.skipped);
           }
           for (const id of result.doc_ext_ids ?? []) uploadedDocs.set(id, result.fileName);
         }
@@ -6995,9 +6996,9 @@ function registerUploadCommand(program2) {
         return;
       }
       if (opts.json) {
-        console.log(JSON.stringify(summary));
+        console.log(JSON.stringify(summary2));
       } else {
-        printSummary(summary);
+        printSummary(summary2);
       }
       if (willWatch && uploadedDocs.size > 0) {
         const pending = new Set(uploadedDocs.keys());
@@ -7059,17 +7060,17 @@ Connection closed. ${pending.size} document(s) still processing.`);
     })()
   );
 }
-function updateSummary(summary, result) {
+function updateSummary(summary2, result) {
   let totalFiles = 0;
   for (const [, info] of result.folders) {
     totalFiles += info.fileCount;
-    summary.folders += 1;
+    summary2.folders += 1;
   }
-  summary.totalFiles += totalFiles;
-  summary.uploaded += result.doc_ext_ids.length;
-  summary.skipped += result.skipped.length;
-  summary.docIds.push(...result.doc_ext_ids);
-  summary.skippedDetails.push(...result.skipped);
+  summary2.totalFiles += totalFiles;
+  summary2.uploaded += result.doc_ext_ids.length;
+  summary2.skipped += result.skipped.length;
+  summary2.docIds.push(...result.doc_ext_ids);
+  summary2.skippedDetails.push(...result.skipped);
 }
 function countSupportedFiles2(dirPath) {
   let count = 0;
@@ -7752,10 +7753,10 @@ Error: ${message}`))
         saveLastMetadata(result.metadata);
       }
       const refs = sdk.countCitations(result.metadata);
-      const summary = opts.quiet !== true ? sdk.formatStreamSummary(result, elapsedTime) : "";
-      if (summary) {
+      const summary2 = opts.quiet !== true ? sdk.formatStreamSummary(result, elapsedTime) : "";
+      if (summary2) {
         const refSuffix = refs > 0 ? ` \xB7 ${refs} ref${refs === 1 ? "" : "s"}` : "";
-        const text = `[${summary}${refSuffix}]`;
+        const text = `[${summary2}${refSuffix}]`;
         const cols = process.stderr.columns || 80;
         const pad = Math.max(0, cols - text.length);
         console.error(chalk2__default.default.dim(" ".repeat(pad) + text));
@@ -9427,6 +9428,9 @@ async function runQuickstart(url) {
     console.log(`  Workspace: ${workspaceName} (${ref(workspaceId)})`);
     console.log("");
     dim('Try: arbi ask "hello"');
+    dim(
+      "Workflows with steps: arbi workflow create --name <n> --steps steps.yaml (see arbi run --help)"
+    );
   } catch (err) {
     if (isExitPromptError(err)) throw err;
     error(`Login failed: ${sdk.getErrorMessage(err)}`);
@@ -9793,14 +9797,59 @@ function registerTaskCommand(program2) {
     })()
   );
 }
+function readStructured(path8) {
+  let text;
+  try {
+    text = fs7.readFileSync(path8, "utf8");
+  } catch (err) {
+    throw new Error(`Cannot read ${path8}: ${err.message}`);
+  }
+  const ext = path6.extname(path8).toLowerCase();
+  try {
+    return ext === ".json" ? JSON.parse(text) : yaml.parse(text);
+  } catch (err) {
+    throw new Error(
+      `${path8} is not valid ${ext === ".json" ? "JSON" : "YAML"}: ${err.message}`
+    );
+  }
+}
+function readStepsFile(path8) {
+  try {
+    return sdk.workflowSteps.parsePlanSteps(readStructured(path8));
+  } catch (err) {
+    if (err instanceof sdk.PlanStepsError) throw new Error(`${path8}: ${err.message}`);
+    throw err;
+  }
+}
+function readInputsFile(path8) {
+  const value = readStructured(path8);
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new Error(`${path8}: expected an object of input values, e.g. {"client": "Acme"}`);
+  return value;
+}
+function collect(value, previous = []) {
+  return [...previous, value];
+}
+
+// src/commands/workflow.ts
 function registerWorkflowCommand(program2) {
-  const workflow = program2.command("workflow").alias("automation").description("Workflows (/v1/workflow): create, list, resume, pause, run, delete");
-  workflow.command("create").description("Create a workflow with exactly one trigger").requiredOption("--name <name>", "Workflow name (required)").option("--rrule <RRULE>", "Trigger: RFC-5545 recurrence rule").option("--run-at <ISO>", "Trigger: run once at this time (ISO-8601)").option("--event-kind <kind>", "Trigger: a notification type to react to").option("--after <con-id>", "Trigger: when this task (conversation) is done").option("--timezone <tz>", "IANA timezone for --rrule", "UTC").option("--action <type>", "Action: annotate_documents or email_documents").option("--documents <ids>", "Comma-separated document IDs").option("--labels <ids>", "Select documents matching these label IDs at execution time").option("--latest", "Select documents uploaded since the previous successful run").option("--tags <ids>", "Annotation field IDs for AI review").option("--overwrite", "Regenerate existing annotation answers").option(
+  const workflow = program2.command("workflow").alias("automation").description(
+    "Workflows (/v1/workflow): create (optionally with steps), list, update, resume, pause, run, delete"
+  );
+  workflow.command("create").description(
+    "Create a workflow: at most one trigger (none = started by hand) and what it runs: --steps, --prompt, --skill or --action"
+  ).requiredOption("--name <name>", "Workflow name (required)").option(
+    "--steps <file>",
+    "Named steps (form/upload/agent/review) as a TaskPlanStep list in .json, .yaml or .yml"
+  ).option("--rrule <RRULE>", "Trigger: RFC-5545 recurrence rule").option("--run-at <ISO>", "Trigger: run once at this time (ISO-8601)").option("--event-kind <kind>", "Trigger: a notification type to react to").option("--after <con-id>", "Trigger: when this task (conversation) is done").option("--timezone <tz>", "IANA timezone for --rrule", "UTC").option("--action <type>", "Action: annotate_documents or email_documents").option("--documents <ids>", "Comma-separated document IDs").option("--labels <ids>", "Select documents matching these label IDs at execution time").option("--latest", "Select documents uploaded since the previous successful run").option("--tags <ids>", "Annotation field IDs for AI review").option("--overwrite", "Regenerate existing annotation answers").option(
     "--auth-mode <mode>",
     "scheduled_require_auth or scheduled_permanent",
     "scheduled_require_auth"
   ).option("--event-filter <json>", "Notification attribute filters as a JSON object").option("--prompt <text>", "Instruction the agent runs").option("--skill <ref>", "Skill reference to run").option("--agent <agt-id>", "Agent to run it as (external id)").option("--workspace <wrk-id>", "Workspace to scope the workflow to (default: the current one)").option("--shared", "Share it with the workspace").option("--json", "Output as JSON").action(
     (opts) => runAction(async () => {
+      if (opts.steps && (opts.prompt || opts.skill || opts.action))
+        throw new Error("Use --steps, or --prompt / --skill / --action, not both");
+      const steps = opts.steps ? readStepsFile(opts.steps) : void 0;
       const { arbi, workspaceId } = await resolveWorkspace();
       const body = {
         name: opts.name,
@@ -9842,12 +9891,16 @@ function registerWorkflowCommand(program2) {
       if (opts.after) body.after_conversation_ext_id = opts.after;
       if (opts.skill) body.skill_ref = opts.skill;
       if (opts.agent) body.agent_ext_id = opts.agent;
+      if (steps) body.plan = sdk.workflowSteps.stepsPlan(steps);
       const data = await sdk.workflows.createWorkflow(arbi, body);
       if (opts.json) {
         printJson(data);
         return;
       }
-      success(`Created workflow: ${data.name} (${ref(data.external_id)})`);
+      success(
+        `Created workflow: ${data.name} (${ref(data.external_id)})${steps ? ` with ${steps.length} steps` : ""}`
+      );
+      if (steps) dim(`Run it: arbi workflow run ${data.external_id}`);
     })()
   );
   workflow.command("list").description("List your workflows").option("--json", "Output as JSON").action(
@@ -9880,7 +9933,9 @@ function registerWorkflowCommand(program2) {
       })()
     );
   }
-  workflow.command("run <id>").description("Start the saved action now (document actions do not create a thread)").option("--json", "Output as JSON").action(
+  workflow.command("run <id>").description(
+    "Run a workflow now: a thread (a stepped one waits for its steps), or a document action without one"
+  ).option("--json", "Output as JSON").action(
     (id, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.workflows.runWorkflow(arbi, id);
@@ -9890,11 +9945,17 @@ function registerWorkflowCommand(program2) {
       }
       if (data.error) throw new Error(data.error);
       success(
-        `${data.started ? "Started" : "Submitted"} automation ${ref(id)}${data.execution_id ? ` \u2014 execution ${data.execution_id}` : ""}${data.conversation_ext_id ? ` \u2014 thread ${ref(data.conversation_ext_id)}` : ""}`
+        `${data.started ? "Started" : "Submitted"} workflow ${ref(id)}${data.execution_id ? ` \u2014 execution ${data.execution_id}` : ""}${data.conversation_ext_id ? ` \u2014 thread ${ref(data.conversation_ext_id)}` : ""}`
       );
+      if (!data.conversation_ext_id) return;
+      const saved = await sdk.workflows.getWorkflow(arbi, id);
+      if (saved.plan?.steps?.length) {
+        dim(`Its steps: arbi run steps ${data.conversation_ext_id}`);
+        dim(`Follow it: arbi run steps ${data.conversation_ext_id} --watch --answers`);
+      }
     })()
   );
-  workflow.command("get <id>").description("Read the complete saved automation configuration").action(
+  workflow.command("get <id>").description("Read the complete saved workflow configuration").action(
     (id) => runAction(async () => {
       const { arbi } = await resolveAuth();
       printJson(await sdk.workflows.getWorkflow(arbi, id));
@@ -9904,7 +9965,7 @@ function registerWorkflowCommand(program2) {
     (id, opts) => runAction(async () => {
       const { arbi } = await resolveAuth();
       const data = await sdk.workflows.listWorkflowRuns(arbi, id);
-      if (!emitListOrTable(data, opts, "This automation has not run yet.")) return;
+      if (!emitListOrTable(data, opts, "This workflow has not run yet.")) return;
       printTable(
         [
           { header: "RUN", width: 10, value: (r) => String(r.id) },
@@ -9922,13 +9983,22 @@ function registerWorkflowCommand(program2) {
       );
     })()
   );
-  workflow.command("update <id>").description("Update any saved automation settings from a JSON file").requiredOption("--file <path>", "JSON UpdateWorkflowRequest file").option("--json", "Output as JSON").action(
+  workflow.command("update <id>").description("Update a saved workflow: its steps (--steps), and any setting from a JSON file").option("--steps <file>", "Replace its steps (TaskPlanStep list in .json, .yaml or .yml)").option("--file <path>", "JSON UpdateWorkflowRequest file").option("--json", "Output as JSON").action(
     (id, opts) => runAction(async () => {
+      if (!opts.file && !opts.steps) throw new Error("Pass --steps <file> and/or --file <path>");
+      const steps = opts.steps ? readStepsFile(opts.steps) : void 0;
+      const body = opts.file ? JSON.parse(fs7.readFileSync(opts.file, "utf8")) : {};
+      if (steps)
+        Object.assign(body, {
+          plan: sdk.workflowSteps.stepsPlan(steps),
+          prompt: "",
+          skill_ref: null,
+          skill_inputs: null
+        });
       const { arbi } = await resolveAuth();
-      const body = JSON.parse(fs7.readFileSync(opts.file, "utf8"));
       const data = await sdk.workflows.updateWorkflow(arbi, id, body);
       if (opts.json) printJson(data);
-      else success(`Updated automation ${ref(id)}`);
+      else success(`Updated workflow ${ref(id)}${steps ? ` \u2014 ${steps.length} steps` : ""}`);
     })()
   );
   workflow.command("delete <id>").description("Delete a workflow (tasks it already created stay)").action(
@@ -9939,6 +10009,226 @@ function registerWorkflowCommand(program2) {
     })()
   );
 }
+function runJson(progress, answers = {}) {
+  const c = progress.conversation;
+  return {
+    conversation_ext_id: c.external_id,
+    title: c.title,
+    waiting_on: progress.waitingOn,
+    in_progress: c.in_progress,
+    pending_auth_request_id: c.pending_auth_request_id ?? null,
+    last_error: c.last_error ?? null,
+    steps: progress.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      kind: s.kind,
+      state: s.phase,
+      after: s.after,
+      answer_id: s.responseId,
+      error: s.error,
+      ...s.responseId && answers[s.responseId] !== void 0 ? { answer: answers[s.responseId] } : {}
+    }))
+  };
+}
+function nextHint(progress, planSteps = []) {
+  const id = progress.conversation.external_id;
+  if (progress.conversation.pending_auth_request_id)
+    return "The run is waiting for access to the workspace: approve the request in ARBI.";
+  switch (progress.waitingOn) {
+    case "finished":
+      return "Every step is done or skipped.";
+    case "agent": {
+      const next = progress.steps.find((s) => s.phase === "running") ?? progress.steps.find((s) => s.kind === "agent" && s.phase === "ready");
+      return `Step ${next ? `"${next.id}" ` : ""}is on its way: arbi run steps ${id} --watch`;
+    }
+    case "person": {
+      const step = progress.steps.find((s) => s.kind !== "agent" && s.phase === "ready");
+      const planned = planSteps.find((p) => p.id === step.id);
+      const have = progress.conversation.skill_inputs ?? {};
+      const fields = (planned ? sdk.workflowSteps.stepFields(planned) : []).filter(
+        (f) => have[f.name] === void 0 || have[f.name] === null || have[f.name] === ""
+      );
+      const inputs = fields.map((f) => ` --input ${f.name}=\u2026`).join("");
+      return `Waiting on ${step.kind} step "${step.id}": arbi run step ${id} ${step.id} complete${inputs}`;
+    }
+    default: {
+      const failed = progress.steps.find((s) => s.phase === "failed");
+      return failed ? `Step "${failed.id}" failed${failed.error ? ` (${failed.error})` : ""}: arbi run step ${id} ${failed.id} skip` : "Nothing can move: a step it waits for has not finished.";
+    }
+  }
+}
+function printRun(progress, answers) {
+  const c = progress.conversation;
+  bold(`Run ${c.external_id}${c.title ? ` \u2014 ${c.title}` : ""}`);
+  printTable(
+    [
+      { header: "STEP", width: 16, value: (r) => r.id },
+      { header: "KIND", width: 8, value: (r) => r.kind },
+      { header: "STATE", width: 9, value: (r) => r.phase },
+      { header: "ANSWER", width: 16, value: (r) => r.responseId ?? "" },
+      { header: "TITLE", width: 40, value: (r) => r.title }
+    ],
+    progress.steps
+  );
+  for (const s of progress.steps) {
+    if (s.phase === "failed" && s.error) warn(`${s.id}: ${s.error}`);
+    if (!s.responseId || answers[s.responseId] === void 0) continue;
+    console.log("");
+    bold(`\u2500\u2500 ${s.id}: ${s.title} (${s.responseId})`);
+    console.log(answers[s.responseId]);
+  }
+  console.log("");
+  dim(nextHint(progress, c.plan?.steps ?? []));
+}
+async function answersFor(arbi, progress) {
+  const ids = progress.steps.filter((s) => s.kind === "agent" && s.phase === "done" && s.responseId).map((s) => s.responseId);
+  return sdk.work.getStepAnswers(arbi, progress.conversation.external_id, ids);
+}
+var sleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
+var summary = (p) => p.steps.map((s) => `${s.id}:${s.phase}`).join(" ");
+async function watchRun(arbi, conversationId, { intervalMs, timeoutMs, quiet }) {
+  const deadline = Date.now() + timeoutMs;
+  let progress = await sdk.work.getRunProgress(arbi, conversationId);
+  let last = "";
+  const report = () => {
+    const now = summary(progress);
+    if (!quiet && now !== last) process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()}  ${now}
+`);
+    last = now;
+  };
+  report();
+  while (progress.waitingOn === "agent" && !progress.conversation.pending_auth_request_id) {
+    if (Date.now() >= deadline) return { progress, timedOut: true };
+    await sleep(intervalMs);
+    progress = await sdk.work.getRunProgress(arbi, conversationId);
+    report();
+  }
+  return { progress, timedOut: false };
+}
+function seconds(value, flag) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(`${flag} must be a positive number of seconds`);
+  return n * 1e3;
+}
+function gatherInputs(pairs, file, fields) {
+  return {
+    ...file ? readInputsFile(file) : {},
+    ...sdk.workflowSteps.parseInputPairs(pairs, fields)
+  };
+}
+function registerRunCommand(program2) {
+  const run = program2.command("run").description(
+    "Stepped workflow runs: start one from a steps file, see its steps, complete or skip a step"
+  );
+  run.command("start").description("Start a one-off stepped run as a work thread, without saving a workflow").requiredOption("--steps <file>", "Plan steps (TaskPlanStep list) as .json, .yaml or .yml").requiredOption("--title <title>", "The run thread's title").option("--input <name=value>", "A run input, e.g. a form field (repeatable)", collect, []).option("--inputs-file <file>", "Run inputs as a JSON or YAML object").option("--agent <agt-id>", "Agent to run the agent steps as (external id)").option("--shared", "Share the thread with the workspace").option("--json", "Output as JSON").action(
+    (opts) => runAction(async () => {
+      const steps = readStepsFile(opts.steps);
+      const inputs = gatherInputs(
+        opts.input,
+        opts.inputsFile,
+        steps.flatMap((s) => sdk.workflowSteps.stepFields(s))
+      );
+      const { arbi } = await resolveWorkspace();
+      const created = await sdk.work.createWork(arbi, {
+        title: opts.title,
+        plan: sdk.workflowSteps.stepsPlan(steps),
+        skill_inputs: Object.keys(inputs).length ? inputs : null,
+        agent_ext_id: opts.agent ?? null,
+        shared: opts.shared ?? null,
+        auth_mode: "run_now_temp"
+      });
+      const progress = await sdk.work.getRunProgress(arbi, created.external_id);
+      if (opts.json) {
+        printJson(runJson(progress));
+        return;
+      }
+      success(`Started run ${ref(created.external_id)} \u2014 ${opts.title}`);
+      dim(`Follow it: arbi run steps ${created.external_id} --watch`);
+      dim(nextHint(progress, steps));
+    })()
+  );
+  run.command("steps <con-id>").description(
+    "A run's steps and their state (pending, ready, running, done, skipped, failed), with each done agent step's answer id"
+  ).option("--answers", "Print the done agent steps' answers from the thread").option("--watch", "Poll until the run stops waiting on an agent step").option("--interval <seconds>", "Poll interval for --watch", "3").option("--timeout <seconds>", "Stop watching after this long", "600").option("--json", "Output as JSON").action(
+    (conversationId, opts) => runAction(async () => {
+      const intervalMs = seconds(opts.interval, "--interval");
+      const timeoutMs = seconds(opts.timeout, "--timeout");
+      const { arbi } = await resolveWorkspace();
+      let progress;
+      let timedOut = false;
+      if (opts.watch) {
+        ;
+        ({ progress, timedOut } = await watchRun(arbi, conversationId, {
+          intervalMs,
+          timeoutMs,
+          quiet: !!opts.json
+        }));
+      } else progress = await sdk.work.getRunProgress(arbi, conversationId);
+      const answers = opts.answers ? await answersFor(arbi, progress) : {};
+      if (opts.json) printJson({ ...runJson(progress, answers), timed_out: timedOut });
+      else {
+        printRun(progress, answers);
+        if (timedOut) warn(`Stopped watching after ${opts.timeout}s; the run is still going.`);
+      }
+    })()
+  );
+  run.command("step <con-id> <step-id> <action>").description(
+    "Act on a step: complete a form, upload or review step (a form takes its inputs), or skip any step"
+  ).option("--input <name=value>", "A form input (repeatable)", collect, []).option("--inputs-file <file>", "Form inputs as a JSON or YAML object").option("--json", "Output as JSON").action(
+    (conversationId, stepId, action, opts) => runAction(async () => {
+      if (action !== "complete" && action !== "skip")
+        throw new Error(`Unknown action "${action}": use complete or skip`);
+      const { arbi } = await resolveWorkspace();
+      const before = await sdk.work.getRunProgress(arbi, conversationId);
+      const plan = before.conversation.plan?.steps ?? [];
+      const step = plan.find((s) => s.id === stepId);
+      if (!step)
+        throw new Error(
+          `No step "${stepId}" in ${conversationId}. Its steps: ${plan.map((s) => s.id).join(", ")}`
+        );
+      const hasInputs = opts.input.length > 0 || !!opts.inputsFile;
+      if (hasInputs && (action === "skip" || step.kind !== "form"))
+        throw new Error("Only completing a form step takes --input / --inputs-file");
+      let inputs;
+      if (action === "complete") {
+        if (step.kind === "agent")
+          throw new Error(
+            `"${stepId}" is an agent step: it runs itself. Skip it with: arbi run step ${conversationId} ${stepId} skip`
+          );
+        const phase = before.steps.find((s) => s.id === stepId)?.phase;
+        if (phase === "pending") {
+          const waits = before.steps.find((s) => s.id === stepId)?.after ?? [];
+          throw new Error(`"${stepId}" waits for ${waits.join(", ")} to finish first`);
+        }
+        if (step.kind === "form") {
+          inputs = gatherInputs(opts.input, opts.inputsFile, sdk.workflowSteps.stepFields(step));
+          const missing = sdk.workflowSteps.missingRequiredFields(step, {
+            ...before.conversation.skill_inputs ?? {},
+            ...inputs
+          });
+          if (missing.length)
+            throw new Error(
+              `Missing required input${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}. Pass ${missing.map((m) => `--input ${m}=\u2026`).join(" ")}`
+            );
+        }
+      }
+      await sdk.work.actOnStep(arbi, conversationId, {
+        step: stepId,
+        action,
+        ...inputs && Object.keys(inputs).length ? { inputs } : {}
+      });
+      const progress = await sdk.work.getRunProgress(arbi, conversationId);
+      if (opts.json) {
+        printJson(runJson(progress));
+        return;
+      }
+      success(
+        `${action === "complete" ? "Completed" : "Skipped"} step "${stepId}" of ${ref(conversationId)}`
+      );
+      dim(nextHint(progress, plan));
+    })()
+  );
+}
 var MARKER_START = "# arbi-cli completion start";
 var MARKER_END = "# arbi-cli completion end";
 var BASH_COMPLETION = `
@@ -10172,12 +10462,12 @@ function printTree(dir, prefix, maxDepth, depth) {
     }
   }
 }
-function humanizeTtl(seconds) {
-  if (!Number.isFinite(seconds) || seconds < 0) return "";
-  if (seconds < 60) return `${seconds}s`;
-  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
-  if (seconds < 86400) return `${Math.round(seconds / 3600)}h`;
-  return `${Math.round(seconds / 86400)}d`;
+function humanizeTtl(seconds2) {
+  if (!Number.isFinite(seconds2) || seconds2 < 0) return "";
+  if (seconds2 < 60) return `${seconds2}s`;
+  if (seconds2 < 3600) return `${Math.round(seconds2 / 60)}m`;
+  if (seconds2 < 86400) return `${Math.round(seconds2 / 3600)}h`;
+  return `${Math.round(seconds2 / 86400)}d`;
 }
 function registerSessionCommand(program2) {
   const session = program2.command("session").description("List and manage sessions");
@@ -10239,7 +10529,7 @@ function parseAddress(value) {
   const name = match?.[1].replace(/^"|"$/g, "");
   return name ? { email, name } : { email };
 }
-function collect(value, previous = []) {
+function collect2(value, previous = []) {
   return [...previous, ...value.split(",").filter((v) => v.trim())];
 }
 var readTextFile = (path8) => fs7__default.default.readFileSync(path8 === "-" ? 0 : path8, "utf8");
@@ -10265,7 +10555,7 @@ function buildCompose(options) {
   };
 }
 function addComposeOptions(command) {
-  return command.option("--to <addresses>", "Recipient(s), comma-separated or repeated", collect).option("--cc <addresses>", "Cc recipient(s)", collect).option("--bcc <addresses>", "Bcc recipient(s)", collect).option("-s, --subject <subject>", "Subject").option("--text <text>", "Plain-text body").option("--text-file <path>", "Read the plain-text body from a file (- for stdin)").option("--html <html>", "HTML body (the plain text stays as the fallback)").option("--html-file <path>", "Read the HTML body from a file (- for stdin)").option("-a, --attach <path>", "Attach a file (repeatable)", (v, prev = []) => [
+  return command.option("--to <addresses>", "Recipient(s), comma-separated or repeated", collect2).option("--cc <addresses>", "Cc recipient(s)", collect2).option("--bcc <addresses>", "Bcc recipient(s)", collect2).option("-s, --subject <subject>", "Subject").option("--text <text>", "Plain-text body").option("--text-file <path>", "Read the plain-text body from a file (- for stdin)").option("--html <html>", "HTML body (the plain text stays as the fallback)").option("--html-file <path>", "Read the HTML body from a file (- for stdin)").option("-a, --attach <path>", "Attach a file (repeatable)", (v, prev = []) => [
     ...prev,
     v
   ]).option("--json", "Output as JSON (recommended for scripting / agents)");
@@ -10997,7 +11287,7 @@ console.info = (...args) => {
   _origInfo(...args);
 };
 var program = new commander.Command();
-program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.4.74").showHelpAfterError(true).showSuggestionAfterError(true);
+program.name("arbi").description("ARBI CLI \u2014 interact with ARBI from the terminal").version("0.4.76").showHelpAfterError(true).showSuggestionAfterError(true);
 registerConfigCommand(program);
 registerLoginCommand(program);
 registerRegisterCommand(program);
@@ -11027,6 +11317,7 @@ registerAgentCreateCommand(program);
 registerAgentCommand(program);
 registerTaskCommand(program);
 registerWorkflowCommand(program);
+registerRunCommand(program);
 registerCompletionCommand(program);
 registerListenCommand(program);
 registerSessionCommand(program);
@@ -11053,7 +11344,7 @@ applyHelpGroups(program, {
   "Search & ask:": ["ask", "find", "cite", "watch"],
   "Tagging:": ["tags", "doctags"],
   "Conversations & messaging:": ["convo", "dm", "listen", "notifications", "contacts"],
-  "Agents & tasks:": ["agent", "agent-create", "task", "workflow", "agentconfig", "session"],
+  "Agents & tasks:": ["agent", "agent-create", "task", "workflow", "run", "agentconfig", "session"],
   "Account:": ["auth", "usage", "files"],
   "System:": ["health", "models", "settings", "tui", "local", "update"]
 });