@openclaw/lobster 2026.3.13 → 2026.5.2-beta.1

package/src/lobster-tool.ts

@@ -1,213 +1,216 @@
-import { spawn } from "node:child_process";
-import path from "node:path";
-import { Type } from "@sinclair/typebox";
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/lobster";
-import { resolveWindowsLobsterSpawn } from "./windows-spawn.js";
-
-type LobsterEnvelope =
-  | {
-      ok: true;
-      status: "ok" | "needs_approval" | "cancelled";
-      output: unknown[];
-      requiresApproval: null | {
-        type: "approval_request";
-        prompt: string;
-        items: unknown[];
-        resumeToken?: string;
-      };
-    }
+import { Type } from "typebox";
+import type { OpenClawPluginApi } from "../runtime-api.js";
+import {
+  createEmbeddedLobsterRunner,
+  resolveLobsterCwd,
+  type LobsterRunner,
+  type LobsterRunnerParams,
+} from "./lobster-runner.js";
+import {
+  type ManagedLobsterFlowResult,
+  resumeManagedLobsterFlow,
+  runManagedLobsterFlow,
+} from "./lobster-taskflow.js";
+
+type BoundTaskFlow = ReturnType<
+  NonNullable<OpenClawPluginApi["runtime"]>["tasks"]["managedFlows"]["bindSession"]
+>;
+
+type JsonLike =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonLike[]
   | {
-      ok: false;
-      error: { type?: string; message: string };
+      [key: string]: JsonLike;
     };
 
-function normalizeForCwdSandbox(p: string): string {
-  const normalized = path.normalize(p);
-  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+type LobsterToolOptions = {
+  runner?: LobsterRunner;
+  taskFlow?: BoundTaskFlow;
+};
+
+type ManagedFlowRunParams = {
+  controllerId: string;
+  goal: string;
+  currentStep?: string;
+  waitingStep?: string;
+  stateJson?: JsonLike;
+};
+
+type ManagedFlowResumeParams = {
+  flowId: string;
+  expectedRevision: number;
+  currentStep?: string;
+  waitingStep?: string;
+};
+
+type ManagedFlowSuccessResult = {
+  ok: true;
+  envelope: unknown;
+  flow: unknown;
+  mutation: unknown;
+};
+
+function readOptionalTrimmedString(value: unknown, fieldName: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${fieldName} must be a string`);
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
 }
 
-function resolveCwd(cwdRaw: unknown): string {
-  if (typeof cwdRaw !== "string" || !cwdRaw.trim()) {
-    return process.cwd();
+function readOptionalNumber(value: unknown, fieldName: string): number | undefined {
+  if (value === undefined) {
+    return undefined;
   }
-  const cwd = cwdRaw.trim();
-  if (path.isAbsolute(cwd)) {
-    throw new Error("cwd must be a relative path");
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error(`${fieldName} must be an integer`);
   }
-  const base = process.cwd();
-  const resolved = path.resolve(base, cwd);
+  return value;
+}
 
-  const rel = path.relative(normalizeForCwdSandbox(base), normalizeForCwdSandbox(resolved));
-  if (rel === "" || rel === ".") {
-    return resolved;
+function readOptionalBoolean(value: unknown, fieldName: string): boolean | undefined {
+  if (value === undefined) {
+    return undefined;
   }
-  if (rel.startsWith("..") || path.isAbsolute(rel)) {
-    throw new Error("cwd must stay within the gateway working directory");
+  if (typeof value !== "boolean") {
+    throw new Error(`${fieldName} must be a boolean`);
   }
-  return resolved;
+  return value;
 }
 
-async function runLobsterSubprocessOnce(params: {
-  execPath: string;
-  argv: string[];
-  cwd: string;
-  timeoutMs: number;
-  maxStdoutBytes: number;
-}) {
-  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;
+function parseOptionalFlowStateJson(value: unknown): JsonLike | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new Error("flowStateJson must be a JSON string");
+  }
+  try {
+    return JSON.parse(value) as JsonLike;
+  } catch {
+    throw new Error("flowStateJson must be valid JSON");
   }
-  const spawnTarget =
-    process.platform === "win32"
-      ? resolveWindowsLobsterSpawn(execPath, argv, env)
-      : { command: execPath, argv };
-
-  return await new Promise<{ stdout: string }>((resolve, reject) => {
-    const child = spawn(spawnTarget.command, spawnTarget.argv, {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      env,
-      windowsHide: spawnTarget.windowsHide,
-    });
-
-    let stdout = "";
-    let stdoutBytes = 0;
-    let stderr = "";
-    let settled = false;
-
-    const settle = (
-      result: { ok: true; value: { stdout: string } } | { ok: false; error: Error },
-    ) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      clearTimeout(timer);
-      if (result.ok) {
-        resolve(result.value);
-      } else {
-        reject(result.error);
-      }
-    };
-
-    const failAndTerminate = (message: string) => {
-      try {
-        child.kill("SIGKILL");
-      } finally {
-        settle({ ok: false, error: new Error(message) });
-      }
-    };
-
-    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) {
-        failAndTerminate("lobster output exceeded maxStdoutBytes");
-        return;
-      }
-      stdout += str;
-    });
-
-    child.stderr?.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-
-    const timer = setTimeout(() => {
-      failAndTerminate("lobster subprocess timed out");
-    }, timeoutMs);
-
-    child.once("error", (err) => {
-      settle({ ok: false, error: err });
-    });
-
-    child.once("exit", (code) => {
-      if (code !== 0) {
-        settle({
-          ok: false,
-          error: new Error(`lobster failed (${code ?? "?"}): ${stderr.trim() || stdout.trim()}`),
-        });
-        return;
-      }
-      settle({ ok: true, value: { stdout } });
-    });
-  });
 }
 
-function parseEnvelope(stdout: string): LobsterEnvelope {
-  const trimmed = stdout.trim();
-
-  const tryParse = (input: string) => {
-    try {
-      return JSON.parse(input) as unknown;
-    } catch {
-      return undefined;
-    }
+function parseRunFlowParams(params: Record<string, unknown>): ManagedFlowRunParams | null {
+  const controllerId = readOptionalTrimmedString(params.flowControllerId, "flowControllerId");
+  const goal = readOptionalTrimmedString(params.flowGoal, "flowGoal");
+  const currentStep = readOptionalTrimmedString(params.flowCurrentStep, "flowCurrentStep");
+  const waitingStep = readOptionalTrimmedString(params.flowWaitingStep, "flowWaitingStep");
+  const stateJson = parseOptionalFlowStateJson(params.flowStateJson);
+  const resumeFlowId = readOptionalTrimmedString(params.flowId, "flowId");
+  const resumeRevision = readOptionalNumber(params.flowExpectedRevision, "flowExpectedRevision");
+
+  const hasRunFields =
+    controllerId !== undefined ||
+    goal !== undefined ||
+    currentStep !== undefined ||
+    waitingStep !== undefined ||
+    stateJson !== undefined;
+
+  if (!hasRunFields) {
+    return null;
+  }
+  if (resumeFlowId !== undefined || resumeRevision !== undefined) {
+    throw new Error("run action does not accept flowId or flowExpectedRevision");
+  }
+  if (!controllerId) {
+    throw new Error("flowControllerId required when using managed TaskFlow run mode");
+  }
+  if (!goal) {
+    throw new Error("flowGoal required when using managed TaskFlow run mode");
+  }
+  return {
+    controllerId,
+    goal,
+    ...(currentStep ? { currentStep } : {}),
+    ...(waitingStep ? { waitingStep } : {}),
+    ...(stateJson !== undefined ? { stateJson } : {}),
   };
+}
 
-  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]);
-    }
+function parseResumeFlowParams(params: Record<string, unknown>): ManagedFlowResumeParams | null {
+  const flowId = readOptionalTrimmedString(params.flowId, "flowId");
+  const expectedRevision = readOptionalNumber(params.flowExpectedRevision, "flowExpectedRevision");
+  const currentStep = readOptionalTrimmedString(params.flowCurrentStep, "flowCurrentStep");
+  const waitingStep = readOptionalTrimmedString(params.flowWaitingStep, "flowWaitingStep");
+  const token = readOptionalTrimmedString(params.token, "token");
+  const approvalId = readOptionalTrimmedString(params.approvalId, "approvalId");
+  const approve = readOptionalBoolean(params.approve, "approve");
+  const runControllerId = readOptionalTrimmedString(params.flowControllerId, "flowControllerId");
+  const runGoal = readOptionalTrimmedString(params.flowGoal, "flowGoal");
+  const stateJson = params.flowStateJson;
+
+  const hasResumeFields =
+    flowId !== undefined ||
+    expectedRevision !== undefined ||
+    currentStep !== undefined ||
+    waitingStep !== undefined;
+
+  if (!hasResumeFields) {
+    return null;
   }
-
-  if (parsed === undefined) {
-    throw new Error("lobster returned invalid JSON");
+  if (runControllerId !== undefined || runGoal !== undefined || stateJson !== undefined) {
+    throw new Error("resume action does not accept flowControllerId, flowGoal, or flowStateJson");
   }
-
-  if (!parsed || typeof parsed !== "object") {
-    throw new Error("lobster returned invalid JSON envelope");
+  if (!flowId) {
+    throw new Error("flowId required when using managed TaskFlow resume mode");
   }
-
-  const ok = (parsed as { ok?: unknown }).ok;
-  if (ok === true || ok === false) {
-    return parsed as LobsterEnvelope;
+  if (expectedRevision === undefined) {
+    throw new Error("flowExpectedRevision required when using managed TaskFlow resume mode");
   }
+  if (!token && !approvalId) {
+    throw new Error("token or approvalId required when using managed TaskFlow resume mode");
+  }
+  if (approve === undefined) {
+    throw new Error("approve required when using managed TaskFlow resume mode");
+  }
+  return {
+    flowId,
+    expectedRevision,
+    ...(currentStep ? { currentStep } : {}),
+    ...(waitingStep ? { waitingStep } : {}),
+  };
+}
 
-  throw new Error("lobster returned invalid JSON envelope");
+function formatManagedFlowResult(result: ManagedFlowSuccessResult) {
+  const envelope =
+    result.envelope && typeof result.envelope === "object" && !Array.isArray(result.envelope)
+      ? result.envelope
+      : { envelope: result.envelope };
+  const details = {
+    ...envelope,
+    flow: result.flow,
+    mutation: result.mutation,
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(details, null, 2) }],
+    details,
+  };
 }
 
-function buildLobsterArgv(action: string, params: Record<string, unknown>): string[] {
-  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;
+function requireTaskFlowRuntime(taskFlow: BoundTaskFlow | undefined, action: "run" | "resume") {
+  if (!taskFlow) {
+    throw new Error(`Managed TaskFlow ${action} mode requires a bound taskFlow runtime`);
   }
-  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"];
+  return taskFlow;
+}
+
+function resolveManagedFlowToolResult(result: ManagedLobsterFlowResult) {
+  if (!result.ok) {
+    throw result.error;
   }
-  throw new Error(`Unknown action: ${action}`);
+  return formatManagedFlowResult(result);
 }
 
-export function createLobsterTool(api: OpenClawPluginApi) {
+export function createLobsterTool(api: OpenClawPluginApi, options?: LobsterToolOptions) {
+  const runner = options?.runner ?? createEmbeddedLobsterRunner();
   return {
     name: "lobster",
     label: "Lobster Workflow",
@@ -219,6 +222,7 @@ export function createLobsterTool(api: OpenClawPluginApi) {
       pipeline: Type.Optional(Type.String()),
       argsJson: Type.Optional(Type.String()),
       token: Type.Optional(Type.String()),
+      approvalId: Type.Optional(Type.String()),
       approve: Type.Optional(Type.Boolean()),
       cwd: Type.Optional(
         Type.String({
@@ -228,35 +232,85 @@ export function createLobsterTool(api: OpenClawPluginApi) {
       ),
       timeoutMs: Type.Optional(Type.Number()),
       maxStdoutBytes: Type.Optional(Type.Number()),
+      flowControllerId: Type.Optional(Type.String()),
+      flowGoal: Type.Optional(Type.String()),
+      flowStateJson: Type.Optional(Type.String()),
+      flowId: Type.Optional(Type.String()),
+      flowExpectedRevision: Type.Optional(Type.Number()),
+      flowCurrentStep: Type.Optional(Type.String()),
+      flowWaitingStep: Type.Optional(Type.String()),
     }),
     async execute(_id: string, params: Record<string, unknown>) {
       const action = typeof params.action === "string" ? params.action.trim() : "";
       if (!action) {
         throw new Error("action required");
       }
+      if (action !== "run" && action !== "resume") {
+        throw new Error(`Unknown action: ${action}`);
+      }
 
-      const execPath = "lobster";
-      const cwd = resolveCwd(params.cwd);
+      const cwd = resolveLobsterCwd(params.cwd);
       const timeoutMs = typeof params.timeoutMs === "number" ? params.timeoutMs : 20_000;
       const maxStdoutBytes =
         typeof params.maxStdoutBytes === "number" ? params.maxStdoutBytes : 512_000;
 
-      const argv = buildLobsterArgv(action, params);
-
       if (api.runtime?.version && api.logger?.debug) {
         api.logger.debug(`lobster plugin runtime=${api.runtime.version}`);
       }
 
-      const { stdout } = await runLobsterSubprocessOnce({
-        execPath,
-        argv,
+      const runnerParams: LobsterRunnerParams = {
+        action,
+        ...(typeof params.pipeline === "string" ? { pipeline: params.pipeline } : {}),
+        ...(typeof params.argsJson === "string" ? { argsJson: params.argsJson } : {}),
+        ...(typeof params.token === "string" ? { token: params.token } : {}),
+        ...(typeof params.approvalId === "string" ? { approvalId: params.approvalId } : {}),
+        ...(typeof params.approve === "boolean" ? { approve: params.approve } : {}),
         cwd,
         timeoutMs,
         maxStdoutBytes,
-      });
+      };
 
-      const envelope = parseEnvelope(stdout);
+      const taskFlow = options?.taskFlow;
+      if (action === "run") {
+        const flowParams = parseRunFlowParams(params);
+        if (flowParams) {
+          return resolveManagedFlowToolResult(
+            await runManagedLobsterFlow({
+              taskFlow: requireTaskFlowRuntime(taskFlow, "run"),
+              runner,
+              runnerParams,
+              controllerId: flowParams.controllerId,
+              goal: flowParams.goal,
+              ...(flowParams.stateJson !== undefined ? { stateJson: flowParams.stateJson } : {}),
+              ...(flowParams.currentStep ? { currentStep: flowParams.currentStep } : {}),
+              ...(flowParams.waitingStep ? { waitingStep: flowParams.waitingStep } : {}),
+            }),
+          );
+        }
+      } else {
+        const flowParams = parseResumeFlowParams(params);
+        if (flowParams) {
+          return resolveManagedFlowToolResult(
+            await resumeManagedLobsterFlow({
+              taskFlow: requireTaskFlowRuntime(taskFlow, "resume"),
+              runner,
+              runnerParams: runnerParams as LobsterRunnerParams & {
+                action: "resume";
+                approve: boolean;
+              } & ({ token: string } | { approvalId: string }),
+              flowId: flowParams.flowId,
+              expectedRevision: flowParams.expectedRevision,
+              ...(flowParams.currentStep ? { currentStep: flowParams.currentStep } : {}),
+              ...(flowParams.waitingStep ? { waitingStep: flowParams.waitingStep } : {}),
+            }),
+          );
+        }
+      }
 
+      const envelope = await runner.run(runnerParams);
+      if (!envelope.ok) {
+        throw new Error(envelope.error.message);
+      }
       return {
         content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
         details: envelope,

package/src/taskflow-test-helpers.ts

@@ -0,0 +1,48 @@
+import { vi } from "vitest";
+import type { OpenClawPluginApi } from "../runtime-api.js";
+
+type BoundTaskFlow = ReturnType<
+  NonNullable<OpenClawPluginApi["runtime"]>["tasks"]["managedFlows"]["bindSession"]
+>;
+
+export function createFakeTaskFlow(overrides?: Partial<BoundTaskFlow>): BoundTaskFlow {
+  const baseFlow = {
+    flowId: "flow-1",
+    revision: 1,
+    syncMode: "managed" as const,
+    controllerId: "tests/lobster",
+    ownerKey: "agent:main:main",
+    status: "running" as const,
+    goal: "Run Lobster workflow",
+  };
+
+  return {
+    sessionKey: "agent:main:main",
+    createManaged: vi.fn().mockReturnValue(baseFlow),
+    get: vi.fn(),
+    list: vi.fn().mockReturnValue([]),
+    findLatest: vi.fn(),
+    resolve: vi.fn(),
+    getTaskSummary: vi.fn(),
+    setWaiting: vi.fn().mockImplementation((input) => ({
+      applied: true,
+      flow: { ...baseFlow, revision: input.expectedRevision + 1, status: "waiting" as const },
+    })),
+    resume: vi.fn().mockImplementation((input) => ({
+      applied: true,
+      flow: { ...baseFlow, revision: input.expectedRevision + 1, status: "running" as const },
+    })),
+    finish: vi.fn().mockImplementation((input) => ({
+      applied: true,
+      flow: { ...baseFlow, revision: input.expectedRevision + 1, status: "completed" as const },
+    })),
+    fail: vi.fn().mockImplementation((input) => ({
+      applied: true,
+      flow: { ...baseFlow, revision: input.expectedRevision + 1, status: "failed" as const },
+    })),
+    requestCancel: vi.fn(),
+    cancel: vi.fn(),
+    runTask: vi.fn(),
+    ...overrides,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/src/test-helpers.ts

@@ -1,43 +0,0 @@
-type PathEnvKey = "PATH" | "Path" | "PATHEXT" | "Pathext";
-
-const PATH_ENV_KEYS = ["PATH", "Path", "PATHEXT", "Pathext"] as const;
-
-export type PlatformPathEnvSnapshot = {
-  platformDescriptor: PropertyDescriptor | undefined;
-  env: Record<PathEnvKey, string | undefined>;
-};
-
-export function setProcessPlatform(platform: NodeJS.Platform): void {
-  Object.defineProperty(process, "platform", {
-    value: platform,
-    configurable: true,
-  });
-}
-
-export function snapshotPlatformPathEnv(): PlatformPathEnvSnapshot {
-  return {
-    platformDescriptor: Object.getOwnPropertyDescriptor(process, "platform"),
-    env: {
-      PATH: process.env.PATH,
-      Path: process.env.Path,
-      PATHEXT: process.env.PATHEXT,
-      Pathext: process.env.Pathext,
-    },
-  };
-}
-
-export function restorePlatformPathEnv(snapshot: PlatformPathEnvSnapshot): void {
-  if (snapshot.platformDescriptor) {
-    Object.defineProperty(process, "platform", snapshot.platformDescriptor);
-  }
-
-  for (const key of PATH_ENV_KEYS) {
-    const value = snapshot.env[key];
-    if (value === undefined) {
-      delete process.env[key];
-      continue;
-    }
-    process.env[key] = value;
-  }
-}
-export { createWindowsCmdShimFixture } from "../../shared/windows-cmd-shim-test-fixtures.js";