@operator-labs/operator-cli 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @operator-labs/operator-cli
+
+Self-calling workflow primitives for [OpenClaw](https://github.com/openclaw/openclaw). A Node.js script controls the flow; `invoke()` spawns agent sessions when intelligence is needed.
+
+## Install
+
+```bash
+npm install -g @operator-labs/operator-cli
+```
+
+## Setup
+
+```bash
+operator setup
+```
+
+Detects your `openclaw.json`, enables hooks, generates tokens, and enables the `llm-task` plugin. Safe to run multiple times. Use `--dry-run` to preview.
+
+```
+$ operator setup
+config: ~/.openclaw/openclaw.json
+hooks.enabled: true (already set)
+hooks.token: exists
+hooks.mappings: operator mapping exists
+llm-task plugin: enabled
+tools.allow: llm-task present
+gateway.auth.token: found
+
+ready (no changes needed)
+```
+
+## CLI
+
+```bash
+operator-cli setup                        # configure gateway
+operator-cli setup --dry-run              # preview changes
+operator-cli examples                     # list example workflows
+operator-cli examples batch-analyze       # view a specific example
+```
+
+## How it works
+
+```js
+import { invoke, think } from "@operator-labs/operator-cli";
+
+await invoke("do step 1");              // → fresh agent session (full tools)
+// poll for results
+const r = await think("classify this"); // → llm-task (JSON, no tools)
+// branch based on result
+await invoke("do step 2");              // → fresh agent session
+```
+
+The script is deterministic. It handles control flow, loops, conditionals, data reading. Each `invoke()` spawns an isolated agent session with fresh context. Each `think()` calls the LLM without a session for lightweight reasoning.
+
+## Examples
+
+```bash
+operator examples                      # list available examples
+operator examples batch-analyze        # view a specific example
+```
+
+Three reference workflows are included:
+
+- **batch-analyze** — process N items with checkpointing and resume
+- **research-pipeline** — sequential gather → analyze → synthesize
+- **monitor-and-act** — conditional branching with CSV state
+
+## JS API
+
+```js
+import { invoke, think } from "@operator-labs/operator-cli";
+
+await invoke("Analyze example.com, write to /tmp/report.md");
+const result = await think("What is 2+2? Return {answer: number}");
+```
+
+After `operator-cli setup`, imports resolve from any script under `~/.openclaw/`.
+
+## Safety
+
+`invoke()` prepends safety rules by default to prevent spawned sessions from writing to `~/.openclaw/skills/`, `~/.openclaw/hooks/`, or `openclaw.json`. This blocks self-replicating skill creation.
+
+Disable with `invoke(message, { safety: false })`.
+
+See [references/safety.md](references/safety.md) for details.
+
+## Reference docs
+
+- [references/patterns.md](references/patterns.md) — batch, pipeline, fan-out patterns
+- [references/error-handling.md](references/error-handling.md) — retries, timeouts, checkpoints
+- [references/safety.md](references/safety.md) — safety rules and limitations

package/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: operator
+description: Spawn autonomous agent sessions from workflow scripts. Use when a workflow needs the agent to reason, use tools, browse, or write files at each step.
+license: Apache-2.0
+compatibility: Requires Node.js 18+ and OpenClaw.
+metadata:
+  author: Operator Labs
+  version: "2.0"
+---
+
+# Operator
+
+Two primitives for workflow scripts:
+
+- `invoke()` spawns a full agent session (tools, browser, filesystem)
+- `think()` calls the LLM directly (no session, returns JSON)
+
+Use invoke when the step needs to act. Use think when the step only needs reasoning.
+
+## Setup
+
+```bash
+operator-cli setup
+```
+
+Or configure manually -- see [references/setup.md](references/setup.md).
+
+## Invoke
+
+```js
+import { invoke } from "@operator-labs/operator-cli";
+
+await invoke("Analyze example.com, write findings to /tmp/report.md");
+```
+
+**Returns immediately.** The agent runs in the background. Your script must
+poll for results -- a file, a database row, an API response, anything.
+
+```js
+await invoke("Write report to /tmp/report.md");
+
+while (!existsSync("/tmp/report.md")) {
+  await new Promise(r => setTimeout(r, 5000));
+}
+```
+
+Safety rules are prepended by default. Pass `{ safety: false }` if the user
+explicitly requests unrestricted access.
+
+## Think
+
+```js
+import { think } from "@operator-labs/operator-cli";
+
+const result = await think("What is 2+2? Return {answer: number}");
+```
+
+Synchronous (request/response). No agent session. Returns JSON. Accepts a
+plain string or a JSON object with llm-task args (`prompt`, `input`, `schema`).
+
+## Writing Workflows
+
+A workflow script is deterministic Node.js that calls `invoke()` and `think()`
+to delegate intelligence. The script handles loops, conditionals, polling,
+and state. Each step gets fresh context.
+
+### When to use invoke vs think
+
+- **invoke** -- the step needs tools, browser, filesystem, or writes output.
+  Async: returns immediately, poll for results.
+- **think** -- the step only needs reasoning, classification, or structured
+  extraction. Sync: blocks until the LLM responds. Cheaper and faster.
+
+In a 50-item batch, use think for classification gates and invoke for the
+actual work. This avoids 50 unnecessary full agent sessions.
+
+### Workflow data
+
+Workflow state lives under `workflows/<name>/` relative to cwd. On OpenClaw
+this resolves to `~/.openclaw/workspace/workflows/<name>/`, alongside
+other workspace conventions like `skills/` and `memory/`.
+
+```js
+const WORK_DIR = join(process.cwd(), "workflows", WORKFLOW_NAME);
+```
+
+Before running, ask the user if they want to track state differently
+(database, API, custom path). The default is the workspace directory.
+
+Never hardcode absolute home directory paths.
+
+### Standard directory layout
+
+```
+workflows/<name>/
+  runs/<runId>.jsonl   # one file per invoke/think call
+  state/               # checkpoints, progress, intermediate data
+  results/             # final output files
+```
+
+### Run tracking
+
+Each `invoke()` or `think()` call gets its own JSONL file in `runs/`,
+matching how OpenClaw stores sessions in `sessions/<sessionId>.jsonl`:
+
+```js
+function logRun(runId, entry) {
+  mkdirSync(join(WORK_DIR, "runs"), { recursive: true });
+  appendFileSync(join(WORK_DIR, "runs", runId + ".jsonl"),
+    JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n");
+}
+
+const run = await invoke(message);
+logRun(run.runId, { type: "invoke", message: message.slice(0, 200), ok: run.ok });
+```
+
+The `runId` correlates with OpenClaw's session logs for debugging.
+
+### Checkpointing
+
+Write progress to `state/` after each step so the workflow can resume if
+interrupted:
+
+```js
+writeFileSync(join(WORK_DIR, "state/progress.txt"), String(i + 1));
+```
+
+### Packaging as a skill
+
+Package the workflow as a skill using the agentskills.io format so it
+appears in the skill catalog on future sessions:
+
+```
+<workflow-name>/
+├── SKILL.md          # name, description (triggers activation), usage docs
+├── scripts/
+│   └── workflow.mjs  # the operator workflow script
+├── references/       # optional: detailed docs loaded on demand
+└── assets/           # optional: templates, config files
+```
+
+SKILL.md frontmatter needs `name` (lowercase, hyphens, max 64 chars, matches
+directory name) and `description` (what it does + when to use it -- this is
+how the agent decides to activate).
+
+Install to `~/.openclaw/workspace/skills/<workflow-name>/`.
+
+### Constraints
+
+- Each invoke spawns a full agent session. No backpressure. Cap concurrency.
+- invoke returns a `runId` -- log it for tracing.
+- Each invoke and think consumes tokens. Prefer think when possible.
+
+### References and examples
+
+See [references/workflow-guide.md](references/workflow-guide.md) for the
+`invokeAndWait` helper, completion checks, and detailed state management.
+
+Before building a workflow, read the examples:
+
+- [examples/batch-analyze.mjs](examples/batch-analyze.mjs) -- checkpointing, resume, progress tracking
+- [examples/research-pipeline.mjs](examples/research-pipeline.mjs) -- sequential steps with validation
+- [examples/monitor-and-act.mjs](examples/monitor-and-act.mjs) -- conditional branching, CSV state
+
+## When to Use
+
+Use when control flow is deterministic but each step needs judgment. The
+script manages context between steps -- read outputs, compose prompts, pass
+forward what matters. This gives you explicit control over what context each
+step sees, without session window limits.
+
+Do not use for single tasks small enough for one session.

package/bin/operator.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+
+const [command, ...rest] = process.argv.slice(2);
+
+function hasFlag(name) {
+  return rest.includes("--" + name);
+}
+
+function flagValue(name) {
+  const idx = rest.indexOf("--" + name);
+  if (idx === -1 || idx + 1 >= rest.length) return undefined;
+  return rest[idx + 1];
+}
+
+function positional() {
+  return rest.filter((a) => !a.startsWith("--"));
+}
+
+switch (command) {
+  case "setup": {
+    if (hasFlag("help") || hasFlag("h")) {
+      console.log(`Configures OpenClaw for operator workflows. Enables hooks, generates
+tokens, enables llm-task plugin, and symlinks the operator skill.
+
+Safe to run multiple times.
+
+Options:
+  --dry-run     Show what would change without writing
+  --config      Path to openclaw.json (default: auto-detect)
+
+Examples:
+  operator-cli setup
+  operator-cli setup --dry-run
+  operator-cli setup --config ~/.openclaw/openclaw.json`);
+      break;
+    }
+    const { setup } = await import("../lib/setup.mjs");
+    const result = await setup({
+      dryRun: hasFlag("dry-run"),
+      configPath: flagValue("config"),
+    });
+    process.exit(result.ok ? 0 : 1);
+    break;
+  }
+
+  case "examples": {
+    if (hasFlag("help") || hasFlag("h")) {
+      console.log(`List or show example workflow scripts.
+
+Usage:
+  operator-cli examples                  List available examples
+  operator-cli examples batch-analyze    Show a specific example`);
+      break;
+    }
+    const name = positional()[0];
+    const examplesDir = join(__dirname, "..", "examples");
+    if (!name) {
+      const { readdirSync } = await import("fs");
+      const files = readdirSync(examplesDir).filter((f) => f.endsWith(".mjs"));
+      console.log("Available examples:\n");
+      for (const f of files) {
+        const stem = f.replace(".mjs", "");
+        const content = readFileSync(join(examplesDir, f), "utf-8");
+        const desc = content.match(/^\/\/\s*(.+)/m);
+        console.log("  " + stem.padEnd(24) + (desc ? desc[1] : ""));
+      }
+      console.log("\nRun 'operator-cli examples <name>' to view.");
+    } else {
+      const file = join(examplesDir, name + ".mjs");
+      try {
+        console.log(readFileSync(file, "utf-8"));
+      } catch {
+        console.error("Error: Unknown example '" + name + "'.");
+        console.error("  operator-cli examples");
+        process.exit(1);
+      }
+    }
+    break;
+  }
+
+  case "workflows": {
+    if (hasFlag("help") || hasFlag("h")) {
+      console.log(`Browse pre-built workflows from the monorepo.
+
+Usage:
+  operator-cli workflows                    List available workflows
+  operator-cli workflows search "email"     Search by keyword
+
+Environment:
+  OPERATOR_REPO      GitHub repo (default: openclaw/operator-mono)
+  OPERATOR_BRANCH    Branch (default: main)
+  GITHUB_TOKEN       Auth token for private repos / rate limits`);
+      break;
+    }
+    const { listWorkflows, searchWorkflows } = await import("../lib/workflows.mjs");
+    const sub = positional()[0];
+    try {
+      if (sub === "search") {
+        const query = positional()[1];
+        if (!query) {
+          console.error("Error: search requires a keyword.");
+          console.error("  operator-cli workflows search \"email\"");
+          process.exit(1);
+        }
+        const results = await searchWorkflows(query);
+        if (results.length === 0) {
+          console.log("No workflows matching '" + query + "'.");
+        } else {
+          console.log("Matching workflows:\n");
+          for (const w of results) {
+            console.log("  " + w.name.padEnd(28) + w.description);
+          }
+          console.log("\nRun 'operator-cli install <name>' to install.");
+        }
+      } else {
+        const workflows = await listWorkflows();
+        if (workflows.length === 0) {
+          console.log("No workflows found in the repository.");
+        } else {
+          console.log("Available workflows:\n");
+          for (const w of workflows) {
+            console.log("  " + w.name.padEnd(28) + w.description);
+          }
+          console.log("\nRun 'operator-cli install <name>' to install.");
+          console.log("Run 'operator-cli workflows search \"keyword\"' to filter.");
+        }
+      }
+    } catch (err) {
+      console.error("Error: " + err.message);
+      if (err.message.includes("403")) {
+        console.error("  Set GITHUB_TOKEN to avoid rate limits.");
+      }
+      process.exit(1);
+    }
+    break;
+  }
+
+  case "install": {
+    if (hasFlag("help") || hasFlag("h")) {
+      console.log(`Install a workflow to detected agent skill directories.
+
+Usage:
+  operator-cli install <name>     Install a workflow by name
+
+The workflow becomes available to the agent on the next session.
+
+Environment:
+  OPERATOR_REPO      GitHub repo (default: openclaw/operator-mono)
+  OPERATOR_BRANCH    Branch (default: main)
+  GITHUB_TOKEN       Auth token for private repos / rate limits`);
+      break;
+    }
+    const workflowName = positional()[0];
+    if (!workflowName) {
+      console.error("Error: install requires a workflow name.");
+      console.error("  operator-cli workflows             # list available");
+      console.error("  operator-cli install <name>        # install one");
+      process.exit(1);
+    }
+    const { installWorkflow } = await import("../lib/workflows.mjs");
+    try {
+      const result = await installWorkflow(workflowName);
+      if (!result.ok) {
+        console.error("Error: " + result.error);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error("Error: " + err.message);
+      process.exit(1);
+    }
+    break;
+  }
+
+  case "--version":
+  case "-v":
+    console.log(pkg.version);
+    break;
+
+  case "--help":
+  case "-h":
+  case undefined:
+    console.log(`operator-cli ${pkg.version} - self-calling workflow primitives for OpenClaw
+
+Usage: operator-cli <command> [options]
+
+Commands:
+  setup      Configure OpenClaw for operator workflows
+  examples   List or show example workflow scripts
+  workflows  Browse pre-built workflows from the monorepo
+  install    Install a workflow to the skill directory
+
+Use invoke() and think() in your workflow scripts:
+
+  import { invoke, think } from "@operator-labs/operator-cli";
+
+Requires OpenClaw.
+
+Run 'operator-cli <command> --help' for command-specific options.`);
+    break;
+
+  default:
+    console.error("Error: Unknown command '" + command + "'.");
+    console.error("  operator-cli --help");
+    process.exit(1);
+}

package/examples/batch-analyze.mjs

@@ -0,0 +1,103 @@
+// Batch analyze: process a list of items, analyze each, synthesize results.
+//
+// Demonstrates: checkpointing, resume, progress tracking, run tracking,
+// think for classification, invoke for analysis, final synthesis step.
+//
+// invoke() returns immediately -- the agent works in the background.
+// The script polls for each output file before moving to the next item.
+//
+// Usage: node examples/batch-analyze.mjs
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "fs";
+import { join } from "path";
+import { invoke, think } from "@operator-labs/operator-cli";
+import { randomUUID } from "crypto";
+
+const WORK_DIR = join(process.cwd(), "workflows", "batch-analyze");
+for (const dir of ["runs", "results", "state"]) {
+  mkdirSync(join(WORK_DIR, dir), { recursive: true });
+}
+
+function logRun(runId, entry) {
+  appendFileSync(join(WORK_DIR, "runs", runId + ".jsonl"),
+    JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n");
+}
+
+function status(fields) {
+  const current = existsSync(join(WORK_DIR, "state/status.json"))
+    ? JSON.parse(readFileSync(join(WORK_DIR, "state/status.json"), "utf-8"))
+    : {};
+  writeFileSync(join(WORK_DIR, "state/status.json"),
+    JSON.stringify({ ...current, ...fields, updatedAt: new Date().toISOString() }, null, 2));
+}
+
+async function waitForFile(path, maxWaitMs = 300000) {
+  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, 5000));
+  }
+  return false;
+}
+
+const urls = [
+  "https://example.com",
+  "https://example.org",
+  "https://example.net",
+];
+
+const progressFile = join(WORK_DIR, "state/progress.txt");
+let start = 0;
+if (existsSync(progressFile)) {
+  start = parseInt(readFileSync(progressFile, "utf-8"), 10);
+}
+
+status({ status: "running", pattern: "batch", total: urls.length, completed: start });
+
+for (let i = start; i < urls.length; i++) {
+  const url = urls[i];
+  const outputPath = join(WORK_DIR, "results/url-" + i + ".md");
+
+  status({ currentStep: "classifying " + url, completed: i });
+
+  const thinkId = randomUUID();
+  const prompt = JSON.stringify({
+    prompt: "Classify this URL as blog, product, docs, or other. Return {type: string}.",
+    input: url,
+    schema: {
+      type: "object",
+      properties: { type: { type: "string", enum: ["blog", "product", "docs", "other"] } },
+      required: ["type"],
+    },
+  });
+  const classification = await think(prompt);
+  logRun(thinkId, { type: "think", prompt: prompt.slice(0, 200), ok: classification.ok, output: classification.output });
+
+  const type = classification.output?.type || "unknown";
+  status({ currentStep: "analyzing " + url + " (type: " + type + ")" });
+
+  const message =
+    "Analyze " + url + " (classified as " + type + "). " +
+    "Write a detailed analysis to " + outputPath + ". " +
+    "Include: purpose, content summary, target audience, and notable features.";
+  const run = await invoke(message);
+  logRun(run.runId, { type: "invoke", message: message.slice(0, 200), ok: run.ok });
+
+  const found = await waitForFile(outputPath);
+  logRun(run.runId, { type: "poll", path: outputPath, found });
+
+  writeFileSync(progressFile, String(i + 1));
+}
+
+status({ currentStep: "synthesizing results", completed: urls.length });
+
+const synthesisMessage =
+  "Read all .md files in " + join(WORK_DIR, "results") + " and write a comparative " +
+  "synthesis to " + join(WORK_DIR, "results/synthesis.md") + ". " +
+  "Include a summary table and key findings.";
+const synthRun = await invoke(synthesisMessage);
+logRun(synthRun.runId, { type: "invoke", message: synthesisMessage.slice(0, 200), ok: synthRun.ok });
+await waitForFile(join(WORK_DIR, "results/synthesis.md"));
+logRun(synthRun.runId, { type: "done" });
+
+status({ status: "completed", currentStep: "done" });

package/examples/monitor-and-act.mjs

@@ -0,0 +1,122 @@
+// Monitor and act: check conditions, branch on results, update state.
+//
+// Demonstrates: think for boolean gates, conditional invoke calls,
+// CSV as shared state, data-driven branching, per-run JSONL tracking.
+//
+// think() returns the decision synchronously; invoke() dispatches the
+// agent and the script polls for the report file before continuing.
+//
+// Usage: node examples/monitor-and-act.mjs
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "fs";
+import { join } from "path";
+import { invoke, think } from "@operator-labs/operator-cli";
+import { randomUUID } from "crypto";
+
+const WORK_DIR = join(process.cwd(), "workflows", "monitor-and-act");
+for (const dir of ["runs", "state"]) {
+  mkdirSync(join(WORK_DIR, dir), { recursive: true });
+}
+
+function logRun(runId, entry) {
+  appendFileSync(join(WORK_DIR, "runs", runId + ".jsonl"),
+    JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n");
+}
+
+async function waitForFile(path, maxWaitMs = 300000) {
+  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, 5000));
+  }
+  return false;
+}
+
+const csvPath = join(WORK_DIR, "state/status.csv");
+if (!existsSync(csvPath)) {
+  writeFileSync(csvPath, "url,status,last_checked,notes\n" +
+    "https://example.com/api/health,pending,,\n" +
+    "https://example.org/status,pending,,\n" +
+    "https://example.net/ping,pending,,\n");
+}
+
+function readCsv() {
+  const lines = readFileSync(csvPath, "utf-8").trim().split("\n");
+  const header = lines[0].split(",");
+  return lines.slice(1).map((line) => {
+    const values = line.split(",");
+    const row = {};
+    header.forEach((h, i) => row[h] = values[i] || "");
+    return row;
+  });
+}
+
+function writeCsv(rows) {
+  const header = Object.keys(rows[0]).join(",");
+  const lines = rows.map((r) => Object.values(r).join(","));
+  writeFileSync(csvPath, header + "\n" + lines.join("\n") + "\n");
+}
+
+const rows = readCsv();
+
+for (const row of rows) {
+  const gateId = randomUUID();
+  const check = await think(JSON.stringify({
+    prompt: "You are monitoring this endpoint. Based on its current status, " +
+      "should it be checked now? Consider: status is '" + row.status + "', " +
+      "last checked: " + (row.last_checked || "never") + ". " +
+      "Return {shouldCheck: boolean, reason: string}",
+    input: { url: row.url, status: row.status, lastChecked: row.last_checked },
+    schema: {
+      type: "object",
+      properties: {
+        shouldCheck: { type: "boolean" },
+        reason: { type: "string" },
+      },
+      required: ["shouldCheck", "reason"],
+    },
+  }));
+  logRun(gateId, { type: "think", step: "gate", url: row.url, ok: check.ok, output: check.output });
+
+  if (!check.output?.shouldCheck) {
+    continue;
+  }
+
+  const reportPath = join(WORK_DIR, "state/report-" + Buffer.from(row.url).toString("base64url").slice(0, 20) + ".md");
+  const checkMsg =
+    "Check the endpoint " + row.url + ". Determine if it is healthy. " +
+    "Write a brief status report to " + reportPath + ". " +
+    "Include: response status, response time estimate, any issues found.";
+  const run = await invoke(checkMsg);
+  logRun(run.runId, { type: "invoke", step: "check", url: row.url, message: checkMsg.slice(0, 200), ok: run.ok });
+  await waitForFile(reportPath, 120000);
+  logRun(run.runId, { type: "poll", path: reportPath, found: existsSync(reportPath) });
+
+  let newStatus = "checked";
+  if (existsSync(reportPath)) {
+    const report = readFileSync(reportPath, "utf-8");
+    const extractId = randomUUID();
+    const extract = await think(JSON.stringify({
+      prompt: "Extract the health status from this report. Return {healthy: boolean, summary: string}",
+      input: report,
+      schema: {
+        type: "object",
+        properties: {
+          healthy: { type: "boolean" },
+          summary: { type: "string" },
+        },
+        required: ["healthy", "summary"],
+      },
+    }));
+    logRun(extractId, { type: "think", step: "extract", url: row.url, ok: extract.ok, output: extract.output });
+
+    newStatus = extract.output?.healthy ? "healthy" : "unhealthy";
+    row.notes = (extract.output?.summary || "").replace(/,/g, ";").slice(0, 100);
+  }
+
+  row.status = newStatus;
+  row.last_checked = new Date().toISOString();
+}
+
+writeCsv(rows);
+console.log("status: " + csvPath);