@mmerterden/multi-agent-pipeline 20.29.0 → 20.33.0

package/pipeline/scripts/service-read.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * @file service-read.mjs  -  read one thing from Confluence, Crashlytics or
+ * Figma through the clients the pipeline already ships, for a client that
+ * shows it next to a run:
+ *
+ *   confluence <page>        lib/fetch-confluence.sh: a page by id or by https
+ *                            URL, both only on the configured
+ *                            prefs.global.hosts.confluence; a URL on any other
+ *                            host, or any URL when no host is configured, is
+ *                            refused before the script runs; title, markdown
+ *                            body, API contracts count
+ *   crashlytics <issue-url>  lib/fetch-crashlytics.sh: one Crashlytics issue,
+ *                            title, occurrences, impacted users, top frames
+ *   figma <file-key> <node>  lib/figma-screenshot.sh (REST with the Figma
+ *                            token, tier 2): one PNG render of a frame. The
+ *                            Figma MCP is never called here; the pipeline
+ *                            keeps MCP access to the analysis phase.
+ *
+ * Search across Confluence, a per-version Crashlytics trend and a Figma file
+ * browser have no client in the pipeline, so none is offered; a client asks
+ * an agent instead.
+ *
+ * The scripts run as child processes without blocking the caller's event
+ * loop (contract-server.mjs serves other routes meanwhile).
+ *
+ * Credentials are read only by those scripts, through credential-store.sh.
+ * Every text that comes back is scrubbed and redacted; an image comes back as
+ * base64.
+ *
+ * Usage:
+ *   service-read.mjs confluence <page-id|https-url>
+ *   service-read.mjs crashlytics <https-issue-url>
+ *   service-read.mjs figma <file-key> <node-id>
+ *
+ * MA_FETCH_CONFLUENCE, MA_FETCH_CRASHLYTICS and MA_FIGMA_SCREENSHOT stand in
+ * for the scripts (tests).
+ *
+ * Exit: 0 printed, 1 refused or failed, 2 usage.
+ *
+ * @module pipeline/scripts/service-read
+ */
+
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRedactor } from "./transcript-index.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TIMEOUT_MS = 90_000;
+const MAX_TEXT = 100_000;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+export const PAGE_ID = /^[0-9]{1,20}$/;
+export const FIGMA_KEY = /^[A-Za-z0-9]{10,64}$/;
+export const FIGMA_NODE = /^[0-9]{1,10}[:-][0-9]{1,10}$/;
+
+export class ServiceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const script = (env, name, override) =>
+  env[override] ||
+  [join(HERE, "..", "lib", name), join(HERE, "..", "..", "lib", name)].find((p) => existsSync(p));
+
+function httpsUrl(v, host = null) {
+  if (typeof v !== "string" || v.length > 2048) return null;
+  let u;
+  try {
+    u = new URL(v);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" || u.username || u.password) return null;
+  if (host && u.hostname !== host) return null;
+  return u.toString();
+}
+
+async function run(env, file, args, failCodes) {
+  if (!file) throw new ServiceError("not-installed", "the service client is not installed");
+  const r = await spawnAsync("bash", [file, ...args], { env, timeoutMs: TIMEOUT_MS });
+  if (r.status !== 0) {
+    const why = failCodes[r.status] ?? "the service could not be read";
+    throw new ServiceError("service-failed", why);
+  }
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    throw new ServiceError(
+      "service-failed",
+      "the service answered with something that is not JSON",
+    );
+  }
+}
+
+function confluenceHost(env) {
+  try {
+    const prefs = JSON.parse(
+      readFileSync(
+        env.MULTI_AGENT_PREFS ||
+          join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json"),
+        "utf8",
+      ),
+    );
+    const h = prefs?.global?.hosts?.confluence;
+    return typeof h === "string" && h ? h.replace(/^https?:\/\//, "").replace(/\/.*$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One Confluence page, by id or by a URL on the configured host only. */
+export async function confluencePage(page, env = process.env) {
+  let args;
+  const host = confluenceHost(env);
+  if (PAGE_ID.test(String(page))) {
+    if (!host) throw new ServiceError("not-configured", "no Confluence host is configured");
+    args = ["--host", host, "--page-id", String(page)];
+  } else {
+    const url = httpsUrl(page);
+    if (!url) throw new ServiceError("bad-input", "a page id or an https URL is required");
+    if (!host) {
+      throw new ServiceError(
+        "host-not-allowed",
+        "no Confluence host is configured, so only a page id is accepted",
+      );
+    }
+    if (new URL(url).hostname !== host) {
+      throw new ServiceError("host-not-allowed", "that host is not the configured Confluence host");
+    }
+    args = [url];
+  }
+  const d = await run(env, script(env, "fetch-confluence.sh", "MA_FETCH_CONFLUENCE"), args, {
+    2: "the Confluence credential is missing or was refused",
+    3: "Confluence could not be reached",
+    6: "that host is not the configured Confluence host",
+  });
+  const R = createRedactor();
+  return {
+    contractVersion: CONTRACT_VERSION,
+    service: "confluence",
+    pageId: d?.source?.pageId ? String(d.source.pageId) : null,
+    title: R.excerpt(d?.title ?? "", 300),
+    body: R.clean(String(d?.bodyMarkdown ?? "").slice(0, MAX_TEXT)),
+    apiContracts: Array.isArray(d?.apiContracts) ? d.apiContracts.length : 0,
+  };
+}
+
+/** One Crashlytics issue. */
+export async function crashlyticsIssue(issueUrl, env = process.env) {
+  const url = httpsUrl(issueUrl, "console.firebase.google.com");
+  if (!url) throw new ServiceError("bad-input", "a Firebase console issue URL is required");
+  const d = await run(env, script(env, "fetch-crashlytics.sh", "MA_FETCH_CRASHLYTICS"), [url], {
+    2: "the Firebase credential is missing or was refused",
+    3: "Crashlytics could not be reached",
+  });
+  const R = createRedactor();
+  const i = d?.issue ?? {};
+  return {
+    contractVersion: CONTRACT_VERSION,
+    service: "crashlytics",
+    title: R.excerpt(i.title ?? "", 300),
+    type: i.type ? String(i.type) : null,
+    occurrences: Number.isFinite(i.occurrences) ? i.occurrences : null,
+    impactedUsers: Number.isFinite(i.impactedUsers) ? i.impactedUsers : null,
+    stackTrace: (Array.isArray(i.stackTrace) ? i.stackTrace : [])
+      .slice(0, 40)
+      .map((f) => R.excerpt(typeof f === "string" ? f : JSON.stringify(f), 300)),
+  };
+}
+
+/** One frame rendered as PNG. */
+export async function figmaFrame(fileKey, nodeId, env = process.env) {
+  if (!FIGMA_KEY.test(String(fileKey)) || !FIGMA_NODE.test(String(nodeId))) {
+    throw new ServiceError("bad-input", "a Figma file key and a node id (1:2) are required");
+  }
+  const out = mkdtempSync(join(tmpdir(), "ma-figma-"));
+  try {
+    const file = script(env, "figma-screenshot.sh", "MA_FIGMA_SCREENSHOT");
+    if (!file) throw new ServiceError("not-installed", "the service client is not installed");
+    const r = await spawnAsync(
+      "bash",
+      [file, "--file-key", fileKey, "--node-id", nodeId.replace("-", ":"), "--output-dir", out],
+      { env, timeoutMs: TIMEOUT_MS, maxBytes: 1024 * 1024 },
+    );
+    const why = {
+      2: "the Figma token is missing or was refused",
+      4: "no such frame",
+      5: "Figma is rate limiting; try again later",
+      6: "Figma could not be reached",
+    };
+    if (r.status !== 0)
+      throw new ServiceError("service-failed", why[r.status] ?? "the frame could not be rendered");
+    const png = readdirSync(out).find((f) => f.endsWith(".png"));
+    if (!png || statSync(join(out, png)).size > MAX_IMAGE_BYTES) {
+      throw new ServiceError("service-failed", "the frame could not be rendered");
+    }
+    return {
+      contractVersion: CONTRACT_VERSION,
+      service: "figma",
+      fileKey,
+      nodeId: nodeId.replace("-", ":"),
+      mime: "image/png",
+      data: readFileSync(join(out, png)).toString("base64"),
+    };
+  } finally {
+    rmSync(out, { recursive: true, force: true });
+  }
+}
+
+async function main(argv) {
+  const [svc, a, b, ...rest] = argv;
+  try {
+    let out;
+    if (svc === "confluence" && a && !b) out = await confluencePage(a);
+    else if (svc === "crashlytics" && a && !b) out = await crashlyticsIssue(a);
+    else if (svc === "figma" && a && b && !rest.length) out = await figmaFrame(a, b);
+    else {
+      process.stderr.write(
+        "usage: service-read.mjs confluence <page> | crashlytics <issue-url> | figma <file-key> <node-id>\n",
+      );
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return 0;
+  } catch (err) {
+    if (!(err instanceof ServiceError)) throw err;
+    process.stderr.write(`service-read: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("service-read", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/stack-toggle.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * @file stack-toggle.mjs  -  read and set which stack plugins a repository
+ * enables, the one writer of `.claude/settings.json` `enabledPlugins` for
+ * `/multi-agent:stack` and the office panel (POST /v1/stack).
+ *
+ * The write rules, applied to the repository's settings file and nothing else:
+ *
+ *   - every plugin `pluginsForStacks()` (scripts/_stack-routing.mjs) derives for
+ *     the selection is set to true;
+ *   - every other stack toolkit of the marketplace is set to false;
+ *   - ai-common-toolkit and ai-analyst-toolkit are always true;
+ *   - retired `ai-*-engineering-toolkit` keys are deleted;
+ *   - `xcode-integration@xcode-apple` follows `ios`, only when the installer
+ *     linked Apple's marketplace (`~/.claude/xcode-apple-marketplace`);
+ *   - every key outside the marketplace and every other setting is kept as it
+ *     was.
+ *
+ * An empty selection is refused rather than written: it would turn every stack
+ * toolkit off, which nobody asks for by selecting nothing. The file is written
+ * atomically (a temporary file renamed over it), keeping its mode.
+ *
+ * Usage:
+ *   stack-toggle.mjs status --repo <path> [--json]
+ *   stack-toggle.mjs set --repo <path> <stack>... [--json] [--dry-run]
+ *
+ * Exit: 0 done, 1 refused (unknown stack, empty selection, unreadable
+ * settings), 2 usage.
+ *
+ * @module pipeline/scripts/stack-toggle
+ */
+
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import {
+  ALWAYS_ON,
+  KNOWN_STACKS,
+  STACK_PLUGIN_ALIAS,
+  expandStackArg,
+  pluginsForStacks,
+} from "./_stack-routing.mjs";
+import { PLUGIN_MARKETPLACE, pluginSkillRootCandidates } from "../lib/plugin-skill-roots.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const SUFFIX = `@${PLUGIN_MARKETPLACE}`;
+const XCODE_KEY = "xcode-integration@xcode-apple";
+const RETIRED = /^ai-[a-z]+-engineering-toolkit@multi-agent-plugins$/;
+
+export class StackError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const home = (env) => env.HOME || homedir();
+const stackPlugin = (s) => `ai-${STACK_PLUGIN_ALIAS[s] ?? s}-toolkit`;
+
+/** The repository's settings file. */
+export function settingsPath(repo) {
+  return join(repo, ".claude", "settings.json");
+}
+
+function readSettings(repo) {
+  const p = settingsPath(repo);
+  if (!existsSync(p)) return {};
+  try {
+    const doc = JSON.parse(readFileSync(p, "utf8"));
+    if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw new Error("not an object");
+    return doc;
+  } catch (err) {
+    throw new StackError(
+      "unreadable-settings",
+      `the repository's .claude/settings.json is not valid JSON (${err.message})`,
+    );
+  }
+}
+
+function marketplaceNames(env) {
+  const path = join(
+    home(env),
+    ".claude",
+    "plugins",
+    "marketplaces",
+    PLUGIN_MARKETPLACE,
+    ".claude-plugin",
+    "marketplace.json",
+  );
+  try {
+    return (JSON.parse(readFileSync(path, "utf8")).plugins || [])
+      .map((p) => p.name)
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+/** The skill names a plugin ships, from its best local root. */
+function skillsOf(plugin, env) {
+  // Marketplace checkout first, then the plugin cache, newest version first.
+  const marketplaceCopy = join(
+    home(env),
+    ".claude",
+    "plugins",
+    "marketplaces",
+    PLUGIN_MARKETPLACE,
+    "plugins",
+    plugin,
+    "skills",
+  );
+  for (const root of [marketplaceCopy, ...pluginSkillRootCandidates(home(env), [plugin])]) {
+    try {
+      return readdirSync(root)
+        .filter((d) => existsSync(join(root, d, "SKILL.md")))
+        .sort();
+    } catch {
+      // The next root may be readable.
+    }
+  }
+  return [];
+}
+
+/**
+ * The repository's current state: which stacks are on, every marketplace
+ * plugin with its enablement and skills.
+ *
+ * @param {string} repo  absolute path
+ */
+export function stackStatus(repo, env = process.env) {
+  if (!isAbsolute(repo)) throw new StackError("bad-repo", "the repository path must be absolute");
+  const enabled = readSettings(repo).enabledPlugins ?? {};
+  const names = marketplaceNames(env) ?? [...ALWAYS_ON, ...KNOWN_STACKS.map(stackPlugin)];
+  const plugins = names.map((name) => ({
+    name,
+    enabled: enabled[`${name}${SUFFIX}`] === true,
+    alwaysOn: ALWAYS_ON.includes(name),
+    stack: KNOWN_STACKS.find((s) => stackPlugin(s) === name) ?? null,
+    skills: skillsOf(name, env),
+  }));
+  return {
+    contractVersion: CONTRACT_VERSION,
+    stacks: KNOWN_STACKS.filter((s) => enabled[`${stackPlugin(s)}${SUFFIX}`] === true),
+    knownStacks: KNOWN_STACKS,
+    plugins,
+    manifestVerified: marketplaceNames(env) !== null,
+  };
+}
+
+/**
+ * The enabledPlugins block the write rules give for a selection.
+ *
+ * @param {object} current  the current enabledPlugins
+ * @param {string[]} args  stack arguments as a user types them (aliases allowed)
+ */
+export function plannedPlugins(current, args, env = process.env) {
+  const stacks = [...new Set(args.flatMap((a) => expandStackArg(a)))];
+  const unknown = args.filter((a) => !expandStackArg(a).length);
+  if (unknown.length) {
+    throw new StackError(
+      "unknown-stack",
+      `unknown stack ${unknown.join(", ")}; one of ${KNOWN_STACKS.join(" ")} mobile fullstack all`,
+    );
+  }
+  if (!stacks.length) {
+    throw new StackError("empty-selection", "no stack selected; nothing is changed");
+  }
+  const { plugins, dropped } = pluginsForStacks(stacks, {
+    manifestPath: join(
+      home(env),
+      ".claude",
+      "plugins",
+      "marketplaces",
+      PLUGIN_MARKETPLACE,
+      ".claude-plugin",
+      "marketplace.json",
+    ),
+  });
+  const next = {};
+  for (const [k, v] of Object.entries(current ?? {})) if (!RETIRED.test(k)) next[k] = v;
+  for (const s of KNOWN_STACKS) next[`${stackPlugin(s)}${SUFFIX}`] = false;
+  for (const p of plugins) next[`${p}${SUFFIX}`] = true;
+  for (const p of ALWAYS_ON) next[`${p}${SUFFIX}`] = true;
+  if (existsSync(join(home(env), ".claude", "xcode-apple-marketplace"))) {
+    next[XCODE_KEY] = stacks.includes("ios");
+  }
+  return { stacks, enabledPlugins: next, dropped };
+}
+
+/**
+ * Apply a selection to the repository's settings file.
+ *
+ * @returns {{contractVersion: string, stacks: string[], enabledPlugins: object,
+ *   changed: string[], dropped: string[], written: boolean}}
+ */
+export function stackSet(repo, args, { env = process.env, dryRun = false } = {}) {
+  if (!isAbsolute(repo)) throw new StackError("bad-repo", "the repository path must be absolute");
+  const doc = readSettings(repo);
+  const before = doc.enabledPlugins ?? {};
+  const plan = plannedPlugins(before, args, env);
+  const keys = new Set([...Object.keys(before), ...Object.keys(plan.enabledPlugins)]);
+  const changed = [...keys].filter((k) => before[k] !== plan.enabledPlugins[k]).sort();
+  if (!dryRun && changed.length) {
+    const p = settingsPath(repo);
+    mkdirSync(join(repo, ".claude"), { recursive: true });
+    const mode = existsSync(p) ? statSync(p).mode & 0o777 : 0o644;
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(
+      tmp,
+      JSON.stringify({ ...doc, enabledPlugins: plan.enabledPlugins }, null, 2) + "\n",
+    );
+    chmodSync(tmp, mode);
+    renameSync(tmp, p);
+  }
+  return {
+    contractVersion: CONTRACT_VERSION,
+    stacks: plan.stacks,
+    enabledPlugins: plan.enabledPlugins,
+    changed,
+    dropped: plan.dropped,
+    written: !dryRun && changed.length > 0,
+  };
+}
+
+function main(argv) {
+  const [mode, ...rest] = argv;
+  let repo = null;
+  let json = false;
+  let dryRun = false;
+  const stacks = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--repo") repo = rest[++i];
+    else if (rest[i] === "--json") json = true;
+    else if (rest[i] === "--dry-run") dryRun = true;
+    else if (rest[i].startsWith("--")) return usage(`unknown argument ${rest[i]}`);
+    else stacks.push(rest[i]);
+  }
+  repo ??= process.cwd();
+  if (mode !== "status" && mode !== "set") return usage();
+  if (mode === "status" && stacks.length) return usage("status takes no stacks");
+  try {
+    const out = mode === "status" ? stackStatus(repo) : stackSet(repo, stacks, { dryRun });
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    else if (mode === "status") {
+      process.stdout.write(`stacks: ${out.stacks.join(" ") || "(none)"}\n`);
+      for (const p of out.plugins)
+        process.stdout.write(`  ${p.enabled ? "on " : "off"} ${p.name}\n`);
+    } else {
+      for (const d of out.dropped) process.stderr.write(`not in the marketplace, dropped: ${d}\n`);
+      process.stdout.write(JSON.stringify({ enabledPlugins: out.enabledPlugins }, null, 2) + "\n");
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof StackError) {
+      process.stderr.write(`stack-toggle: ${err.message}\n`);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+function usage(why) {
+  if (why) process.stderr.write(`stack-toggle: ${why}\n`);
+  process.stderr.write(
+    "usage: stack-toggle.mjs status --repo <path> [--json] | set --repo <path> <stack>... [--json] [--dry-run]\n",
+  );
+  return 2;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("stack-toggle", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/steer-run.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * @file steer-run.mjs  -  queue one instruction for a running task, the writer
+ * behind `/multi-agent:steer` step 5 and POST /v1/runs/{id}/steer.
+ *
+ * The instruction is stored as `pendingSteer` in the run's agent-state.json
+ * through the state lock (gate-ledger.mjs updateState), never by editing the
+ * file, because the running task writes it too. The next phase reads it at its
+ * entry, applies it and sets `appliedAt` (multi-agent-refs/phases.md, "Phase
+ * entry - pending steer"). One instruction is queued at a time: a new one
+ * replaces an unconsumed one, and the replaced text is returned so the caller
+ * can show what was dropped.
+ *
+ * A finished run is refused: nothing would read the instruction.
+ *
+ * Usage:
+ *   steer-run.mjs <agent-state.json> --text <instruction>
+ *   steer-run.mjs <agent-state.json> --text-file <path>
+ *
+ * Stdout: one JSON line {contractVersion, queuedAt, replaced, status, currentPhase}.
+ * Exit: 0 queued, 1 refused, 2 usage.
+ *
+ * @module pipeline/scripts/steer-run
+ */
+
+import { readFileSync } from "node:fs";
+import { updateState } from "./gate-ledger.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const MAX_STEER_CHARS = 4000;
+const FINISHED = new Set(["complete", "completed", "done"]);
+
+export class SteerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/**
+ * Queue `text` on the run whose state file is `stateFile`.
+ *
+ * @returns {Promise<{contractVersion: string, queuedAt: string, replaced: string|null,
+ *   status: string|null, currentPhase: number|null}>}
+ */
+export async function queueSteer(stateFile, text) {
+  if (typeof text !== "string" || !text.trim()) {
+    throw new SteerError("empty", "the instruction is empty");
+  }
+  if (text.length > MAX_STEER_CHARS) {
+    throw new SteerError("too-long", `the instruction is over ${MAX_STEER_CHARS} characters`);
+  }
+  const queuedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  let replaced = null;
+  let status = null;
+  let currentPhase = null;
+  await updateState(stateFile, (s) => {
+    status = typeof s.status === "string" ? s.status : null;
+    currentPhase = Number.isFinite(Number(s.currentPhase)) ? Number(s.currentPhase) : null;
+    if (FINISHED.has(status)) {
+      throw new SteerError("finished", "the run is finished; nothing would read the instruction");
+    }
+    const prev = s.pendingSteer;
+    if (prev && typeof prev === "object" && !prev.appliedAt && typeof prev.text === "string") {
+      replaced = prev.text;
+    }
+    return { ...s, pendingSteer: { text, at: queuedAt, appliedAt: null, appliedPhase: null } };
+  });
+  return { contractVersion: CONTRACT_VERSION, queuedAt, replaced, status, currentPhase };
+}
+
+async function main(argv) {
+  const [file, flag, value, ...rest] = argv;
+  if (!file || rest.length || !value || (flag !== "--text" && flag !== "--text-file")) {
+    process.stderr.write(
+      "usage: steer-run.mjs <agent-state.json> --text <instruction> | --text-file <path>\n",
+    );
+    return 2;
+  }
+  const text = flag === "--text" ? value : readFileSync(value, "utf8");
+  try {
+    process.stdout.write(`${JSON.stringify(await queueSteer(file, text))}\n`);
+    return 0;
+  } catch (err) {
+    if (!(err instanceof SteerError) && err?.code !== "no-state") throw err;
+    process.stderr.write(`steer-run: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("steer-run", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}