fix(lobster): keep ordinary run/resume on default flow fields (#102036)

LiLan0125 · vincentkoc · web-flow · commit 8cb92636920b · 2026-07-07T23:04:01.000-07:00
* fix(lobster): keep default flow fields on runner path

* fix(lobster): reject incomplete managed resume revisions

* fix(lobster): preserve explicit empty managed flow state

* fix(lobster): preserve cross-mode validation

---------

Co-authored-by: Vincent Koc &lt;vincentkoc@ieee.org&gt;
diff --git a/extensions/lobster/src/lobster-tool.test.ts b/extensions/lobster/src/lobster-tool.test.ts
@@ -110,6 +110,139 @@ describe("lobster plugin tool", () => {
     expect(approval.resumeToken).toBe("resume-token-1");
   });
 
+  it("keeps ordinary run on the embedded runner when flow defaults are injected", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
+        ok: true,
+        status: "needs_approval",
+        output: [],
+        requiresApproval: {
+          type: "approval_request",
+          prompt: "Continue?",
+          items: [],
+          resumeToken: "resume-token-1",
+        },
+      }),
+    };
+    const taskFlow = createFakeTaskFlow();
+
+    const tool = createLobsterTool(fakeApi(), { runner, taskFlow });
+    const res = await tool.execute("call-default-flow-run", {
+      action: "run",
+      pipeline: "noop",
+      flowStateJson: "{}",
+      flowExpectedRevision: 0,
+    });
+
+    expect(taskFlow.createManaged).not.toHaveBeenCalled();
+    expect(runner.run).toHaveBeenCalledWith({
+      action: "run",
+      pipeline: "noop",
+      cwd: process.cwd(),
+      timeoutMs: 20_000,
+      maxStdoutBytes: 512_000,
+    });
+    const details = requireRecord(res.details, "ordinary run with flow defaults details");
+    expect(details.status).toBe("needs_approval");
+  });
+
+  it.each([{ flowId: "flow-1" }, { flowExpectedRevision: 1 }])(
+    "rejects resume-only fields on run before the ordinary fallback",
+    async (resumeFields) => {
+      const runner = { run: vi.fn() };
+      const tool = createLobsterTool(fakeApi(), {
+        runner,
+        taskFlow: createFakeTaskFlow(),
+      });
+
+      await expect(
+        tool.execute("call-run-with-resume-fields", {
+          action: "run",
+          pipeline: "noop",
+          flowStateJson: "{}",
+          flowExpectedRevision: 0,
+          ...resumeFields,
+        }),
+      ).rejects.toThrow(/run action does not accept flowId or flowExpectedRevision/);
+      expect(runner.run).not.toHaveBeenCalled();
+    },
+  );
+
+  it("keeps ordinary resume on the embedded runner when flow defaults are injected", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
+        ok: true,
+        status: "ok",
+        output: [{ approved: true }],
+        requiresApproval: null,
+      }),
+    };
+    const taskFlow = createFakeTaskFlow();
+
+    const tool = createLobsterTool(fakeApi(), { runner, taskFlow });
+    const res = await tool.execute("call-default-flow-resume", {
+      action: "resume",
+      token: "resume-token-1",
+      approve: true,
+      flowStateJson: "{}",
+      flowExpectedRevision: 0,
+    });
+
+    expect(taskFlow.resume).not.toHaveBeenCalled();
+    expect(runner.run).toHaveBeenCalledWith({
+      action: "resume",
+      token: "resume-token-1",
+      approve: true,
+      cwd: process.cwd(),
+      timeoutMs: 20_000,
+      maxStdoutBytes: 512_000,
+    });
+    const details = requireRecord(res.details, "ordinary resume with flow defaults details");
+    expect(details.ok).toBe(true);
+    expect(details.status).toBe("ok");
+  });
+
+  it.each([
+    { flowControllerId: "tests/lobster" },
+    { flowGoal: "Run Lobster workflow" },
+    { flowStateJson: '{"lane":"email"}' },
+  ])("rejects run-only fields on resume before the ordinary fallback", async (runFields) => {
+    const runner = { run: vi.fn() };
+    const tool = createLobsterTool(fakeApi(), {
+      runner,
+      taskFlow: createFakeTaskFlow(),
+    });
+
+    await expect(
+      tool.execute("call-resume-with-run-fields", {
+        action: "resume",
+        token: "resume-token-1",
+        approve: true,
+        flowExpectedRevision: 0,
+        ...runFields,
+      }),
+    ).rejects.toThrow(/resume action does not accept flowControllerId, flowGoal, or flowStateJson/);
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
+  it("rejects resume with a non-default flow revision but no flowId", async () => {
+    const runner = { run: vi.fn() };
+    const tool = createLobsterTool(fakeApi(), {
+      runner,
+      taskFlow: createFakeTaskFlow(),
+    });
+
+    await expect(
+      tool.execute("call-revision-without-flow-id", {
+        action: "resume",
+        token: "resume-token-1",
+        approve: true,
+        flowExpectedRevision: 1,
+      }),
+    ).rejects.toThrow(/flowId required when using managed TaskFlow resume mode/);
+    expect(runner.run).not.toHaveBeenCalled();
+  });
+
   it("normalizes numeric string run limits before invoking the runner", async () => {
     const runner = {
       run: vi.fn().mockResolvedValue({
@@ -203,6 +336,7 @@ describe("lobster plugin tool", () => {
       flowControllerId: "tests/lobster",
       flowGoal: "Run Lobster workflow",
       flowStateJson: '{"lane":"email"}',
+      flowExpectedRevision: 0,
       flowCurrentStep: "run_lobster",
       flowWaitingStep: "await_review",
     });
@@ -234,6 +368,41 @@ describe("lobster plugin tool", () => {
     expect(mutation.applied).toBe(true);
   });
 
+  it("preserves explicit empty flow state in managed TaskFlow run mode", async () => {
+    const runner = {
+      run: vi.fn().mockResolvedValue({
+        ok: true,
+        status: "ok",
+        output: [],
+        requiresApproval: null,
+      }),
+    };
+    const taskFlow = createFakeTaskFlow();
+
+    const tool = createLobsterTool(fakeApi(), { runner, taskFlow });
+    await tool.execute("call-managed-run-empty-state", {
+      action: "run",
+      pipeline: "noop",
+      flowControllerId: "tests/lobster",
+      flowGoal: "Run Lobster workflow",
+      flowStateJson: "{}",
+    });
+
+    expect(taskFlow.createManaged).toHaveBeenCalledWith({
+      controllerId: "tests/lobster",
+      goal: "Run Lobster workflow",
+      currentStep: "run_lobster",
+      stateJson: {},
+    });
+    expect(runner.run).toHaveBeenCalledWith({
+      action: "run",
+      pipeline: "noop",
+      cwd: process.cwd(),
+      timeoutMs: 20_000,
+      maxStdoutBytes: 512_000,
+    });
+  });
+
   it("rejects managed TaskFlow params when no bound taskFlow runtime is available", async () => {
     const tool = createLobsterTool(fakeApi(), {
       runner: { run: vi.fn() },
@@ -284,6 +453,7 @@ describe("lobster plugin tool", () => {
       approve: true,
       flowId: "flow-1",
       flowExpectedRevision: 1,
+      flowStateJson: "{}",
       flowCurrentStep: "resume_lobster",
     });
 
diff --git a/extensions/lobster/src/lobster-tool.ts b/extensions/lobster/src/lobster-tool.ts
@@ -97,13 +97,27 @@ function parseOptionalFlowStateJson(value: unknown): JsonLike | undefined {
   if (typeof value !== "string") {
     throw new Error("flowStateJson must be a JSON string");
   }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
   try {
-    return JSON.parse(value) as JsonLike;
+    return JSON.parse(trimmed) as JsonLike;
   } catch {
     throw new Error("flowStateJson must be valid JSON");
   }
 }
 
+function isEmptyJsonObject(value: JsonLike | undefined): boolean {
+  return (
+    value !== undefined &&
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 0
+  );
+}
+
 function parseRunFlowParams(params: Record<string, unknown>): ManagedFlowRunParams | null {
   const controllerId = readOptionalTrimmedString(params.flowControllerId, "flowControllerId");
   const goal = readOptionalTrimmedString(params.flowGoal, "flowGoal");
@@ -112,20 +126,22 @@ function parseRunFlowParams(params: Record<string, unknown>): ManagedFlowRunPara
   const stateJson = parseOptionalFlowStateJson(params.flowStateJson);
   const resumeFlowId = readOptionalTrimmedString(params.flowId, "flowId");
   const resumeRevision = readOptionalNumber(params.flowExpectedRevision, "flowExpectedRevision");
+  const stateJsonSignalsRunMode = stateJson !== undefined && !isEmptyJsonObject(stateJson);
+
+  if (resumeFlowId !== undefined || (resumeRevision !== undefined && resumeRevision !== 0)) {
+    throw new Error("run action does not accept flowId or flowExpectedRevision");
+  }
 
   const hasRunFields =
     controllerId !== undefined ||
     goal !== undefined ||
     currentStep !== undefined ||
     waitingStep !== undefined ||
-    stateJson !== undefined;
+    stateJsonSignalsRunMode;
 
   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");
   }
@@ -151,20 +167,22 @@ function parseResumeFlowParams(params: Record<string, unknown>): ManagedFlowResu
   const approve = readOptionalBoolean(params.approve, "approve");
   const runControllerId = readOptionalTrimmedString(params.flowControllerId, "flowControllerId");
   const runGoal = readOptionalTrimmedString(params.flowGoal, "flowGoal");
-  const stateJson = params.flowStateJson;
+  const stateJson = parseOptionalFlowStateJson(params.flowStateJson);
+  const stateJsonDisallowed = stateJson !== undefined && !isEmptyJsonObject(stateJson);
+
+  if (runControllerId !== undefined || runGoal !== undefined || stateJsonDisallowed) {
+    throw new Error("resume action does not accept flowControllerId, flowGoal, or flowStateJson");
+  }
 
   const hasResumeFields =
     flowId !== undefined ||
-    expectedRevision !== undefined ||
+    (expectedRevision !== undefined && expectedRevision !== 0) ||
     currentStep !== undefined ||
     waitingStep !== undefined;
 
   if (!hasResumeFields) {
     return null;
   }
-  if (runControllerId !== undefined || runGoal !== undefined || stateJson !== undefined) {
-    throw new Error("resume action does not accept flowControllerId, flowGoal, or flowStateJson");
-  }
   if (!flowId) {
     throw new Error("flowId required when using managed TaskFlow resume mode");
   }
