Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Allow prewarming existing sessions across deployments (#4735)

Karthik Kalyanea3a387d6826
diff --git a/.changeset/typing-session-prewarm.md b/.changeset/typing-session-prewarm.md
new file mode 100644
index 000000000..1f1060048
--- /dev/null
+++ b/.changeset/typing-session-prewarm.md
@@ -0,0 +1,7 @@
+---
+"eve": patch
+---
+
+Calling `prewarm()` on an existing session can now prepare an idle owner on the Vercel deployment accepting the request before the next message. Apps can trigger it when typing starts; it preserves the session, history, stream, and expiry, and does not block Send or run the model.
+
+Preparation uses the existing `POST /eve/v1/session/:sessionId` endpoint with no body or `{}`. Requests with messages or input responses keep their existing behavior.
diff --git a/docs/channels/eve.mdx b/docs/channels/eve.mdx
index 78f91fa99..2641ac03a 100644
--- a/docs/channels/eve.mdx
+++ b/docs/channels/eve.mdx
@@ -91,7 +91,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
- `GET /eve/v1/health` (check whether the application is reachable)
- `GET /eve/v1/info` (inspect the agent)
- `POST /eve/v1/session` (create a session, optionally sending its first message)
-- `POST /eve/v1/session/:sessionId` (send a follow-up)
+- `POST /eve/v1/session/:sessionId` (send a follow-up, respond to an input request, or prepare an idle session with an empty body)
- `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
- `POST /eve/v1/session/:sessionId/clear` (clear the session's model history)
- `POST /eve/v1/session/:sessionId/compact` (compact the session's context)
@@ -100,6 +100,17 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
+`POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session using
+the channel's auth policy. Non-empty bodies retain the message and input-response behavior;
+empty or invalid messages and payloads without either input are rejected. Preparation
+returns `{ ok: true, status }`: `ready` when the owner already uses the serving
+deployment, `accepted` (HTTP 202) when a background preparation hint has been queued,
+`unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
+owner exists. Other successful statuses use HTTP 200. Acceptance does not mean the handoff
+has completed. Idle preparation preserves the session ID, stream, history, and expiry;
+active work is not interrupted. See the [frontend guide](../guides/frontend/overview#returned-state)
+for client usage and deployment routing.
+
`GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
### Start and continue a session
diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdx
index a2a8993dc..308385dbc 100644
--- a/docs/guides/frontend/overview.mdx
+++ b/docs/guides/frontend/overview.mdx
@@ -78,7 +78,7 @@ export function Chat() {
| `error` | The latest session creation, stream, resume, or turn failure. |
| `events` | Raw eve stream events for this session. |
| `session` | Serializable fixed session cursor (`sessionId`, `streamIndex`). |
-| `prewarm` | Create the durable session without starting a turn. |
+| `prewarm` | Create a session or prepare its idle owner without starting a turn. |
| `send` | Send text or a multi-part message, with per-turn options. |
| `respond` | Answer pending HITL input requests, with per-turn options. |
| `resume` | Replay an attached session and follow its in-flight turn. |
@@ -131,7 +131,7 @@ An initial `true` value or a later `false` to `true` change prepares the current
Changing `prewarm` back to `false` does not abort creation or discard an existing session. If
a reset and state update happen in the same event, React applies both before deciding whether
to prepare the next session. Vue and Svelte read `prewarm` when their binding is created; call
-their returned `prewarm()` method for interaction-driven creation.
+their returned `prewarm()` method when typing starts.
Prewarming defaults to `false`: the first send creates the session. Set it to `true` only after
your application's auth, headers, and any chat-record binding are ready. Applications that
@@ -141,15 +141,35 @@ Prewarming starts the workflow and establishes its inbox, then parks before sess
dynamic definitions, or sandbox setup run. The first message passes through the channel's
`onMessage` hook and supplies the identity and context for initialization and `turn_0`.
-The explicit `prewarm()` method resolves on `202 Accepted`, as does `client.sessions.create()`.
-It does not wait for an initialization event; concurrent calls share the same create request.
+For an existing session, `prewarm()` checks the owner against the exact deployment accepting
+that request. On Vercel, an idle owner on another deployment can transfer in the background
+before Send. The session ID, history, stream, and expiry stay the same; no model call runs.
+An owner already serving that deployment needs no workflow wake-up. Active turns are never
+interrupted; an active turn can finish before preparation, and a queued real message takes priority.
+An owner with pending tasks or input requests can skip the hint.
+Older owners without preparation support and Worlds without deployment affinity are left alone.
+
+Call `agent.prewarm()` once when a new typing burst begins, with an application-level cooldown
+if you also retry during long drafts. eve shares concurrent calls; it does not listen to inputs
+or poll deployments. `prewarm: true` also prepares a restored session when the binding mounts.
+A production alias targets its current deployment; a preview alias targets that preview.
+Requests pinned to an immutable deployment (including deployment-skew routing) cannot discover
+a newer deployment. Local development retains session-creation behavior.
+
+`client.sessions.attach(sessionId).prewarm({ signal })` returns `ready`, `accepted`,
+`unsupported`, or `no_active_session`. `accepted` means the hint was persisted, not that handoff
+has finished. It never replaces an expired session. Send retains its existing retry and
+handoff behavior if preparation is unavailable, fails, or has not finished.
+
+The explicit `prewarm()` method resolves after ingress acceptance, as does `client.sessions.create()`.
+It does not wait for an initialization event; concurrent calls share the same preparation request.
The composer stays `"ready"`, meaning it can accept input, and prewarming does not run
-`prepareSend`. A concurrent `send()` waits only for acceptance, then posts the message.
+`prepareSend`. A concurrent `send()` waits for initial creation acceptance when needed, but never waits for existing-session preparation.
If the inbox is still starting, the client retries `409 session_not_ready` with bounded
exponential backoff for up to 20 seconds. The caller's abort signal cancels the wait. Stream
events are not a prerequisite for sending.
-A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
+An existing-session preparation failure rejects the explicit call without setting the composer's error or blocking Send. A failed create sets `error` and calls `onError` when no send is waiting. A waiting send can
fall back to creating a session with its message. After creation succeeds, initialization
failures arrive on the stream during the first turn. The configured session timeout starts
at creation, so an unused prewarmed session can expire before its first message. React does not
diff --git a/e2e/fixtures/agent-basic-runtime/evals/runtime/session-prewarm.eval.ts b/e2e/fixtures/agent-basic-runtime/evals/runtime/session-prewarm.eval.ts
index 7d9fe11c7..7c146f80f 100644
--- a/e2e/fixtures/agent-basic-runtime/evals/runtime/session-prewarm.eval.ts
+++ b/e2e/fixtures/agent-basic-runtime/evals/runtime/session-prewarm.eval.ts
@@ -1,11 +1,23 @@
import { defineEval } from "eve/evals";
-import { equals } from "eve/evals/expect";
+import { equals, satisfies } from "eve/evals/expect";
export default defineEval({
description: "A prewarmed workflow initializes only when its first message arrives.",
async test(t) {
const session = await t.session();
const sessionId = session.sessionId;
+ const prepare = await t.target.fetch(`/eve/v1/session/${sessionId}`, {
+ method: "POST",
+ });
+ await t.require(prepare.ok, equals(true));
+ await t.require(
+ await prepare.json(),
+ satisfies(
+ (value: { status?: string }) =>
+ ["ready", "unsupported", "no_active_session"].includes(value.status ?? ""),
+ "same deployment preparation starts no turn",
+ ),
+ );
const message = `Alice opened this chat while the session warmed up. Greet her briefly and include reference ${crypto.randomUUID()}.`;
const live = await session.start(message);
const observed = t.target.watchTurn(live.sessionId, { startIndex: 0 });
diff --git a/packages/eve/extension-contracts/compatibility/channel/v66.ts b/packages/eve/extension-contracts/compatibility/channel/v66.ts
new file mode 100644
index 000000000..404ce252f
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/channel/v66.ts
@@ -0,0 +1,12 @@
+import { defineChannel, POST } from "#public/channels/index.js";
+
+// Retained channel epoch 66: existing session authoring works with proactive preparation.
+export default defineChannel({
+ routes: [
+ POST("/reports", async (_request, { from }) => {
+ const { session } = await from("reports").create({ auth: null });
+ await session.send("Summarize the attached screenshot.", { auth: null });
+ return Response.json({ sessionId: session.id });
+ }),
+ ],
+});
diff --git a/packages/eve/extension-contracts/compatibility/connection/v54.ts b/packages/eve/extension-contracts/compatibility/connection/v54.ts
new file mode 100644
index 000000000..ee463d4bb
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/connection/v54.ts
@@ -0,0 +1,11 @@
+// Retained connection epoch 54: existing authoring works with proactive session preparation.
+import { defineMcpClientConnection } from "#public/connections/index.js";
+
+export default defineMcpClientConnection({
+ description: "Read reports from the tracker.",
+ url: "https://tracker.example.com/mcp",
+ auth: {
+ principalType: "app",
+ getToken: async () => ({ token: "service-credential" }),
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/schedule/v36.ts b/packages/eve/extension-contracts/compatibility/schedule/v36.ts
new file mode 100644
index 000000000..1dae8d10c
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/schedule/v36.ts
@@ -0,0 +1,21 @@
+// Retained schedule epoch 36: existing authoring works with proactive session preparation.
+import { defineChannel } from "#public/channels/index.js";
+import { defineSchedule } from "#public/schedules/index.js";
+
+const reports = defineChannel({
+ routes: [],
+ receive(input, { from }) {
+ return from("reports").send(input.message, { auth: input.auth });
+ },
+});
+
+export default defineSchedule({
+ cron: "0 2 * * *",
+ async run({ to, appAuth }) {
+ const session = await to(reports, {}).send("Prepare Alice's report.", { auth: appAuth });
+ await session.send("Include Bob's notes.", {
+ auth: appAuth,
+ history: [{ role: "user", text: "Bob reviewed the earlier draft." }],
+ });
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/tool/v99.ts b/packages/eve/extension-contracts/compatibility/tool/v99.ts
new file mode 100644
index 000000000..63fb706ba
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v99.ts
@@ -0,0 +1,27 @@
+// Retained tool epoch 99: file outputs still compile with proactive session preparation.
+import { defineTool, toolOutput, toolOutputPart } from "#public/tools/index.js";
+
+export default defineTool({
+ description: "Capture a screenshot.",
+ inputSchema: {
+ type: "object",
+ properties: { page: { type: "string" } },
+ required: ["page"],
+ additionalProperties: false,
+ },
+ async execute(input: { page: string }) {
+ return { page: input.page, png: "aGVsbG8=" };
+ },
+ toModelOutput(output) {
+ return toolOutput.content([
+ toolOutputPart.text(`Screenshot of ${output.page}:`),
+ toolOutputPart.file(output.png, { mediaType: "image/png", filename: "page.png" }),
+ toolOutputPart.fileUrl("https://reports.example.com/page.png", { mediaType: "image/png" }),
+ {
+ type: "file",
+ data: { type: "data", data: output.png },
+ mediaType: "image/png",
+ },
+ ]);
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/channel/v67.json b/packages/eve/extension-contracts/reports/channel/v67.json
new file mode 100644
index 000000000..8f9ec86e2
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/channel/v67.json
@@ -0,0 +1,24 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "channel",
+ "epoch": 67,
+ "sha256": "3c9f0182869056b33a80ecf9885b39140070503aeca1e6402f8dffa72e743798",
+ "exports": [
+ "DELETE",
+ "GET",
+ "HEAD",
+ "InvalidSessionHistoryError",
+ "OPTIONS",
+ "PATCH",
+ "POST",
+ "PUT",
+ "SessionStrandedError",
+ "WS",
+ "attachmentError",
+ "createWebSocketUpgradeServer",
+ "defineChannel",
+ "disableRoute",
+ "isChannel",
+ "isDisabledRouteSentinel"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/connection/v55.json b/packages/eve/extension-contracts/reports/connection/v55.json
new file mode 100644
index 000000000..28ce83df5
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v55.json
@@ -0,0 +1,16 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 55,
+ "sha256": "58be2b1d3b5b0f5acff201974e8e8bddc90360b395c22fd91f199fb3eff715fd",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineDynamic",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/schedule/v37.json b/packages/eve/extension-contracts/reports/schedule/v37.json
new file mode 100644
index 000000000..4b9428ab1
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/schedule/v37.json
@@ -0,0 +1,15 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "schedule",
+ "epoch": 37,
+ "sha256": "959947b80b3a3cd72a38ded1e3e6b7f4fecfc94da8f857c0a0321380b6cb6472",
+ "exports": [
+ "ScheduleDefinition",
+ "ScheduleHandlerArgs",
+ "ScheduleRunHandler",
+ "ScheduleToFn",
+ "TypedReceiveTarget",
+ "defineSchedule",
+ "isScheduleAuth"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v100.json b/packages/eve/extension-contracts/reports/tool/v100.json
new file mode 100644
index 000000000..e875111b4
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v100.json
@@ -0,0 +1,29 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 100,
+ "sha256": "5f11f5e36032278575f2b42fe8f95b675be63a0368ed61d3f2ae0c753d215d36",
+ "exports": [
+ "AgentRouterInput",
+ "AgentRouterTool",
+ "WorkflowStepToolContext",
+ "WorkflowTool",
+ "WorkflowToolDefinition",
+ "WorkflowToolInput",
+ "WorkflowToolOptions",
+ "agentRouter",
+ "decide",
+ "defaultWebSearch",
+ "defineTool",
+ "defineWorkflowTool",
+ "disableTool",
+ "isDisabledToolSentinel",
+ "isWebSearchToolDefinition",
+ "serializeModelInputSchema",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch",
+ "workflow"
+ ]
+}
diff --git a/packages/eve/src/channel/cross-channel-receive.test.ts b/packages/eve/src/channel/cross-channel-receive.test.ts
index 7bc21fb2c..4ee303680 100644
--- a/packages/eve/src/channel/cross-channel-receive.test.ts
+++ b/packages/eve/src/channel/cross-channel-receive.test.ts
@@ -39,6 +39,9 @@ function makeSession(): Session {
async respond() {
return { sessionId: "sess_1", status: "accepted" };
},
+ async prewarm() {
+ return { status: "ready" as const };
+ },
async compact() {
return { status: "no_active_session" };
},
diff --git a/packages/eve/src/channel/session.ts b/packages/eve/src/channel/session.ts
index 0c4b98bec..214619bef 100644
--- a/packages/eve/src/channel/session.ts
+++ b/packages/eve/src/channel/session.ts
@@ -58,6 +58,8 @@ export interface Session {
): Promise<SessionSendCommandResult>;
/** Requests cancellation of this exact session's active turn. */
cancel(options?: { turnId?: string }): Promise<CancelTurnResult>;
+ /** Prepares an idle session on the deployment accepting this request, without a model turn. */
+ prewarm(): Promise<import("#protocol/prewarm-session.js").PrewarmSessionResult>;
/** Queues compaction on this exact session ID. */
compact(): Promise<CompactSessionResult>;
/** Queues a context clear on this exact session ID. */
@@ -181,6 +183,12 @@ export function createSession(
if (options?.turnId !== undefined) command.turnId = options.turnId;
return await runtime.dispatchSession({ command, sessionId: id });
},
+ async prewarm() {
+ return await runtime.dispatchSession({
+ command: { kind: "prewarm", targetDeploymentId: metadata.acceptedDeploymentId },
+ sessionId: id,
+ });
+ },
async compact() {
return await runtime.dispatchSession({ command: { kind: "compact" }, sessionId: id });
},
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index 38b37a7cf..bb77b2c93 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -203,6 +203,7 @@ export type SessionCommand =
readonly kind: "cancel";
readonly turnId?: string;
}
+ | { readonly kind: "prewarm"; readonly targetDeploymentId?: string }
| { readonly kind: "compact" }
| { readonly kind: "clear" }
| { readonly kind: "reset"; readonly reason?: string };
@@ -221,15 +222,17 @@ export type ResetSessionResult =
| { readonly status: "no_active_session" };
export type SessionCommandResult<TCommand extends SessionCommand = SessionCommand> =
- TCommand extends { readonly kind: "send" }
- ? SessionSendCommandResult
- : TCommand extends { readonly kind: "cancel" }
- ? CancelTurnResult
- : TCommand extends { readonly kind: "compact" }
- ? CompactSessionResult
- : TCommand extends { readonly kind: "clear" }
- ? ClearSessionResult
- : ResetSessionResult;
+ TCommand extends { readonly kind: "prewarm" }
+ ? import("#protocol/prewarm-session.js").PrewarmSessionResult
+ : TCommand extends { readonly kind: "send" }
+ ? SessionSendCommandResult
+ : TCommand extends { readonly kind: "cancel" }
+ ? CancelTurnResult
+ : TCommand extends { readonly kind: "compact" }
+ ? CompactSessionResult
+ : TCommand extends { readonly kind: "clear" }
+ ? ClearSessionResult
+ : ResetSessionResult;
export interface DispatchContinuationInput<TCommand extends SessionCommand = SessionCommand> {
readonly command: TCommand;
diff --git a/packages/eve/src/client/eve-agent-store.test.ts b/packages/eve/src/client/eve-agent-store.test.ts
index 728f9afca..1169bf9a1 100644
--- a/packages/eve/src/client/eve-agent-store.test.ts
+++ b/packages/eve/src/client/eve-agent-store.test.ts
@@ -666,6 +666,43 @@ describe("EveAgentStore agent-session following", () => {
});
describe("EveAgentStore prewarming", () => {
+ it("deduplicates existing-session preparation and sends while it is pending or fails", async () => {
+ const preparation = Promise.withResolvers<Response>();
+ const stream = controlledStreamResponse();
+ const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (_url, init) => {
+ if (init?.method === "POST" && init.body === undefined) return preparation.promise;
+ if (init?.method === "POST") return startedResponse();
+ return stream.response;
+ });
+ const store = createStore({
+ initialSession: { sessionId: "session_1", streamIndex: 0 },
+ reducer: defaultMessageReducer(),
+ });
+ const prewarm = store.prewarm();
+ expect(store.prewarm()).toBe(prewarm);
+ const rejected = expect(prewarm).rejects.toThrow("prepare failed");
+ const sending = store.send({ message: "Hello" });
+ await vi.waitFor(() =>
+ expect(
+ fetchMock.mock.calls.some(
+ ([url, init]) =>
+ String(url) === "/eve/v1/session/session_1" &&
+ init?.method === "POST" &&
+ typeof init.body === "string" &&
+ JSON.parse(init.body).message === "Hello",
+ ),
+ ).toBe(true),
+ );
+ preparation.reject(new Error("prepare failed"));
+ await rejected;
+ for (const event of turnEvents())
+ stream.emit({ ...event, meta: { ...event.meta, deliveryIds: ["delivery_1"] } });
+ await sending;
+ expect(store.snapshot.status).toBe("ready");
+ expect(store.snapshot.error).toBeUndefined();
+ expect(store.snapshot.session?.sessionId).toBe("session_1");
+ });
+
it("settles a send aborted during preparation without creating a session", async () => {
const fetchMock = vi.spyOn(globalThis, "fetch");
const store = createStore({ reducer: defaultMessageReducer() });
diff --git a/packages/eve/src/client/eve-agent-store.ts b/packages/eve/src/client/eve-agent-store.ts
index fb69ff12d..b1bf6d280 100644
--- a/packages/eve/src/client/eve-agent-store.ts
+++ b/packages/eve/src/client/eve-agent-store.ts
@@ -137,11 +137,11 @@ export class EveAgentStore<TData> {
return () => void this.#subscribers.delete(callback);
}
- /** Creates this store's owned session without starting a turn. */
+ /** Creates a session or prepares its idle owner without starting a turn. */
prewarm(): Promise<void> {
if (this.#prewarmPromise !== undefined) return this.#prewarmPromise;
- if (this.#session !== undefined || this.#externalSession) return Promise.resolve();
- if (this.#activeTurn !== undefined) {
+ if (this.#session === undefined && this.#externalSession) return Promise.resolve();
+ if (this.#activeTurn !== undefined && this.#session === undefined) {
return this.#activeTurn.response.then((response) => {
if (response === undefined) {
throw this.#error ?? new DOMException("Session creation was aborted.", "AbortError");
@@ -149,7 +149,8 @@ export class EveAgentStore<TData> {
});
}
const client = this.#client;
- if (client === undefined) {
+ const session = this.#session;
+ if (client === undefined && session === undefined) {
return Promise.reject(new Error("This eve agent store does not own a session client."));
}
@@ -158,7 +159,11 @@ export class EveAgentStore<TData> {
this.#prewarmController = controller;
const promise = (async () => {
try {
- const created = await client.sessions.create({ signal: controller.signal });
+ if (session !== undefined) {
+ await session.prewarm({ signal: controller.signal });
+ return;
+ }
+ const created = await client!.sessions.create({ signal: controller.signal });
if (generation !== this.#prewarmGeneration) return;
this.#error = undefined;
if (this.#status === "error") this.#status = "ready";
@@ -167,6 +172,7 @@ export class EveAgentStore<TData> {
if (this.#followIdle) this.#ensureStream();
} catch (error) {
if (
+ session === undefined &&
generation === this.#prewarmGeneration &&
this.#activeTurn === undefined &&
this.#error === undefined
@@ -518,7 +524,7 @@ export class EveAgentStore<TData> {
headers: input.headers,
streamReconnectPolicy: input.streamReconnectPolicy,
};
- if (this.#prewarmPromise !== undefined) {
+ if (this.#session === undefined && this.#prewarmPromise !== undefined) {
// A failed speculative create must not prevent the user's message from being sent.
await waitWithSignal(
this.#prewarmPromise.catch((error: unknown) => {
diff --git a/packages/eve/src/client/index.ts b/packages/eve/src/client/index.ts
index 32420bc0b..cc9aff7aa 100644
--- a/packages/eve/src/client/index.ts
+++ b/packages/eve/src/client/index.ts
@@ -30,6 +30,7 @@ export type {
export { createDataUrlFilePart, createTextWithFileContent } from "#client/file-parts.js";
export { MessageResponse } from "#client/message-response.js";
export { ClientAgentSession } from "#client/agent-session.js";
+export type { PrewarmSessionResult } from "#protocol/prewarm-session.js";
export { ClientSession } from "#client/session.js";
export {
ClientSessions,
diff --git a/packages/eve/src/client/session-controls.ts b/packages/eve/src/client/session-controls.ts
index 170f6a578..9b076abb5 100644
--- a/packages/eve/src/client/session-controls.ts
+++ b/packages/eve/src/client/session-controls.ts
@@ -1,3 +1,4 @@
+import { PrewarmResponseSchema, type PrewarmSessionResult } from "#protocol/prewarm-session.js";
import { createClientError } from "#client/client-error.js";
import type {
CancelSessionResult,
@@ -16,6 +17,7 @@ import {
createEveSessionClearRoutePath,
createEveSessionCompactRoutePath,
createEveSessionResetRoutePath,
+ createEveSessionRoutePath,
} from "#protocol/routes.js";
interface SessionControlContext {
@@ -24,6 +26,22 @@ interface SessionControlContext {
resolveHeaders(): Promise<Headers>;
}
+export async function prewarmClientSession(input: {
+ readonly context: SessionControlContext;
+ readonly sessionId: string;
+ readonly signal?: AbortSignal;
+}): Promise<PrewarmSessionResult> {
+ const { payload } = await postJson({
+ context: input.context,
+ operation: "Prewarm",
+ path: createEveSessionRoutePath(input.sessionId),
+ signal: input.signal,
+ });
+ const result = PrewarmResponseSchema.safeParse(payload);
+ if (!result.success) throw new Error("Prewarm route returned an invalid response.");
+ return { status: result.data.status };
+}
+
export async function cancelClientSession(input: {
readonly context: SessionControlContext;
readonly options?: {
diff --git a/packages/eve/src/client/session.test.ts b/packages/eve/src/client/session.test.ts
index c4aae36e3..8061196bf 100644
--- a/packages/eve/src/client/session.test.ts
+++ b/packages/eve/src/client/session.test.ts
@@ -102,6 +102,20 @@ function createBoundedStreamResponse(events: readonly unknown[]) {
}
describe("ClientSession", () => {
+ it("prepares the fixed session with a bodyless POST to its existing input endpoint", async () => {
+ const fetchMock = vi
+ .spyOn(globalThis, "fetch")
+ .mockResolvedValue(Response.json({ ok: true, status: "accepted" }, { status: 202 }));
+ const session = createSession({ sessionId: "session/1", streamIndex: 4 });
+
+ await expect(session.prewarm()).resolves.toEqual({ status: "accepted" });
+ expect(fetchMock).toHaveBeenCalledOnce();
+ expect(fetchMock.mock.calls[0]?.[0]).toBe("https://eve.test/eve/v1/session/session%2F1");
+ expect(fetchMock.mock.calls[0]?.[1]?.method).toBe("POST");
+ expect(fetchMock.mock.calls[0]?.[1]?.body).toBeUndefined();
+ expect(session.state).toEqual({ sessionId: "session/1", streamIndex: 4 });
+ });
+
it("cancels an accepted turn before its stream settles with freshly resolved auth", async () => {
let headerResolution = 0;
const requests: Array<{ headers: Headers; method: string; url: string }> = [];
diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.ts
index 33df352bc..7cebb3318 100644
--- a/packages/eve/src/client/session.ts
+++ b/packages/eve/src/client/session.ts
@@ -13,6 +13,7 @@ import { MessageResponse } from "#client/message-response.js";
import { followStreamIterable, sleep } from "#client/open-stream.js";
import {
cancelClientSession,
+ prewarmClientSession,
clearClientSession,
compactClientSession,
resetClientSession,
@@ -169,6 +170,17 @@ export class ClientSession {
);
}
+ /** Requests preparation of an existing idle session; never starts a model turn. */
+ async prewarm(options?: {
+ readonly signal?: AbortSignal;
+ }): Promise<import("#protocol/prewarm-session.js").PrewarmSessionResult> {
+ return await prewarmClientSession({
+ context: this.#context,
+ sessionId: this.#state.sessionId,
+ signal: options?.signal,
+ });
+ }
+
/** Requests cooperative cancellation of this session's active turn. */
async cancel(options?: {
readonly signal?: AbortSignal;
diff --git a/packages/eve/src/client/subagent-stream.integration.test.ts b/packages/eve/src/client/subagent-stream.integration.test.ts
index 08c83ba35..4409b90e7 100644
--- a/packages/eve/src/client/subagent-stream.integration.test.ts
+++ b/packages/eve/src/client/subagent-stream.integration.test.ts
@@ -132,6 +132,9 @@ function createParentRoute(
async cancel() {
return { status: "no_active_turn" };
},
+ async prewarm() {
+ return { status: "ready" as const };
+ },
async compact() {
return { sessionId: "parent-1", status: "accepted" };
},
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index 5243e92a2..8f8e1b476 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,10 +22,10 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: {
- current: 99,
+ current: 100,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 29, 30, 31, 32, 34, 35, 76, 77, 78, 80, 81, 82, 84,
- 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 97, 98, 99,
+ 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 97, 98, 99, 100,
],
dropped: {
14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",
@@ -137,10 +137,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
channel: {
- current: 66,
+ current: 67,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 29, 31, 36, 37, 38, 39, 40, 41, 42,
- 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 65, 66,
+ 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 65, 66, 67,
],
dropped: {
12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -164,10 +164,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
schedule: {
- current: 36,
+ current: 37,
supported: [
1, 2, 3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28,
- 29, 30, 31, 32, 33, 34, 35, 36,
+ 29, 30, 31, 32, 33, 34, 35, 36, 37,
],
dropped: {
5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",
@@ -194,10 +194,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {
},
},
connection: {
- current: 54,
+ current: 55,
supported: [
1, 2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24, 26, 32, 33, 34,
- 35, 36, 37, 38, 39, 40, 41, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54,
+ 35, 36, 37, 38, 39, 40, 41, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55,
],
dropped: {
9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",
diff --git a/packages/eve/src/eve-channel/index.ts b/packages/eve/src/eve-channel/index.ts
index 432189f7b..56c010d17 100644
--- a/packages/eve/src/eve-channel/index.ts
+++ b/packages/eve/src/eve-channel/index.ts
@@ -64,7 +64,6 @@ import {
parseCancelTurnBody,
parseCreateBody,
parseIncludeTailIndex,
- parseJsonRequest,
parseOptionalJsonRequest,
parseResetBody,
parseSessionControlBody,
@@ -409,8 +408,26 @@ export function eveChannel(input: EveChannelInput): EveChannel {
const sessionId = requireSessionId(params);
if (sessionId instanceof Response) return sessionId;
- const payload = await parseJsonRequest(req);
+ const payload = await parseOptionalJsonRequest(req);
if (payload instanceof Response) return payload;
+ if (Object.keys(payload).length === 0) {
+ try {
+ const result = await attachSession(sessionId).prewarm();
+ return Response.json(
+ { ok: true, ...result },
+ {
+ headers: { "cache-control": "no-store" },
+ status: result.status === "accepted" ? 202 : 200,
+ },
+ );
+ } catch (error) {
+ const errorId = logError(log, "session-prewarm request failed", error, { sessionId });
+ return Response.json(
+ { ok: false, error: "Failed to prewarm the session.", errorId },
+ { status: 500 },
+ );
+ }
+ }
const forwarded = await resolveForwardedPrincipal({
trustedForwarders: input.trustedForwarders,
forwarder: sessionAuthFromResult(authResult),
diff --git a/packages/eve/src/eve-channel/request.ts b/packages/eve/src/eve-channel/request.ts
index 8b1f92f2d..74acbc555 100644
--- a/packages/eve/src/eve-channel/request.ts
+++ b/packages/eve/src/eve-channel/request.ts
@@ -221,19 +221,6 @@ export async function parseCancelTurnBody(req: Request): Promise<ParsedCancelTur
return typeof turnId === "string" ? { turnId } : {};
}
-export async function parseJsonRequest(req: Request): Promise<Record<string, unknown> | Response> {
- let payload: unknown;
- try {
- payload = await req.json();
- } catch {
- return Response.json({ error: "Invalid JSON body.", ok: false }, { status: 400 });
- }
- if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
- return Response.json({ error: "Expected a JSON object.", ok: false }, { status: 400 });
- }
- return payload as Record<string, unknown>;
-}
-
export async function parseResetBody(
req: Request,
): Promise<{ readonly reason?: string } | Response> {
diff --git a/packages/eve/src/execution/eve-workflow-attributes.ts b/packages/eve/src/execution/eve-workflow-attributes.ts
index f00a82c3a..6124cb323 100644
--- a/packages/eve/src/execution/eve-workflow-attributes.ts
+++ b/packages/eve/src/execution/eve-workflow-attributes.ts
@@ -56,7 +56,10 @@ import {
import { isSampledTrace } from "#shared/trace-policy.js";
import { resolveForwardedTraceSeed } from "#shared/forwarded-trace-policy.js";
-/** eve version recorded on every run eve starts; handoff successors and legacy importers re-record it at boot. */
+/** Explicit support for idle preparation hints on a session owner. */
+export const EVE_PREWARM_ATTRIBUTE = "$eve.prewarm";
+
+/** eve version recorded on every run eve starts; successors re-record it at boot. */
export const EVE_VERSION_ATTRIBUTE = "$eve.version";
/** Run kind; only runs started as a session or subagent session carry it. */
diff --git a/packages/eve/src/execution/session-inbox/inbox.ts b/packages/eve/src/execution/session-inbox/inbox.ts
index 72e8eddd4..f9df180a3 100644
--- a/packages/eve/src/execution/session-inbox/inbox.ts
+++ b/packages/eve/src/execution/session-inbox/inbox.ts
@@ -1,3 +1,4 @@
+import type { SessionPrewarmPayload } from "#execution/session-prewarm.js";
import { sessionInboxHookToken } from "#execution/session-inbox/address.js";
import { createHook, getWorkflowMetadata, type Hook } from "#compiled/@workflow/core/index.js";
import { releaseSessionHooksStep } from "#execution/session-inbox/release-step.js";
@@ -43,6 +44,7 @@ export interface SessionHandoverPayload {
}
export type SessionInboxPayload =
+ | SessionPrewarmPayload
| SessionFailurePayload
| SessionHandoverPayload
| HookPayload
diff --git a/packages/eve/src/execution/session-inbox/protocol.ts b/packages/eve/src/execution/session-inbox/protocol.ts
index a6b303c42..c8c9252e0 100644
--- a/packages/eve/src/execution/session-inbox/protocol.ts
+++ b/packages/eve/src/execution/session-inbox/protocol.ts
@@ -5,7 +5,10 @@ import type {
} from "#channel/types.js";
import { validateDeliveryIdempotencyKey } from "#channel/delivery-idempotency.js";
+import type { SessionPrewarmPayload } from "#execution/session-prewarm.js";
+
type DecodedSessionInbox =
+ | SessionPrewarmPayload
| DeliverHookPayload
| SessionTimeoutHookPayload
| Extract<SessionCommand, { readonly kind: "cancel" | "clear" | "compact" | "reset" }>;
@@ -57,6 +60,15 @@ export function decodeSessionInboxPayload(value: unknown): DecodedSessionInbox {
}
return value as DeliverHookPayload;
}
+ case "session-prewarm":
+ if (
+ typeof payload.expectedOwnerRunId !== "string" ||
+ typeof payload.targetDeploymentId !== "string" ||
+ payload.targetDeploymentId.length === 0 ||
+ payload.targetDeploymentId === "latest"
+ )
+ throw new SessionInboxPayloadError("Invalid session prewarm hint.");
+ return value as SessionPrewarmPayload;
case "cancel":
case "clear":
case "compact":
diff --git a/packages/eve/src/execution/session-inbox/resume.ts b/packages/eve/src/execution/session-inbox/resume.ts
index 28c69d237..7f202151f 100644
--- a/packages/eve/src/execution/session-inbox/resume.ts
+++ b/packages/eve/src/execution/session-inbox/resume.ts
@@ -1,3 +1,4 @@
+import type { SessionPrewarmPayload } from "#execution/session-prewarm.js";
import type { SessionFailurePayload } from "#execution/session-inbox/inbox.js";
import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
import type {
@@ -47,7 +48,12 @@ export interface ResumedSessionInboxHook {
*/
export async function resumeSessionInbox(
address: string | SessionInboxAddress,
- command: DeliverHookPayload | SessionCommand | SessionTimeoutHookPayload | SessionFailurePayload,
+ command:
+ | DeliverHookPayload
+ | SessionCommand
+ | SessionTimeoutHookPayload
+ | SessionFailurePayload
+ | SessionPrewarmPayload,
): Promise<ResumedSessionInboxHook> {
const token = logicalSessionToken(address);
const knownSessionId = typeof address === "string" ? undefined : address.sessionId;
@@ -59,7 +65,7 @@ export async function resumeSessionInbox(
} catch (error) {
if (!HookNotFoundError.is(error)) throw error;
if (await waitWhileHandoffInProgress(token, deadline)) continue;
- if (command.kind === "session-failure") throw error;
+ if (command.kind === "session-failure" || command.kind === "session-prewarm") throw error;
return await resumeLegacyInbox(token, command).catch(rethrowUnsupportedAsNotFound);
}
let identity: Promise<string> | undefined;
diff --git a/packages/eve/src/execution/session-prewarm.test.ts b/packages/eve/src/execution/session-prewarm.test.ts
new file mode 100644
index 000000000..266b6a88f
--- /dev/null
+++ b/packages/eve/src/execution/session-prewarm.test.ts
@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { prewarmWorkflowSession } from "#execution/session-prewarm.js";
+import { getHookByToken, getWorld } from "#internal/workflow/runtime.js";
+import { resumeSessionInbox } from "#execution/session-inbox/resume.js";
+vi.mock("#internal/workflow/runtime.js", () => ({ getWorld: vi.fn(), getHookByToken: vi.fn() }));
+vi.mock("#execution/session-inbox/resume.js", () => ({ resumeSessionInbox: vi.fn() }));
+afterEach(() => vi.resetAllMocks());
+describe("session prewarm ingress", () => {
+ it.each([
+ ["dpl_b", "1", "ready"],
+ ["dpl_a", undefined, "unsupported"],
+ ["dpl_a", "1", "accepted"],
+ ] as const)(
+ "handles owner deployment %s and support %s as %s",
+ async (deploymentId, support, status) => {
+ const get = vi.fn().mockResolvedValue({
+ status: "running",
+ deploymentId,
+ attributes: { "$eve.prewarm": support },
+ });
+ vi.mocked(getWorld).mockResolvedValue({
+ capabilities: { deploymentAffinity: true },
+ runs: { get },
+ } as never);
+ vi.mocked(getHookByToken).mockResolvedValue({ runId: "wrun_owner" } as never);
+ await expect(prewarmWorkflowSession("wrun_session", "dpl_b")).resolves.toEqual({ status });
+ if (status === "accepted")
+ expect(resumeSessionInbox).toHaveBeenCalledWith(
+ { sessionId: "wrun_session" },
+ {
+ kind: "session-prewarm",
+ targetDeploymentId: "dpl_b",
+ expectedOwnerRunId: "wrun_owner",
+ },
+ );
+ else expect(resumeSessionInbox).not.toHaveBeenCalled();
+ },
+ );
+ it("propagates failed durable acceptance without reporting completion", async () => {
+ vi.mocked(getWorld).mockResolvedValue({
+ capabilities: { deploymentAffinity: true },
+ runs: {
+ get: vi.fn().mockResolvedValue({
+ status: "running",
+ deploymentId: "dpl_a",
+ attributes: { "$eve.prewarm": "1" },
+ }),
+ },
+ } as never);
+ vi.mocked(getHookByToken).mockResolvedValue({ runId: "wrun_owner" } as never);
+ vi.mocked(resumeSessionInbox).mockRejectedValue(new Error("acceptance failed"));
+ await expect(prewarmWorkflowSession("wrun_session", "dpl_b")).rejects.toThrow(
+ "acceptance failed",
+ );
+ });
+});
diff --git a/packages/eve/src/execution/session-prewarm.ts b/packages/eve/src/execution/session-prewarm.ts
new file mode 100644
index 000000000..e638362c7
--- /dev/null
+++ b/packages/eve/src/execution/session-prewarm.ts
@@ -0,0 +1,49 @@
+import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
+import { getHookByToken, getWorld } from "#internal/workflow/runtime.js";
+import { EVE_PREWARM_ATTRIBUTE } from "#execution/eve-workflow-attributes.js";
+import {
+ sessionCommandHookToken,
+ sessionInboxHookToken,
+} from "#execution/session-inbox/address.js";
+import { resumeSessionInbox } from "#execution/session-inbox/resume.js";
+import type { PrewarmSessionResult } from "#protocol/prewarm-session.js";
+
+/** Internal hint, scoped to the owner inspected by ingress to avoid stale transfers. */
+export interface SessionPrewarmPayload {
+ readonly kind: "session-prewarm";
+ readonly expectedOwnerRunId: string;
+ readonly targetDeploymentId: string;
+}
+
+export async function prewarmWorkflowSession(
+ sessionId: string,
+ targetDeploymentId: string | undefined,
+): Promise<PrewarmSessionResult> {
+ if (
+ targetDeploymentId === undefined ||
+ targetDeploymentId.length === 0 ||
+ targetDeploymentId === "latest"
+ )
+ return { status: "unsupported" };
+ const world = await getWorld();
+ // Single-build Worlds cannot proactively migrate an owner to another build.
+ if (world.capabilities?.deploymentAffinity !== true) return { status: "unsupported" };
+ let hook;
+ try {
+ hook = await getHookByToken(sessionInboxHookToken(sessionCommandHookToken(sessionId)));
+ } catch (error) {
+ if (HookNotFoundError.is(error)) return { status: "no_active_session" };
+ throw error;
+ }
+ const owner = await world.runs.get(hook.runId, { resolveData: "none" });
+ if (owner.status !== "running" && owner.status !== "pending")
+ return { status: "no_active_session" };
+ if (owner.deploymentId === targetDeploymentId) return { status: "ready" };
+ // Never wake an older owner with an inbox payload it cannot decode.
+ if (owner.attributes[EVE_PREWARM_ATTRIBUTE] !== "1") return { status: "unsupported" };
+ await resumeSessionInbox(
+ { sessionId },
+ { kind: "session-prewarm", expectedOwnerRunId: hook.runId, targetDeploymentId },
+ );
+ return { status: "accepted" };
+}
diff --git a/packages/eve/src/execution/session-stranded.integration.test.ts b/packages/eve/src/execution/session-stranded.integration.test.ts
index 52812ea1e..64a36e912 100644
--- a/packages/eve/src/execution/session-stranded.integration.test.ts
+++ b/packages/eve/src/execution/session-stranded.integration.test.ts
@@ -186,6 +186,10 @@ function httpAddress(runtime: Runtime, continuationToken: string) {
async function resetSession(runtime: Runtime, sessionId: string | undefined): Promise<void> {
if (sessionId === undefined) return;
await runtime.dispatchSession({ command: { kind: "reset" }, sessionId });
+ // Keep the World through shutdown without reading result data, which may already have expired.
+ await vi.waitFor(async () => {
+ expect(["completed", "cancelled", "failed"]).toContain(await getRun(sessionId).status);
+ });
}
describe("stranded sessions", () => {
diff --git a/packages/eve/src/execution/session/admission.ts b/packages/eve/src/execution/session/admission.ts
index 421d0f730..f00e5e4b0 100644
--- a/packages/eve/src/execution/session/admission.ts
+++ b/packages/eve/src/execution/session/admission.ts
@@ -52,6 +52,10 @@ export async function admitSessionInboxPayload(
}
switch (command.kind) {
+ case "session-prewarm":
+ if (command.expectedOwnerRunId === getWorkflowMetadata().workflowRunId)
+ input.queue.prepareOnDeployment(command.targetDeploymentId);
+ return { kind: "consumed" };
case "deliver": {
const admission = input.queue.enqueueDelivery(command);
return admission === undefined ? { kind: "consumed" } : { admission, kind: "delivery" };
diff --git a/packages/eve/src/execution/session/checkpoint-migrations.ts b/packages/eve/src/execution/session/checkpoint-migrations.ts
index ff89467d8..08fc0e26d 100644
--- a/packages/eve/src/execution/session/checkpoint-migrations.ts
+++ b/packages/eve/src/execution/session/checkpoint-migrations.ts
@@ -116,6 +116,8 @@ const CHECKPOINT_UPGRADES: Readonly<
},
// Older owners have never admitted keyed deliveries.
15: (checkpoint) => ({ ...checkpoint, admittedDeliveryKeys: [] }),
+ // Older targets cannot preserve an idle deadline during proactive preparation.
+ 16: (checkpoint) => checkpoint,
};
/**
diff --git a/packages/eve/src/execution/session/entry-input.ts b/packages/eve/src/execution/session/entry-input.ts
index 8a0ad2727..206f3585c 100644
--- a/packages/eve/src/execution/session/entry-input.ts
+++ b/packages/eve/src/execution/session/entry-input.ts
@@ -35,17 +35,18 @@ export type SessionHandoffStart =
}
| {
/**
- * The previous owner compacted the session and moved it to a fresh run on
- * its own deployment, so no single run's event log grows with the
- * session.
+ * The previous owner rotated an idle session after compaction or prepared
+ * it on the deployment accepting the next interaction.
*/
- readonly reason: "compaction";
+ readonly reason: "compaction" | "prewarm";
/**
* Only sources older than version 3 send one: the lone delivery that
* arrived before they could move, processed first. Without one, the
* successor parks until the next input arrives.
*/
readonly delivery?: DeliverHookPayload;
+ /** Proactive preparation preserves the current idle deadline. */
+ readonly sessionTimeoutDeadline?: Date;
};
/** A successor owner started by a previous owner during a handoff. */
diff --git a/packages/eve/src/execution/session/entry-prewarm.integration.test.ts b/packages/eve/src/execution/session/entry-prewarm.integration.test.ts
new file mode 100644
index 000000000..f8d92261c
--- /dev/null
+++ b/packages/eve/src/execution/session/entry-prewarm.integration.test.ts
@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AnyEventRequest } from "@workflow/world";
+import { hydrateStepReturnValue, hydrateWorkflowArguments } from "@workflow/core/serialization";
+import { startSessionOwner } from "#internal/testing/workflow-test-helpers.js";
+import { createTestRuntime } from "#internal/testing/app-harness.js";
+import { captureTurnEvents } from "#internal/testing/events.js";
+import { buildSerializedContext, handoffFollowUp } from "#internal/testing/entry-test-helpers.js";
+import { waitForParkedTurnStep } from "#internal/testing/session-test-helpers.js";
+import { workflowEntry } from "#execution/session/entry.js";
+import { getWorld, resumeHook } from "#internal/workflow/runtime.js";
+import {
+ sessionCommandHookToken,
+ sessionInboxHookToken,
+} from "#execution/session-inbox/address.js";
+import { createWorkflowRuntime, waitForCommandHookOwner } from "#execution/workflow-runtime.js";
+import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
+import { captureConsoleOutput, workflowSdkNotice } from "#internal/testing/log-records.js";
+
+async function deadline(runId: string): Promise<Date> {
+ const world = await getWorld();
+ let result: Date | undefined;
+ await vi.waitFor(async () => {
+ const steps = await world.steps.list({ runId, resolveData: "all" });
+ const start = steps.data.find((step) => step.stepName.endsWith("//startSessionTimeoutStep"));
+ expect(start?.output).toBeDefined();
+ const timer = (await hydrateStepReturnValue(start!.output, runId, undefined)) as {
+ runId: string;
+ };
+ const run = await world.runs.get(timer.runId, { resolveData: "all" });
+ const [input] = (await hydrateWorkflowArguments(run.input, run.runId, undefined)) as [
+ { deadline: Date },
+ ];
+ result = input.deadline;
+ expect(result).toBeInstanceOf(Date);
+ });
+ return result!;
+}
+
+describe("idle session prewarm handoff", () => {
+ it("delivers a message exactly once when Send arrives while the successor starts", async () => {
+ const output = captureConsoleOutput();
+ const runtime = await createTestRuntime({ agent: { name: "typing-successor-race" } });
+ await runtime.run(async () => {
+ const anchor = await startSessionOwner(workflowEntry, [
+ {
+ kind: "initial",
+ ownerDeploymentId: "dpl_a",
+ sessionTimeoutMs: false,
+ input: {},
+ serializedContext: buildSerializedContext({
+ acceptedDeploymentId: "dpl_a",
+ channelKind: "http",
+ }),
+ },
+ ]);
+ const stream = captureTurnEvents(anchor);
+ const world = await getWorld();
+ const workflowRuntime = createWorkflowRuntime({
+ compiledArtifactsSource: createBundledRuntimeCompiledArtifactsSource(),
+ });
+ const token = sessionInboxHookToken(sessionCommandHookToken(anchor.runId));
+ const createBatch = world.events.createBatch;
+ world.events.createBatch = undefined;
+ const createEvent = world.events.create.bind(world.events);
+ let sending: Promise<unknown> | undefined;
+ const spy = vi.spyOn(world.events, "create").mockImplementation(async (...args) => {
+ const [runId] = args;
+ const event = args[1] as AnyEventRequest;
+ if (
+ sending === undefined &&
+ runId !== anchor.runId &&
+ event.eventType === "run_created" &&
+ event.eventData.deploymentId === "dpl_b"
+ ) {
+ sending = workflowRuntime.dispatchSession({
+ sessionId: anchor.runId,
+ command: handoffFollowUp("dpl_b", "Alice writes during preparation.", "typing-race"),
+ });
+ await sending;
+ }
+ return await createEvent(...args);
+ });
+ try {
+ await waitForCommandHookOwner(token);
+ await resumeHook(token, {
+ kind: "session-prewarm",
+ expectedOwnerRunId: anchor.runId,
+ targetDeploymentId: "dpl_b",
+ });
+ const events = await stream.nextTurn();
+ expect(sending).toBeDefined();
+ await expect(sending).resolves.toMatchObject({
+ status: "accepted",
+ sessionId: anchor.runId,
+ });
+ expect(
+ events.filter(
+ (event) =>
+ event.type === "message.received" &&
+ event.data.message === "Alice writes during preparation.",
+ ),
+ ).toHaveLength(1);
+ expect(
+ events.some(
+ (event) =>
+ event.type === "message.completed" &&
+ event.data.message?.includes("Alice writes") === true,
+ ),
+ ).toBe(true);
+ expect((await waitForCommandHookOwner(token)).runId).not.toBe(anchor.runId);
+ await workflowRuntime.dispatchSession({
+ sessionId: anchor.runId,
+ command: { kind: "reset" },
+ });
+ await anchor.returnValue;
+ } finally {
+ spy.mockRestore();
+ world.events.createBatch = createBatch;
+ stream.dispose();
+ if ((await world.runs.get(anchor.runId)).status === "running") await anchor.cancel();
+ }
+ });
+ expect(output.unexpected(workflowSdkNotice.unpinnedDelivery)).toEqual([]);
+ });
+ it.each([false, true])(
+ "moves before Send, preserves expiry and stream, and ignores stale hints (conversation: %s)",
+ async (conversation) => {
+ const output = captureConsoleOutput();
+ const runtime = await createTestRuntime({ agent: { name: "typing-prewarm" } });
+ await runtime.run(async () => {
+ const anchor = await startSessionOwner(workflowEntry, [
+ {
+ kind: "initial",
+ ownerDeploymentId: "dpl_a",
+ sessionTimeoutMs: 60_000,
+ input: conversation ? { message: "Alice records the research milestone." } : {},
+ serializedContext: buildSerializedContext({
+ acceptedDeploymentId: "dpl_a",
+ channelKind: "http",
+ }),
+ },
+ ]);
+ const stream = captureTurnEvents(anchor);
+ const world = await getWorld();
+ const workflowRuntime = createWorkflowRuntime({
+ compiledArtifactsSource: createBundledRuntimeCompiledArtifactsSource(),
+ });
+ const token = sessionInboxHookToken(sessionCommandHookToken(anchor.runId));
+ let successorId: string | undefined;
+ try {
+ await waitForCommandHookOwner(token);
+ if (conversation) {
+ await stream.nextTurn();
+ await waitForParkedTurnStep(anchor.runId);
+ }
+ const originalDeadline = await deadline(anchor.runId);
+ await resumeHook(token, {
+ kind: "session-prewarm",
+ expectedOwnerRunId: "wrun_stale",
+ targetDeploymentId: "dpl_c",
+ });
+ await resumeHook(token, {
+ kind: "session-prewarm",
+ expectedOwnerRunId: anchor.runId,
+ targetDeploymentId: "dpl_b",
+ });
+ await vi.waitFor(
+ async () => {
+ successorId = (await waitForCommandHookOwner(token)).runId;
+ expect(successorId).not.toBe(anchor.runId);
+ },
+ { timeout: 10_000 },
+ );
+ const preparedDeadline = await deadline(successorId!);
+ if (conversation) {
+ // Completed turns extend the idle window; preparation itself must not renew it.
+ expect(preparedDeadline.getTime()).toBeGreaterThanOrEqual(originalDeadline.getTime());
+ const successor = await world.runs.get(successorId!);
+ expect(preparedDeadline.getTime()).toBeLessThan(successor.createdAt.getTime() + 60_000);
+ } else {
+ expect(preparedDeadline).toEqual(originalDeadline);
+ }
+ const steps = await world.steps.list({ runId: successorId! });
+ expect(
+ steps.data.some(
+ (step) =>
+ step.stepName.includes("invokeAgent") || step.stepName.endsWith("//runTurnStep"),
+ ),
+ ).toBe(false);
+ // A retry inspected before handoff must not move the successor backwards.
+ await resumeHook(token, {
+ kind: "session-prewarm",
+ expectedOwnerRunId: anchor.runId,
+ targetDeploymentId: "dpl_c",
+ });
+ await workflowRuntime.dispatchSession({
+ sessionId: anchor.runId,
+ command: handoffFollowUp(
+ "dpl_b",
+ "Alice confirms the research milestone.",
+ "typing-next",
+ ),
+ });
+ const events = await stream.nextTurn();
+ expect(
+ events.some(
+ (event) =>
+ event.type === "message.completed" &&
+ event.data.message?.includes("Alice confirms") === true,
+ ),
+ ).toBe(true);
+ expect((await waitForCommandHookOwner(token)).runId).toBe(successorId);
+ expect(await deadline(successorId!)).toEqual(preparedDeadline);
+ await workflowRuntime.dispatchSession({
+ sessionId: anchor.runId,
+ command: { kind: "reset" },
+ });
+ await expect(anchor.returnValue).resolves.toEqual({ output: "" });
+ } finally {
+ stream.dispose();
+ if ((await world.runs.get(anchor.runId)).status === "running") await anchor.cancel();
+ }
+ });
+ expect(output.unexpected(workflowSdkNotice.unpinnedDelivery)).toEqual([]);
+ },
+ );
+});
diff --git a/packages/eve/src/execution/session/entry.ts b/packages/eve/src/execution/session/entry.ts
index 45e90d8ed..f2448f179 100644
--- a/packages/eve/src/execution/session/entry.ts
+++ b/packages/eve/src/execution/session/entry.ts
@@ -454,6 +454,7 @@ async function startSuccessor(
sessionId,
sessionState: checkpoint.sessionState,
sessionTimeoutControl: createSessionTimeoutControl({
+ deadline: input.reason === "prewarm" ? input.sessionTimeoutDeadline : undefined,
sessionId,
timeoutMs: checkpoint.sessionTimeoutMs,
}),
diff --git a/packages/eve/src/execution/session/handoff-steps.ts b/packages/eve/src/execution/session/handoff-steps.ts
index 99d10ccdc..844171623 100644
--- a/packages/eve/src/execution/session/handoff-steps.ts
+++ b/packages/eve/src/execution/session/handoff-steps.ts
@@ -36,6 +36,7 @@ import { resolveInstalledPackageInfo } from "#internal/application/package.js";
import {
EVE_SESSION_ATTRIBUTE,
EVE_VERSION_ATTRIBUTE,
+ EVE_PREWARM_ATTRIBUTE,
} from "#execution/eve-workflow-attributes.js";
import { getResolvedRuntimeAgentNode } from "#runtime/graph.js";
import { owningSandboxDefinition } from "#runtime/sandbox/registry.js";
@@ -283,6 +284,7 @@ async function recordSessionOwner(sessionId: string): Promise<void> {
await setAttributes(
{
[EVE_SESSION_ATTRIBUTE]: sessionId,
+ [EVE_PREWARM_ATTRIBUTE]: "1",
[EVE_VERSION_ATTRIBUTE]: resolveInstalledPackageInfo().version,
},
{ allowReservedAttributes: true },
diff --git a/packages/eve/src/execution/session/handoff.ts b/packages/eve/src/execution/session/handoff.ts
index 3e885e30f..6b42cf5f5 100644
--- a/packages/eve/src/execution/session/handoff.ts
+++ b/packages/eve/src/execution/session/handoff.ts
@@ -42,7 +42,7 @@ import { isObject } from "#shared/guards.js";
* A newer successor must always accept older checkpoints: every bump adds the
* upgrade from the previous version in `checkpoint-migrations.ts`.
*/
-export const SESSION_CHECKPOINT_VERSION = 16;
+export const SESSION_CHECKPOINT_VERSION = 17;
/** Everything a successor needs to continue an idle session. Hooks are derived from the state. */
export interface SessionCheckpoint {
@@ -273,6 +273,21 @@ export class SessionHandoff {
return await this.transfer(state, deploymentId, { reason: "compaction" });
}
+ async tryPrewarmTransfer(
+ state: SessionTransferState,
+ targetDeploymentId: string,
+ sessionTimeoutDeadline: Date | undefined,
+ ): Promise<SessionTransferOutcome> {
+ if (targetDeploymentId === this.input.deploymentId)
+ return { kind: "retained", reason: "same-deployment" };
+ if (this.incompatibleTargetDeploymentIds.has(targetDeploymentId))
+ return { kind: "retained", reason: "known-incompatible" };
+ return await this.transfer(state, targetDeploymentId, {
+ reason: "prewarm",
+ sessionTimeoutDeadline,
+ });
+ }
+
private async transfer(
state: SessionTransferState,
targetDeploymentId: string,
diff --git a/packages/eve/src/execution/session/input-queue.ts b/packages/eve/src/execution/session/input-queue.ts
index 118846a6d..cf3ca7f25 100644
--- a/packages/eve/src/execution/session/input-queue.ts
+++ b/packages/eve/src/execution/session/input-queue.ts
@@ -55,6 +55,16 @@ export class SessionInputQueue {
private readonly entries: QueuedSessionInput[] = [];
private readonly admittedKeys: Set<string>;
private nextSequence = 0;
+ private prewarmDeploymentId: string | undefined;
+
+ prepareOnDeployment(deploymentId: string): void {
+ this.prewarmDeploymentId = deploymentId;
+ }
+ takePrewarmDeployment(): string | undefined {
+ const target = this.prewarmDeploymentId;
+ this.prewarmDeploymentId = undefined;
+ return target;
+ }
constructor(admittedDeliveryKeys: readonly string[]) {
this.admittedKeys = new Set(admittedDeliveryKeys);
@@ -85,6 +95,8 @@ export class SessionInputQueue {
this.admittedKeys.delete(this.admittedKeys.values().next().value!);
}
}
+ // A real message supersedes any speculative hint.
+ this.prewarmDeploymentId = undefined;
const admission = { delivery, sequence: this.nextSequence++ };
this.entries.push({ ...admission, kind: "delivery" });
return admission;
diff --git a/packages/eve/src/execution/session/next-input.ts b/packages/eve/src/execution/session/next-input.ts
index d18ca12b7..22b98d8a5 100644
--- a/packages/eve/src/execution/session/next-input.ts
+++ b/packages/eve/src/execution/session/next-input.ts
@@ -12,6 +12,7 @@ import type { SessionStateCursor } from "#execution/session/state-cursor.js";
import type { WorkflowToolRunMessage } from "#execution/tools/workflow/messages.js";
export type NextTurnInstruction =
+ | { readonly kind: "prewarm"; readonly targetDeploymentId: string }
| { readonly kind: "workflow"; readonly message: WorkflowToolRunMessage }
| { readonly kind: SessionControl }
| { readonly kind: "closed" }
@@ -46,6 +47,11 @@ export async function nextTurnDelivery(input: {
return routed;
}
+ if (!inbox.hasPending()) {
+ const targetDeploymentId = queue.takePrewarmDeployment();
+ if (targetDeploymentId !== undefined) return { kind: "prewarm", targetDeploymentId };
+ }
+
// A delivery may already be in the pump queue by the time the owner exits
// its committed waiting step. It is still an idle arrival when no earlier
// input was admitted; the post-read `hasPending()` check below rejects a
diff --git a/packages/eve/src/execution/session/program.ts b/packages/eve/src/execution/session/program.ts
index 2585bdfaa..3aff59e51 100644
--- a/packages/eve/src/execution/session/program.ts
+++ b/packages/eve/src/execution/session/program.ts
@@ -225,7 +225,8 @@ async function runSessionLoop(
const sessionTimeout = boot.sessionTimeoutControl;
const nextParkedActivity = async (): Promise<
- Exclude<NextTurnInstruction, { kind: "workflow" | "cancel-working-tasks" }>
+ | Exclude<NextTurnInstruction, { kind: "workflow" | "cancel-working-tasks" | "prewarm" }>
+ | { readonly kind: "transferred" }
> => {
while (true) {
const next = await nextTurnDelivery({
@@ -234,6 +235,23 @@ async function runSessionLoop(
inbox,
queue,
});
+ if (next.kind === "prewarm") {
+ if (
+ progress.caller === undefined &&
+ workingTasks(sessionTaskTable(cursor)).length === 0 &&
+ queue.pendingCount === 0 &&
+ !inbox.hasPending()
+ ) {
+ const deadline = sessionTimeout?.getDeadline();
+ const result = await handoff.tryPrewarmTransfer(
+ transferState(),
+ next.targetDeploymentId,
+ deadline,
+ );
+ if (result.kind === "transferred") return result;
+ }
+ continue;
+ }
if (next.kind === "workflow") {
await execution.handleWorkflowMessage(next.message);
continue;
@@ -312,6 +330,8 @@ async function runSessionLoop(
// Taken over outside an attempt: the new owner now writes the stream.
if (inbox.takenOver) return await handoff.adoptTakeover();
return { kind: "terminal", outcome: { kind: "expired" } };
+ case "transferred":
+ return next;
case "expired":
case "reset":
return { kind: "terminal", outcome: { kind: "expired" } };
@@ -386,6 +406,8 @@ async function runSessionLoop(
// Taken over outside an attempt: the new owner now writes the stream.
if (inbox.takenOver) return await handoff.adoptTakeover();
return { kind: "terminal", outcome: { kind: "expired" } };
+ case "transferred":
+ return next;
case "expired":
case "reset":
return { kind: "terminal", outcome: { kind: "expired" } };
diff --git a/packages/eve/src/execution/session/timeout-control.test.ts b/packages/eve/src/execution/session/timeout-control.test.ts
index 87b6030de..0c8b524da 100644
--- a/packages/eve/src/execution/session/timeout-control.test.ts
+++ b/packages/eve/src/execution/session/timeout-control.test.ts
@@ -53,6 +53,28 @@ describe("createSessionTimeoutControl", () => {
});
});
+ it("preserves an inherited idle deadline until real activity renews it", async () => {
+ const deadline = new Date(BOOT.getTime() + 20_000);
+ vi.mocked(startSessionTimeoutStep).mockResolvedValue({ runId: "timer-run" });
+ const control = createSessionTimeoutControl({
+ deadline,
+ sessionId: "wrun_1",
+ timeoutMs: TIMEOUT_MS,
+ })!;
+ expect(control.getDeadline()).toEqual(deadline);
+ await control.start();
+ expect(startSessionTimeoutStep).toHaveBeenCalledWith(expect.objectContaining({ deadline }));
+ vi.setSystemTime(deadline);
+ await expect(control.handleTimerElapsed()).resolves.toBe("expired");
+
+ control.recordActivity();
+ expect(control.getDeadline()).toEqual(new Date(deadline.getTime() + TIMEOUT_MS));
+ await expect(control.handleTimerElapsed()).resolves.toBe("extended");
+ expect(startSessionTimeoutStep).toHaveBeenLastCalledWith(
+ expect.objectContaining({ deadline: new Date(deadline.getTime() + TIMEOUT_MS) }),
+ );
+ });
+
it("extends the deadline from the latest activity instead of expiring", async () => {
vi.mocked(startSessionTimeoutStep)
.mockResolvedValueOnce({ runId: "timer-1" })
diff --git a/packages/eve/src/execution/session/timeout-control.ts b/packages/eve/src/execution/session/timeout-control.ts
index 75d6c7cfb..217ab09ff 100644
--- a/packages/eve/src/execution/session/timeout-control.ts
+++ b/packages/eve/src/execution/session/timeout-control.ts
@@ -14,6 +14,8 @@ import { sessionCommandHookToken } from "#execution/session-inbox/address.js";
* per turn.
*/
export interface SessionTimeoutControl {
+ /** Current idle deadline, including activity since the durable timer was armed. */
+ getDeadline(): Date;
dispose(): Promise<void>;
/**
* Answers this owner's elapsed timer: `expired` once the session has been
@@ -28,6 +30,8 @@ export interface SessionTimeoutControl {
/** Creates the idle timeout for one owner run, or `undefined` when timeouts are disabled. */
export function createSessionTimeoutControl(input: {
+ /** Preserve the idle window when proactively moving an existing session. */
+ readonly deadline?: Date;
readonly sessionId: string;
readonly timeoutMs: number | false;
}): SessionTimeoutControl | undefined {
@@ -36,7 +40,8 @@ export function createSessionTimeoutControl(input: {
// Workflow's clock is replay-stable. An owner boots right after activity:
// the session's creation, the delivery a successor runs, or the turn that
// compacted before a successor took over.
- let lastActivityAt = Date.now();
+ let lastActivityAt =
+ input.deadline === undefined ? Date.now() : input.deadline.getTime() - timeoutMs;
let active: { readonly runId: string } | undefined;
let startup: Promise<void> | undefined;
@@ -52,6 +57,10 @@ export function createSessionTimeoutControl(input: {
};
return {
+ getDeadline(): Date {
+ return new Date(lastActivityAt + timeoutMs);
+ },
+
async dispose(): Promise<void> {
try {
await startup;
diff --git a/packages/eve/src/execution/workflow-runtime.test.ts b/packages/eve/src/execution/workflow-runtime.test.ts
index 80e93ee41..186e85ce8 100644
--- a/packages/eve/src/execution/workflow-runtime.test.ts
+++ b/packages/eve/src/execution/workflow-runtime.test.ts
@@ -587,6 +587,7 @@ describe("createWorkflowRuntime#createSession", () => {
attributes: {
"$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.prewarm": "1",
"$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
@@ -788,6 +789,7 @@ describe("createWorkflowRuntime#createSession", () => {
"$eve.channel_request_id": "req_run",
"$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.prewarm": "1",
"$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
@@ -833,6 +835,7 @@ describe("createWorkflowRuntime#createSession", () => {
"$eve.parent": "parent-session",
"$eve.parent_call": "call-1",
"$eve.parent_turn": "turn-1",
+ "$eve.prewarm": "1",
"$eve.root": "root-session",
"$eve.subagent": "researcher",
"$eve.is_trace_content_visible": "false",
@@ -862,6 +865,7 @@ describe("createWorkflowRuntime#createSession", () => {
attributes: {
"$eve.is_otel_trace_enabled": "false",
"$eve.is_trace_content_visible": "false",
+ "$eve.prewarm": "1",
"$eve.title": "hello",
"$eve.trigger": "http",
"$eve.type": "session",
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index e5564e9b6..0c326a45b 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -1,3 +1,4 @@
+import { prewarmWorkflowSession } from "#execution/session-prewarm.js";
import { validateToolStubTargets } from "#tool-stubs/validate-targets.js";
import { validateDeliveryIdempotencyKey } from "#channel/delivery-idempotency.js";
import { context, trace } from "#compiled/@opentelemetry/api/index.js";
@@ -23,6 +24,7 @@ import {
buildSessionAttributes,
buildSubagentRootAttributes,
EVE_VERSION_ATTRIBUTE,
+ EVE_PREWARM_ATTRIBUTE,
readParentLineage,
} from "#execution/eve-workflow-attributes.js";
import { resolveInstalledPackageInfo } from "#internal/application/package.js";
@@ -208,6 +210,7 @@ export function createWorkflowRuntime(config: {
});
const attributes = {
...sessionAttributes,
+ [EVE_PREWARM_ATTRIBUTE]: "1",
...(input.externalInvocation === undefined
? {}
: buildInvocationAttributes(input.externalInvocation)),
@@ -328,6 +331,13 @@ async function dispatchWorkflowCommand<TCommand extends SessionCommand>(
token: string | SessionInboxAddress,
command: TCommand,
): Promise<SessionCommandResult<TCommand>> {
+ if (command.kind === "prewarm") {
+ return (
+ typeof token === "string"
+ ? { status: "unsupported" }
+ : await prewarmWorkflowSession(token.sessionId, command.targetDeploymentId)
+ ) as SessionCommandResult<TCommand>;
+ }
let hook: SessionInboxOwnerRecord;
try {
const resumed = await resumeSessionInbox(token, command);
diff --git a/packages/eve/src/protocol/prewarm-session.ts b/packages/eve/src/protocol/prewarm-session.ts
new file mode 100644
index 000000000..4409a5ccb
--- /dev/null
+++ b/packages/eve/src/protocol/prewarm-session.ts
@@ -0,0 +1,9 @@
+import { z } from "#compiled/zod/index.js";
+/** Acceptance is durable, but does not mean the successor has activated. */
+export type PrewarmSessionResult = {
+ readonly status: "ready" | "accepted" | "unsupported" | "no_active_session";
+};
+export const PrewarmResponseSchema = z.object({
+ ok: z.literal(true),
+ status: z.enum(["ready", "accepted", "unsupported", "no_active_session"]),
+});
diff --git a/packages/eve/src/protocol/routes.ts b/packages/eve/src/protocol/routes.ts
index 2773bf5e8..27e083103 100644
--- a/packages/eve/src/protocol/routes.ts
+++ b/packages/eve/src/protocol/routes.ts
@@ -22,7 +22,7 @@ export const EVE_INFO_ROUTE_PATH = `${EVE_ROUTE_PREFIX}/info`;
/** Stable route for creating ID-addressed sessions. */
export const EVE_SESSION_ROUTE_PATH = `${EVE_ROUTE_PREFIX}/session`;
-/** Stable route pattern for sending a message to one exact session ID. */
+/** Stable route pattern for preparing or delivering input to one exact session ID. */
export const EVE_SESSION_ROUTE_PATTERN = `${EVE_SESSION_ROUTE_PATH}/:sessionId`;
/** Stable route pattern for cancelling one exact session ID. */
@@ -118,7 +118,7 @@ export const EVE_CONNECTION_CALLBACK_ROUTE_PATTERN = `${EVE_ROUTE_PREFIX}/connec
*/
export const EVE_CALLBACK_ROUTE_PATTERN = `${EVE_ROUTE_PREFIX}/callback/:token`;
-/** Builds the ID-addressed message route for one session. */
+/** Builds the ID-addressed preparation and input route for one session. */
export function createEveSessionRoutePath(sessionId: string): string {
return `${EVE_SESSION_ROUTE_PATH}/${encodeURIComponent(sessionId)}`;
}
diff --git a/packages/eve/src/public/channels/eve-session-routes.test.ts b/packages/eve/src/public/channels/eve-session-routes.test.ts
index 642fb6bbf..9dba6535f 100644
--- a/packages/eve/src/public/channels/eve-session-routes.test.ts
+++ b/packages/eve/src/public/channels/eve-session-routes.test.ts
@@ -30,6 +30,7 @@ function createFixedSession(overrides: Partial<Session> = {}): Session {
send: vi.fn().mockResolvedValue({ sessionId: "wrun_A", status: "accepted" }),
respond: vi.fn().mockResolvedValue({ sessionId: "wrun_A", status: "accepted" }),
cancel: vi.fn().mockResolvedValue({ sessionId: "wrun_A", status: "accepted" }),
+ prewarm: vi.fn().mockResolvedValue({ status: "accepted" }),
compact: vi.fn().mockResolvedValue({ sessionId: "wrun_A", status: "accepted" }),
clear: vi.fn().mockResolvedValue({ sessionId: "wrun_A", status: "accepted" }),
reset: vi.fn().mockResolvedValue({ previousSessionId: "wrun_A", status: "reset" }),
@@ -52,6 +53,57 @@ function createArgs(session = createFixedSession()): RouteHandlerArgs {
}
describe("eve ID-addressed session routes", () => {
+ it("does not prepare a session when resource authentication rejects the request", async () => {
+ const session = createFixedSession();
+ const response = await route("POST", "/eve/v1/session/:sessionId", {
+ auth: () => null,
+ })(
+ new Request("https://eve.test/eve/v1/session/wrun_A", { method: "POST" }),
+ createArgs(session),
+ );
+ expect(response.status).toBe(401);
+ expect(session.prewarm).not.toHaveBeenCalled();
+ });
+ it.each([undefined, "{}"])(
+ "prepares the authenticated fixed session without starting a turn, with body %s",
+ async (body) => {
+ const session = createFixedSession();
+ const onMessage = vi.fn();
+ const response = await route("POST", "/eve/v1/session/:sessionId", {
+ auth: none(),
+ onMessage,
+ })(
+ new Request("https://eve.test/eve/v1/session/wrun_A", { method: "POST", body }),
+ createArgs(session),
+ );
+ expect(response.status).toBe(202);
+ await expect(response.json()).resolves.toEqual({ ok: true, status: "accepted" });
+ expect(session.prewarm).toHaveBeenCalledOnce();
+ expect(onMessage).not.toHaveBeenCalled();
+ expect(session.send).not.toHaveBeenCalled();
+ expect(session.respond).not.toHaveBeenCalled();
+ },
+ );
+ it.each([
+ ["deployment-only payload", '{"targetDeploymentId":"dpl_injected"}'],
+ ["empty message", '{"message":""}'],
+ ["invalid message", '{"message":null}'],
+ ["empty input responses", '{"inputResponses":[]}'],
+ ["continuation token", '{"continuationToken":"wrun_B"}'],
+ ["malformed JSON", "{"],
+ ["non-object JSON", "[]"],
+ ])("rejects %s rather than treating it as preparation", async (_description, body) => {
+ const session = createFixedSession();
+ const response = await route("POST", "/eve/v1/session/:sessionId")(
+ new Request("https://eve.test/eve/v1/session/wrun_A", { method: "POST", body }),
+ createArgs(session),
+ );
+ expect(response.status).toBe(400);
+ expect(session.prewarm).not.toHaveBeenCalled();
+ expect(session.send).not.toHaveBeenCalled();
+ expect(session.respond).not.toHaveBeenCalled();
+ });
+
it.each([
["without a request body", undefined],
["with an empty JSON object", "{}"],
diff --git a/packages/eve/src/public/channels/eve-subagent-stream.test.ts b/packages/eve/src/public/channels/eve-subagent-stream.test.ts
index 62cf60f63..1d1e57270 100644
--- a/packages/eve/src/public/channels/eve-subagent-stream.test.ts
+++ b/packages/eve/src/public/channels/eve-subagent-stream.test.ts
@@ -236,6 +236,9 @@ function createHarness(input: {
async cancel() {
return { status: "no_active_turn" };
},
+ async prewarm() {
+ return { status: "ready" as const };
+ },
async compact() {
return { sessionId: coordinates.parentSessionId, status: "accepted" };
},
diff --git a/packages/eve/src/public/channels/eve.test.ts b/packages/eve/src/public/channels/eve.test.ts
index ed6d1faef..59ea10edc 100644
--- a/packages/eve/src/public/channels/eve.test.ts
+++ b/packages/eve/src/public/channels/eve.test.ts
@@ -82,6 +82,7 @@ function createMockSession(overrides: Partial<Session> = {}): Session {
send: vi.fn().mockResolvedValue({ sessionId: "test-session-id", status: "accepted" }),
respond: vi.fn().mockResolvedValue({ sessionId: "test-session-id", status: "accepted" }),
cancel: vi.fn().mockResolvedValue({ status: "no_active_turn" }),
+ prewarm: vi.fn().mockResolvedValue({ status: "ready" }),
compact: vi.fn().mockResolvedValue({ sessionId: "test-session-id", status: "accepted" }),
clear: vi.fn().mockResolvedValue({ sessionId: "test-session-id", status: "accepted" }),
reset: vi.fn().mockResolvedValue({
diff --git a/packages/eve/src/public/definitions/channel.test.ts b/packages/eve/src/public/definitions/channel.test.ts
index 091a158b8..e3f3429c3 100644
--- a/packages/eve/src/public/definitions/channel.test.ts
+++ b/packages/eve/src/public/definitions/channel.test.ts
@@ -650,6 +650,9 @@ describe("defineChannel", () => {
async cancel() {
return { status: "no_active_turn" as const };
},
+ async prewarm() {
+ return { status: "ready" as const };
+ },
async compact() {
return { sessionId: channelId, status: "accepted" as const };
},
diff --git a/packages/eve/src/react/use-eve-agent.test.ts b/packages/eve/src/react/use-eve-agent.test.ts
index b53041018..39f97e015 100644
--- a/packages/eve/src/react/use-eve-agent.test.ts
+++ b/packages/eve/src/react/use-eve-agent.test.ts
@@ -241,6 +241,8 @@ describe("useEveAgent", () => {
it("prewarms when the option changes from false to true without replacing the session", async () => {
let creates = 0;
const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (_request, init) => {
+ if (String(_request) === "/eve/v1/session/session_1" && init?.method === "POST")
+ return Response.json({ ok: true, status: "ready" });
if (init?.method === "POST") return createStartedMessageResponse(`session_${++creates}`, "");
return createEagerStreamResponse([createSessionWaitingEvent(TEST_USAGE)]);
});
@@ -284,7 +286,7 @@ describe("useEveAgent", () => {
});
expect(creates).toBe(1);
- expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(fetchMock).toHaveBeenCalledTimes(3);
expect(agent?.session?.sessionId).toBe("session_1");
});
diff --git a/packages/eve/src/react/use-eve-agent.ts b/packages/eve/src/react/use-eve-agent.ts
index 60a770b6f..27a37331c 100644
--- a/packages/eve/src/react/use-eve-agent.ts
+++ b/packages/eve/src/react/use-eve-agent.ts
@@ -121,7 +121,7 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
*/
readonly followIdle?: boolean;
/**
- * Prewarm an owned session when true. React observes this value across renders;
+ * Create a session or prepare its existing idle owner when true. React observes this value across renders;
* changing it from false to true prepares the current session, and reset checks
* the latest rendered value before preparing the next session.
*
diff --git a/packages/eve/src/svelte/use-eve-agent.ts b/packages/eve/src/svelte/use-eve-agent.ts
index a478b31bc..6eac42f41 100644
--- a/packages/eve/src/svelte/use-eve-agent.ts
+++ b/packages/eve/src/svelte/use-eve-agent.ts
@@ -141,7 +141,7 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
* on the next send, answer, or resume. @default true
*/
readonly followIdle?: boolean;
- /** Prewarm an owned session on mount and after reset. @default false */
+ /** Create a session or prepare its existing idle owner on mount and after reset. @default false */
readonly prewarm?: boolean;
/**
* Projects stream events into `TData`. Defaults to the conversation reducer.
diff --git a/packages/eve/src/vue/use-eve-agent.ts b/packages/eve/src/vue/use-eve-agent.ts
index 75f2ff286..f1804d34c 100644
--- a/packages/eve/src/vue/use-eve-agent.ts
+++ b/packages/eve/src/vue/use-eve-agent.ts
@@ -139,7 +139,7 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
* on the next send, answer, or resume. @default true
*/
readonly followIdle?: boolean;
- /** Prewarm an owned session on mount and after reset. @default false */
+ /** Create a session or prepare its existing idle owner on mount and after reset. @default false */
readonly prewarm?: boolean;
/**
* Projects stream events into `TData`.
diff --git a/research/typing-session-prewarm.md b/research/typing-session-prewarm.md
new file mode 100644
index 000000000..0542caf1b
--- /dev/null
+++ b/research/typing-session-prewarm.md
@@ -0,0 +1,51 @@
+---
+issue: "Maintainer-requested implementation"
+status: implemented
+last_updated: "2026-10-13"
+---
+
+# Prepare idle sessions while composing
+
+Extend the existing `prewarm()` surface: create an unused session, or request a background
+handoff of an existing idle session to the exact deployment serving the request. Applications
+call it when typing starts; no second flag, webhook, project sweep, or promotion subscription
+is required. React's live `prewarm` option and the Vue/Svelte imperative helpers share it.
+
+The existing authenticated `POST /eve/v1/session/:sessionId` prepares the session with no
+body or `{}`. Non-empty bodies retain message and input-response validation and delivery;
+there is no separate preparation route. Ingress
+compares the current inbox owner's run deployment, avoiding a wake-up for the same owner.
+A reserved support attribute prevents sending new control payloads to older deployments.
+A differing supported owner receives a durable hint scoped to its run ID. The owner reuses
+its checkpoint, hook release, successor activation, and recovery protocol when idle. Real
+messages supersede hints; active work is not interrupted. Preparation preserves the public
+session ID, original stream, conversation history, and recorded timeout deadline.
+
+Acceptance is not activation. Existing-session preparation never blocks Send and failures
+leave the existing Send fallback usable. Immutable URLs and skew-pinned requests remain on
+their pinned deployment; production and preview aliases follow whichever deployment accepts
+the request. Non-affine Worlds and older owners safely skip preparation.
+
+Validation covers ingress rollout/no-op behavior, authenticated transport, client failures
+and Send races, and real Workflow owner transfer before a message with preserved expiry.
+The Evo clone exercises two deployments and real Gateway timing. Checkpoint version 15
+protects the new idle startup reason: older targets reject it instead of renewing expiry;
+version 14 state needs no changes when upgraded by a newer successor.
+
+Implemented on `codex/typing-session-prewarm`, based on main at `de7a408e4`.
+Validation passed after endpoint consolidation: 326 focused route, client, and React unit
+tests, repository typecheck, invariant guard, lint, and docs checks. Earlier validation
+covered three Workflow integration tests, package build, and clone build. The fixture-owned
+prewarm eval now uses the shared endpoint and runs in CI; it was not run locally.
+
+The controlled Evo clone experiment promoted A to B during an idle period, then compared
+three direct turns with three prepared turns for each cohort. Server POST-to-Gateway median
+fell from 3.139s to 0.756s for first turns and from 3.003s to 0.724s for follow-ups.
+Client Send-to-Gateway medians were 3.182s to 0.793s and 3.052s to 0.765s respectively;
+client timing uses a clock calibration with ±57.5ms uncertainty. All six
+prepared owners activated B before Send without new session events; all follow-ups retained
+history. A tab loaded on A prepared B on typing, and immediate Send during preparation
+succeeded. These are small clone samples, not production percentiles. Preparation moves
+handoff work before Send and needs a typing head start to hide it fully.
+These measurements used the preparation protocol before its HTTP endpoint was consolidated;
+the route change does not alter the transfer protocol, and the latency experiment was not rerun.