@openclaw/lobster 2026.1.29 → 2026.2.2

package/README.md

@@ -5,7 +5,7 @@ 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*.
+- This plugin integrates Lobster with OpenClaw _without core changes_.
 
 ## Enable
 
@@ -53,22 +53,17 @@ Example (allow only a small set of tools):
       {
         "id": "main",
         "tools": {
-          "allow": [
-            "lobster",
-            "web_fetch",
-            "web_search",
-            "gog",
-            "gh"
-          ],
-          "deny": ["gateway"]
-        }
-      }
-    ]
-  }
+          "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.
 

package/SKILL.md

@@ -8,13 +8,13 @@ Lobster executes multi-step workflows with approval checkpoints. Use it when:
 
 ## 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 |
+| 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
 
@@ -28,6 +28,7 @@ Lobster executes multi-step workflows with approval checkpoints. Use it when:
 ```
 
 Returns structured result:
+
 ```json
 {
   "protocolVersion": 1,
@@ -41,6 +42,7 @@ Returns structured result:
 ### Handle approval
 
 If the workflow needs approval:
+
 ```json
 {
   "status": "needs_approval",
@@ -54,6 +56,7 @@ If the workflow needs approval:
 ```
 
 Present the prompt to the user. If they approve:
+
 ```json
 {
   "action": "resume",
@@ -65,15 +68,19 @@ Present the prompt to the user. If they approve:
 ## 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

package/index.ts

@@ -1,11 +1,12 @@
 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;
+      if (ctx.sandboxed) {
+        return null;
+      }
       return createLobsterTool(api);
     },
     { optional: true },

package/package.json

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

package/src/lobster-tool.test.ts

@@ -1,9 +1,7 @@
 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";
 
@@ -33,12 +31,14 @@ async function writeFakeLobster(params: { payload: unknown }) {
   return await writeFakeLobsterScript(scriptBody);
 }
 
-function fakeApi(): OpenClawPluginApi {
+function fakeApi(overrides: Partial<OpenClawPluginApi> = {}): OpenClawPluginApi {
   return {
     id: "lobster",
     name: "lobster",
     source: "test",
-    config: {} as any,
+    config: {},
+    pluginConfig: {},
+    // oxlint-disable-next-line typescript/no-explicit-any
     runtime: { version: "test" } as any,
     logger: { info() {}, warn() {}, error() {}, debug() {} },
     registerTool() {},
@@ -48,13 +48,18 @@ function fakeApi(): OpenClawPluginApi {
     registerCli() {},
     registerService() {},
     registerProvider() {},
+    registerHook() {},
+    registerHttpRoute() {},
+    registerCommand() {},
+    on() {},
     resolvePath: (p) => p,
+    ...overrides,
   };
 }
 
 function fakeCtx(overrides: Partial<OpenClawPluginToolContext> = {}): OpenClawPluginToolContext {
   return {
-    config: {} as any,
+    config: {},
     workspaceDir: "/tmp",
     agentDir: "/tmp",
     agentId: "main",
@@ -72,68 +77,167 @@ describe("lobster plugin tool", () => {
       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,
-    });
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${fake.dir}${path.delimiter}${originalPath ?? ""}`;
+
+    try {
+      const tool = createLobsterTool(fakeApi());
+      const res = await tool.execute("call1", {
+        action: "run",
+        pipeline: "noop",
+        timeoutMs: 1000,
+      });
 
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+      expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    } finally {
+      process.env.PATH = originalPath;
+    }
   });
 
   it("tolerates noisy stdout before the JSON envelope", async () => {
     const payload = { ok: true, status: "ok", output: [], requiresApproval: null };
-    const { binPath } = await writeFakeLobsterScript(
+    const { dir } = 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,
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${dir}${path.delimiter}${originalPath ?? ""}`;
+
+    try {
+      const tool = createLobsterTool(fakeApi());
+      const res = await tool.execute("call-noisy", {
+        action: "run",
+        pipeline: "noop",
+        timeoutMs: 1000,
+      });
+
+      expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+  });
+
+  it("requires absolute lobsterPath when provided (even though it is ignored)", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [{ hello: "world" }], requiresApproval: null },
+    });
+
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${fake.dir}${path.delimiter}${originalPath ?? ""}`;
+
+    try {
+      const tool = createLobsterTool(fakeApi());
+      await expect(
+        tool.execute("call2", {
+          action: "run",
+          pipeline: "noop",
+          lobsterPath: "./lobster",
+        }),
+      ).rejects.toThrow(/absolute path/);
+    } finally {
+      process.env.PATH = originalPath;
+    }
+  });
+
+  it("rejects lobsterPath (deprecated) when invalid", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [{ hello: "world" }], requiresApproval: null },
     });
 
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${fake.dir}${path.delimiter}${originalPath ?? ""}`;
+
+    try {
+      const tool = createLobsterTool(fakeApi());
+      await expect(
+        tool.execute("call2b", {
+          action: "run",
+          pipeline: "noop",
+          lobsterPath: "/bin/bash",
+        }),
+      ).rejects.toThrow(/lobster executable/);
+    } finally {
+      process.env.PATH = originalPath;
+    }
   });
 
-  it("requires absolute lobsterPath when provided", async () => {
+  it("rejects absolute cwd", async () => {
     const tool = createLobsterTool(fakeApi());
     await expect(
-      tool.execute("call2", {
+      tool.execute("call2c", {
         action: "run",
         pipeline: "noop",
-        lobsterPath: "./lobster",
+        cwd: "/tmp",
       }),
-    ).rejects.toThrow(/absolute path/);
+    ).rejects.toThrow(/cwd must be a relative path/);
   });
 
-  it("rejects invalid JSON from lobster", async () => {
-    const { binPath } = await writeFakeLobsterScript(
-      `process.stdout.write("nope");\n`,
-      "openclaw-lobster-plugin-bad-",
-    );
-
+  it("rejects cwd that escapes the gateway working directory", async () => {
     const tool = createLobsterTool(fakeApi());
     await expect(
-      tool.execute("call3", {
+      tool.execute("call2d", {
         action: "run",
         pipeline: "noop",
-        lobsterPath: binPath,
+        cwd: "../../etc",
       }),
-    ).rejects.toThrow(/invalid JSON/);
+    ).rejects.toThrow(/must stay within/);
+  });
+
+  it("uses pluginConfig.lobsterPath when provided", async () => {
+    const fake = await writeFakeLobster({
+      payload: { ok: true, status: "ok", output: [{ hello: "world" }], requiresApproval: null },
+    });
+
+    // Ensure `lobster` is NOT discoverable via PATH, while still allowing our
+    // fake lobster (a Node script with `#!/usr/bin/env node`) to run.
+    const originalPath = process.env.PATH;
+    process.env.PATH = path.dirname(process.execPath);
+
+    try {
+      const tool = createLobsterTool(fakeApi({ pluginConfig: { lobsterPath: fake.binPath } }));
+      const res = await tool.execute("call-plugin-config", {
+        action: "run",
+        pipeline: "noop",
+        timeoutMs: 1000,
+      });
+
+      expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    } finally {
+      process.env.PATH = originalPath;
+    }
+  });
+
+  it("rejects invalid JSON from lobster", async () => {
+    const { dir } = await writeFakeLobsterScript(
+      `process.stdout.write("nope");\n`,
+      "openclaw-lobster-plugin-bad-",
+    );
+
+    const originalPath = process.env.PATH;
+    process.env.PATH = `${dir}${path.delimiter}${originalPath ?? ""}`;
+
+    try {
+      const tool = createLobsterTool(fakeApi());
+      await expect(
+        tool.execute("call3", {
+          action: "run",
+          pipeline: "noop",
+        }),
+      ).rejects.toThrow(/invalid JSON/);
+    } finally {
+      process.env.PATH = originalPath;
+    }
   });
 
   it("can be gated off in sandboxed contexts", async () => {
     const api = fakeApi();
     const factoryTool = (ctx: OpenClawPluginToolContext) => {
-      if (ctx.sandboxed) return null;
+      if (ctx.sandboxed) {
+        return null;
+      }
       return createLobsterTool(api);
     };
 

package/src/lobster-tool.ts

@@ -1,7 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import { spawn } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
-
 import type { OpenClawPluginApi } from "../../../src/plugins/types.js";
 
 type LobsterEnvelope =
@@ -23,16 +23,77 @@ type LobsterEnvelope =
 
 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)");
+
+  // SECURITY:
+  // Never allow arbitrary executables (e.g. /bin/bash). If the caller overrides
+  // the path, it must still be the lobster binary (by name) and be absolute.
+  if (lobsterPath !== "lobster") {
+    if (!path.isAbsolute(lobsterPath)) {
+      throw new Error("lobsterPath must be an absolute path (or omit to use PATH)");
+    }
+    const base = path.basename(lobsterPath).toLowerCase();
+    const allowed =
+      process.platform === "win32" ? ["lobster.exe", "lobster.cmd", "lobster.bat"] : ["lobster"];
+    if (!allowed.includes(base)) {
+      throw new Error("lobsterPath must point to the lobster executable");
+    }
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(lobsterPath);
+    } catch {
+      throw new Error("lobsterPath must exist");
+    }
+    if (!stat.isFile()) {
+      throw new Error("lobsterPath must point to a file");
+    }
+    if (process.platform !== "win32") {
+      try {
+        fs.accessSync(lobsterPath, fs.constants.X_OK);
+      } catch {
+        throw new Error("lobsterPath must be executable");
+      }
+    }
   }
+
   return lobsterPath;
 }
 
-function isWindowsSpawnEINVAL(err: unknown) {
-  if (!err || typeof err !== "object") return false;
+function normalizeForCwdSandbox(p: string): string {
+  const normalized = path.normalize(p);
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function resolveCwd(cwdRaw: unknown): string {
+  if (typeof cwdRaw !== "string" || !cwdRaw.trim()) {
+    return process.cwd();
+  }
+  const cwd = cwdRaw.trim();
+  if (path.isAbsolute(cwd)) {
+    throw new Error("cwd must be a relative path");
+  }
+  const base = process.cwd();
+  const resolved = path.resolve(base, cwd);
+
+  const rel = path.relative(normalizeForCwdSandbox(base), normalizeForCwdSandbox(resolved));
+  if (rel === "" || rel === ".") {
+    return resolved;
+  }
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error("cwd must stay within the gateway working directory");
+  }
+  return resolved;
+}
+
+function isWindowsSpawnErrorThatCanUseShell(err: unknown) {
+  if (!err || typeof err !== "object") {
+    return false;
+  }
   const code = (err as { code?: unknown }).code;
-  return code === "EINVAL";
+
+  // On Windows, spawning scripts discovered on PATH (e.g. lobster.cmd) can fail
+  // with EINVAL, and PATH discovery itself can fail with ENOENT when the binary
+  // is only available via PATHEXT/script wrappers.
+  return code === "EINVAL" || code === "ENOENT";
 }
 
 async function runLobsterSubprocessOnce(
@@ -123,7 +184,7 @@ async function runLobsterSubprocess(params: {
   try {
     return await runLobsterSubprocessOnce(params, false);
   } catch (err) {
-    if (process.platform === "win32" && isWindowsSpawnEINVAL(err)) {
+    if (process.platform === "win32" && isWindowsSpawnErrorThatCanUseShell(err)) {
       return await runLobsterSubprocessOnce(params, true);
     }
     throw err;
@@ -180,26 +241,49 @@ export function createLobsterTool(api: OpenClawPluginApi) {
       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()),
+      // SECURITY: Do not allow the agent to choose an executable path.
+      // Host can configure the lobster binary via plugin config.
+      lobsterPath: Type.Optional(
+        Type.String({ description: "(deprecated) Use plugin config instead." }),
+      ),
+      cwd: Type.Optional(
+        Type.String({
+          description:
+            "Relative working directory (optional). Must stay within the gateway working directory.",
+        }),
+      ),
       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 action = typeof params.action === "string" ? params.action.trim() : "";
+      if (!action) {
+        throw new Error("action required");
+      }
+
+      // SECURITY: never allow tool callers (agent/user) to select executables.
+      // If a host needs to override the binary, it must do so via plugin config.
+      // We still validate the parameter shape to prevent reintroducing an RCE footgun.
+      if (typeof params.lobsterPath === "string" && params.lobsterPath.trim()) {
+        resolveExecutablePath(params.lobsterPath);
+      }
 
       const execPath = resolveExecutablePath(
-        typeof params.lobsterPath === "string" ? params.lobsterPath : undefined,
+        typeof api.pluginConfig?.lobsterPath === "string"
+          ? api.pluginConfig.lobsterPath
+          : undefined,
       );
-      const cwd = typeof params.cwd === "string" && params.cwd.trim() ? params.cwd.trim() : process.cwd();
+      const cwd = resolveCwd(params.cwd);
       const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : 20_000;
-      const maxStdoutBytes = typeof params.maxStdoutBytes === "number" ? params.maxStdoutBytes : 512_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");
+          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()) {
@@ -209,9 +293,13 @@ export function createLobsterTool(api: OpenClawPluginApi) {
         }
         if (action === "resume") {
           const token = typeof params.token === "string" ? params.token : "";
-          if (!token.trim()) throw new Error("token required");
+          if (!token.trim()) {
+            throw new Error("token required");
+          }
           const approve = params.approve;
-          if (typeof approve !== "boolean") throw new Error("approve required");
+          if (typeof approve !== "boolean") {
+            throw new Error("approve required");
+          }
           return ["resume", "--token", token, "--approve", approve ? "yes" : "no"];
         }
         throw new Error(`Unknown action: ${action}`);