@openclaw/lobster 2026.5.2 → 2026.5.3-beta.2

package/src/lobster-runner.ts

@@ -1,395 +0,0 @@
-import { readFileSync } from "node:fs";
-import { stat } from "node:fs/promises";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { Readable, Writable } from "node:stream";
-import { pathToFileURL } from "node:url";
-import { installLobsterAjvCompileCache } from "./lobster-ajv-cache.js";
-
-export type LobsterEnvelope =
-  | {
-      ok: true;
-      status: "ok" | "needs_approval" | "cancelled";
-      output: unknown[];
-      requiresApproval: null | {
-        type: "approval_request";
-        prompt: string;
-        items: unknown[];
-        resumeToken?: string;
-        approvalId?: string;
-      };
-    }
-  | {
-      ok: false;
-      error: { type?: string; message: string };
-    };
-
-export type LobsterRunnerParams = {
-  action: "run" | "resume";
-  pipeline?: string;
-  argsJson?: string;
-  token?: string;
-  approvalId?: string;
-  approve?: boolean;
-  cwd: string;
-  timeoutMs: number;
-  maxStdoutBytes: number;
-};
-
-export type LobsterRunner = {
-  run: (params: LobsterRunnerParams) => Promise<LobsterEnvelope>;
-};
-
-type EmbeddedToolContext = {
-  cwd?: string;
-  env?: Record<string, string | undefined>;
-  mode?: "tool" | "human" | "sdk";
-  stdin?: NodeJS.ReadableStream;
-  stdout?: NodeJS.WritableStream;
-  stderr?: NodeJS.WritableStream;
-  signal?: AbortSignal;
-  registry?: unknown;
-  llmAdapters?: Record<string, unknown>;
-};
-
-type EmbeddedToolEnvelope = {
-  protocolVersion?: number;
-  ok: boolean;
-  status?: "ok" | "needs_approval" | "needs_input" | "cancelled";
-  output?: unknown[];
-  requiresApproval?: {
-    type?: "approval_request";
-    prompt: string;
-    items: unknown[];
-    preview?: string;
-    resumeToken?: string;
-    approvalId?: string;
-  } | null;
-  requiresInput?: {
-    prompt: string;
-    schema?: unknown;
-    items?: unknown[];
-    resumeToken?: string;
-    approvalId?: string;
-  } | null;
-  error?: {
-    type?: string;
-    message: string;
-  };
-};
-
-type EmbeddedToolRuntime = {
-  runToolRequest: (params: {
-    pipeline?: string;
-    filePath?: string;
-    args?: Record<string, unknown>;
-    ctx?: EmbeddedToolContext;
-  }) => Promise<EmbeddedToolEnvelope>;
-  resumeToolRequest: (params: {
-    token?: string;
-    approvalId?: string;
-    approved?: boolean;
-    response?: unknown;
-    cancel?: boolean;
-    ctx?: EmbeddedToolContext;
-  }) => Promise<EmbeddedToolEnvelope>;
-};
-
-type LoadEmbeddedToolRuntime = () => Promise<EmbeddedToolRuntime>;
-
-type LoadEmbeddedToolRuntimeFromPackageOptions = {
-  importModule?: (specifier: string) => Promise<Partial<EmbeddedToolRuntime>>;
-  resolvePackageEntry?: (specifier: string) => string;
-};
-
-const lobsterRequire = createRequire(import.meta.url);
-
-function toEmbeddedToolRuntime(
-  moduleExports: Partial<EmbeddedToolRuntime>,
-  source: string,
-): EmbeddedToolRuntime {
-  const { runToolRequest, resumeToolRequest } = moduleExports;
-  if (typeof runToolRequest === "function" && typeof resumeToolRequest === "function") {
-    return { runToolRequest, resumeToolRequest };
-  }
-  throw new Error(`${source} does not export Lobster embedded runtime functions`);
-}
-
-function findLobsterPackageRoot(resolvedEntryPath: string): string {
-  let dir = path.dirname(resolvedEntryPath);
-  while (true) {
-    const packageJsonPath = path.join(dir, "package.json");
-    try {
-      const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { name?: string };
-      if (parsed.name === "@clawdbot/lobster") {
-        return dir;
-      }
-    } catch {
-      // Keep walking until the installed package root is found.
-    }
-
-    const parent = path.dirname(dir);
-    if (parent === dir) {
-      throw new Error(`Could not locate @clawdbot/lobster package root from ${resolvedEntryPath}`);
-    }
-    dir = parent;
-  }
-}
-
-function normalizeForCwdSandbox(p: string): string {
-  const normalized = path.normalize(p);
-  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
-}
-
-export function resolveLobsterCwd(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 createLimitedSink(maxBytes: number, label: "stdout" | "stderr") {
-  let bytes = 0;
-  return new Writable({
-    write(chunk, _encoding, callback) {
-      bytes += Buffer.byteLength(String(chunk), "utf8");
-      if (bytes > maxBytes) {
-        callback(new Error(`lobster ${label} exceeded maxStdoutBytes`));
-        return;
-      }
-      callback();
-    },
-  });
-}
-
-function normalizeEnvelope(envelope: EmbeddedToolEnvelope): LobsterEnvelope {
-  if (envelope.ok) {
-    if (envelope.status === "needs_input") {
-      return {
-        ok: false,
-        error: {
-          type: "unsupported_status",
-          message: "Lobster input requests are not supported by the OpenClaw Lobster tool yet",
-        },
-      };
-    }
-    return {
-      ok: true,
-      status: envelope.status ?? "ok",
-      output: Array.isArray(envelope.output) ? envelope.output : [],
-      requiresApproval: envelope.requiresApproval
-        ? {
-            type: "approval_request",
-            prompt: envelope.requiresApproval.prompt,
-            items: envelope.requiresApproval.items,
-            ...(envelope.requiresApproval.resumeToken
-              ? { resumeToken: envelope.requiresApproval.resumeToken }
-              : {}),
-            ...(envelope.requiresApproval.approvalId
-              ? { approvalId: envelope.requiresApproval.approvalId }
-              : {}),
-          }
-        : null,
-    };
-  }
-  return {
-    ok: false,
-    error: {
-      type: envelope.error?.type,
-      message: envelope.error?.message ?? "lobster runtime failed",
-    },
-  };
-}
-
-function throwOnErrorEnvelope(envelope: LobsterEnvelope): Extract<LobsterEnvelope, { ok: true }> {
-  if (envelope.ok) {
-    return envelope;
-  }
-  throw new Error(envelope.error.message);
-}
-
-async function resolveWorkflowFile(candidate: string, cwd: string) {
-  const resolved = path.isAbsolute(candidate) ? candidate : path.resolve(cwd, candidate);
-  const fileStat = await stat(resolved);
-  if (!fileStat.isFile()) {
-    throw new Error("Workflow path is not a file");
-  }
-  const ext = path.extname(resolved).toLowerCase();
-  if (![".lobster", ".yaml", ".yml", ".json"].includes(ext)) {
-    throw new Error("Workflow file must end in .lobster, .yaml, .yml, or .json");
-  }
-  return resolved;
-}
-
-async function detectWorkflowFile(candidate: string, cwd: string) {
-  const trimmed = candidate.trim();
-  if (!trimmed || trimmed.includes("|")) {
-    return null;
-  }
-  try {
-    return await resolveWorkflowFile(trimmed, cwd);
-  } catch {
-    return null;
-  }
-}
-
-function parseWorkflowArgs(argsJson: string) {
-  return JSON.parse(argsJson) as Record<string, unknown>;
-}
-
-function createEmbeddedToolContext(
-  params: LobsterRunnerParams,
-  signal?: AbortSignal,
-): EmbeddedToolContext {
-  const env = { ...process.env } as Record<string, string | undefined>;
-  return {
-    cwd: params.cwd,
-    env,
-    mode: "tool",
-    stdin: Readable.from([]),
-    stdout: createLimitedSink(Math.max(1024, params.maxStdoutBytes), "stdout"),
-    stderr: createLimitedSink(Math.max(1024, params.maxStdoutBytes), "stderr"),
-    signal,
-  };
-}
-
-async function withTimeout<T>(
-  timeoutMs: number,
-  fn: (signal?: AbortSignal) => Promise<T>,
-): Promise<T> {
-  const timeout = Math.max(200, timeoutMs);
-  const controller = new AbortController();
-  return await new Promise<T>((resolve, reject) => {
-    const onTimeout = () => {
-      const error = new Error("lobster runtime timed out");
-      controller.abort(error);
-      reject(error);
-    };
-
-    const timer = setTimeout(onTimeout, timeout);
-    void fn(controller.signal).then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (error) => {
-        clearTimeout(timer);
-        reject(error);
-      },
-    );
-  });
-}
-
-export async function loadEmbeddedToolRuntimeFromPackage(
-  options: LoadEmbeddedToolRuntimeFromPackageOptions = {},
-): Promise<EmbeddedToolRuntime> {
-  installLobsterAjvCompileCache();
-
-  const importModule =
-    options.importModule ??
-    (async (specifier: string) => (await import(specifier)) as Partial<EmbeddedToolRuntime>);
-  const resolvePackageEntry =
-    options.resolvePackageEntry ?? ((specifier: string) => lobsterRequire.resolve(specifier));
-
-  let coreLoadError: unknown;
-  try {
-    const coreSpecifier = ["@clawdbot", "lobster", "core"].join("/");
-    return toEmbeddedToolRuntime(await importModule(coreSpecifier), "@clawdbot/lobster/core");
-  } catch (error) {
-    coreLoadError = error;
-  }
-
-  let fallbackLoadError: unknown;
-  try {
-    const packageEntryPath = 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) {
-    fallbackLoadError = error;
-  }
-
-  throw new Error("Failed to load the Lobster embedded runtime", {
-    cause: new AggregateError(
-      [coreLoadError, fallbackLoadError],
-      "Both Lobster embedded runtime load paths failed",
-    ),
-  });
-}
-
-export function createEmbeddedLobsterRunner(options?: {
-  loadRuntime?: LoadEmbeddedToolRuntime;
-}): LobsterRunner {
-  const loadRuntime = options?.loadRuntime ?? loadEmbeddedToolRuntimeFromPackage;
-  let runtimePromise: Promise<EmbeddedToolRuntime> | undefined;
-  return {
-    async run(params) {
-      runtimePromise ??= loadRuntime();
-      const runtime = await runtimePromise;
-      return await withTimeout(params.timeoutMs, async (signal) => {
-        const ctx = createEmbeddedToolContext(params, signal);
-
-        if (params.action === "run") {
-          const pipeline = params.pipeline?.trim() ?? "";
-          if (!pipeline) {
-            throw new Error("pipeline required");
-          }
-
-          const filePath = await detectWorkflowFile(pipeline, params.cwd);
-          if (filePath) {
-            const parsedArgsJson = params.argsJson?.trim() ?? "";
-            let args: Record<string, unknown> | undefined;
-            if (parsedArgsJson) {
-              try {
-                args = parseWorkflowArgs(parsedArgsJson);
-              } catch {
-                throw new Error("run --args-json must be valid JSON");
-              }
-            }
-            return throwOnErrorEnvelope(
-              normalizeEnvelope(await runtime.runToolRequest({ filePath, args, ctx })),
-            );
-          }
-
-          return throwOnErrorEnvelope(
-            normalizeEnvelope(await runtime.runToolRequest({ pipeline, ctx })),
-          );
-        }
-
-        const token = params.token?.trim() ?? "";
-        const approvalId = params.approvalId?.trim() ?? "";
-        if (!token && !approvalId) {
-          throw new Error("token or approvalId required");
-        }
-        if (typeof params.approve !== "boolean") {
-          throw new Error("approve required");
-        }
-
-        return throwOnErrorEnvelope(
-          normalizeEnvelope(
-            await runtime.resumeToolRequest({
-              ...(token ? { token } : {}),
-              ...(approvalId ? { approvalId } : {}),
-              approved: params.approve,
-              ctx,
-            }),
-          ),
-        );
-      });
-    },
-  };
-}

package/src/lobster-taskflow.test.ts

@@ -1,227 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { LobsterRunner } from "./lobster-runner.js";
-import { resumeManagedLobsterFlow, runManagedLobsterFlow } from "./lobster-taskflow.js";
-import { createFakeTaskFlow } from "./taskflow-test-helpers.js";
-
-function expectManagedFlowFailure(
-  result: Awaited<ReturnType<typeof runManagedLobsterFlow | typeof resumeManagedLobsterFlow>>,
-) {
-  expect(result.ok).toBe(false);
-  if (result.ok) {
-    throw new Error("Expected managed Lobster flow to fail");
-  }
-  return result;
-}
-function createRunner(result: Awaited<ReturnType<LobsterRunner["run"]>>): LobsterRunner {
-  return {
-    run: vi.fn().mockResolvedValue(result),
-  };
-}
-
-function createRunFlowParams(
-  taskFlow: ReturnType<typeof createFakeTaskFlow>,
-  runner: LobsterRunner,
-): Parameters<typeof runManagedLobsterFlow>[0] {
-  return {
-    taskFlow,
-    runner,
-    runnerParams: {
-      action: "run",
-      pipeline: "noop",
-      cwd: process.cwd(),
-      timeoutMs: 1000,
-      maxStdoutBytes: 4096,
-    },
-    controllerId: "tests/lobster",
-    goal: "Run Lobster workflow",
-  };
-}
-
-function createResumeFlowParams(
-  taskFlow: ReturnType<typeof createFakeTaskFlow>,
-  runner: LobsterRunner,
-): Parameters<typeof resumeManagedLobsterFlow>[0] {
-  return {
-    taskFlow,
-    runner,
-    flowId: "flow-1",
-    expectedRevision: 4,
-    runnerParams: {
-      action: "resume",
-      token: "resume-1",
-      approve: true,
-      cwd: process.cwd(),
-      timeoutMs: 1000,
-      maxStdoutBytes: 4096,
-    },
-  };
-}
-
-describe("runManagedLobsterFlow", () => {
-  it("creates a flow and finishes it when Lobster succeeds", async () => {
-    const taskFlow = createFakeTaskFlow();
-    const runner = createRunner({
-      ok: true,
-      status: "ok",
-      output: [{ id: "result-1" }],
-      requiresApproval: null,
-    });
-
-    const result = await runManagedLobsterFlow(createRunFlowParams(taskFlow, runner));
-
-    expect(result.ok).toBe(true);
-    expect(taskFlow.createManaged).toHaveBeenCalledWith({
-      controllerId: "tests/lobster",
-      goal: "Run Lobster workflow",
-      currentStep: "run_lobster",
-    });
-    expect(taskFlow.finish).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 1,
-    });
-  });
-
-  it("moves the flow to waiting when Lobster requests approval", async () => {
-    const taskFlow = createFakeTaskFlow();
-    const createdAt = new Date("2026-04-05T21:00:00.000Z");
-    const runner = createRunner({
-      ok: true,
-      status: "needs_approval",
-      output: [],
-      requiresApproval: {
-        type: "approval_request",
-        prompt: "Approve this?",
-        items: [{ id: "item-1", createdAt, count: 2n, skip: undefined }],
-        resumeToken: "resume-1",
-      },
-    });
-
-    const result = await runManagedLobsterFlow(createRunFlowParams(taskFlow, runner));
-
-    expect(result.ok).toBe(true);
-    expect(taskFlow.setWaiting).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 1,
-      currentStep: "await_lobster_approval",
-      waitJson: {
-        kind: "lobster_approval",
-        prompt: "Approve this?",
-        items: [{ id: "item-1", createdAt: createdAt.toISOString(), count: "2" }],
-        resumeToken: "resume-1",
-      },
-    });
-  });
-
-  it("fails the flow when Lobster returns an error envelope", async () => {
-    const taskFlow = createFakeTaskFlow();
-    const runner = createRunner({
-      ok: false,
-      error: {
-        type: "runtime_error",
-        message: "boom",
-      },
-    });
-
-    const result = expectManagedFlowFailure(
-      await runManagedLobsterFlow(createRunFlowParams(taskFlow, runner)),
-    );
-    expect(result.error.message).toBe("boom");
-    expect(taskFlow.fail).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 1,
-    });
-  });
-
-  it("fails the flow when the runner throws", async () => {
-    const taskFlow = createFakeTaskFlow();
-    const runner: LobsterRunner = {
-      run: vi.fn().mockRejectedValue(new Error("crashed")),
-    };
-
-    const result = expectManagedFlowFailure(
-      await runManagedLobsterFlow(createRunFlowParams(taskFlow, runner)),
-    );
-    expect(result.error.message).toBe("crashed");
-    expect(taskFlow.fail).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 1,
-    });
-  });
-});
-
-describe("resumeManagedLobsterFlow", () => {
-  it("resumes the flow and finishes it on success", async () => {
-    const taskFlow = createFakeTaskFlow();
-    const runner = createRunner({
-      ok: true,
-      status: "ok",
-      output: [],
-      requiresApproval: null,
-    });
-
-    const result = await resumeManagedLobsterFlow(createResumeFlowParams(taskFlow, runner));
-
-    expect(result.ok).toBe(true);
-    expect(taskFlow.resume).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 4,
-      status: "running",
-      currentStep: "resume_lobster",
-    });
-    expect(taskFlow.finish).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 5,
-    });
-  });
-
-  it("returns a mutation error when taskFlow resume is rejected", async () => {
-    const taskFlow = createFakeTaskFlow({
-      resume: vi.fn().mockReturnValue({
-        applied: false,
-        code: "revision_conflict",
-      }),
-    });
-    const runner = createRunner({
-      ok: true,
-      status: "ok",
-      output: [],
-      requiresApproval: null,
-    });
-
-    const result = expectManagedFlowFailure(
-      await resumeManagedLobsterFlow(createResumeFlowParams(taskFlow, runner)),
-    );
-    expect(result.error.message).toMatch(/revision_conflict/);
-    expect(runner.run).not.toHaveBeenCalled();
-  });
-
-  it("returns to waiting when the resumed Lobster run needs approval again", async () => {
-    const taskFlow = createFakeTaskFlow();
-    const runner = createRunner({
-      ok: true,
-      status: "needs_approval",
-      output: [],
-      requiresApproval: {
-        type: "approval_request",
-        prompt: "Approve this too?",
-        items: [{ id: "item-2" }],
-        resumeToken: "resume-2",
-      },
-    });
-
-    const result = await resumeManagedLobsterFlow(createResumeFlowParams(taskFlow, runner));
-
-    expect(result.ok).toBe(true);
-    expect(taskFlow.setWaiting).toHaveBeenCalledWith({
-      flowId: "flow-1",
-      expectedRevision: 5,
-      currentStep: "await_lobster_approval",
-      waitJson: {
-        kind: "lobster_approval",
-        prompt: "Approve this too?",
-        items: [{ id: "item-2" }],
-        resumeToken: "resume-2",
-      },
-    });
-  });
-});