Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 authenti
The 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.ts
index 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.ts
index 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}.`,
);
}