@openclaw/lobster 2026.1.29

package/README.md

@@ -0,0 +1,80 @@
+# Lobster (plugin)
+
+Adds the `lobster` agent tool as an **optional** plugin tool.
+
+## What this is
+
+- Lobster is a standalone workflow shell (typed JSON-first pipelines + approvals/resume).
+- This plugin integrates Lobster with OpenClaw *without core changes*.
+
+## Enable
+
+Because this tool can trigger side effects (via workflows), it is registered with `optional: true`.
+
+Enable it in an agent allowlist:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "lobster" // plugin id (enables all tools from this plugin)
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Using `openclaw.invoke` (Lobster → OpenClaw tools)
+
+Some Lobster pipelines may include a `openclaw.invoke` step to call back into OpenClaw tools/plugins (for example: `gog` for Google Workspace, `gh` for GitHub, `message.send`, etc.).
+
+For this to work, the OpenClaw Gateway must expose the tool bridge endpoint and the target tool must be allowed by policy:
+
+- OpenClaw provides an HTTP endpoint: `POST /tools/invoke`.
+- The request is gated by **gateway auth** (e.g. `Authorization: Bearer …` when token auth is enabled).
+- The invoked tool is gated by **tool policy** (global + per-agent + provider + group policy). If the tool is not allowed, OpenClaw returns `404 Tool not available`.
+
+### Allowlisting recommended
+
+To avoid letting workflows call arbitrary tools, set a tight allowlist on the agent that will be used by `openclaw.invoke`.
+
+Example (allow only a small set of tools):
+
+```jsonc
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "lobster",
+            "web_fetch",
+            "web_search",
+            "gog",
+            "gh"
+          ],
+          "deny": ["gateway"]
+        }
+      }
+    ]
+  }
+}
+```
+
+Notes:
+- If `tools.allow` is omitted or empty, it behaves like "allow everything (except denied)". For a real allowlist, set a **non-empty** `allow`.
+- Tool names depend on which plugins you have installed/enabled.
+
+## Security
+
+- Runs the `lobster` executable as a local subprocess.
+- Does not manage OAuth/tokens.
+- Uses timeouts, stdout caps, and strict JSON envelope parsing.
+- Prefer an absolute `lobsterPath` in production to avoid PATH hijack.

package/SKILL.md

@@ -0,0 +1,90 @@
+# Lobster
+
+Lobster executes multi-step workflows with approval checkpoints. Use it when:
+
+- User wants a repeatable automation (triage, monitor, sync)
+- Actions need human approval before executing (send, post, delete)
+- Multiple tool calls should run as one deterministic operation
+
+## When to use Lobster
+
+| User intent | Use Lobster? |
+|-------------|--------------|
+| "Triage my email" | Yes — multi-step, may send replies |
+| "Send a message" | No — single action, use message tool directly |
+| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval |
+| "What's the weather?" | No — simple query |
+| "Monitor this PR and notify me of changes" | Yes — stateful, recurring |
+
+## Basic usage
+
+### Run a pipeline
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
+}
+```
+
+Returns structured result:
+```json
+{
+  "protocolVersion": 1,
+  "ok": true,
+  "status": "ok",
+  "output": [{ "summary": {...}, "items": [...] }],
+  "requiresApproval": null
+}
+```
+
+### Handle approval
+
+If the workflow needs approval:
+```json
+{
+  "status": "needs_approval",
+  "output": [],
+  "requiresApproval": {
+    "prompt": "Send 3 draft replies?",
+    "items": [...],
+    "resumeToken": "..."
+  }
+}
+```
+
+Present the prompt to the user. If they approve:
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+## Example workflows
+
+### Email triage
+```
+gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
+```
+Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
+
+### Email triage with approval gate
+```
+gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
+```
+Same as above, but halts for approval before returning.
+
+## Key behaviors
+
+- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
+- **Approval gates**: `approve` command halts execution, returns token
+- **Resumable**: Use `resume` action with token to continue
+- **Structured output**: Always returns JSON envelope with `protocolVersion`
+
+## Don't use Lobster for
+
+- Simple single-action requests (just use the tool directly)
+- Queries that need LLM interpretation mid-flow
+- One-off tasks that won't be repeated

package/index.ts

@@ -0,0 +1,13 @@
+import type { OpenClawPluginApi } from "../../src/plugins/types.js";
+
+import { createLobsterTool } from "./src/lobster-tool.js";
+
+export default function register(api: OpenClawPluginApi) {
+  api.registerTool(
+    (ctx) => {
+      if (ctx.sandboxed) return null;
+      return createLobsterTool(api);
+    },
+    { optional: true },
+  );
+}

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "lobster",
+  "name": "Lobster",
+  "description": "Typed workflow tool with resumable approvals.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@openclaw/lobster",
+  "version": "2026.1.29",
+  "type": "module",
+  "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/lobster-tool.test.ts

@@ -0,0 +1,143 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "../../../src/plugins/types.js";
+import { createLobsterTool } from "./lobster-tool.js";
+
+async function writeFakeLobsterScript(scriptBody: string, prefix = "openclaw-lobster-plugin-") {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  const isWindows = process.platform === "win32";
+
+  if (isWindows) {
+    const scriptPath = path.join(dir, "lobster.js");
+    const cmdPath = path.join(dir, "lobster.cmd");
+    await fs.writeFile(scriptPath, scriptBody, { encoding: "utf8" });
+    const cmd = `@echo off\r\n"${process.execPath}" "${scriptPath}" %*\r\n`;
+    await fs.writeFile(cmdPath, cmd, { encoding: "utf8" });
+    return { dir, binPath: cmdPath };
+  }
+
+  const binPath = path.join(dir, "lobster");
+  const file = `#!/usr/bin/env node\n${scriptBody}\n`;
+  await fs.writeFile(binPath, file, { encoding: "utf8", mode: 0o755 });
+  return { dir, binPath };
+}
+
+async function writeFakeLobster(params: { payload: unknown }) {
+  const scriptBody =
+    `const payload = ${JSON.stringify(params.payload)};\n` +
+    `process.stdout.write(JSON.stringify(payload));\n`;
+  return await writeFakeLobsterScript(scriptBody);
+}
+
+function fakeApi(): OpenClawPluginApi {
+  return {
+    id: "lobster",
+    name: "lobster",
+    source: "test",
+    config: {} as any,
+    runtime: { version: "test" } as any,
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    registerTool() {},
+    registerHttpHandler() {},
+    registerChannel() {},
+    registerGatewayMethod() {},
+    registerCli() {},
+    registerService() {},
+    registerProvider() {},
+    resolvePath: (p) => p,
+  };
+}
+
+function fakeCtx(overrides: Partial<OpenClawPluginToolContext> = {}): OpenClawPluginToolContext {
+  return {
+    config: {} as any,
+    workspaceDir: "/tmp",
+    agentDir: "/tmp",
+    agentId: "main",
+    sessionKey: "main",
+    messageChannel: undefined,
+    agentAccountId: undefined,
+    sandboxed: false,
+    ...overrides,
+  };
+}
+
+describe("lobster plugin tool", () => {
+  it("runs lobster and returns parsed envelope in details", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [{ hello: "world" }], requiresApproval: null },
+    });
+
+    const tool = createLobsterTool(fakeApi());
+    const res = await tool.execute("call1", {
+      action: "run",
+      pipeline: "noop",
+      lobsterPath: fake.binPath,
+      timeoutMs: 1000,
+    });
+
+    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+  });
+
+  it("tolerates noisy stdout before the JSON envelope", async () => {
+    const payload = { ok: true, status: "ok", output: [], requiresApproval: null };
+    const { binPath } = await writeFakeLobsterScript(
+      `const payload = ${JSON.stringify(payload)};\n` +
+        `console.log("noise before json");\n` +
+        `process.stdout.write(JSON.stringify(payload));\n`,
+      "openclaw-lobster-plugin-noisy-",
+    );
+
+    const tool = createLobsterTool(fakeApi());
+    const res = await tool.execute("call-noisy", {
+      action: "run",
+      pipeline: "noop",
+      lobsterPath: binPath,
+      timeoutMs: 1000,
+    });
+
+    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+  });
+
+  it("requires absolute lobsterPath when provided", async () => {
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call2", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: "./lobster",
+      }),
+    ).rejects.toThrow(/absolute path/);
+  });
+
+  it("rejects invalid JSON from lobster", async () => {
+    const { binPath } = await writeFakeLobsterScript(
+      `process.stdout.write("nope");\n`,
+      "openclaw-lobster-plugin-bad-",
+    );
+
+    const tool = createLobsterTool(fakeApi());
+    await expect(
+      tool.execute("call3", {
+        action: "run",
+        pipeline: "noop",
+        lobsterPath: binPath,
+      }),
+    ).rejects.toThrow(/invalid JSON/);
+  });
+
+  it("can be gated off in sandboxed contexts", async () => {
+    const api = fakeApi();
+    const factoryTool = (ctx: OpenClawPluginToolContext) => {
+      if (ctx.sandboxed) return null;
+      return createLobsterTool(api);
+    };
+
+    expect(factoryTool(fakeCtx({ sandboxed: true }))).toBeNull();
+    expect(factoryTool(fakeCtx({ sandboxed: false }))?.name).toBe("lobster");
+  });
+});

package/src/lobster-tool.ts

@@ -0,0 +1,240 @@
+import { Type } from "@sinclair/typebox";
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+import type { OpenClawPluginApi } from "../../../src/plugins/types.js";
+
+type LobsterEnvelope =
+  | {
+      ok: true;
+      status: "ok" | "needs_approval" | "cancelled";
+      output: unknown[];
+      requiresApproval: null | {
+        type: "approval_request";
+        prompt: string;
+        items: unknown[];
+        resumeToken?: string;
+      };
+    }
+  | {
+      ok: false;
+      error: { type?: string; message: string };
+    };
+
+function resolveExecutablePath(lobsterPathRaw: string | undefined) {
+  const lobsterPath = lobsterPathRaw?.trim() || "lobster";
+  if (lobsterPath !== "lobster" && !path.isAbsolute(lobsterPath)) {
+    throw new Error("lobsterPath must be an absolute path (or omit to use PATH)");
+  }
+  return lobsterPath;
+}
+
+function isWindowsSpawnEINVAL(err: unknown) {
+  if (!err || typeof err !== "object") return false;
+  const code = (err as { code?: unknown }).code;
+  return code === "EINVAL";
+}
+
+async function runLobsterSubprocessOnce(
+  params: {
+    execPath: string;
+    argv: string[];
+    cwd: string;
+    timeoutMs: number;
+    maxStdoutBytes: number;
+  },
+  useShell: boolean,
+) {
+  const { execPath, argv, cwd } = params;
+  const timeoutMs = Math.max(200, params.timeoutMs);
+  const maxStdoutBytes = Math.max(1024, params.maxStdoutBytes);
+
+  const env = { ...process.env, LOBSTER_MODE: "tool" } as Record<string, string | undefined>;
+  const nodeOptions = env.NODE_OPTIONS ?? "";
+  if (nodeOptions.includes("--inspect")) {
+    delete env.NODE_OPTIONS;
+  }
+
+  return await new Promise<{ stdout: string }>((resolve, reject) => {
+    const child = spawn(execPath, argv, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      env,
+      shell: useShell,
+      windowsHide: useShell ? true : undefined,
+    });
+
+    let stdout = "";
+    let stdoutBytes = 0;
+    let stderr = "";
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+
+    child.stdout?.on("data", (chunk) => {
+      const str = String(chunk);
+      stdoutBytes += Buffer.byteLength(str, "utf8");
+      if (stdoutBytes > maxStdoutBytes) {
+        try {
+          child.kill("SIGKILL");
+        } finally {
+          reject(new Error("lobster output exceeded maxStdoutBytes"));
+        }
+        return;
+      }
+      stdout += str;
+    });
+
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } finally {
+        reject(new Error("lobster subprocess timed out"));
+      }
+    }, timeoutMs);
+
+    child.once("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`));
+        return;
+      }
+      resolve({ stdout });
+    });
+  });
+}
+
+async function runLobsterSubprocess(params: {
+  execPath: string;
+  argv: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxStdoutBytes: number;
+}) {
+  try {
+    return await runLobsterSubprocessOnce(params, false);
+  } catch (err) {
+    if (process.platform === "win32" && isWindowsSpawnEINVAL(err)) {
+      return await runLobsterSubprocessOnce(params, true);
+    }
+    throw err;
+  }
+}
+
+function parseEnvelope(stdout: string): LobsterEnvelope {
+  const trimmed = stdout.trim();
+
+  const tryParse = (input: string) => {
+    try {
+      return JSON.parse(input) as unknown;
+    } catch {
+      return undefined;
+    }
+  };
+
+  let parsed: unknown = tryParse(trimmed);
+
+  // Some environments can leak extra stdout (e.g. warnings/logs) before the
+  // final JSON envelope. Be tolerant and parse the last JSON-looking suffix.
+  if (parsed === undefined) {
+    const suffixMatch = trimmed.match(/({[\s\S]*}|\[[\s\S]*])\s*$/);
+    if (suffixMatch?.[1]) {
+      parsed = tryParse(suffixMatch[1]);
+    }
+  }
+
+  if (parsed === undefined) {
+    throw new Error("lobster returned invalid JSON");
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("lobster returned invalid JSON envelope");
+  }
+
+  const ok = (parsed as { ok?: unknown }).ok;
+  if (ok === true || ok === false) {
+    return parsed as LobsterEnvelope;
+  }
+
+  throw new Error("lobster returned invalid JSON envelope");
+}
+
+export function createLobsterTool(api: OpenClawPluginApi) {
+  return {
+    name: "lobster",
+    description:
+      "Run Lobster pipelines as a local-first workflow runtime (typed JSON envelope + resumable approvals).",
+    parameters: Type.Object({
+      // NOTE: Prefer string enums in tool schemas; some providers reject unions/anyOf.
+      action: Type.Unsafe<"run" | "resume">({ type: "string", enum: ["run", "resume"] }),
+      pipeline: Type.Optional(Type.String()),
+      argsJson: Type.Optional(Type.String()),
+      token: Type.Optional(Type.String()),
+      approve: Type.Optional(Type.Boolean()),
+      lobsterPath: Type.Optional(Type.String()),
+      cwd: Type.Optional(Type.String()),
+      timeoutMs: Type.Optional(Type.Number()),
+      maxStdoutBytes: Type.Optional(Type.Number()),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const action = String(params.action || "").trim();
+      if (!action) throw new Error("action required");
+
+      const execPath = resolveExecutablePath(
+        typeof params.lobsterPath === "string" ? params.lobsterPath : undefined,
+      );
+      const cwd = typeof params.cwd === "string" && params.cwd.trim() ? params.cwd.trim() : process.cwd();
+      const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : 20_000;
+      const maxStdoutBytes = typeof params.maxStdoutBytes === "number" ? params.maxStdoutBytes : 512_000;
+
+      const argv = (() => {
+        if (action === "run") {
+          const pipeline = typeof params.pipeline === "string" ? params.pipeline : "";
+          if (!pipeline.trim()) throw new Error("pipeline required");
+          const argv = ["run", "--mode", "tool", pipeline];
+          const argsJson = typeof params.argsJson === "string" ? params.argsJson : "";
+          if (argsJson.trim()) {
+            argv.push("--args-json", argsJson);
+          }
+          return argv;
+        }
+        if (action === "resume") {
+          const token = typeof params.token === "string" ? params.token : "";
+          if (!token.trim()) throw new Error("token required");
+          const approve = params.approve;
+          if (typeof approve !== "boolean") throw new Error("approve required");
+          return ["resume", "--token", token, "--approve", approve ? "yes" : "no"];
+        }
+        throw new Error(`Unknown action: ${action}`);
+      })();
+
+      if (api.runtime?.version && api.logger?.debug) {
+        api.logger.debug(`lobster plugin runtime=${api.runtime.version}`);
+      }
+
+      const { stdout } = await runLobsterSubprocess({
+        execPath,
+        argv,
+        cwd,
+        timeoutMs,
+        maxStdoutBytes,
+      });
+
+      const envelope = parseEnvelope(stdout);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+        details: envelope,
+      };
+    },
+  };
+}