Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): defer scheduled delivery until background results (#3350)

Ruidafa5586086c
diff --git a/.changeset/quiet-taxis-wait.md b/.changeset/quiet-taxis-wait.md
new file mode 100644
index 000000000..d5dfd8bdc
--- /dev/null
+++ b/.changeset/quiet-taxis-wait.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Scheduled runs that start background work now stay open and silent until the result is available, then deliver the final response once.
diff --git a/e2e/fixtures/agent-background-tools/evals/scheduled-export.quiet-launch.eval.ts b/e2e/fixtures/agent-background-tools/evals/scheduled-export.quiet-launch.eval.ts
index 5979802df..46627c9ac 100644
--- a/e2e/fixtures/agent-background-tools/evals/scheduled-export.quiet-launch.eval.ts
+++ b/e2e/fixtures/agent-background-tools/evals/scheduled-export.quiet-launch.eval.ts
@@ -2,6 +2,7 @@ import { defineEval } from "eve/evals";
import { equals, satisfies } from "eve/evals/expect";
const RESULT = "EXPORT-COMPLETE";
+const FINAL = "SCHEDULED-EXPORT-DONE";
/**
* A schedule-launched turn that dispatches a background task sends no launch
@@ -19,6 +20,7 @@ export default defineEval({
t.skip("Target has no dev routes; schedule dispatch is dev-only.");
}
+ // Scheduled root dispatch: the schedule, not an inbound turn, creates the session.
const dispatch = await t.target.dispatchSchedule("scheduled-export");
await t.require(dispatch.scheduleId, equals("scheduled-export"));
await t.require(
@@ -63,13 +65,18 @@ export default defineEval({
satisfies((message) => message === undefined, "the pending message wake is silent"),
);
- // Only the settled wake produces a user-facing report.
+ // Agent receives background task result after turn ended.
+ // Only the settled wake produces the single final non-null delivery.
const doneLive = t.target.watchTurn(sessionId, {
startIndex: requireStreamIndex(updateLive.session, "completion wait"),
});
const doneTurn = await doneLive.result();
doneTurn.expectOk();
- doneTurn.messageIncludes("SCHEDULED-EXPORT-DONE");
+ doneTurn.messageIncludes(FINAL);
+ doneTurn.event("message.completed", {
+ data: (data) => data.finishReason !== "tool-calls" && data.message !== null,
+ count: 1,
+ });
await t.require(
doneTurn.events,
satisfies(
@@ -83,6 +90,39 @@ export default defineEval({
"the report follows the executor completion",
),
);
+
+ // Replay all three durable turns. Only the late report survives as assistant output.
+ const replayedLaunch = await t.target.attachSession(sessionId);
+ const replayedUpdateLive = t.target.watchTurn(sessionId, {
+ startIndex: requireStreamIndex(replayedLaunch, "replayed update"),
+ });
+ await replayedUpdateLive.result();
+ const replayedDoneLive = t.target.watchTurn(sessionId, {
+ startIndex: requireStreamIndex(replayedUpdateLive.session, "replayed completion"),
+ });
+ await replayedDoneLive.result();
+ const replayedEvents = [
+ ...replayedLaunch.events,
+ ...replayedUpdateLive.events,
+ ...replayedDoneLive.events,
+ ];
+ await t.require(
+ replayedEvents,
+ satisfies(
+ (events: typeof replayedEvents) =>
+ events.some(
+ (event) =>
+ event.type === "message.received" && messageText(event.data.message).includes(RESULT),
+ ) &&
+ events.filter(
+ (event) =>
+ event.type === "message.completed" &&
+ event.data.message !== null &&
+ JSON.stringify(event.data.message).includes(FINAL),
+ ).length === 1,
+ "replay retains one final export report",
+ ),
+ );
t.noFailedActions();
t.succeeded();
},
diff --git a/e2e/fixtures/agent-subagents/agent/agent.ts b/e2e/fixtures/agent-subagents/agent/agent.ts
index 5cabe7625..13ee3be45 100644
--- a/e2e/fixtures/agent-subagents/agent/agent.ts
+++ b/e2e/fixtures/agent-subagents/agent/agent.ts
@@ -2,7 +2,12 @@ import { e2eAgentConfig } from "@eve-e2e/config";
import { defineAgent, defineDynamic } from "eve";
import { mockModel } from "eve/evals";
-import { WORKSPACE_FORWARDING_MARKER, WORKSPACE_LOOKUP_MESSAGE } from "../constants";
+import {
+ SCHEDULED_REMOTE_CHILD_SCENARIO,
+ SCHEDULED_REMOTE_ROOT_SCENARIO,
+ WORKSPACE_FORWARDING_MARKER,
+ WORKSPACE_LOOKUP_MESSAGE,
+} from "../constants";
if (process.env.EVE_E2E_MODEL === "mock") {
process.env.EVE_MOCK_AUTHORED_MODELS = "1";
@@ -63,6 +68,54 @@ const workspaceDispatcher = mockModel({
};
},
});
+const scheduledRemoteModel = mockModel({
+ modelId: "scheduled-remote-completion",
+ respond(request) {
+ if (request.userMessages.some((message) => message.includes(SCHEDULED_REMOTE_CHILD_SCENARIO))) {
+ return "SCHEDULED-REMOTE-CHILD-RESULT";
+ }
+
+ const remote = completedTaskOutput(request.userMessages, "remote-loopback");
+ if (remote !== undefined) return `SCHEDULED-REMOTE-FINAL ${remote}`;
+ if (!request.toolResults.some((result) => result.id === "scheduled-remote")) {
+ return {
+ toolCalls: [
+ {
+ id: "scheduled-remote",
+ input: { message: SCHEDULED_REMOTE_CHILD_SCENARIO },
+ name: "remote-loopback",
+ },
+ ],
+ };
+ }
+ return "Weekly report could not be completed before delivery because the analytics query did not return a result.";
+ },
+});
+
+function completedTaskOutput(messages: readonly string[], name: string): string | undefined {
+ const prefix = "[Task state]\n";
+ const state = [...messages].reverse().find((message) => message.startsWith(prefix));
+ if (state === undefined) return undefined;
+ const parsed: unknown = JSON.parse(state.slice(prefix.length));
+ if (parsed === null || typeof parsed !== "object") return undefined;
+ const tasks = Reflect.get(parsed, "tasks");
+ if (!Array.isArray(tasks)) return undefined;
+ const task = tasks.find(
+ (candidate) =>
+ candidate !== null &&
+ typeof candidate === "object" &&
+ Reflect.get(candidate, "name") === name &&
+ Reflect.get(candidate, "status") === "completed",
+ );
+ if (task === undefined) return undefined;
+ const output = Reflect.get(task, "output");
+ return output !== null &&
+ typeof output === "object" &&
+ Reflect.get(output, "type") === "result" &&
+ typeof Reflect.get(output, "data") === "string"
+ ? (Reflect.get(output, "data") as string)
+ : undefined;
+}
export default defineAgent({
...agentConfig,
@@ -84,6 +137,15 @@ export default defineAgent({
if (messages.some((message) => message.includes(WORKSPACE_FORWARDING_MARKER))) {
return { model: workspaceDispatcher, modelContextWindowTokens: 1_000_000 };
}
+ if (
+ messages.some(
+ (message) =>
+ message.includes(SCHEDULED_REMOTE_ROOT_SCENARIO) ||
+ message.includes(SCHEDULED_REMOTE_CHILD_SCENARIO),
+ )
+ ) {
+ return { model: scheduledRemoteModel, modelContextWindowTokens: 1_000_000 };
+ }
return { model: defaultModel, modelContextWindowTokens };
},
},
diff --git a/e2e/fixtures/agent-subagents/agent/channels/scheduled-remote-sink.ts b/e2e/fixtures/agent-subagents/agent/channels/scheduled-remote-sink.ts
new file mode 100644
index 000000000..83f7b3c76
--- /dev/null
+++ b/e2e/fixtures/agent-subagents/agent/channels/scheduled-remote-sink.ts
@@ -0,0 +1,20 @@
+import { defineChannel, POST } from "eve/channels";
+
+/** Rejects any non-null scheduled reply except the late remote-agent result. */
+export default defineChannel<undefined, void, { id: string }>({
+ routes: [POST("/scheduled-remote-sink", async () => new Response("ok"))],
+ receive(input, { from }) {
+ return from(input.target.id).send(input.message, { auth: input.auth });
+ },
+ events: {
+ "message.completed"(event) {
+ if (
+ event.finishReason !== "tool-calls" &&
+ event.message !== null &&
+ !JSON.stringify(event.message).includes("SCHEDULED-REMOTE-FINAL")
+ ) {
+ throw new Error(`Scheduled remote sink received an unexpected message: ${event.message}`);
+ }
+ },
+ },
+});
diff --git a/e2e/fixtures/agent-subagents/agent/schedules/scheduled-remote.ts b/e2e/fixtures/agent-subagents/agent/schedules/scheduled-remote.ts
new file mode 100644
index 000000000..ff630ef88
--- /dev/null
+++ b/e2e/fixtures/agent-subagents/agent/schedules/scheduled-remote.ts
@@ -0,0 +1,15 @@
+import { defineSchedule } from "eve/schedules";
+
+import { SCHEDULED_REMOTE_ROOT_SCENARIO } from "../../constants";
+import scheduledRemoteSink from "../channels/scheduled-remote-sink";
+
+export default defineSchedule({
+ cron: "0 0 * * *",
+ run({ appAuth, to, waitUntil }) {
+ waitUntil(
+ to(scheduledRemoteSink, { id: "scheduled-remote" }).send(SCHEDULED_REMOTE_ROOT_SCENARIO, {
+ auth: appAuth,
+ }),
+ );
+ },
+});
diff --git a/e2e/fixtures/agent-subagents/constants.ts b/e2e/fixtures/agent-subagents/constants.ts
index 29b7cbf0a..9069872cd 100644
--- a/e2e/fixtures/agent-subagents/constants.ts
+++ b/e2e/fixtures/agent-subagents/constants.ts
@@ -4,3 +4,8 @@ export const WORKSPACE_LOOKUP_MESSAGE = [
"Report the returned name, or explain if access is denied.",
].join(" ");
export const WORKSPACE_FORWARDING_MARKER = "Shared workspace membership check.";
+
+export const SCHEDULED_REMOTE_ROOT_SCENARIO =
+ "SCHEDULED-REMOTE-ROOT Ask remote-loopback to prepare Alice's scheduled report.";
+export const SCHEDULED_REMOTE_CHILD_SCENARIO =
+ "SCHEDULED-REMOTE-CHILD Return exactly SCHEDULED-REMOTE-CHILD-RESULT.";
diff --git a/e2e/fixtures/agent-subagents/evals/scheduled-remote-completion.eval.ts b/e2e/fixtures/agent-subagents/evals/scheduled-remote-completion.eval.ts
new file mode 100644
index 000000000..3ebe182c1
--- /dev/null
+++ b/e2e/fixtures/agent-subagents/evals/scheduled-remote-completion.eval.ts
@@ -0,0 +1,138 @@
+import { defineEval } from "eve/evals";
+import { equals, satisfies } from "eve/evals/expect";
+
+const FINAL = "SCHEDULED-REMOTE-FINAL SCHEDULED-REMOTE-CHILD-RESULT";
+const PREMATURE =
+ "Weekly report could not be completed before delivery because the analytics query did not return a result.";
+
+/**
+ * The schedule creates a root session, so no TurnCaller exists. This E2E observes
+ * that boundary through the channel stream; TurnCaller absence itself has no event.
+ */
+export default defineEval({
+ description:
+ "A scheduled root suppresses its nonempty remote-agent launch fallback and delivers the late result exactly once.",
+ async test(t) {
+ if (!t.target.capabilities.devRoutes) {
+ t.skip("Target has no dev routes; schedule dispatch is dev-only.");
+ }
+
+ // Scheduled root dispatch: the schedule, not an inbound turn, creates the session.
+ const dispatch = await t.target.dispatchSchedule("scheduled-remote");
+ await t.require(dispatch.scheduleId, equals("scheduled-remote"));
+ await t.require(
+ dispatch.sessionIds,
+ satisfies((ids: readonly string[]) => ids.length > 0, "schedule started a root session"),
+ );
+ const sessionId = dispatch.sessionIds[0]!;
+
+ // Initiating turn: withhold the deliberate nonempty premature fallback from
+ // both the event stream and the channel.
+ const launch = await t.target.attachSession(sessionId);
+ launch.succeeded();
+ launch.calledTool("remote-loopback");
+ launch.event("subagent.completed", {
+ data: (data) => data.subagentName === "remote-loopback" && data.backgroundTask !== undefined,
+ count: 1,
+ });
+ launch.event("message.completed", {
+ data: (data) => data.finishReason !== "tool-calls" && data.message === null,
+ count: 1,
+ });
+ launch.notEvent("message.completed", {
+ data: (data) => data.finishReason !== "tool-calls" && data.message !== null,
+ });
+ await t.require(
+ launch.events,
+ satisfies(
+ (events: typeof launch.events) => !JSON.stringify(events).includes(PREMATURE),
+ "the adapter and channel suppress the premature fallback",
+ ),
+ );
+
+ // Agent receives background task result after turn ended.
+ if (launch.state === undefined) throw new Error("scheduled launch has no stream cursor");
+ const completedLive = t.target.watchTurn(sessionId, {
+ startIndex: launch.state.streamIndex,
+ });
+ const completed = await completedLive.result();
+ completed.expectOk();
+ completed.messageIncludes(FINAL);
+ await t.require(
+ completed.events,
+ satisfies(
+ (events: typeof completed.events) =>
+ events.some(
+ (event) =>
+ event.type === "message.received" &&
+ messageText(event.data.message).includes("is completed") &&
+ messageText(event.data.message).includes("SCHEDULED-REMOTE-CHILD-RESULT"),
+ ),
+ "the final reply follows the late remote-agent result",
+ ),
+ );
+ completed.event("message.completed", {
+ data: (data) =>
+ data.finishReason !== "tool-calls" &&
+ data.message !== null &&
+ JSON.stringify(data.message).includes(FINAL),
+ count: 1,
+ });
+
+ // Replay both durable turns. The fallback never becomes assistant output,
+ // while the late remote result does exactly once.
+ const replayedLaunch = await t.target.attachSession(sessionId);
+ if (replayedLaunch.state === undefined) throw new Error("replayed launch has no stream cursor");
+ const replayedCompletion = await t.target
+ .watchTurn(sessionId, { startIndex: replayedLaunch.state.streamIndex })
+ .result();
+ const replayedEvents = [...replayedLaunch.events, ...replayedCompletion.events];
+ await t.require(
+ replayedEvents,
+ satisfies(
+ (events: typeof replayedEvents) =>
+ !JSON.stringify(events).includes(PREMATURE) &&
+ events.filter(
+ (event) =>
+ event.type === "message.completed" &&
+ event.data.message !== null &&
+ JSON.stringify(event.data.message).includes(FINAL),
+ ).length === 1,
+ "replay retains one final remote result and no premature fallback",
+ ),
+ );
+
+ // Across both turns, assert exactly one final non-null delivery crosses the channel boundary.
+ const allEvents = [...launch.events, ...completed.events];
+ await t.require(
+ allEvents,
+ satisfies(
+ (events: typeof allEvents) =>
+ events.filter(
+ (event) =>
+ event.type === "message.completed" &&
+ event.data.finishReason !== "tool-calls" &&
+ event.data.message !== null,
+ ).length === 1,
+ "exactly one final non-null reply crosses the channel boundary",
+ ),
+ );
+ t.noFailedActions();
+ t.succeeded();
+ },
+});
+
+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/packages/eve/src/execution/scheduled-launch-delivery.test.ts b/packages/eve/src/execution/scheduled-launch-delivery.test.ts
new file mode 100644
index 000000000..5dab45e43
--- /dev/null
+++ b/packages/eve/src/execution/scheduled-launch-delivery.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ createMessageAppendedEvent,
+ createMessageCompletedEvent,
+ createResultCompletedEvent,
+} from "#protocol/message.js";
+import { scheduledLaunchDeliveryEvent } from "#execution/scheduled-launch-delivery.js";
+
+describe("scheduledLaunchDeliveryEvent", () => {
+ const completed = createMessageCompletedEvent({
+ message: "answer",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ });
+
+ it("hides an initiating scheduled reply but keeps its completion event", () => {
+ const appended = createMessageAppendedEvent({
+ messageDelta: "answer",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ });
+
+ expect(
+ scheduledLaunchDeliveryEvent(appended, {
+ isFirstTurn: true,
+ isScheduled: true,
+ taskPhase: "initiating",
+ }),
+ ).toBeUndefined();
+ expect(
+ scheduledLaunchDeliveryEvent(completed, {
+ isFirstTurn: true,
+ isScheduled: true,
+ taskPhase: "initiating",
+ }),
+ ).toEqual(expect.objectContaining({ data: expect.objectContaining({ message: null }) }));
+ });
+
+ it("keeps a direct scheduled answer", () => {
+ expect(
+ scheduledLaunchDeliveryEvent(completed, {
+ isFirstTurn: true,
+ isScheduled: true,
+ taskPhase: "none",
+ }),
+ ).toBe(completed);
+ });
+
+ it("keeps an interactive acknowledgement in a schedule-created session", () => {
+ expect(
+ scheduledLaunchDeliveryEvent(completed, {
+ isFirstTurn: false,
+ isScheduled: true,
+ taskPhase: "initiating",
+ }),
+ ).toBe(completed);
+ });
+
+ it("hides an initiating scheduled structured result", () => {
+ const result = createResultCompletedEvent({
+ result: { status: "pending" },
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ });
+ expect(
+ scheduledLaunchDeliveryEvent(result, {
+ isFirstTurn: true,
+ isScheduled: true,
+ taskPhase: "initiating",
+ }),
+ ).toBeUndefined();
+ });
+});
diff --git a/packages/eve/src/execution/scheduled-launch-delivery.ts b/packages/eve/src/execution/scheduled-launch-delivery.ts
new file mode 100644
index 000000000..a7c4306ba
--- /dev/null
+++ b/packages/eve/src/execution/scheduled-launch-delivery.ts
@@ -0,0 +1,18 @@
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+
+/** Hides a scheduled background launch while preserving its turn boundary. */
+export function scheduledLaunchDeliveryEvent(
+ event: UnstampedMessageStreamEvent,
+ input: {
+ readonly isFirstTurn: boolean;
+ readonly isScheduled: boolean;
+ readonly taskPhase: "none" | "initiating" | "pending" | "settled" | undefined;
+ },
+): UnstampedMessageStreamEvent | undefined {
+ if (!input.isFirstTurn || !input.isScheduled || input.taskPhase !== "initiating") return event;
+ if (event.type === "message.appended" || event.type === "result.completed") return undefined;
+ if (event.type === "message.completed") {
+ return { ...event, data: { ...event.data, message: null } };
+ }
+ return event;
+}
diff --git a/packages/eve/src/execution/tasks/parent/tool-execution.ts b/packages/eve/src/execution/tasks/parent/tool-execution.ts
index d5c3ed80e..4f72ab4f6 100644
--- a/packages/eve/src/execution/tasks/parent/tool-execution.ts
+++ b/packages/eve/src/execution/tasks/parent/tool-execution.ts
@@ -197,6 +197,10 @@ class BackgroundToolExecutionScope implements BackgroundToolExecutor {
});
}
+ hasPendingTasks(): boolean {
+ return this.records.some((record) => record.settled && record.task !== undefined);
+ }
+
async commit(session: HarnessSession): Promise<HarnessSession> {
const incomplete = this.records.filter((record) => !record.settled);
if (incomplete.length > 0) {
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index 04bc83e98..5b81604b0 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -16,6 +16,7 @@ import {
ContinuationTokenKey,
DynamicSubagentAgentConfigKey,
ModeKey,
+ ScheduleIdKey,
SessionCallbackKey,
SessionDynamicSubagentRuntimeRevisionKey,
SessionDynamicModelReferenceKey,
@@ -35,8 +36,15 @@ import { getPendingAuthorization, setPendingAuthorization } from "#harness/autho
import { getProxyInputRequests, upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
import { appendPendingInputBatch } from "#harness/input-requests.js";
import type { HarnessSession, StepFn, StepResult } from "#harness/types.js";
-import { createEmptyHookRegistry } from "#runtime/hooks/registry.js";
-import { createActionsRequestedEvent, createInputRequestedEvent } from "#protocol/message.js";
+import { createEmptyHookRegistry, createRuntimeHookRegistry } from "#runtime/hooks/registry.js";
+import {
+ createActionsRequestedEvent,
+ createInputRequestedEvent,
+ createMessageAppendedEvent,
+ createMessageCompletedEvent,
+ createResultCompletedEvent,
+ type UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
import {
createDurableSessionState,
@@ -1199,6 +1207,188 @@ describe("dispatchCoordinationStep", () => {
});
describe("turnStep", () => {
+ it("keeps one task stream open while hiding a scheduled fallback from delivery hooks", async () => {
+ const appended: string[] = [];
+ const delivered: Array<string | null> = [];
+ const hookEvents: string[] = [];
+ const adapter: ChannelAdapter = {
+ kind: "scheduled-output-capture",
+ "message.appended"(data) {
+ appended.push(data.messageDelta);
+ },
+ "message.completed"(data) {
+ delivered.push(data.message);
+ },
+ };
+ const bundle = Object.assign({}, createTurnStepTestBundle() as object, {
+ adapterRegistry: { adaptersByKind: new Map([[adapter.kind, adapter]]) },
+ hookRegistry: createRuntimeHookRegistry([
+ {
+ events: {
+ "*": async (event: UnstampedMessageStreamEvent) => {
+ hookEvents.push(JSON.stringify(event));
+ },
+ },
+ logicalPath: "hooks/audit.ts",
+ slug: "audit",
+ sourceId: "hooks/audit.ts",
+ sourceKind: "module",
+ } as never,
+ ]),
+ }) as never;
+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);
+
+ const task = {
+ createdByTurnId: "turn_0",
+ executor: { data: {}, kind: "workflow-tool" },
+ metadata: { kind: "report", name: "daily_report" },
+ taskId: "task_report",
+ taskInboxToken: "task-token",
+ taskRunId: "task-run",
+ };
+ const emissionState = {
+ sequence: 0,
+ sessionStarted: true,
+ stepIndex: 0,
+ turnId: "turn_0",
+ };
+ const pending = createStubSession({
+ state: {
+ "eve.harness.emission": emissionState,
+ "eve.tasks": { tasks: [task], version: 2 },
+ },
+ });
+ const terminalView = {
+ lastOutput: { data: "report complete", type: "result" as const },
+ metadata: task.metadata,
+ status: "completed" as const,
+ taskId: task.taskId,
+ };
+ const settled = createStubSession({
+ state: {
+ "eve.harness.emission": { ...emissionState, sequence: 1, turnId: "turn_1" },
+ "eve.tasks": {
+ tasks: [{ ...task, terminalView }],
+ version: 2,
+ },
+ },
+ });
+ installSessionStoreMocks([pending, settled]);
+
+ let modelTurn = 0;
+ vi.mocked(createExecutionNodeStep).mockImplementation((input) => {
+ return async (session): Promise<StepResult> => {
+ const message = modelTurn++ === 0 ? "Premature fallback" : "Final report";
+ await input.handleEvent?.(
+ createMessageAppendedEvent({
+ messageDelta: message,
+ sequence: modelTurn - 1,
+ stepIndex: 0,
+ turnId: `turn_${String(modelTurn - 1)}`,
+ }),
+ session.history,
+ );
+ await input.handleEvent?.(
+ createMessageCompletedEvent({
+ message,
+ sequence: modelTurn - 1,
+ stepIndex: 0,
+ turnId: `turn_${String(modelTurn - 1)}`,
+ }),
+ session.history,
+ );
+ await input.handleEvent?.(
+ createResultCompletedEvent({
+ result: { report: message },
+ sequence: modelTurn - 1,
+ stepIndex: 0,
+ turnId: `turn_${String(modelTurn - 1)}`,
+ }),
+ session.history,
+ );
+ return modelTurn === 1
+ ? { next: null, session, settledTurn: { output: { report: message } } }
+ : { next: { done: true, output: { report: message } }, session };
+ };
+ });
+
+ const ctx = new ContextContainer();
+ ctx.set(AuthKey, null);
+ ctx.set(BundleKey, bundle);
+ ctx.set(ChannelKey, adapter);
+ ctx.set(ContinuationTokenKey, "http:scheduled-output-capture");
+ ctx.set(ModeKey, "task");
+ ctx.set(ScheduleIdKey, "daily-report");
+ ctx.set(SessionIdKey, "session-1");
+ const serializedContext = serializeContext(ctx);
+ const writable = createTestWritable("scheduled-task");
+
+ const launch = await turnStep({
+ input: {
+ kind: "deliver",
+ payloads: [
+ {
+ message: "Run the daily report",
+ outputSchema: {
+ properties: { report: { type: "string" } },
+ required: ["report"],
+ type: "object",
+ },
+ },
+ ],
+ },
+ parentWritable: writable,
+ serializedContext,
+ sessionState: createStubSessionState({ emissionState }),
+ });
+ expect(appended).toEqual([]);
+ expect(delivered).toEqual([null]);
+ const launchEvents = (workflowWritesByNamespace.get("scheduled-task") ?? []).map((chunk) =>
+ JSON.parse(new TextDecoder().decode(chunk as Uint8Array)),
+ );
+ expect(launchEvents).toEqual([
+ expect.objectContaining({
+ data: expect.objectContaining({ message: null }),
+ type: "message.completed",
+ }),
+ ]);
+ expect(JSON.stringify(launchEvents)).not.toContain("Premature fallback");
+ expect(hookEvents.join("\n")).not.toContain("Premature fallback");
+
+ await turnStep({
+ input: {
+ kind: "deliver",
+ payloads: [{ message: "Background task task_report is completed." }],
+ taskDeliveryId: "task_report:ready:completed",
+ },
+ parentWritable: writable,
+ serializedContext: launch.serializedContext,
+ sessionState: launch.sessionState,
+ });
+
+ expect(appended).toEqual(["Final report"]);
+ expect(delivered).toEqual([null, "Final report"]);
+ const settledEvents = (workflowWritesByNamespace.get("scheduled-task") ?? []).map((chunk) =>
+ JSON.parse(new TextDecoder().decode(chunk as Uint8Array)),
+ );
+ expect(settledEvents.filter((event) => event.type === "message.completed")).toEqual([
+ expect.objectContaining({
+ data: expect.objectContaining({ message: null }),
+ type: "message.completed",
+ }),
+ expect.objectContaining({
+ data: expect.objectContaining({ message: "Final report" }),
+ type: "message.completed",
+ }),
+ ]);
+ expect(settledEvents.filter((event) => event.type === "result.completed")).toEqual([
+ expect.objectContaining({
+ data: expect.objectContaining({ result: { report: "Final report" } }),
+ type: "result.completed",
+ }),
+ ]);
+ });
+
it("runs the configured number of model calls inside one Workflow step", async () => {
const bundle = createTurnStepTestBundle(3);
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index 947963eb3..68b25bdf5 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -26,6 +26,7 @@ import {
ChannelDeliveryKey,
HandleEventKey,
ModeKey,
+ ScheduleIdKey,
SessionDynamicSubagentRuntimeRevisionKey,
SessionDynamicToolRuntimeRevisionKey,
StaticModelReferenceKey,
@@ -64,7 +65,6 @@ import {
encodeMessageStreamEvent,
type UnstampedMessageStreamEvent,
stampMessageStreamEvent,
- type MessageStreamEvent,
} from "#protocol/message.js";
import {
CallbackBaseUrlKey,
@@ -84,6 +84,7 @@ import {
resolveInitiatingTaskContext,
resolveTaskDeliveryContext,
} from "#tasks/delivery-context.js";
+import { scheduledLaunchDeliveryEvent } from "#execution/scheduled-launch-delivery.js";
import {
readRetainedBackgroundToolResult,
runBackgroundStep,
@@ -385,22 +386,29 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
}
const writer = input.parentWritable.getWriter();
-
- const emit = async (event: UnstampedMessageStreamEvent): Promise<MessageStreamEvent> => {
- const toEmit = await callAdapterEventHandler(adapter, event, adapterCtx);
+ const emit = async (event: UnstampedMessageStreamEvent) => {
+ const deliverableEvent = scheduledLaunchDeliveryEvent(event, {
+ isFirstTurn: initialEmissionState.sequence === 0,
+ isScheduled: ctx.get(ScheduleIdKey) !== undefined,
+ taskPhase: ctx.get(TurnTaskDeliveryKey),
+ });
+ if (deliverableEvent === undefined)
+ return {
+ event: stampMessageStreamEvent(event, ctx.get(TurnDeliveryIdsKey)),
+ suppressed: true,
+ };
+ const toEmit = await callAdapterEventHandler(adapter, deliverableEvent, adapterCtx);
setChannelContext(ctx, { ...adapter, state: { ...adapterCtx.state } });
const stamped = stampMessageStreamEvent(toEmit, ctx.get(TurnDeliveryIdsKey));
await writer.write(encodeMessageStreamEvent(stamped));
- return stamped;
+ return { event: stamped, suppressed: false };
};
const handleEvent: HandleEventFn = async (event, messages): Promise<void> => {
activityCohort.updateActivityBlockers(ctx, event);
- // A remote task's parent owns its HITL. Forward blocking events over
- // the task callback and keep them out of the child's local channel;
- // otherwise two TUIs can present and answer the same request.
+ // A remote task's parent owns its blocking events.
const forwardedToTaskParent = await forwardTaskEventToSessionCallback(ctx, event);
const emitted = forwardedToTaskParent
- ? stampMessageStreamEvent(event, ctx.get(TurnDeliveryIdsKey))
+ ? { event: stampMessageStreamEvent(event, ctx.get(TurnDeliveryIdsKey)), suppressed: false }
: await emit(event);
const lifecycleMessages = await dispatchMemoryLifecycleEvent({
abortSignal: input.abortSignal,
@@ -412,13 +420,14 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
messages,
nodeId: bundle.nodeId ?? "__root__",
});
- void observeSessionActivity({ ctx, event: emitted, sessionId: initialSession.sessionId });
- await dispatchStreamEventHooks({ ctx, registry: hookRegistry, event: emitted });
- if (emitted.type !== "step.started") {
+ void observeSessionActivity({ ctx, event: emitted.event, sessionId: initialSession.sessionId });
+ if (!emitted.suppressed)
+ await dispatchStreamEventHooks({ ctx, registry: hookRegistry, event: emitted.event });
+ if (emitted.event.type !== "step.started") {
await dispatchDynamicModelEvent({
ctx,
dynamicModel: effectiveAgent.turnAgent.dynamicModel,
- event: emitted,
+ event: emitted.event,
messages: lifecycleMessages,
scope: {
moduleMap: bundle.moduleMap,
@@ -426,29 +435,29 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
},
});
}
- await dynamicConnections.dispatch(emitted);
+ await dynamicConnections.dispatch(emitted.event);
await dispatchDynamicSubagentEvent({
ctx,
resolvers: dynamicSubagentResolvers,
- event: emitted,
+ event: emitted.event,
messages: lifecycleMessages,
});
await dispatchDynamicToolEvent({
ctx,
resolvers: dynamicToolResolvers,
- event: emitted,
+ event: emitted.event,
messages: lifecycleMessages,
});
await dispatchDynamicSkillEvent({
ctx,
resolvers: dynamicSkillResolvers,
- event: emitted,
+ event: emitted.event,
messages: lifecycleMessages,
});
await dispatchDynamicInstructionEvent({
ctx,
resolvers: dynamicInstructionsResolvers,
- event: emitted,
+ event: emitted.event,
messages: lifecycleMessages,
});
};
diff --git a/packages/eve/src/harness/background-tools.ts b/packages/eve/src/harness/background-tools.ts
index 35e69c710..9516fa7c9 100644
--- a/packages/eve/src/harness/background-tools.ts
+++ b/packages/eve/src/harness/background-tools.ts
@@ -33,6 +33,7 @@ export interface BackgroundToolCallBatch {
}
export interface BackgroundToolExecutor {
+ hasPendingTasks?(): boolean;
readAgentViews?(): Promise<readonly AgentView[]>;
execute(input: {
readonly batch: BackgroundToolCallBatch;
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 4ae54858f..c9641b477 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -2664,6 +2664,33 @@ describe("createToolLoopHarness", () => {
expect(result.next).toEqual({ done: true, output: { summary: "Done" } });
});
+ it("parks a scheduled task turn while its launched background task is pending", async () => {
+ const schema = {
+ properties: { summary: { type: "string" } },
+ required: ["summary"],
+ type: "object",
+ } as const;
+ setupMockAgent(finalOutputResult("Starting.", { summary: "Pending" }));
+ const { emit, events } = createEventCollector();
+ const runStep = createToolLoopHarness(createTestConfig("task", emit));
+ const ctx = new ContextContainer();
+ ctx.set(ScheduleIdKey, "scheduled-report");
+ ctx.set(BackgroundToolExecutorKey, {
+ execute: vi.fn(),
+ hasPendingTasks: () => true,
+ });
+
+ const result = await contextStorage.run(ctx, () =>
+ runStep(createTestSession({ outputSchema: schema }), { message: "Run the report" }),
+ );
+
+ expect(result.next).toBeNull();
+ expect(result.settledTurn).toEqual({ output: { summary: "Pending" } });
+ expect(result.session.outputSchema).toBe(schema);
+ expect(events.some((event) => event.type === "result.completed")).toBe(false);
+ expect(events.at(-1)?.type).toBe("session.waiting");
+ });
+
it("fails a task turn as an error when structured output is not produced", async () => {
setupMockAgent({
finishReason: "stop",
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index d2ddc76e1..bdf1a7fac 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -2778,10 +2778,22 @@ async function handleStepResult(input: {
return { next: runStep, session: nextSession };
}
- // `mode` is the fundamental terminal split: a task run must finish (an unmet
- // schema becomes an error), a conversation run may park. Whether a schema is
- // in effect is mode-independent — it is resolved once at the execution layer
- // and read straight off the session here.
+ if (
+ config.mode === "task" &&
+ contextStorage.getStore()?.get(ScheduleIdKey) !== undefined &&
+ contextStorage.getStore()?.get(BackgroundToolExecutorKey)?.hasPendingTasks?.() === true
+ ) {
+ return deferTaskTurn({
+ emissionState,
+ emit,
+ history: promptMessages,
+ result,
+ schema: nextSession.outputSchema,
+ session: nextSession,
+ stepOutput,
+ });
+ }
+
if (config.mode === "task") {
return finishTaskTurn({
emissionState,
@@ -2805,6 +2817,37 @@ async function handleStepResult(input: {
});
}
+/** Keeps a scheduled task session open until its background work settles. */
+async function deferTaskTurn(input: {
+ readonly emissionState: ReturnType<typeof getHarnessEmissionState>;
+ readonly emit?: ToolLoopHarnessConfig["handleEvent"];
+ readonly history: readonly HarnessModelMessage[];
+ readonly result: HarnessStepResult;
+ readonly schema: JsonObject | undefined;
+ readonly session: HarnessSession;
+ readonly stepOutput: string | null;
+}): Promise<StepResult> {
+ const { emit, history, result, schema, stepOutput } = input;
+ let { emissionState, session } = input;
+ session = clearTurnClientContextState(session);
+ const structured = schema === undefined ? undefined : extractFinalOutput(result);
+ if (structured !== undefined) {
+ session = {
+ ...persistStructuredAssistantTurn(session, history, structured),
+ outputSchema: schema,
+ };
+ }
+ if (emit) {
+ emissionState = await emitTurnEpilogue(emit, emissionState, "conversation");
+ session = setHarnessEmissionState(session, emissionState);
+ }
+ return {
+ next: null,
+ session,
+ settledTurn: { output: structured ?? stepOutput ?? "" },
+ };
+}
+
function isDeferredHarnessTool(tool: HarnessToolDefinition | undefined): boolean {
return (
tool?.runtimeAction !== undefined ||