@plateforme-ai/lobster 2026.6.12

package/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/README.md

@@ -0,0 +1,353 @@
+# 🦞 Lobster
+
+![Lobster banner](docs/assets/readme-banner.jpg)
+
+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.
+- Use `retry`, `timeout_ms`, and `on_error` per step to control transient-failure behavior and recovery.
+- Approval steps can optionally enforce identity constraints:
+  - `approval.required_approver` (or `requiredApprover`) requires an exact approver id.
+  - `approval.require_different_approver` (or `requireDifferentApprover`) requires approver id to differ from initiator.
+  - `approval.initiated_by` (or `initiatedBy`) sets the initiator id for comparison.
+  - `LOBSTER_APPROVAL_INITIATED_BY` can provide a default initiator id at run time.
+  - `LOBSTER_APPROVAL_APPROVED_BY` is used at resume/approval time for identity checks.
+
+### Command-level input requests
+
+Pipeline commands can call `ctx.requestInput({ prompt, responseSchema, defaults, subject, suspendedState })` to pause in tool mode, workflows, or the SDK and resume the same command after a structured response. CLI/tool resume tokens store only a state key; the persisted state validates the suspended request metadata before returning the submitted response to the command. SDK same-command resumes store the command frame in the configured SDK state directory.
+
+Commands are re-run on resume, so they must be idempotent until `requestInput` returns. Array-backed command input is snapshotted with bounds for replay; lazy stream input is not buffered and requires a compact JSON `suspendedState` supplied by the command. On resume, call `ctx.requestInput.getSuspendedState()` before reading lazy input to restore that command-owned continuation state.
+
+## Visualizing workflows
+
+Use `lobster graph` to inspect workflow structure before execution.
+
+```bash
+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
+lobster graph --file path/to/workflow.lobster --format ascii
+lobster graph --file path/to/workflow.lobster --args-json '{"location":"Seattle"}'
+```
+
+What gets visualized:
+
+- each workflow step as a node (`run`, `pipeline`, `approval`, etc.)
+- data-flow edges from `stdin: $step.stdout` / `$step.json` references
+- conditional dependencies from `when:` / `condition:` expressions
+- approval gates as diamond-shaped nodes in `mermaid` and `dot` output
+
+Format notes:
+
+- `mermaid` (default): emits `flowchart TD` text for GitHub/Markdown rendering
+- `dot`: emits Graphviz DOT syntax
+- `ascii`: emits a terminal-friendly node/edge list
+
+## 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`
+
+Workflow `_meta.cost` and `cost_limit` use a static pricing table plus optional overrides from `LOBSTER_LLM_PRICING_JSON`, for example `{"my-model":{"input":1.0,"output":2.0}}` in USD per million tokens. Unknown or missing model IDs still record token counts with zero estimated cost, but Lobster warns on stderr so stale or missing pricing does not fail silently.
+
+`llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.
+
+### `pipeline:` vs `run:` for LLM calls
+
+- Use `pipeline:` for `llm.invoke` and `llm_task.invoke` (they are Lobster pipeline stages, not shell executables).
+- Use `run:` only for real binaries in your shell (for example `openclaw.invoke`).
+
+Example (`stdin` from a prior step is passed to the LLM as artifacts):
+
+```yaml
+steps:
+  - id: make_words
+    run: echo "One two three four five six"
+
+  - id: count_words
+    pipeline: llm_task.invoke --prompt "How many words have been pasted below?"
+    stdin: $make_words.stdout
+```
+
+## 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/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/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/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/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);