@openclaw/lobster 2026.5.20-beta.2 → 2026.5.22

package/node_modules/@clawdbot/lobster/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vignesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,294 @@
+# Lobster
+
+An OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.
+
+
+## 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.
+
+### 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"
+    }
+  }
+]
+```
+### 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"
+    }
+  }
+]
+```
+
+## Goals
+
+
+- Typed pipelines (objects/arrays), not text pipes.
+- Local-first execution.
+- No new auth surface: Lobster must not own OAuth/tokens.
+- Composable macros that OpenClaw (or any agent) can invoke in one step to save tokens.
+
+## Quick start
+
+From this folder:
+
+- `pnpm install`
+- `pnpm test`
+- `pnpm lint`
+- `node ./bin/lobster.js --help`
+- `node ./bin/lobster.js doctor`
+- `node ./bin/lobster.js "exec --json --shell 'echo [1,2,3]' | where '0>=0' | json"`
+
+### Notes
+
+- `pnpm test` runs `tsc` and then executes tests against `dist/`.
+- `bin/lobster.js` prefers the compiled entrypoint in `dist/` when present.
+## Commands
+
+- `exec`: run OS commands
+- `exec --stdin raw|json|jsonl`: feed pipeline input into subprocess stdin
+- `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.
+
+## Workflow files
+
+Lobster workflow files are meant to read like small scripts:
+
+- `run:` or `command:` for deterministic shell/CLI steps
+- `pipeline:` for native Lobster stages like `llm.invoke`
+- `approval:` for hard workflow gates between steps
+- `stdin: $step.stdout` or `stdin: $step.json` to pass data forward
+
+```
+lobster run path/to/workflow.lobster
+lobster run --file path/to/workflow.lobster --args-json '{"tag":"family"}'
+```
+
+Example file:
+
+```yaml
+name: jacket-advice
+args:
+  location:
+    default: Phoenix
+steps:
+  - id: fetch
+    run: weather --json ${location}
+
+  - id: confirm
+    approval: Want jacket advice from the LLM?
+    stdin: $fetch.json
+
+  - id: advice
+    pipeline: >
+      llm.invoke --prompt "Given this weather data, should I wear a jacket?
+      Be concise and return JSON."
+    stdin: $fetch.json
+    when: $confirm.approved
+```
+
+Notes:
+
+- `run:` and `command:` are equivalent; `run:` is the preferred spelling for new files.
+- `pipeline:` shares the same args/env/results model as shell steps, so later steps can still reference `$step.stdout` or `$step.json`.
+- If you need a human checkpoint before an LLM call, use a dedicated `approval:` step in the workflow file rather than `approve` inside the nested pipeline.
+- `cwd`, `env`, `stdin`, `when`, and `condition` work for both shell and pipeline steps.
+
+## Calling LLMs from workflows
+
+Use `llm.invoke` from a native `pipeline:` step for model-backed work:
+
+```bash
+llm.invoke --prompt 'Summarize this diff'
+llm.invoke --provider openclaw --prompt 'Summarize this diff'
+llm.invoke --provider pi --prompt 'Summarize this diff'
+```
+
+Provider resolution order:
+
+- `--provider`
+- `LOBSTER_LLM_PROVIDER`
+- auto-detect from environment
+
+Built-in providers today:
+
+- `openclaw` via `OPENCLAW_URL` / `OPENCLAW_TOKEN`
+- `pi` via `LOBSTER_PI_LLM_ADAPTER_URL` (typically supplied by the Pi extension)
+- `http` via `LOBSTER_LLM_ADAPTER_URL`
+
+`llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.
+
+## Calling OpenClaw tools from workflows
+
+Shell `run:` steps execute in your system shell, so OpenClaw tool calls there must be real executables.
+
+If you install Lobster via npm/pnpm, it installs a small shim executable named:
+
+- `openclaw.invoke` (preferred)
+- `clawd.invoke` (alias)
+
+These shims forward to the Lobster pipeline command of the same name.
+
+### Example: invoke llm-task
+
+Prereqs:
+
+- `OPENCLAW_URL` points at a running OpenClaw gateway
+- optionally `OPENCLAW_TOKEN` if auth is enabled
+
+```bash
+export OPENCLAW_URL=http://127.0.0.1:18789
+# export OPENCLAW_TOKEN=...
+```
+
+In a workflow:
+
+```yaml
+name: hello-world
+steps:
+  - id: greeting
+    run: >
+      openclaw.invoke --tool llm-task --action json --args-json '{"prompt":"Hello"}'
+```
+
+### Passing data between steps (no temp files)
+
+Use `stdin: $stepId.stdout` to pipe output from one step into the next.
+
+## Args and shell-safety
+
+`${arg}` substitution is a raw string replace into the shell command text.
+
+For anything that may contain quotes, `$`, backticks, or newlines, prefer env vars:
+
+- every resolved workflow arg is exposed as `LOBSTER_ARG_<NAME>` (uppercased, non-alnum → `_`)
+- the full args object is also available as `LOBSTER_ARGS_JSON`
+
+Example:
+
+```yaml
+args:
+  text:
+    default: ""
+steps:
+  - id: safe
+    env:
+      TEXT: "$LOBSTER_ARG_TEXT"
+    command: |
+      jq -n --arg text "$TEXT" '{"result": $text}'
+```

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

@@ -0,0 +1,249 @@
+# Lobster: Vision & Value Proposition
+
+## One-liner
+
+**Lobster is safe automation for OpenClaw — workflows that ask before acting.**
+
+---
+
+## What is Lobster?
+
+Lobster is a workflow runtime for OpenClaw. It lets you define multi-step automations that:
+
+- 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
+
+Think of it as **IFTTT/Zapier for OpenClaw, but with human checkpoints**.
+
+---
+
+## The Problem Lobster Solves
+
+### Today's workflow in OpenClaw
+
+```
+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 |

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

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+
+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 res = spawnSync('lobster', [pipeline], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(res.status ?? 1);

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, join } from "node:path";
+
+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));

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+
+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 res = spawnSync('lobster', [pipeline], {
+  stdio: 'inherit',
+  env: process.env,
+});
+
+process.exit(res.status ?? 1);