Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): batch queued sibling completions and measure wake cost (#3144)

Rui22046b243f47
diff --git a/.changeset/task-completion-batching.md b/.changeset/task-completion-batching.md
new file mode 100644
index 000000000..03d1c1959
--- /dev/null
+++ b/.changeset/task-completion-batching.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Combine adjacent queued successful sibling completions into one parent turn, reducing redundant model calls while retaining every result. Batching happens automatically without waiting for unfinished tasks.
diff --git a/docs/subagents/index.mdx b/docs/subagents/index.mdx
index 0bc5bda37..e9c4591ee 100644
--- a/docs/subagents/index.mdx
+++ b/docs/subagents/index.mdx
@@ -5,6 +5,16 @@ description: "Delegate work to root-agent copies or declared specialists with th
eve supports two ways to delegate work: the root-only built-in `agent` tool, which starts or continues a copy of the root agent, and declared subagents, which are specialists with their own directories. Use a subagent to run independent work in parallel, narrow the available tools, or give a task to a specialist.
+## Completion batching
+
+eve automatically combines adjacent successful completions already queued from
+tasks launched in the same parent turn. Every result is retained, and the parent
+responds to the batch in one turn. No configuration is required.
+
+There is no debounce timer or waiting for unfinished tasks. Failures, input
+requests, explicit updates, user messages, and different task cohorts remain
+separate delivery boundaries.
+
## The built-in `agent` tool
The root session receives `agent` by default. The model calls it to delegate a task to a new copy of the root agent or continue an existing copy:
diff --git a/e2e/fixtures/agent-task-reporting/agent/agent.ts b/e2e/fixtures/agent-task-reporting/agent/agent.ts
index fb7a0c6d4..7d574b65f 100644
--- a/e2e/fixtures/agent-task-reporting/agent/agent.ts
+++ b/e2e/fixtures/agent-task-reporting/agent/agent.ts
@@ -1,6 +1,18 @@
import { e2eAgentConfig } from "@eve-e2e/config";
+import { gateway, wrapLanguageModel } from "ai";
import { defineAgent } from "eve";
+import { reportingMiddleware } from "./lib/reporting-model.js";
+
const base = e2eAgentConfig();
-export default defineAgent({ ...base });
+export default defineAgent({
+ ...base,
+ // Wrapped Gateway handles do not resolve through eve's catalog lookup.
+ // Both comparison arms use this fixture budget, well above the short cases.
+ modelContextWindowTokens: 128_000,
+ model: wrapLanguageModel({
+ model: typeof base.model === "string" ? gateway(base.model) : base.model,
+ middleware: reportingMiddleware,
+ }),
+});
diff --git a/e2e/fixtures/agent-task-reporting/agent/lib/reporting-model.ts b/e2e/fixtures/agent-task-reporting/agent/lib/reporting-model.ts
new file mode 100644
index 000000000..830730661
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/agent/lib/reporting-model.ts
@@ -0,0 +1,48 @@
+import type { LanguageModelMiddleware } from "ai";
+
+export type PendingInstruction = "on" | "off";
+
+export function reportingControl(instruction: PendingInstruction): string {
+ return `<reporting-eval pending-instruction="${instruction}"/>\n`;
+}
+
+const PENDING_INSTRUCTION = "Background task control: incomplete cohort\n";
+
+// Both arms remove their control marker before inference. Only the off arm
+// removes the pending instruction; task state, results and other guidance stay.
+export const reportingMiddleware: LanguageModelMiddleware = {
+ transformParams: async ({ params }) => {
+ let instruction: PendingInstruction | undefined;
+ const prompt = params.prompt.map((message) => {
+ if (message.role !== "user") return message;
+ return {
+ ...message,
+ content: message.content.map((part) => {
+ if (part.type !== "text") return part;
+ for (const variant of ["on", "off"] as const) {
+ const control = reportingControl(variant);
+ if (!part.text.startsWith(control)) continue;
+ instruction = variant;
+ return { ...part, text: part.text.slice(control.length) };
+ }
+ return part;
+ }),
+ };
+ });
+
+ if (instruction !== "off") return { ...params, prompt };
+
+ return {
+ ...params,
+ prompt: prompt.filter(
+ (message) =>
+ !(
+ message.role === "user" &&
+ message.content.length === 1 &&
+ message.content[0]?.type === "text" &&
+ message.content[0].text.startsWith(PENDING_INSTRUCTION)
+ ),
+ ),
+ };
+ },
+};
diff --git a/e2e/fixtures/agent-task-reporting/evals/README.md b/e2e/fixtures/agent-task-reporting/evals/README.md
new file mode 100644
index 000000000..0a79bca28
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/evals/README.md
@@ -0,0 +1,42 @@
+# Background task reporting
+
+This fixture measures whether pending-cohort guidance suppresses a required user
+response after an intermediate task wake.
+
+`consolidated-report.eval.ts` runs eight reporting/compaction trials.
+`pending-response.eval.ts` runs 20 trials with the pending instruction and 20
+without it, interleaved. Each comparison trial
+starts the same three warehouse lookups, observes an intermediate completion,
+asks an unrelated arithmetic question, and waits for the combined inventory
+report. The comparison trials do not request compaction.
+
+The fixture model strips the trial marker from both variants before inference.
+The off variant also removes the current pending-cohort instruction. Task state,
+task results, launch guidance, settled guidance, model settings, and the runtime
+delivery policy are preserved. Both arms use the same 128,000-token fixture
+context budget and assert that no compaction occurred. Unit tests compare the requests and check that
+the original history is unchanged. This is a prompt ablation, not a simulation
+of cohort settlement or wake coalescing.
+
+Assertions record three outcomes separately:
+
+- Whether intermediate wakes produce user-facing text. This is a gate for the
+ on variant and a recorded score with threshold zero for the off control.
+- Whether the user receives the arithmetic answer, without tools, before the
+ last child turn completes. Server event timestamps establish ordering; seeing
+ a reply before the final parent notification alone is insufficient.
+- Whether the final parent report includes all inventory results.
+
+A separate timing assertion requires the question to reach its parent turn before the
+last child completes. A trial that misses that window cannot establish a prompt
+effect. Provider errors, failed delegation, and missing intermediate wakes are
+also setup/runtime failures rather than evidence of unwanted silence.
+
+The variants share the same scenario and configured probe delays; stochastic
+model decisions and observed completion times can differ. Inspect per-trial
+outcomes and timing logs before attributing a difference to the instruction.
+Passing this small sample does not establish absence of interference in other
+conversations or models.
+
+Run the fixture's `test:unit` script for the request-transformation checks. The
+real-model comparison runs in the `agent-task-reporting` model-suite CI jobs.
diff --git a/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts b/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
index 5d7585f28..2a8fd6ebb 100644
--- a/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
+++ b/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
@@ -1,10 +1,15 @@
-import { defineEval, type EveEvalSession, type EveEvalTurn } from "eve/evals";
+import { defineEval } from "eve/evals";
import { satisfies } from "eve/evals/expect";
-const TASK_COUNT = 3;
-const MIN_BACKGROUND_TASKS = 2;
-const RESULTS = [/\boranges\b/iu, /\bpears\b/iu, /\bapples\b/iu];
-const COMPLETION = /Background task (task_[a-z0-9]+) \([^)]+\) is completed\./giu;
+import {
+ completeReport,
+ intermediateWakes,
+ requireStreamIndex,
+ silentWake,
+ startWarehouseLookups,
+ waitForPartialCompletion,
+ waitForReport,
+} from "./reporting.js";
function reportingEval() {
return defineEval({
@@ -12,184 +17,42 @@ function reportingEval() {
"A stock eve agent acknowledges accepted background work, keeps partial wakes silent, and reports all results after settlement.",
tags: ["real-model"],
async test(t) {
- const started =
- await t.send(`Please find the inventory item at each of our three sample warehouses using the built-in agent tool. Start all three lookups in the background without waiting for their results. Delegate the lookups instead of calling probe yourself.
-
-1. "Call probe with check=first and report its result value."
-2. "Call probe with check=second and report its result value."
-3. "Call probe with check=third and report its result value."`);
-
- started.expectOk();
- started.calledSubagent("agent", { count: TASK_COUNT }).soft().label("no repeated delegation");
- await t.require(
- started,
- satisfies(
- (turn: EveEvalTurn) => hasPostReceiptAcknowledgement(turn),
- "an acknowledgement follows all background task receipts",
- ),
+ const run = await startWarehouseLookups(t);
+ await waitForPartialCompletion(t, run);
+
+ const compaction = t.target.watchTurn(run.sessionId, {
+ startIndex: requireStreamIndex(run.session),
+ });
+ const response = await t.target.fetch(
+ `/eve/v1/session/${encodeURIComponent(run.sessionId)}/compact`,
+ {
+ body: "{}",
+ headers: { "content-type": "application/json" },
+ method: "POST",
+ },
);
await t.require(
- started.message,
- satisfies(
- (message: unknown) =>
- typeof message === "string" &&
- message.trim().length > 0 &&
- RESULTS.every((result) => !result.test(message)),
- "the initiating turn acknowledges work without claiming results",
- ),
+ response.status,
+ satisfies((status: number) => status === 202, "parent session accepts compaction"),
);
- const taskIds = backgroundTaskIds(started);
- await t.require(
- taskIds,
- satisfies(
- (ids: readonly string[]) => ids.length >= MIN_BACKGROUND_TASKS,
- "multiple independent background tasks exercise partial wakes",
- ),
- );
-
- let session: EveEvalSession | typeof t = t;
- const observed = new Set<string>();
- let finalReport: string | undefined;
- let compactionAttempted = false;
- for (let attempt = 0; attempt < 8 && observed.size < taskIds.length; attempt += 1) {
- const live = t.target.watchTurn(started.sessionId, {
- startIndex: requireStreamIndex(session),
- });
- const turn = await live.result();
- const completed = completedTaskIds(turn).filter((taskId) => taskIds.includes(taskId));
- for (const taskId of completed) observed.add(taskId);
- t.log(
- `wake ${String(attempt + 1)}: completed=${String(observed.size)}/${String(taskIds.length)} message=${JSON.stringify(turn.message)}`,
- );
- turn.expectOk();
-
- if (observed.size < taskIds.length) {
- await t.require(
- turn.message,
- satisfies((message) => message === undefined, "intermediate task wake is silent"),
- );
- } else {
- finalReport = turn.message;
- }
- turn.noFailedActions();
- session = live.session;
-
- if (!compactionAttempted && observed.size > 0 && observed.size < taskIds.length) {
- const compaction = t.target.watchTurn(started.sessionId, {
- startIndex: requireStreamIndex(session),
- });
- const response = await t.target.fetch(
- `/eve/v1/session/${encodeURIComponent(started.sessionId)}/compact`,
- {
- body: "{}",
- headers: { "content-type": "application/json" },
- method: "POST",
- },
- );
- await t.require(
- response.status,
- satisfies((status: number) => status === 202, "parent session accepts compaction"),
- );
- const compactedTurn = await compaction.result();
- compactedTurn.event("compaction.requested", { count: 1 });
- // A declined summary preserves history; the caller still needs the complete report.
- compactedTurn
- .event("compaction.completed", { count: 1 })
- .soft()
- .label("successful checkpoint");
- compactedTurn.noFailedActions();
- session = compaction.session;
- compactionAttempted = true;
- }
+ const compactedTurn = await compaction.result();
+ compactedTurn.event("compaction.requested", { count: 1 });
+ // A declined summary preserves history; the caller still needs the complete report.
+ compactedTurn
+ .event("compaction.completed", { count: 1 })
+ .soft()
+ .label("successful checkpoint");
+ compactedTurn.noFailedActions();
+ run.session = compaction.session;
+
+ const report = await waitForReport(t, run);
+ for (const wake of intermediateWakes(run)) {
+ await t.require(wake.message, silentWake());
}
-
- await t.require(
- [...observed],
- satisfies(
- (ids: readonly string[]) => ids.length === taskIds.length,
- "all task wakes observed",
- ),
- );
- await t.require(
- finalReport,
- satisfies(
- (message: unknown) =>
- typeof message === "string" && RESULTS.every((result) => result.test(message)),
- "settled tasks produce a complete user-facing report",
- ),
- );
- await t.require(
- compactionAttempted,
- satisfies((value: boolean) => value, "parent session handled compaction between wakes"),
- );
+ await t.require(report, completeReport());
t.noFailedActions();
},
});
}
export default Array.from({ length: 8 }, reportingEval);
-
-function backgroundTaskIds(turn: EveEvalTurn): readonly string[] {
- return [
- ...new Set(
- turn.events.flatMap((event) =>
- event.type === "subagent.completed" &&
- event.data.subagentName === "agent" &&
- event.data.backgroundTask !== undefined
- ? [event.data.backgroundTask.taskId]
- : [],
- ),
- ),
- ];
-}
-
-function hasPostReceiptAcknowledgement(turn: EveEvalTurn): boolean {
- const receiptIndexes = turn.events.flatMap((event, index) =>
- event.type === "subagent.completed" &&
- event.data.subagentName === "agent" &&
- event.data.backgroundTask !== undefined
- ? [index]
- : [],
- );
- if (receiptIndexes.length < MIN_BACKGROUND_TASKS) return false;
- const lastReceiptIndex = Math.max(...receiptIndexes);
- return turn.events.some(
- (event, index) =>
- index > lastReceiptIndex &&
- event.type === "message.completed" &&
- event.data.finishReason !== "tool-calls" &&
- event.data.message !== null &&
- event.data.message.trim().length > 0,
- );
-}
-
-function completedTaskIds(turn: EveEvalTurn): readonly string[] {
- return turn.events.flatMap((event) => {
- if (event.type !== "message.received") return [];
- return [...messageText(event.data.message).matchAll(COMPLETION)].map(
- (match) => match[1] as string,
- );
- });
-}
-
-function requireStreamIndex(
- session: EveEvalSession | { readonly state?: { streamIndex: number } },
-) {
- if (session.state === undefined) throw new Error("Task reporting session has no stream index.");
- return session.state.streamIndex;
-}
-
-function messageText(message: unknown): string {
- if (typeof message === "string") return message;
- if (!Array.isArray(message)) return "";
- return message
- .flatMap((part) =>
- part !== null &&
- typeof part === "object" &&
- Reflect.get(part, "type") === "text" &&
- typeof Reflect.get(part, "text") === "string"
- ? [Reflect.get(part, "text") as string]
- : [],
- )
- .join("\n");
-}
diff --git a/e2e/fixtures/agent-task-reporting/evals/pending-response.eval.ts b/e2e/fixtures/agent-task-reporting/evals/pending-response.eval.ts
new file mode 100644
index 000000000..a8d17c282
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/evals/pending-response.eval.ts
@@ -0,0 +1,87 @@
+import { defineEval, type Assertion, type EveEvalTurn } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+import { reportingControl, type PendingInstruction } from "../agent/lib/reporting-model.js";
+import {
+ completeReport,
+ intermediateWakes,
+ QUESTION,
+ sendQuestion,
+ silentWake,
+ startWarehouseLookups,
+ TASK_COUNT,
+ waitForPartialCompletion,
+ waitForReport,
+} from "./reporting.js";
+
+function pendingResponseEval(pendingInstruction: PendingInstruction, silence: Assertion) {
+ return defineEval({
+ description: `After an intermediate task wake, the parent answers a user before settlement, then reports all results (pending instruction ${pendingInstruction}).`,
+ tags: ["real-model", "pending-response"],
+ metadata: { pendingInstruction },
+ async test(t) {
+ const run = await startWarehouseLookups(t, reportingControl(pendingInstruction));
+ await waitForPartialCompletion(t, run);
+
+ const question = await sendQuestion(t, run);
+ question.messageIncludes(/\b56\b/u);
+ question.usedNoTools();
+ t.log(
+ `pending instruction ${pendingInstruction}: user reply=${JSON.stringify(question.message)}`,
+ );
+
+ const report = await waitForReport(t, run);
+ for (const wake of intermediateWakes(run)) {
+ t.check(wake.message, silence);
+ }
+ t.check(report, completeReport());
+ t.notEvent("compaction.requested");
+
+ await t.require(
+ run.childSessionIds.size,
+ satisfies(
+ (count) => count === TASK_COUNT,
+ "all child sessions are available for timing checks",
+ ),
+ );
+ const children = await Promise.all(
+ [...run.childSessionIds].map((sessionId) => t.target.watchTurn(sessionId).result()),
+ );
+ const settledAt = Math.max(...children.map(completedAt));
+ const received = question.events.find(
+ (event) => event.type === "message.received" && event.data.message.includes(QUESTION),
+ );
+ const answered = question.events.find(
+ (event) =>
+ event.type === "message.completed" &&
+ event.data.finishReason !== "tool-calls" &&
+ /\b56\b/u.test(event.data.message ?? ""),
+ );
+ const askedAt = Date.parse(received?.meta.at ?? "");
+ const answeredAt = Date.parse(answered?.meta.at ?? "");
+ t.check(
+ askedAt < settledAt,
+ satisfies(Boolean, "the user question reached the parent before cohort settlement"),
+ );
+ t.check(
+ answeredAt < settledAt,
+ satisfies(Boolean, "the user received an answer before cohort settlement"),
+ );
+ t.log(
+ `pending instruction ${pendingInstruction}: asked=${askedAt} answered=${answeredAt} settled=${settledAt}`,
+ );
+ t.noFailedActions();
+ },
+ });
+}
+
+export default Array.from({ length: 20 }, () => [
+ pendingResponseEval("on", silentWake()),
+ pendingResponseEval("off", silentWake().soft(0)),
+]).flat();
+
+function completedAt(turn: EveEvalTurn): number {
+ const event = turn.events.find((entry) => entry.type === "turn.completed");
+ if (event === undefined) throw new Error("Missing child completion event for timing check.");
+ return Date.parse(event.meta.at);
+}
diff --git a/e2e/fixtures/agent-task-reporting/evals/reporting.ts b/e2e/fixtures/agent-task-reporting/evals/reporting.ts
new file mode 100644
index 000000000..bd04c772b
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/evals/reporting.ts
@@ -0,0 +1,207 @@
+import type { EveEvalContext, EveEvalLiveTurn, EveEvalSession, EveEvalTurn } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+export const TASK_COUNT = 3;
+export const QUESTION =
+ "Alice is packing seven boxes with eight jars in each. How many jars is that? Reply with just the number.";
+
+const MIN_BACKGROUND_TASKS = 2;
+const RESULTS = [/\boranges\b/iu, /\bpears\b/iu, /\bapples\b/iu];
+const COMPLETION = /Background task (task_[a-z0-9]+) \([^)]+\) is completed\./giu;
+
+interface ReportingRun {
+ readonly sessionId: string;
+ readonly taskIds: readonly string[];
+ readonly observed: Set<string>;
+ readonly childSessionIds: Set<string>;
+ readonly wakes: { turn: EveEvalTurn; completed: number; settled: boolean }[];
+ session: EveEvalSession | EveEvalContext;
+}
+
+export async function startWarehouseLookups(
+ t: EveEvalContext,
+ control = "",
+): Promise<ReportingRun> {
+ const started =
+ await t.send(`${control}Please find the inventory item at each of our three sample warehouses using the built-in agent tool. Start all three lookups in the background without waiting for their results. Delegate the lookups instead of calling probe yourself.
+
+1. "Call probe with check=first and report its result value."
+2. "Call probe with check=second and report its result value."
+3. "Call probe with check=third and report its result value."`);
+ started.expectOk();
+ started.calledSubagent("agent", { count: TASK_COUNT }).soft().label("no repeated delegation");
+ await t.require(
+ started,
+ satisfies(
+ hasPostReceiptAcknowledgement,
+ "an acknowledgement follows all background task receipts",
+ ),
+ );
+ await t.require(
+ started.message,
+ satisfies(
+ (message: unknown) =>
+ typeof message === "string" &&
+ message.trim().length > 0 &&
+ RESULTS.every((result) => !result.test(message)),
+ "the initiating turn acknowledges work without claiming results",
+ ),
+ );
+ const taskIds = [
+ ...new Set(
+ started.events.flatMap((event) =>
+ event.type === "subagent.completed" &&
+ event.data.subagentName === "agent" &&
+ event.data.backgroundTask !== undefined
+ ? [event.data.backgroundTask.taskId]
+ : [],
+ ),
+ ),
+ ];
+ await t.require(
+ taskIds,
+ satisfies(
+ (ids: readonly string[]) => ids.length >= MIN_BACKGROUND_TASKS,
+ "multiple independent background tasks exercise partial wakes",
+ ),
+ );
+ return {
+ session: t,
+ sessionId: started.sessionId,
+ taskIds,
+ observed: new Set(),
+ childSessionIds: new Set(childSessions(started)),
+ wakes: [],
+ };
+}
+
+export async function waitForPartialCompletion(
+ t: EveEvalContext,
+ run: ReportingRun,
+): Promise<void> {
+ for (let attempt = 0; attempt < 8 && run.observed.size === 0; attempt += 1) {
+ await readTurn(t, run, nextTurn(t, run));
+ }
+ await t.require(
+ run.observed.size,
+ satisfies(
+ (count: number) => count > 0 && count < run.taskIds.length,
+ "an intermediate completion leaves sibling tasks pending",
+ ),
+ );
+}
+
+export async function sendQuestion(t: EveEvalContext, run: ReportingRun): Promise<EveEvalTurn> {
+ let live = await run.session.start(QUESTION);
+ for (let attempt = 0; attempt < 8; attempt += 1) {
+ const turn = await readTurn(t, run, live);
+ if (receivedQuestion(turn)) return turn;
+ live = nextTurn(t, run);
+ }
+ throw new Error("No user turn followed the intermediate wake.");
+}
+
+export async function waitForReport(
+ t: EveEvalContext,
+ run: ReportingRun,
+): Promise<string | undefined> {
+ for (let attempt = 0; attempt < 8 && run.observed.size < run.taskIds.length; attempt += 1) {
+ await readTurn(t, run, nextTurn(t, run));
+ }
+ await t.require(
+ run.observed.size,
+ satisfies((count: number) => count === run.taskIds.length, "all task wakes observed"),
+ );
+ return run.wakes
+ .filter((wake) => wake.completed > 0 && wake.settled && !receivedQuestion(wake.turn))
+ .at(-1)?.turn.message;
+}
+
+export function intermediateWakes(run: ReportingRun): readonly EveEvalTurn[] {
+ return run.wakes
+ .filter((wake) => wake.completed > 0 && !wake.settled && !receivedQuestion(wake.turn))
+ .map((wake) => wake.turn);
+}
+
+export function silentWake() {
+ return satisfies((message) => message === undefined, "intermediate task wake is silent");
+}
+
+export function completeReport() {
+ return satisfies(
+ (message: unknown) =>
+ typeof message === "string" && RESULTS.every((result) => result.test(message)),
+ "settled tasks produce a complete user-facing report",
+ );
+}
+
+export function requireStreamIndex(session: EveEvalSession | EveEvalContext): number {
+ if (session.state === undefined) throw new Error("Task reporting session has no stream index.");
+ return session.state.streamIndex;
+}
+
+function nextTurn(t: EveEvalContext, run: ReportingRun): EveEvalLiveTurn {
+ return t.target.watchTurn(run.sessionId, { startIndex: requireStreamIndex(run.session) });
+}
+
+async function readTurn(
+ t: EveEvalContext,
+ run: ReportingRun,
+ live: EveEvalLiveTurn,
+): Promise<EveEvalTurn> {
+ const turn = await live.result();
+ turn.expectOk();
+ turn.noFailedActions();
+ const completed = turn.events
+ .flatMap((event) => {
+ if (event.type !== "message.received") return [];
+ return [...event.data.message.matchAll(COMPLETION)].map((match) => match[1] as string);
+ })
+ .filter((taskId) => run.taskIds.includes(taskId));
+ for (const taskId of completed) run.observed.add(taskId);
+ for (const sessionId of childSessions(turn)) run.childSessionIds.add(sessionId);
+ run.session = live.session;
+ run.wakes.push({
+ turn,
+ completed: completed.length,
+ settled: run.observed.size === run.taskIds.length,
+ });
+ t.log(
+ `wake ${run.wakes.length}: completed=${run.observed.size}/${run.taskIds.length} message=${JSON.stringify(turn.message)}`,
+ );
+ return turn;
+}
+
+function childSessions(turn: EveEvalTurn): string[] {
+ return turn.events.flatMap((event) =>
+ event.type === "subagent.called" ? [event.data.childSessionId] : [],
+ );
+}
+
+function receivedQuestion(turn: EveEvalTurn): boolean {
+ return turn.events.some(
+ (event) => event.type === "message.received" && event.data.message.includes(QUESTION),
+ );
+}
+
+function hasPostReceiptAcknowledgement(turn: EveEvalTurn): boolean {
+ const receiptIndexes = turn.events.flatMap((event, index) =>
+ event.type === "subagent.completed" &&
+ event.data.subagentName === "agent" &&
+ event.data.backgroundTask !== undefined
+ ? [index]
+ : [],
+ );
+ const lastReceiptIndex = Math.max(...receiptIndexes);
+ return (
+ receiptIndexes.length >= MIN_BACKGROUND_TASKS &&
+ turn.events.some(
+ (event, index) =>
+ index > lastReceiptIndex &&
+ event.type === "message.completed" &&
+ event.data.finishReason !== "tool-calls" &&
+ event.data.message !== null &&
+ event.data.message.trim().length > 0,
+ )
+ );
+}
diff --git a/e2e/fixtures/agent-task-reporting/package.json b/e2e/fixtures/agent-task-reporting/package.json
index b42d86d14..d7ce359bf 100644
--- a/e2e/fixtures/agent-task-reporting/package.json
+++ b/e2e/fixtures/agent-task-reporting/package.json
@@ -8,11 +8,13 @@
"dev": "eve dev",
"start": "eve start",
"typecheck": "eve build && tsc",
- "test:e2e": "eve eval --strict"
+ "test:e2e": "eve eval --strict",
+ "test:unit": "node --test test/*.test.mjs"
},
"dependencies": {
"@eve-e2e/config": "workspace:*",
"@workflow/world-postgres": "catalog:",
+ "ai": "catalog:",
"eve": "workspace:*",
"just-bash": "3.1.0",
"zod": "catalog:"
diff --git a/e2e/fixtures/agent-task-reporting/test/reporting-model.test.mjs b/e2e/fixtures/agent-task-reporting/test/reporting-model.test.mjs
new file mode 100644
index 000000000..9e75cca74
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/test/reporting-model.test.mjs
@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+import { reportingControl, reportingMiddleware } from "../agent/lib/reporting-model.ts";
+
+const source = readFileSync(
+ new URL("../../../../packages/eve/src/tasks/delivery-context.ts", import.meta.url),
+ "utf8",
+);
+const pending = source.match(/TASK_DELIVERY_PENDING_INSTRUCTION = `([\s\S]*?)`;/)[1];
+const user = (text) => ({ role: "user", content: [{ type: "text", text }] });
+
+async function transform(variant) {
+ const prompt = [
+ { role: "system", content: "You are a helpful assistant." },
+ user(`${reportingControl(variant)}Start the lookups.`),
+ user('[Task state]\n{"tasks":[{"status":"pending"}]}'),
+ user(pending),
+ user("Background task task_1 is completed.\nResult: oranges"),
+ { role: "assistant", content: [{ type: "text", text: "<eve-empty-delivery/>" }] },
+ user("How many jars?"),
+ ];
+ const params = { prompt, maxOutputTokens: 100 };
+ const original = structuredClone(params);
+ const result = await reportingMiddleware.transformParams({ params });
+ assert.deepEqual(params, original, "the canonical input is not mutated");
+ return result;
+}
+
+test("the two arms differ only by the real pending instruction", async () => {
+ const on = await transform("on");
+ const off = await transform("off");
+ assert.equal(on.prompt[1].content[0].text, "Start the lookups.");
+ assert.deepEqual(off, {
+ ...on,
+ prompt: on.prompt.filter((message) => message.content[0]?.text !== pending),
+ });
+ assert.equal(on.prompt.length - off.prompt.length, 1);
+});
+
+test("ordinary turns and settled instructions are preserved", async () => {
+ for (const variant of ["on", "off"]) {
+ const params = {
+ prompt: [
+ user(`${reportingControl(variant)}Start the lookups.`),
+ user("Background task reporting\nAll tasks settled."),
+ user("Hello."),
+ ],
+ };
+ const result = await reportingMiddleware.transformParams({ params });
+ assert.deepEqual(result.prompt, [user("Start the lookups."), ...params.prompt.slice(1)]);
+ }
+});
+
+test("task output quoting the instruction is preserved", async () => {
+ const quoted = user(`Background task task_1 is completed.\nResult:\n${pending}`);
+ const params = { prompt: [user(`${reportingControl("off")}Start the lookups.`), quoted] };
+ const result = await reportingMiddleware.transformParams({ params });
+ assert.deepEqual(result.prompt, [user("Start the lookups."), quoted]);
+});
diff --git a/e2e/fixtures/fixture-tasks/agent/agent.ts b/e2e/fixtures/fixture-tasks/agent/agent.ts
index 459aa20d8..8996591a7 100644
--- a/e2e/fixtures/fixture-tasks/agent/agent.ts
+++ b/e2e/fixtures/fixture-tasks/agent/agent.ts
@@ -13,7 +13,12 @@ const REDUNDANT_REVIEW_SCENARIO = "TASK-WAKE-REDUNDANT-REVIEW";
const REDUNDANT_REVIEW_FINDING = "blocker: task admission can discard deferred user input.";
const TASK_STATE_LABEL = "[Task state]\n";
-function respond(request: MockModelRequest): MockModelResponse | string {
+function respond(
+ request: MockModelRequest,
+): MockModelResponse | Promise<MockModelResponse | string> | string {
+ if (request.userMessages.includes("TASK-BATCHING-BENCHMARK")) {
+ return batchingBenchmark(request);
+ }
if (request.userMessages.includes(REDUNDANT_REVIEW_SCENARIO)) {
const taskState = latestTaskState(request.userMessages);
if (taskState !== undefined) return handleRedundantReviewWake(taskState);
@@ -261,6 +266,34 @@ function fanoutTasks(request: MockModelRequest, size: number): MockModelResponse
return "TASK-FANOUT-STARTED";
}
+async function batchingBenchmark(request: MockModelRequest): Promise<MockModelResponse | string> {
+ const message = [...request.userMessages]
+ .reverse()
+ .find((entry) => entry.startsWith("TASK-BATCHING-") || entry.startsWith("Background task "));
+ if (message === "TASK-BATCHING-QUESTION") return "56";
+ if (message === "TASK-BATCHING-BENCHMARK") return fanoutTasks(request, 10);
+ if (message?.endsWith("needs input.")) return "TASK-NOTIFICATION-ACK";
+
+ // Keep the first completion's model call active while the burst arrives.
+ // This is fixture inference time, not a runtime debounce or settlement wait.
+ const completionMessages = request.userMessages.filter(
+ (entry) => entry.startsWith("Background task ") && entry.includes(" is completed."),
+ );
+ if (completionMessages.length === 1) {
+ await new Promise((resolve) => setTimeout(resolve, 10_000));
+ }
+ const state = latestTaskState(request.userMessages);
+ if (state === undefined) return "TASK-FANOUT-STARTED";
+ // Script perfect compliance so the eval measures delivery cost, not model obedience.
+ if (state.tasks.some((task) => task.status === "pending")) return EMPTY_DELIVERY_SENTINEL;
+ const results = state.tasks.flatMap((task) =>
+ task.output?.type === "result" && typeof task.output.data === "string"
+ ? [task.output.data]
+ : [],
+ );
+ return JSON.stringify({ report: "TASK-BATCHING-REPORT", results: results.sort() });
+}
+
const FAN_IN_CALL_IDS = ["task-fan-in-1", "task-fan-in-2"] as const;
function fanInTasks(request: MockModelRequest): MockModelResponse | string {
diff --git a/e2e/fixtures/fixture-tasks/agent/subagents/fanout-worker/agent.ts b/e2e/fixtures/fixture-tasks/agent/subagents/fanout-worker/agent.ts
index b5dccf3dd..f10500c82 100644
--- a/e2e/fixtures/fixture-tasks/agent/subagents/fanout-worker/agent.ts
+++ b/e2e/fixtures/fixture-tasks/agent/subagents/fanout-worker/agent.ts
@@ -10,7 +10,9 @@ function respond(request: MockModelRequest): MockModelResponse | string {
return { toolCalls: [{ input: { marker: fanInMarker ?? "RELEASE" }, name: "release" }] };
}
if (fanInMarker !== undefined) return `FANOUT-COMPLETE:${fanInMarker}`;
- return `FANOUT-COMPLETE:${request.lastUserMessage ?? ""}`;
+ const message = request.lastUserMessage ?? "";
+ const marker = /FANOUT-WORKER-\d+/u.exec(message)?.[0] ?? message;
+ return `FANOUT-COMPLETE:${marker}`;
}
export default defineAgent({
diff --git a/e2e/fixtures/fixture-tasks/evals/README.md b/e2e/fixtures/fixture-tasks/evals/README.md
index d2cd1aaac..79651baff 100644
--- a/e2e/fixtures/fixture-tasks/evals/README.md
+++ b/e2e/fixtures/fixture-tasks/evals/README.md
@@ -1,5 +1,40 @@
# Task eval transitions
+## Completion batching measurement
+
+`task.parent.wake.emitted-ready.batching.eval.ts` launches ten children behind
+approval gates. The burst case releases nine together; the staggered case releases
+each child only after the parent has finished responding to the previous one.
+The last child stays blocked while the eval verifies silence and sends a user
+question, then completes to produce a report containing all ten distinct results.
+
+Each case logs a JSON `task-batching` record with completion-driven parent turns,
+model steps, silent and visible messages, and completions per turn. Setup wakes
+and the user question are excluded. The scripted model always obeys the silence
+policy, so this measures the runtime cost of perfect compliance; the real-model
+prompt ablation lives in `agent-task-reporting`.
+
+Batching is automatic. Both schedules run against the same runtime.
+The first completion's mock model call takes ten seconds, allowing later burst
+completions to enter the active parent's buffer. This delay belongs to the test
+model; the runtime adds no timer. The cases allow three minutes because the
+Vercel staggered run exceeded the previous two-minute timeout.
+
+At `76a18ee1`, the same burst workload with the previous option off/on took
+10/4 parent model steps in the local world. The staggered control took 10/10.
+Those measurements are retained in PR #3144; future runs exercise the default
+behavior and log their actual counts.
+
+Callback timing still varies across workflow worlds. Compare the observed batch
+sizes and model-step counts, not an assumed ten-to-one gain. The unit test at the
+delivery boundary separately proves that 100 buffered sibling completions become
+one parent turn with every payload and its metadata preserved.
+Counts are measurements, not fixed assertions that would prohibit improvements.
+The staggered case is a control for active-parent coalescing: it intentionally
+leaves no opportunity to merge adjacent completions. A policy that withholds all
+intermediate deliveries until cohort settlement needs a different driver because
+this case waits for each delivery before releasing the next child.
+
## Remote callback routing regression
`task.input.answer.accepted-complete.remote.eval.ts` reuses the existing remote
diff --git a/e2e/fixtures/fixture-tasks/evals/batching.ts b/e2e/fixtures/fixture-tasks/evals/batching.ts
new file mode 100644
index 000000000..4e88310e3
--- /dev/null
+++ b/e2e/fixtures/fixture-tasks/evals/batching.ts
@@ -0,0 +1,99 @@
+import { type EveEvalContext, type EveEvalTurn, type InputRequest } from "eve/evals";
+import { equals } from "eve/evals/expect";
+
+import { requireSessionStreamIndex, type TaskEvalSessionDriver } from "./shared.js";
+
+/** Start the benchmark and wait until every child is blocked on its release tool. */
+export async function startBlockedFanout(t: EveEvalContext, count: number) {
+ let session: TaskEvalSessionDriver = t;
+ const started = await t.send("TASK-BATCHING-BENCHMARK");
+ started.expectOk();
+ started.calledSubagent("fanout-worker", { count });
+ const taskIds = started.events.flatMap((event) =>
+ event.type === "subagent.completed" && event.data.backgroundTask !== undefined
+ ? [event.data.backgroundTask.taskId]
+ : [],
+ );
+ await t.require(
+ { receipts: taskIds.length, distinct: new Set(taskIds).size },
+ equals({ receipts: count, distinct: count }),
+ );
+
+ const requests = new Map<string, InputRequest>();
+ collectRequests(started);
+ for (let attempt = 0; requests.size < count && attempt < count; attempt += 1) {
+ collectRequests(await nextTurn());
+ }
+ await t.require({ releaseRequests: requests.size }, equals({ releaseRequests: count }));
+ const remaining = [...requests.values()];
+
+ // Only completion turns contribute to measurements; setup and user turns do not.
+ const completionTurns: EveEvalTurn[] = [];
+ const deliveredCount = () => completionTurns.flatMap(completedTaskIds).length;
+ return {
+ taskIds,
+ completionTurns,
+ async completeNext(batchSize: number) {
+ const batch = remaining.splice(0, batchSize);
+ await t.require({ releaseRequests: batch.length }, equals({ releaseRequests: batchSize }));
+ observe(
+ await session.respond(batch.map(({ requestId }) => ({ requestId, optionId: "approve" }))),
+ );
+ const expected = count - remaining.length;
+ for (let attempt = 0; deliveredCount() < expected && attempt < count; attempt += 1) {
+ observe(await nextTurn());
+ }
+ await t.require(
+ { completedDeliveries: deliveredCount() },
+ equals({ completedDeliveries: expected }),
+ );
+ },
+ async send(message: string) {
+ return observe(await session.send(message));
+ },
+ };
+
+ function collectRequests(turn: EveEvalTurn) {
+ for (const request of turn.inputRequests) {
+ if (request.action.toolName === "release") requests.set(request.requestId, request);
+ }
+ }
+
+ function observe(turn: EveEvalTurn) {
+ turn.expectOk();
+ if (completedTaskIds(turn).length > 0) completionTurns.push(turn);
+ return turn;
+ }
+
+ async function nextTurn() {
+ if (session.sessionId === undefined) throw new Error("Fanout has no parent session id.");
+ const live = t.target.watchTurn(session.sessionId, {
+ startIndex: requireSessionStreamIndex(session, "Batching benchmark"),
+ });
+ const turn = await live.result();
+ session = live.session;
+ return turn.expectOk();
+ }
+}
+
+export function completedTaskIds(turn: EveEvalTurn): string[] {
+ const notification = /Background task (task_[a-z0-9]+) \([^)]+\) is completed\./giu;
+ return turn.events.flatMap((event) => {
+ if (event.type !== "message.received") return [];
+ return [...event.data.message.matchAll(notification)].map((match) => match[1]!);
+ });
+}
+
+export function completionMetrics(turns: readonly EveEvalTurn[]) {
+ const events = turns.flatMap((turn) => turn.events);
+ const messages = events
+ .filter((event) => event.type === "message.completed")
+ .filter((event) => event.data.finishReason !== "tool-calls");
+ return {
+ parentTurns: turns.length,
+ modelSteps: events.filter((event) => event.type === "step.started").length,
+ silentMessages: messages.filter((event) => event.data.message === null).length,
+ visibleMessages: messages.filter((event) => event.data.message !== null).length,
+ completionsPerTurn: turns.map((turn) => completedTaskIds(turn).length),
+ };
+}
diff --git a/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.batching.eval.ts b/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.batching.eval.ts
new file mode 100644
index 000000000..953a88699
--- /dev/null
+++ b/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.batching.eval.ts
@@ -0,0 +1,65 @@
+import { equals } from "eve/evals/expect";
+
+import { completedTaskIds, completionMetrics, startBlockedFanout } from "./batching.js";
+import { defineTaskEval } from "./task-transition.js";
+
+const FANOUT_SIZE = 10;
+const EXPECTED_REPORT = JSON.stringify({
+ report: "TASK-BATCHING-REPORT",
+ results: Array.from(
+ { length: FANOUT_SIZE },
+ (_, index) => `FANOUT-COMPLETE:FANOUT-WORKER-${index + 1}`,
+ ).sort(),
+});
+
+export default [
+ { schedule: "burst", batches: [9] },
+ { schedule: "staggered", batches: [1, 1, 1, 1, 1, 1, 1, 1, 1] },
+].map(({ schedule, batches }) =>
+ defineTaskEval({
+ description: `Measure completion-driven parent model steps for ${FANOUT_SIZE} children (${schedule}).`,
+ timeoutMs: 180_000,
+ transition: {
+ primary: "task.parent.wake.emitted-ready",
+ setup: [
+ "task.dispatch.start.accepted-acknowledged",
+ "task.input.require.accepted-valid-batch",
+ "task.input.answer.accepted-complete",
+ "task.lifecycle.complete.accepted-nonterminal",
+ ],
+ dimensions: { transport: "local", parentPhase: "parked" },
+ },
+ async test(t) {
+ const children = await startBlockedFanout(t, FANOUT_SIZE);
+
+ // Complete nine children, keeping the last child blocked.
+ // Each batch waits for the parent response before releasing the next.
+ for (const count of batches) await children.completeNext(count);
+ const intermediate = completionMetrics(children.completionTurns);
+ t.check(intermediate.visibleMessages, equals(0)).label("intermediate completions are silent");
+
+ const question = await children.send("TASK-BATCHING-QUESTION");
+ t.check(question.message, equals("56")).label(
+ "user question answered while a child is blocked",
+ );
+ question.usedNoTools();
+
+ await children.completeNext(1);
+ t.check(
+ children.completionTurns.flatMap(completedTaskIds).sort(),
+ equals([...children.taskIds].sort()),
+ ).label("every child result delivered exactly once, with no unknown task ids");
+ t.check(children.completionTurns.at(-1)?.message, equals(EXPECTED_REPORT)).label(
+ "final report contains every distinct child result exactly once",
+ );
+
+ const total = completionMetrics(children.completionTurns);
+ t.check(total.visibleMessages, equals(1)).label("one visible final report");
+ t.log(
+ `task-batching ${JSON.stringify({ schedule, children: FANOUT_SIZE, intermediate, total })}`,
+ );
+ t.notEvent("compaction.requested");
+ t.noFailedActions();
+ },
+ }),
+);
diff --git a/packages/eve/src/execution/parked-delivery-wait.test.ts b/packages/eve/src/execution/parked-delivery-wait.test.ts
index 4200a647e..943a3ff1a 100644
--- a/packages/eve/src/execution/parked-delivery-wait.test.ts
+++ b/packages/eve/src/execution/parked-delivery-wait.test.ts
@@ -292,3 +292,165 @@ describe("nextTurnDelivery routing", () => {
expect(stateCursor.sessionState).toBe(routedSessionState);
});
});
+
+function completion(taskId: string): DeliverHookPayload {
+ return {
+ kind: "deliver",
+ taskDeliveryId: `${taskId}:ready:completed`,
+ payloads: [
+ {
+ message: taskId,
+ task: {
+ views: [
+ {
+ taskId,
+ status: "completed",
+ metadata: { kind: "subagent", name: "worker" },
+ lastOutput: { type: "result", data: taskId },
+ },
+ ],
+ },
+ },
+ ],
+ deliveryMetadata: [
+ {
+ payloadIndex: 0,
+ deliveryId: taskId,
+ channelKind: "eve",
+ channelName: "eve",
+ acceptedDeploymentId: "deployment",
+ },
+ ],
+ };
+}
+
+function batchingInput() {
+ const input = waitInput(createMockInbox([]));
+ input.stateCursor.adoptState({
+ sessionState: {
+ ...sessionState,
+ snapshot: {
+ version: 1,
+ session: {
+ sessionId: "session",
+ continuationToken: "token",
+ history: [],
+ agent: { system: "" },
+ state: {
+ "eve.tasks": {
+ version: 2,
+ tasks: Array.from({ length: 100 }, (_, index) => ({
+ taskId: `task_${index}`,
+ taskRunId: `run-${index}`,
+ taskInboxToken: `inbox-${index}`,
+ createdByTurnId: "turn-1",
+ metadata: { kind: "subagent", name: "worker" },
+ })).concat([
+ {
+ taskId: "other-cohort",
+ taskRunId: "other-run",
+ taskInboxToken: "other-inbox",
+ createdByTurnId: "turn-2",
+ metadata: { kind: "subagent", name: "worker" },
+ },
+ ]),
+ },
+ },
+ },
+ },
+ },
+ });
+ vi.mocked(routeDeliverToChildren).mockImplementation(
+ async ({ delivery, sessionState, serializedContext }) => ({
+ kind: "continue",
+ remainder: delivery,
+ sessionState,
+ serializedContext,
+ }),
+ );
+ return input;
+}
+
+describe("buffered task completion batching", () => {
+ beforeEach(() => vi.mocked(routeDeliverToChildren).mockReset());
+ afterEach(() => vi.mocked(routeDeliverToChildren).mockReset());
+
+ it("delivers 100 buffered sibling results and their metadata in one parent turn", async () => {
+ const input = batchingInput();
+ const deliveries = Array.from({ length: 100 }, (_, index) => completion(`task_${index}`));
+ const bufferedDeliveries = [...deliveries];
+ const next = await nextTurnDelivery({ ...input, bufferedDeliveries });
+
+ expect(next).toMatchObject({
+ kind: "turn",
+ delivery: {
+ taskDeliveryId: "task_0:ready:completed",
+ payloads: deliveries.flatMap((delivery) => delivery.payloads),
+ deliveryMetadata: deliveries.map((delivery, payloadIndex) => ({
+ ...delivery.deliveryMetadata![0],
+ payloadIndex,
+ })),
+ },
+ });
+ expect(bufferedDeliveries).toEqual([]);
+ expect(routeDeliverToChildren).toHaveBeenCalledTimes(1);
+ });
+
+ it.each([
+ ["failed", { ...completion("task_2"), taskDeliveryId: "task_2:ready:failed" }],
+ ["cancelled", { ...completion("task_2"), taskDeliveryId: "task_2:ready:cancelled" }],
+ ["input request", { ...completion("task_2"), taskDeliveryId: "task_2:input:request-1" }],
+ ["update", { ...completion("task_2"), taskDeliveryId: "task_2:update:1" }],
+ ["other cohort", completion("other-cohort")],
+ ["unknown task", completion("unknown-task")],
+ ["user message", { kind: "deliver", payloads: [{ message: "user direction" }] }],
+ [
+ "caller",
+ {
+ ...completion("task_2"),
+ caller: {
+ callId: "call",
+ subagentName: "worker",
+ replyTo: { kind: "hook", token: "reply" },
+ taskId: "task_2",
+ },
+ },
+ ],
+ ] satisfies readonly (readonly [string, DeliverHookPayload])[])(
+ "stops at a %s without reaching later siblings",
+ async (_name, boundary) => {
+ const input = batchingInput();
+ const first = completion("task_0");
+ const second = completion("task_1");
+ const later = completion("task_3");
+ const bufferedDeliveries = [first, second, boundary, later];
+ const next = await nextTurnDelivery({ ...input, bufferedDeliveries });
+ expect(next).toMatchObject({
+ kind: "turn",
+ delivery: { payloads: [...first.payloads, ...second.payloads] },
+ });
+ expect(bufferedDeliveries).toEqual([boundary, later]);
+ },
+ );
+
+ it("delivers an available completion without waiting for unfinished siblings", async () => {
+ const input = batchingInput();
+ const first = completion("task_0");
+ const next = await nextTurnDelivery({ ...input, bufferedDeliveries: [first] });
+ expect(next).toMatchObject({ kind: "turn", delivery: { payloads: first.payloads } });
+ expect(routeDeliverToChildren).toHaveBeenCalledTimes(1);
+ });
+
+ it("services ready authorization before a buffered completion batch", async () => {
+ const input = batchingInput();
+ const bufferedDeliveries = [completion("task_0"), completion("task_1")];
+ const next = await nextTurnDelivery({
+ ...input,
+ bufferedDeliveries,
+ commandInbox: createMockInbox([authorizationRead()], true),
+ });
+ expect(next.kind).toBe("authorization");
+ expect(bufferedDeliveries).toHaveLength(2);
+ expect(routeDeliverToChildren).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/eve/src/execution/parked-delivery-wait.ts b/packages/eve/src/execution/parked-delivery-wait.ts
index 6389215fb..3dd9f4b43 100644
--- a/packages/eve/src/execution/parked-delivery-wait.ts
+++ b/packages/eve/src/execution/parked-delivery-wait.ts
@@ -10,6 +10,7 @@ import {
type DecodedSessionInbox,
} from "#execution/wire/session-inbox-wire.js";
import { coalesceDeliveries } from "#harness/messages.js";
+import { getSessionTaskCohorts } from "#tasks/session-task-cohorts.js";
type NextSessionAction =
| { readonly kind: "clear" }
@@ -166,7 +167,10 @@ async function waitForNextSessionAction(input: {
input.bufferedDeliveries.length > 0
) {
return {
- delivery: takeBufferedTurnDelivery(input.bufferedDeliveries),
+ delivery: takeBufferedTurnDelivery(
+ input.bufferedDeliveries,
+ getSessionTaskCohorts(input.stateCursor.sessionState.snapshot?.session.state),
+ ),
kind: "delivery",
};
}
@@ -267,7 +271,10 @@ function isCancelledTaskDeliveryId(
);
}
-function takeBufferedTurnDelivery(bufferedDeliveries: DeliverHookPayload[]): DeliverHookPayload {
+function takeBufferedTurnDelivery(
+ bufferedDeliveries: DeliverHookPayload[],
+ cohorts: ReadonlyMap<string, string>,
+): DeliverHookPayload {
const first = bufferedDeliveries.shift();
if (first === undefined) {
throw new Error("Cannot take a turn delivery from an empty buffer.");
@@ -275,12 +282,13 @@ function takeBufferedTurnDelivery(bufferedDeliveries: DeliverHookPayload[]): Del
const turnDeliveries = [first];
let caller = first.caller;
+ const cohort = completionCohort(first, cohorts);
while (bufferedDeliveries.length > 0) {
const next = bufferedDeliveries[0];
if (
next === undefined ||
- first.taskDeliveryId !== undefined ||
- next.taskDeliveryId !== undefined ||
+ ((first.taskDeliveryId !== undefined || next.taskDeliveryId !== undefined) &&
+ (cohort === undefined || completionCohort(next, cohorts) !== cohort)) ||
(caller !== undefined && next.caller !== undefined)
) {
break;
@@ -296,3 +304,13 @@ function takeBufferedTurnDelivery(bufferedDeliveries: DeliverHookPayload[]): Del
return coalesceDeliveries(turnDeliveries);
}
+
+/** Only successful sibling notifications can share their existing cohort context. */
+function completionCohort(
+ delivery: DeliverHookPayload,
+ cohorts: ReadonlyMap<string, string>,
+): string | undefined {
+ const suffix = ":ready:completed";
+ if (delivery.caller !== undefined || !delivery.taskDeliveryId?.endsWith(suffix)) return undefined;
+ return cohorts.get(delivery.taskDeliveryId.slice(0, -suffix.length));
+}
diff --git a/packages/eve/src/internal/workflow-bundle/builder.scenario.test.ts b/packages/eve/src/internal/workflow-bundle/builder.scenario.test.ts
index 516dc8c75..91be973a7 100644
--- a/packages/eve/src/internal/workflow-bundle/builder.scenario.test.ts
+++ b/packages/eve/src/internal/workflow-bundle/builder.scenario.test.ts
@@ -659,11 +659,14 @@ describe("WorkflowBundleBuilder", () => {
}
});
- it("keeps the sleep tool schemas out of the workflow driver", async () => {
- const tempRoot = await mkdtemp(join(tmpdir(), "eve-workflow-bundle-sleep-tool-"));
+ it.each([
+ ["sleep tool", "src/execution/tools/sleep-workflow.ts", "executeSleepTool"],
+ ["session driver", "src/execution/workflow-entry.ts", "nextTurnDelivery"],
+ ])("keeps the %s schemas out of the workflow driver", async (_name, sourcePath, marker) => {
+ const tempRoot = await mkdtemp(join(tmpdir(), "eve-workflow-bundle-no-schemas-"));
const outDir = join(tempRoot, "workflow-build");
const compiledArtifactsBootstrapPath = join(tempRoot, "compiled-artifacts-bootstrap.mjs");
- const sleepWorkflowPath = resolvePackageSourceFilePath("src/execution/tools/sleep-workflow.ts");
+ const workflowPath = resolvePackageSourceFilePath(sourcePath);
try {
await writeFile(compiledArtifactsBootstrapPath, "export {};\n");
@@ -677,7 +680,7 @@ describe("WorkflowBundleBuilder", () => {
rootDir: resolvePackageRoot(),
watch: false,
},
- [sleepWorkflowPath],
+ [workflowPath],
);
await builder.build();
@@ -691,7 +694,7 @@ describe("WorkflowBundleBuilder", () => {
const encodedChunks = JSON.parse(encodedChunksMatch?.[1] ?? "[]") as string[];
const decodedWorkflowCode = Buffer.from(encodedChunks.join(""), "base64").toString("utf8");
- expect(decodedWorkflowCode).toContain("executeSleepTool");
+ expect(decodedWorkflowCode).toContain(marker);
expect(decodedWorkflowCode).not.toContain("compiled/zod");
} finally {
await rm(tempRoot, { force: true, recursive: true });
diff --git a/packages/eve/src/tasks/session-index.ts b/packages/eve/src/tasks/session-index.ts
index a2b022ea1..657121223 100644
--- a/packages/eve/src/tasks/session-index.ts
+++ b/packages/eve/src/tasks/session-index.ts
@@ -4,6 +4,10 @@ import type { HarnessSession, SessionStateMap } from "#harness/types.js";
import type { JsonValue } from "#shared/json.js";
import type { TaskExecutorBinding } from "#tools/task.js";
import { sameTaskMetadata, type TaskMetadata, type TaskView } from "#tasks/types.js";
+import {
+ SESSION_TASKS_STATE_KEY,
+ SESSION_TASKS_STATE_VERSION,
+} from "#tasks/session-task-cohorts.js";
/**
* Session-state key for the parent's live-task index.
@@ -14,8 +18,7 @@ import { sameTaskMetadata, type TaskMetadata, type TaskView } from "#tasks/types
* threads through step results, while callback routes and child
* executors must update tasks without holding the current snapshot.
*/
-export const SESSION_TASKS_STATE_KEY = "eve.tasks";
-const SESSION_TASKS_STATE_VERSION = 2;
+export { SESSION_TASKS_STATE_KEY } from "#tasks/session-task-cohorts.js";
/**
* One task owned by this session. Immutable model-safe metadata keeps the
diff --git a/packages/eve/src/tasks/session-task-cohorts.test.ts b/packages/eve/src/tasks/session-task-cohorts.test.ts
new file mode 100644
index 000000000..e622bce01
--- /dev/null
+++ b/packages/eve/src/tasks/session-task-cohorts.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+import { getSessionTaskIndex } from "#tasks/session-index.js";
+import { getSessionTaskCohorts, SESSION_TASKS_STATE_KEY } from "#tasks/session-task-cohorts.js";
+
+describe("workflow task cohort lookup", () => {
+ it("projects the same identities as the full task index", () => {
+ const state = {
+ [SESSION_TASKS_STATE_KEY]: {
+ version: 2,
+ tasks: ["turn-1", "turn-1", "turn-2"].map((createdByTurnId, index) => ({
+ taskId: `task_${index}`,
+ taskRunId: `run-${index}`,
+ taskInboxToken: `inbox-${index}`,
+ createdByTurnId,
+ metadata: { kind: "subagent", name: "worker" },
+ })),
+ },
+ };
+ expect([...getSessionTaskCohorts(state)]).toEqual(
+ getSessionTaskIndex(state).map((task) => [task.taskId, task.createdByTurnId]),
+ );
+ });
+
+ it("returns no cohorts when the task index is absent", () => {
+ expect(getSessionTaskCohorts(undefined).size).toBe(0);
+ expect(getSessionTaskCohorts({}).size).toBe(0);
+ });
+
+ it.each([
+ null,
+ { version: 1, tasks: [] },
+ { version: 3, tasks: [] },
+ { version: 2, tasks: null },
+ { version: 2, tasks: [null] },
+ { version: 2, tasks: [{ taskId: "", createdByTurnId: "turn-1" }] },
+ { version: 2, tasks: [{ taskId: "task_1", createdByTurnId: "" }] },
+ { version: 2, tasks: [{ taskId: "task_1", createdByTurnId: 1 }] },
+ {
+ version: 2,
+ tasks: [
+ { taskId: "task_1", createdByTurnId: "turn-1" },
+ { taskId: "task_1", createdByTurnId: "turn-2" },
+ ],
+ },
+ ])("rejects ambiguous or invalid cohort identities: %j", (raw) => {
+ expect(() => getSessionTaskCohorts({ [SESSION_TASKS_STATE_KEY]: raw })).toThrow(/task index/u);
+ });
+});
diff --git a/packages/eve/src/tasks/session-task-cohorts.ts b/packages/eve/src/tasks/session-task-cohorts.ts
new file mode 100644
index 000000000..79e61aef3
--- /dev/null
+++ b/packages/eve/src/tasks/session-task-cohorts.ts
@@ -0,0 +1,44 @@
+import type { SessionStateMap } from "#harness/types.js";
+import { isNonEmptyString, isObject } from "#shared/guards.js";
+
+/** Session-state key for the parent's task index; mutable task records live in task runs. */
+export const SESSION_TASKS_STATE_KEY = "eve.tasks";
+export const SESSION_TASKS_STATE_VERSION = 2;
+
+/**
+ * Reads only the identities needed for workflow-side completion batching.
+ * Full task validation stays in getSessionTaskIndex on the step side, so
+ * the workflow bundle does not retain the task schemas and their dependencies.
+ */
+export function getSessionTaskCohorts(
+ state: SessionStateMap | undefined,
+): ReadonlyMap<string, string> {
+ const cohorts = new Map<string, string>();
+ const raw = state?.[SESSION_TASKS_STATE_KEY];
+ if (raw === undefined) return cohorts;
+
+ if (!isObject(raw) || raw.version !== SESSION_TASKS_STATE_VERSION) {
+ throw new Error(
+ `Unsupported task index version under session state key "${SESSION_TASKS_STATE_KEY}".`,
+ );
+ }
+ if (!Array.isArray(raw.tasks)) {
+ throw new Error(
+ `Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}": expected tasks array.`,
+ );
+ }
+ for (const task of raw.tasks) {
+ if (
+ !isObject(task) ||
+ !isNonEmptyString(task.taskId) ||
+ !isNonEmptyString(task.createdByTurnId) ||
+ cohorts.has(task.taskId)
+ ) {
+ throw new Error(
+ `Corrupt task index under session state key "${SESSION_TASKS_STATE_KEY}": invalid task cohort identity.`,
+ );
+ }
+ cohorts.set(task.taskId, task.createdByTurnId);
+ }
+ return cohorts;
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ebd76ce02..c7bf8ac21 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -976,6 +976,9 @@ importers:
'@workflow/world-postgres':
specifier: 'catalog:'
+ ai:
+ specifier: 'catalog:'
+ version: 7.0.84([email protected])
eve:
specifier: workspace:*
version: link:../../../packages/eve