@openclaw/lobster 2026.5.24-beta.2 → 2026.5.26-beta.1

package/dist/index.js

@@ -7,12 +7,10 @@ import path from "node:path";
 import { Readable, Writable } from "node:stream";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
-import AjvPkg from "ajv";
 //#region extensions/lobster/src/lobster-ajv-cache.ts
 const installedSymbol = Symbol.for("openclaw.lobster.ajv-compile-cache.installed");
 const cacheSymbol = Symbol.for("openclaw.lobster.ajv-compile-cache.entries");
 const maxEntries = 512;
-const AjvCtor = AjvPkg;
 function stableJsonStringify(value, seen = /* @__PURE__ */ new WeakSet()) {
 	if (value === null || typeof value !== "object") return JSON.stringify(value);
 	if (seen.has(value)) throw new TypeError("Cannot cache cyclic JSON schema");
@@ -60,7 +58,17 @@ function rememberCompiledValidator(params) {
 		validate
 	});
 }
-function installLobsterAjvCompileCache() {
+async function resolveLobsterAjvConstructor(packageEntryPath) {
+	const ajvModule = await import(pathToFileURL(createRequire(packageEntryPath).resolve("ajv")).href);
+	return ajvModule.default ?? ajvModule;
+}
+async function installLobsterAjvCompileCache(packageEntryPath) {
+	let AjvCtor;
+	try {
+		AjvCtor = await resolveLobsterAjvConstructor(packageEntryPath);
+	} catch {
+		return;
+	}
 	const proto = AjvCtor.prototype;
 	if (proto[installedSymbol]) return;
 	const originalCompile = proto.compile;
@@ -230,9 +238,9 @@ async function withTimeout(timeoutMs, fn) {
 	});
 }
 async function loadEmbeddedToolRuntimeFromPackage(options = {}) {
-	installLobsterAjvCompileCache();
 	const importModule = options.importModule ?? (async (specifier) => await import(specifier));
-	const resolvePackageEntry = options.resolvePackageEntry ?? ((specifier) => lobsterRequire.resolve(specifier));
+	const packageEntryPath = (options.resolvePackageEntry ?? ((specifier) => lobsterRequire.resolve(specifier)))("@clawdbot/lobster");
+	await installLobsterAjvCompileCache(packageEntryPath);
 	let coreLoadError;
 	try {
 		return toEmbeddedToolRuntime(await importModule([
@@ -245,7 +253,7 @@ async function loadEmbeddedToolRuntimeFromPackage(options = {}) {
 	}
 	let fallbackLoadError;
 	try {
-		const packageRoot = findLobsterPackageRoot(resolvePackageEntry("@clawdbot/lobster"));
+		const packageRoot = findLobsterPackageRoot(packageEntryPath);
 		const coreRuntimeUrl = pathToFileURL(path.join(packageRoot, "dist/src/core/index.js")).href;
 		return toEmbeddedToolRuntime(await importModule(coreRuntimeUrl), coreRuntimeUrl);
 	} catch (error) {

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

@@ -1,4 +1,4 @@
-# Lobster
+# 🦞 Lobster
 
 An OpenClaw-native workflow shell: typed (JSON-first) pipelines, jobs, and approval gates.
 
@@ -208,6 +208,38 @@ Notes:
 - `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.
+
+## 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
 
@@ -233,6 +265,23 @@ Built-in providers today:
 
 `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.