Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): announce parked agents as framework-injected user notes (#1706)

Rui2054b9f65b36
diff --git a/.changeset/agents-listing-system-channel.md b/.changeset/agents-listing-system-channel.md
new file mode 100644
index 000000000..245e434f5
--- /dev/null
+++ b/.changeset/agents-listing-system-channel.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Agent-messaging `<agents>` listings are now announced as framework-injected user-role notes instead of assistant messages appended to history. This fixes parent resume failures on models that reject assistant-final requests (e.g. `This model does not support assistant message prefill` from Claude via AI Gateway) after a persistent child parks, keeps the announcement append-only so provider prompt caches stay warm, and the agent-messaging system prompt now declares the `[Agents]` note as framework-injected.
diff --git a/docs/subagents.mdx b/docs/subagents.mdx
index 4dfbccb78..9f597b432 100644
--- a/docs/subagents.mdx
+++ b/docs/subagents.mdx
@@ -192,7 +192,7 @@ Without the opt-in, delegated children run as one-shot tasks: they answer once a
With it enabled, a child parks after answering instead of terminating, keeping its session and conversation history alive. A failed child turn can also leave the child parked — its latest status shows the error and the parent may message it again. Pass a parked child's `agentId` to the same subagent tool with a new `message` to continue that session. Omitting `agentId` (or passing an empty string or `null`) always starts a new child, and an `agentId` that matches no known agent falls back to starting a new child rather than failing. Passing a known `agentId` through a different subagent tool fails with `AGENT_MISMATCH`, and messaging a child that is still starting or working on its previous request fails with `AGENT_BUSY` — wait for its result before continuing it.
-On every model call, eve injects a system message containing an `<agents>` block listing the currently parked (resumable) children — each entry carries the `agentId`, name, and latest status. It is a per-call injection, not part of the conversation history: it always reflects the current state, never accumulates stale copies, and children that are starting or running do not appear until they park again.
+Whenever the set of parked (resumable) children changes, eve appends a framework-injected note to the conversation — labeled `[Agents]` and carrying an `<agents>` block — listing each child's `agentId`, name, and latest status. The static system prompt tells the model the note is injected by eve, not written by the user. The note is appended only when the listing changes (an append-only design that preserves the provider prompt cache), the most recent note is authoritative, and children that are starting or running do not appear until they park again.
The parent holds agent handles only for its session lifetime. When the parent session ends, eve terminates its local children. Remote children are not terminated on parent shutdown — that is a known gap: a parked remote child stays alive on its own deployment until that deployment's own lifecycle ends it. For [remote agents](./guides/remote-agents), both deployments must run the same eve version to use agent messaging.
diff --git a/e2e/fixtures/agent-subagents/package.json b/e2e/fixtures/agent-subagents/package.json
index 927e0e7a6..0ee8d2fd7 100644
--- a/e2e/fixtures/agent-subagents/package.json
+++ b/e2e/fixtures/agent-subagents/package.json
@@ -22,5 +22,8 @@
"devDependencies": {
"@types/node": "catalog:",
"typescript": "catalog:"
+ },
+ "e2e": {
+ "modelMatrix": "full"
}
}
diff --git a/packages/eve/src/execution/agent-messaging.scenario.test.ts b/packages/eve/src/execution/agent-messaging.scenario.test.ts
index 4ae1d7f04..0317e9d54 100644
--- a/packages/eve/src/execution/agent-messaging.scenario.test.ts
+++ b/packages/eve/src/execution/agent-messaging.scenario.test.ts
@@ -44,8 +44,8 @@ const model = mockModel((request) => {
}
if (childResults.length === 1) {
- // The agents listing rides the conversation as an assistant announcement
- // (not the system prompt), so scan every message for the latest listing.
+ // The agents listing rides the conversation as a framework-injected
+ // user-role announcement, so scan every message for the latest listing.
const agentsSnippet = request.messages.map((message) => message.text).join("\\n");
const agentId = AGENT_ID_PATTERN.exec(agentsSnippet)?.[1];
if (agentId === undefined) {
diff --git a/packages/eve/src/harness/handles/prompt.test.ts b/packages/eve/src/harness/handles/prompt.test.ts
index 64a450863..906a7dd6d 100644
--- a/packages/eve/src/harness/handles/prompt.test.ts
+++ b/packages/eve/src/harness/handles/prompt.test.ts
@@ -80,12 +80,12 @@ describe("resolveAgentsAnnouncement", () => {
expect(messages).toEqual([{ content: "Earlier response", role: "assistant" }]);
});
- it("does not repeat an unchanged listing", () => {
+ it("does not repeat an unchanged listing already announced as user content", () => {
const content = renderAgentsSnippet({ handles: [parkedRemoteHandle] });
expect(
resolveAgentsAnnouncement({
- messages: [{ content, role: "assistant" }],
+ messages: [{ content, role: "user" }],
store: { handles: [parkedRemoteHandle] },
}),
).toBeUndefined();
@@ -96,7 +96,7 @@ describe("resolveAgentsAnnouncement", () => {
expect(
resolveAgentsAnnouncement({
- messages: [{ content: previous, role: "assistant" }],
+ messages: [{ content: previous, role: "user" }],
store: { handles: [runningHandle] },
}),
).toBe("[Agents]\n<agents>\n</agents>");
@@ -105,4 +105,17 @@ describe("resolveAgentsAnnouncement", () => {
it("skips empty scaffolding when no listing was previously announced", () => {
expect(resolveAgentsAnnouncement({ messages: [], store: undefined })).toBeUndefined();
});
+
+ it("ignores an assistant message that happens to start with the label", () => {
+ const content = renderAgentsSnippet({ handles: [parkedRemoteHandle] });
+
+ // Only framework-injected user-role announcements gate re-announcement;
+ // model output echoing the label must not suppress a fresh listing.
+ expect(
+ resolveAgentsAnnouncement({
+ messages: [{ content, role: "assistant" }],
+ store: { handles: [parkedRemoteHandle] },
+ }),
+ ).toBe(content);
+ });
});
diff --git a/packages/eve/src/harness/handles/prompt.ts b/packages/eve/src/harness/handles/prompt.ts
index c2fe0a6d1..b6399ad55 100644
--- a/packages/eve/src/harness/handles/prompt.ts
+++ b/packages/eve/src/harness/handles/prompt.ts
@@ -2,7 +2,12 @@ import type { ModelMessage } from "ai";
import type { AgentHandle, AgentHandleStore } from "#harness/handles/store.js";
-const AGENTS_SNIPPET_LABEL = "[Agents]";
+/**
+ * Label prefixing every framework-injected agents announcement. Mock model
+ * adapters use it to treat announcements as transparent scaffolding rather
+ * than authored user input.
+ */
+export const AGENTS_SNIPPET_LABEL = "[Agents]";
/** Returns the resumable handles: the only phase the model may continue. */
export function projectParkedAgentHandles(
@@ -25,9 +30,22 @@ export function renderAgentsSnippet(store: AgentHandleStore): string {
}
/**
- * Returns an append-only model announcement when the visible handle listing
- * changed. Keeping volatile handles in conversation history preserves the
- * stable system prompt cache prefix.
+ * Returns an append-only announcement when the visible handle listing
+ * changed since the last one in history, or `undefined` when it is
+ * unchanged.
+ *
+ * The announcement is framework-injected `user`-role conversation content
+ * (the pattern system-reminder notes use in Claude Code and OpenCode), not
+ * an `assistant` or `system` entry:
+ *
+ * - `assistant` breaks providers that reject assistant-final requests
+ * (a settle resume carries no new user input, so the announcement would
+ * end the request) and invites the model to imitate the listing.
+ * - `system` busts the provider prompt cache for the entire conversation
+ * every time a child settles; append-only history preserves the prefix.
+ *
+ * The static agent-messaging prompt block declares the `[Agents]` label as
+ * eve-injected so the model does not attribute it to the user.
*/
export function resolveAgentsAnnouncement(input: {
readonly messages: readonly ModelMessage[];
@@ -35,7 +53,7 @@ export function resolveAgentsAnnouncement(input: {
}): string | undefined {
const latest = input.messages.findLast(
(message) =>
- message.role === "assistant" &&
+ message.role === "user" &&
typeof message.content === "string" &&
message.content.startsWith(AGENTS_SNIPPET_LABEL),
);
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index bbfe76275..d5ab19cef 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -692,7 +692,7 @@ describe("createToolLoopHarness", () => {
expect(agentCall!.tools).not.toHaveProperty("Workflow");
});
- it("announces current agents outside the cacheable system prompt", async () => {
+ it("announces parked agents as user-role content before the user message, outside the system prompt", async () => {
setupMockAgent({
finishReason: "stop",
response: { messages: [{ content: "Hello!", role: "assistant" }] },
@@ -742,18 +742,25 @@ describe("createToolLoopHarness", () => {
generate: ReturnType<typeof vi.fn>;
};
const messages = agent.generate.mock.calls[0]?.[0].messages as ModelMessage[];
+ // The volatile listing stays out of the system prompt (prompt cache) and
+ // rides history as a labeled, framework-injected user message.
expect(instructions).toBe("You are a test assistant.");
expect(messages).toContainEqual({
content: expect.stringContaining(
'<agent id="ag_research:123456789012" name="research">waiting</agent>',
),
- role: "assistant",
+ role: "user",
});
+ // The announcement precedes the turn's actual user message.
expect(messages.at(-1)).toEqual({ content: "Hi", role: "user" });
+ expect(messages.at(-2)).toEqual({
+ content: expect.stringContaining("[Agents]"),
+ role: "user",
+ });
expect(JSON.stringify({ instructions, messages })).not.toContain("private-token");
expect(result.session.history).toContainEqual({
content: expect.stringContaining('<agent id="ag_research:123456789012"'),
- role: "assistant",
+ role: "user",
});
});
@@ -804,6 +811,95 @@ describe("createToolLoopHarness", () => {
expect(JSON.stringify(messages)).not.toContain("<agents>");
});
+ // Regression: a child settling used to append the updated <agents> listing
+ // to history as an assistant message. On a resume with no new user input the
+ // request then ended with `assistant`, which Anthropic rejects ("this model
+ // does not support assistant message prefill"). The announcement is
+ // user-role content, so on a no-input resume it trails the tool results
+ // and the request stays user-final.
+ it("keeps a no-input resume provider-valid when a parked handle is announced", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Done.", role: "assistant" }] },
+ text: "Done.",
+ toolCalls: [],
+ toolResults: [],
+ });
+
+ const runStep = createToolLoopHarness(
+ createTestConfig("conversation", undefined, { persistentSubagentSessions: true }),
+ );
+ const session = createTestSession({
+ history: [
+ { content: "Delegate this.", role: "user" },
+ {
+ content: [
+ {
+ input: { message: "do it" },
+ toolCallId: "call-1",
+ toolName: "research",
+ type: "tool-call",
+ },
+ ],
+ role: "assistant",
+ },
+ {
+ content: [
+ {
+ output: { type: "text", value: "child answered" },
+ toolCallId: "call-1",
+ toolName: "research",
+ type: "tool-result",
+ },
+ ],
+ role: "tool",
+ },
+ ],
+ state: {
+ [AGENT_HANDLES_STATE_KEY]: {
+ handles: [
+ {
+ address: {
+ continuationToken: "private-token",
+ kind: "agent/local",
+ sessionId: "child-session-123456789012",
+ },
+ identity: {
+ id: "ag_research:123456789012",
+ name: "research",
+ nodeId: "subagents/research",
+ },
+ lastStatus: "child answered",
+ phase: "parked",
+ },
+ ],
+ },
+ },
+ });
+
+ const result = await runStep(session);
+
+ const { instructions } = vi.mocked(ToolLoopAgent).mock.calls[0]![0];
+ const agent = vi.mocked(ToolLoopAgent).mock.results[0]?.value as {
+ generate: ReturnType<typeof vi.fn>;
+ };
+ const messages = agent.generate.mock.calls[0]?.[0].messages as ModelMessage[];
+ // The request ends user-final: the announcement trails the tool results.
+ expect(messages.at(-1)).toEqual({
+ content: expect.stringContaining('<agent id="ag_research:123456789012"'),
+ role: "user",
+ });
+ expect(messages.filter((message) => message.role === "assistant")).toHaveLength(1);
+ // The volatile listing never rides the system prompt (prompt cache).
+ expect(JSON.stringify(instructions ?? "")).not.toContain("<agents>");
+ // The announcement persists append-only so the next step's diff gate
+ // sees it and does not re-announce an unchanged listing.
+ expect(result.session.history.at(-2)).toEqual({
+ content: expect.stringContaining("[Agents]"),
+ role: "user",
+ });
+ });
+
it("uses dynamic model selection for the model call", async () => {
setupMockAgent({
finishReason: "stop",
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 110b80b65..fbf2c0350 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -754,13 +754,19 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
}
session = continuation.session;
+ // Announce the parked-agents listing as framework-injected user-role
+ // content, before any new user input so a message present on this step
+ // stays the turn's focus. On a no-input settle resume it trails the tool
+ // results, keeping the request user-final for providers that reject
+ // assistant-final histories. See resolveAgentsAnnouncement for the role
+ // rationale (assistant-final rejection, prompt-cache preservation).
if (config.persistentSubagentSessions === true) {
const announcement = resolveAgentsAnnouncement({
messages,
store: getAgentHandleStore(session.state),
});
if (announcement !== undefined) {
- messages.push({ content: announcement, role: "assistant" });
+ messages.push({ content: announcement, role: "user" });
}
}
diff --git a/packages/eve/src/runtime/agent/bootstrap-model-utils.ts b/packages/eve/src/runtime/agent/bootstrap-model-utils.ts
index 131819117..9f5cac87a 100644
--- a/packages/eve/src/runtime/agent/bootstrap-model-utils.ts
+++ b/packages/eve/src/runtime/agent/bootstrap-model-utils.ts
@@ -1,5 +1,7 @@
import type { MockLanguageModelV3 } from "ai/test";
+import { AGENTS_SNIPPET_LABEL } from "#harness/handles/prompt.js";
+
export type BootstrapGenerateOptions = Parameters<MockLanguageModelV3["doGenerate"]>[0];
export type BootstrapPrompt = BootstrapGenerateOptions["prompt"];
export type BootstrapGenerateResult = Awaited<ReturnType<MockLanguageModelV3["doGenerate"]>>;
@@ -155,6 +157,10 @@ export function getPromptContentText(content: BootstrapPrompt[number]["content"]
/**
* Returns the text from the last user message in the prompt, or `null`.
+ *
+ * Skips framework-injected `[Agents]` announcements: they ride the user
+ * role in conversation history, but they are not authored input and must
+ * not drive mock directive parsing.
*/
export function getLastUserPromptText(prompt: BootstrapPrompt): string | null {
for (const message of [...prompt].reverse()) {
@@ -164,6 +170,10 @@ export function getLastUserPromptText(prompt: BootstrapPrompt): string | null {
const text = getPromptContentText(message.content).trim();
+ if (isAgentsAnnouncementText(text)) {
+ continue;
+ }
+
if (text.length > 0) {
return text;
}
@@ -172,6 +182,16 @@ export function getLastUserPromptText(prompt: BootstrapPrompt): string | null {
return null;
}
+/**
+ * True when the text is a framework-injected `[Agents]` announcement.
+ * Announcements are user-role scaffolding, not authored input: mock model
+ * heuristics must scan past them instead of treating them as the turn's
+ * message or as a turn boundary.
+ */
+export function isAgentsAnnouncementText(text: string): boolean {
+ return text.startsWith(AGENTS_SNIPPET_LABEL);
+}
+
/**
* Joins all message content in the prompt into a single string.
*/
diff --git a/packages/eve/src/runtime/agent/mock-model-adapter.test.ts b/packages/eve/src/runtime/agent/mock-model-adapter.test.ts
index 3e5127761..d30c0a182 100644
--- a/packages/eve/src/runtime/agent/mock-model-adapter.test.ts
+++ b/packages/eve/src/runtime/agent/mock-model-adapter.test.ts
@@ -699,6 +699,68 @@ describe("createMockAuthoredRuntimeModel", () => {
]);
});
+ // Regression: the [Agents] announcement is user-role scaffolding injected
+ // after a subagent settles. Treating it as a turn boundary masked the tool
+ // result, and the adapter re-issued the same deterministic tool call — a
+ // duplicate start operation that fatally failed the parent session in the
+ // mock world suites.
+ it("replies to a tool result behind a framework [Agents] announcement instead of re-calling", async () => {
+ const result = await generateWithPrompt(
+ [
+ {
+ content: "Call conditional-marker exactly once.",
+ role: "user",
+ },
+ {
+ content: [
+ {
+ input: JSON.stringify({ message: "run" }),
+ toolCallId: "call_conditional_marker",
+ toolName: "conditional-marker",
+ type: "tool-call",
+ },
+ ],
+ role: "assistant",
+ },
+ {
+ content: [
+ {
+ output: { type: "json", value: "DYNAMIC_SUBAGENT_ENABLED" },
+ toolCallId: "call_conditional_marker",
+ toolName: "conditional-marker",
+ type: "tool-result",
+ },
+ ],
+ role: "tool",
+ },
+ {
+ content:
+ '[Agents]\n<agents>\n<agent id="ag_conditional-marker:5ae9bfd35776" name="conditional-marker">DYNAMIC_SUBAGENT_ENABLED</agent>\n</agents>',
+ role: "user",
+ },
+ ],
+ [
+ {
+ inputSchema: {
+ properties: { message: { type: "string" } },
+ required: ["message"],
+ type: "object",
+ },
+ name: "conditional-marker",
+ type: "function",
+ },
+ ],
+ );
+
+ expect(result.finishReason).toEqual({ raw: undefined, unified: "stop" });
+ expect(result.content).toEqual([
+ {
+ text: 'Used conditional-marker for "Call conditional-marker exactly once.": DYNAMIC_SUBAGENT_ENABLED',
+ type: "text",
+ },
+ ]);
+ });
+
it("does not reuse a prior turn's tool result after a later user message", async () => {
const result = await generateWithPrompt([
{
diff --git a/packages/eve/src/runtime/agent/mock-model-adapter.ts b/packages/eve/src/runtime/agent/mock-model-adapter.ts
index 58d1a8066..fc3c2bcd0 100644
--- a/packages/eve/src/runtime/agent/mock-model-adapter.ts
+++ b/packages/eve/src/runtime/agent/mock-model-adapter.ts
@@ -23,6 +23,7 @@ import {
getLastUserPromptText,
getPromptContentText,
getPromptText,
+ isAgentsAnnouncementText,
} from "#runtime/agent/bootstrap-model-utils.js";
import {
findRelevantSkill,
@@ -484,6 +485,14 @@ function getAvailableTools(options: BootstrapGenerateOptions): AvailableBootstra
function getLastAuthoredToolResult(prompt: BootstrapPrompt): BootstrapToolResult | null {
for (const message of [...prompt].reverse()) {
if (message.role === "user") {
+ // A framework-injected [Agents] announcement is scaffolding, not a
+ // turn boundary. Treating it as one masks the tool result behind it,
+ // and the adapter then re-issues the same deterministic tool call —
+ // for subagent starts that collides on the derived operation id and
+ // fatally fails the parent session.
+ if (isAgentsAnnouncementText(getPromptContentText(message.content).trim())) {
+ continue;
+ }
return null;
}
diff --git a/packages/eve/src/runtime/agent/mock-model-fixtures.ts b/packages/eve/src/runtime/agent/mock-model-fixtures.ts
index 13f4829e2..ec8378abd 100644
--- a/packages/eve/src/runtime/agent/mock-model-fixtures.ts
+++ b/packages/eve/src/runtime/agent/mock-model-fixtures.ts
@@ -1,5 +1,8 @@
import type { BootstrapPrompt } from "#runtime/agent/bootstrap-model-utils.js";
-import { getPromptContentText } from "#runtime/agent/bootstrap-model-utils.js";
+import {
+ getPromptContentText,
+ isAgentsAnnouncementText,
+} from "#runtime/agent/bootstrap-model-utils.js";
import { createJsonSchemaSample } from "#runtime/agent/mock-structured-output.js";
import { LOAD_SKILL_TOOL_NAME } from "#runtime/skills/fragment-context.js";
@@ -138,7 +141,11 @@ function getTrailingUserText(prompt: BootstrapPrompt): string {
for (const message of [...prompt].reverse()) {
if (message.role === "system") continue;
if (message.role !== "user") break;
- texts.unshift(getPromptContentText(message.content));
+ const text = getPromptContentText(message.content);
+ // Framework-injected [Agents] announcements are scaffolding, not part
+ // of the turn's authored ask.
+ if (isAgentsAnnouncementText(text.trim())) continue;
+ texts.unshift(text);
}
return texts.join("\n");
diff --git a/packages/eve/src/runtime/prompt/compose.ts b/packages/eve/src/runtime/prompt/compose.ts
index b9233018c..2b2327b53 100644
--- a/packages/eve/src/runtime/prompt/compose.ts
+++ b/packages/eve/src/runtime/prompt/compose.ts
@@ -12,7 +12,7 @@ const PARALLEL_ACTION_INSTRUCTION =
"Tool execution\nA single tool or subagent call runs as one serial action. If you call multiple independent tools or subagents in one response, eve treats that batch as parallel work. Only batch work that is independent and does not rely on another call in the same response.";
const AGENT_MESSAGING_INSTRUCTION =
- "Agent messaging\nAgents you have already delegated to stay available after they answer. The system-message `<agents>` list is only a record of those existing agents — their `agentId`, name, and latest status. It does not limit which subagent tools you can call: your tool list is the source of truth, and any subagent tool can always be called without `agentId` to start a new agent, including when the `<agents>` list is empty or absent. Pass `agentId` to the same subagent tool only to continue one of those existing agents' sessions.";
+ "Agent messaging\nAgents you have already delegated to stay available after they answer. eve injects the current `<agents>` list into the conversation as a note labeled `[Agents]`; it is added automatically by the framework, not written by the user, and never requires a reply. The list is only a record of those existing agents — their `agentId`, name, and latest status. It does not limit which subagent tools you can call: your tool list is the source of truth, and any subagent tool can always be called without `agentId` to start a new agent, including when the `<agents>` list is empty or absent. Pass `agentId` to the same subagent tool only to continue one of those existing agents' sessions.";
/**
* Input for composing the base authored instructions prompt for one