@openclaw/lobster 2026.9.5 → 2026.9.6

package/node_modules/@clawdbot/lobster/README.md

@@ -2,139 +2,20 @@
 
 ![Lobster banner](docs/assets/readme-banner.jpg)
 
-An OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.
+An OpenClaw-native workflow shell: typed (JSON-first) pipelines and approval gates.
 
+## Example
 
-## Example of Lobster at work
-OpenClaw (or any other AI agent) can use `lobster` as a workflow engine and avoid re-planning every step — saving tokens while improving determinism and resumability.
+A named workflow fetches a pull request with `gh`, compares it with the saved snapshot, and returns a notification only when it changes:
 
-### Watching a PR that hasn't had changes
-```
-node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1152}'"
-[
-  {
-    "kind": "github.pr.monitor",
-    "repo": "openclaw/openclaw",
-    "prNumber": 1152,
-    "key": "github.pr:openclaw/openclaw#1152",
-    "changed": false,
-    "summary": {
-      "changedFields": [],
-      "changes": {}
-    },
-    "prSnapshot": {
-      "author": {
-        "id": "MDQ6VXNlcjE0MzY4NTM=",
-        "is_bot": false,
-        "login": "vignesh07",
-        "name": "Vignesh"
-      },
-      "baseRefName": "main",
-      "headRefName": "feat/lobster-plugin",
-      "isDraft": false,
-      "mergeable": "MERGEABLE",
-      "number": 1152,
-      "reviewDecision": "",
-      "state": "OPEN",
-      "title": "feat: Add optional lobster plugin tool (typed workflows, approvals/resume)",
-      "updatedAt": "2026-01-18T20:16:56Z",
-      "url": "https://github.com/openclaw/openclaw/pull/1152"
-    }
-  }
-]
+```bash
+node bin/lobster.js run --mode tool "workflows.run --name github.pr.monitor.notify --args-json '{\"repo\":\"openclaw/lobster\",\"pr\":167}'"
 ```
-### And a PR that has a state change (in this case an approved PR)
 
-```
- node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo\":\"openclaw/openclaw\",\"pr\":1200}'"
-[
-  {
-    "kind": "github.pr.monitor",
-    "repo": "openclaw/openclaw",
-    "prNumber": 1200,
-    "key": "github.pr:openclaw/openclaw#1200",
-    "changed": true,
-    "summary": {
-      "changedFields": [
-        "number",
-        "title",
-        "url",
-        "state",
-        "isDraft",
-        "mergeable",
-        "reviewDecision",
-        "updatedAt",
-        "baseRefName",
-        "headRefName"
-      ],
-      "changes": {
-        "number": {
-          "from": null,
-          "to": 1200
-        },
-        "title": {
-          "from": null,
-          "to": "feat(tui): add syntax highlighting for code blocks"
-        },
-        "url": {
-          "from": null,
-          "to": "https://github.com/openclaw/openclaw/pull/1200"
-        },
-        "state": {
-          "from": null,
-          "to": "MERGED"
-        },
-        "isDraft": {
-          "from": null,
-          "to": false
-        },
-        "mergeable": {
-          "from": null,
-          "to": "UNKNOWN"
-        },
-        "reviewDecision": {
-          "from": null,
-          "to": ""
-        },
-        "updatedAt": {
-          "from": null,
-          "to": "2026-01-19T05:06:09Z"
-        },
-        "baseRefName": {
-          "from": null,
-          "to": "main"
-        },
-        "headRefName": {
-          "from": null,
-          "to": "feat/tui-syntax-highlighting"
-        }
-      }
-    },
-    "prSnapshot": {
-      "author": {
-        "id": "MDQ6VXNlcjE0MzY4NTM=",
-        "is_bot": false,
-        "login": "vignesh07",
-        "name": "Vignesh"
-      },
-      "baseRefName": "main",
-      "headRefName": "feat/tui-syntax-highlighting",
-      "isDraft": false,
-      "mergeable": "UNKNOWN",
-      "number": 1200,
-      "reviewDecision": "",
-      "state": "MERGED",
-      "title": "feat(tui): add syntax highlighting for code blocks",
-      "updatedAt": "2026-01-19T05:06:09Z",
-      "url": "https://github.com/openclaw/openclaw/pull/1200"
-    }
-  }
-]
-```
+For repeatable automation, put shell commands, native pipeline steps, and explicit approval/input gates in a workflow file. OpenClaw presents the gate to the user and resumes with their decision.
 
 ## Goals
 
-
 - Typed pipelines (objects/arrays), not text pipes.
 - Local-first execution.
 - No new auth surface: Lobster must not own OAuth/tokens.
@@ -142,9 +23,10 @@ node bin/lobster.js "workflows.run --name github.pr.monitor --args-json '{\"repo
 
 ## Quick start
 
-From this folder:
+Requires Node.js 22 or newer and the pnpm version pinned in `package.json`. From this folder:
 
-- `pnpm install`
+- `pnpm install --frozen-lockfile`
+- `pnpm build`
 - `pnpm test`
 - `pnpm lint`
 - `node ./bin/lobster.js --help`
@@ -154,7 +36,9 @@ From this folder:
 ### Notes
 
 - `pnpm test` runs `tsc` and then executes tests against `dist/`.
-- `bin/lobster.js` prefers the compiled entrypoint in `dist/` when present.
+- `bin/lobster.js` runs the compiled entrypoint in `dist/`; build after changing source files.
+Invalid explicit workflow file paths are reported as input errors (exit code 2). In `--mode tool`, these failures use the same JSON error envelope as other parsing errors.
+
 ## Process output limits
 
 Captured process stdout and stderr remain unlimited by default. Set
@@ -187,20 +71,16 @@ keep pipes open after overflow. Calls without an AbortSignal relay terminal
 interrupts to that group and retain the host's existing signal handlers or
 conventional interrupt exit status.
 
-
 ## Commands
 
 - `exec`: run OS commands
 - `exec --json <command...>`: parse subprocess stdout as JSON before the next stage
 - `exec --stdin raw|json|jsonl`: feed pipeline input into subprocess stdin
+- Explicit quoted empty arguments are retained by both pipeline `exec` and SDK `exec`. Invocation shims preserve argument punctuation without shell expansion.
 - `where`, `pick`, `head`: data shaping
 - `json`, `table`: renderers
 - `approve`: approval gate (TTY prompt or `--emit` for OpenClaw integration)
 
-## Next steps
-
-- OpenClaw integration: ship as an optional OpenClaw plugin tool.
-
 ## SDK cancellation
 
 Pass an `AbortSignal` to `new Lobster({ signal })` to cancel SDK `exec()` stages,
@@ -303,6 +183,7 @@ Commands are re-run on resume, so they must be idempotent until `requestInput` r
 Use `lobster graph` to inspect workflow structure before execution.
 
 ```bash
+lobster graph --help
 lobster graph --file path/to/workflow.lobster
 lobster graph --file path/to/workflow.lobster --format mermaid
 lobster graph --file path/to/workflow.lobster --format dot
@@ -462,3 +343,9 @@ The limit counts bytes read from the response stream, including decompressed
 content. A declared Content-Length over the limit is also rejected immediately.
 Tool dispatch remains non-retryable after an overflow, as with other
 post-dispatch errors; `llm.invoke` retains its existing retry policy.
+
+## Development
+
+The source is one TypeScript package. `src/core` contains the embeddable tool API, cost tracking, and LLM accounting; `src/sdk` provides pipeline composition; `src/commands` holds the command registry and standard library. Workflow loading, expressions, dry-run rendering, and execution live under `src/workflows`. `src/state` owns atomic file persistence, locks, and resume capabilities. GitHub SDK recipes and built-in workflows share transport and snapshot helpers.
+
+Run `pnpm test`, `pnpm typecheck`, and `pnpm lint` before submitting changes. Tests compile into `dist/test` and use Node's test runner; platform-specific process tests run only where their OS primitives exist. Dependencies observe the two-day release-age policy in `pnpm-workspace.yaml`.

package/node_modules/@clawdbot/lobster/VISION.md

@@ -1,249 +1,26 @@
-# Lobster: Vision & Value Proposition
+# Lobster
 
-## One-liner
+Lobster executes repeatable workflows for OpenClaw. The host chooses a workflow, presents requests for approval or structured input, and resumes with the user's decision. Lobster owns deterministic execution and saved continuation state.
 
-**Lobster is safe automation for OpenClaw — workflows that ask before acting.**
+## Responsibilities
 
----
+- Compose JSON pipelines and workflow files with shell commands, native stages, conditions, loops, and parallel branches.
+- Pause at explicit approval or input gates and return a continuation token.
+- Persist snapshots and resume state locally, with atomic publication and cancellation-aware cleanup.
+- Report estimated LLM spend and enforce configured workflow cost limits.
 
-## What is Lobster?
+Approvals are explicit workflow steps. They protect actions placed after the gate; they are not an automatic sandbox for arbitrary shell commands or tool calls. Workflow authors must put gates before actions that require user consent.
 
-Lobster is a workflow runtime for OpenClaw. It lets you define multi-step automations that:
+## Host boundary
 
-- Run deterministically (no LLM re-planning each step)
-- Halt at checkpoints and ask for approval before side effects
-- Resume exactly where they left off
-- Remember what they've already processed
+OpenClaw owns intent, user interaction, authentication, provider integration, and tool execution policy. Lobster orchestrates those capabilities. It does not own OAuth or a credential store.
 
-Think of it as **IFTTT/Zapier for OpenClaw, but with human checkpoints**.
+The intended inference direction is gateway-only, as recorded in [#135](https://github.com/openclaw/lobster/issues/135). Current releases still support OpenClaw, Pi, HTTP, and injected adapters. The gateway contract and compatibility window must be settled before those configurations are retired; no new vendor adapters belong in the engine.
 
----
+Lobster currently renders static workflow graphs in Mermaid, DOT, and ASCII. A live dashboard and retained run history are separate product decisions, tracked in [#163](https://github.com/openclaw/lobster/issues/163).
 
-## The Problem Lobster Solves
+## Use
 
-### Today's workflow in OpenClaw
+Use a direct tool call for a one-off action. Use Lobster when a sequence is repeatable, needs saved state, or includes a human checkpoint. Deterministic steps avoid repeatedly asking a model to reconstruct the same execution sequence; model calls remain explicit stages where judgment is needed.
 
-```
-User: "Check my email, draft replies to anything urgent, and send them"
-
-What happens:
-1. LLM plans: "I should search emails first"
-2. Tool call: gmail.search
-3. LLM interprets results, plans next step
-4. Tool call: gmail.get (for each email)
-5. LLM drafts replies
-6. LLM decides to send
-7. Tool call: gmail.send
-... repeat for each email
-```
-
-**Problems:**
-- Many tool calls = many tokens = expensive
-- LLM decides when to send = risky (what if it misunderstands?)
-- No memory = tomorrow it re-triages the same emails
-- Not repeatable = you can't save this as an automation
-
-### With Lobster
-
-```
-OpenClaw calls: lobster.run("email.triage")
-
-What happens:
-1. Lobster fetches emails (deterministic)
-2. Lobster classifies them (rule-based)
-3. Lobster drafts replies (optional LLM step)
-4. Lobster HALTS: "Send 3 drafts? [approve/reject]"
-5. User approves
-6. Lobster sends
-
-Tomorrow: Lobster remembers cursor, only processes new emails
-```
-
-**One call. Deterministic. Safe. Stateful.**
-
----
-
-## Why Lobster Makes OpenClaw Better
-
-| Without Lobster | With Lobster |
-|-----------------|--------------|
-| LLM orchestrates every step | Deterministic pipeline, LLM only for judgment |
-| 10+ tool calls per workflow | 1 call to Lobster |
-| "Don't send until I confirm" (hope it listens) | `approve` halts execution until explicit resume |
-| Forgets what it did yesterday | Stateful — tracks cursors/checkpoints |
-| Hard to share automations | Workflows are code — shareable, versionable |
-
-### Token savings (real)
-A 10-step workflow today might cost 10 tool calls × LLM planning overhead.
-With Lobster: 1 tool call + compact structured output.
-
-### Safety (the killer feature)
-The `approve` primitive isn't a prompt hint — it's a **hard stop**. The workflow literally cannot continue until you resume it. No "oops, it sent 50 emails."
-
-### Memory (underrated)
-Workflows can persist state: "last processed email ID", "last PR SHA seen", etc. Tomorrow's run picks up where yesterday left off.
-
----
-
-## How Lobster Fits with OpenClaw
-
-```
-┌─────────────────────────────────────────────────┐
-│                   User                          │
-│         "triage my email daily"                 │
-└─────────────────────┬───────────────────────────┘
-                      │
-                      ▼
-┌─────────────────────────────────────────────────┐
-│                 OpenClaw                       │
-│   - Understands intent                          │
-│   - Chooses appropriate tool/workflow           │
-│   - Presents results and approval prompts       │
-└─────────────────────┬───────────────────────────┘
-                      │ lobster.run("email.triage")
-                      ▼
-┌─────────────────────────────────────────────────┐
-│                  Lobster                        │
-│   - Executes deterministic pipeline             │
-│   - Calls OpenClaw tools (gmail, trello, etc)  │
-│   - Halts at approval checkpoints               │
-│   - Returns structured result + resume token    │
-└─────────────────────────────────────────────────┘
-```
-
-**Key insight:** Lobster doesn't replace OpenClaw. It's the execution layer that makes OpenClaw's automations safe and efficient.
-
-- **OpenClaw** = the brain (understands what you want)
-- **Lobster** = the hands (executes workflows safely)
-- **Tools/Skills** = the capabilities (gmail, trello, github, etc.)
-
----
-
-## Who Should Use Lobster?
-
-### Average OpenClaw users (invisible benefit)
-They don't need to know Lobster exists. They just notice:
-- "Set up daily email triage" works better
-- Automations ask before sending/posting
-- Things don't get re-processed every day
-
-### Power users / tinkerers
-They can:
-- Customize workflows ("I want triage to also create Trello cards")
-- Write new workflows for their specific needs
-- Share workflows with the community
-
-### The OpenClaw ecosystem
-- Workflow recipes become a new category of shareable assets
-- Skills stay simple (just expose APIs)
-- Lobster handles the orchestration layer
-
----
-
-## Analogies That Work
-
-| If you know... | Lobster is like... |
-|----------------|-------------------|
-| IFTTT/Zapier | Multi-step version with approval checkpoints |
-| GitHub Actions | But for personal automation, not CI/CD |
-| AWS Step Functions | But local-first and human-in-the-loop |
-| Unix pipes | But for JSON objects, not text bytes |
-| Temporal | But 80/20 version for personal workflows |
-
-**Best analogy for most people:**
-> "Lobster is Zapier for OpenClaw, except it asks you before doing anything irreversible."
-
----
-
-## Why Not Build This Into OpenClaw Core?
-
-It could be. But the plugin architecture is intentional:
-
-1. **Core stays small** — OpenClaw is already complex
-2. **Faster iteration** — Lobster can evolve without core releases
-3. **Opt-in** — Not everyone needs workflow automation
-4. **Community** — Easier to contribute workflows than core changes
-5. **Ecosystem proof** — If plugins work for Lobster, they work for other capabilities
-
-OpenClaw explicitly provides a plugin boundary to enable this pattern. Lobster is the first proof that it works.
-
----
-
-## Example Workflows
-
-### Email triage (flagship)
-```
-gog.gmail.search --query "newer_than:1d" 
-  | email.normalize 
-  | email.classify 
-  | where bucket==needs_reply 
-  | draft.reply 
-  | approve --prompt "Send N replies?" 
-  | gog.gmail.send
-```
-
-### PR monitor
-```
-github.pr.get --repo org/repo --pr 123
-  | diff.last
-  | where changed==true
-  | notify --channel telegram --message "PR updated: {summary}"
-```
-
-### Daily planning
-```
-calendar.today
-  | join tasks.today
-  | prioritize
-  | format.plan
-  | approve --prompt "Post to #daily?"
-  | message.send --channel slack --to "#daily"
-```
-
-### Inbox → Trello
-```
-email.triage
-  | where bucket==needs_action
-  | to.trelloCard
-  | approve --prompt "Create N cards?"
-  | trello.card.create --list "Inbox"
-```
-
----
-
-## The USP (Unique Selling Proposition)
-
-**"Automations that ask before acting."**
-
-Other automation tools either:
-- Run blindly (IFTTT, Zapier) — scary for important actions
-- Require complex configuration for approvals
-- Don't integrate with your AI assistant
-
-Lobster is:
-- Native to OpenClaw (uses the same tools you already have)
-- Safe by default (approvals are a language primitive)
-- Invisible when you want (OpenClaw uses it automatically)
-- Customizable when you need (write your own workflows)
-
----
-
-## What Lobster Is NOT
-
-- **Not a terminal replacement** — You don't switch your shell to Lobster
-- **Not a general programming language** — It's for workflows, not apps
-- **Not trying to replace OpenClaw** — It makes OpenClaw better
-- **Not managing your secrets** — OpenClaw handles auth, Lobster orchestrates
-
----
-
-## Summary
-
-| Question | Answer |
-|----------|--------|
-| What is it? | Workflow runtime for OpenClaw |
-| One-liner? | Safe automation — workflows that ask before acting |
-| Why use it? | Cheaper, safer, stateful automations |
-| Who uses it? | Everyone (invisibly) or power users (directly) |
-| Why not in core? | Plugin architecture — core stays small, capabilities are extensions |
-| Best analogy? | Zapier for OpenClaw, but with approval checkpoints |
+See the [README](README.md) for working commands, workflow syntax, cancellation, output limits, and SDK examples.

package/node_modules/@clawdbot/lobster/bin/clawd.invoke.js

@@ -1,24 +1,5 @@
 #!/usr/bin/env node
 
-import { spawnSync } from "node:child_process";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { runInvoke } from "./invoke.js";
 
-function shellQuote(arg) {
-	if (/^[A-Za-z0-9_\-./:=@]+$/.test(arg)) return arg;
-	return `'${String(arg).replace(/'/g, `'\\''`)}'`;
-}
-
-const argv = process.argv.slice(2);
-const pipeline = ["clawd.invoke", ...argv.map(shellQuote)].join(" ");
-const lobsterBin = join(dirname(fileURLToPath(import.meta.url)), "lobster.js");
-
-const res = spawnSync(process.execPath, [lobsterBin, pipeline], {
-	stdio: "inherit",
-	env: process.env,
-});
-if (res.error) {
-	console.error(`clawd.invoke failed to spawn lobster: ${res.error.message}`);
-}
-
-process.exit(res.status ?? 1);
+runInvoke("clawd.invoke");

package/node_modules/@clawdbot/lobster/bin/invoke.js

@@ -0,0 +1,19 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+function quotePipelineArgument(value) {
+	// Escape for Lobster's double-quoted token syntax, not for a shell.
+	return `"${String(value).replace(/[\\"$`]/g, "\\$&")}"`;
+}
+
+export function runInvoke(commandName) {
+	const pipeline = [commandName, ...process.argv.slice(2).map(quotePipelineArgument)].join(" ");
+	const result = spawnSync(
+		process.execPath,
+		[fileURLToPath(new URL("./lobster.js", import.meta.url)), pipeline],
+		{ stdio: "inherit", env: process.env },
+	);
+	if (result.error)
+		console.error(`${commandName} failed to spawn lobster: ${result.error.message}`);
+	process.exit(result.status ?? 1);
+}

package/node_modules/@clawdbot/lobster/bin/lobster.js

@@ -1,24 +1,5 @@
 #!/usr/bin/env node
 
-import { existsSync } from "node:fs";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { dirname, join } from "node:path";
+import { runCli } from "../dist/src/cli.js";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-async function load() {
-	const distEntry = join(__dirname, "../dist/src/cli.js");
-	if (existsSync(distEntry)) {
-		return import(pathToFileURL(distEntry).href);
-	}
-	const srcEntry = join(__dirname, "../src/cli.js");
-	return import(pathToFileURL(srcEntry).href);
-}
-
-const mod = await load();
-if (typeof mod.runCli !== "function") {
-	throw new Error("lobster CLI entrypoint missing runCli()");
-}
-
-await mod.runCli(process.argv.slice(2));
+await runCli(process.argv.slice(2));

package/node_modules/@clawdbot/lobster/bin/openclaw.invoke.js

@@ -1,27 +1,5 @@
 #!/usr/bin/env node
 
-import { spawnSync } from "node:child_process";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { runInvoke } from "./invoke.js";
 
-function shellQuote(arg) {
-	// Conservative POSIX-ish quoting for embedding argv into a single pipeline string.
-	// Lobster's pipeline parser preserves quoted substrings.
-	if (/^[A-Za-z0-9_\-./:=@]+$/.test(arg)) return arg;
-	// single-quote, escaping embedded single quotes: ' -> '\''
-	return `'${String(arg).replace(/'/g, `'\\''`)}'`;
-}
-
-const argv = process.argv.slice(2);
-const pipeline = ["openclaw.invoke", ...argv.map(shellQuote)].join(" ");
-const lobsterBin = join(dirname(fileURLToPath(import.meta.url)), "lobster.js");
-
-const res = spawnSync(process.execPath, [lobsterBin, pipeline], {
-	stdio: "inherit",
-	env: process.env,
-});
-if (res.error) {
-	console.error(`openclaw.invoke failed to spawn lobster: ${res.error.message}`);
-}
-
-process.exit(res.status ?? 1);
+runInvoke("openclaw.invoke");