@asteroidai/cli 1.9.111 → 1.9.122

package/dist/asteroid.js

@@ -1946,6 +1946,34 @@ var COMMANDS = [
     destructive: false,
     capability: "run_execution"
   },
+  {
+    command: "execution sync",
+    tool: "execution_sync",
+    title: "Wait for an execution to finish",
+    description: "Wait up to `timeoutSeconds` (1-25, default 25) for a running execution to finish. Returns the terminal `status` and `executionResult` when it finishes in time. Otherwise returns the current status: call it again to keep waiting. A paused or `awaiting_confirmation` execution returns at once, since it needs a person. Use it after `workflow_execute_post`, or after `workflow_execute_sync_post` timed out, instead of polling `execution_get`.",
+    method: "GET",
+    path: "/agents/v2/executions/{executionId}/sync",
+    args: [
+      {
+        name: "executionId",
+        flag: "execution-id",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [
+      {
+        name: "timeoutSeconds",
+        flag: "timeout-seconds",
+        type: "integer",
+        required: false,
+        description: "Seconds to wait for the execution to finish before returning 202. Defaults to 25."
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "insight get",
     tool: "insight_get",
@@ -2206,7 +2234,7 @@ var COMMANDS = [
     command: "portal-skills add",
     tool: "portal_skills_add",
     title: "Add portal skills",
-    description: "Add a portal's skills to an organization, by a `portalId` from `portal_skills_list`. Needs a Startup plan or above. Astro loads the portal's skills once it is added. Adding one the organization already has is a no-op.",
+    description: "Add a portal's skills to an organization, by the `portalId` of a portal skill from `skills_list`. Needs a Startup plan or above. Astro loads the portal's skills once it is added, and `skill_get` serves them. Adding one the organization already has is a no-op.",
     method: "POST",
     path: "/agents/v2/portal-skills/{portalId}",
     args: [
@@ -2222,27 +2250,6 @@ var COMMANDS = [
     readOnly: false,
     destructive: false
   },
-  {
-    command: "portal-skills list",
-    tool: "portal_skills_list",
-    title: "List portal skills",
-    description: "List the skills for third-party portals, or only for the portals matching a portal name or task, such as `caloptima eligibility`. A portal skill is general knowledge about how a portal works: sign-in, page quirks, field mappings. Each portal comes with its skill names, and whether the organization has added it. Add one with `portal_skills_add`.",
-    method: "GET",
-    path: "/astro/v2/portal-skills",
-    args: [],
-    query: [
-      {
-        name: "query",
-        flag: "query",
-        type: "string",
-        required: false,
-        description: "A portal name or task, at least three characters. Omit to list every portal with skills."
-      }
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false
-  },
   {
     command: "profile clear-cache",
     tool: "profile_clear_browser_cache",
@@ -4018,6 +4025,80 @@ var COMMANDS = [
       credentialOrganization: false
     }
   },
+  {
+    command: "skill get",
+    tool: "skill_get",
+    title: "Get skill",
+    description: "Get one skill with the content of every file, SKILL.md first, in the Agent Skills format. A name resolves to the public skill, then a portal's, then the organization's; set `kind` to pick one. A portal skill needs its portal added with `portal_skills_add`. Pass `surface` `mcp` to spell the platform's commands as MCP tools.",
+    method: "GET",
+    path: "/astro/v2/skills/{name}",
+    args: [
+      {
+        name: "name",
+        flag: "name",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [
+      {
+        name: "kind",
+        flag: "kind",
+        type: "string",
+        required: false,
+        description: "Only a skill of this kind.",
+        enum: ["public", "portal", "organization"]
+      },
+      {
+        name: "surface",
+        flag: "surface",
+        type: "string",
+        required: false,
+        description: "The surface the skill is rendered for. Defaults to `cli`.",
+        enum: ["cli", "mcp"]
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
+  {
+    command: "skill list",
+    tool: "skills_list",
+    title: "List skills",
+    description: "List the skills an organization can load, by kind then name: Asteroid's `public` skills, the `portal` skills (general knowledge of a third-party portal: sign-in, page quirks, field mappings) with whether the organization has added the portal, and the `organization`'s own. Filter with `kind`, or rank by a `query` such as `caloptima eligibility`. Each skill comes with its file paths and digests; `skill_get` returns the content. Add a portal with `portal_skills_add`.",
+    method: "GET",
+    path: "/astro/v2/skills",
+    args: [],
+    query: [
+      {
+        name: "kind",
+        flag: "kind",
+        type: "string",
+        required: false,
+        description: "Only skills of this kind.",
+        enum: ["public", "portal", "organization"]
+      },
+      {
+        name: "query",
+        flag: "query",
+        type: "string",
+        required: false,
+        description: "A skill name, portal name or task, at least three characters. Best matches first."
+      },
+      {
+        name: "surface",
+        flag: "surface",
+        type: "string",
+        required: false,
+        description: "The surface the skills are rendered for. Defaults to `cli`.",
+        enum: ["cli", "mcp"]
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "tag create",
     tool: "workflow_tags_create",
@@ -6147,6 +6228,85 @@ var COMMANDS = [
   }
 ];
 
+// src/sync/types.ts
+var MANIFEST = ".asteroid.json";
+function get(path, query = {}) {
+  return { method: "GET", path, query: new URLSearchParams(query) };
+}
+function statusOf(error) {
+  const status = error?.status;
+  return typeof status === "number" ? status : void 0;
+}
+
+// src/sync/execution-wait.ts
+var WAIT_TIMEOUT_SECONDS = 600;
+var WAIT_INTERVAL_SECONDS = 15;
+var MAX_WAIT_TIMEOUT_SECONDS = 3600;
+var MAX_WAIT_INTERVAL_SECONDS = 120;
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "cancelled", "failed"]);
+function isTerminalExecutionStatus(status) {
+  return TERMINAL.has(status);
+}
+var SYNC_TIMEOUT_SECONDS = 25;
+function pause(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function readStatus(sync, executionId2, timeoutMs) {
+  if (timeoutMs <= 0)
+    return await sync.remote.json(
+      get(`/agents/v2/executions/${executionId2}`)
+    );
+  const timeoutSeconds = Math.min(
+    SYNC_TIMEOUT_SECONDS,
+    Math.max(1, Math.ceil(timeoutMs / 1e3))
+  );
+  const response = await sync.remote.json(
+    get(`/agents/v2/executions/${executionId2}/sync`, {
+      timeoutSeconds: String(timeoutSeconds)
+    })
+  );
+  return {
+    id: response.executionId,
+    status: response.status,
+    executionResult: response.executionResult
+  };
+}
+async function waitForExecution(sync, options) {
+  const timeoutMs = (options.timeoutSeconds ?? WAIT_TIMEOUT_SECONDS) * 1e3;
+  const intervalMs = (options.intervalSeconds ?? WAIT_INTERVAL_SECONDS) * 1e3;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? pause;
+  const started = now();
+  let polls = 0;
+  for (; ; ) {
+    const called = now();
+    const execution = await readStatus(
+      sync,
+      options.executionId,
+      timeoutMs - (called - started)
+    );
+    polls++;
+    const elapsed = now() - started;
+    const waitedSeconds = Math.round(elapsed / 1e3);
+    if (isTerminalExecutionStatus(execution.status))
+      return { execution, terminal: true, waitedSeconds, polls };
+    const remaining = timeoutMs - elapsed;
+    if (remaining <= 0)
+      return { execution, terminal: false, waitedSeconds, polls };
+    const early = intervalMs - (now() - called);
+    if (early > 0) await sleep(Math.min(early, remaining));
+  }
+}
+function formatExecutionWait(result) {
+  const { execution } = result;
+  if (!result.terminal) {
+    return `Execution ${execution.id} still ${execution.status} after ${result.waitedSeconds}s. Wait again, or read what it has so far with \`asteroid execution pull ${execution.id}\`.`;
+  }
+  const line2 = `Execution ${execution.id} ${execution.status}.`;
+  const outcome = execution.executionResult;
+  return outcome ? `${line2} Result: ${outcome.outcome}: ${outcome.reasoning}` : line2;
+}
+
 // src/sync/commands.ts
 function option(name, type, description, extra = {}) {
   return { name, flag: name, type, required: false, description, ...extra };
@@ -6158,6 +6318,12 @@ var local = {
   destructive: false,
   local: true
 };
+var executionId = {
+  name: "executionId",
+  flag: "execution-id",
+  type: "string",
+  required: true
+};
 var SYNC_COMMANDS = [
   {
     ...local,
@@ -6166,14 +6332,7 @@ var SYNC_COMMANDS = [
     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
-      }
-    ],
+    args: [executionId],
     query: [
       option(
         "files",
@@ -6199,6 +6358,54 @@ var SYNC_COMMANDS = [
         "Write here instead of `<workflow-name>/executions/<id>/` under the current directory."
       )
     ]
+  },
+  {
+    ...local,
+    command: "execution wait",
+    tool: "execution_wait",
+    title: "Wait for an execution to end",
+    description: "Poll an execution until it is completed, failed or cancelled, then print its status and, when the run produced one, its result. When the timeout passes first, print the status it still has, so you can wait again.",
+    readOnly: true,
+    args: [executionId],
+    query: [
+      option(
+        "timeout",
+        "integer",
+        `Give up after this many seconds, ${WAIT_TIMEOUT_SECONDS} unless set, ${MAX_WAIT_TIMEOUT_SECONDS} at most.`
+      ),
+      option(
+        "interval",
+        "integer",
+        `Poll every this many seconds, ${WAIT_INTERVAL_SECONDS} unless set, ${MAX_WAIT_INTERVAL_SECONDS} at most.`
+      )
+    ]
+  },
+  {
+    ...local,
+    command: "insight pull",
+    tool: "insight_pull",
+    title: "Pull insights to disk",
+    description: "Write insights to `insights/<name>.md`, one markdown file each with YAML frontmatter (id, type, status, name, next_steps). Name an insight to pull that one. A file another insight or an unpushed draft already holds keeps its name; the pulled one gets a -2, -3 suffix.",
+    readOnly: true,
+    args: [
+      {
+        name: "insightId",
+        flag: "insight-id",
+        type: "string",
+        required: false,
+        description: "One insight to pull. Without it, every insight, or one workflow's with --workflow-id."
+      }
+    ],
+    query: [
+      option("workflowId", "string", "Only this workflow's insights.", {
+        flag: "workflow-id"
+      }),
+      option(
+        "dir",
+        "string",
+        "Write here instead of `insights/` under the current directory."
+      )
+    ]
   }
 ];
 
@@ -6657,15 +6864,16 @@ function defineCommands(root, options, dotted2 = /* @__PURE__ */ new Map(), onIn
       (arg) => options.defaultArg?.(command, arg)
     );
     const defaulted = defaults[0] !== void 0;
+    const optional = (arg, i) => i === 0 && defaulted || !arg.required;
     command.args.forEach((arg) => {
       leaf.argument(
-        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
+        defaulted || !arg.required ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
     if (defaulted) {
       const names = command.args.map(
-        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+        (arg, i) => optional(arg, i) ? `[${arg.flag}]` : `<${arg.flag}>`
       );
       leaf.usage(`[options] ${names.join(" ")}`);
     }
@@ -6682,8 +6890,9 @@ ${notes.join("\n")}`);
       if (positionals.length === command.args.length - 1 && defaults[0] !== void 0) {
         positionals = [defaults[0], ...positionals];
       }
-      if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
+      const required = command.args.filter((arg) => arg.required).length;
+      if (positionals.length < required || positionals.length > command.args.length) {
+        const expected = command.args.map((a, i) => optional(a, i) ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );
@@ -7205,7 +7414,7 @@ var ApiError = class extends Error {
   status;
   body;
 };
-var VERSION = "1.9.111";
+var VERSION = "1.9.122";
 function problem(status, body, fallback) {
   if (body && typeof body === "object") {
     const record2 = body;
@@ -8017,6 +8226,13 @@ function normalizeNodeName(name) {
   }
   return result;
 }
+function lossySlugOr(name, fallback) {
+  try {
+    return normalizeNodeName(name);
+  } catch {
+    return fallback;
+  }
+}
 function nodeDirName(name) {
   if (isNameCharsetConforming(name)) {
     return name.replaceAll(" ", "_");
@@ -8030,8 +8246,8 @@ function agentDirName(name) {
     return "agent";
   }
 }
-function executionDirName(executionId) {
-  return executionId.slice(0, 8);
+function executionDirName(executionId2) {
+  return executionId2.slice(0, 8);
 }
 function workflowDirName(workflowId, version, parentId, parentVersion) {
   const short = workflowId.slice(0, 8);
@@ -8079,16 +8295,6 @@ function matchesGlob(path, pattern) {
   return new RegExp(`^${source}$`).test(path);
 }
 
-// src/sync/types.ts
-var MANIFEST = ".asteroid.json";
-function get(path, query = {}) {
-  return { method: "GET", path, query: new URLSearchParams(query) };
-}
-function statusOf(error) {
-  const status = error?.status;
-  return typeof status === "number" ? status : void 0;
-}
-
 // src/sync/execution-pull.ts
 var DIRECTORIES = ["workspace", "downloads", "shared"];
 function relativeFilePath(file) {
@@ -8126,14 +8332,14 @@ async function writeActivities(sync, dir, execution) {
     return false;
   }
 }
-async function listFiles(sync, executionId) {
+async function listFiles(sync, executionId2) {
   const listing = await sync.remote.json(
-    get(`/agents/v2/executions/${executionId}/files`)
+    get(`/agents/v2/executions/${executionId2}/files`)
   );
   return DIRECTORIES.flatMap((name) => listing.directories[name] ?? []);
 }
-async function download(sync, executionId, file) {
-  const path = `/agents/v2/executions/${executionId}/files/${file.id}/signed-url`;
+async function download(sync, executionId2, file) {
+  const path = `/agents/v2/executions/${executionId2}/files/${file.id}/signed-url`;
   const { url } = await sync.remote.json(get(path));
   return sync.remote.download(url);
 }
@@ -8261,6 +8467,114 @@ ${result.skipped.map((s) => `  - ${s}`).join("\n")}` : null,
   ].filter(Boolean).join("\n");
 }
 
+// src/sync/insight-file.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)(?:\r?\n)?/;
+function serializeInsightFile(meta, body) {
+  const front = {};
+  if (meta.id) front.id = meta.id;
+  front.type = meta.type;
+  if (meta.status) front.status = meta.status;
+  front.name = meta.name;
+  if (meta.nextSteps) front.next_steps = meta.nextSteps;
+  const yaml = stringifyYaml(front).trimEnd();
+  return `---
+${yaml}
+---
+
+${body}`;
+}
+function insightFileId(text3) {
+  const match = FRONTMATTER.exec(text3);
+  if (!match) return void 0;
+  try {
+    const id = parseYaml(match[1])?.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sync/insight-pull.ts
+var INSIGHTS_DIR = "insights";
+var PAGE_SIZE = 100;
+async function listInsights(sync, workflowId) {
+  const all = [];
+  for (let page = 1; ; page++) {
+    const query = {
+      page: String(page),
+      pageSize: String(PAGE_SIZE)
+    };
+    if (workflowId) query.workflowId = workflowId;
+    const { items, total } = await sync.remote.json(
+      get("/astro/v2/insights", query)
+    );
+    all.push(...items);
+    if (items.length === 0 || all.length >= total) return all;
+  }
+}
+async function stemOwners(sync, dir) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const name of await sync.files.list(dir)) {
+    if (!name.endsWith(".md") || name.includes("/")) continue;
+    const bytes = await sync.files.read(join3(dir, name));
+    const text3 = bytes ? Buffer.from(bytes).toString("utf8") : "";
+    owners.set(name.slice(0, -".md".length).toLowerCase(), insightFileId(text3));
+  }
+  return owners;
+}
+function assignStems(owners, insights) {
+  const used = /* @__PURE__ */ new Set();
+  const heldByOther = (stem, id) => owners.has(stem) && owners.get(stem) !== id;
+  return insights.map((insight) => {
+    const base = lossySlugOr(insight.name, "insight");
+    let stem = base;
+    for (let n = 2; used.has(stem) || heldByOther(stem, insight.id); n++) {
+      stem = `${base}-${n}`;
+    }
+    used.add(stem);
+    return [insight, stem];
+  });
+}
+async function pullInsights(sync, options = {}) {
+  const dir = options.dir ?? INSIGHTS_DIR;
+  const insights = options.insightId ? [
+    await sync.remote.json(
+      get(`/astro/v2/insights/${options.insightId}`)
+    )
+  ] : await listInsights(sync, options.workflowId);
+  const pulled = [];
+  for (const [insight, stem] of assignStems(
+    await stemOwners(sync, dir),
+    insights
+  )) {
+    const path = join3(dir, `${stem}.md`);
+    const text3 = serializeInsightFile(
+      {
+        id: insight.id,
+        type: insight.type,
+        status: insight.status,
+        name: insight.name,
+        nextSteps: insight.nextSteps ?? void 0
+      },
+      insight.content
+    );
+    await sync.files.write(path, Buffer.from(text3, "utf8"));
+    const { id, name, type, status } = insight;
+    pulled.push({ id, name, type, status, path });
+  }
+  return { dir, insights: pulled };
+}
+function formatInsightPull(result) {
+  const count = result.insights.length;
+  return [
+    `Pulled ${count} insight${count === 1 ? "" : "s"} into ${result.dir}/.`,
+    ...result.insights.map(
+      (insight) => `  - ${insight.path}: ${insight.name} (${insight.type}, ${insight.status})`
+    )
+  ].join("\n");
+}
+
 // src/sync/node-files.ts
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname as dirname2, relative, resolve, sep } from "node:path";
@@ -8673,6 +8987,35 @@ function integer(parsed, name) {
     throw new UsageError(`--${name} must be a whole number`);
   return Number(raw);
 }
+function bounded(parsed, name, min, max) {
+  const value2 = integer(parsed, name);
+  if (value2 === void 0) return void 0;
+  if (value2 < min || value2 > max)
+    throw new UsageError(`--${name} must be between ${min} and ${max}`);
+  return value2;
+}
+function executionWaitOptions(parsed) {
+  return {
+    executionId: parsed.positionals[0],
+    timeoutSeconds: bounded(parsed, "timeout", 0, MAX_WAIT_TIMEOUT_SECONDS),
+    intervalSeconds: bounded(parsed, "interval", 1, MAX_WAIT_INTERVAL_SECONDS)
+  };
+}
+function given(value2, name) {
+  if (value2 === void 0) return void 0;
+  if (value2 === "") throw new UsageError(`${name} must not be empty`);
+  return value2;
+}
+function insightPullOptions(parsed) {
+  const options = {};
+  const insightId = given(parsed.positionals[0], "<insight-id>");
+  if (insightId) options.insightId = insightId;
+  const workflowId = given(flag(parsed, "workflow-id"), "--workflow-id");
+  if (workflowId) options.workflowId = workflowId;
+  const dir = given(flag(parsed, "dir"), "--dir");
+  if (dir) options.dir = dir;
+  return options;
+}
 function executionOptions(parsed) {
   const summaryOnly = flag(parsed, "summary-only") === "true";
   const glob = flag(parsed, "files");
@@ -8734,6 +9077,20 @@ async function execute(command, parsed, sync, deps) {
     );
     return { result: result2, text: formatWorkflowPush(result2) };
   }
+  if (command.command === "execution wait") {
+    const result2 = await waitForExecution(sync, {
+      ...executionWaitOptions(parsed),
+      ...deps.executionWait
+    });
+    return { result: result2, text: formatExecutionWait(result2) };
+  }
+  if (command.command === "insight pull") {
+    const result2 = await pullInsights(sync, {
+      ...deps.insightPull,
+      ...insightPullOptions(parsed)
+    });
+    return { result: result2, text: formatInsightPull(result2) };
+  }
   if (command.command !== "execution pull")
     throw new UsageError(`unknown command ${command.command}`);
   const result = await pullExecution(sync, {

package/dist/core.js

@@ -1967,6 +1967,34 @@ var COMMANDS = [
     destructive: false,
     capability: "run_execution"
   },
+  {
+    command: "execution sync",
+    tool: "execution_sync",
+    title: "Wait for an execution to finish",
+    description: "Wait up to `timeoutSeconds` (1-25, default 25) for a running execution to finish. Returns the terminal `status` and `executionResult` when it finishes in time. Otherwise returns the current status: call it again to keep waiting. A paused or `awaiting_confirmation` execution returns at once, since it needs a person. Use it after `workflow_execute_post`, or after `workflow_execute_sync_post` timed out, instead of polling `execution_get`.",
+    method: "GET",
+    path: "/agents/v2/executions/{executionId}/sync",
+    args: [
+      {
+        name: "executionId",
+        flag: "execution-id",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [
+      {
+        name: "timeoutSeconds",
+        flag: "timeout-seconds",
+        type: "integer",
+        required: false,
+        description: "Seconds to wait for the execution to finish before returning 202. Defaults to 25."
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "insight get",
     tool: "insight_get",
@@ -2227,7 +2255,7 @@ var COMMANDS = [
     command: "portal-skills add",
     tool: "portal_skills_add",
     title: "Add portal skills",
-    description: "Add a portal's skills to an organization, by a `portalId` from `portal_skills_list`. Needs a Startup plan or above. Astro loads the portal's skills once it is added. Adding one the organization already has is a no-op.",
+    description: "Add a portal's skills to an organization, by the `portalId` of a portal skill from `skills_list`. Needs a Startup plan or above. Astro loads the portal's skills once it is added, and `skill_get` serves them. Adding one the organization already has is a no-op.",
     method: "POST",
     path: "/agents/v2/portal-skills/{portalId}",
     args: [
@@ -2243,27 +2271,6 @@ var COMMANDS = [
     readOnly: false,
     destructive: false
   },
-  {
-    command: "portal-skills list",
-    tool: "portal_skills_list",
-    title: "List portal skills",
-    description: "List the skills for third-party portals, or only for the portals matching a portal name or task, such as `caloptima eligibility`. A portal skill is general knowledge about how a portal works: sign-in, page quirks, field mappings. Each portal comes with its skill names, and whether the organization has added it. Add one with `portal_skills_add`.",
-    method: "GET",
-    path: "/astro/v2/portal-skills",
-    args: [],
-    query: [
-      {
-        name: "query",
-        flag: "query",
-        type: "string",
-        required: false,
-        description: "A portal name or task, at least three characters. Omit to list every portal with skills."
-      }
-    ],
-    binary: false,
-    readOnly: true,
-    destructive: false
-  },
   {
     command: "profile clear-cache",
     tool: "profile_clear_browser_cache",
@@ -4039,6 +4046,80 @@ var COMMANDS = [
       credentialOrganization: false
     }
   },
+  {
+    command: "skill get",
+    tool: "skill_get",
+    title: "Get skill",
+    description: "Get one skill with the content of every file, SKILL.md first, in the Agent Skills format. A name resolves to the public skill, then a portal's, then the organization's; set `kind` to pick one. A portal skill needs its portal added with `portal_skills_add`. Pass `surface` `mcp` to spell the platform's commands as MCP tools.",
+    method: "GET",
+    path: "/astro/v2/skills/{name}",
+    args: [
+      {
+        name: "name",
+        flag: "name",
+        type: "string",
+        required: true
+      }
+    ],
+    query: [
+      {
+        name: "kind",
+        flag: "kind",
+        type: "string",
+        required: false,
+        description: "Only a skill of this kind.",
+        enum: ["public", "portal", "organization"]
+      },
+      {
+        name: "surface",
+        flag: "surface",
+        type: "string",
+        required: false,
+        description: "The surface the skill is rendered for. Defaults to `cli`.",
+        enum: ["cli", "mcp"]
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
+  {
+    command: "skill list",
+    tool: "skills_list",
+    title: "List skills",
+    description: "List the skills an organization can load, by kind then name: Asteroid's `public` skills, the `portal` skills (general knowledge of a third-party portal: sign-in, page quirks, field mappings) with whether the organization has added the portal, and the `organization`'s own. Filter with `kind`, or rank by a `query` such as `caloptima eligibility`. Each skill comes with its file paths and digests; `skill_get` returns the content. Add a portal with `portal_skills_add`.",
+    method: "GET",
+    path: "/astro/v2/skills",
+    args: [],
+    query: [
+      {
+        name: "kind",
+        flag: "kind",
+        type: "string",
+        required: false,
+        description: "Only skills of this kind.",
+        enum: ["public", "portal", "organization"]
+      },
+      {
+        name: "query",
+        flag: "query",
+        type: "string",
+        required: false,
+        description: "A skill name, portal name or task, at least three characters. Best matches first."
+      },
+      {
+        name: "surface",
+        flag: "surface",
+        type: "string",
+        required: false,
+        description: "The surface the skills are rendered for. Defaults to `cli`.",
+        enum: ["cli", "mcp"]
+      }
+    ],
+    binary: false,
+    readOnly: true,
+    destructive: false
+  },
   {
     command: "tag create",
     tool: "workflow_tags_create",
@@ -6527,15 +6608,16 @@ function defineCommands(root, options, dotted2 = /* @__PURE__ */ new Map(), onIn
       (arg) => options.defaultArg?.(command, arg)
     );
     const defaulted = defaults[0] !== void 0;
+    const optional = (arg, i) => i === 0 && defaulted || !arg.required;
     command.args.forEach((arg) => {
       leaf.argument(
-        defaulted ? `[${arg.flag}]` : `<${arg.flag}>`,
+        defaulted || !arg.required ? `[${arg.flag}]` : `<${arg.flag}>`,
         arg.description ?? ""
       );
     });
     if (defaulted) {
       const names = command.args.map(
-        (arg, i) => i === 0 ? `[${arg.flag}]` : `<${arg.flag}>`
+        (arg, i) => optional(arg, i) ? `[${arg.flag}]` : `<${arg.flag}>`
       );
       leaf.usage(`[options] ${names.join(" ")}`);
     }
@@ -6552,8 +6634,9 @@ ${notes.join("\n")}`);
       if (positionals.length === command.args.length - 1 && defaults[0] !== void 0) {
         positionals = [defaults[0], ...positionals];
       }
-      if (positionals.length !== command.args.length) {
-        const expected = command.args.map((a, i) => i === 0 && defaulted ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
+      const required = command.args.filter((arg) => arg.required).length;
+      if (positionals.length < required || positionals.length > command.args.length) {
+        const expected = command.args.map((a, i) => optional(a, i) ? `[${a.flag}]` : `<${a.flag}>`).join(" ");
         throw new UsageError(
           `expected ${expected}, got ${cmd.args.length} argument(s)`
         );
@@ -6851,6 +6934,85 @@ function rejectUnknown(flags) {
   }
 }
 
+// src/sync/types.ts
+var MANIFEST = ".asteroid.json";
+function get(path, query = {}) {
+  return { method: "GET", path, query: new URLSearchParams(query) };
+}
+function statusOf(error) {
+  const status = error?.status;
+  return typeof status === "number" ? status : void 0;
+}
+
+// src/sync/execution-wait.ts
+var WAIT_TIMEOUT_SECONDS = 600;
+var WAIT_INTERVAL_SECONDS = 15;
+var MAX_WAIT_TIMEOUT_SECONDS = 3600;
+var MAX_WAIT_INTERVAL_SECONDS = 120;
+var TERMINAL = /* @__PURE__ */ new Set(["completed", "cancelled", "failed"]);
+function isTerminalExecutionStatus(status) {
+  return TERMINAL.has(status);
+}
+var SYNC_TIMEOUT_SECONDS = 25;
+function pause(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function readStatus(sync, executionId2, timeoutMs) {
+  if (timeoutMs <= 0)
+    return await sync.remote.json(
+      get(`/agents/v2/executions/${executionId2}`)
+    );
+  const timeoutSeconds = Math.min(
+    SYNC_TIMEOUT_SECONDS,
+    Math.max(1, Math.ceil(timeoutMs / 1e3))
+  );
+  const response = await sync.remote.json(
+    get(`/agents/v2/executions/${executionId2}/sync`, {
+      timeoutSeconds: String(timeoutSeconds)
+    })
+  );
+  return {
+    id: response.executionId,
+    status: response.status,
+    executionResult: response.executionResult
+  };
+}
+async function waitForExecution(sync, options) {
+  const timeoutMs = (options.timeoutSeconds ?? WAIT_TIMEOUT_SECONDS) * 1e3;
+  const intervalMs = (options.intervalSeconds ?? WAIT_INTERVAL_SECONDS) * 1e3;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? pause;
+  const started = now();
+  let polls = 0;
+  for (; ; ) {
+    const called = now();
+    const execution = await readStatus(
+      sync,
+      options.executionId,
+      timeoutMs - (called - started)
+    );
+    polls++;
+    const elapsed = now() - started;
+    const waitedSeconds = Math.round(elapsed / 1e3);
+    if (isTerminalExecutionStatus(execution.status))
+      return { execution, terminal: true, waitedSeconds, polls };
+    const remaining = timeoutMs - elapsed;
+    if (remaining <= 0)
+      return { execution, terminal: false, waitedSeconds, polls };
+    const early = intervalMs - (now() - called);
+    if (early > 0) await sleep(Math.min(early, remaining));
+  }
+}
+function formatExecutionWait(result) {
+  const { execution } = result;
+  if (!result.terminal) {
+    return `Execution ${execution.id} still ${execution.status} after ${result.waitedSeconds}s. Wait again, or read what it has so far with \`asteroid execution pull ${execution.id}\`.`;
+  }
+  const line2 = `Execution ${execution.id} ${execution.status}.`;
+  const outcome = execution.executionResult;
+  return outcome ? `${line2} Result: ${outcome.outcome}: ${outcome.reasoning}` : line2;
+}
+
 // src/sync/commands.ts
 function option(name, type, description, extra = {}) {
   return { name, flag: name, type, required: false, description, ...extra };
@@ -6862,6 +7024,12 @@ var local = {
   destructive: false,
   local: true
 };
+var executionId = {
+  name: "executionId",
+  flag: "execution-id",
+  type: "string",
+  required: true
+};
 var SYNC_COMMANDS = [
   {
     ...local,
@@ -6870,14 +7038,7 @@ var SYNC_COMMANDS = [
     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
-      }
-    ],
+    args: [executionId],
     query: [
       option(
         "files",
@@ -6903,6 +7064,54 @@ var SYNC_COMMANDS = [
         "Write here instead of `<workflow-name>/executions/<id>/` under the current directory."
       )
     ]
+  },
+  {
+    ...local,
+    command: "execution wait",
+    tool: "execution_wait",
+    title: "Wait for an execution to end",
+    description: "Poll an execution until it is completed, failed or cancelled, then print its status and, when the run produced one, its result. When the timeout passes first, print the status it still has, so you can wait again.",
+    readOnly: true,
+    args: [executionId],
+    query: [
+      option(
+        "timeout",
+        "integer",
+        `Give up after this many seconds, ${WAIT_TIMEOUT_SECONDS} unless set, ${MAX_WAIT_TIMEOUT_SECONDS} at most.`
+      ),
+      option(
+        "interval",
+        "integer",
+        `Poll every this many seconds, ${WAIT_INTERVAL_SECONDS} unless set, ${MAX_WAIT_INTERVAL_SECONDS} at most.`
+      )
+    ]
+  },
+  {
+    ...local,
+    command: "insight pull",
+    tool: "insight_pull",
+    title: "Pull insights to disk",
+    description: "Write insights to `insights/<name>.md`, one markdown file each with YAML frontmatter (id, type, status, name, next_steps). Name an insight to pull that one. A file another insight or an unpushed draft already holds keeps its name; the pulled one gets a -2, -3 suffix.",
+    readOnly: true,
+    args: [
+      {
+        name: "insightId",
+        flag: "insight-id",
+        type: "string",
+        required: false,
+        description: "One insight to pull. Without it, every insight, or one workflow's with --workflow-id."
+      }
+    ],
+    query: [
+      option("workflowId", "string", "Only this workflow's insights.", {
+        flag: "workflow-id"
+      }),
+      option(
+        "dir",
+        "string",
+        "Write here instead of `insights/` under the current directory."
+      )
+    ]
   }
 ];
 
@@ -7015,6 +7224,13 @@ function normalizeNodeName(name) {
   }
   return result;
 }
+function lossySlugOr(name, fallback) {
+  try {
+    return normalizeNodeName(name);
+  } catch {
+    return fallback;
+  }
+}
 function nodeDirName(name) {
   if (isNameCharsetConforming(name)) {
     return name.replaceAll(" ", "_");
@@ -7028,8 +7244,8 @@ function agentDirName(name) {
     return "agent";
   }
 }
-function executionDirName(executionId) {
-  return executionId.slice(0, 8);
+function executionDirName(executionId2) {
+  return executionId2.slice(0, 8);
 }
 function workflowDirName(workflowId, version, parentId, parentVersion) {
   const short = workflowId.slice(0, 8);
@@ -7077,16 +7293,6 @@ function matchesGlob(path, pattern) {
   return new RegExp(`^${source}$`).test(path);
 }
 
-// src/sync/types.ts
-var MANIFEST = ".asteroid.json";
-function get(path, query = {}) {
-  return { method: "GET", path, query: new URLSearchParams(query) };
-}
-function statusOf(error) {
-  const status = error?.status;
-  return typeof status === "number" ? status : void 0;
-}
-
 // src/sync/execution-pull.ts
 var DIRECTORIES = ["workspace", "downloads", "shared"];
 function relativeFilePath(file) {
@@ -7124,14 +7330,14 @@ async function writeActivities(sync, dir, execution) {
     return false;
   }
 }
-async function listFiles(sync, executionId) {
+async function listFiles(sync, executionId2) {
   const listing = await sync.remote.json(
-    get(`/agents/v2/executions/${executionId}/files`)
+    get(`/agents/v2/executions/${executionId2}/files`)
   );
   return DIRECTORIES.flatMap((name) => listing.directories[name] ?? []);
 }
-async function download(sync, executionId, file) {
-  const path = `/agents/v2/executions/${executionId}/files/${file.id}/signed-url`;
+async function download(sync, executionId2, file) {
+  const path = `/agents/v2/executions/${executionId2}/files/${file.id}/signed-url`;
   const { url } = await sync.remote.json(get(path));
   return sync.remote.download(url);
 }
@@ -7259,6 +7465,114 @@ ${result.skipped.map((s) => `  - ${s}`).join("\n")}` : null,
   ].filter(Boolean).join("\n");
 }
 
+// src/sync/insight-file.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)(?:\r?\n)?/;
+function serializeInsightFile(meta, body) {
+  const front = {};
+  if (meta.id) front.id = meta.id;
+  front.type = meta.type;
+  if (meta.status) front.status = meta.status;
+  front.name = meta.name;
+  if (meta.nextSteps) front.next_steps = meta.nextSteps;
+  const yaml = stringifyYaml(front).trimEnd();
+  return `---
+${yaml}
+---
+
+${body}`;
+}
+function insightFileId(text2) {
+  const match = FRONTMATTER.exec(text2);
+  if (!match) return void 0;
+  try {
+    const id = parseYaml(match[1])?.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sync/insight-pull.ts
+var INSIGHTS_DIR = "insights";
+var PAGE_SIZE = 100;
+async function listInsights(sync, workflowId) {
+  const all = [];
+  for (let page = 1; ; page++) {
+    const query = {
+      page: String(page),
+      pageSize: String(PAGE_SIZE)
+    };
+    if (workflowId) query.workflowId = workflowId;
+    const { items, total } = await sync.remote.json(
+      get("/astro/v2/insights", query)
+    );
+    all.push(...items);
+    if (items.length === 0 || all.length >= total) return all;
+  }
+}
+async function stemOwners(sync, dir) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const name of await sync.files.list(dir)) {
+    if (!name.endsWith(".md") || name.includes("/")) continue;
+    const bytes = await sync.files.read(join(dir, name));
+    const text2 = bytes ? Buffer.from(bytes).toString("utf8") : "";
+    owners.set(name.slice(0, -".md".length).toLowerCase(), insightFileId(text2));
+  }
+  return owners;
+}
+function assignStems(owners, insights) {
+  const used = /* @__PURE__ */ new Set();
+  const heldByOther = (stem, id) => owners.has(stem) && owners.get(stem) !== id;
+  return insights.map((insight) => {
+    const base = lossySlugOr(insight.name, "insight");
+    let stem = base;
+    for (let n = 2; used.has(stem) || heldByOther(stem, insight.id); n++) {
+      stem = `${base}-${n}`;
+    }
+    used.add(stem);
+    return [insight, stem];
+  });
+}
+async function pullInsights(sync, options = {}) {
+  const dir = options.dir ?? INSIGHTS_DIR;
+  const insights = options.insightId ? [
+    await sync.remote.json(
+      get(`/astro/v2/insights/${options.insightId}`)
+    )
+  ] : await listInsights(sync, options.workflowId);
+  const pulled = [];
+  for (const [insight, stem] of assignStems(
+    await stemOwners(sync, dir),
+    insights
+  )) {
+    const path = join(dir, `${stem}.md`);
+    const text2 = serializeInsightFile(
+      {
+        id: insight.id,
+        type: insight.type,
+        status: insight.status,
+        name: insight.name,
+        nextSteps: insight.nextSteps ?? void 0
+      },
+      insight.content
+    );
+    await sync.files.write(path, Buffer.from(text2, "utf8"));
+    const { id, name, type, status } = insight;
+    pulled.push({ id, name, type, status, path });
+  }
+  return { dir, insights: pulled };
+}
+function formatInsightPull(result) {
+  const count = result.insights.length;
+  return [
+    `Pulled ${count} insight${count === 1 ? "" : "s"} into ${result.dir}/.`,
+    ...result.insights.map(
+      (insight) => `  - ${insight.path}: ${insight.name} (${insight.type}, ${insight.status})`
+    )
+  ].join("\n");
+}
+
 // src/sync/manifest.ts
 async function loadManifest(sync, dir) {
   const bytes = await sync.files.read(join(dir, MANIFEST));
@@ -7671,6 +7985,35 @@ function integer(parsed, name) {
     throw new UsageError(`--${name} must be a whole number`);
   return Number(raw);
 }
+function bounded(parsed, name, min, max) {
+  const value2 = integer(parsed, name);
+  if (value2 === void 0) return void 0;
+  if (value2 < min || value2 > max)
+    throw new UsageError(`--${name} must be between ${min} and ${max}`);
+  return value2;
+}
+function executionWaitOptions(parsed) {
+  return {
+    executionId: parsed.positionals[0],
+    timeoutSeconds: bounded(parsed, "timeout", 0, MAX_WAIT_TIMEOUT_SECONDS),
+    intervalSeconds: bounded(parsed, "interval", 1, MAX_WAIT_INTERVAL_SECONDS)
+  };
+}
+function given(value2, name) {
+  if (value2 === void 0) return void 0;
+  if (value2 === "") throw new UsageError(`${name} must not be empty`);
+  return value2;
+}
+function insightPullOptions(parsed) {
+  const options = {};
+  const insightId = given(parsed.positionals[0], "<insight-id>");
+  if (insightId) options.insightId = insightId;
+  const workflowId = given(flag(parsed, "workflow-id"), "--workflow-id");
+  if (workflowId) options.workflowId = workflowId;
+  const dir = given(flag(parsed, "dir"), "--dir");
+  if (dir) options.dir = dir;
+  return options;
+}
 function executionOptions(parsed) {
   const summaryOnly = flag(parsed, "summary-only") === "true";
   const glob = flag(parsed, "files");
@@ -7732,6 +8075,20 @@ async function execute(command, parsed, sync, deps) {
     );
     return { result: result2, text: formatWorkflowPush(result2) };
   }
+  if (command.command === "execution wait") {
+    const result2 = await waitForExecution(sync, {
+      ...executionWaitOptions(parsed),
+      ...deps.executionWait
+    });
+    return { result: result2, text: formatExecutionWait(result2) };
+  }
+  if (command.command === "insight pull") {
+    const result2 = await pullInsights(sync, {
+      ...deps.insightPull,
+      ...insightPullOptions(parsed)
+    });
+    return { result: result2, text: formatInsightPull(result2) };
+  }
   if (command.command !== "execution pull")
     throw new UsageError(`unknown command ${command.command}`);
   const result = await pullExecution(sync, {
@@ -7754,15 +8111,20 @@ async function runSync(command, parsed, deps) {
 export {
   ALL_COMMANDS,
   COMMANDS,
+  INSIGHTS_DIR,
   MANIFEST,
   SYNC_COMMANDS,
   UsageError,
   buildRequest,
   formatActivitiesMarkdown,
   formatExecutionPull,
+  formatExecutionWait,
+  formatInsightPull,
   formatWorkflowPull,
   formatWorkflowPush,
   headFilesRequest,
+  insightFileId,
+  isTerminalExecutionStatus,
   leadingWords,
   loadManifest,
   matchCommand,
@@ -7770,12 +8132,15 @@ export {
   parseInvocation,
   pullDir,
   pullExecution,
+  pullInsights,
   pullWorkflow,
   pushWorkflow,
   readManifest,
   render,
   runSync,
   runsLocally,
+  serializeInsightFile,
+  waitForExecution,
   withSyncCommands,
   writeManifest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteroidai/cli",
-  "version": "1.9.111",
+  "version": "1.9.122",
   "description": "The asteroid command-line interface for the Asteroid platform.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,8 @@
     "cli-table3": "^0.6.5",
     "commander": "^15.0.0",
     "env-paths": "^4.0.0",
-    "proper-lockfile": "^4.1.2"
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
@@ -33,7 +34,6 @@
     "tsx": "^4.23.12",
     "typescript": "5.9.3",
     "vitest": "^4.1.11",
-    "yaml": "^2.9.0",
     "@asteroid/workflow-files": "0.1.0"
   },
   "scripts": {