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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdxindex 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 atThis contract currently supports framework-owned task executors, including local and remotesubagents 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` parameterdiff --git a/e2e/fixtures/agent-background-tools/agent/agent.ts b/e2e/fixtures/agent-background-tools/agent/agent.tsnew file mode 100644index 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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/durablimport 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<DurableStepResulet 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<DurableStepResuresolved = { 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.tsindex 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.tsindex 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.tsindex 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", "<eve-empty-delivery/>"],+ ])(+ "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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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("<eve-empty-delivery/>")).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.tsindex 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 = "<eve-empty-delivery/>";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.tsindex 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 withdiff --git a/packages/eve/src/tasks/delivery-context.test.ts b/packages/eve/src/tasks/delivery-context.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.yamlindex 1a9544483..426b80751 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -566,6 +566,28 @@ importers:specifier: 'catalog:'version: 4.1.10(@edge-runtime/[email protected])(@opentelemetry/[email protected])(@types/[email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))+ e2e/fixtures/agent-background-tools:+ dependencies:+ '@eve-e2e/config':+ specifier: workspace:*+ version: link:../e2e-config+ '@workflow/world-postgres':+ specifier: 'catalog:'+ version: 5.0.0-beta.35(@opentelemetry/[email protected])(@types/[email protected])(@upstash/[email protected])([email protected])([email protected])([email protected])+ 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:'+ version: 5.0.0-beta.35(@opentelemetry/[email protected])(@types/[email protected])(@upstash/[email protected])([email protected])([email protected])([email protected])+ 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':