@asteroidai/cli 1.9.4 → 1.9.12

package/src/run.test.ts

@@ -1,11 +1,11 @@
-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";
 
 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,109 @@ describe("terminal safety", () => {
   });
 });
 
+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,
+        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", "version", "pull", "w1", "v-2", "--out", 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("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(
       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 { runsLocally, 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,16 +162,37 @@ 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,
+      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);
@@ -172,6 +202,14 @@ export async function run(argv: string[], deps: Deps): Promise<number> {
     if (invocation.kind === "builtin") {
       return await runBuiltin(invocation.name, invocation.parsed, deps);
     }
+    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, {
+        ...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,63 @@
+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 local = {
+  method: "GET",
+  path: "",
+  binary: false,
+  destructive: false,
+  local: true,
+} as const;
+
+export const SYNC_COMMANDS: CliCommand[] = [
+  {
+    ...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.",
+      ),
+    ],
+  },
+];

package/src/sync/execution-pull.ts

@@ -0,0 +1,273 @@
+import { type Activity, formatActivitiesMarkdown } from "./activities";
+import {
+  executionDirName,
+  isContained,
+  join,
+  matchesGlob,
+  workflowRoot,
+} from "./paths";
+import { get, type Sync } from "./types";
+
+export interface Execution {
+  id: string;
+  status: string;
+  workflowId: string;
+  workflowVersionId?: string;
+  workflowName?: string;
+  inputs?: unknown;
+  executionResult?: { outcome?: string; reasoning?: string } | null;
+  createdAt: string;
+  terminalAt?: string | null;
+  duration?: number | null;
+  scriptFailures?: { nodeName?: string; error?: string }[] | null;
+  purgedAt?: string | null;
+}
+
+interface ExecutionFile {
+  id: string;
+  fileName: string;
+  filePath: string;
+  fileSize: number;
+  directory: string;
+}
+
+const DIRECTORIES = ["workspace", "downloads", "shared"] as const;
+
+export interface ExecutionPullOptions {
+  executionId: string;
+  root: string;
+  dir?: (execution: Execution) => string | undefined;
+  files?: boolean;
+  activities?: boolean;
+  glob?: string;
+  maxFileBytes?: number;
+}
+
+export interface ExecutionPullResult {
+  execution: Execution;
+  dir: string;
+  written: string[];
+  downloaded: number;
+  candidates: number;
+  skipped: string[];
+  failed: string[];
+  skippedBy?: string;
+}
+
+export function relativeFilePath(
+  file: Pick<ExecutionFile, "filePath" | "directory">,
+): string {
+  const at = file.filePath.indexOf(`/${file.directory}/`);
+  if (at === -1)
+    return `${file.directory}/${file.filePath.split("/").pop() ?? "unknown"}`;
+  return file.filePath
+    .slice(at + 1)
+    .replace(/^workspace\/\.execution-context\//, "");
+}
+
+function executionDir(
+  options: ExecutionPullOptions,
+  execution: Execution,
+): string {
+  const chosen = options.dir?.(execution);
+  if (chosen) return chosen;
+  const root = workflowRoot(
+    options.root,
+    execution.workflowName ?? execution.workflowId,
+  );
+  return join(root, "executions", executionDirName(execution.id));
+}
+
+async function writeText(sync: Sync, path: string, text: string) {
+  await sync.files.write(path, Buffer.from(text, "utf8"));
+}
+
+async function writeActivities(sync: Sync, dir: string, execution: Execution) {
+  try {
+    const activities = (await sync.remote.json(
+      get(`/agents/v2/executions/${execution.id}/activities`, { order: "asc" }),
+    )) as Activity[];
+    if (activities.length === 0) return false;
+    const markdown = formatActivitiesMarkdown(
+      activities,
+      execution.status,
+      execution.createdAt,
+    );
+    await writeText(sync, join(dir, "activities.md"), markdown);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listFiles(
+  sync: Sync,
+  executionId: string,
+): Promise<ExecutionFile[]> {
+  const listing = (await sync.remote.json(
+    get(`/agents/v2/executions/${executionId}/files`),
+  )) as {
+    directories: Partial<Record<string, ExecutionFile[]>>;
+  };
+  return DIRECTORIES.flatMap((name) => listing.directories[name] ?? []);
+}
+
+async function download(sync: Sync, executionId: string, file: ExecutionFile) {
+  const path = `/agents/v2/executions/${executionId}/files/${file.id}/signed-url`;
+  const { url } = (await sync.remote.json(get(path))) as { url: string };
+  return sync.remote.download(url);
+}
+
+function selectFiles(
+  files: ExecutionFile[],
+  options: ExecutionPullOptions,
+  skipped: string[],
+) {
+  return files.filter((file) => {
+    const path = relativeFilePath(file);
+    if (!isContained(path)) skipped.push(`${path} (unsafe path)`);
+    else if (options.glob !== undefined && !matchesGlob(path, options.glob))
+      skipped.push(`${path} (excluded by --files)`);
+    else if (
+      options.maxFileBytes !== undefined &&
+      file.fileSize > options.maxFileBytes
+    )
+      skipped.push(`${path} (${file.fileSize} bytes, over the size limit)`);
+    else return true;
+    return false;
+  });
+}
+
+async function pullFiles(
+  sync: Sync,
+  dir: string,
+  options: ExecutionPullOptions,
+) {
+  const skipped: string[] = [];
+  const failed: string[] = [];
+  let files: ExecutionFile[];
+  try {
+    files = await listFiles(sync, options.executionId);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      downloaded: 0,
+      candidates: 0,
+      skipped,
+      failed: [`file listing (${reason})`],
+    };
+  }
+  let downloaded = 0;
+  await Promise.all(
+    selectFiles(files, options, skipped).map(async (file) => {
+      try {
+        const bytes = await download(sync, options.executionId, file);
+        await sync.files.write(join(dir, relativeFilePath(file)), bytes);
+        downloaded++;
+      } catch (error) {
+        failed.push(
+          `${file.fileName} (${error instanceof Error ? error.message : String(error)})`,
+        );
+      }
+    }),
+  );
+  return { downloaded, candidates: files.length, skipped, failed };
+}
+
+export async function pullExecution(
+  sync: Sync,
+  options: ExecutionPullOptions,
+): Promise<ExecutionPullResult> {
+  const execution = (await sync.remote.json(
+    get(`/agents/v2/executions/${options.executionId}`),
+  )) as Execution;
+  const dir = executionDir(options, execution);
+  await writeText(
+    sync,
+    join(dir, "summary.json"),
+    JSON.stringify(execution, null, 2),
+  );
+  const result = {
+    execution,
+    dir,
+    written: ["summary.json"],
+    downloaded: 0,
+    candidates: 0,
+    skipped: [],
+    failed: [],
+  };
+  if (execution.purgedAt) return result;
+  if (
+    options.activities !== false &&
+    (await writeActivities(sync, dir, execution))
+  )
+    result.written.push("activities.md");
+  if (options.files === false) {
+    return {
+      ...result,
+      skippedBy: options.activities === false ? "--summary-only" : "--no-files",
+    };
+  }
+  return { ...result, ...(await pullFiles(sync, dir, options)) };
+}
+
+function filesLine(result: ExecutionPullResult): string {
+  const parts = [...result.written];
+  if (result.downloaded > 0) parts.push(`${result.downloaded} downloaded`);
+  const counted = `Files: ${result.written.length + result.downloaded} written (${parts.join(", ")})`;
+  if (result.skippedBy)
+    return `${counted}; downloads skipped (${result.skippedBy})`;
+  if (result.candidates === 0) return `${counted}; no execution files matched`;
+  return counted;
+}
+
+function failures(execution: Execution): string | null {
+  const list = execution.scriptFailures ?? [];
+  if (list.length === 0) return null;
+  const lines = list.map(
+    (f) =>
+      `  - ${f.nodeName ?? "(unknown node)"}: ${(f.error ?? "").split("\n")[0]}`,
+  );
+  return `Script failures: ${list.length}\n${lines.join("\n")}`;
+}
+
+function purged(result: ExecutionPullResult): string {
+  const { execution } = result;
+  return [
+    `Execution: ${execution.id}`,
+    `Status: ${execution.status}`,
+    `Purged: ${execution.purgedAt}`,
+    "This run was retention-purged. Activities, files, inputs and result are gone. Do not diagnose it.",
+    `Written to: ${result.dir}/`,
+  ].join("\n");
+}
+
+export function formatExecutionPull(result: ExecutionPullResult): string {
+  const { execution } = result;
+  if (execution.purgedAt) return purged(result);
+  const outcome = execution.executionResult;
+  return [
+    `Execution: ${execution.id}`,
+    `Status: ${execution.status}`,
+    `Workflow: ${execution.workflowName ?? execution.workflowId}`,
+    execution.workflowVersionId
+      ? `Workflow version: ${execution.workflowVersionId}`
+      : null,
+    execution.inputs ? `Inputs: ${JSON.stringify(execution.inputs)}` : null,
+    outcome ? `Result: ${outcome.outcome}: ${outcome.reasoning}` : null,
+    `Created: ${execution.createdAt}`,
+    execution.terminalAt ? `Completed: ${execution.terminalAt}` : null,
+    execution.duration != null
+      ? `Duration: ${execution.duration.toFixed(1)}s`
+      : null,
+    failures(execution),
+    filesLine(result),
+    result.skipped.length > 0
+      ? `Skipped:\n${result.skipped.map((s) => `  - ${s}`).join("\n")}`
+      : null,
+    result.failed.length > 0 ? `Failed: ${result.failed.join(", ")}` : null,
+    `Written to: ${result.dir}/`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+}