@operator-labs/operator-cli 0.1.0

package/references/safety.md

@@ -0,0 +1,37 @@
+# Safety Rules
+
+`invoke()` prepends safety rules to every message by default. This prevents hook-spawned agent sessions from creating persistent autonomous behavior.
+
+## What it does
+
+`invoke()` prepends a short block of text before your message:
+
+```
+OPERATOR SAFETY RULES:
+You MUST NOT write to the following paths:
+- ~/.openclaw/skills
+- ~/.openclaw/hooks
+- openclaw.json
+...
+
+---
+
+<your actual message>
+```
+
+The agent still has full tool access. The rules tell it not to use write tools on specific paths.
+
+## What it prevents
+
+An agent that writes a new skill to `~/.openclaw/skills/` containing its own `operator invoke` calls creates a self-replicating loop. The safety rules prevent this by instructing the agent to skip writes to the skills directory, hooks directory, and gateway config.
+
+## Limitations
+
+This is a prompt-level boundary. The agent is told not to write to protected paths, not mechanically prevented. This is the same trust model OpenClaw uses for external content wrapping. It works for non-adversarial workflows processing structured data. It does not prevent a crafted prompt injection designed to override the rules.
+
+## Disabling
+
+```js
+// Per invocation
+await invoke("your message", { safety: false });
+```

package/references/setup.md

@@ -0,0 +1,60 @@
+# Manual Setup
+
+If you prefer to configure manually instead of running `operator-cli setup`,
+the following must be present in `openclaw.json` (typically at
+`~/.openclaw/openclaw.json` or `$OPENCLAW_CONFIG_PATH`):
+
+## 1. Hooks enabled with a token and the operator mapping
+
+- `hooks.enabled`: `true`
+- `hooks.token`: any non-empty string (generate with `require("crypto").randomBytes(32).toString("hex")`)
+- `hooks.mappings`: must include:
+
+```json
+{
+  "id": "operator",
+  "match": { "path": "operator" },
+  "action": "agent",
+  "messageTemplate": "{{message}}"
+}
+```
+
+## 2. llm-task plugin enabled (required for think())
+
+- `plugins.entries.llm-task.enabled`: `true`
+
+## 3. llm-task in the tool allowlist
+
+- `tools.allow` must include `"llm-task"`
+
+## 4. Gateway auth token (required for think(), not for invoke())
+
+- `gateway.auth.token` in config, or `OPENCLAW_GATEWAY_TOKEN` env var
+- Must differ from `hooks.token` -- OpenClaw rejects startup if they match
+
+## Full example
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "token": "<generated 64-char hex>",
+    "mappings": [
+      {
+        "id": "operator",
+        "match": { "path": "operator" },
+        "action": "agent",
+        "messageTemplate": "{{message}}"
+      }
+    ]
+  },
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  },
+  "tools": {
+    "allow": ["llm-task"]
+  }
+}
+```

package/references/workflow-guide.md

@@ -0,0 +1,150 @@
+# Writing Workflow Scripts
+
+Workflows are Node.js scripts that import `invoke` and `think` from
+`@operator-labs/operator-cli`. After `operator-cli setup`, imports resolve
+from any script in the agent's skill directory or from a project with the
+package installed.
+
+A workflow is a skill. It lives in the agent's skill directory alongside a
+`SKILL.md` so the agent can discover and run it on future sessions.
+
+## invokeAndWait
+
+`invoke()` returns immediately. Poll for the result:
+
+```js
+async function invokeAndWait(message, done, { interval = 5000, maxWait = 300000 } = {}) {
+  await invoke(message);
+  const start = Date.now();
+  while (Date.now() - start < maxWait) {
+    if (await done()) return;
+    await new Promise(r => setTimeout(r, interval));
+  }
+  throw new Error("timed out waiting for task to complete");
+}
+```
+
+The `done()` check is yours -- file, database row, API call, anything:
+
+```js
+const fileReady = (path) => () => existsSync(path) && readFileSync(path, "utf-8").trim();
+const apiReady  = (url)  => async () => (await fetch(url)).ok;
+const dbRow     = (query) => async () => (await db.query(query)).rows.length > 0;
+```
+
+## Full example
+
+```js
+import { readFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { invoke, think } from "@operator-labs/operator-cli";
+
+const WORK_DIR = join(process.cwd(), "workflows", "my-workflow");
+for (const dir of ["results", "state", "logs"]) {
+  mkdirSync(join(WORK_DIR, dir), { recursive: true });
+}
+
+// Classify with think (synchronous request/response)
+const classification = await think(JSON.stringify({
+  prompt: "Classify this URL.",
+  input: "https://example.com",
+  schema: {
+    type: "object",
+    properties: { type: { type: "string", enum: ["blog", "product", "docs"] } },
+    required: ["type"],
+  },
+}));
+
+// Invoke and wait for output file
+const analysisPath = join(WORK_DIR, "results/analysis.md");
+await invoke(
+  "Analyze https://example.com (type: " + classification.output?.type + "). " +
+  "Write findings to " + analysisPath,
+);
+while (!existsSync(analysisPath) || !readFileSync(analysisPath, "utf-8").trim()) {
+  await new Promise(r => setTimeout(r, 5000));
+}
+```
+
+## State management
+
+Workflow data lives under `workflows/<name>/` relative to cwd. On OpenClaw
+this resolves to `~/.openclaw/workspace/workflows/<name>/`.
+
+Standard 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 });
+// append more events to the same file as the run progresses
+logRun(run.runId, { type: "poll", path: outputPath, found: true });
+```
+
+The `runId` correlates with OpenClaw's session logs for debugging.
+
+### Checkpointing
+
+For workflows that benefit from resume (batches, long pipelines), write
+progress to `state/` after each step so the workflow can pick up where it
+left off.
+
+## Where workflows live
+
+A workflow is a skill. The agent creates it in its own skill directory:
+
+- `~/.openclaw/workspace/skills/<workflow-name>/`
+
+Each workflow follows the agentskills.io format:
+
+```
+<workflow-name>/
+├── SKILL.md                # frontmatter (name, description) + instructions
+├── scripts/                # executable workflow code
+│   └── workflow.mjs
+├── references/             # docs loaded on demand (optional)
+│   └── *.md
+└── assets/                 # templates, config files (optional)
+```
+
+SKILL.md frontmatter requires `name` (lowercase, hyphens, max 64 chars)
+and `description` (what it does + when to use it). The description is how the
+agent decides to activate the skill, so include specific triggers. The body
+contains usage instructions, loaded only after activation.
+
+On future sessions the workflow appears in the skill catalog and can be
+reused or modified.
+
+Pre-built workflows from the monorepo can be installed with
+`operator-cli install <name>`, which copies the skill into the skill directory.
+
+## Constraints
+
+- Each `invoke` spawns a full agent session. Parallel invokes without a concurrency cap can exhaust resources.
+- `invoke()` returns a `runId`. Log it -- it's the only link between your workflow log and the agent session.
+- Each invoke and think call consumes tokens. Prefer `think` over `invoke` when the step only needs reasoning.
+
+## Examples
+
+Before building a workflow, read the bundled examples:
+
+- `examples/batch-analyze.mjs` — checkpointing, resume, progress tracking
+- `examples/research-pipeline.mjs` — sequential steps with validation
+- `examples/monitor-and-act.mjs` — conditional branching, CSV state