@operator-labs/operator-cli 0.1.0

package/examples/research-pipeline.mjs

@@ -0,0 +1,122 @@
+// Research pipeline: gather data, analyze, validate, synthesize.
+//
+// Demonstrates: sequential steps with data validation between them,
+// file-as-shared-memory, deterministic logic mixed with agent steps,
+// retry on malformed output, per-run JSONL tracking.
+//
+// Usage: node examples/research-pipeline.mjs ["topic here"]
+
+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", "research-pipeline");
+for (const dir of ["runs", "state", "results"]) {
+  mkdirSync(join(WORK_DIR, dir), { recursive: true });
+}
+
+const TOPIC = process.argv[2] || "open source AI frameworks in 2026";
+
+function logRun(runId, entry) {
+  appendFileSync(join(WORK_DIR, "runs", runId + ".jsonl"),
+    JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n");
+}
+
+function validateJson(path) {
+  try {
+    JSON.parse(readFileSync(path, "utf-8"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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;
+}
+
+// Step 1: Agent gathers raw research
+const findingsPath = join(WORK_DIR, "state/raw-findings.json");
+const msg1 =
+  "Research the topic: " + TOPIC + ". " +
+  "Browse relevant sources, collect key facts and data points. " +
+  "Write raw findings as JSON to " + findingsPath + ". " +
+  "Format: {sources: [{url, title, summary}], keyFacts: [string]}";
+const run1 = await invoke(msg1);
+logRun(run1.runId, { type: "invoke", step: "gather", message: msg1.slice(0, 200), ok: run1.ok });
+await waitForFile(findingsPath, 300000);
+logRun(run1.runId, { type: "poll", path: findingsPath, found: existsSync(findingsPath) });
+
+if (!validateJson(findingsPath)) {
+  const msg1r =
+    "The previous research output was not valid JSON. " +
+    "Read " + findingsPath + " and fix it. " +
+    "Write valid JSON to the same path. " +
+    "Format: {sources: [{url, title, summary}], keyFacts: [string]}";
+  const run1r = await invoke(msg1r);
+  logRun(run1r.runId, { type: "invoke", step: "gather-retry", message: msg1r.slice(0, 200), ok: run1r.ok });
+  await waitForFile(findingsPath, 120000);
+}
+
+const findings = JSON.parse(readFileSync(findingsPath, "utf-8"));
+
+// Step 2: think() to extract themes
+const thinkId = randomUUID();
+const themesResult = await think(JSON.stringify({
+  prompt: "Identify the 3-5 main themes from these research findings. " +
+    "Return {themes: [{name: string, description: string, relevantFacts: number[]}]}",
+  input: findings,
+  schema: {
+    type: "object",
+    properties: {
+      themes: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            description: { type: "string" },
+            relevantFacts: { type: "array", items: { type: "number" } },
+          },
+          required: ["name", "description"],
+        },
+      },
+    },
+    required: ["themes"],
+  },
+}));
+logRun(thinkId, { type: "think", step: "themes", ok: themesResult.ok, themeCount: themesResult.output?.themes?.length });
+
+const themesPath = join(WORK_DIR, "state/themes.json");
+writeFileSync(themesPath, JSON.stringify(themesResult.output, null, 2));
+
+// Step 3: Agent writes detailed analysis
+const analysisPath = join(WORK_DIR, "results/analysis.md");
+const msg3 =
+  "Read the research findings at " + findingsPath +
+  " and the themes at " + themesPath + ". " +
+  "Write a detailed analysis to " + analysisPath + ". " +
+  "Structure it with one section per theme, citing sources. " +
+  "Include a summary table at the top.";
+const run3 = await invoke(msg3);
+logRun(run3.runId, { type: "invoke", step: "analysis", message: msg3.slice(0, 200), ok: run3.ok });
+await waitForFile(analysisPath, 300000);
+
+// Step 4: Agent writes executive summary
+const summaryPath = join(WORK_DIR, "results/summary.md");
+const msg4 =
+  "Read the analysis at " + analysisPath + ". " +
+  "Write a concise executive summary (max 500 words) to " + summaryPath + ". " +
+  "Focus on actionable takeaways.";
+const run4 = await invoke(msg4);
+logRun(run4.runId, { type: "invoke", step: "summary", message: msg4.slice(0, 200), ok: run4.ok });
+await waitForFile(summaryPath, 120000);
+logRun(run4.runId, { type: "done" });
+
+console.log("results: " + join(WORK_DIR, "results/"));

package/index.mjs

@@ -0,0 +1,5 @@
+export { invoke } from "./lib/invoke.mjs";
+export { think } from "./lib/think.mjs";
+export { setup } from "./lib/setup.mjs";
+export { resolveBackend, detectInstalledAgents, detectRuntime } from "./lib/backend.mjs";
+export { resolveConfigPath, readConfig, resolveGatewayToken, resolveHooksToken } from "./lib/config.mjs";

package/lib/backend.mjs

@@ -0,0 +1,71 @@
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const BACKENDS = ["openclaw"];
+
+const LEGACY_STATE_DIRS = [".clawdbot", ".moldbot", ".moltbot"];
+
+function detectRuntime() {
+  const { env } = process;
+
+  if (env.AI_AGENT) {
+    const name = env.AI_AGENT.trim().toLowerCase();
+    if (name === "openclaw") return "openclaw";
+  }
+
+  if (env.OPENCLAW_SHELL) return "openclaw";
+
+  return null;
+}
+
+const DETECT_INSTALLED = {
+  openclaw: () => {
+    const home = homedir();
+    return [".openclaw", ...LEGACY_STATE_DIRS].some(
+      (d) => existsSync(join(home, d)),
+    );
+  },
+};
+
+let _cached = null;
+
+export async function resolveBackend() {
+  if (_cached) return _cached;
+
+  const runtime = detectRuntime();
+  if (runtime) {
+    _cached = await loadBackend(runtime);
+    return _cached;
+  }
+
+  for (const name of BACKENDS) {
+    if (DETECT_INSTALLED[name]()) {
+      _cached = await loadBackend(name);
+      return _cached;
+    }
+  }
+
+  throw new Error(
+    "No agent host detected. Install OpenClaw.",
+  );
+}
+
+export function detectInstalledAgents() {
+  return BACKENDS.filter((name) => DETECT_INSTALLED[name]());
+}
+
+export { detectRuntime };
+
+async function loadBackend(name) {
+  try {
+    return await import(`./backends/${name}.mjs`);
+  } catch (err) {
+    if (err.code === "ERR_MODULE_NOT_FOUND") {
+      throw new Error(
+        "Backend '" + name + "' is not yet implemented.",
+      );
+    }
+    throw err;
+  }
+}

package/lib/backends/openclaw.mjs

@@ -0,0 +1,151 @@
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import {
+  resolveConfigPath,
+  readConfig,
+  resolveHooksToken,
+  resolveGatewayToken,
+  resolveGatewayPort,
+  resolveStateDir,
+} from "../config.mjs";
+import { post } from "../http.mjs";
+
+export const name = "openclaw";
+
+const LEGACY_STATE_DIRS = [".clawdbot", ".moldbot", ".moltbot"];
+
+export function detect() {
+  const home = homedir();
+  const dirs = [".openclaw", ...LEGACY_STATE_DIRS];
+  return dirs.some((d) => existsSync(join(home, d)));
+}
+
+export function skillsDir() {
+  return join(resolveStateDir(), "skills");
+}
+
+export async function invoke(message, options = {}) {
+  const { timeout = 120000, configPath: configOverride, idempotencyKey } = options;
+  const configPath = resolveConfigPath(configOverride);
+  const config = readConfig(configPath);
+  if (!config) {
+    console.error("error: config not found at " + configPath);
+    console.error("  operator-cli setup");
+    return { ok: false, error: "config_not_found" };
+  }
+
+  const token = resolveHooksToken(config);
+  if (!token) {
+    console.error("error: hooks.token not set in " + configPath);
+    console.error("  operator-cli setup");
+    return { ok: false, error: "no_hooks_token" };
+  }
+
+  try {
+    const port = resolveGatewayPort(config);
+    const key = idempotencyKey || createHash("sha256").update(message).digest("hex").slice(0, 32);
+    const res = await post(
+      `http://localhost:${port}/hooks/operator`,
+      { message },
+      token,
+      timeout,
+      { "Idempotency-Key": key },
+    );
+
+    if (res.status >= 200 && res.status < 300) {
+      let runId;
+      try {
+        const json = JSON.parse(res.body);
+        runId = json.runId;
+      } catch {}
+      if (runId) {
+        console.log("run_id: " + runId);
+        console.log("status: dispatched");
+      }
+      return { ok: true, runId };
+    }
+
+    console.error("error: gateway returned " + res.status);
+    console.error(res.body.slice(0, 500));
+    return { ok: false, error: "gateway_" + res.status };
+  } catch (err) {
+    console.error("error: " + err.message);
+    if (err.message.includes("ECONNREFUSED")) {
+      console.error("  Is the OpenClaw gateway running on port 18789?");
+    }
+    return { ok: false, error: err.message };
+  }
+}
+
+export async function think(prompt, options = {}) {
+  const { timeout = 120000, configPath: configOverride } = options;
+  const configPath = resolveConfigPath(configOverride);
+  const config = readConfig(configPath);
+  if (!config) {
+    console.error("error: config not found at " + configPath);
+    console.error("  operator-cli setup");
+    return { ok: false, error: "config_not_found" };
+  }
+
+  const token = resolveGatewayToken(config);
+  if (!token) {
+    console.error("error: gateway auth token not found");
+    console.error("  Set gateway.auth.token in " + configPath);
+    console.error("  or export OPENCLAW_GATEWAY_TOKEN=<token>");
+    return { ok: false, error: "no_gateway_token" };
+  }
+
+  let args;
+  try {
+    const parsed = JSON.parse(prompt);
+    args = parsed.prompt ? parsed : { prompt };
+  } catch {
+    args = { prompt };
+  }
+
+  try {
+    const port = resolveGatewayPort(config);
+    const res = await post(
+      `http://localhost:${port}/tools/invoke`,
+      { tool: "llm-task", action: "json", args },
+      token,
+      timeout,
+    );
+
+    if (res.status >= 200 && res.status < 300) {
+      try {
+        const json = JSON.parse(res.body);
+        if (json.ok) {
+          const output = json.result?.json ?? json.result?.details ?? json.result;
+          if (output !== undefined && output !== null) {
+            const text = typeof output === "string" ? output : JSON.stringify(output);
+            process.stdout.write(text);
+          }
+          return { ok: true, output };
+        }
+        const msg = json.error?.message || res.body.slice(0, 500);
+        console.error("error: " + msg);
+        return { ok: false, error: msg };
+      } catch {
+        console.error("error: invalid response from gateway");
+        console.error(res.body.slice(0, 500));
+        return { ok: false, error: "invalid_response" };
+      }
+    }
+
+    console.error("error: gateway returned " + res.status);
+    console.error(res.body.slice(0, 500));
+    if (res.status === 404) {
+      console.error("  Is the llm-task plugin enabled? Run: operator-cli setup");
+    }
+    return { ok: false, error: "gateway_" + res.status };
+  } catch (err) {
+    console.error("error: " + err.message);
+    if (err.message.includes("ECONNREFUSED")) {
+      console.error("  Is the OpenClaw gateway running on port 18789?");
+    }
+    return { ok: false, error: err.message };
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const LEGACY_STATE_DIRS = [".clawdbot", ".moldbot", ".moltbot"];
+const CONFIG_FILENAMES = ["openclaw.json", "clawdbot.json", "moldbot.json", "moltbot.json"];
+
+/**
+ * Resolve the OpenClaw state directory.
+ * Mirrors src/config/paths.ts resolveStateDir.
+ */
+export function resolveStateDir() {
+  const override =
+    process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  if (override) return override;
+
+  const home = homedir();
+  const primary = join(home, ".openclaw");
+  if (existsSync(primary)) return primary;
+
+  for (const legacy of LEGACY_STATE_DIRS) {
+    const dir = join(home, legacy);
+    if (existsSync(dir)) return dir;
+  }
+  return primary;
+}
+
+/**
+ * Resolve the openclaw config file path.
+ * Mirrors src/config/paths.ts resolveDefaultConfigCandidates + first-existing pick.
+ *
+ * Precedence:
+ *   1. OPENCLAW_CONFIG_PATH or CLAWDBOT_CONFIG_PATH env var
+ *   2. First existing file scanning state dir + legacy dirs/filenames
+ *   3. ~/.openclaw/openclaw.json (default even if missing)
+ */
+export function resolveConfigPath(override) {
+  if (override) return override;
+
+  const envPath =
+    process.env.OPENCLAW_CONFIG_PATH?.trim() || process.env.CLAWDBOT_CONFIG_PATH?.trim();
+  if (envPath) return envPath;
+
+  const home = homedir();
+  const stateDir = resolveStateDir();
+
+  // Scan state dir with all config filenames
+  for (const name of CONFIG_FILENAMES) {
+    const candidate = join(stateDir, name);
+    if (existsSync(candidate)) return candidate;
+  }
+
+  // Scan default + legacy state dirs
+  const dirs = [join(home, ".openclaw"), ...LEGACY_STATE_DIRS.map((d) => join(home, d))];
+  for (const dir of dirs) {
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  return join(home, ".openclaw", "openclaw.json");
+}
+
+/**
+ * Read and parse the config file. Returns null on missing or parse error.
+ * OpenClaw uses JSON5 (supports comments, trailing commas). We attempt
+ * JSON.parse first, then strip // and /* comments as a fallback.
+ */
+export function readConfig(configPath) {
+  if (!existsSync(configPath)) return null;
+  const raw = readFileSync(configPath, "utf-8");
+
+  // Try strict JSON first (most common)
+  try {
+    return JSON.parse(raw);
+  } catch {}
+
+  // Fallback: strip comments and trailing commas, then retry.
+  // Only strips // comments at the start of a line (with optional whitespace)
+  // to avoid mangling URLs like "https://example.com" inside string values.
+  try {
+    const stripped = raw
+      .replace(/^\s*\/\/[^\n]*/gm, "")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/,\s*([}\]])/g, "$1");
+    return JSON.parse(stripped);
+  } catch {}
+
+  return null;
+}
+
+/**
+ * Find the hooks token. Always a string in config at hooks.token.
+ * No dedicated env var exists for this.
+ */
+export function resolveHooksToken(config) {
+  const token = config?.hooks?.token;
+  if (typeof token === "string" && token.trim()) return token.trim();
+  return null;
+}
+
+/**
+ * Find the gateway auth token. Checks config then env vars.
+ * Mirrors src/gateway/auth.ts + src/gateway/credential-planner.ts.
+ *
+ * Precedence (config-first):
+ *   1. gateway.auth.token in config (plain string)
+ *   2. OPENCLAW_GATEWAY_TOKEN env var
+ *   3. CLAWDBOT_GATEWAY_TOKEN env var (legacy)
+ *
+ * Note: gateway.token (top-level, no .auth) is a common miskey and is ignored
+ * by OpenClaw. We check it and warn.
+ */
+export function resolveGatewayToken(config) {
+  // Config value (plain string only; secret refs need gateway-side resolution)
+  const fromConfig = config?.gateway?.auth?.token;
+  if (typeof fromConfig === "string" && fromConfig.trim()) {
+    return fromConfig.trim();
+  }
+
+  // Env vars
+  const fromEnv =
+    process.env.OPENCLAW_GATEWAY_TOKEN?.trim() ||
+    process.env.CLAWDBOT_GATEWAY_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+
+  return null;
+}
+
+/**
+ * Resolve the gateway port.
+ * Mirrors src/config/paths.ts resolveGatewayPort.
+ */
+export function resolveGatewayPort(config) {
+  const fromEnv =
+    process.env.OPENCLAW_GATEWAY_PORT?.trim() || process.env.CLAWDBOT_GATEWAY_PORT?.trim();
+  if (fromEnv && !isNaN(Number(fromEnv))) return Number(fromEnv);
+  const fromConfig = config?.gateway?.port;
+  if (typeof fromConfig === "number" && fromConfig > 0) return fromConfig;
+  return 18789;
+}
+
+/**
+ * Check for common config miskeys and return warnings.
+ */
+export function checkConfigWarnings(config) {
+  const warnings = [];
+  if (config?.gateway?.token && !config?.gateway?.auth?.token) {
+    warnings.push(
+      "gateway.token is set but ignored by OpenClaw. Did you mean gateway.auth.token?",
+    );
+  }
+  return warnings;
+}

package/lib/http.mjs

@@ -0,0 +1,31 @@
+import { request } from "http";
+
+/**
+ * POST JSON to a local gateway endpoint. Returns { status, body }.
+ */
+export function post(url, data, token, timeoutMs = 120000, extraHeaders = {}) {
+  const payload = JSON.stringify(data);
+  return new Promise((resolve, reject) => {
+    const req = request(url, {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + token,
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+        ...extraHeaders,
+      },
+      timeout: timeoutMs,
+    }, (res) => {
+      let body = "";
+      res.on("data", (chunk) => body += chunk);
+      res.on("end", () => resolve({ status: res.statusCode, body }));
+    });
+    req.on("error", reject);
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error("request timed out after " + timeoutMs + "ms"));
+    });
+    req.write(payload);
+    req.end();
+  });
+}

package/lib/invoke.mjs

@@ -0,0 +1,24 @@
+import { resolveBackend } from "./backend.mjs";
+import { applySafety } from "./safety.mjs";
+
+/**
+ * Spawn a full agent session via the active backend.
+ *
+ * Returns immediately after dispatch. The agent runs in the background --
+ * poll for your expected output to know when it's done.
+ *
+ * @param {string} message - The task prompt
+ * @param {object} [options]
+ * @param {boolean} [options.safety=true] - Prepend safety rules.
+ *   Pass { safety: false } if the user explicitly requests unrestricted access.
+ * @param {number} [options.timeout=120000] - Request timeout in ms (not agent timeout)
+ * @param {string} [options.configPath] - Override config path (OpenClaw only)
+ * @param {string} [options.idempotencyKey] - Dedup key (OpenClaw only)
+ * @returns {{ ok: boolean, runId?: string, error?: string }}
+ */
+export async function invoke(message, options = {}) {
+  const { safety = true, ...backendOpts } = options;
+  const backend = await resolveBackend();
+  const body = safety ? applySafety(message, backend.name) : message;
+  return backend.invoke(body, backendOpts);
+}

package/lib/safety.mjs

@@ -0,0 +1,36 @@
+import { join } from "path";
+import { resolveStateDir } from "./config.mjs";
+
+function getDenyPaths(backendName) {
+  if (backendName === "openclaw") {
+    const stateDir = resolveStateDir();
+    return [
+      join(stateDir, "skills"),
+      join(stateDir, "hooks"),
+      "openclaw.json",
+    ];
+  }
+  return [];
+}
+
+function buildSafetyPrefix(denyPaths) {
+  return `OPERATOR SAFETY RULES:
+You MUST NOT write to the following paths or any files within them:
+${denyPaths.map((p) => "- " + p).join("\n")}
+
+Do not create new skills, modify hook transforms, or change agent
+configuration. If your task requires writing to these paths, report
+that the operation is not permitted and continue with other work.
+
+---
+
+`;
+}
+
+export function applySafety(message, backendName) {
+  const paths = getDenyPaths(backendName);
+  if (paths.length === 0) return message;
+  return buildSafetyPrefix(paths) + message;
+}
+
+export { getDenyPaths };