@openclaw/lobster 2026.9.4 → 2026.9.6

package/assets/activity.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <path fill="currentColor" stroke="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M8.2 10 A5.2 5.2 0 1 0 8.2 20.4 A5.2 5.2 0 0 0 8.2 10 Z M10.2 20 C14.5 20.8 19 18.6 22.3 13.2 C21 12.9 19.7 12.7 18.4 12.8 L17.5 14.6 L16 12.9 L14.3 14.5 L13.5 13 L11.5 14.2 Z" />
+  <path fill="currentColor" stroke="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" transform="rotate(-10 8.6 11)" d="M5.6 12.2 C5.2 5.6 10.4 1.4 15.6 2 C19.4 2.6 21.8 5.2 22.6 8.2 C20.9 7.7 19.2 7.6 17.6 7.9 L16.9 6.3 L15.2 8.5 C13.6 9.4 12.2 10.9 11.6 12.4 L6.8 13 Z" />
+</svg>

package/dist/index.js

@@ -219,18 +219,18 @@ async function executeManagedLobsterFlow(params, flow) {
 		if (!envelope.ok) return {
 			ok: false,
 			flow,
-			mutation: params.taskFlow.fail(flowMutation),
+			mutation: await params.taskFlow.fail(flowMutation),
 			error: new Error(envelope.error.message)
 		};
 		return {
 			ok: true,
 			envelope,
 			flow,
-			mutation: envelope.status === "needs_approval" ? params.taskFlow.setWaiting({
+			mutation: envelope.status === "needs_approval" ? await params.taskFlow.setWaiting({
 				...flowMutation,
 				currentStep: params.waitingStep ?? "await_lobster_approval",
 				waitJson: buildApprovalWaitState(envelope)
-			}) : params.taskFlow.finish(flowMutation)
+			}) : await params.taskFlow.finish(flowMutation)
 		};
 	} catch (error) {
 		const err = error instanceof Error ? error : new Error(String(error));
@@ -238,7 +238,7 @@ async function executeManagedLobsterFlow(params, flow) {
 			return {
 				ok: false,
 				flow,
-				mutation: params.taskFlow.fail({
+				mutation: await params.taskFlow.fail({
 					flowId: flow.flowId,
 					expectedRevision: flow.revision
 				}),
@@ -260,7 +260,7 @@ async function runManagedLobsterFlow(params) {
 		currentStep: params.currentStep ?? "run_lobster",
 		...params.stateJson !== void 0 ? { stateJson: params.stateJson } : {}
 	};
-	const flow = params.taskFlow.tryCreateManaged ? params.taskFlow.tryCreateManaged(createFlowParams) : params.taskFlow.createManaged(createFlowParams);
+	const flow = await params.taskFlow.tryCreateManaged(createFlowParams);
 	if (!flow) return {
 		ok: false,
 		error: /* @__PURE__ */ new Error("TaskFlow persistence failed.")
@@ -268,7 +268,31 @@ async function runManagedLobsterFlow(params) {
 	return await executeManagedLobsterFlow(params, flow);
 }
 async function resumeManagedLobsterFlow(params) {
-	const resumed = params.taskFlow.resume({
+	const saved = await params.taskFlow.get(params.flowId);
+	if (!saved || saved.syncMode !== "managed" || saved.endedAt !== void 0 || saved.cancelRequestedAt !== void 0 || saved.status !== "waiting" && saved.status !== "blocked") return {
+		ok: false,
+		error: /* @__PURE__ */ new Error("TaskFlow has no resumable Lobster checkpoint.")
+	};
+	const wait = saved.waitJson;
+	if (!wait || typeof wait !== "object" || Array.isArray(wait) || wait.kind !== "lobster_approval") return {
+		ok: false,
+		error: /* @__PURE__ */ new Error("TaskFlow is not waiting for Lobster approval.")
+	};
+	const token = typeof wait.resumeToken === "string" ? wait.resumeToken : void 0;
+	const approvalId = typeof wait.approvalId === "string" ? wait.approvalId : void 0;
+	if (!token && !approvalId || params.runnerParams.token !== void 0 && params.runnerParams.token.trim() !== token || params.runnerParams.approvalId !== void 0 && params.runnerParams.approvalId.trim() !== approvalId) return {
+		ok: false,
+		error: /* @__PURE__ */ new Error("Lobster checkpoint does not match the selected TaskFlow.")
+	};
+	const runnerParams = {
+		...params.runnerParams,
+		...params.runnerParams.token || params.runnerParams.approvalId ? {} : token ? { token } : { approvalId }
+	};
+	if (saved.revision !== params.expectedRevision) return {
+		ok: false,
+		error: /* @__PURE__ */ new Error("TaskFlow resume failed: revision_conflict")
+	};
+	const resumed = await params.taskFlow.resume({
 		flowId: params.flowId,
 		expectedRevision: params.expectedRevision,
 		status: "running",
@@ -279,7 +303,10 @@ async function resumeManagedLobsterFlow(params) {
 		mutation: resumed,
 		error: /* @__PURE__ */ new Error(`TaskFlow resume failed: ${resumed.code}`)
 	};
-	return await executeManagedLobsterFlow(params, resumed.flow);
+	return await executeManagedLobsterFlow({
+		...params,
+		runnerParams
+	}, resumed.flow);
 }
 //#endregion
 //#region extensions/lobster/src/lobster-tool.ts
@@ -350,7 +377,6 @@ function parseManagedFlowParams(action, params, runnerParams) {
 	if (!flowId) throw new Error("flowId required when using managed TaskFlow resume mode");
 	if (expectedRevision === void 0) throw new Error("flowExpectedRevision required when using managed TaskFlow resume mode");
 	const credentialParams = token ? { token: runnerParams.token ?? token } : approvalId ? { approvalId: runnerParams.approvalId ?? approvalId } : null;
-	if (!credentialParams) throw new Error("token or approvalId required when using managed TaskFlow resume mode");
 	if (approve === void 0) throw new Error("approve required when using managed TaskFlow resume mode");
 	return {
 		action,
@@ -397,7 +423,7 @@ function createLobsterTool(api, options) {
 			flowControllerId: Type.Optional(Type.String()),
 			flowGoal: Type.Optional(Type.String()),
 			flowStateJson: Type.Optional(Type.String()),
-			flowId: Type.Optional(Type.String()),
+			flowId: Type.Optional(Type.String({ description: "Managed flow to resume. Its saved approval checkpoint is used when token and approvalId are omitted." })),
 			flowExpectedRevision: optionalNonNegativeIntegerSchema(),
 			flowCurrentStep: Type.Optional(Type.String()),
 			flowWaitingStep: Type.Optional(Type.String())
@@ -459,7 +485,10 @@ var lobster_default = definePluginEntry({
 	register(api) {
 		api.registerTool(((ctx) => {
 			if (ctx.sandboxed) return null;
-			return createLobsterTool(api, { taskFlow: api.runtime?.tasks.managedFlows && ctx.sessionKey ? api.runtime.tasks.managedFlows.fromToolContext(ctx) : void 0 });
+			return createLobsterTool(api, { taskFlow: api.runtime && ctx.sessionKey ? {
+				...api.runtime.tasks.async.managedFlows.fromToolContext(ctx),
+				cancel: api.runtime.tasks.managedFlows.fromToolContext(ctx).cancel
+			} : void 0 });
 		}), { optional: true });
 	}
 });

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,18 +36,85 @@ 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
+`LOBSTER_MAX_OUTPUT_BYTES` to a positive integer to opt into a byte limit **per
+stream, per process**. Unset or empty means unlimited; zero, negative, fractional,
+and non-numeric values are rejected before a process starts. This applies to
+CLI `exec`, workflow shell steps, SDK `exec`/shell calls, GitHub recipes, and Gog
+commands. The existing `openclaw.agent` 10 MiB limit remains in place; an opted-in
+limit can lower it.
+
+```bash
+LOBSTER_MAX_OUTPUT_BYTES=1048576 lobster run --mode tool 'exec my-command'
+```
+
+Use workflow or step `env` to scope the limit:
+
+```yaml
+steps:
+  - id: bounded
+    env:
+      LOBSTER_MAX_OUTPUT_BYTES: "1048576"
+    run: my-command
+```
+
+SDK callers set the same variable in `new Lobster({ env: { ...process.env,
+LOBSTER_MAX_OUTPUT_BYTES: "1048576" } })`. Values exactly at the limit succeed;
+overflow terminates the process tree and returns an error without partial
+output. POSIX capped calls own a process group so background producers cannot
+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
+## SDK cancellation
+
+Pass an `AbortSignal` to `new Lobster({ signal })` to cancel SDK `exec()` stages,
+including `exec(command, { shell: true })`. The signal is retained by `clone()`
+and forwarded when a pipeline resumes. Aborting terminates the running child
+process tree before `run()` or `resume()` returns an error result containing the
+abort reason. A signal that is already aborted prevents the command from starting.
+
+```js
+import { Lobster, exec } from '@clawdbot/lobster';
+
+const controller = new AbortController();
+const pending = new Lobster({ signal: controller.signal })
+  .pipe(exec('node long-task.js', { json: false }))
+  .run();
+// When the host needs to stop the command:
+controller.abort(new Error('Host cancelled the command'));
+const result = await pending;
+```
+
+Custom stages receive the signal as `ctx.signal` and must cooperate with it to
+cancel their own work.
+
+## GitHub recipe cancellation
+
+The SDK GitHub recipes accept an `AbortSignal` in both
+`prMonitor({ repo, pr, signal })` and `prMonitorNotify({ repo, pr, signal })`.
+Aborting stops the running GitHub CLI child before the recipe returns an error
+result containing the abort reason. A cancelled fetch does not update the saved
+PR snapshot or emit a notification.
 
-- OpenClaw integration: ship as an optional OpenClaw plugin tool.
+For a manually composed pipeline, pass the signal to
+`new Lobster({ signal }).pipe(ghPrView({ repo, pr }))`. Custom stages receive
+`ctx.signal` and must cooperate with it to cancel their own work.
 
 ## Workflow files
 
@@ -211,6 +160,7 @@ Notes:
 - 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.
+- On `for_each`, these policies cover the entire loop: each attempt gets one timeout budget (including batch pauses), and retry restarts at the first item. Previously completed children may run again, so only enable loop retries for work that is safe to repeat. A `cost_limit` stop or an attempted OpenClaw dispatch prevents retries; paid LLM usage is checked even when a later pipeline command fails. `on_error: continue` records `$loop.error` and proceeds to the next workflow step; `skip_rest` skips the remaining workflow steps.
 - 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.
@@ -218,6 +168,10 @@ Notes:
   - `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.
 
+### Retries after OpenClaw dispatch
+
+`openclaw.invoke` (including `clawd.invoke`) and `openclaw.agent` suppress automatic workflow-step retries once dispatch is attempted. This applies to timeouts, HTTP or process failures, and errors in later commands of the same pipeline step, even when `retry.max` is greater than one. A failed local request cannot establish whether a remote action already completed. Read-only and dry-run requests use the same conservative rule: Lobster does not know the remote tool’s retry guarantees, and the [OpenClaw gateway currently ignores `dryRun`](https://docs.openclaw.ai/gateway/tools-invoke-http-api#request-body). The flag does not prevent tool execution. Check the remote outcome before manually running the step again. `llm.invoke` retains its existing retry policy.
+
 ### 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.
@@ -229,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
@@ -271,13 +226,28 @@ Built-in providers today:
 - `pi` via `LOBSTER_PI_LLM_ADAPTER_URL` (typically supplied by the Pi extension)
 - `http` via `LOBSTER_LLM_ADAPTER_URL`
 
+A host embedding Lobster can supply its own adapters through `ctx.llmAdapters`. Step `timeout_ms` and workflow cancellation reach an adapter as `ctx.signal`: Lobster stops waiting as soon as that signal aborts, so the step fails or retries on time either way, but it cannot cancel work an adapter has already started. An injected adapter should observe `ctx.signal` and abort its own request — otherwise a timed-out step can leave a model call running, and billed, in the background.
+
 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.
 
+A cached or replayed answer is not billed again: a model call is counted once, in the run that made it, however many later steps re-emit its answer. This holds while the answer stays inside Lobster: through pipelines, renderers, projections, run state, `workflow:` steps and a resume. It does not survive a stage that hands the items to an external process and reads them back — `exec --stdin json --json ...` — because what comes back is whatever that process printed, and Lobster cannot tell a faithful copy of a replay from a fresh claim to have made the call. Such a step is billed as a call, which is what earlier versions did everywhere. A `workflow:` step counts what its sub-workflow spent, and a replay the sub-workflow returned is not billed a second time by the run that composed it. Spend also survives a pause — a workflow that stops at an approval or `input` gate keeps what it has recorded, so `_meta.cost` covers the whole run after a resume and `cost_limit` applies to the whole run rather than to the steps after the last gate.
+
 `llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.
 
+### Calling configured OpenClaw agents
+
+Use `openclaw.agent` when a workflow needs a configured OpenClaw agent rather than a direct model call:
+
+```bash
+openclaw.agent --agent ops --prompt 'Summarize these logs'
+openclaw.agent --agent ops --session-key incident-42 --model openai/gpt-5.4 --prompt 'Continue the investigation'
+```
+
+The command delegates agent identity, model defaults and overrides, sessions, authentication, and execution to the installed `openclaw agent` CLI. It accepts `--agent`, `--session-key`, `--session-id`, `--model`, `--thinking`, `--timeout`, and `--local`, and returns OpenClaw's structured `--json` response. Pipeline input is appended to the prompt as labeled JSONL.
+
 ### `pipeline:` vs `run:` for LLM calls
 
-- Use `pipeline:` for `llm.invoke` and `llm_task.invoke` (they are Lobster pipeline stages, not shell executables).
+- Use `pipeline:` for `openclaw.agent`, `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):
@@ -351,3 +321,31 @@ steps:
     command: |
       jq -n --arg text "$TEXT" '{"result": $text}'
 ```
+
+## HTTP response limits
+
+HTTP response bodies remain unlimited by default. Set
+`LOBSTER_MAX_HTTP_RESPONSE_BYTES` to a positive integer to opt into a per-response
+byte limit for `openclaw.invoke`/`clawd.invoke` and the built-in OpenClaw, HTTP,
+and Pi `llm.invoke` adapters. Unset or empty means unlimited; invalid or non-positive
+values fail before dispatch. Host-injected adapters own their transport limits.
+
+```bash
+LOBSTER_MAX_HTTP_RESPONSE_BYTES=1048576 lobster run --mode tool 'openclaw.invoke --tool example --action read'
+```
+
+Workflow and step `env` can set the same variable. SDK integrations pass it in
+their environment (`new Lobster({ env: { ...process.env,
+LOBSTER_MAX_HTTP_RESPONSE_BYTES: "1048576" } })` or the tool-runtime context).
+Responses exactly at the limit succeed. Oversized declared or streamed bodies
+are cancelled and rejected before JSON parsing; no partial response is returned.
+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`.