Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): supply background task reporting state (#2406)

vercel-gh-bot-3[bot]923921c05692
diff --git a/.changeset/steady-background-reports.md b/.changeset/steady-background-reports.md
new file mode 100644
index 000000000..2592cf86e
--- /dev/null
+++ b/.changeset/steady-background-reports.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Give models runtime-authored task state after background work starts so initiating turns acknowledge launch, partial task wakes stay silent, and settled cohorts produce one combined report.
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
index f8a9ed831..349fe39e5 100644
--- a/docs/tools/overview.mdx
+++ b/docs/tools/overview.mdx
@@ -70,10 +70,11 @@ progress with `task.send({ kind: "update", message })` and the terminal result w
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.
+After the initiating turn accepts background tasks, eve supplies runtime-authored state for that
+cohort and instructs the model to acknowledge that the work started without waiting for results.
+Later task-triggered parent turns receive fresh state for the same cohort. The model is instructed
+to keep related intermediate results silent while any task remains pending. 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-task-reporting/agent/agent.ts b/e2e/fixtures/agent-task-reporting/agent/agent.ts
index e44efea13..ce44dbb17 100644
--- a/e2e/fixtures/agent-task-reporting/agent/agent.ts
+++ b/e2e/fixtures/agent-task-reporting/agent/agent.ts
@@ -1,91 +1,12 @@
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 });
+const base = e2eAgentConfig();
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
index 2b71b769f..bce87b044 100644
--- a/e2e/fixtures/agent-task-reporting/agent/instructions.md
+++ b/e2e/fixtures/agent-task-reporting/agent/instructions.md
@@ -1,3 +1,3 @@
-# Task reporting fixture
+# Identity
-Follow the user's request exactly. When asked to start background probes, use `report_probe`.
+You are a helpful assistant.
diff --git a/e2e/fixtures/agent-task-reporting/agent/sandbox.ts b/e2e/fixtures/agent-task-reporting/agent/sandbox.ts
new file mode 100644
index 000000000..319677b16
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/agent/sandbox.ts
@@ -0,0 +1,10 @@
+import { defineSandbox } from "eve/sandbox";
+import { justbash } from "eve/sandbox/just-bash";
+
+// This eval exercises background-task delivery, not shell or filesystem behavior.
+// Keep external sandbox provisioning out of the experiment.
+export default defineSandbox({
+ backend: justbash({
+ filesystem: ({ justBash }) => new justBash.InMemoryFs(),
+ }),
+});
diff --git a/e2e/fixtures/agent-task-reporting/agent/tools/probe.ts b/e2e/fixtures/agent-task-reporting/agent/tools/probe.ts
new file mode 100644
index 000000000..18e5c0a71
--- /dev/null
+++ b/e2e/fixtures/agent-task-reporting/agent/tools/probe.ts
@@ -0,0 +1,20 @@
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+const PROBES = {
+ first: { delayMs: 10_000, result: "WAKE-MECHANISM" },
+ second: { delayMs: 40_000, result: "CHANNEL-DELIVERY" },
+ third: { delayMs: 70_000, result: "REPORTING-POLICY" },
+} as const;
+
+export default defineTool({
+ description: "Complete one requested reporting probe after its configured delay.",
+ inputSchema: z.strictObject({
+ check: z.enum(["first", "second", "third"]),
+ }),
+ async execute({ check }) {
+ const probe = PROBES[check];
+ await new Promise((resolve) => setTimeout(resolve, probe.delayMs));
+ return { result: probe.result };
+ },
+});
diff --git a/e2e/fixtures/agent-task-reporting/agent/tools/report_probe.ts b/e2e/fixtures/agent-task-reporting/agent/tools/report_probe.ts
deleted file mode 100644
index 5eb6963b0..000000000
--- a/e2e/fixtures/agent-task-reporting/agent/tools/report_probe.ts
+++ /dev/null
@@ -1,30 +0,0 @@
-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
index 38bba8400..733bb6c1b 100644
--- a/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
+++ b/e2e/fixtures/agent-task-reporting/evals/consolidated-report.eval.ts
@@ -8,25 +8,35 @@ const COMPLETION = /Background task (task_[a-z0-9]+) \([^)]+\) is completed\./gi
function reportingEval() {
return defineEval({
description:
- "Related background results produce no intermediate delivery and one consolidated final report.",
+ "A stock Eve agent acknowledges accepted background work, keeps partial wakes silent, and reports once after settlement.",
+ tags: ["real-model"],
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
+ const started =
+ await t.send(`Please investigate these three independent checks using the built-in agent tool. Start them sequentially within this same turn: issue at most one agent call per model step, then use the next model step after its working receipt to issue the next call. Do not wait for a completed result before starting the next agent, and do not call other tools yourself.
-After the three task receipts, reply only with "investigation started". Then handle the background results normally.`);
+1. "Call probe exactly once with check=first. After it returns, reply with exactly the result value from the tool."
+2. "Call probe exactly once with check=second. After it returns, reply with exactly the result value from the tool."
+3. "Call probe exactly once with check=third. After it returns, reply with exactly the result value from the tool."`);
started.expectOk();
- started.calledTool("report_probe", { count: TASK_COUNT });
- started.messageIncludes("investigation started");
+ started.calledSubagent("agent", { count: TASK_COUNT });
+ await t.require(
+ started,
+ satisfies(
+ (turn: EveEvalTurn) => hasPostReceiptAcknowledgement(turn),
+ "one non-empty acknowledgement follows all background task receipts",
+ ),
+ );
+ await t.require(
+ started.message,
+ satisfies(
+ (message: unknown) =>
+ typeof message === "string" &&
+ message.trim().length > 0 &&
+ RESULTS.every((result) => !message.includes(result)),
+ "the initiating turn acknowledges work without claiming results",
+ ),
+ );
const taskIds = backgroundTaskIds(started);
await t.require(
taskIds,
@@ -114,19 +124,33 @@ After the three task receipts, reply only with "investigation started". Then han
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] : [];
- });
+ return turn.events.flatMap((event) =>
+ event.type === "subagent.completed" &&
+ event.data.subagentName === "agent" &&
+ event.data.backgroundTask !== undefined
+ ? [event.data.backgroundTask.taskId]
+ : [],
+ );
+}
+
+function hasPostReceiptAcknowledgement(turn: EveEvalTurn): boolean {
+ const receiptIndexes = turn.events.flatMap((event, index) =>
+ event.type === "subagent.completed" &&
+ event.data.subagentName === "agent" &&
+ event.data.backgroundTask !== undefined
+ ? [index]
+ : [],
+ );
+ if (receiptIndexes.length !== TASK_COUNT) return false;
+ const lastReceiptIndex = Math.max(...receiptIndexes);
+ return turn.events.some(
+ (event, index) =>
+ index > lastReceiptIndex &&
+ event.type === "message.completed" &&
+ event.data.finishReason !== "tool-calls" &&
+ event.data.message !== null &&
+ event.data.message.trim().length > 0,
+ );
}
function completedTaskIds(turn: EveEvalTurn): readonly string[] {
diff --git a/e2e/fixtures/agent-task-reporting/package.json b/e2e/fixtures/agent-task-reporting/package.json
index 392564d39..b42d86d14 100644
--- a/e2e/fixtures/agent-task-reporting/package.json
+++ b/e2e/fixtures/agent-task-reporting/package.json
@@ -14,6 +14,7 @@
"@eve-e2e/config": "workspace:*",
"@workflow/world-postgres": "catalog:",
"eve": "workspace:*",
+ "just-bash": "3.1.0",
"zod": "catalog:"
},
"devDependencies": {
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index e44d05c39..f1d31ea0a 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -71,10 +71,12 @@ 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");
-/** Task-cohort phase when the active turn began from a task-addressed durable delivery. */
-export const TurnTaskDeliveryKey = new ContextKey<"none" | "pending" | "settled">(
+/** Task-reporting phase for the active root turn. */
+export const TurnTaskDeliveryKey = new ContextKey<"none" | "initiating" | "pending" | "settled">(
"eve.turnTaskDelivery",
);
+/** Framework-authored task state supplied to the model without altering user-message history. */
+export const TurnTaskStateKey = new ContextKey<string>("eve.turnTaskState");
export interface ActiveChannelDelivery {
readonly agentName?: string;
readonly delivery: InstrumentationChannelDeliveryRef;
diff --git a/packages/eve/src/execution/pending-turn-state.ts b/packages/eve/src/execution/pending-turn-state.ts
new file mode 100644
index 000000000..6c2a4d02b
--- /dev/null
+++ b/packages/eve/src/execution/pending-turn-state.ts
@@ -0,0 +1,30 @@
+import { getPendingAuthorization } from "#harness/authorization.js";
+import { hasPendingInputBatch } from "#harness/input-requests.js";
+import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
+import type { HarnessSession } from "#harness/types.js";
+import { getRuntimeActionRequestKey } from "#runtime/actions/keys.js";
+
+/** Derives the workflow fields used to select the next action at the park boundary. */
+export function derivePendingState(session: HarnessSession): {
+ readonly authorizationAttemptIds?: readonly string[];
+ readonly authorizationNames?: readonly string[];
+ readonly hasPendingAuthorization: boolean;
+ readonly hasPendingInputBatch: boolean;
+ readonly pendingRuntimeActionKeys?: readonly string[];
+} {
+ const batch = getPendingRuntimeActionBatch(session.state);
+ const pendingAuth = getPendingAuthorization(session.state);
+ const base = {
+ authorizationAttemptIds: pendingAuth?.challenges.flatMap((challenge) =>
+ challenge.attemptId === undefined ? [] : [challenge.attemptId],
+ ),
+ authorizationNames: pendingAuth?.challenges.map((challenge) => challenge.name),
+ hasPendingAuthorization: pendingAuth !== undefined,
+ hasPendingInputBatch: hasPendingInputBatch(session.state),
+ };
+ if (batch === undefined) return base;
+ return {
+ ...base,
+ pendingRuntimeActionKeys: batch.actions.map((action) => getRuntimeActionRequestKey(action)),
+ };
+}
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index e516e9ee6..52db413b9 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -22,6 +22,7 @@ import {
SessionDynamicToolRuntimeRevisionKey,
SessionIdKey,
TurnTaskDeliveryKey,
+ TurnTaskStateKey,
} from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { serializeContext } from "#context/serialize.js";
@@ -2307,6 +2308,7 @@ describe("turnStep", () => {
it("sets task-delivery provenance only when the runtime supplies owned task state", async () => {
const observedTaskDeliveries: unknown[] = [];
+ const observedTaskStates: unknown[] = [];
const metadata = { kind: "report-probe", name: "report_probe" } as const;
const session = createStubSession({
state: {
@@ -2333,10 +2335,14 @@ describe("turnStep", () => {
vi.mocked(createExecutionNodeStep).mockImplementation(() => {
return async (stepSession): Promise<StepResult> => {
observedTaskDeliveries.push(contextStorage.getStore()?.get(TurnTaskDeliveryKey));
+ observedTaskStates.push(contextStorage.getStore()?.get(TurnTaskStateKey));
return { next: { done: true, output: "ok" }, session: stepSession };
};
});
+ const initialSerializedContext = createSerializedContext();
+ initialSerializedContext[TurnTaskStateKey.name] = "stale task state";
+
const first = await turnStep({
input: {
kind: "deliver",
@@ -2344,7 +2350,7 @@ describe("turnStep", () => {
taskDeliveryId: "task_1:ready:completed",
},
parentWritable: createTestWritable(),
- serializedContext: createSerializedContext(),
+ serializedContext: initialSerializedContext,
sessionState: createStubSessionState(),
});
const second = await turnStep({
@@ -2365,6 +2371,89 @@ describe("turnStep", () => {
});
expect(observedTaskDeliveries).toEqual(["settled", "none", "none"]);
+ expect(observedTaskStates).toEqual([undefined, undefined, undefined]);
+ });
+
+ it("supplies initiating task state after the active turn accepts delegated work", async () => {
+ const tasksBundle = {
+ adapterRegistry: {
+ adaptersByKind: new Map([[threadContextAdapter.kind, threadContextAdapter]]),
+ },
+ compiledArtifactsSource: {} as never,
+ graph: {
+ nodesByNodeId: new Map(),
+ root: {
+ sandboxRegistry: { sandbox: null },
+ turnAgent: TestTurnAgent,
+ },
+ },
+ moduleMap: { nodes: {} },
+ hookRegistry: createEmptyHookRegistry(),
+ resolvedAgent: { config: { experimental: { tasks: true } } },
+ subagentRegistry: {},
+ toolRegistry: {},
+ turnAgent: TestTurnAgent,
+ } as never;
+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(tasksBundle);
+
+ const session = createStubSession({
+ state: {
+ "eve.harness.emission": {
+ sequence: 0,
+ sessionStarted: true,
+ stepIndex: 1,
+ turnId: "turn_0",
+ },
+ "eve.tasks": {
+ tasks: [
+ {
+ createdByStepIndex: 0,
+ createdByTurnId: "turn_0",
+ executor: { data: {}, kind: "subagent" },
+ metadata: { kind: "report-probe", name: "report_probe" },
+ taskId: "task_1",
+ taskInboxToken: "task-token",
+ taskRunId: "run_1",
+ },
+ ],
+ },
+ },
+ });
+ installSessionStoreMocks([session]);
+
+ let observedInput: unknown;
+ let observedPhase: unknown;
+ let observedTaskState: unknown;
+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {
+ return async (stepSession, stepInput): Promise<StepResult> => {
+ observedInput = stepInput;
+ observedPhase = contextStorage.getStore()?.get(TurnTaskDeliveryKey);
+ observedTaskState = contextStorage.getStore()?.get(TurnTaskStateKey);
+ return { next: { done: true, output: "ok" }, session: stepSession };
+ };
+ });
+ const serializedContext = createSerializedContext();
+ serializedContext[TurnTaskDeliveryKey.name] = "none";
+
+ await turnStep({
+ input: undefined,
+ parentWritable: createTestWritable(),
+ serializedContext,
+ sessionState: createStubSessionState({
+ emissionState: {
+ sequence: 0,
+ sessionStarted: true,
+ stepIndex: 1,
+ turnId: "turn_0",
+ },
+ }),
+ });
+
+ expect(observedPhase).toBe("initiating");
+ expect(observedTaskState).toBe(
+ '[Task state]\n{"tasks":[{"name":"report_probe","status":"pending","taskId":"task_1"}]}',
+ );
+ expect(observedInput).toBeUndefined();
});
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 94a68bfdc..91a766ef4 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -28,6 +28,7 @@ import {
SessionDynamicToolRuntimeRevisionKey,
TasksEnabledKey,
TurnTaskDeliveryKey,
+ TurnTaskStateKey,
} from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { deserializeContext, serializeContext } from "#context/serialize.js";
@@ -57,11 +58,10 @@ import {
isWorkflowRuntimeActionInterrupt,
} from "#harness/workflow-runtime-action-state.js";
import { getPendingWorkflowInterrupt } from "#harness/workflow-interrupt-state.js";
-import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";
import { getTurnUsageState, takeSessionUsageDelta, toUsage } from "#harness/turn-tag-state.js";
import type { DurableStepResult } from "#execution/next-driver-action.js";
-import { getRuntimeActionRequestKey } from "#runtime/actions/keys.js";
+import { derivePendingState } from "#execution/pending-turn-state.js";
import {
createAuthorizationCompletedEvent,
createSessionStartedEvent,
@@ -83,7 +83,10 @@ 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 {
+ resolveInitiatingTaskContext,
+ resolveTaskDeliveryContext,
+} from "#tasks/delivery-context.js";
import {
readRetainedBackgroundToolResult,
runBackgroundStep,
@@ -120,6 +123,7 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
const ctx = await deserializeContext(input.serializedContext);
if (rawInput.input?.kind === "deliver") {
ctx.set(TurnTaskDeliveryKey, "none");
+ ctx.delete(TurnTaskStateKey);
}
const adapter = ctx.require(ChannelKey);
const bundle = ctx.require(BundleKey);
@@ -269,6 +273,17 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
}
}
+ if (tasksEnabled && ctx.get(TurnTaskDeliveryKey) === "none") {
+ const taskContext = resolveInitiatingTaskContext({
+ state: durableSession.state,
+ turnId: activeTurnId(initialEmissionState),
+ });
+ if (taskContext !== undefined) {
+ ctx.set(TurnTaskDeliveryKey, taskContext.phase);
+ ctx.set(TurnTaskStateKey, taskContext.context);
+ }
+ }
+
// Persist adapter-state mutations across the step boundary.
if (input.input?.kind === "deliver") {
const updatedAdapter = { ...adapter, state: { ...adapterCtx.state } };
@@ -663,33 +678,3 @@ async function preserveCancelledTurnMessage(
const content = await stageAttachmentsToSandbox(message);
return { ...session, history: [...session.history, { content, role: "user" }] };
}
-
-/**
- * Derives the pending-state fields the turn workflow needs to choose
- * the right `NextDriverAction` arm at the park boundary.
- */
-function derivePendingState(session: HarnessSession): {
- readonly authorizationAttemptIds?: readonly string[];
- readonly authorizationNames?: readonly string[];
- readonly hasPendingAuthorization: boolean;
- readonly hasPendingInputBatch: boolean;
- readonly pendingRuntimeActionKeys?: readonly string[];
-} {
- const batch = getPendingRuntimeActionBatch(session.state);
- const pendingAuth = getPendingAuthorization(session.state);
- const base = {
- authorizationAttemptIds: pendingAuth?.challenges.flatMap((challenge) =>
- challenge.attemptId === undefined ? [] : [challenge.attemptId],
- ),
- authorizationNames: pendingAuth?.challenges.map((c) => c.name),
- hasPendingAuthorization: pendingAuth !== undefined,
- hasPendingInputBatch: hasPendingInputBatch(session.state),
- };
- if (batch !== undefined) {
- return {
- ...base,
- pendingRuntimeActionKeys: batch.actions.map((action) => getRuntimeActionRequestKey(action)),
- };
- }
- return base;
-}
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 9c7144a89..8963d9955 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -28,6 +28,7 @@ import {
SessionDynamicSubagentSelectionsKey,
StepDynamicToolMetadataKey,
TurnTaskDeliveryKey,
+ TurnTaskStateKey,
} from "#context/keys.js";
import { SCHEDULE_APP_AUTH } from "#channel/schedule-auth.js";
import { decodeSandboxRef, isSandboxRefUrl } from "#internal/attachments/sandbox-refs.js";
@@ -73,6 +74,7 @@ import {
EMPTY_DELIVERY_SENTINEL,
} from "#shared/empty-delivery.js";
import {
+ TASK_DELIVERY_INITIATING_INSTRUCTION,
TASK_DELIVERY_PENDING_INSTRUCTION,
TASK_DELIVERY_SETTLED_INSTRUCTION,
} from "#tasks/delivery-context.js";
@@ -5193,6 +5195,36 @@ describe("createToolLoopHarness", () => {
}
});
+ it("does not offer silent delivery on an initiating-task retry", async () => {
+ setupFirstThenAgent(emptyResult, successResult);
+ const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+ const { emit } = createEventCollector();
+ const runStep = createToolLoopHarness(createTestConfig("conversation", emit));
+ const ctx = new ContextContainer();
+ ctx.set(TurnTaskDeliveryKey, "initiating");
+
+ try {
+ await contextStorage.run(ctx, () =>
+ runStep(createTestSession(), { message: "[Task state]" }),
+ );
+
+ const reissueAgent = vi.mocked(ToolLoopAgent).mock.results[1]?.value as {
+ stream: ReturnType<typeof vi.fn>;
+ };
+ const reissueMessages = reissueAgent.stream.mock.calls[0]?.[0]?.messages as Array<{
+ content: unknown;
+ role: string;
+ }>;
+ expect(reissueMessages.at(-1)).toMatchObject({
+ content: expect.stringContaining("was not delivered"),
+ role: "user",
+ });
+ expect(reissueMessages.at(-1)?.content).not.toContain(EMPTY_DELIVERY_SENTINEL);
+ } finally {
+ warnSpy.mockRestore();
+ }
+ });
+
it("does not offer conditional delivery on a scheduled retry with an output schema", async () => {
setupFirstThenAgent(emptyResult, finalOutputResult("Done.", { status: "ok" }));
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
@@ -11372,6 +11404,41 @@ describe("createToolLoopHarness", () => {
expect(instructions).toBe("You are a test assistant.");
});
+ it("adds initiating task-reporting guidance without enabling silent delivery", async () => {
+ setupMockAgent(defaultModelResult());
+ const runStep = createToolLoopHarness(createTestConfig("conversation"));
+ const ctx = new ContextContainer();
+ ctx.set(TurnTaskDeliveryKey, "initiating");
+ ctx.set(TurnTaskStateKey, '[Task state]\n{"tasks":[]}');
+
+ await contextStorage.run(ctx, () =>
+ runStep(createTestSession(), { message: "Start the background work." }),
+ );
+
+ const { instructions } = getLastAgentSettings();
+ expect(instructions).toEqual({
+ role: "system",
+ content: `You are a test assistant.\n\n[Task state]\n{"tasks":[]}\n\n${TASK_DELIVERY_INITIATING_INSTRUCTION}`,
+ });
+ });
+
+ it("keeps a scheduled initiating task turn conditionally deliverable", async () => {
+ setupMockAgent(defaultModelResult());
+ const runStep = createToolLoopHarness(createTestConfig("conversation"));
+ const ctx = createScheduleContext();
+ ctx.set(TurnTaskDeliveryKey, "initiating");
+
+ await contextStorage.run(ctx, () =>
+ runStep(createTestSession(), { message: "[Task state]" }),
+ );
+
+ const { instructions } = getLastAgentSettings();
+ expect(instructions).toEqual({
+ role: "system",
+ content: `You are a test assistant.\n\n${CONDITIONAL_DELIVERY_INSTRUCTION}`,
+ });
+ });
+
it.each([
["pending", TASK_DELIVERY_PENDING_INSTRUCTION],
["settled", TASK_DELIVERY_SETTLED_INSTRUCTION],
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index a338ee47a..787d68979 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -38,6 +38,7 @@ import {
ParentTraceContextKey,
SessionCallbackKey,
TurnTaskDeliveryKey,
+ TurnTaskStateKey,
} from "#context/keys.js";
import {
buildDynamicInstructionMessages,
@@ -213,6 +214,7 @@ import {
hasEmptyDeliverySentinel,
} from "#shared/empty-delivery.js";
import {
+ TASK_DELIVERY_INITIATING_INSTRUCTION,
TASK_DELIVERY_PENDING_INSTRUCTION,
TASK_DELIVERY_SETTLED_INSTRUCTION,
} from "#tasks/delivery-context.js";
@@ -1301,18 +1303,26 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const approvedTools = getApprovedTools(session);
const taskDeliveryPhase = ctx?.get(TurnTaskDeliveryKey);
- const emptyDeliveryEnabled =
+ const deliveryInstruction =
// A structured-output run must always produce its declared result.
- session.outputSchema === undefined &&
+ session.outputSchema !== undefined ||
// Eligibility requires durable framework provenance from the active context.
- ctx !== undefined &&
+ ctx === undefined ||
// A child must always return its result to its parent, even when framework-triggered.
- ctx.get(ParentSessionKey) === undefined &&
- // 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.
- taskDeliveryPhase === "pending" ||
- taskDeliveryPhase === "settled");
+ ctx.get(ParentSessionKey) !== undefined
+ ? undefined
+ : taskDeliveryPhase === "pending"
+ ? TASK_DELIVERY_PENDING_INSTRUCTION
+ : taskDeliveryPhase === "settled"
+ ? TASK_DELIVERY_SETTLED_INSTRUCTION
+ : // A schedule-initiated root turn may have nothing worth delivering.
+ isScheduleAppAuth(ctx.get(AuthKey))
+ ? CONDITIONAL_DELIVERY_INSTRUCTION
+ : taskDeliveryPhase === "initiating"
+ ? TASK_DELIVERY_INITIATING_INSTRUCTION
+ : undefined;
+ const emptyDeliveryEnabled =
+ deliveryInstruction !== undefined && taskDeliveryPhase !== "initiating";
// --- Execute via ToolLoopAgent ------------------------------------------
@@ -1344,14 +1354,12 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
if (skillAnnouncement !== undefined && skillAnnouncement.length > 0) {
systemMessages.push({ role: "system", content: skillAnnouncement });
}
+ const taskState = ctx.get(TurnTaskStateKey);
+ if (taskState !== undefined) {
+ systemMessages.push({ role: "system", content: taskState });
+ }
}
- if (emptyDeliveryEnabled) {
- const deliveryInstruction =
- taskDeliveryPhase === "pending"
- ? TASK_DELIVERY_PENDING_INSTRUCTION
- : taskDeliveryPhase === "settled"
- ? TASK_DELIVERY_SETTLED_INSTRUCTION
- : CONDITIONAL_DELIVERY_INSTRUCTION;
+ if (deliveryInstruction !== undefined) {
systemMessages.push({
role: "system",
content: deliveryInstruction,
diff --git a/packages/eve/src/tasks/delivery-context.test.ts b/packages/eve/src/tasks/delivery-context.test.ts
index 13299053a..377c98d72 100644
--- a/packages/eve/src/tasks/delivery-context.test.ts
+++ b/packages/eve/src/tasks/delivery-context.test.ts
@@ -3,8 +3,10 @@ import { describe, expect, it } from "vitest";
import type { SessionStateMap } from "#harness/types.js";
import { EMPTY_DELIVERY_SENTINEL } from "#shared/empty-delivery.js";
import {
+ resolveInitiatingTaskContext,
resolveTaskDeliveryContext,
TASK_DELIVERY_CONTEXT_LABEL,
+ TASK_DELIVERY_INITIATING_INSTRUCTION,
TASK_DELIVERY_PENDING_INSTRUCTION,
TASK_DELIVERY_SETTLED_INSTRUCTION,
} from "#tasks/delivery-context.js";
@@ -14,6 +16,22 @@ import type { TaskView } from "#tasks/types.js";
const metadata = { kind: "report-probe", name: "report_probe" } as const;
describe("task delivery instructions", () => {
+ it("initiating instruction requires one launch acknowledgement", () => {
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).toContain(TASK_DELIVERY_CONTEXT_LABEL);
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).toContain("runtime-authored");
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).toContain(
+ "continue independently after this turn",
+ );
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).toContain(
+ "including starting any remaining background work",
+ );
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).toContain(
+ "When no further tool calls are needed in this turn",
+ );
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).toContain("one brief user-facing acknowledgement");
+ expect(TASK_DELIVERY_INITIATING_INSTRUCTION).not.toContain(EMPTY_DELIVERY_SENTINEL);
+ });
+
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");
@@ -49,6 +67,33 @@ describe("task delivery instructions", () => {
});
});
+describe("resolveInitiatingTaskContext", () => {
+ it("projects the active turn's accepted background tasks as initiating", () => {
+ expect(
+ resolveInitiatingTaskContext({
+ state: taskState([
+ taskEntry("task_1", "turn_1", undefined, { data: {}, kind: "subagent" }),
+ taskEntry("task_2", "turn_2", undefined, { data: {}, kind: "subagent" }),
+ ]),
+ turnId: "turn_1",
+ }),
+ ).toEqual({
+ context:
+ '[Task state]\n{"tasks":[{"name":"report_probe","status":"pending","taskId":"task_1"}]}',
+ phase: "initiating",
+ });
+ });
+
+ it("ignores task records that were not accepted by an executor", () => {
+ expect(
+ resolveInitiatingTaskContext({
+ state: taskState([taskEntry("task_1", "turn_1")]),
+ turnId: "turn_1",
+ }),
+ ).toBeUndefined();
+ });
+});
+
describe("resolveTaskDeliveryContext", () => {
it("projects terminal and pending siblings from the delivered task's parent turn", () => {
const completed = {
@@ -111,9 +156,15 @@ describe("resolveTaskDeliveryContext", () => {
});
});
-function taskEntry(taskId: string, createdByTurnId: string, terminalView?: TaskView) {
+function taskEntry(
+ taskId: string,
+ createdByTurnId: string,
+ terminalView?: TaskView,
+ executor?: { readonly data: Record<string, never>; readonly kind: string },
+) {
return {
createdByTurnId,
+ executor,
metadata,
taskId,
taskInboxToken: `inbox-${taskId}`,
diff --git a/packages/eve/src/tasks/delivery-context.ts b/packages/eve/src/tasks/delivery-context.ts
index a1bcc8319..6a6b0866d 100644
--- a/packages/eve/src/tasks/delivery-context.ts
+++ b/packages/eve/src/tasks/delivery-context.ts
@@ -1,9 +1,14 @@
import type { SessionStateMap } from "#harness/types.js";
import { EMPTY_DELIVERY_SENTINEL } from "#shared/empty-delivery.js";
-import { getSessionTaskIndex } from "#tasks/session-index.js";
+import { getSessionTaskIndex, type SessionTaskIndexEntry } from "#tasks/session-index.js";
export const TASK_DELIVERY_CONTEXT_LABEL = "[Task state]";
+export const TASK_DELIVERY_INITIATING_INSTRUCTION = `Background task reporting: launch acknowledgement
+The accompanying ${TASK_DELIVERY_CONTEXT_LABEL} system message is runtime-authored and lists background tasks accepted so far from the current turn. They continue independently after this turn.
+
+Continue carrying out the user's request, including starting any remaining background work. When no further tool calls are needed in this turn, send one brief user-facing acknowledgement that the background work has started. Do not wait for results or report results that are not available yet. End the turn after the acknowledgement.`;
+
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.
@@ -34,6 +39,27 @@ export function resolveTaskDeliveryContext(input: {
if (delivered === undefined) return undefined;
const cohort = entries.filter((entry) => entry.createdByTurnId === delivered.createdByTurnId);
+ return projectTaskCohort(cohort);
+}
+
+/** Returns model context for durable tasks launched by the active parent turn. */
+export function resolveInitiatingTaskContext(input: {
+ readonly state: SessionStateMap | undefined;
+ readonly turnId: string;
+}): { readonly context: string; readonly phase: "initiating" } | undefined {
+ const cohort = getSessionTaskIndex(input.state).filter(
+ (entry) => entry.createdByTurnId === input.turnId,
+ );
+ if (!cohort.some((entry) => entry.executor !== undefined && entry.terminalView === undefined)) {
+ return undefined;
+ }
+ return { ...projectTaskCohort(cohort), phase: "initiating" };
+}
+
+function projectTaskCohort(cohort: readonly SessionTaskIndexEntry[]): {
+ readonly context: string;
+ readonly phase: "pending" | "settled";
+} {
const settled = cohort.every((entry) => entry.terminalView !== undefined);
const tasks = cohort.map((entry) => ({
name: entry.metadata.name,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ab72325f..9b19ef4f8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -905,6 +905,9 @@ importers:
eve:
specifier: workspace:*
version: link:../../../packages/eve
+ just-bash:
+ specifier: 3.1.0
+ version: 3.1.0([email protected])
zod:
specifier: 'catalog:'
version: 4.4.3