@openclaw/lobster 2026.3.13 → 2026.5.1-beta.1

package/src/lobster-tool.test.ts

@@ -1,56 +1,18 @@
-import { EventEmitter } from "node:events";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { PassThrough } from "node:stream";
-import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk/lobster";
-import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import {
-  createWindowsCmdShimFixture,
-  restorePlatformPathEnv,
-  setProcessPlatform,
-  snapshotPlatformPathEnv,
-} from "./test-helpers.js";
-
-const spawnState = vi.hoisted(() => ({
-  queue: [] as Array<{ stdout: string; stderr?: string; exitCode?: number }>,
-  spawn: vi.fn(),
-}));
-
-vi.mock("node:child_process", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("node:child_process")>();
-  return {
-    ...actual,
-    spawn: (...args: unknown[]) => spawnState.spawn(...args),
-  };
-});
-
-let createLobsterTool: typeof import("./lobster-tool.js").createLobsterTool;
+import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
+import { describe, expect, it, vi } from "vitest";
+import type { OpenClawPluginApi, OpenClawPluginToolContext } from "../runtime-api.js";
+import { createLobsterTool } from "./lobster-tool.js";
+import { createFakeTaskFlow } from "./taskflow-test-helpers.js";
 
 function fakeApi(overrides: Partial<OpenClawPluginApi> = {}): OpenClawPluginApi {
-  return {
+  return createTestPluginApi({
     id: "lobster",
     name: "lobster",
     source: "test",
-    config: {},
-    pluginConfig: {},
-    // oxlint-disable-next-line typescript/no-explicit-any
     runtime: { version: "test" } as any,
-    logger: { info() {}, warn() {}, error() {}, debug() {} },
-    registerTool() {},
-    registerChannel() {},
-    registerGatewayMethod() {},
-    registerCli() {},
-    registerService() {},
-    registerProvider() {},
-    registerHook() {},
-    registerHttpRoute() {},
-    registerCommand() {},
-    registerContextEngine() {},
-    on() {},
     resolvePath: (p) => p,
     ...overrides,
-  };
+  });
 }
 
 function fakeCtx(overrides: Partial<OpenClawPluginToolContext> = {}): OpenClawPluginToolContext {
@@ -68,140 +30,279 @@ function fakeCtx(overrides: Partial<OpenClawPluginToolContext> = {}): OpenClawPl
 }
 
 describe("lobster plugin tool", () => {
-  let tempDir = "";
-  const originalProcessState = snapshotPlatformPathEnv();
-
-  beforeAll(async () => {
-    ({ createLobsterTool } = await import("./lobster-tool.js"));
-
-    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-lobster-plugin-"));
-  });
-
-  afterEach(() => {
-    restorePlatformPathEnv(originalProcessState);
-  });
-
-  afterAll(async () => {
-    if (!tempDir) {
-      return;
-    }
-    if (process.platform === "win32") {
-      await fs.rm(tempDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
-    } else {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  beforeEach(() => {
-    spawnState.queue.length = 0;
-    spawnState.spawn.mockReset();
-    spawnState.spawn.mockImplementation(() => {
-      const next = spawnState.queue.shift() ?? { stdout: "" };
-      const stdout = new PassThrough();
-      const stderr = new PassThrough();
-      const child = new EventEmitter() as EventEmitter & {
-        stdout: PassThrough;
-        stderr: PassThrough;
-        kill: (signal?: string) => boolean;
-      };
-      child.stdout = stdout;
-      child.stderr = stderr;
-      child.kill = () => true;
-
-      setImmediate(() => {
-        if (next.stderr) {
-          stderr.end(next.stderr);
-        } else {
-          stderr.end();
-        }
-        stdout.end(next.stdout);
-        child.emit("exit", next.exitCode ?? 0);
-      });
-
-      return child;
-    });
-  });
-
-  const queueSuccessfulEnvelope = (hello = "world") => {
-    spawnState.queue.push({
-      stdout: JSON.stringify({
+  it("returns the Lobster envelope in details", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
         ok: true,
         status: "ok",
-        output: [{ hello }],
+        output: [{ hello: "world" }],
         requiresApproval: null,
       }),
+    };
+
+    const tool = createLobsterTool(fakeApi(), { runner });
+    const res = await tool.execute("call1", {
+      action: "run",
+      pipeline: "noop",
+      timeoutMs: 1000,
     });
-  };
 
-  it("runs lobster and returns parsed envelope in details", async () => {
-    spawnState.queue.push({
-      stdout: JSON.stringify({
+    expect(runner.run).toHaveBeenCalledWith({
+      action: "run",
+      pipeline: "noop",
+      cwd: process.cwd(),
+      timeoutMs: 1000,
+      maxStdoutBytes: 512_000,
+    });
+    expect(res.details).toMatchObject({
+      ok: true,
+      status: "ok",
+      output: [{ hello: "world" }],
+      requiresApproval: null,
+    });
+  });
+
+  it("supports approval envelopes without changing the tool contract", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
         ok: true,
-        status: "ok",
-        output: [{ hello: "world" }],
-        requiresApproval: null,
+        status: "needs_approval",
+        output: [],
+        requiresApproval: {
+          type: "approval_request",
+          prompt: "Send these alerts?",
+          items: [{ id: "alert-1" }],
+          resumeToken: "resume-token-1",
+        },
       }),
-    });
+    };
 
-    const tool = createLobsterTool(fakeApi());
-    const res = await tool.execute("call1", {
+    const tool = createLobsterTool(fakeApi(), { runner });
+    const res = await tool.execute("call-injected-runner", {
       action: "run",
       pipeline: "noop",
-      timeoutMs: 1000,
+      argsJson: '{"since_hours":1}',
+      timeoutMs: 1500,
+      maxStdoutBytes: 4096,
     });
 
-    expect(spawnState.spawn).toHaveBeenCalled();
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    expect(runner.run).toHaveBeenCalledWith({
+      action: "run",
+      pipeline: "noop",
+      argsJson: '{"since_hours":1}',
+      cwd: process.cwd(),
+      timeoutMs: 1500,
+      maxStdoutBytes: 4096,
+    });
+    expect(res.details).toMatchObject({
+      ok: true,
+      status: "needs_approval",
+      requiresApproval: {
+        type: "approval_request",
+        prompt: "Send these alerts?",
+        resumeToken: "resume-token-1",
+      },
+    });
   });
 
-  it("tolerates noisy stdout before the JSON envelope", async () => {
-    const payload = { ok: true, status: "ok", output: [], requiresApproval: null };
-    spawnState.queue.push({
-      stdout: `noise before json\n${JSON.stringify(payload)}`,
+  it("throws when the runner returns an error envelope", async () => {
+    const tool = createLobsterTool(fakeApi(), {
+      runner: {
+        run: vi.fn().mockResolvedValue({
+          ok: false,
+          error: {
+            type: "runtime_error",
+            message: "boom",
+          },
+        }),
+      },
     });
 
-    const tool = createLobsterTool(fakeApi());
-    const res = await tool.execute("call-noisy", {
+    await expect(
+      tool.execute("call-runner-error", {
+        action: "run",
+        pipeline: "noop",
+      }),
+    ).rejects.toThrow("boom");
+  });
+
+  it("can run through managed TaskFlow mode", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
+        ok: true,
+        status: "needs_approval",
+        output: [],
+        requiresApproval: {
+          type: "approval_request",
+          prompt: "Approve this?",
+          items: [{ id: "item-1" }],
+          resumeToken: "resume-1",
+          approvalId: "approval-1",
+        },
+      }),
+    };
+    const taskFlow = createFakeTaskFlow();
+
+    const tool = createLobsterTool(fakeApi(), { runner, taskFlow });
+    const res = await tool.execute("call-managed-run", {
       action: "run",
       pipeline: "noop",
-      timeoutMs: 1000,
+      flowControllerId: "tests/lobster",
+      flowGoal: "Run Lobster workflow",
+      flowStateJson: '{"lane":"email"}',
+      flowCurrentStep: "run_lobster",
+      flowWaitingStep: "await_review",
     });
 
-    expect(res.details).toMatchObject({ ok: true, status: "ok" });
+    expect(taskFlow.createManaged).toHaveBeenCalledWith({
+      controllerId: "tests/lobster",
+      goal: "Run Lobster workflow",
+      currentStep: "run_lobster",
+      stateJson: { lane: "email" },
+    });
+    expect(taskFlow.setWaiting).toHaveBeenCalledWith({
+      flowId: "flow-1",
+      expectedRevision: 1,
+      currentStep: "await_review",
+      waitJson: {
+        kind: "lobster_approval",
+        prompt: "Approve this?",
+        items: [{ id: "item-1" }],
+        resumeToken: "resume-1",
+        approvalId: "approval-1",
+      },
+    });
+    expect(res.details).toMatchObject({
+      ok: true,
+      status: "needs_approval",
+      flow: {
+        flowId: "flow-1",
+      },
+      mutation: {
+        applied: true,
+      },
+    });
   });
 
-  it("requires action", async () => {
-    const tool = createLobsterTool(fakeApi());
-    await expect(tool.execute("call-action-missing", {})).rejects.toThrow(/action required/);
+  it("rejects managed TaskFlow params when no bound taskFlow runtime is available", async () => {
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+    });
+
+    await expect(
+      tool.execute("call-missing-taskflow", {
+        action: "run",
+        pipeline: "noop",
+        flowControllerId: "tests/lobster",
+        flowGoal: "Run Lobster workflow",
+      }),
+    ).rejects.toThrow(/Managed TaskFlow run mode requires a bound taskFlow runtime/);
   });
 
-  it("requires pipeline for run action", async () => {
-    const tool = createLobsterTool(fakeApi());
+  it("rejects invalid flowStateJson in managed TaskFlow mode", async () => {
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+      taskFlow: createFakeTaskFlow(),
+    });
+
     await expect(
-      tool.execute("call-pipeline-missing", {
+      tool.execute("call-invalid-flow-json", {
         action: "run",
+        pipeline: "noop",
+        flowControllerId: "tests/lobster",
+        flowGoal: "Run Lobster workflow",
+        flowStateJson: "{bad",
       }),
-    ).rejects.toThrow(/pipeline required/);
+    ).rejects.toThrow(/flowStateJson must be valid JSON/);
   });
 
-  it("requires token and approve for resume action", async () => {
-    const tool = createLobsterTool(fakeApi());
+  it("can resume managed TaskFlow mode with only approvalId", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
+        ok: true,
+        status: "ok",
+        output: [],
+        requiresApproval: null,
+      }),
+    };
+    const taskFlow = createFakeTaskFlow();
+    const tool = createLobsterTool(fakeApi(), { runner, taskFlow });
+
+    const res = await tool.execute("call-managed-resume-approval-id", {
+      action: "resume",
+      approvalId: "approval-1",
+      approve: true,
+      flowId: "flow-1",
+      flowExpectedRevision: 1,
+      flowCurrentStep: "resume_lobster",
+    });
+
+    expect(taskFlow.resume).toHaveBeenCalledWith({
+      flowId: "flow-1",
+      expectedRevision: 1,
+      status: "running",
+      currentStep: "resume_lobster",
+    });
+    expect(runner.run).toHaveBeenCalledWith({
+      action: "resume",
+      approvalId: "approval-1",
+      approve: true,
+      cwd: process.cwd(),
+      timeoutMs: 20_000,
+      maxStdoutBytes: 512_000,
+    });
+    expect(res.details).toMatchObject({
+      ok: true,
+      status: "ok",
+      mutation: {
+        applied: true,
+      },
+    });
+  });
+
+  it("rejects managed TaskFlow resume mode without a token or approvalId", async () => {
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+      taskFlow: createFakeTaskFlow(),
+    });
+
     await expect(
-      tool.execute("call-resume-token-missing", {
+      tool.execute("call-missing-resume-token", {
         action: "resume",
+        flowId: "flow-1",
+        flowExpectedRevision: 1,
         approve: true,
       }),
-    ).rejects.toThrow(/token required/);
+    ).rejects.toThrow(/token or approvalId required when using managed TaskFlow resume mode/);
+  });
+
+  it("rejects managed TaskFlow resume mode without approve", async () => {
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+      taskFlow: createFakeTaskFlow(),
+    });
+
     await expect(
-      tool.execute("call-resume-approve-missing", {
+      tool.execute("call-missing-resume-approve", {
         action: "resume",
         token: "resume-token",
+        flowId: "flow-1",
+        flowExpectedRevision: 1,
       }),
-    ).rejects.toThrow(/approve required/);
+    ).rejects.toThrow(/approve required when using managed TaskFlow resume mode/);
+  });
+
+  it("requires action", async () => {
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+    });
+    await expect(tool.execute("call-action-missing", {})).rejects.toThrow(/action required/);
   });
 
   it("rejects unknown action", async () => {
-    const tool = createLobsterTool(fakeApi());
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+    });
     await expect(
       tool.execute("call-action-unknown", {
         action: "explode",
@@ -210,9 +311,11 @@ describe("lobster plugin tool", () => {
   });
 
   it("rejects absolute cwd", async () => {
-    const tool = createLobsterTool(fakeApi());
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+    });
     await expect(
-      tool.execute("call2c", {
+      tool.execute("call-absolute-cwd", {
         action: "run",
         pipeline: "noop",
         cwd: "/tmp",
@@ -221,9 +324,11 @@ describe("lobster plugin tool", () => {
   });
 
   it("rejects cwd that escapes the gateway working directory", async () => {
-    const tool = createLobsterTool(fakeApi());
+    const tool = createLobsterTool(fakeApi(), {
+      runner: { run: vi.fn() },
+    });
     await expect(
-      tool.execute("call2d", {
+      tool.execute("call-escape-cwd", {
         action: "run",
         pipeline: "noop",
         cwd: "../../etc",
@@ -231,78 +336,15 @@ describe("lobster plugin tool", () => {
     ).rejects.toThrow(/must stay within/);
   });
 
-  it("rejects invalid JSON from lobster", async () => {
-    spawnState.queue.push({ stdout: "nope" });
-
-    const tool = createLobsterTool(fakeApi());
-    await expect(
-      tool.execute("call3", {
-        action: "run",
-        pipeline: "noop",
-      }),
-    ).rejects.toThrow(/invalid JSON/);
-  });
-
-  it("runs Windows cmd shims through Node without enabling shell", async () => {
-    setProcessPlatform("win32");
-    const shimScriptPath = path.join(tempDir, "shim-dist", "lobster-cli.cjs");
-    const shimPath = path.join(tempDir, "shim-bin", "lobster.cmd");
-    await createWindowsCmdShimFixture({
-      shimPath,
-      scriptPath: shimScriptPath,
-      shimLine: `"%dp0%\\..\\shim-dist\\lobster-cli.cjs" %*`,
-    });
-    process.env.PATHEXT = ".CMD;.EXE";
-    process.env.PATH = `${path.dirname(shimPath)};${process.env.PATH ?? ""}`;
-    queueSuccessfulEnvelope();
-
-    const tool = createLobsterTool(fakeApi());
-    await tool.execute("call-win-shim", {
-      action: "run",
-      pipeline: "noop",
-    });
-
-    const [command, argv, options] = spawnState.spawn.mock.calls[0] ?? [];
-    expect(command).toBe(process.execPath);
-    expect(argv).toEqual([shimScriptPath, "run", "--mode", "tool", "noop"]);
-    expect(options).toMatchObject({ windowsHide: true });
-    expect(options).not.toHaveProperty("shell");
-  });
-
-  it("does not retry a failed Windows spawn with shell fallback", async () => {
-    setProcessPlatform("win32");
-    spawnState.spawn.mockReset();
-    spawnState.spawn.mockImplementationOnce(() => {
-      const child = new EventEmitter() as EventEmitter & {
-        stdout: PassThrough;
-        stderr: PassThrough;
-        kill: (signal?: string) => boolean;
-      };
-      child.stdout = new PassThrough();
-      child.stderr = new PassThrough();
-      child.kill = () => true;
-      const err = Object.assign(new Error("spawn failed"), { code: "ENOENT" });
-      setImmediate(() => child.emit("error", err));
-      return child;
-    });
-
-    const tool = createLobsterTool(fakeApi());
-    await expect(
-      tool.execute("call-win-no-retry", {
-        action: "run",
-        pipeline: "noop",
-      }),
-    ).rejects.toThrow(/spawn failed/);
-    expect(spawnState.spawn).toHaveBeenCalledTimes(1);
-  });
-
   it("can be gated off in sandboxed contexts", async () => {
     const api = fakeApi();
     const factoryTool = (ctx: OpenClawPluginToolContext) => {
       if (ctx.sandboxed) {
         return null;
       }
-      return createLobsterTool(api);
+      return createLobsterTool(api, {
+        runner: { run: vi.fn() },
+      });
     };
 
     expect(factoryTool(fakeCtx({ sandboxed: true }))).toBeNull();