Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add background-tool progress and consolidated reporting (#2324)

Ruif3f4f4aeae18
diff --git a/.changeset/background-tool-update-coordinates.md b/.changeset/background-tool-update-coordinates.md
new file mode 100644
index 000000000..2afe659b1
--- /dev/null
+++ b/.changeset/background-tool-update-coordinates.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Allow in-process background tool executors to report progress and terminal results through `task.send`. Progress updates now use executor-neutral coordinates internally, and background task types are exported from `eve/tools`.
diff --git a/.changeset/task-delivery-state.md b/.changeset/task-delivery-state.md
new file mode 100644
index 000000000..ac040fdcc
--- /dev/null
+++ b/.changeset/task-delivery-state.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Give the parent model runtime-authored task state on background wakes so related intermediate results can stay silent and settle into one consolidated report.
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
index 21399831d..f8a9ed831 100644
--- a/docs/tools/overview.mdx
+++ b/docs/tools/overview.mdx
@@ -65,9 +65,15 @@ The root agent must enable `experimental.tasks`; eve rejects background tools at
This contract currently supports framework-owned task executors, including local and remote
subagents when `experimental.tasks` is enabled. After delegating, an in-process executor reports
-the terminal result with `task.send({ kind: "complete", data })` (or `fail` / `cancel`). `send` is
-not restart-safe — an in-memory callback dies with the process — so the cross-process executor
-wire remains framework-owned and is not yet a stable authored-tool API.
+progress with `task.send({ kind: "update", message })` and the terminal result with
+`task.send({ kind: "complete", data })` (or `fail` / `cancel`). `send` is not restart-safe — an
+in-memory callback dies with the process — so the cross-process executor wire remains
+framework-owned and is not yet a stable authored-tool API.
+
+Each task-triggered parent turn includes runtime-authored state for tasks started by the same
+parent turn. The model is instructed to keep related intermediate results silent while that state
+contains pending tasks. Once every related task is terminal, the state includes their outputs so
+the model can combine the useful results.
### The `ctx` parameter
diff --git a/e2e/fixtures/agent-background-tools/agent/agent.ts b/e2e/fixtures/agent-background-tools/agent/agent.ts
new file mode 100644
index 000000000..42651664a
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/agent/agent.ts
@@ -0,0 +1,56 @@
+import { e2eAgentConfig } from "@eve-e2e/config";
+import { defineAgent } from "eve";
+import { mockModel, type MockModelRequest, type MockModelResponse } from "eve/evals";
+
+const PROGRESS = "EXPORT-PROGRESS";
+const RESULT = "EXPORT-COMPLETE";
+
+function respond(request: MockModelRequest): MockModelResponse | string {
+ const message = [...request.userMessages].reverse().find((entry) => entry.trim() !== "") ?? "";
+
+ if (message.includes("BACKGROUND-EXPORT-START")) {
+ const roles = request.messages.map((entry) => entry.role);
+ if (roles.lastIndexOf("tool") <= roles.lastIndexOf("user")) {
+ return {
+ toolCalls: [
+ {
+ name: "export",
+ input: { query: "ship-it" },
+ },
+ ],
+ };
+ }
+ return "BACKGROUND-EXPORT-STARTED";
+ }
+
+ if (message.includes(`update: ${PROGRESS}`)) {
+ return "BACKGROUND-EXPORT-UPDATE-RECEIVED";
+ }
+
+ if (
+ message.includes("is completed") &&
+ (message.includes(RESULT) || message.includes("ship-it"))
+ ) {
+ return "BACKGROUND-EXPORT-DONE";
+ }
+
+ if (message.startsWith("Background task ")) {
+ return "BACKGROUND-EXPORT-ACK";
+ }
+
+ return "BACKGROUND-EXPORT-IDLE";
+}
+
+const base = e2eAgentConfig({ mock: respond });
+
+export default defineAgent({
+ ...base,
+ experimental: {
+ ...base.experimental,
+ tasks: true,
+ },
+ // Always author the deterministic script so this fixture never depends on a
+ // live model; world suites already set EVE_E2E_MODEL=mock.
+ model: mockModel(respond),
+ modelContextWindowTokens: base.modelContextWindowTokens ?? 1_000_000,
+});
diff --git a/e2e/fixtures/agent-background-tools/agent/instructions.md b/e2e/fixtures/agent-background-tools/agent/instructions.md
new file mode 100644
index 000000000..b02adc5eb
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/agent/instructions.md
@@ -0,0 +1 @@
+You are a test agent for generic background tools. Follow the mock model script.
diff --git a/e2e/fixtures/agent-background-tools/agent/tools/export.ts b/e2e/fixtures/agent-background-tools/agent/tools/export.ts
new file mode 100644
index 000000000..874227288
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/agent/tools/export.ts
@@ -0,0 +1,66 @@
+import { defineTool, type TaskExec } from "eve/tools";
+import { z } from "zod";
+
+const PROGRESS = "EXPORT-PROGRESS";
+const RESULT = "EXPORT-COMPLETE";
+
+/**
+ * Authored background tool with an in-process executor.
+ *
+ * Delegates immediately, then reports one progress update and a terminal
+ * result through the task capability so the parent sees both.
+ */
+export default defineTool({
+ description: "Start a durable background export.",
+ execution: "background",
+ inputSchema: z.strictObject({
+ query: z.string(),
+ }),
+ outputSchema: z.strictObject({
+ status: z.literal("working"),
+ taskId: z.string(),
+ }),
+ async execute(input, _ctx, task) {
+ const executor = {
+ data: { query: input.query },
+ kind: "export",
+ };
+
+ // Start a deterministic in-process executor before the tool returns so
+ // completion is independent of the parent turn.
+ void runExportExecutor({
+ query: input.query,
+ send: task.send,
+ });
+
+ return task.delegated({
+ executor,
+ receipt: {},
+ });
+ },
+});
+
+async function runExportExecutor(input: {
+ readonly query: string;
+ readonly send: TaskExec["send"];
+}): Promise<void> {
+ // Give the parent turn a moment to acknowledge the delegated task so
+ // the update is not buffered past completion.
+ await delay(250);
+
+ await input.send({
+ kind: "update",
+ message: PROGRESS,
+ });
+
+ await delay(250);
+
+ await input.send({
+ data: { query: input.query, result: RESULT },
+ kind: "complete",
+ });
+}
+
+function delay(ms: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
diff --git a/e2e/fixtures/agent-background-tools/evals/background-export.update-and-complete.eval.ts b/e2e/fixtures/agent-background-tools/evals/background-export.update-and-complete.eval.ts
new file mode 100644
index 000000000..a2809bb72
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/evals/background-export.update-and-complete.eval.ts
@@ -0,0 +1,96 @@
+import { defineEval } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+const PROGRESS = "EXPORT-PROGRESS";
+const RESULT = "EXPORT-COMPLETE";
+
+export default defineEval({
+ description:
+ "An authored background defineTool posts one task update then completes; the parent sees both.",
+ async test(t) {
+ const started = await t.send("BACKGROUND-EXPORT-START");
+ started.expectOk();
+ started.calledTool("export");
+
+ const receipt = started.requireToolCall("export");
+ const taskId = readTaskId(receipt.output);
+ if (taskId === undefined) throw new Error("export receipt is missing taskId.");
+
+ const sessionId = t.sessionId;
+ if (sessionId === undefined) throw new Error("Eval has no parent session id.");
+
+ const updateLive = t.target.watchTurn(sessionId, {
+ startIndex: requireStreamIndex(t, "update wait"),
+ });
+ const updateTurn = await updateLive.result();
+ updateTurn.expectOk();
+ updateTurn.messageIncludes("BACKGROUND-EXPORT-UPDATE-RECEIVED");
+ await t.require(
+ updateTurn.events,
+ satisfies(
+ (events: typeof updateTurn.events) =>
+ events.some(
+ (event) =>
+ event.type === "message.received" &&
+ messageText(event.data.message).includes(
+ `Background task ${taskId} (export) update: ${PROGRESS}`,
+ ),
+ ),
+ "parent receives the executor update with task identity",
+ ),
+ );
+
+ const doneLive = t.target.watchTurn(sessionId, {
+ startIndex: requireStreamIndex(updateLive.session, "completion wait"),
+ });
+ const doneTurn = await doneLive.result();
+ doneTurn.expectOk();
+ doneTurn.messageIncludes("BACKGROUND-EXPORT-DONE");
+ await t.require(
+ doneTurn.events,
+ satisfies(
+ (events: typeof doneTurn.events) =>
+ events.some(
+ (event) =>
+ event.type === "message.received" &&
+ messageText(event.data.message).includes(
+ `Background task ${taskId} (export) is completed.`,
+ ) &&
+ messageText(event.data.message).includes(RESULT),
+ ),
+ "parent receives the executor completion with task identity",
+ ),
+ );
+ t.noFailedActions();
+ },
+});
+
+function readTaskId(output: unknown): string | undefined {
+ if (output === null || typeof output !== "object") return undefined;
+ const taskId = Reflect.get(output, "taskId");
+ return typeof taskId === "string" ? taskId : undefined;
+}
+
+function requireStreamIndex(
+ session: { readonly state?: { readonly streamIndex?: number } },
+ operation: string,
+): number {
+ const streamIndex = session.state?.streamIndex;
+ if (streamIndex === undefined) throw new Error(`${operation} has no session stream index.`);
+ return 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-background-tools/evals/evals.config.ts b/e2e/fixtures/agent-background-tools/evals/evals.config.ts
new file mode 100644
index 000000000..fb5823bde
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/evals/evals.config.ts
@@ -0,0 +1,8 @@
+import { defineEvalConfig } from "eve/evals";
+
+export default defineEvalConfig({
+ // Background tools dispatch durable task runs; serialize to avoid starving
+ // children past the per-eval timeout.
+ maxConcurrency: 1,
+ timeoutMs: 120_000,
+});
diff --git a/e2e/fixtures/agent-background-tools/package.json b/e2e/fixtures/agent-background-tools/package.json
new file mode 100644
index 000000000..968ace0d4
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "agent-background-tools",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "eve build",
+ "dev": "eve dev",
+ "start": "eve start",
+ "typecheck": "eve build && tsc",
+ "test:e2e": "eve eval --strict"
+ },
+ "dependencies": {
+ "@eve-e2e/config": "workspace:*",
+ "@workflow/world-postgres": "catalog:",
+ "eve": "workspace:*",
+ "zod": "catalog:"
+ },
+ "devDependencies": {
+ "@types/node": "catalog:",
+ "typescript": "catalog:"
+ }
+}
diff --git a/e2e/fixtures/agent-background-tools/tsconfig.json b/e2e/fixtures/agent-background-tools/tsconfig.json
new file mode 100644
index 000000000..7e570d043
--- /dev/null
+++ b/e2e/fixtures/agent-background-tools/tsconfig.json
@@ -0,0 +1,17 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "outDir": "dist",
+ "rootDir": ".",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "noEmit": true,
+ "types": ["node"]
+ },
+ "include": ["agent/**/*.ts", "evals/**/*.ts"]
+}
diff --git a/e2e/fixtures/agent-task-reporting/agent/agent.ts b/e2e/fixtures/agent-task-reporting/agent/agent.ts
new file mode 100644
index 000000000..e44efea13
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/agent/agent.ts
@@ -0,0 +1,91 @@
+import { e2eAgentConfig } from "@eve-e2e/config";
+import { defineAgent } from "eve";
+import { mockModel, type MockModelRequest, type MockModelResponse } from "eve/evals";
+
+const EMPTY_DELIVERY_SENTINEL = "<eve-empty-delivery/>";
+const SCENARIO = "TASK-REPORTING-PROBE";
+const TASK_STATE_LABEL = "[Task state]\n";
+const RESULTS = ["WAKE-MECHANISM", "CHANNEL-DELIVERY", "REPORTING-POLICY"] as const;
+const DELAYS_MS = [10_000, 40_000, 70_000] as const;
+
+interface TaskState {
+ readonly tasks: readonly {
+ readonly output?: {
+ readonly data: unknown;
+ readonly type: string;
+ };
+ readonly status: string;
+ }[];
+}
+
+function respond(request: MockModelRequest): MockModelResponse | string {
+ const taskState = latestTaskState(request.userMessages);
+ if (taskState !== undefined) {
+ const alreadyReported = request.messages.some(
+ (message) => message.role === "assistant" && message.text.startsWith("Consolidated report:"),
+ );
+ if (alreadyReported || taskState.tasks.some((task) => task.status === "pending")) {
+ return EMPTY_DELIVERY_SENTINEL;
+ }
+ const results = taskState.tasks.flatMap((task) => {
+ if (task.output?.type !== "result") return [];
+ const result =
+ task.output.data !== null && typeof task.output.data === "object"
+ ? Reflect.get(task.output.data, "result")
+ : undefined;
+ return typeof result === "string" ? [result] : [];
+ });
+ return `Consolidated report: ${results.join(", ")}`;
+ }
+
+ if (!request.userMessages.some((message) => message.includes(SCENARIO))) {
+ return `Mock reply: ${request.lastUserMessage ?? ""}`;
+ }
+
+ const probeResults = request.toolResults.filter((result) => result.name === "report_probe");
+ if (probeResults.length > 0) return "investigation started";
+ return {
+ toolCalls: RESULTS.map((result, index) => ({
+ id: `report-probe-${String(index + 1)}`,
+ input: { delayMs: DELAYS_MS[index], result },
+ name: "report_probe",
+ })),
+ };
+}
+
+function latestTaskState(messages: readonly string[]): TaskState | undefined {
+ let message: string | undefined;
+ for (let index = messages.length - 1; index >= 0; index -= 1) {
+ const candidate = messages[index];
+ if (candidate?.startsWith(TASK_STATE_LABEL) === true) {
+ message = candidate;
+ break;
+ }
+ }
+ if (message === undefined) return undefined;
+ const parsed: unknown = JSON.parse(message.slice(TASK_STATE_LABEL.length));
+ if (
+ parsed === null ||
+ typeof parsed !== "object" ||
+ !Array.isArray(Reflect.get(parsed, "tasks"))
+ ) {
+ throw new Error("Invalid task state supplied to the model.");
+ }
+ return parsed as TaskState;
+}
+
+const base = e2eAgentConfig({ mock: respond });
+
+export default defineAgent({
+ ...base,
+ // Compaction must erase history without introducing another model variable.
+ compaction: {
+ model: mockModel("Background report probe remains in progress."),
+ modelContextWindowTokens: 1_000_000,
+ },
+ experimental: {
+ ...base.experimental,
+ tasks: true,
+ },
+ reasoning: "low",
+});
diff --git a/e2e/fixtures/agent-task-reporting/agent/instructions.md b/e2e/fixtures/agent-task-reporting/agent/instructions.md
new file mode 100644
index 000000000..2b71b769f
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/agent/instructions.md
@@ -0,0 +1,3 @@
+# Task reporting fixture
+
+Follow the user's request exactly. When asked to start background probes, use `report_probe`.
diff --git a/e2e/fixtures/agent-task-reporting/agent/tools/report_probe.ts b/e2e/fixtures/agent-task-reporting/agent/tools/report_probe.ts
new file mode 100644
index 000000000..5eb6963b0
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/agent/tools/report_probe.ts
@@ -0,0 +1,30 @@
+import { defineTool, type TaskExec } from "eve/tools";
+import { z } from "zod";
+
+export default defineTool({
+ description: "Start one requested background reporting probe.",
+ execution: "background",
+ inputSchema: z.strictObject({
+ delayMs: z.number().int().min(1).max(180_000),
+ result: z.string().min(1),
+ }),
+ outputSchema: z.strictObject({
+ status: z.literal("working"),
+ taskId: z.string(),
+ }),
+ async execute(input, _ctx, task) {
+ void completeProbe(input, task.send);
+ return task.delegated({
+ executor: { data: input, kind: "report-probe" },
+ receipt: {},
+ });
+ },
+});
+
+async function completeProbe(
+ input: { readonly delayMs: number; readonly result: string },
+ send: TaskExec["send"],
+): Promise<void> {
+ await new Promise((resolve) => setTimeout(resolve, input.delayMs));
+ await send({ kind: "complete", data: { result: input.result } });
+}
diff --git a/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts b/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
new file mode 100644
index 000000000..38bba8400
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
@@ -0,0 +1,161 @@
+import { defineEval, type EveEvalSession, type EveEvalTurn } from "eve/evals";
+import { satisfies } from "eve/evals/expect";
+
+const TASK_COUNT = 3;
+const RESULTS = ["WAKE-MECHANISM", "CHANNEL-DELIVERY", "REPORTING-POLICY"] as const;
+const COMPLETION = /Background task (task_[a-z0-9]+) \([^)]+\) is completed\./giu;
+
+function reportingEval() {
+ return defineEval({
+ description:
+ "Related background results produce no intermediate delivery and one consolidated final report.",
+ async test(t) {
+ if (new URL(t.target.url).hostname.endsWith(".vercel.app")) {
+ t.skip("The in-process timer executor is not restart-safe on a serverless deployment.");
+ }
+
+ const started = await t.send(`TASK-REPORTING-PROBE
+
+Call report_probe exactly three times in one response and call no other tool:
+
+1. delayMs=10000, result=WAKE-MECHANISM
+2. delayMs=40000, result=CHANNEL-DELIVERY
+3. delayMs=70000, result=REPORTING-POLICY
+
+After the three task receipts, reply only with "investigation started". Then handle the background results normally.`);
+
+ started.expectOk();
+ started.calledTool("report_probe", { count: TASK_COUNT });
+ started.messageIncludes("investigation started");
+ const taskIds = backgroundTaskIds(started);
+ await t.require(
+ taskIds,
+ satisfies(
+ (ids: readonly string[]) => ids.length === TASK_COUNT && new Set(ids).size === TASK_COUNT,
+ "three distinct background task receipts",
+ ),
+ );
+
+ let session: EveEvalSession | typeof t = t;
+ const observed = new Set<string>();
+ let finalReports = 0;
+ let compacted = false;
+ for (let attempt = 0; attempt < 8 && observed.size < TASK_COUNT; 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(TASK_COUNT)} message=${JSON.stringify(turn.message)}`,
+ );
+
+ if (observed.size < TASK_COUNT) {
+ await t.require(
+ turn.message,
+ satisfies((message) => message === undefined, "intermediate task wake is silent"),
+ );
+ } else if (turn.message !== undefined) {
+ finalReports += 1;
+ await t.require(
+ turn.message,
+ satisfies(
+ (message: string) => RESULTS.every((result) => message.includes(result)),
+ "final report consolidates every task result",
+ ),
+ );
+ }
+ turn.noFailedActions();
+ session = live.session;
+
+ if (!compacted && observed.size > 0 && observed.size < TASK_COUNT) {
+ 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 });
+ compactedTurn.event("compaction.completed", { count: 1 });
+ compactedTurn.noFailedActions();
+ session = compaction.session;
+ compacted = true;
+ }
+ }
+
+ await t.require(
+ [...observed],
+ satisfies((ids: readonly string[]) => ids.length === TASK_COUNT, "all task wakes observed"),
+ );
+ await t.require(
+ finalReports,
+ satisfies((count: number) => count === 1, "exactly one final user-facing report"),
+ );
+ await t.require(
+ compacted,
+ satisfies((value: boolean) => value, "parent session was compacted between wakes"),
+ );
+ t.noFailedActions();
+ },
+ });
+}
+
+export default Array.from({ length: 8 }, reportingEval);
+
+function backgroundTaskIds(turn: EveEvalTurn): readonly string[] {
+ return turn.events.flatMap((event) => {
+ if (
+ event.type !== "action.result" ||
+ event.data.result.kind !== "tool-result" ||
+ event.data.result.toolName !== "report_probe"
+ ) {
+ return [];
+ }
+ const output = event.data.result.output;
+ if (output === null || typeof output !== "object") return [];
+ const taskId = Reflect.get(output, "taskId");
+ return typeof taskId === "string" ? [taskId] : [];
+ });
+}
+
+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/evals.config.ts b/e2e/fixtures/agent-task-reporting/evals/evals.config.ts
new file mode 100644
index 000000000..e6f07e550
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/evals/evals.config.ts
@@ -0,0 +1,6 @@
+import { defineEvalConfig } from "eve/evals";
+
+export default defineEvalConfig({
+ maxConcurrency: 4,
+ timeoutMs: 180_000,
+});
diff --git a/e2e/fixtures/agent-task-reporting/package.json b/e2e/fixtures/agent-task-reporting/package.json
new file mode 100644
index 000000000..392564d39
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/package.json
@@ -0,0 +1,26 @@
+{
+ "name": "agent-task-reporting",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "eve build",
+ "dev": "eve dev",
+ "start": "eve start",
+ "typecheck": "eve build && tsc",
+ "test:e2e": "eve eval --strict"
+ },
+ "dependencies": {
+ "@eve-e2e/config": "workspace:*",
+ "@workflow/world-postgres": "catalog:",
+ "eve": "workspace:*",
+ "zod": "catalog:"
+ },
+ "devDependencies": {
+ "@types/node": "catalog:",
+ "typescript": "catalog:"
+ },
+ "e2e": {
+ "modelMatrix": "full"
+ }
+}
diff --git a/e2e/fixtures/agent-task-reporting/tsconfig.json b/e2e/fixtures/agent-task-reporting/tsconfig.json
new file mode 100644
index 000000000..7e570d043
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/tsconfig.json
@@ -0,0 +1,17 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "outDir": "dist",
+ "rootDir": ".",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "noEmit": true,
+ "types": ["node"]
+ },
+ "include": ["agent/**/*.ts", "evals/**/*.ts"]
+}
diff --git a/e2e/fixtures/fixture-tasks/agent/agent.ts b/e2e/fixtures/fixture-tasks/agent/agent.ts
index 0eaf515a8..924f3b1b4 100644
--- a/e2e/fixtures/fixture-tasks/agent/agent.ts
+++ b/e2e/fixtures/fixture-tasks/agent/agent.ts
@@ -9,13 +9,16 @@ import {
const TASK_ID_PATTERN = /task_[a-z0-9]+/iu;
const EMPTY_DELIVERY_SENTINEL = "<eve-empty-delivery/>";
-const CONDITIONAL_DELIVERY_MARKER = "Conditional delivery";
const REDUNDANT_REVIEW_SCENARIO = "TASK-WAKE-REDUNDANT-REVIEW";
const REDUNDANT_REVIEW_FINDING = "blocker: task admission can discard deferred user input.";
-const REDUNDANT_DELIVERY_GUIDANCE =
- "results already delivered or incorporated into an earlier response";
+const TASK_STATE_LABEL = "[Task state]\n";
function respond(request: MockModelRequest): MockModelResponse | string {
+ if (request.userMessages.includes(REDUNDANT_REVIEW_SCENARIO)) {
+ const taskState = latestTaskState(request.userMessages);
+ if (taskState !== undefined) return handleRedundantReviewWake(taskState);
+ }
+
// Framework agent-list notes are model context, not scenario turns.
const message = [...request.userMessages].reverse().find(isScenarioMessage) ?? "";
if (request.userMessages.some((entry) => entry.includes("TASK-UPDATE-PROGRESS"))) {
@@ -77,9 +80,6 @@ function respond(request: MockModelRequest): MockModelResponse | string {
}
if (message.includes("TASK-C8-REMOTE-CHILD")) return runRemoteGate(request);
if (message.startsWith("Background task ")) {
- if (request.userMessages.includes(REDUNDANT_REVIEW_SCENARIO)) {
- return handleRedundantReviewWake(request, message);
- }
// Scenarios that act on wake notifications route to their script;
// every other scenario acknowledges them without running tools.
// The exclusivity race delegates so a completion notification that
@@ -201,29 +201,43 @@ function startRedundantReviewers(request: MockModelRequest): MockModelResponse |
return "TASK-REDUNDANT-REVIEWERS-STARTED";
}
-function handleRedundantReviewWake(
- request: MockModelRequest,
- message: string,
-): MockModelResponse | string {
- if (!message.includes(REDUNDANT_REVIEW_FINDING)) {
- throw new Error("The completed reviewer did not return the expected finding.");
+function handleRedundantReviewWake(taskState: TaskState): string {
+ if (taskState.tasks.some((task) => task.status === "pending")) {
+ return EMPTY_DELIVERY_SENTINEL;
}
-
- const findingWasAlreadyReported = request.messages.some(
- (entry) => entry.role === "assistant" && entry.text.includes(REDUNDANT_REVIEW_FINDING),
+ const outputs = taskState.tasks.flatMap((task) =>
+ task.output?.type === "result" && typeof task.output.data === "string"
+ ? [task.output.data]
+ : [],
);
- if (!findingWasAlreadyReported) {
- return `request changes on PR #2277.\n\n- ${REDUNDANT_REVIEW_FINDING}`;
+ if (
+ outputs.length !== taskState.tasks.length ||
+ !outputs.every((output) => output.includes(REDUNDANT_REVIEW_FINDING))
+ ) {
+ throw new Error("The settled reviewer cohort did not contain every expected finding.");
}
+ return `request changes on PR #2277.\n\n- ${REDUNDANT_REVIEW_FINDING}`;
+}
- const conditionalInstruction = request.messages.find(
- (entry) => entry.role === "system" && entry.text.includes(CONDITIONAL_DELIVERY_MARKER),
- );
- if (conditionalInstruction === undefined) return "TASK-WAKE-WAS-NOT-CONDITIONAL";
+interface TaskState {
+ readonly tasks: readonly {
+ readonly output?: { readonly data: unknown; readonly type: string };
+ readonly status: string;
+ }[];
+}
- return conditionalInstruction.text.includes(REDUNDANT_DELIVERY_GUIDANCE)
- ? EMPTY_DELIVERY_SENTINEL
- : "already incorporated into the review above.";
+function latestTaskState(messages: readonly string[]): TaskState | undefined {
+ const message = [...messages].reverse().find((entry) => entry.startsWith(TASK_STATE_LABEL));
+ if (message === undefined) return undefined;
+ const parsed: unknown = JSON.parse(message.slice(TASK_STATE_LABEL.length));
+ if (
+ parsed === null ||
+ typeof parsed !== "object" ||
+ !Array.isArray(Reflect.get(parsed, "tasks"))
+ ) {
+ throw new Error("Invalid task state supplied to the model.");
+ }
+ return parsed as TaskState;
}
function sendTaskUpdate(request: MockModelRequest): MockModelResponse | string {
diff --git a/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.conditional-delivery.eval.ts b/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.conditional-delivery.eval.ts
index 8839a1303..f23547db5 100644
--- a/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.conditional-delivery.eval.ts
+++ b/e2e/fixtures/fixture-tasks/evals/task.parent.wake.emitted-ready.conditional-delivery.eval.ts
@@ -6,10 +6,10 @@ import { requireSessionStreamIndex } from "./shared.js";
const REVIEW_FINDING = "blocker: task admission can discard deferred user input.";
-/** A late reviewer result already represented in the conversation requires no new message. */
+/** Related reviewer results stay silent until their same-turn cohort settles. */
export default defineTaskEval({
description:
- "A completed reviewer repeats a finding already delivered to the user, so its wake remains silent.",
+ "Related reviewer wakes remain silent while pending, then produce one settled report.",
transition: {
primary: "task.parent.wake.emitted-ready",
setup: [
@@ -43,7 +43,6 @@ export default defineTaskEval({
const firstWake = await firstLive.result();
firstWake.expectOk();
- firstWake.messageIncludes(`request changes on PR #2277.\n\n- ${REVIEW_FINDING}`);
const firstNotification = requireTaskNotification(firstWake);
await t.require(
firstNotification,
@@ -54,6 +53,17 @@ export default defineTaskEval({
),
);
firstWake.notCalledTool("task_peek");
+ firstWake.event("message.completed", {
+ count: 1,
+ data: (data) => data.finishReason !== "tool-calls" && data.message === null,
+ });
+ firstWake.notEvent("message.completed", {
+ data: (data) => data.finishReason !== "tool-calls" && data.message !== null,
+ });
+ await t.require(
+ firstWake.message,
+ satisfies((message) => message === undefined, "the pending cohort wake is silent"),
+ );
const secondLive = t.target.watchTurn(sessionId, {
startIndex: requireSessionStreamIndex(firstLive.session, "Late reviewer wake"),
@@ -73,17 +83,11 @@ export default defineTaskEval({
),
);
wake.notCalledTool("task_peek");
+ wake.messageIncludes(`request changes on PR #2277.\n\n- ${REVIEW_FINDING}`);
wake.event("message.completed", {
count: 1,
- data: (data) => data.finishReason !== "tool-calls" && data.message === null,
- });
- wake.notEvent("message.completed", {
data: (data) => data.finishReason !== "tool-calls" && data.message !== null,
});
- await t.require(
- wake.message,
- satisfies((message) => message === undefined, "the task wake delivers no channel message"),
- );
t.notCalledTool("task_peek");
t.noFailedActions();
},
diff --git a/packages/eve/extension-contracts/compatibility/tool/v16.ts b/packages/eve/extension-contracts/compatibility/tool/v16.ts
new file mode 100644
index 000000000..8a728e2a8
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v16.ts
@@ -0,0 +1,18 @@
+import { z as z3 } from "zod/v3";
+
+import { defineTool } from "#public/tools/index.js";
+
+export default defineTool({
+ description: "Start a report.",
+ execution: "background",
+ inputSchema: z3.object({ reportId: z3.string() }),
+ execute(input, _ctx, task) {
+ void Promise.resolve().then(() =>
+ task.send({ data: { reportId: input.reportId }, kind: "complete" }),
+ );
+ return task.delegated({
+ executor: { data: { reportId: input.reportId }, kind: "report" },
+ receipt: { reportId: input.reportId },
+ });
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/tool/v17.json b/packages/eve/extension-contracts/reports/tool/v17.json
new file mode 100644
index 000000000..5165e1fe3
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v17.json
@@ -0,0 +1,22 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 17,
+ "sha256": "ffd393709ef63277253253189c25422abc724a1fde34a6591e47876e9a9c6fa0",
+ "exports": [
+ "defineBashTool",
+ "defineGlobTool",
+ "defineGrepTool",
+ "defineReadFileTool",
+ "defineTool",
+ "defineWriteFileTool",
+ "disableTool",
+ "experimental_workflow",
+ "isDisabledToolSentinel",
+ "isExperimentalWorkflowToolDefinition",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch"
+ ]
+}
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index b403693a4..176291c97 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,8 +22,8 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 16,
- supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16],
+ current: 17,
+ supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 17],
dropped: { 15: "TaskExec replaces stageEffect with send" },
},
dynamicTool: {
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index b33f2d9e7..e44d05c39 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -71,8 +71,10 @@ export const SessionIdKey = new ContextKey<string>("eve.sessionId");
export const ContinuationTokenKey = new ContextKey<string>("eve.continuationToken");
export const ChannelRequestIdKey = new ContextKey<string>("eve.channelRequestId");
export const ChannelDeliveryKey = new ContextKey<ChannelDeliveryMetadata>("eve.channelDelivery");
-/** Whether the active turn began from a task-addressed durable delivery. */
-export const TurnTaskDeliveryKey = new ContextKey<boolean>("eve.turnTaskDelivery");
+/** Task-cohort phase when the active turn began from a task-addressed durable delivery. */
+export const TurnTaskDeliveryKey = new ContextKey<"none" | "pending" | "settled">(
+ "eve.turnTaskDelivery",
+);
export interface ActiveChannelDelivery {
readonly agentName?: string;
readonly delivery: InstrumentationChannelDeliveryRef;
diff --git a/packages/eve/src/execution/session-callback-step.test.ts b/packages/eve/src/execution/session-callback-step.test.ts
index 72367b41f..71e3ad468 100644
--- a/packages/eve/src/execution/session-callback-step.test.ts
+++ b/packages/eve/src/execution/session-callback-step.test.ts
@@ -315,16 +315,16 @@ describe("fireTaskUpdateCallbackStep", () => {
url: "https://caller.example.com/eve/v1/callback/task-token",
},
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
message: "Found three matching records.",
});
expect(taskId).toBe("task_abc");
expect(parsePostedBody(fetchMock)).toEqual({
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
kind: "task.update",
message: "Found three matching records.",
taskId: "task_abc",
diff --git a/packages/eve/src/execution/session-callback-step.ts b/packages/eve/src/execution/session-callback-step.ts
index d36e132fb..f77ea1376 100644
--- a/packages/eve/src/execution/session-callback-step.ts
+++ b/packages/eve/src/execution/session-callback-step.ts
@@ -46,8 +46,8 @@ export async function fireTaskEventCallbackStep(input: {
export async function fireTaskUpdateCallbackStep(input: {
readonly callback: unknown;
readonly callId: string;
- readonly childStepIndex: number;
- readonly childTurnId: string;
+ readonly updateIndex: number;
+ readonly updateEpoch: string;
readonly message: string;
}): Promise<string | undefined> {
"use step";
@@ -57,8 +57,8 @@ export async function fireTaskUpdateCallbackStep(input: {
const response = await postSessionCallbackRequest({
body: {
callId: input.callId,
- childStepIndex: input.childStepIndex,
- childTurnId: input.childTurnId,
+ updateIndex: input.updateIndex,
+ updateEpoch: input.updateEpoch,
kind: "task.update",
message: input.message,
taskId: callback.taskId,
diff --git a/packages/eve/src/execution/tasks/child/steps.ts b/packages/eve/src/execution/tasks/child/steps.ts
index f057785be..6ab60f612 100644
--- a/packages/eve/src/execution/tasks/child/steps.ts
+++ b/packages/eve/src/execution/tasks/child/steps.ts
@@ -130,7 +130,7 @@ export async function wakeTaskUpdateParentStep(input: {
payload: {
message: `Background task ${input.view.taskId} (${input.view.metadata.name}) update: ${input.update.message}`,
},
- taskDeliveryId: `${input.view.taskId}:update:${input.update.childTurnId}:${input.update.childStepIndex}:${input.update.callId}`,
+ taskDeliveryId: `${input.view.taskId}:update:${input.update.updateEpoch}:${input.update.updateIndex}:${input.update.callId}`,
};
try {
await resumeSessionInbox(input.token, command);
diff --git a/packages/eve/src/execution/tasks/child/update.test.ts b/packages/eve/src/execution/tasks/child/update.test.ts
index c8699046f..839c74338 100644
--- a/packages/eve/src/execution/tasks/child/update.test.ts
+++ b/packages/eve/src/execution/tasks/child/update.test.ts
@@ -35,15 +35,15 @@ describe("executeTaskUpdate", () => {
subagentName: "agent",
},
} as never,
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
serializedContext: {},
});
expect(resumeHookMock).toHaveBeenCalledWith(token, {
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
kind: "task-update",
message: "Found three matching records.",
});
@@ -62,16 +62,16 @@ describe("executeTaskUpdate", () => {
const result = await executeTaskUpdate({
action,
adapter: undefined,
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
serializedContext: { "eve.sessionCallback": callback },
});
expect(fireTaskUpdateCallbackStep).toHaveBeenCalledWith({
callback,
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
message: "Found three matching records.",
});
expect(result).toMatchObject({ output: { status: "sent", taskId: "task_abc" } });
diff --git a/packages/eve/src/execution/tasks/child/update.ts b/packages/eve/src/execution/tasks/child/update.ts
index dd844d815..7777acef3 100644
--- a/packages/eve/src/execution/tasks/child/update.ts
+++ b/packages/eve/src/execution/tasks/child/update.ts
@@ -15,8 +15,8 @@ import type { TaskInboundUpdate } from "#tasks/types.js";
export async function executeTaskUpdate(input: {
readonly action: RuntimeToolCallActionRequest;
readonly adapter: ChannelAdapter | undefined;
- readonly childStepIndex: number;
- readonly childTurnId: string;
+ readonly updateIndex: number;
+ readonly updateEpoch: string;
readonly serializedContext: Record<string, unknown> | undefined;
}): Promise<RuntimeActionResult> {
const message = readUpdateMessage(input.action.input);
@@ -29,8 +29,8 @@ export async function executeTaskUpdate(input: {
const taskId = await fireTaskUpdateCallbackStep({
callback,
callId: input.action.callId,
- childStepIndex: input.childStepIndex,
- childTurnId: input.childTurnId,
+ updateIndex: input.updateIndex,
+ updateEpoch: input.updateEpoch,
message,
});
if (taskId === undefined) {
@@ -50,8 +50,8 @@ export async function executeTaskUpdate(input: {
}
const update: TaskInboundUpdate = {
callId: input.action.callId,
- childStepIndex: input.childStepIndex,
- childTurnId: input.childTurnId,
+ updateIndex: input.updateIndex,
+ updateEpoch: input.updateEpoch,
kind: "task-update",
message,
};
diff --git a/packages/eve/src/execution/tasks/child/workflow.test.ts b/packages/eve/src/execution/tasks/child/workflow.test.ts
index a1d234986..2e7c47350 100644
--- a/packages/eve/src/execution/tasks/child/workflow.test.ts
+++ b/packages/eve/src/execution/tasks/child/workflow.test.ts
@@ -79,8 +79,8 @@ describe("taskRunWorkflow", () => {
it("forwards child updates after dispatch acknowledgement without changing the view", async () => {
const update = {
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
kind: "task-update" as const,
message: "Found three matching records.",
};
@@ -114,8 +114,8 @@ describe("taskRunWorkflow", () => {
it("forwards a fast child update before its terminal wake", async () => {
const update = {
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
kind: "task-update" as const,
message: "Final progress update.",
};
diff --git a/packages/eve/src/execution/tasks/parent/dispatch.ts b/packages/eve/src/execution/tasks/parent/dispatch.ts
index f39db9b99..132131e8d 100644
--- a/packages/eve/src/execution/tasks/parent/dispatch.ts
+++ b/packages/eve/src/execution/tasks/parent/dispatch.ts
@@ -76,8 +76,8 @@ export async function executeTaskControlAction(input: {
result: await executeTaskUpdate({
action,
adapter: input.adapter,
- childStepIndex: input.parentStepIndex ?? 0,
- childTurnId: input.parentTurnId,
+ updateIndex: input.parentStepIndex ?? 0,
+ updateEpoch: input.parentTurnId,
serializedContext: input.serializedContext,
}),
session,
diff --git a/packages/eve/src/execution/tasks/parent/tool-execution.test.ts b/packages/eve/src/execution/tasks/parent/tool-execution.test.ts
index cbee8c551..552ce06d6 100644
--- a/packages/eve/src/execution/tasks/parent/tool-execution.test.ts
+++ b/packages/eve/src/execution/tasks/parent/tool-execution.test.ts
@@ -28,6 +28,7 @@ const mocks = vi.hoisted(() => ({
propagateSubagentExecutorCancel: vi.fn(),
rejectDelegatedDispatch: vi.fn(),
sendTaskCommand: vi.fn(),
+ sendTaskInboundPayload: vi.fn(),
}));
vi.mock("#execution/tasks/parent/delegate.js", async (importOriginal) => ({
@@ -42,6 +43,7 @@ vi.mock("#execution/tasks/parent/dispatch.js", async (importOriginal) => ({
vi.mock("#execution/tasks/parent/run-parent.js", async (importOriginal) => ({
...(await importOriginal<typeof import("#execution/tasks/parent/run-parent.js")>()),
sendTaskCommand: mocks.sendTaskCommand,
+ sendTaskInboundPayload: mocks.sendTaskInboundPayload,
}));
const usage = {
@@ -124,6 +126,7 @@ describe("background tool execution", () => {
mocks.propagateSubagentExecutorCancel.mockReset();
mocks.rejectDelegatedDispatch.mockReset();
mocks.sendTaskCommand.mockReset();
+ mocks.sendTaskInboundPayload.mockReset();
});
it("runs a non-subagent defineTool through the generic durable task lifecycle", async () => {
@@ -275,7 +278,7 @@ describe("background tool execution", () => {
expect(mocks.rejectDelegatedDispatch).not.toHaveBeenCalled();
});
- it("send delivers terminal commands after delegation and rejects once the task is terminal", async () => {
+ it("send delivers progress and terminal commands after delegation", async () => {
const task = {
createdByStepIndex: 0,
createdByTurnId: "turn-1",
@@ -286,6 +289,7 @@ describe("background tool execution", () => {
} as const;
mocks.beginBackgroundTask.mockResolvedValue(task);
mocks.sendTaskCommand.mockResolvedValue("delivered");
+ mocks.sendTaskInboundPayload.mockResolvedValue("delivered");
let background: TaskExec | undefined;
const definition = defineTool({
description: "Start an external export.",
@@ -354,6 +358,35 @@ describe("background tool execution", () => {
);
expect(background).toBeDefined();
+ await background!.send({
+ kind: "update",
+ message: "Exported 10 rows.",
+ });
+ await background!.send({
+ kind: "update",
+ message: "Exported 20 rows.",
+ });
+ expect(mocks.sendTaskInboundPayload).toHaveBeenNthCalledWith(1, {
+ payload: {
+ callId: "call-export",
+ kind: "task-update",
+ message: "Exported 10 rows.",
+ updateEpoch: "task-export",
+ updateIndex: 0,
+ },
+ taskInboxToken: "inbox-export",
+ });
+ expect(mocks.sendTaskInboundPayload).toHaveBeenNthCalledWith(2, {
+ payload: {
+ callId: "call-export",
+ kind: "task-update",
+ message: "Exported 20 rows.",
+ updateEpoch: "task-export",
+ updateIndex: 1,
+ },
+ taskInboxToken: "inbox-export",
+ });
+
await background!.send({ data: { rows: 10 }, kind: "complete" });
expect(mocks.sendTaskCommand).toHaveBeenLastCalledWith({
command: { data: { rows: 10 }, kind: "complete" },
diff --git a/packages/eve/src/execution/tasks/parent/tool-execution.ts b/packages/eve/src/execution/tasks/parent/tool-execution.ts
index f6f2c2893..ad0528b4f 100644
--- a/packages/eve/src/execution/tasks/parent/tool-execution.ts
+++ b/packages/eve/src/execution/tasks/parent/tool-execution.ts
@@ -18,11 +18,16 @@ import { createEveCallbackRoutePath } from "#protocol/routes.js";
import { isAsyncIterable } from "#shared/async-iterable.js";
import { parseJsonValue } from "#shared/json.js";
import type { ToolExecuteOptions } from "#shared/tool-definition.js";
-import { createTaskDelegated, isTaskDelegated, type TaskExec } from "#shared/tool-task.js";
+import {
+ createTaskDelegated,
+ isTaskDelegated,
+ type TaskExec,
+ type TaskSendCommand,
+} from "#shared/tool-task.js";
import { recordTaskAgentAddress } from "#harness/handles/transitions.js";
import { BundleKey, type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
import { recordSessionTask } from "#tasks/session-index.js";
-import { readSubagentExecutor } from "#tasks/types.js";
+import { readSubagentExecutor, type TaskInboundUpdate } from "#tasks/types.js";
import { createWorkflowCallbackUrl } from "#execution/workflow-callback-url.js";
import {
beginBackgroundTask,
@@ -30,7 +35,7 @@ import {
type BackgroundTask,
} from "#execution/tasks/parent/delegate.js";
import { propagateSubagentExecutorCancel } from "#execution/tasks/parent/dispatch.js";
-import { sendTaskCommand } from "#execution/tasks/parent/run-parent.js";
+import { sendTaskCommand, sendTaskInboundPayload } from "#execution/tasks/parent/run-parent.js";
interface BackgroundToolExecutionRecord {
settled: boolean;
@@ -241,7 +246,7 @@ class BackgroundToolExecutionScope implements BackgroundToolExecutor {
batch: input.batch.calls,
binding,
delegated: ({ executor, receipt }) => createTaskDelegated({ binding, executor, receipt }),
- send: (command) => deliverTaskCommand(task, command),
+ send: createTaskSender(task, input.options.toolCallId),
session: this.initialSession,
task,
};
@@ -285,6 +290,34 @@ async function deliverTaskCommand(
}
}
+function createTaskSender(
+ task: BackgroundTask,
+ callId: string,
+): (command: TaskSendCommand) => Promise<void> {
+ let nextUpdateIndex = 0;
+ return async (command) => {
+ if (command.kind !== "update") {
+ await deliverTaskCommand(task, command);
+ return;
+ }
+
+ const payload: TaskInboundUpdate = {
+ callId,
+ kind: "task-update",
+ message: command.message,
+ updateEpoch: task.taskId,
+ updateIndex: nextUpdateIndex++,
+ };
+ const outcome = await sendTaskInboundPayload({
+ payload,
+ taskInboxToken: task.taskInboxToken,
+ });
+ if (outcome !== "delivered") {
+ throw new Error(`Task run "${task.taskId}" did not accept "${command.kind}".`);
+ }
+ };
+}
+
async function compensateBackgroundToolExecution(
records: readonly BackgroundToolExecutionRecord[],
cause: unknown,
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index 83a929ab8..76c99a783 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -2301,10 +2301,31 @@ describe("turnStep", () => {
});
});
- it("sets and resets task-delivery provenance from durable deliveries", async () => {
+ it("sets task-delivery provenance only when the runtime supplies owned task state", async () => {
const observedTaskDeliveries: unknown[] = [];
- const session = createStubSession();
- installSessionStoreMocks([session, session]);
+ const metadata = { kind: "report-probe", name: "report_probe" } as const;
+ const session = createStubSession({
+ state: {
+ "eve.tasks": {
+ tasks: [
+ {
+ taskInboxToken: "task-token",
+ createdByTurnId: "turn-parent",
+ metadata,
+ taskId: "task_1",
+ taskRunId: "run_1",
+ terminalView: {
+ lastOutput: { data: { result: "done" }, type: "result" },
+ metadata,
+ status: "completed",
+ taskId: "task_1",
+ },
+ },
+ ],
+ },
+ },
+ });
+ installSessionStoreMocks([session, session, session]);
vi.mocked(createExecutionNodeStep).mockImplementation(() => {
return async (stepSession): Promise<StepResult> => {
observedTaskDeliveries.push(contextStorage.getStore()?.get(TurnTaskDeliveryKey));
@@ -2322,14 +2343,24 @@ describe("turnStep", () => {
serializedContext: createSerializedContext(),
sessionState: createStubSessionState(),
});
- await turnStep({
- input: { kind: "deliver", payloads: [{ message: "What happened?" }] },
+ const second = await turnStep({
+ input: {
+ kind: "deliver",
+ payloads: [{ message: "Background task task_unknown is completed." }],
+ taskDeliveryId: "task_unknown:ready:completed",
+ },
parentWritable: createTestWritable(),
serializedContext: first.serializedContext,
sessionState: first.sessionState,
});
+ await turnStep({
+ input: { kind: "deliver", payloads: [{ message: "What happened?" }] },
+ parentWritable: createTestWritable(),
+ serializedContext: second.serializedContext,
+ sessionState: second.sessionState,
+ });
- expect(observedTaskDeliveries).toEqual([true, false]);
+ expect(observedTaskDeliveries).toEqual(["settled", "none", "none"]);
});
it("projects a requested sleep onto the durable step result", async () => {
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index bb49ff2d0..ef05c9d37 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -83,6 +83,7 @@ import { createDurableSessionState, readDurableSession } from "#execution/durabl
import type { TurnStepInput } from "#execution/durable-session-migrations/turn-workflow.js";
import { buildRuntimeIdentity, createExecutionNodeStep } from "#execution/node-step.js";
import { appendTaskAgentAnnouncement } from "#execution/tasks/parent/agent-views.js";
+import { resolveTaskDeliveryContext } from "#tasks/delivery-context.js";
import {
readRetainedBackgroundToolResult,
runBackgroundStep,
@@ -117,7 +118,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
let durableSession = await readDurableSession(input.sessionState);
const ctx = await deserializeContext(input.serializedContext);
if (rawInput.input?.kind === "deliver") {
- ctx.set(TurnTaskDeliveryKey, rawInput.input.taskDeliveryId !== undefined);
+ ctx.set(TurnTaskDeliveryKey, "none");
}
const adapter = ctx.require(ChannelKey);
const bundle = ctx.require(BundleKey);
@@ -249,6 +250,24 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
resolved = { runtimeActionResults: input.input.results };
}
+ if (
+ resolved !== undefined &&
+ rawInput.input?.kind === "deliver" &&
+ rawInput.input.taskDeliveryId !== undefined
+ ) {
+ const taskContext = resolveTaskDeliveryContext({
+ state: durableSession.state,
+ taskDeliveryId: rawInput.input.taskDeliveryId,
+ });
+ if (taskContext !== undefined) {
+ ctx.set(TurnTaskDeliveryKey, taskContext.phase);
+ resolved = {
+ ...resolved,
+ context: [...(resolved.context ?? []), taskContext.context],
+ };
+ }
+ }
+
// Persist adapter-state mutations across the step boundary.
if (input.input?.kind === "deliver") {
const updatedAdapter = { ...adapter, state: { ...adapterCtx.state } };
diff --git a/packages/eve/src/harness/messages.test.ts b/packages/eve/src/harness/messages.test.ts
index b50d7e4eb..0f7c188ae 100644
--- a/packages/eve/src/harness/messages.test.ts
+++ b/packages/eve/src/harness/messages.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import {
coalesceDeliveries,
coalesceTurnInputs,
+ normalizeModelMessages,
normalizeUserContent,
resolveAssistantStepText,
} from "#harness/messages.js";
@@ -225,6 +226,26 @@ describe("normalizeUserContent", () => {
});
});
+describe("normalizeModelMessages", () => {
+ it("drops blank text without removing meaningful structured content", () => {
+ const toolCall = {
+ input: {},
+ toolCallId: "call-1",
+ toolName: "probe",
+ type: "tool-call" as const,
+ };
+ const visible = { content: "Keep me", role: "user" as const };
+
+ expect(
+ normalizeModelMessages([
+ { content: " ", role: "assistant" },
+ { content: [{ text: "", type: "text" }, toolCall], role: "assistant" },
+ visible,
+ ]),
+ ).toEqual([{ content: [toolCall], role: "assistant" }, visible]);
+ });
+});
+
describe("resolveAssistantStepText", () => {
it("extracts text from a string-content assistant message", () => {
const messages: ModelMessage[] = [{ content: "Hello!", role: "assistant" }];
diff --git a/packages/eve/src/harness/messages.ts b/packages/eve/src/harness/messages.ts
index ae093f21f..1618611fa 100644
--- a/packages/eve/src/harness/messages.ts
+++ b/packages/eve/src/harness/messages.ts
@@ -81,6 +81,23 @@ export function normalizeUserContent(
return parts.length === content.length ? content : parts;
}
+/** Removes blank text blocks that some providers reject from model-bound history. */
+export function normalizeModelMessages(messages: readonly ModelMessage[]): ModelMessage[] {
+ return messages.flatMap((message) => {
+ if (typeof message.content === "string") {
+ return message.content.trim().length > 0 ? [message] : [];
+ }
+
+ const content = message.content.filter(
+ (part) => part.type !== "text" || part.text.trim().length > 0,
+ );
+ if (content.length === 0) return [];
+ return content.length === message.content.length
+ ? [message]
+ : [{ ...message, content } as ModelMessage];
+ });
+}
+
/**
* Extracts the final visible assistant text from model response messages.
*
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 1c0ae009e..e72884f61 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -71,6 +71,10 @@ import {
CONDITIONAL_DELIVERY_INSTRUCTION,
EMPTY_DELIVERY_SENTINEL,
} from "#shared/empty-delivery.js";
+import {
+ TASK_DELIVERY_PENDING_INSTRUCTION,
+ TASK_DELIVERY_SETTLED_INSTRUCTION,
+} from "#tasks/delivery-context.js";
vi.mock("ai", () => ({
ToolLoopAgent: vi.fn(),
@@ -822,38 +826,79 @@ describe("createToolLoopHarness", () => {
}
});
- it("parks without delivery when a terminal response contains the empty-delivery sentinel", async () => {
+ it("removes blank text blocks from persisted history before the provider call", async () => {
setupMockAgent({
finishReason: "stop",
- response: {
- messages: [
- {
- content: `internal ${EMPTY_DELIVERY_SENTINEL} trailing`,
- role: "assistant",
- },
- ],
- },
- text: `internal ${EMPTY_DELIVERY_SENTINEL} trailing`,
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
toolCalls: [],
toolResults: [],
});
- const { emit, events } = createEventCollector();
- const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
-
- const result = await runStep(createTestSession(), { message: "Hi" });
-
- expect(result.next).toBeNull();
- expect(result.session.history).toEqual([{ content: "Hi", role: "user" }]);
- expect(vi.mocked(ToolLoopAgent).mock.calls.length).toBe(1);
- expect(events).toContainEqual(
- expect.objectContaining({
- data: expect.objectContaining({ message: null }),
- type: "message.completed",
+ const runStep = createToolLoopHarness(createTestConfig("conversation"));
+ await runStep(
+ createTestSession({
+ history: [
+ { content: " ", role: "assistant" },
+ {
+ content: [
+ { text: "", type: "text" },
+ { text: "Previous reply", type: "text" },
+ ],
+ role: "assistant",
+ },
+ ],
}),
+ { message: "Continue" },
);
+
+ const agent = vi.mocked(ToolLoopAgent).mock.results[0]?.value as {
+ generate: ReturnType<typeof vi.fn>;
+ };
+ expect(agent.generate.mock.calls[0]?.[0].messages).toEqual([
+ { content: [{ text: "Previous reply", type: "text" }], role: "assistant" },
+ { content: "Continue", role: "user" },
+ ]);
});
+ it.each([
+ ["literal", EMPTY_DELIVERY_SENTINEL],
+ ["HTML-escaped", "&lt;eve-empty-delivery/&gt;"],
+ ])(
+ "parks without delivery when a terminal response contains the %s sentinel",
+ async (_, sentinel) => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: {
+ messages: [
+ {
+ content: `internal ${sentinel} trailing`,
+ role: "assistant",
+ },
+ ],
+ },
+ text: `internal ${sentinel} trailing`,
+ toolCalls: [],
+ toolResults: [],
+ });
+
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
+
+ const result = await runStep(createTestSession(), { message: "Hi" });
+
+ expect(result.next).toBeNull();
+ expect(result.session.history).toEqual([{ content: "Hi", role: "user" }]);
+ expect(vi.mocked(ToolLoopAgent).mock.calls.length).toBe(1);
+ expect(events).toContainEqual(
+ expect.objectContaining({
+ data: expect.objectContaining({ message: null }),
+ type: "message.completed",
+ }),
+ );
+ },
+ );
+
it("keeps executable tools directly available to the model", async () => {
setupMockAgent({
finishReason: "stop",
@@ -11268,22 +11313,28 @@ describe("createToolLoopHarness", () => {
expect(instructions).toBe("You are a test assistant.");
});
- it("adds conditional-delivery guidance to a top-level framework wake", async () => {
- setupMockAgent(defaultModelResult());
- const runStep = createToolLoopHarness(createTestConfig("conversation"));
- const ctx = new ContextContainer();
- ctx.set(TurnTaskDeliveryKey, true);
+ it.each([
+ ["pending", TASK_DELIVERY_PENDING_INSTRUCTION],
+ ["settled", TASK_DELIVERY_SETTLED_INSTRUCTION],
+ ] as const)(
+ "adds %s task-delivery guidance to a top-level framework wake",
+ async (phase, instruction) => {
+ setupMockAgent(defaultModelResult());
+ const runStep = createToolLoopHarness(createTestConfig("conversation"));
+ const ctx = new ContextContainer();
+ ctx.set(TurnTaskDeliveryKey, phase);
- await contextStorage.run(ctx, () =>
- runStep(createTestSession(), { message: "Background task task_1 is completed." }),
- );
+ await contextStorage.run(ctx, () =>
+ runStep(createTestSession(), { message: "Background task task_1 is completed." }),
+ );
- const { instructions } = getLastAgentSettings();
- expect(instructions).toEqual({
- role: "system",
- content: `You are a test assistant.\n\n${CONDITIONAL_DELIVERY_INSTRUCTION}`,
- });
- });
+ const { instructions } = getLastAgentSettings();
+ expect(instructions).toEqual({
+ role: "system",
+ content: `You are a test assistant.\n\n${instruction}`,
+ });
+ },
+ );
it("does not add conditional-delivery guidance to a human continuation", async () => {
setupMockAgent(defaultModelResult());
@@ -11308,7 +11359,7 @@ describe("createToolLoopHarness", () => {
setupMockAgent(defaultModelResult());
const runStep = createToolLoopHarness(createTestConfig("conversation"));
const ctx = new ContextContainer();
- ctx.set(TurnTaskDeliveryKey, true);
+ ctx.set(TurnTaskDeliveryKey, "pending");
setDelegatedParent(ctx);
await contextStorage.run(ctx, () =>
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index c5a357caf..df4f29351 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -171,7 +171,11 @@ import {
import { getInstrumentationConfig } from "#harness/instrumentation/config.js";
import { getInstrumentationRuntime } from "#harness/instrumentation/runtime.js";
import type { OtelHarnessSettings } from "#tracing/otel-declaration.js";
-import { normalizeUserContent, resolveAssistantStepText } from "#harness/messages.js";
+import {
+ normalizeModelMessages,
+ normalizeUserContent,
+ resolveAssistantStepText,
+} from "#harness/messages.js";
import { normalizeProviderToolHistory } from "#harness/provider-tool-history.js";
import {
type AuthorizationSignal,
@@ -203,6 +207,10 @@ import {
EMPTY_DELIVERY_SENTINEL,
hasEmptyDeliverySentinel,
} from "#shared/empty-delivery.js";
+import {
+ TASK_DELIVERY_PENDING_INSTRUCTION,
+ TASK_DELIVERY_SETTLED_INSTRUCTION,
+} from "#tasks/delivery-context.js";
import { extractWorkflowStreamWriteErrorDetails } from "#harness/workflow-stream-error.js";
import {
ensureOtelIntegration,
@@ -1264,7 +1272,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
if (compaction.compacted) {
messages = compaction.messages;
}
- projectedMessages = projectHistory(messages, session.state);
+ projectedMessages = normalizeModelMessages(projectHistory(messages, session.state));
if (emit) {
await emitStepStarted(
@@ -1274,9 +1282,9 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
projectedMessages,
);
}
-
const approvedTools = getApprovedTools(session);
+ const taskDeliveryPhase = ctx?.get(TurnTaskDeliveryKey);
const emptyDeliveryEnabled =
// A structured-output run must always produce its declared result.
session.outputSchema === undefined &&
@@ -1287,7 +1295,8 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
// A schedule-initiated root turn may have nothing worth delivering.
(isScheduleAppAuth(ctx.get(AuthKey)) ||
// A task-notification root turn may act on the wake without messaging the user.
- ctx.get(TurnTaskDeliveryKey) === true);
+ taskDeliveryPhase === "pending" ||
+ taskDeliveryPhase === "settled");
// --- Execute via ToolLoopAgent ------------------------------------------
@@ -1321,7 +1330,16 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
}
}
if (emptyDeliveryEnabled) {
- systemMessages.push({ role: "system", content: CONDITIONAL_DELIVERY_INSTRUCTION });
+ const deliveryInstruction =
+ taskDeliveryPhase === "pending"
+ ? TASK_DELIVERY_PENDING_INSTRUCTION
+ : taskDeliveryPhase === "settled"
+ ? TASK_DELIVERY_SETTLED_INSTRUCTION
+ : CONDITIONAL_DELIVERY_INSTRUCTION;
+ systemMessages.push({
+ role: "system",
+ content: deliveryInstruction,
+ });
}
const modelMessages = nonSystemMessages;
diff --git a/packages/eve/src/public/tools/index.ts b/packages/eve/src/public/tools/index.ts
index 55834961e..e2f885be0 100644
--- a/packages/eve/src/public/tools/index.ts
+++ b/packages/eve/src/public/tools/index.ts
@@ -3,6 +3,7 @@
*/
export {
+ type BackgroundToolDefinition,
type DisabledToolSentinel,
type ExperimentalWorkflowToolDefinition,
type ExperimentalWorkflowToolInput,
@@ -12,6 +13,11 @@ export {
experimental_workflow,
isDisabledToolSentinel,
isExperimentalWorkflowToolDefinition,
+ type TaskBinding,
+ type TaskDelegated,
+ type TaskExec,
+ type TaskExecutorBinding,
+ type TaskReceipt,
type ToolAuthOptions,
type ToolAuthProvider,
type ToolDefinition,
diff --git a/packages/eve/src/runtime/session-callback-route.test.ts b/packages/eve/src/runtime/session-callback-route.test.ts
index da9a15167..c2150b515 100644
--- a/packages/eve/src/runtime/session-callback-route.test.ts
+++ b/packages/eve/src/runtime/session-callback-route.test.ts
@@ -123,8 +123,8 @@ describe("session callback route", () => {
new Request(`https://app.example.com/eve/v1/callback/${TASK_TOKEN}`, {
body: JSON.stringify({
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
kind: "task.update",
message: "Found three matching records.",
taskId: TASK_ID,
@@ -137,8 +137,8 @@ describe("session callback route", () => {
expect(response.status).toBe(202);
expect(resumeHookMock).toHaveBeenCalledWith(TASK_TOKEN, {
callId: "update-call",
- childStepIndex: 2,
- childTurnId: "turn-child",
+ updateIndex: 2,
+ updateEpoch: "turn-child",
kind: "task-update",
message: "Found three matching records.",
});
diff --git a/packages/eve/src/runtime/session-callback-route.ts b/packages/eve/src/runtime/session-callback-route.ts
index e140dd142..a73135362 100644
--- a/packages/eve/src/runtime/session-callback-route.ts
+++ b/packages/eve/src/runtime/session-callback-route.ts
@@ -120,11 +120,11 @@ const taskTurnStartedCallbackSchema = z.object({
const taskUpdateCallbackSchema = z.object({
callId: z.string().min(1),
- childStepIndex: eventCoordinateSchema,
- childTurnId: z.string().min(1),
kind: z.literal("task.update"),
message: z.string().min(1),
taskId: z.string().min(1),
+ updateEpoch: z.string().min(1),
+ updateIndex: eventCoordinateSchema,
});
/**
@@ -330,10 +330,10 @@ function projectTaskUpdate(
if (tokenRejection !== undefined) return tokenRejection;
return {
callId: parsed.data.callId,
- childStepIndex: parsed.data.childStepIndex,
- childTurnId: parsed.data.childTurnId,
kind: "task-update",
message: parsed.data.message,
+ updateEpoch: parsed.data.updateEpoch,
+ updateIndex: parsed.data.updateIndex,
};
}
diff --git a/packages/eve/src/shared/empty-delivery.test.ts b/packages/eve/src/shared/empty-delivery.test.ts
index 075ea09c7..b8b4c78d1 100644
--- a/packages/eve/src/shared/empty-delivery.test.ts
+++ b/packages/eve/src/shared/empty-delivery.test.ts
@@ -7,6 +7,10 @@ describe("hasEmptyDeliverySentinel", () => {
expect(hasEmptyDeliverySentinel(EMPTY_DELIVERY_SENTINEL)).toBe(true);
});
+ it("recognizes an HTML-escaped sentinel", () => {
+ expect(hasEmptyDeliverySentinel("&lt;eve-empty-delivery/&gt;")).toBe(true);
+ });
+
it("recognizes the sentinel anywhere in the response", () => {
expect(hasEmptyDeliverySentinel(`before ${EMPTY_DELIVERY_SENTINEL} after`)).toBe(true);
});
diff --git a/packages/eve/src/shared/empty-delivery.ts b/packages/eve/src/shared/empty-delivery.ts
index 687c3e00a..95100b561 100644
--- a/packages/eve/src/shared/empty-delivery.ts
+++ b/packages/eve/src/shared/empty-delivery.ts
@@ -1,7 +1,11 @@
export const EMPTY_DELIVERY_SENTINEL = "<eve-empty-delivery/>";
+const HTML_ESCAPED_EMPTY_DELIVERY_SENTINEL = "&lt;eve-empty-delivery/&gt;";
export const CONDITIONAL_DELIVERY_INSTRUCTION = `Conditional delivery\nOnly when the current task explicitly makes delivery conditional and there is nothing new to report, reply with exactly ${EMPTY_DELIVERY_SENTINEL} and no other text. This includes results already delivered or incorporated into an earlier response; do not send an acknowledgement of that redundancy. Do not use this marker for ordinary conversations, after input or approval responses, or to omit commentary from a response that still needs delivery. Never return an empty response; use the marker to intentionally deliver nothing.`;
export function hasEmptyDeliverySentinel(text: string | null | undefined): boolean {
- return text?.includes(EMPTY_DELIVERY_SENTINEL) ?? false;
+ return (
+ text?.includes(EMPTY_DELIVERY_SENTINEL) === true ||
+ text?.includes(HTML_ESCAPED_EMPTY_DELIVERY_SENTINEL) === true
+ );
}
diff --git a/packages/eve/src/shared/tool-task.ts b/packages/eve/src/shared/tool-task.ts
index a8fa3c368..edfd558c3 100644
--- a/packages/eve/src/shared/tool-task.ts
+++ b/packages/eve/src/shared/tool-task.ts
@@ -45,11 +45,15 @@ export interface TaskDelegated<TData extends JsonObject = JsonObject> {
}
/**
- * Terminal commands an in-process executor may report to its task via
+ * Commands an in-process executor may report to its task via
* {@link TaskExec.send}. Deliberately narrower than the task run's full
* command surface — bind, ready, and input routing stay runtime-owned.
*/
export type TaskSendCommand =
+ | {
+ readonly kind: "update";
+ readonly message: string;
+ }
| { readonly kind: "complete"; readonly data: JsonValue }
| { readonly kind: "fail"; readonly data: JsonValue }
| { readonly kind: "cancel" };
@@ -75,8 +79,8 @@ export interface TaskExec {
*/
readonly session: HarnessSession;
/**
- * Delivers a terminal command to this task's inbox from the same process,
- * for executors that outlive `execute` in-memory (e.g. a callback firing
+ * Delivers progress or a terminal command to this task's inbox from the same
+ * process, for executors that outlive `execute` in-memory (e.g. a callback firing
* after delegation). Call it only after `execute` returned `delegated(...)`
* — the runtime settles non-delegated returns itself, and a second terminal
* command is refused. Not restart-safe: an in-process callback dies with
diff --git a/packages/eve/src/tasks/delivery-context.test.ts b/packages/eve/src/tasks/delivery-context.test.ts
new file mode 100644
index 000000000..13299053a
--- /dev/null
+++ b/packages/eve/src/tasks/delivery-context.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+
+import type { SessionStateMap } from "#harness/types.js";
+import { EMPTY_DELIVERY_SENTINEL } from "#shared/empty-delivery.js";
+import {
+ resolveTaskDeliveryContext,
+ TASK_DELIVERY_CONTEXT_LABEL,
+ TASK_DELIVERY_PENDING_INSTRUCTION,
+ TASK_DELIVERY_SETTLED_INSTRUCTION,
+} from "#tasks/delivery-context.js";
+import { SESSION_TASKS_STATE_KEY } from "#tasks/session-index.js";
+import type { TaskView } from "#tasks/types.js";
+
+const metadata = { kind: "report-probe", name: "report_probe" } as const;
+
+describe("task delivery instructions", () => {
+ it("pending instruction unconditionally requires the sentinel", () => {
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(TASK_DELIVERY_CONTEXT_LABEL);
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain("runtime-authored");
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain("still pending");
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(
+ "overrides any earlier instruction to report, summarize, acknowledge",
+ );
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(
+ "may call tools only if the newly delivered task result requires immediate action",
+ );
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(
+ "Do not provide progress, status, an acknowledgement, or a waiting message",
+ );
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(
+ `entire final text response must be exactly ${EMPTY_DELIVERY_SENTINEL} and no other text`,
+ );
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(
+ 'Incorrect: "Two of three tasks have completed."',
+ );
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).toContain(`Correct: ${EMPTY_DELIVERY_SENTINEL}`);
+ expect(TASK_DELIVERY_PENDING_INSTRUCTION).not.toContain("If any task");
+ });
+
+ it("settled instruction unconditionally forbids the sentinel and requires one combined response", () => {
+ expect(TASK_DELIVERY_SETTLED_INSTRUCTION).toContain(TASK_DELIVERY_CONTEXT_LABEL);
+ expect(TASK_DELIVERY_SETTLED_INSTRUCTION).toContain("runtime-authored");
+ expect(TASK_DELIVERY_SETTLED_INSTRUCTION).toContain("terminal output");
+ expect(TASK_DELIVERY_SETTLED_INSTRUCTION).toContain(
+ `Do not reply with ${EMPTY_DELIVERY_SENTINEL}`,
+ );
+ expect(TASK_DELIVERY_SETTLED_INSTRUCTION).toContain("one user-facing response");
+ expect(TASK_DELIVERY_SETTLED_INSTRUCTION).not.toContain("When no task");
+ });
+});
+
+describe("resolveTaskDeliveryContext", () => {
+ it("projects terminal and pending siblings from the delivered task's parent turn", () => {
+ const completed = {
+ lastOutput: { data: { result: "first" }, type: "result" },
+ metadata,
+ status: "completed",
+ taskId: "task_1",
+ } satisfies TaskView;
+ const state = taskState([
+ taskEntry("task_1", "turn_1", completed),
+ taskEntry("task_2", "turn_1"),
+ taskEntry("task_3", "turn_2"),
+ ]);
+
+ expect(resolveTaskDeliveryContext({ state, taskDeliveryId: "task_1:ready:completed" })).toEqual(
+ {
+ context:
+ '[Task state]\n{"tasks":[{"name":"report_probe","status":"completed","taskId":"task_1"},{"name":"report_probe","status":"pending","taskId":"task_2"}]}',
+ phase: "pending",
+ },
+ );
+ });
+
+ it("includes every output once the parent has received the whole terminal cohort", () => {
+ const first = {
+ lastOutput: { data: { result: "first" }, type: "result" },
+ metadata,
+ status: "completed",
+ taskId: "task_1",
+ } satisfies TaskView;
+ const second = {
+ lastOutput: { data: { result: "second" }, type: "result" },
+ metadata,
+ status: "completed",
+ taskId: "task_2",
+ } satisfies TaskView;
+
+ expect(
+ resolveTaskDeliveryContext({
+ state: taskState([
+ taskEntry("task_1", "turn_1", first),
+ taskEntry("task_2", "turn_1", second),
+ ]),
+ taskDeliveryId: "task_2:ready:completed",
+ }),
+ ).toEqual({
+ context:
+ '[Task state]\n{"tasks":[{"name":"report_probe","output":{"data":{"result":"first"},"type":"result"},"status":"completed","taskId":"task_1"},{"name":"report_probe","output":{"data":{"result":"second"},"type":"result"},"status":"completed","taskId":"task_2"}]}',
+ phase: "settled",
+ });
+ });
+
+ it("returns no context when the delivery is not owned by the session task index", () => {
+ expect(
+ resolveTaskDeliveryContext({
+ state: taskState([taskEntry("task_1", "turn_1")]),
+ taskDeliveryId: "task_unknown:ready:completed",
+ }),
+ ).toBeUndefined();
+ });
+});
+
+function taskEntry(taskId: string, createdByTurnId: string, terminalView?: TaskView) {
+ return {
+ createdByTurnId,
+ metadata,
+ taskId,
+ taskInboxToken: `inbox-${taskId}`,
+ taskRunId: `run-${taskId}`,
+ terminalView,
+ };
+}
+
+function taskState(tasks: readonly ReturnType<typeof taskEntry>[]): SessionStateMap {
+ return { [SESSION_TASKS_STATE_KEY]: { tasks } } as SessionStateMap;
+}
diff --git a/packages/eve/src/tasks/delivery-context.ts b/packages/eve/src/tasks/delivery-context.ts
new file mode 100644
index 000000000..a1bcc8319
--- /dev/null
+++ b/packages/eve/src/tasks/delivery-context.ts
@@ -0,0 +1,49 @@
+import type { SessionStateMap } from "#harness/types.js";
+import { EMPTY_DELIVERY_SENTINEL } from "#shared/empty-delivery.js";
+import { getSessionTaskIndex } from "#tasks/session-index.js";
+
+export const TASK_DELIVERY_CONTEXT_LABEL = "[Task state]";
+
+export const TASK_DELIVERY_PENDING_INSTRUCTION = `Background task control: incomplete cohort
+This framework-authored instruction overrides any earlier instruction to report, summarize, acknowledge, or otherwise handle background results.
+
+The accompanying ${TASK_DELIVERY_CONTEXT_LABEL} message is runtime-authored and lists tasks started by the same parent turn. At least one of those tasks is still pending, so the combined report is not ready.
+
+Action:
+- You may call tools only if the newly delivered task result requires immediate action.
+- Otherwise, take no action.
+
+Delivery:
+- Do not report completed tasks or partial results.
+- Do not provide progress, status, an acknowledgement, or a waiting message.
+- After any necessary tool calls, your entire final text response must be exactly ${EMPTY_DELIVERY_SENTINEL} and no other text.
+
+Incorrect: "Two of three tasks have completed."
+Incorrect: "Still waiting for the remaining task."
+Correct: ${EMPTY_DELIVERY_SENTINEL}`;
+
+export const TASK_DELIVERY_SETTLED_INSTRUCTION = `Background task reporting\nThis turn was triggered by background task activity. The accompanying ${TASK_DELIVERY_CONTEXT_LABEL} message is runtime-authored and lists tasks started by the same parent turn, all settled, with every available terminal output. Do not reply with ${EMPTY_DELIVERY_SENTINEL}. Send one user-facing response that combines their useful results.`;
+
+/** Returns model context and cohort phase for tasks started by the same parent turn as this delivery. */
+export function resolveTaskDeliveryContext(input: {
+ readonly state: SessionStateMap | undefined;
+ readonly taskDeliveryId: string;
+}): { readonly context: string; readonly phase: "pending" | "settled" } | undefined {
+ const entries = getSessionTaskIndex(input.state);
+ const delivered = entries.find((entry) => input.taskDeliveryId.startsWith(`${entry.taskId}:`));
+ if (delivered === undefined) return undefined;
+
+ const cohort = entries.filter((entry) => entry.createdByTurnId === delivered.createdByTurnId);
+ const settled = cohort.every((entry) => entry.terminalView !== undefined);
+ const tasks = cohort.map((entry) => ({
+ name: entry.metadata.name,
+ output: settled ? entry.terminalView?.lastOutput : undefined,
+ status: entry.terminalView?.status ?? "pending",
+ taskId: entry.taskId,
+ }));
+
+ return {
+ context: `${TASK_DELIVERY_CONTEXT_LABEL}\n${JSON.stringify({ tasks })}`,
+ phase: settled ? "settled" : "pending",
+ };
+}
diff --git a/packages/eve/src/tasks/types.ts b/packages/eve/src/tasks/types.ts
index 23aa54fe3..ab9f2004d 100644
--- a/packages/eve/src/tasks/types.ts
+++ b/packages/eve/src/tasks/types.ts
@@ -419,8 +419,10 @@ export interface TaskInboundTurnStarted {
/** Intermediate progress sent by a running child to its parent agent. */
export interface TaskInboundUpdate {
readonly callId: string;
- readonly childStepIndex: number;
- readonly childTurnId: string;
+ /** Executor-neutral monotonic index within {@link updateEpoch}. */
+ readonly updateIndex: number;
+ /** Executor-neutral epoch id used with {@link updateIndex} for update dedupe. */
+ readonly updateEpoch: string;
readonly kind: "task-update";
readonly message: string;
}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1a9544483..426b80751 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -566,6 +566,28 @@ importers:
specifier: 'catalog:'
+ e2e/fixtures/agent-background-tools:
+ dependencies:
+ '@eve-e2e/config':
+ specifier: workspace:*
+ version: link:../e2e-config
+ '@workflow/world-postgres':
+ specifier: 'catalog:'
+ eve:
+ specifier: workspace:*
+ version: link:../../../packages/eve
+ zod:
+ specifier: 'catalog:'
+ version: 4.4.3
+ devDependencies:
+ '@types/node':
+ specifier: 'catalog:'
+ version: 25.9.1
+ typescript:
+ specifier: 'catalog:'
+ version: 7.0.2
+
e2e/fixtures/agent-basic-runtime:
dependencies:
'@eve-e2e/config':
@@ -868,6 +890,28 @@ importers:
specifier: 'catalog:'
version: 7.0.2
+ e2e/fixtures/agent-task-reporting:
+ dependencies:
+ '@eve-e2e/config':
+ specifier: workspace:*
+ version: link:../e2e-config
+ '@workflow/world-postgres':
+ specifier: 'catalog:'
+ eve:
+ specifier: workspace:*
+ version: link:../../../packages/eve
+ zod:
+ specifier: 'catalog:'
+ version: 4.4.3
+ devDependencies:
+ '@types/node':
+ specifier: 'catalog:'
+ version: 25.9.1
+ typescript:
+ specifier: 'catalog:'
+ version: 7.0.2
+
e2e/fixtures/agent-tools:
dependencies:
'@eve-e2e/config':