@operator-labs/operator-cli 0.1.0

package/lib/setup.mjs

@@ -0,0 +1,197 @@
+import { existsSync, mkdirSync, symlinkSync, readlinkSync, writeFileSync } from "fs";
+import { randomBytes } from "crypto";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { resolveConfigPath, resolveStateDir, readConfig, resolveGatewayToken, checkConfigWarnings } from "./config.mjs";
+import { detectInstalledAgents } from "./backend.mjs";
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function linkSkill(skillsDir, dryRun, changes) {
+  const skillLink = join(skillsDir, "operator");
+  if (existsSync(skillLink)) {
+    let target;
+    try { target = readlinkSync(skillLink); } catch {}
+    if (target === PACKAGE_ROOT) {
+      console.log("  skill: linked");
+    } else {
+      console.log("  skill: " + skillLink + " exists (not managed by setup)");
+    }
+    return;
+  }
+  if (dryRun) {
+    changes.push("skill: link " + skillLink);
+    console.log("  skill: would link " + skillLink + " → " + PACKAGE_ROOT);
+    return;
+  }
+  mkdirSync(skillsDir, { recursive: true });
+  symlinkSync(PACKAGE_ROOT, skillLink);
+  changes.push("skill: linked " + skillLink);
+  console.log("  skill: linked " + skillLink + " → " + PACKAGE_ROOT);
+}
+
+function linkNodeModules(stateDir, dryRun, changes) {
+  const nmScopeDir = join(stateDir, "node_modules", "@operator-labs");
+  const nmLink = join(nmScopeDir, "operator-cli");
+  if (existsSync(nmLink)) {
+    let target;
+    try { target = readlinkSync(nmLink); } catch {}
+    if (target === PACKAGE_ROOT) {
+      console.log("  node_modules: linked");
+    } else {
+      console.log("  node_modules: " + nmLink + " exists (not managed by setup)");
+    }
+    return;
+  }
+  if (dryRun) {
+    changes.push("node_modules: link " + nmLink);
+    console.log("  node_modules: would link " + nmLink + " → " + PACKAGE_ROOT);
+    return;
+  }
+  mkdirSync(nmScopeDir, { recursive: true });
+  symlinkSync(PACKAGE_ROOT, nmLink);
+  changes.push("node_modules: linked " + nmLink);
+  console.log("  node_modules: linked " + nmLink + " → " + PACKAGE_ROOT);
+}
+
+async function setupOpenclaw(options, changes, warnings) {
+  const { dryRun = false, configPath: configOverride } = options;
+  const configPath = resolveConfigPath(configOverride);
+
+  const configExists = existsSync(configPath);
+  let config = configExists ? readConfig(configPath) : {};
+
+  if (configExists && config === null) {
+    console.error("error: could not parse config at " + configPath);
+    console.error("  If it uses advanced JSON5 syntax, run these commands manually:");
+    console.error("");
+    console.error('  openclaw config set hooks.enabled true --strict-json');
+    console.error('  openclaw config set hooks.token "$(openssl rand -hex 32)"');
+    console.error('  openclaw config set plugins.entries.llm-task.enabled true --strict-json');
+    return { ok: false, configPath };
+  }
+
+  if (!config) config = {};
+
+  for (const w of checkConfigWarnings(config)) {
+    warnings.push(w);
+    console.log("  warning: " + w);
+  }
+
+  console.log("  config: " + configPath);
+
+  if (!config.hooks || typeof config.hooks !== "object") config.hooks = {};
+  if (config.hooks.enabled === true) {
+    console.log("  hooks.enabled: true (already set)");
+  } else {
+    config.hooks.enabled = true;
+    changes.push("hooks.enabled: set to true");
+    console.log("  hooks.enabled: set to true");
+  }
+
+  if (config.hooks.token) {
+    console.log("  hooks.token: exists");
+  } else {
+    config.hooks.token = randomBytes(32).toString("hex");
+    changes.push("hooks.token: generated");
+    console.log("  hooks.token: generated");
+  }
+
+  if (!Array.isArray(config.hooks.mappings)) config.hooks.mappings = [];
+  const hasMapping = config.hooks.mappings.some(
+    (m) => m.id === "operator" || m.match?.path === "operator",
+  );
+  if (hasMapping) {
+    console.log("  hooks.mappings: operator mapping exists");
+  } else {
+    config.hooks.mappings.push({
+      id: "operator",
+      match: { path: "operator" },
+      action: "agent",
+      messageTemplate: "{{message}}",
+    });
+    changes.push("hooks.mappings: added operator mapping");
+    console.log("  hooks.mappings: added operator mapping");
+  }
+
+  if (!config.plugins || typeof config.plugins !== "object") config.plugins = {};
+  if (!config.plugins.entries || typeof config.plugins.entries !== "object") {
+    config.plugins.entries = {};
+  }
+  const llm = config.plugins.entries["llm-task"];
+  if (llm?.enabled === true) {
+    console.log("  llm-task plugin: enabled");
+  } else {
+    if (!llm) {
+      config.plugins.entries["llm-task"] = { enabled: true };
+    } else {
+      llm.enabled = true;
+    }
+    changes.push("llm-task plugin: enabled");
+    console.log("  llm-task plugin: enabled");
+  }
+
+  if (!config.tools || typeof config.tools !== "object") config.tools = {};
+  if (!Array.isArray(config.tools.allow)) config.tools.allow = [];
+  if (config.tools.allow.includes("llm-task")) {
+    console.log("  tools.allow: llm-task present");
+  } else {
+    config.tools.allow.push("llm-task");
+    changes.push("tools.allow: added llm-task");
+    console.log("  tools.allow: added llm-task");
+  }
+
+  const gatewayToken = resolveGatewayToken(config);
+  if (gatewayToken) {
+    console.log("  gateway.auth.token: found");
+  } else {
+    warnings.push("gateway.auth.token: not found");
+    console.log("  gateway.auth.token: not found");
+    console.log("    Set gateway.auth.token in your config or export OPENCLAW_GATEWAY_TOKEN");
+    console.log("    Required for 'operator think'. Run 'openclaw setup' if not yet configured.");
+  }
+
+  linkSkill(join(resolveStateDir(), "skills"), dryRun, changes);
+  linkNodeModules(resolveStateDir(), dryRun, changes);
+
+  if (!dryRun && changes.length > 0) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+    const verb = configExists ? "updated" : "created";
+    console.log("  " + verb + " " + configPath);
+  }
+
+  return { ok: true, configPath };
+}
+
+/**
+ * Configure OpenClaw for operator workflows.
+ * Non-interactive, idempotent. Safe to run multiple times.
+ */
+export async function setup(options = {}) {
+  const { dryRun = false } = options;
+  const changes = [];
+  const warnings = [];
+
+  const agents = detectInstalledAgents();
+
+  if (agents.length === 0) {
+    console.error("error: OpenClaw not detected");
+    console.error("  Install OpenClaw first.");
+    return { ok: false, agents: [], changes, warnings };
+  }
+
+  console.log("[openclaw]");
+  const result = await setupOpenclaw(options, changes, warnings);
+  if (!result.ok) return { ok: false, agents, changes, warnings };
+
+  if (changes.length === 0) {
+    console.log("\nready (no changes needed)");
+  } else if (dryRun) {
+    console.log("\ndry run: " + changes.length + " change(s) not written");
+  } else {
+    console.log("\n" + changes.length + " change(s) applied");
+  }
+
+  return { ok: true, agents, changes, warnings };
+}

package/lib/think.mjs

@@ -0,0 +1,18 @@
+import { resolveBackend } from "./backend.mjs";
+
+/**
+ * Run a lightweight LLM call via the active backend.
+ *
+ * Synchronous request/response -- returns when the LLM responds (unlike
+ * invoke, which returns before the agent finishes).
+ *
+ * @param {string} prompt - Plain string or JSON with backend-specific args
+ * @param {object} [options]
+ * @param {number} [options.timeout=120000] - Request timeout in ms
+ * @param {string} [options.configPath] - Override config path (OpenClaw only)
+ * @returns {{ ok: boolean, output?: unknown, error?: string }}
+ */
+export async function think(prompt, options = {}) {
+  const backend = await resolveBackend();
+  return backend.think(prompt, options);
+}

package/lib/workflows.mjs

@@ -0,0 +1,178 @@
+import { get as httpsGet } from "https";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { detectInstalledAgents } from "./backend.mjs";
+import { resolveStateDir } from "./config.mjs";
+
+const DEFAULT_REPO = "operatorlabs/operator-mono";
+const DEFAULT_BRANCH = "main";
+const WORKFLOWS_DIR = "workflows";
+
+function getRepo() {
+  return process.env.OPERATOR_REPO || DEFAULT_REPO;
+}
+
+function getBranch() {
+  return process.env.OPERATOR_BRANCH || DEFAULT_BRANCH;
+}
+
+function ghApi(path) {
+  return new Promise((resolve, reject) => {
+    const url = `https://api.github.com${path}`;
+    const headers = { "User-Agent": "operator-cli", Accept: "application/vnd.github.v3+json" };
+    if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+    httpsGet(url, { headers }, (res) => {
+      let body = "";
+      res.on("data", (chunk) => (body += chunk));
+      res.on("end", () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            resolve(JSON.parse(body));
+          } catch {
+            reject(new Error("invalid JSON from GitHub API"));
+          }
+        } else {
+          reject(new Error(`GitHub API ${res.statusCode}: ${body.slice(0, 200)}`));
+        }
+      });
+    }).on("error", reject);
+  });
+}
+
+function ghRaw(filePath) {
+  return new Promise((resolve, reject) => {
+    const url = `https://raw.githubusercontent.com/${getRepo()}/${getBranch()}/${filePath}`;
+    httpsGet(url, { headers: { "User-Agent": "operator-cli" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        httpsGet(res.headers.location, { headers: { "User-Agent": "operator-cli" } }, (r2) => {
+          let body = "";
+          r2.on("data", (chunk) => (body += chunk));
+          r2.on("end", () => (r2.statusCode < 300 ? resolve(body) : reject(new Error(`raw ${r2.statusCode} for ${filePath}`))));
+        }).on("error", reject);
+        return;
+      }
+      let body = "";
+      res.on("data", (chunk) => (body += chunk));
+      res.on("end", () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) resolve(body);
+        else reject(new Error(`raw ${res.statusCode} for ${filePath}`));
+      });
+    }).on("error", reject);
+  });
+}
+
+/**
+ * List available workflows from the monorepo's workflows/ directory.
+ * Fetches each SKILL.md for description and full content (used by search).
+ * @returns {Promise<Array<{ name: string, description: string, content: string }>>}
+ */
+export async function listWorkflows() {
+  const entries = await ghApi(`/repos/${getRepo()}/contents/${WORKFLOWS_DIR}?ref=${getBranch()}`);
+  const dirs = entries.filter((e) => e.type === "dir");
+
+  const workflows = await Promise.all(dirs.map(async (dir) => {
+    let description = "";
+    let content = "";
+    try {
+      content = await ghRaw(`${WORKFLOWS_DIR}/${dir.name}/SKILL.md`);
+      const match = content.match(/^description:\s*(.+)/m);
+      if (match) {
+        description = match[1].trim();
+      } else {
+        for (const line of content.split("\n")) {
+          const t = line.trim();
+          if (t && !t.startsWith("#") && !t.startsWith("---")) {
+            description = t;
+            break;
+          }
+        }
+      }
+    } catch {}
+    return { name: dir.name, description, content };
+  }));
+
+  return workflows;
+}
+
+/**
+ * Search workflows by keyword. Matches against name, description,
+ * and full SKILL.md content.
+ */
+export async function searchWorkflows(query) {
+  const all = await listWorkflows();
+  const q = query.toLowerCase();
+  return all
+    .map((w) => {
+      const nameMatch = w.name.toLowerCase().includes(q);
+      const descMatch = w.description.toLowerCase().includes(q);
+      const contentMatch = w.content.toLowerCase().includes(q);
+      if (!nameMatch && !descMatch && !contentMatch) return null;
+      const score = (nameMatch ? 3 : 0) + (descMatch ? 2 : 0) + (contentMatch ? 1 : 0);
+      return { name: w.name, description: w.description, score };
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.score - a.score);
+}
+
+const SKILL_DIRS = {
+  openclaw: () => join(resolveStateDir(), "workspace", "skills"),
+};
+
+/**
+ * Install a workflow to all detected agent skill directories.
+ * Fetches files from the monorepo and writes them locally.
+ */
+export async function installWorkflow(name) {
+  let entries;
+  try {
+    entries = await ghApi(`/repos/${getRepo()}/contents/${WORKFLOWS_DIR}/${name}?ref=${getBranch()}`);
+  } catch (err) {
+    return { ok: false, error: `workflow "${name}" not found: ${err.message}` };
+  }
+
+  if (!Array.isArray(entries)) {
+    return { ok: false, error: `workflow "${name}" not found in ${WORKFLOWS_DIR}/` };
+  }
+
+  const files = entries.filter((e) => e.type === "file");
+  if (files.length === 0) {
+    return { ok: false, error: `workflow "${name}" has no files` };
+  }
+
+  const fileContents = [];
+  for (const file of files) {
+    try {
+      const content = await ghRaw(`${WORKFLOWS_DIR}/${name}/${file.name}`);
+      fileContents.push({ name: file.name, content });
+    } catch (err) {
+      return { ok: false, error: `failed to download ${file.name}: ${err.message}` };
+    }
+  }
+
+  const agents = detectInstalledAgents();
+  if (agents.length === 0) {
+    return { ok: false, error: "no agent hosts detected" };
+  }
+
+  const installed = [];
+  for (const agent of agents) {
+    const getDir = SKILL_DIRS[agent];
+    if (!getDir) continue;
+
+    const targetDir = join(getDir(), name);
+    mkdirSync(targetDir, { recursive: true });
+
+    for (const file of fileContents) {
+      writeFileSync(join(targetDir, file.name), file.content, "utf-8");
+    }
+
+    installed.push({ agent, dir: targetDir });
+    console.log("[" + agent + "] installed: " + targetDir);
+  }
+
+  const fileNames = fileContents.map((f) => f.name);
+  console.log("files: " + fileNames.join(", "));
+  console.log("status: available on next agent session");
+
+  return { ok: true, installed, files: fileNames };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@operator-labs/operator-cli",
+  "version": "0.1.0",
+  "description": "Self-calling workflow primitives for OpenClaw",
+  "type": "module",
+  "bin": {
+    "operator-cli": "./bin/operator.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "examples/",
+    "references/",
+    "index.mjs",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/operator"
+  }
+}

package/references/error-handling.md

@@ -0,0 +1,100 @@
+# Error Handling
+
+## Exit Codes
+
+Both `invoke.mjs` and `think.mjs` use the same exit code convention:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | No message/prompt provided |
+| 2 | Config error (missing token) |
+| 3 | Gateway or tool error |
+
+## Check Exit Codes
+
+`execFileSync` throws on non-zero exit. The `invoke` and `think` wrappers in SKILL.md catch and log these.
+
+## Verify Results
+
+Agent sessions can complete without producing expected output. Always check that files exist and have content after each invocation:
+
+```js
+function invoke(message, expectedOutput) {
+  try {
+    execFileSync("node", [INVOKE, message], { stdio: "inherit", timeout: 120000 });
+  } catch (e) {
+    log("INVOKE FAILED: " + e.message);
+    throw e;
+  }
+  if (expectedOutput && (!existsSync(expectedOutput) || readFileSync(expectedOutput, "utf-8").trim() === "")) {
+    log("WARNING: expected output missing: " + expectedOutput);
+  }
+}
+```
+
+## Retry with Backoff
+
+```js
+async function invokeWithRetry(message, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      execFileSync("node", [INVOKE, message], { stdio: "inherit", timeout: 120000 });
+      return;
+    } catch (e) {
+      if (i === retries - 1) throw e;
+      await new Promise(r => setTimeout(r, 5000 * (i + 1)));
+    }
+  }
+}
+```
+
+## Timeouts
+
+The `invoke.mjs` HTTP request has a 120-second timeout. This is how long it waits for the gateway to respond, not how long the agent session takes to complete its work. If the agent task takes longer than 120 seconds, the HTTP call may return or time out before the agent finishes writing its result file. For long-running tasks, do not treat a timeout as a failure. Poll for the expected result file instead:
+
+```js
+function invokeAndWait(message, expectedOutput, maxWaitMs = 600000) {
+  try {
+    execFileSync("node", [INVOKE, message], { stdio: "inherit", timeout: 120000 });
+  } catch {
+    // Timeout is not necessarily a failure; the session may still be running
+  }
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    if (existsSync(expectedOutput) && readFileSync(expectedOutput, "utf-8").trim() !== "") return true;
+    execFileSync("sleep", ["10"]);
+  }
+  return false;
+}
+```
+
+## Checkpoint and Resume
+
+Write progress after each successful step so a crashed workflow restarts from where it left off:
+
+```js
+for (let i = start; i < items.length; i++) {
+  processItem(items[i]);
+  writeFileSync(progressFile, String(i + 1));
+}
+```
+
+## Validate Data Between Steps
+
+In pipelines, verify output has the expected format before passing it forward:
+
+```js
+function validateJson(path) {
+  try {
+    JSON.parse(readFileSync(path, "utf-8"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+## Concurrency Throttling
+
+For fan-out patterns, limit concurrent invocations to avoid overwhelming the gateway. Each agent session allocates 150-200MB on the gateway heap. On a 2GB container, 2-3 concurrent sessions is the practical limit.

package/references/patterns.md

@@ -0,0 +1,144 @@
+# Workflow Patterns
+
+## 1. Batch
+
+Script enumerates items, invokes agent per item. Guarantees every item is processed.
+
+```js
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, execFileSync } from "fs";
+
+const WORK_DIR = process.env.HOME + "/.openclaw/workspace/workflows/sentry-triage";
+const LOG = WORK_DIR + "/logs/workflow.log";
+const INVOKE = process.env.HOME + "/.openclaw/skills/workflow-builder/scripts/invoke.mjs";
+
+for (const dir of ["input", "results", "state", "logs"]) {
+  mkdirSync(WORK_DIR + "/" + dir, { recursive: true });
+}
+
+function log(msg) { appendFileSync(LOG, "[" + new Date().toISOString() + "] " + msg + "\n"); }
+
+function invoke(message) {
+  execFileSync("node", [INVOKE, message], { stdio: "inherit", timeout: 120000 });
+}
+
+function analyzeIssue(issue, outputPath) {
+  invoke("Analyze this Sentry issue and write findings to " + outputPath + ": " + JSON.stringify(issue));
+}
+
+// Fetch items
+execFileSync("curl", ["-sf", "https://sentry.io/api/0/projects/org/proj/issues/",
+  "-H", "Authorization: Bearer " + process.env.SENTRY_TOKEN,
+  "-o", WORK_DIR + "/input/issues.json"]);
+const issues = JSON.parse(readFileSync(WORK_DIR + "/input/issues.json", "utf-8"));
+
+// Resume from checkpoint
+let start = 0;
+const progressFile = WORK_DIR + "/state/progress.txt";
+if (existsSync(progressFile)) start = parseInt(readFileSync(progressFile, "utf-8"), 10);
+
+for (let i = start; i < issues.length; i++) {
+  analyzeIssue(issues[i], WORK_DIR + "/results/issue-" + i + ".md");
+  writeFileSync(progressFile, String(i + 1));
+  log("issue " + i + ": done");
+}
+```
+
+## 2. Pipeline
+
+Script chains steps sequentially. Deterministic work (API calls, transforms) between agent invocations.
+
+```js
+import { mkdirSync, execFileSync } from "fs";
+
+const WORK_DIR = process.env.HOME + "/.openclaw/workspace/workflows/report-pipeline";
+const INVOKE = process.env.HOME + "/.openclaw/skills/workflow-builder/scripts/invoke.mjs";
+
+for (const dir of ["state", "results", "logs"]) {
+  mkdirSync(WORK_DIR + "/" + dir, { recursive: true });
+}
+
+function invoke(message) {
+  execFileSync("node", [INVOKE, message], { stdio: "inherit", timeout: 120000 });
+}
+
+function analyzeReport(input, output) {
+  invoke("Read " + input + " and write an analysis to " + output + ". Focus on anomalies and trends.");
+}
+
+function validateResponse(response, analysis, output) {
+  invoke("Review " + response + " against " + analysis + ". Write a summary to " + output);
+}
+
+// Step 1: Deterministic fetch
+execFileSync("curl", ["-sf", "https://api.example.com/report", "-o", WORK_DIR + "/state/raw-report.json"]);
+
+// Step 2: Agent analyzes
+analyzeReport(WORK_DIR + "/state/raw-report.json", WORK_DIR + "/state/analysis.md");
+
+// Step 3: Deterministic API call
+execFileSync("curl", ["-sf", "-X", "POST", "https://api.example.com/alerts",
+  "-d", "@" + WORK_DIR + "/state/analysis.md",
+  "-o", WORK_DIR + "/state/alert-response.json"]);
+
+// Step 4: Agent validates
+validateResponse(WORK_DIR + "/state/alert-response.json", WORK_DIR + "/state/analysis.md", WORK_DIR + "/results/summary.md");
+```
+
+## 3. Fan-out / Fan-in
+
+Dispatch N parallel agent sessions, wait for results, then synthesize.
+
+```js
+import { existsSync, readFileSync, mkdirSync, appendFileSync, execFile } from "fs";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+const WORK_DIR = process.env.HOME + "/.openclaw/workspace/workflows/competitor-research";
+const LOG = WORK_DIR + "/logs/workflow.log";
+const INVOKE = process.env.HOME + "/.openclaw/skills/workflow-builder/scripts/invoke.mjs";
+
+for (const dir of ["results", "logs"]) {
+  mkdirSync(WORK_DIR + "/" + dir, { recursive: true });
+}
+
+function log(msg) { appendFileSync(LOG, "[" + new Date().toISOString() + "] " + msg + "\n"); }
+
+async function invoke(message) {
+  await execFileAsync("node", [INVOKE, message], { timeout: 120000 });
+}
+
+async function research(topic, outputPath) {
+  await invoke("Research " + topic + " thoroughly. Write findings to " + outputPath);
+}
+
+async function synthesize(inputDir, outputPath) {
+  await invoke("Read all files in " + inputDir + " and write a comparative analysis to " + outputPath);
+}
+
+async function waitForFile(path, maxWaitMs = 600000) {
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    if (existsSync(path) && readFileSync(path, "utf-8").trim() !== "") return true;
+    await new Promise(r => setTimeout(r, 10000));
+  }
+  return false;
+}
+
+const topics = ["competitor-a", "competitor-b", "competitor-c"];
+
+for (const topic of topics) {
+  research(topic, WORK_DIR + "/results/" + topic + ".md")
+    .catch(e => log("FAILED: " + topic + " - " + e.message));
+  await new Promise(r => setTimeout(r, 2000));
+}
+
+for (const topic of topics) {
+  if (!await waitForFile(WORK_DIR + "/results/" + topic + ".md")) {
+    log("WARNING: no result for " + topic);
+  }
+}
+
+await synthesize(WORK_DIR + "/results", WORK_DIR + "/results/synthesis.md");
+```
+
+Fan-out is aggressive on memory. Each concurrent `invoke` spawns a 150-200MB agent session on the gateway. Limit concurrency to 2-3 on a 2GB container, or use `think` for steps that only need reasoning.