The Open Framework for Building Agents
fix: explain when a failed remote call may have completed (#4463)
Philipp Comans192732a4ce18
diff --git a/.changeset/remote-agent-uncertain-outcomes.md b/.changeset/remote-agent-uncertain-outcomes.mdnew file mode 100644index 000000000..dc1f91f02--- /dev/null+++ b/.changeset/remote-agent-uncertain-outcomes.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Remote-agent create requests now report that work may have completed when a successful response has an incompatible protocol or unreadable body. These failures stop automatic workflow retries, and protocol mismatches include the remote session ID for checking the outcome.diff --git a/docs/guides/remote-agents.md b/docs/guides/remote-agents.mdindex 12e9c6224..6f23f5279 100644--- a/docs/guides/remote-agents.md+++ b/docs/guides/remote-agents.md@@ -217,6 +217,13 @@ When the workflow run that opened a remote child finishes, eve sends an authentiThe parent names its eve remote agent protocol version when it creates the child, and the remote answers with the version it serves. A remote also serves parents on protocol 1 (eve 0.66 through 0.68), including their approvals and sign-in requests, so upgrade remote agents before their callers; see [Upgrade remote agents before their callers](../tools/tasks-upgrade#upgrade-remote-agents-before-their-callers). Any other mismatch fails the call at start with an error naming both versions. A failed _start_ fails the call immediately. After a remote starts, a terminal failure callback fails the call with the remote's error. Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than completing the call, so the engine retries it.+If a remote accepts the create request but its response has an incompatible+protocol or an unreadable body, the work may have completed. eve stops workflow+retries and reports that uncertainty. A protocol mismatch includes the accepted+remote session ID so you can inspect the outcome before sending another request.+Upgrading the remote does not undo work that it already performed. A receiver's+explicit protocol rejection remains a compatibility error.+## What to read next- Local delegation and the isolation boundary → [Subagents](../subagents)diff --git a/packages/eve/src/execution/agent-sessions/remote.test.ts b/packages/eve/src/execution/agent-sessions/remote.test.tsindex 2dcf4e808..48c60f1f5 100644--- a/packages/eve/src/execution/agent-sessions/remote.test.ts+++ b/packages/eve/src/execution/agent-sessions/remote.test.ts@@ -1,5 +1,6 @@import { afterEach, describe, expect, it, vi } from "vitest";+import { FatalError } from "#compiled/@workflow/core/index.js";import type { SessionAuthContext } from "#channel/types.js";import { readForwardedParentSessionBaggage } from "#protocol/baggage.js";import {@@ -331,38 +332,77 @@ describe("startRemoteAgentSession", () => {});});- it("rejects the former create-session response shape", async () => {- const fetchMock = vi- .fn()- .mockResolvedValue(- new Response(JSON.stringify({ ok: true, sessionId: "remote-session" }), { status: 202 }),- );+ it.each([+ ["the former response shape", () => Response.json({ ok: true, sessionId: "remote-session" })],+ ["a missing session ID", () => Response.json({ ok: true })],+ ["non-JSON", () => new Response("accepted")],+ ])("stops replay and reports an unknown outcome after accepting %s", async (_label, response) => {+ const fetchMock = vi.fn().mockResolvedValue(response());vi.stubGlobal("fetch", fetchMock);- await expect(- startRemoteAgentSession({- action: createAction(),- callbackBaseUrl: "https://caller.example.com",- remote: createRemoteAgent(),- session: { continuationToken: "eve:parent-token" },- }),- ).rejects.toThrow("create-session response was invalid");+ const result = startRemoteAgentSession({+ action: createAction(),+ callbackBaseUrl: "https://caller.example.com",+ remote: createRemoteAgent(),+ session: { continuationToken: "eve:parent-token" },+ });+ await expect(result).rejects.toBeInstanceOf(FatalError);+ await expect(result).rejects.toThrow("may have completed");+ await expect(result).rejects.toThrow("Do not retry automatically");+ expect(fetchMock).toHaveBeenCalledTimes(1);});- it("rejects a create-session response without any sessionId", async () => {- const fetchMock = vi- .fn()- .mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 202 }));- vi.stubGlobal("fetch", fetchMock);+ it.each([1, undefined])(+ "reports accepted protocol %s work as potentially completed",+ async (protocolVersion) => {+ const fetchMock = vi.fn().mockResolvedValue(+ Response.json(+ {+ ok: true,+ protocolVersion,+ sessionId: "remote-session",+ status: "accepted",+ },+ { status: 202 },+ ),+ );+ vi.stubGlobal("fetch", fetchMock);- await expect(- startRemoteAgentSession({+ const result = startRemoteAgentSession({action: createAction(),callbackBaseUrl: "https://caller.example.com",remote: createRemoteAgent(),session: { continuationToken: "eve:parent-token" },- }),- ).rejects.toThrow("create-session response was invalid");+ });+ await expect(result).rejects.toBeInstanceOf(FatalError);+ await expect(result).rejects.toThrow("may have completed");+ await expect(result).rejects.toThrow("Remote session: remote-session");+ expect(fetchMock).toHaveBeenCalledTimes(1);+ },+ );++ it("keeps a receiver's protocol rejection distinct from accepted work", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn().mockResolvedValue(+ Response.json(+ {+ code: "REMOTE_AGENT_PROTOCOL_MISMATCH",+ protocolVersion: 3,+ },+ { status: 409 },+ ),+ ),+ );+ const result = startRemoteAgentSession({+ action: createAction(),+ callbackBaseUrl: "https://caller.example.com",+ remote: createRemoteAgent(),+ session: { continuationToken: "eve:parent-token" },+ });+ await expect(result).rejects.toBeInstanceOf(FatalError);+ await expect(result).rejects.toThrow("protocol 3");+ await expect(result).rejects.not.toThrow("may have completed");});it("preserves a prefixed remote base path on create-session requests", async () => {diff --git a/packages/eve/src/execution/agent-sessions/remote.ts b/packages/eve/src/execution/agent-sessions/remote.tsindex 3b43525c4..8bc759139 100644--- a/packages/eve/src/execution/agent-sessions/remote.ts+++ b/packages/eve/src/execution/agent-sessions/remote.ts@@ -51,6 +51,9 @@ const CreateSessionResponseSchema = z.object({status: z.literal("accepted"),});+const UNKNOWN_REMOTE_OUTCOME =+ "The request may have completed on the remote agent. Do not retry automatically; check the remote outcome before sending the request again.";+type RemoteAgentSessionCoordinates = {readonly sessionId: string;};@@ -167,21 +170,21 @@ export async function startRemoteAgentSession(input: {try {body = await response.json();} catch {- throw new Error(- `Remote agent "${input.action.remoteAgentName}" create-session response was not valid JSON.`,+ throw new FatalError(+ `Remote agent "${input.action.remoteAgentName}" create-session response was not valid JSON. ${UNKNOWN_REMOTE_OUTCOME}`,);}const parsed = CreateSessionResponseSchema.safeParse(body);if (!parsed.success) {- throw new Error(- `Remote agent "${input.action.remoteAgentName}" create-session response was invalid.`,+ throw new FatalError(+ `Remote agent "${input.action.remoteAgentName}" create-session response was invalid. ${UNKNOWN_REMOTE_OUTCOME}`,);}const receiverVersion = readRemoteAgentProtocolVersion(parsed.data.protocolVersion);if (receiverVersion !== REMOTE_AGENT_PROTOCOL_VERSION) {throw new FatalError(- formatRemoteAgentProtocolMismatch({ name: input.action.remoteAgentName, receiverVersion }),+ `${formatRemoteAgentProtocolMismatch({ name: input.action.remoteAgentName, receiverVersion })} ${UNKNOWN_REMOTE_OUTCOME} Remote session: ${parsed.data.sessionId}.`,);}