@asteroidai/cli 1.9.4 → 1.9.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.9.4",
+  "version": "1.9.11",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,8 @@
     "tsx": "^4.23.12",
     "typescript": "5.9.3",
     "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@asteroid/workflow-files": "0.1.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts && pnpm exec prettier --write src/generated/commands.ts",

package/src/commands.ts

@@ -0,0 +1,13 @@
+import { COMMANDS } from "./generated/commands";
+import { SYNC_COMMANDS } from "./sync/commands";
+import type { CliCommand } from "./types";
+
+export function withSyncCommands(
+  commands: readonly CliCommand[],
+): CliCommand[] {
+  return [...commands, ...SYNC_COMMANDS].sort((a, b) =>
+    a.command.localeCompare(b.command),
+  );
+}
+
+export const ALL_COMMANDS = withSyncCommands(COMMANDS);

package/src/core.ts

@@ -8,3 +8,34 @@ export {
 } from "./program";
 export { type BuiltRequest, buildRequest, type InputReader } from "./request";
 export type { CliCommand, Option } from "./types";
+export { ALL_COMMANDS, withSyncCommands } from "./commands";
+export { type Activity, formatActivitiesMarkdown } from "./sync/activities";
+export {
+  type Execution,
+  type ExecutionPullOptions,
+  type ExecutionPullResult,
+  formatExecutionPull,
+  pullExecution,
+} from "./sync/execution-pull";
+export { matchesGlob } from "./sync/paths";
+export { runSync, type SyncDeps, SYNC_COMMANDS } from "./sync/run";
+export {
+  type FileEntry,
+  type FileTree,
+  type LocalFiles,
+  MANIFEST,
+  type Manifest,
+  type Remote,
+  type Sync,
+} from "./sync/types";
+export {
+  formatWorkflowPull,
+  pullWorkflow,
+  type WorkflowPullOptions,
+  type WorkflowPullResult,
+} from "./sync/workflow-pull";
+export {
+  formatWorkflowPush,
+  pushWorkflow,
+  type WorkflowPushResult,
+} from "./sync/workflow-push";

package/src/main.ts

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 
+import { ALL_COMMANDS } from "./commands";
 import { readEnv } from "./config";
-import { COMMANDS } from "./generated/commands";
 import { runCompletion } from "./program";
 import { BUILTINS } from "./reference";
 import { run } from "./run";
@@ -27,7 +27,7 @@ function openUrl(url: string) {
 
 const argv = process.argv.slice(2);
 if (argv[0] === "complete") {
-  await runCompletion(argv, { commands: COMMANDS, builtins: BUILTINS });
+  await runCompletion(argv, { commands: ALL_COMMANDS, builtins: BUILTINS });
   process.exit(0);
 }
 

package/src/program.test.ts

@@ -133,4 +133,23 @@ describe("parseInvocation", () => {
       "expected [workflow-id] <schedule-id>, got 0 argument(s)",
     );
   });
+
+  it("prints the version only as the first argument", async () => {
+    const options = {
+      commands: COMMANDS,
+      builtins: BUILTINS,
+      version: "1.2.3",
+    };
+
+    const version = await parseInvocation(["--version"], options);
+    const create = await parseInvocation(
+      ["workflow", "create", "--name", "W", "--version", "{}"],
+      options,
+    );
+
+    expect(version).toMatchObject({ kind: "exit", code: 0, stdout: "1.2.3\n" });
+    expect(create.kind).toBe("command");
+    if (create.kind === "command")
+      expect(create.parsed.flags.get("version")).toEqual(["{}"]);
+  });
 });

package/src/program.ts

@@ -85,6 +85,8 @@ function leafOptions(leaf: Command, command: CliCommand) {
       optionText(option),
       collect,
     );
+    if (option.negatable)
+      leaf.option(`--no-${option.flag}`, `Skip ${option.flag}.`);
   }
   for (const file of command.body?.files ?? []) {
     leaf.option(`--${file} <path>`, "File to upload. Repeatable.", collect);
@@ -122,7 +124,11 @@ export function defineCommands(
   onInvocation: (invocation: Invocation) => void = () => undefined,
 ): Command {
   if (options.description) root.description(options.description);
-  if (options.version) root.version(options.version, "-v, --version");
+  if (options.version)
+    root.addHelpText(
+      "after",
+      "\nRun `asteroid --version` to print the CLI version.",
+    );
   for (const [flags, text] of GLOBAL_FLAGS) {
     if (!flags.startsWith("-h")) root.option(flags, text);
   }
@@ -224,6 +230,14 @@ export async function parseInvocation(
   let stderr = "";
   let result: Invocation | undefined;
 
+  if (options.version && (argv[0] === "-v" || argv[0] === "--version")) {
+    return {
+      kind: "exit",
+      code: 0,
+      stdout: `${options.version}\n`,
+      stderr: "",
+    };
+  }
   const { argv: rest, dotted } = splitDotted(argv);
   const root = new Command("asteroid")
     .exitOverride()

package/src/run.test.ts

@@ -4,8 +4,8 @@ import { join } from "node:path";
 import { beforeEach, describe, expect, it } from "vitest";
 
 import { CredentialStore } from "./auth/store";
+import { ALL_COMMANDS } from "./commands";
 import { readEnv, saveConfig } from "./config";
-import { COMMANDS } from "./generated/commands";
 import { renderReference } from "./reference";
 import { type Deps, run } from "./run";
 
@@ -323,12 +323,45 @@ describe("terminal safety", () => {
   });
 });
 
+describe("workflow pull", () => {
+  it("pulls a pinned version into the folder it is given", async () => {
+    const h = harness({ ASTEROID_API_KEY: "sk_test" }, () =>
+      json({
+        rev: 1,
+        version: 2,
+        versionId: "v-2",
+        workflowName: "Fill form",
+        files: [
+          {
+            path: "settings.yaml",
+            kind: "structural",
+            size: 3,
+            content: "a: 1",
+          },
+        ],
+      }),
+    );
+    const dir = join(h.configDir, "pulled");
+
+    const code = await run(
+      ["workflow", "pull", "w1", "--version-id", "v-2", "--dir", dir],
+      h.deps,
+    );
+
+    expect(code).toBe(0);
+    expect(h.calls[0].url).toBe(
+      "https://odyssey.asteroid.ai/agents/v2/workflows/w1/versions/v-2/files?contents=all",
+    );
+    expect(readFileSync(join(dir, "settings.yaml"), "utf8")).toBe("a: 1");
+  });
+});
+
 describe("reference", () => {
   it("matches the generated agent-docs page", () => {
     const page = readFileSync(
       new URL("../../../docs/cli/reference.mdx", import.meta.url),
       "utf8",
     );
-    expect(page).toBe(renderReference(COMMANDS));
+    expect(page).toBe(renderReference(ALL_COMMANDS));
   });
 });

package/src/run.ts

@@ -10,13 +10,15 @@ import {
   UNSET_API_KEY,
 } from "./auth/credentials";
 import { WorkosError } from "./auth/workos";
+import { ALL_COMMANDS } from "./commands";
 import { type Env, loadConfig, orgLabel, requestedOrg } from "./config";
-import { COMMANDS } from "./generated/commands";
 import { ApiError, send, VERSION } from "./http";
 import { clean, render } from "./output";
 import { parseInvocation } from "./program";
 import { BUILTINS } from "./reference";
 import { buildRequest } from "./request";
+import { runSync } from "./sync/run";
+import type { Remote } from "./sync/types";
 import type { CliCommand } from "./types";
 import type { Ui } from "./ui";
 
@@ -82,6 +84,28 @@ async function credentialOrganization(
     ?.organizationId;
 }
 
+async function authFor(parsed: Parsed, deps: Deps): Promise<Auth> {
+  rejectOrgWithApiKey(deps, parsed.org);
+  const config = loadConfig(deps.env);
+  return resolveAuth(
+    deps.env,
+    config,
+    requestedOrg(parsed.org, deps.env, deps.cwd, config),
+    deps.fetch,
+  );
+}
+
+function announce(command: CliCommand, auth: Auth, deps: Deps) {
+  if (command.readOnly) return;
+  const org =
+    auth.kind === "api-key"
+      ? "the API key's organization"
+      : auth.org
+        ? orgLabel(auth.org)
+        : "your default organization";
+  deps.stderr(`Acting in ${org}.\n`);
+}
+
 async function runCommand(
   command: CliCommand,
   parsed: Parsed,
@@ -91,26 +115,11 @@ async function runCommand(
   let request = needsOrganization
     ? undefined
     : await buildRequest(command, parsed);
-  rejectOrgWithApiKey(deps, parsed.org);
-  const config = loadConfig(deps.env);
-  const auth = await resolveAuth(
-    deps.env,
-    config,
-    requestedOrg(parsed.org, deps.env, deps.cwd, config),
-    deps.fetch,
-  );
+  const auth = await authFor(parsed, deps);
   request ??= await buildRequest(command, parsed, {
     organizationId: await credentialOrganization(deps, auth),
   });
-  if (!command.readOnly) {
-    const org =
-      auth.kind === "api-key"
-        ? "the API key's organization"
-        : auth.org
-          ? orgLabel(auth.org)
-          : "your default organization";
-    deps.stderr(`Acting in ${org}.\n`);
-  }
+  announce(command, auth, deps);
 
   const response = await send(
     deps.env.apiUrl,
@@ -153,13 +162,30 @@ async function runCommand(
   return 0;
 }
 
+function nodeRemote(
+  apiUrl: string,
+  auth: Auth,
+  fetchImpl: typeof fetch,
+): Remote {
+  return {
+    json: async (request) =>
+      (await send(apiUrl, auth, request, false, fetchImpl)).json,
+    async download(url) {
+      const response = await fetchImpl(url);
+      if (!response.ok)
+        throw new Error(`download failed: HTTP ${response.status}`);
+      return new Uint8Array(await response.arrayBuffer());
+    },
+  };
+}
+
 const DESCRIPTION =
   "The Asteroid CLI. Sign in with `asteroid login`, or set ASTEROID_API_KEY.\nAt a terminal, tables show up to 6 columns and cut long cells to fit; when output is piped, they show every column in full. Use `--json` for every field.";
 
 export async function run(argv: string[], deps: Deps): Promise<number> {
   try {
     const invocation = await parseInvocation(argv, {
-      commands: COMMANDS,
+      commands: ALL_COMMANDS,
       builtins: BUILTINS,
       version: VERSION,
       description: DESCRIPTION,
@@ -172,6 +198,14 @@ 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) {
+      const auth = await authFor(invocation.parsed, deps);
+      announce(invocation.command, auth, deps);
+      return await runSync(invocation.command, invocation.parsed, {
+        ...deps,
+        remote: nodeRemote(deps.env.apiUrl, auth, deps.fetch),
+      });
+    }
     return await runCommand(invocation.command, invocation.parsed, deps);
   } catch (error) {
     if (error instanceof UsageError) {

package/src/sync/activities.ts

@@ -0,0 +1,80 @@
+interface Payload {
+  activityType: string;
+  display?: { turnId?: string; summaryText?: string };
+  reasoning?: string;
+  message?: string;
+  actionName?: string;
+  info?: Record<string, unknown>;
+  summaryTokens?: number;
+  durationMs?: number;
+}
+
+export interface Activity {
+  payload: Payload;
+}
+
+function indentJson(data: Record<string, unknown>): string {
+  return JSON.stringify(data, null, 2)
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+function action(label: string, payload: Payload): string {
+  const info = payload.info;
+  const detail =
+    info && Object.keys(info).length > 0 ? `\ninfo:\n${indentJson(info)}` : "";
+  return `[${label}: ${payload.actionName}]:${detail}\n`;
+}
+
+function line(payload: Payload): string {
+  switch (payload.activityType) {
+    case "reasoning":
+      return `[reasoning]:\n${payload.reasoning}\n`;
+    case "generic":
+      return `[message]:\n${payload.message}\n`;
+    case "user_message_received":
+      return `[user_message]:\n${payload.message}\n`;
+    case "action_started":
+      return action("action_started", payload);
+    case "action_completed":
+      return action("action_completed", payload);
+    case "action_failed":
+      return `[action_failed: ${payload.actionName}]:\nfailure: ${payload.message}\n`;
+    case "compaction_performed":
+      return `[compaction]: summary_tokens: ${payload.summaryTokens}, duration_ms: ${payload.durationMs}\n`;
+    case "compaction_started":
+      return "[compaction_started]\n";
+    default: {
+      const summary = payload.display?.summaryText;
+      return summary
+        ? `[${payload.activityType}]: ${summary}\n`
+        : `[${payload.activityType}]\n`;
+    }
+  }
+}
+
+export function formatActivitiesMarkdown(
+  activities: Activity[],
+  status: string,
+  createdAt: string,
+): string {
+  const lines = [
+    "# Execution Activities\n",
+    `Status: ${status}`,
+    `Started: ${createdAt}`,
+  ];
+  let currentTurn = "";
+  for (const { payload } of activities) {
+    const turnId = payload.display?.turnId ?? "";
+    if (turnId && turnId !== currentTurn) {
+      currentTurn = turnId;
+      lines.push(`\n---\n\n## ${turnId}\n`);
+    } else if (!currentTurn && !turnId) {
+      currentTurn = "_started";
+      lines.push("\n---\n");
+    }
+    lines.push(line(payload));
+  }
+  return lines.join("\n");
+}

package/src/sync/commands.ts

@@ -0,0 +1,111 @@
+import type { CliCommand, Option } from "../types";
+
+function option(
+  name: string,
+  type: Option["type"],
+  description: string,
+  extra: Partial<Option> = {},
+): Option {
+  return { name, flag: name, type, required: false, description, ...extra };
+}
+
+const DIR = option(
+  "dir",
+  "string",
+  "Write here instead of `<workflow-name>/...` under the current directory.",
+);
+
+const local = {
+  method: "GET",
+  path: "",
+  binary: false,
+  destructive: false,
+  local: true,
+} as const;
+
+export const SYNC_COMMANDS: CliCommand[] = [
+  {
+    ...local,
+    command: "workflow pull",
+    tool: "workflow_pull",
+    title: "Pull a workflow to disk",
+    description:
+      "Write a workflow's editable head to `<workflow-name>/head/` as files: settings, per-node instructions and scripts, and the workflow's own files. Pass --version-id for a pinned version, written read-only to `<workflow-name>/.versions/`. Edit the head files, then run `asteroid workflow push` from that folder.",
+    readOnly: true,
+    args: [
+      {
+        name: "workflowId",
+        flag: "workflow-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      option(
+        "version-id",
+        "string",
+        "A workflow version ID. Omit for the editable head.",
+      ),
+      DIR,
+    ],
+  },
+  {
+    ...local,
+    command: "workflow push",
+    tool: "workflow_push",
+    title: "Push local edits to a workflow head",
+    description:
+      "Send the edits in a pulled head folder to the workflow's editable head: changed and new files are written, removed files are deleted. Fails if the head changed since the pull; pull again and reapply. Push does not publish.",
+    readOnly: false,
+    args: [],
+    query: [
+      option(
+        "dir",
+        "string",
+        "The pulled head folder. Defaults to the current directory.",
+      ),
+    ],
+  },
+  {
+    ...local,
+    command: "execution pull",
+    tool: "execution_pull",
+    title: "Pull an execution to disk",
+    description:
+      "Write an execution to `<workflow-name>/executions/<id>/`: summary.json, activities.md (the step-by-step log), and the files the run produced.",
+    readOnly: true,
+    args: [
+      {
+        name: "executionId",
+        flag: "execution-id",
+        type: "string",
+        required: true,
+      },
+    ],
+    query: [
+      option(
+        "files",
+        "string",
+        "Only download files whose path matches this glob. --no-files skips downloads.",
+        {
+          negatable: true,
+        },
+      ),
+      option(
+        "summary-only",
+        "boolean",
+        "Write summary.json only: no activities, no files.",
+      ),
+      option(
+        "max-file-size",
+        "integer",
+        "Skip files larger than this many bytes.",
+      ),
+      option(
+        "dir",
+        "string",
+        "Write here instead of `<workflow-name>/executions/<id>/` under the current directory.",
+      ),
+    ],
+  },
+];