@kodelyth/lobster 2026.5.42 → 2026.6.2

package/src/lobster-taskflow.ts

@@ -1,279 +0,0 @@
-import type { KlawPluginApi } from "../runtime-api.js";
-import type { LobsterEnvelope, LobsterRunner, LobsterRunnerParams } from "./lobster-runner.js";
-
-type JsonLike =
-  | null
-  | boolean
-  | number
-  | string
-  | JsonLike[]
-  | {
-      [key: string]: JsonLike;
-    };
-
-type BoundTaskFlow = ReturnType<
-  NonNullable<KlawPluginApi["runtime"]>["tasks"]["managedFlows"]["bindSession"]
->;
-
-type FlowRecord = ReturnType<BoundTaskFlow["createManaged"]>;
-type MutationResult = ReturnType<BoundTaskFlow["setWaiting"]>;
-
-type LobsterApprovalWaitState = {
-  kind: "lobster_approval";
-  prompt: string;
-  items: JsonLike[];
-  resumeToken?: string;
-  approvalId?: string;
-};
-
-type RunManagedLobsterFlowParams = {
-  taskFlow: BoundTaskFlow;
-  runner: LobsterRunner;
-  runnerParams: LobsterRunnerParams;
-  controllerId: string;
-  goal: string;
-  stateJson?: JsonLike;
-  currentStep?: string;
-  waitingStep?: string;
-};
-
-type ResumeManagedLobsterFlowParams = {
-  taskFlow: BoundTaskFlow;
-  runner: LobsterRunner;
-  runnerParams: LobsterRunnerParams & {
-    action: "resume";
-    approve: boolean;
-  } & ({ token: string } | { approvalId: string });
-  flowId: string;
-  expectedRevision: number;
-  currentStep?: string;
-  waitingStep?: string;
-};
-
-export type ManagedLobsterFlowResult =
-  | {
-      ok: true;
-      envelope: LobsterEnvelope;
-      flow: FlowRecord;
-      mutation: MutationResult;
-    }
-  | {
-      ok: false;
-      flow?: FlowRecord;
-      mutation?: MutationResult;
-      error: Error;
-    };
-
-function toJsonLike(value: unknown, seen = new WeakSet<object>()): JsonLike {
-  if (value === null) {
-    return null;
-  }
-  switch (typeof value) {
-    case "boolean":
-    case "string":
-      return value;
-    case "number":
-      return Number.isFinite(value) ? value : String(value);
-    case "bigint":
-      return value.toString();
-    case "undefined":
-    case "function":
-    case "symbol":
-      return null;
-    case "object": {
-      if (value instanceof Date) {
-        return value.toISOString();
-      }
-      if (Array.isArray(value)) {
-        return value.map((item) => toJsonLike(item, seen));
-      }
-      if (seen.has(value)) {
-        return "[Circular]";
-      }
-      seen.add(value);
-      const jsonObject: Record<string, JsonLike> = {};
-      for (const [key, entry] of Object.entries(value)) {
-        if (entry === undefined || typeof entry === "function" || typeof entry === "symbol") {
-          continue;
-        }
-        jsonObject[key] = toJsonLike(entry, seen);
-      }
-      seen.delete(value);
-      return jsonObject;
-    }
-  }
-  return null;
-}
-
-function buildApprovalWaitState(envelope: Extract<LobsterEnvelope, { ok: true }>): JsonLike {
-  if (!envelope.requiresApproval) {
-    return {
-      kind: "lobster_approval",
-      prompt: "",
-      items: [],
-    } satisfies LobsterApprovalWaitState;
-  }
-  return {
-    kind: "lobster_approval",
-    prompt: envelope.requiresApproval.prompt,
-    items: envelope.requiresApproval.items.map((item) => toJsonLike(item)),
-    ...(envelope.requiresApproval.resumeToken
-      ? { resumeToken: envelope.requiresApproval.resumeToken }
-      : {}),
-    ...(envelope.requiresApproval.approvalId
-      ? { approvalId: envelope.requiresApproval.approvalId }
-      : {}),
-  } satisfies LobsterApprovalWaitState;
-}
-
-function applyEnvelopeToFlow(params: {
-  taskFlow: BoundTaskFlow;
-  flow: FlowRecord;
-  envelope: LobsterEnvelope;
-  waitingStep: string;
-}): MutationResult {
-  const { taskFlow, flow, envelope, waitingStep } = params;
-
-  if (!envelope.ok) {
-    return taskFlow.fail({
-      flowId: flow.flowId,
-      expectedRevision: flow.revision,
-    });
-  }
-
-  if (envelope.status === "needs_approval") {
-    return taskFlow.setWaiting({
-      flowId: flow.flowId,
-      expectedRevision: flow.revision,
-      currentStep: waitingStep,
-      waitJson: buildApprovalWaitState(envelope),
-    });
-  }
-
-  return taskFlow.finish({
-    flowId: flow.flowId,
-    expectedRevision: flow.revision,
-  });
-}
-
-function buildEnvelopeError(envelope: Extract<LobsterEnvelope, { ok: false }>) {
-  return new Error(envelope.error.message);
-}
-
-export async function runManagedLobsterFlow(
-  params: RunManagedLobsterFlowParams,
-): Promise<ManagedLobsterFlowResult> {
-  const flow = params.taskFlow.createManaged({
-    controllerId: params.controllerId,
-    goal: params.goal,
-    currentStep: params.currentStep ?? "run_lobster",
-    ...(params.stateJson !== undefined ? { stateJson: params.stateJson } : {}),
-  });
-
-  try {
-    const envelope = await params.runner.run(params.runnerParams);
-    const mutation = applyEnvelopeToFlow({
-      taskFlow: params.taskFlow,
-      flow,
-      envelope,
-      waitingStep: params.waitingStep ?? "await_lobster_approval",
-    });
-    if (!envelope.ok) {
-      return {
-        ok: false,
-        flow,
-        mutation,
-        error: buildEnvelopeError(envelope),
-      };
-    }
-    return {
-      ok: true,
-      envelope,
-      flow,
-      mutation,
-    };
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    try {
-      const mutation = params.taskFlow.fail({
-        flowId: flow.flowId,
-        expectedRevision: flow.revision,
-      });
-      return {
-        ok: false,
-        flow,
-        mutation,
-        error: err,
-      };
-    } catch {
-      return {
-        ok: false,
-        flow,
-        error: err,
-      };
-    }
-  }
-}
-
-export async function resumeManagedLobsterFlow(
-  params: ResumeManagedLobsterFlowParams,
-): Promise<ManagedLobsterFlowResult> {
-  const resumed = params.taskFlow.resume({
-    flowId: params.flowId,
-    expectedRevision: params.expectedRevision,
-    status: "running",
-    currentStep: params.currentStep ?? "resume_lobster",
-  });
-
-  if (!resumed.applied) {
-    return {
-      ok: false,
-      mutation: resumed,
-      error: new Error(`TaskFlow resume failed: ${resumed.code}`),
-    };
-  }
-
-  try {
-    const envelope = await params.runner.run(params.runnerParams);
-    const mutation = applyEnvelopeToFlow({
-      taskFlow: params.taskFlow,
-      flow: resumed.flow,
-      envelope,
-      waitingStep: params.waitingStep ?? "await_lobster_approval",
-    });
-    if (!envelope.ok) {
-      return {
-        ok: false,
-        flow: resumed.flow,
-        mutation,
-        error: buildEnvelopeError(envelope),
-      };
-    }
-    return {
-      ok: true,
-      envelope,
-      flow: resumed.flow,
-      mutation,
-    };
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    try {
-      const mutation = params.taskFlow.fail({
-        flowId: params.flowId,
-        expectedRevision: resumed.flow.revision,
-      });
-      return {
-        ok: false,
-        flow: resumed.flow,
-        mutation,
-        error: err,
-      };
-    } catch {
-      return {
-        ok: false,
-        flow: resumed.flow,
-        error: err,
-      };
-    }
-  }
-}

package/src/lobster-tool.test.ts

@@ -1,352 +0,0 @@
-import { createTestPluginApi } from "klaw/plugin-sdk/plugin-test-api";
-import { describe, expect, it, vi } from "vitest";
-import type { KlawPluginApi, KlawPluginToolContext } from "../runtime-api.js";
-import { createLobsterTool } from "./lobster-tool.js";
-import { createFakeTaskFlow } from "./taskflow-test-helpers.js";
-
-function fakeApi(overrides: Partial<KlawPluginApi> = {}): KlawPluginApi {
-  return createTestPluginApi({
-    id: "lobster",
-    name: "lobster",
-    source: "test",
-    runtime: { version: "test" } as any,
-    resolvePath: (p) => p,
-    ...overrides,
-  });
-}
-
-function fakeCtx(overrides: Partial<KlawPluginToolContext> = {}): KlawPluginToolContext {
-  return {
-    config: {},
-    workspaceDir: "/tmp",
-    agentDir: "/tmp",
-    agentId: "main",
-    sessionKey: "main",
-    messageChannel: undefined,
-    agentAccountId: undefined,
-    sandboxed: false,
-    ...overrides,
-  };
-}
-
-function requireRecord(value: unknown, label: string): Record<string, unknown> {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`expected ${label} to be a record`);
-  }
-  return value as Record<string, unknown>;
-}
-
-describe("lobster plugin tool", () => {
-  it("returns the Lobster envelope in details", async () => {
-    const runner = {
-      run: vi.fn().mockResolvedValue({
-        ok: true,
-        status: "ok",
-        output: [{ hello: "world" }],
-        requiresApproval: null,
-      }),
-    };
-
-    const tool = createLobsterTool(fakeApi(), { runner });
-    const res = await tool.execute("call1", {
-      action: "run",
-      pipeline: "noop",
-      timeoutMs: 1000,
-    });
-
-    expect(runner.run).toHaveBeenCalledWith({
-      action: "run",
-      pipeline: "noop",
-      cwd: process.cwd(),
-      timeoutMs: 1000,
-      maxStdoutBytes: 512_000,
-    });
-    const details = requireRecord(res.details, "lobster tool details");
-    expect(details.ok).toBe(true);
-    expect(details.status).toBe("ok");
-    expect(details.output).toEqual([{ hello: "world" }]);
-    expect(details.requiresApproval).toBeNull();
-  });
-
-  it("supports approval envelopes without changing the tool contract", async () => {
-    const runner = {
-      run: vi.fn().mockResolvedValue({
-        ok: true,
-        status: "needs_approval",
-        output: [],
-        requiresApproval: {
-          type: "approval_request",
-          prompt: "Send these alerts?",
-          items: [{ id: "alert-1" }],
-          resumeToken: "resume-token-1",
-        },
-      }),
-    };
-
-    const tool = createLobsterTool(fakeApi(), { runner });
-    const res = await tool.execute("call-injected-runner", {
-      action: "run",
-      pipeline: "noop",
-      argsJson: '{"since_hours":1}',
-      timeoutMs: 1500,
-      maxStdoutBytes: 4096,
-    });
-
-    expect(runner.run).toHaveBeenCalledWith({
-      action: "run",
-      pipeline: "noop",
-      argsJson: '{"since_hours":1}',
-      cwd: process.cwd(),
-      timeoutMs: 1500,
-      maxStdoutBytes: 4096,
-    });
-    const details = requireRecord(res.details, "approval lobster tool details");
-    expect(details.ok).toBe(true);
-    expect(details.status).toBe("needs_approval");
-    const approval = requireRecord(details.requiresApproval, "approval request");
-    expect(approval.type).toBe("approval_request");
-    expect(approval.prompt).toBe("Send these alerts?");
-    expect(approval.resumeToken).toBe("resume-token-1");
-  });
-
-  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",
-          },
-        }),
-      },
-    });
-
-    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",
-      flowControllerId: "tests/lobster",
-      flowGoal: "Run Lobster workflow",
-      flowStateJson: '{"lane":"email"}',
-      flowCurrentStep: "run_lobster",
-      flowWaitingStep: "await_review",
-    });
-
-    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",
-      },
-    });
-    const details = requireRecord(res.details, "managed run lobster tool details");
-    expect(details.ok).toBe(true);
-    expect(details.status).toBe("needs_approval");
-    const flow = requireRecord(details.flow, "managed run flow details");
-    expect(flow.flowId).toBe("flow-1");
-    const mutation = requireRecord(details.mutation, "managed run mutation details");
-    expect(mutation.applied).toBe(true);
-  });
-
-  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("rejects invalid flowStateJson in managed TaskFlow mode", async () => {
-    const tool = createLobsterTool(fakeApi(), {
-      runner: { run: vi.fn() },
-      taskFlow: createFakeTaskFlow(),
-    });
-
-    await expect(
-      tool.execute("call-invalid-flow-json", {
-        action: "run",
-        pipeline: "noop",
-        flowControllerId: "tests/lobster",
-        flowGoal: "Run Lobster workflow",
-        flowStateJson: "{bad",
-      }),
-    ).rejects.toThrow(/flowStateJson must be valid JSON/);
-  });
-
-  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,
-    });
-    const details = requireRecord(res.details, "managed resume lobster tool details");
-    expect(details.ok).toBe(true);
-    expect(details.status).toBe("ok");
-    const mutation = requireRecord(details.mutation, "managed resume mutation details");
-    expect(mutation.applied).toBe(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-missing-resume-token", {
-        action: "resume",
-        flowId: "flow-1",
-        flowExpectedRevision: 1,
-        approve: true,
-      }),
-    ).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-missing-resume-approve", {
-        action: "resume",
-        token: "resume-token",
-        flowId: "flow-1",
-        flowExpectedRevision: 1,
-      }),
-    ).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(), {
-      runner: { run: vi.fn() },
-    });
-    await expect(
-      tool.execute("call-action-unknown", {
-        action: "explode",
-      }),
-    ).rejects.toThrow(/Unknown action/);
-  });
-
-  it("rejects absolute cwd", async () => {
-    const tool = createLobsterTool(fakeApi(), {
-      runner: { run: vi.fn() },
-    });
-    await expect(
-      tool.execute("call-absolute-cwd", {
-        action: "run",
-        pipeline: "noop",
-        cwd: "/tmp",
-      }),
-    ).rejects.toThrow(/cwd must be a relative path/);
-  });
-
-  it("rejects cwd that escapes the gateway working directory", async () => {
-    const tool = createLobsterTool(fakeApi(), {
-      runner: { run: vi.fn() },
-    });
-    await expect(
-      tool.execute("call-escape-cwd", {
-        action: "run",
-        pipeline: "noop",
-        cwd: "../../etc",
-      }),
-    ).rejects.toThrow(/must stay within/);
-  });
-
-  it("can be gated off in sandboxed contexts", () => {
-    const api = fakeApi();
-    const factoryTool = (ctx: KlawPluginToolContext) => {
-      if (ctx.sandboxed) {
-        return null;
-      }
-      return createLobsterTool(api, {
-        runner: { run: vi.fn() },
-      });
-    };
-
-    expect(factoryTool(fakeCtx({ sandboxed: true }))).toBeNull();
-    expect(factoryTool(fakeCtx({ sandboxed: false }))?.name).toBe("lobster");
-  });
-});