@asteroidai/cli 1.9.11 → 1.9.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.9.11",
+  "version": "1.9.12",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",

package/src/generated/commands.ts

@@ -128,6 +128,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "context",
@@ -1092,6 +1093,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "execution resume",
@@ -1113,6 +1115,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "insight get",
@@ -2004,6 +2007,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "schedule delete",
@@ -2031,6 +2035,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: true,
+    capability: "run_execution",
   },
   {
     command: "schedule get",
@@ -2222,6 +2227,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution cancel",
@@ -2243,6 +2249,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution create",
@@ -2315,6 +2322,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "scheduled-execution list",
@@ -2421,6 +2429,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "schema validate",
@@ -3621,6 +3630,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
+    capability: "run_execution",
   },
   {
     command: "workflow execute-sync",
@@ -3731,119 +3741,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
-  },
-  {
-    command: "workflow file list",
-    tool: "workflow_files_list",
-    title: "List workflow files",
-    description:
-      "List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.",
-    method: "GET",
-    path: "/agents/v2/workflows/{workflowId}/head/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [
-      {
-        name: "contents",
-        flag: "contents",
-        type: "string",
-        required: false,
-        description:
-          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
-        enum: ["none", "structural", "all"],
-      },
-      {
-        name: "paths",
-        flag: "paths",
-        type: "string[]",
-        required: false,
-        description:
-          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
-      },
-      {
-        name: "variants",
-        flag: "variants",
-        type: "string",
-        required: false,
-        description:
-          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
-      },
-      {
-        name: "maxFileBytes",
-        flag: "max-file-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
-      },
-      {
-        name: "maxTotalBytes",
-        flag: "max-total-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
-      },
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false,
-  },
-  {
-    command: "workflow file patch",
-    tool: "workflow_files_patch",
-    title: "Write workflow files",
-    description:
-      "Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries `contentBase64`: base64-encode the file content, plain text is rejected with 400.",
-    method: "PATCH",
-    path: "/agents/v2/workflows/{workflowId}/head/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [],
-    binary: false,
-    readOnly: false,
-    destructive: true,
-    body: {
-      required: true,
-      contentType: "application/json",
-      fields: [
-        {
-          name: "baseRev",
-          flag: "base-rev",
-          type: "integer",
-          required: true,
-          description:
-            "The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision.",
-        },
-        {
-          name: "writes",
-          flag: "writes",
-          type: "json",
-          required: true,
-          description: "Files to upsert.",
-        },
-        {
-          name: "deletes",
-          flag: "deletes",
-          type: "string[]",
-          required: true,
-        },
-      ],
-      files: [],
-      credentialOrganization: false,
-    },
+    capability: "run_execution",
   },
   {
     command: "workflow get",
@@ -3894,6 +3792,7 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "publish",
   },
   {
     command: "workflow head revert",
@@ -4024,6 +3923,121 @@ export const COMMANDS: CliCommand[] = [
     readOnly: true,
     destructive: false,
   },
+  {
+    command: "workflow pull",
+    tool: "workflow_files_list",
+    title: "List workflow files",
+    description:
+      "List the workflow's editable head as a directory of files: the graph rendered as structural files (settings.yaml, per-node instructions.md, scripts) alongside the workflow's own files. Those files are referenced by fileId unless contents=all is set. Pass paths to read named files only, or contents=none for a manifest with no bodies. The returned rev is what you pass as baseRev to write.",
+    method: "GET",
+    path: "/agents/v2/workflows/{workflowId}/head/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      {
+        name: "contents",
+        flag: "contents",
+        type: "string",
+        required: false,
+        description:
+          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
+        enum: ["none", "structural", "all"],
+      },
+      {
+        name: "paths",
+        flag: "paths",
+        type: "string[]",
+        required: false,
+        description:
+          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
+      },
+      {
+        name: "variants",
+        flag: "variants",
+        type: "string",
+        required: false,
+        description:
+          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
+      },
+      {
+        name: "maxFileBytes",
+        flag: "max-file-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
+      },
+      {
+        name: "maxTotalBytes",
+        flag: "max-total-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
+      },
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false,
+    files: "pull",
+  },
+  {
+    command: "workflow push",
+    tool: "workflow_files_patch",
+    title: "Write workflow files",
+    description:
+      "Write and delete files on the workflow's editable head in one patch. Structural files re-derive the graph; the workflow's own files go to its file store, you just write paths. Pass the rev from `workflow_files_list` as baseRev; a stale value is rejected with 409, so re-read and retry. Editing a published or already-executed version forks a new one instead of rewriting it. Each write carries `contentBase64`: base64-encode the file content, plain text is rejected with 400.",
+    method: "PATCH",
+    path: "/agents/v2/workflows/{workflowId}/head/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [],
+    binary: false,
+    readOnly: false,
+    destructive: true,
+    body: {
+      required: true,
+      contentType: "application/json",
+      fields: [
+        {
+          name: "baseRev",
+          flag: "base-rev",
+          type: "integer",
+          required: true,
+          description:
+            "The revision this edit is based on. Agent-file-only patches overlay the current head even when this is stale. A structural-file patch is rejected with 409 when it does not match the stored head revision.",
+        },
+        {
+          name: "writes",
+          flag: "writes",
+          type: "json",
+          required: true,
+          description: "Files to upsert.",
+        },
+        {
+          name: "deletes",
+          flag: "deletes",
+          type: "string[]",
+          required: true,
+        },
+      ],
+      files: [],
+      credentialOrganization: false,
+    },
+    files: "push",
+  },
   {
     command: "workflow rename",
     tool: "workflow_rename",
@@ -4449,75 +4463,7 @@ export const COMMANDS: CliCommand[] = [
       files: [],
       credentialOrganization: false,
     },
-  },
-  {
-    command: "workflow version file list",
-    tool: "workflow_version_files_list",
-    title: "List workflow version files",
-    description:
-      "List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.",
-    method: "GET",
-    path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/files",
-    args: [
-      {
-        name: "workflowId",
-        flag: "workflow-id",
-        type: "string",
-        required: true,
-      },
-      {
-        name: "versionId",
-        flag: "version-id",
-        type: "string",
-        required: true,
-      },
-    ],
-    query: [
-      {
-        name: "contents",
-        flag: "contents",
-        type: "string",
-        required: false,
-        description:
-          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
-        enum: ["none", "structural", "all"],
-      },
-      {
-        name: "paths",
-        flag: "paths",
-        type: "string[]",
-        required: false,
-        description:
-          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
-      },
-      {
-        name: "variants",
-        flag: "variants",
-        type: "string",
-        required: false,
-        description:
-          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
-      },
-      {
-        name: "maxFileBytes",
-        flag: "max-file-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
-      },
-      {
-        name: "maxTotalBytes",
-        flag: "max-total-bytes",
-        type: "integer",
-        required: false,
-        description:
-          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
-      },
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false,
+    capability: "run_execution",
   },
   {
     command: "workflow version file url",
@@ -4680,6 +4626,77 @@ export const COMMANDS: CliCommand[] = [
     binary: false,
     readOnly: false,
     destructive: false,
+    capability: "publish",
+  },
+  {
+    command: "workflow version pull",
+    tool: "workflow_version_files_list",
+    title: "List workflow version files",
+    description:
+      "List a version's files, like `workflow_files_list` does for the editable head. Versions are immutable, so this is read-only.",
+    method: "GET",
+    path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/files",
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+      {
+        name: "versionId",
+        flag: "version-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      {
+        name: "contents",
+        flag: "contents",
+        type: "string",
+        required: false,
+        description:
+          "Which contents come inline: none (a pure manifest), structural (the default), or all (structural plus file bytes within the response budget).",
+        enum: ["none", "structural", "all"],
+      },
+      {
+        name: "paths",
+        flag: "paths",
+        type: "string[]",
+        required: false,
+        description:
+          "Return only the files at these exact tree paths. A path that names nothing yields no entry. The inline budget applies to the filtered set, so a narrow read can inline files a whole-tree read would have to skip.",
+      },
+      {
+        name: "variants",
+        flag: "variants",
+        type: "string",
+        required: false,
+        description:
+          'Narrow which variants/<key>/ files the tree carries: "none" strips every variant, a comma-separated list keeps only those variant keys. Files outside variants/ are always kept, and the response\'s variantKeys still names every variant. Ignored unless the workflow has variant mode enabled; absent keeps every variant.',
+      },
+      {
+        name: "maxFileBytes",
+        flag: "max-file-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Per-file ceiling, in bytes, for inlined file contents. Clamped to the server maximum. Files above the ceiling stay references.",
+      },
+      {
+        name: "maxTotalBytes",
+        flag: "max-total-bytes",
+        type: "integer",
+        required: false,
+        description:
+          "Ceiling, in bytes, on the total inlined file contents in one response. Clamped to the server maximum. Files are admitted in path order until the ceiling is reached; the rest stay references.",
+      },
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false,
+    files: "pull",
   },
   {
     command: "workflow version validate",

package/src/program.ts

@@ -91,6 +91,16 @@ function leafOptions(leaf: Command, command: CliCommand) {
   for (const file of command.body?.files ?? []) {
     leaf.option(`--${file} <path>`, "File to upload. Repeatable.", collect);
   }
+  if (command.files === "pull")
+    leaf.option(
+      "--out <dir>",
+      "Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead.",
+    );
+  if (command.files === "push")
+    leaf.option(
+      "--from <dir>",
+      "The pulled head folder to push. Defaults to the current folder.",
+    );
 }
 
 function toParsed(

package/src/reference.ts

@@ -75,7 +75,11 @@ export const GLOBAL_FLAGS: [string, string][] = [
 ];
 
 export function usage(command: CliCommand): string {
-  const args = command.args.map((arg) => `<${arg.flag}>`).join(" ");
+  const args = command.args
+    .map((arg) =>
+      command.files === "push" ? `[${arg.flag}]` : `<${arg.flag}>`,
+    )
+    .join(" ");
   return `asteroid ${command.command}${args ? ` ${args}` : ""} [flags]`;
 }
 
@@ -109,6 +113,14 @@ export function flagLines(command: CliCommand): string[] {
   for (const file of command.body?.files ?? []) {
     lines.push(`--${file} <path>  File to upload (repeatable)`);
   }
+  if (command.files === "pull")
+    lines.push(
+      "--out <dir>  Write here instead of ./<workflow-name>/head (a version: ./<workflow-name>/.versions/...). --json prints the file listing instead",
+    );
+  if (command.files === "push")
+    lines.push(
+      "--from <dir>  The pulled head folder to push. Defaults to the current folder",
+    );
   return lines;
 }
 

package/src/run.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeEach, describe, expect, it } from "vitest";
@@ -323,8 +323,8 @@ describe("terminal safety", () => {
   });
 });
 
-describe("workflow pull", () => {
-  it("pulls a pinned version into the folder it is given", async () => {
+describe("files --out", () => {
+  it("writes a pinned version into the folder it is given", async () => {
     const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
       json({
         rev: 1,
@@ -344,7 +344,7 @@ describe("workflow pull", () => {
     const dir = join(h.configDir, "pulled");
 
     const code = await run(
-      ["workflow", "pull", "w1", "--version-id", "v-2", "--dir", dir],
+      ["workflow", "version", "pull", "w1", "v-2", "--out", dir],
       h.deps,
     );
 
@@ -356,6 +356,70 @@ describe("workflow pull", () => {
   });
 });
 
+describe("workflow pull and push", () => {
+  const tree = {
+    rev: 1,
+    version: 2,
+    versionId: "v-2",
+    workflowName: "Fill form",
+    files: [
+      { path: "settings.yaml", kind: "structural", size: 4, content: "a: 1" },
+    ],
+  };
+
+  it("pulls into ./<workflow-name>/head and pushes from there with no arguments", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
+      call.init.method === "PATCH" ? json({}) : json({ ...tree, rev: 2 }),
+    );
+
+    expect(await run(["workflow", "pull", "w1"], h.deps)).toBe(0);
+    const head = join(h.configDir, "Fill_form", "head");
+    expect(readFileSync(join(head, "settings.yaml"), "utf8")).toBe("a: 1");
+
+    writeFileSync(join(head, "settings.yaml"), "a: 2");
+    const code = await run(["workflow", "push"], { ...h.deps, cwd: head });
+
+    expect(code).toBe(0);
+    const patch = h.calls.find((call) => call.init.method === "PATCH")!;
+    expect(patch.url).toBe(
+      "https://odyssey.asteroid.ai/agents/v2/workflows/w1/head/files",
+    );
+    expect(JSON.parse(String(patch.init.body))).toMatchObject({ baseRev: 2 });
+  });
+
+  it("pushes the folder --from names, taking the workflow from its manifest", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, (call) =>
+      call.init.method === "PATCH" ? json({}) : json({ ...tree, rev: 2 }),
+    );
+    await run(["workflow", "pull", "w9"], h.deps);
+    const head = join(h.configDir, "Fill_form", "head");
+    writeFileSync(join(head, "settings.yaml"), "a: 3");
+
+    const code = await run(["workflow", "push", "--from", head], h.deps);
+
+    expect(code).toBe(0);
+    const patch = h.calls.find((call) => call.init.method === "PATCH")!;
+    expect(patch.url).toBe(
+      "https://odyssey.asteroid.ai/agents/v2/workflows/w9/head/files",
+    );
+  });
+});
+
+describe("workflow pull with a filter", () => {
+  it("refuses a partial tree, which would delete the files it leaves out", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () => json({}));
+
+    const code = await run(
+      ["workflow", "pull", "w1", "--paths", "a.md"],
+      h.deps,
+    );
+
+    expect(code).toBe(2);
+    expect(h.calls).toEqual([]);
+    expect(h.err.join("")).toContain("cannot take --paths");
+  });
+});
+
 describe("reference", () => {
   it("matches the generated agent-docs page", () => {
     const page = readFileSync(

package/src/run.ts

@@ -17,7 +17,7 @@ import { clean, render } from "./output";
 import { parseInvocation } from "./program";
 import { BUILTINS } from "./reference";
 import { buildRequest } from "./request";
-import { runSync } from "./sync/run";
+import { runsLocally, runSync } from "./sync/run";
 import type { Remote } from "./sync/types";
 import type { CliCommand } from "./types";
 import type { Ui } from "./ui";
@@ -189,6 +189,10 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
       builtins: BUILTINS,
       version: VERSION,
       description: DESCRIPTION,
+      defaultArg: (command, arg) =>
+        command.files === "push" && arg.name === "workflowId" ? "" : undefined,
+      defaultArgNote:
+        "<workflow-id> defaults to the workflow the pushed folder was pulled from.",
     });
     if (invocation.kind === "exit") {
       if (invocation.stdout) deps.stdout(invocation.stdout);
@@ -198,7 +202,7 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
     if (invocation.kind === "builtin") {
       return await runBuiltin(invocation.name, invocation.parsed, deps);
     }
-    if (invocation.command.local) {
+    if (runsLocally(invocation.command, invocation.parsed)) {
       const auth = await authFor(invocation.parsed, deps);
       announce(invocation.command, auth, deps);
       return await runSync(invocation.command, invocation.parsed, {