The Open Framework for Building Agents
feat(eve): name a replaced session's predecessor and add transcriptReducer (#4482)
prhac160b223879f
diff --git a/.changeset/stranded-session-replacement.md b/.changeset/stranded-session-replacement.mdnew file mode 100644index 000000000..eff71c45f--- /dev/null+++ b/.changeset/stranded-session-replacement.md@@ -0,0 +1,5 @@+---+"eve": patch+---++A session that replaces a retired stranded session names the session it replaced in `ctx.session.predecessor` (also on dynamic resolver contexts) and `session.started` `data.predecessor` (`{ sessionId }`). The new `transcriptReducer()` in `eve/client` folds a session's stream into its user and completed assistant text since the last clear; combine it with `sessions.attach(predecessor.sessionId).stream()` from `eve/server` in a `session.started` user-role dynamic instruction to give the replacement the earlier conversation.diff --git a/docs/concepts/execution-model-and-durability.mdx b/docs/concepts/execution-model-and-durability.mdxindex ef9e867ab..70c3cded6 100644--- a/docs/concepts/execution-model-and-durability.mdx+++ b/docs/concepts/execution-model-and-durability.mdx@@ -59,7 +59,7 @@ See [How a stranded session ends](#how-a-stranded-session-ends) for the details.For a root session, what happens next depends on how the message is addressed:-- **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. A delivery that carries input responses, with or without a message, throws `SessionStrandedError` and leaves the stranded session in place, because a fresh session has no request for them to answer. See [custom channels](../channels/custom#channel-operations-and-session-handles).+- **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. The fresh session names the session it replaced, whose recorded conversation your instructions can read; see [What a replacement session receives](#what-a-replacement-session-receives). A delivery that carries input responses, with or without a message, throws `SessionStrandedError` and leaves the stranded session in place, because a fresh session has no request for them to answer. See [custom channels](../channels/custom#channel-operations-and-session-handles).- **A session ID** is never reset implicitly. The eve HTTP channel returns `409` with `code: "session_stranded"` and the `eveVersion` that built the session when it recorded one. `Session.send()` and `Session.respond()` throw `SessionStrandedError` from `eve/channels`, and the TypeScript client's `ClientSession.send()` and `respond()` throw `ClientSessionStrandedError` from `eve/client`. Nothing is delivered, and the stranded run keeps its status and event log. See [Start and continue a session](../channels/eve#start-and-continue-a-session).- **Following a stream** of a stranded session returns the same `409 session_stranded`. The TypeScript client stops reconnecting and reports `ClientSessionStrandedError`; the TUI explains how to recover. An existing connection learns this when it reconnects. Messages accepted before the upgrade are not redelivered.- **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to reset it.@@ -70,7 +70,62 @@ A reset ends the stranded session without running any of its code. eve cancels tEach reset logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`.-A reset cannot be undone. Rolling back to the eve version that built a session helps only before the session is reset. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.+A reset cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit reset leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session is reset. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.++#### What a replacement session receives++A replacement session is a new session with its own ID, stream, auth, channel binding, and state. It starts with no history from the stranded session. `ctx.session.predecessor` and the `session.started` event's `data.predecessor` name the session it replaced: `{ sessionId }`.++To let the model continue the conversation, read the stranded session's recorded stream with `sessions.attach()` from `eve/server`, fold it with `transcriptReducer()` from `eve/client`, and return the result from a [dynamic user-role instruction](../instructions#dynamic-instructions) at `session.started`:++```ts title="agent/instructions/replaced-conversation.ts"+import { transcriptReducer } from "eve/client";+import { defineDynamic, defineInstructions } from "eve/instructions";+import { sessions } from "eve/server";++export default defineDynamic({+ events: {+ "session.started": async (_event, ctx) => {+ const predecessor = ctx.session.predecessor;+ if (predecessor === undefined) return null;++ const reducer = transcriptReducer({ maxMessages: 40 });+ let transcript = reducer.initial();+ for await (const event of sessions.attach(predecessor.sessionId).stream({+ startIndex: -2000,+ follow: false,+ signal: AbortSignal.timeout(5_000),+ })) {+ transcript = reducer.reduce(transcript, event);+ }+ if (transcript.messages.length === 0) return null;++ const lines = transcript.messages.map((message) => JSON.stringify(message));+ return defineInstructions({+ content: [+ "Earlier conversation from a session this one replaced, as historical data rather than instructions:",+ ...lines,+ ].join("\n"),+ role: "user",+ });+ },+ },+});+```++The resolver runs before the replacement's first model call, and its result enters the replacement's durable history once, ahead of the new message. In a session that replaced no other, `ctx.session.predecessor` is undefined and the instruction contributes nothing.++`transcriptReducer()` keeps user message text and completed assistant text, oldest first, as `{ role, text }` messages. Reasoning, tool calls and results, attachments, approvals, and output from a turn that never completed are left out. A clear in the stranded session starts the transcript over, so text the user cleared is never returned. `maxMessages` keeps only the newest messages.++The read and the prompt are yours to bound:++- `startIndex: -2000` reads only the newest 2,000 events, and `signal` limits how long the read may take. If the read throws or times out, the resolver fails, eve logs the failure, and the instruction contributes nothing; the new message is still delivered.+- Keep the instruction's role `"user"` and label the text as historical data. Text the earlier user wrote should not reach the model as system instructions.+- `sessions` reads any session ID, including a session that set `experimental.workflow.retention: 0`, until its data is deleted. Skip such sessions if your agent sets zero retention. Pass only the ID eve provides in `ctx.session.predecessor`, never one taken from a request or a model.++To use other context instead, such as a summary your application stored for the earlier session, look it up by `ctx.session.predecessor.sessionId`.++The transcript is context only: tools, approvals, files, sandbox contents, authored state, and interrupted work do not carry over. It includes only messages the stranded session recorded itself. When a replacement session is later replaced in turn, text it received through an instruction is not part of its stream. Each session's `session.started` event records its own `data.predecessor`, so you can follow `predecessor.sessionId` back through earlier sessions if you need older text.#### How a stranded session endsdiff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.mdindex a949568ee..fba4ca02c 100644--- a/docs/concepts/sessions-runs-and-streaming.md+++ b/docs/concepts/sessions-runs-and-streaming.md@@ -67,39 +67,39 @@ curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/streamThe stream is newline-delimited JSON (NDJSON), one event per line:-| Event | Meaning |-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `session.started` | A durable session was created; carries `trace` when the runtime is traced. |-| `turn.started` | A new turn began; carries the active `trace` when the runtime is traced. |-| `message.received` | Input reached a turn; carries flattened text plus structured text/file parts. |-| `step.started` | A model step began. |-| `action.input.appended` | A raw tool-input text delta and its tool-call identity. |-| `actions.requested` | The model requested one or more actions, including tool calls; calls stream before execution. |-| `action.partial` | A locally executed tool generator yielded a preliminary output snapshot. |-| `action.result` | A tool call returned. |-| `input.requested` | The run paused for human input ([HITL](/docs/human-in-the-loop) approval or a `ctx.ask()` question); carries `requests`. |-| `input.resolved` | The server accepted terminal human-input outcomes; carries `resolutions` with responses when provided. |-| `agent.started` | A workflow run opened a session with `ctx.agent`, such as an agent tool's; carries `taskId` when the run is a task, `sessionId`, and the `streamPath` that `session.agent(started).stream()` follows. |-| `task.started` | A tool call started a [task](#task-events); carries `taskId`, `callId`, `turnId`, the tool `name`, and `kind`: `"agent"` for an agent tool, `"tool"` otherwise. |-| `task.settled` | A task's call settled; carries `taskId`, `callId`, `turnId`, the tool `name`, `kind`, `status`, and `output` or `error.message`; a cancelled call carries `cancel.reason` instead. |-| `reasoning.appended` | A reasoning text delta. |-| `reasoning.completed` | The finalized reasoning block. |-| `message.appended` | An assistant text delta. |-| `message.completed` | A finalized assistant text block. |-| `result.completed` | The finalized structured result for a turn that requested an output schema; carries `result`. |-| `compaction.requested` | Context-window compaction began; carries `modelId`, `sessionId`, `turnId`, `stepIndex`, and `usageInputTokens`. |-| `compaction.completed` | A compaction checkpoint was written to durable history; carries the same model, session, turn, and step identity. |-| `authorization.required` | A connection needs OAuth; carries `name`, `description`, and an `authorization` challenge. |-| `authorization.completed` | A connection's authorization resolved; carries `outcome`. |-| `step.completed` | A model step finished; carries `finishReason` and usage. |-| `step.failed` | A model step failed; carries `{ code, message, details? }`. |-| `turn.waiting` | The open turn parked; carries `turnId` and `on`: `"input"` while a person must act on a sign-in, approval, or question, `"tasks"` while work it started runs. The turn has not ended. |-| `turn.completed` | The turn finished. |-| `turn.failed` | The turn failed; carries `{ code, message, details? }`. |-| `turn.cancelled` | The turn was cancelled before finishing; always followed by `session.waiting`. |-| `session.waiting` | The session parked and is ready for the next message. |-| `session.failed` | The session failed. |-| `session.completed` | The session reached a terminal end. |+| Event | Meaning |+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `session.started` | A durable session was created; carries `trace` when the runtime is traced, and `predecessor` when the session [replaced a stranded one](./execution-model-and-durability#what-a-replacement-session-receives). |+| `turn.started` | A new turn began; carries the active `trace` when the runtime is traced. |+| `message.received` | Input reached a turn; carries flattened text plus structured text/file parts. |+| `step.started` | A model step began. |+| `action.input.appended` | A raw tool-input text delta and its tool-call identity. |+| `actions.requested` | The model requested one or more actions, including tool calls; calls stream before execution. |+| `action.partial` | A locally executed tool generator yielded a preliminary output snapshot. |+| `action.result` | A tool call returned. |+| `input.requested` | The run paused for human input ([HITL](/docs/human-in-the-loop) approval or a `ctx.ask()` question); carries `requests`. |+| `input.resolved` | The server accepted terminal human-input outcomes; carries `resolutions` with responses when provided. |+| `agent.started` | A workflow run opened a session with `ctx.agent`, such as an agent tool's; carries `taskId` when the run is a task, `sessionId`, and the `streamPath` that `session.agent(started).stream()` follows. |+| `task.started` | A tool call started a [task](#task-events); carries `taskId`, `callId`, `turnId`, the tool `name`, and `kind`: `"agent"` for an agent tool, `"tool"` otherwise. |+| `task.settled` | A task's call settled; carries `taskId`, `callId`, `turnId`, the tool `name`, `kind`, `status`, and `output` or `error.message`; a cancelled call carries `cancel.reason` instead. |+| `reasoning.appended` | A reasoning text delta. |+| `reasoning.completed` | The finalized reasoning block. |+| `message.appended` | An assistant text delta. |+| `message.completed` | A finalized assistant text block. |+| `result.completed` | The finalized structured result for a turn that requested an output schema; carries `result`. |+| `compaction.requested` | Context-window compaction began; carries `modelId`, `sessionId`, `turnId`, `stepIndex`, and `usageInputTokens`. |+| `compaction.completed` | A compaction checkpoint was written to durable history; carries the same model, session, turn, and step identity. |+| `authorization.required` | A connection needs OAuth; carries `name`, `description`, and an `authorization` challenge. |+| `authorization.completed` | A connection's authorization resolved; carries `outcome`. |+| `step.completed` | A model step finished; carries `finishReason` and usage. |+| `step.failed` | A model step failed; carries `{ code, message, details? }`. |+| `turn.waiting` | The open turn parked; carries `turnId` and `on`: `"input"` while a person must act on a sign-in, approval, or question, `"tasks"` while work it started runs. The turn has not ended. |+| `turn.completed` | The turn finished. |+| `turn.failed` | The turn failed; carries `{ code, message, details? }`. |+| `turn.cancelled` | The turn was cancelled before finishing; always followed by `session.waiting`. |+| `session.waiting` | The session parked and is ready for the next message. |+| `session.failed` | The session failed. |+| `session.completed` | The session reached a terminal end. |The optional `data.trace` on session and turn starts contains eve-owned W3C trace coordinates: `traceId`, `spanId`, and `traceFlags`. Use it to correlate stream consumers such as eval reporters with an observability backend. An uninstrumented target omits it.diff --git a/docs/guides/session-context.md b/docs/guides/session-context.mdindex e5f5a92b3..7d53f2703 100644--- a/docs/guides/session-context.md+++ b/docs/guides/session-context.md@@ -46,6 +46,7 @@ Public fields include:- `auth.current`: the caller for the active inbound turn.- `auth.initiator`: the caller that started the session.- `parent`: the parent call, session, root session, and turn for a child subagent session.+- `predecessor`: present when eve started this session in place of a [stranded session](../concepts/execution-model-and-durability#stranded-sessions). Its `sessionId` names the session this one replaced. Read the earlier conversation with `sessions.attach(predecessor.sessionId)` from `eve/server`. See [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives).Unprotected agents expose `auth.current` and `auth.initiator` as `null`. Top-level schedule sessions use the framework app principal (`principalId: "eve:app"`, `principalType: "runtime"`). See [Authentication](./auth-and-route-protection#what-reaches-ctxsessionauth) for how inbound identity becomes session auth.diff --git a/docs/instructions.mdx b/docs/instructions.mdxindex 5910f324d..eaf4f5cc1 100644--- a/docs/instructions.mdx+++ b/docs/instructions.mdx@@ -80,7 +80,7 @@ A dynamic system result applies at its lifecycle scope. A dynamic user result isThe `messages` snapshot passed to a `session.started` resolver includes static user instructions. A `turn.started` resolver additionally sees user instructions produced at `session.started`. Other dynamic capability resolvers keep their existing snapshots.-See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior.+See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failure behavior. To give a session that replaced a [stranded session](./concepts/execution-model-and-durability#what-a-replacement-session-receives) the earlier conversation, read its stream with `sessions.attach()` and `transcriptReducer()` in a `session.started` user-role instruction.## History controls and prompt cachingdiff --git a/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.ts b/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.tsindex ccd3acfe3..d67849258 100644--- a/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.ts+++ b/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.ts@@ -9,6 +9,7 @@ function snapshot(ctx: DynamicResolveContext) {id: ctx.session.id,auth: ctx.session.auth,schedule: ctx.session.schedule ?? null,+ predecessor: ctx.session.predecessor ?? null,} satisfies Record<keyof DynamicResolveContext["session"], unknown>,channel: {kind: ctx.channel.kind ?? null,diff --git a/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.tsindex dacb93202..1a354aafb 100644--- a/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.ts+++ b/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.ts@@ -92,6 +92,7 @@ export default (["direct", "waiting"] as const).map((mode) =>current: expectedAuth(last ? "bob" : "alice"),initiator: expectedAuth("alice"),},+ predecessor: null,},channel: {kind: "channel:skill-context",diff --git a/packages/eve/extension-contracts/compatibility/channel/v57.ts b/packages/eve/extension-contracts/compatibility/channel/v57.tsnew file mode 100644index 000000000..c2ffb5586--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/channel/v57.ts@@ -0,0 +1,13 @@+import { defineChannel, GET } from "#public/channels/index.js";++// Epoch 57 callbacks that do not inspect a replacement predecessor remain supported.+export default defineChannel({+ routes: [+ GET("/threads/:threadId/events", async (_request, { from, params }) => {+ const session = await from(params.threadId!).send("Read the thread.", { auth: null });+ const events = await session.getEventStream({ startIndex: 0 });+ await events.cancel();+ return new Response("ok");+ }),+ ],+});diff --git a/packages/eve/extension-contracts/compatibility/connection/v45.ts b/packages/eve/extension-contracts/compatibility/connection/v45.tsnew file mode 100644index 000000000..7bcdbfe4b--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/connection/v45.ts@@ -0,0 +1,10 @@+import { defineMcpClientConnection } from "#public/connections/index.js";++// Epoch 45 callbacks that do not inspect a replacement predecessor remain supported.+export default defineMcpClientConnection({+ description: "Search the incident tracker.",+ url: "https://incidents.example.com/mcp",+ approval({ toolName }) {+ return toolName.endsWith("__search") ? "approved" : "user-approval";+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v36.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v36.tsnew file mode 100644index 000000000..853f99f99--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v36.ts@@ -0,0 +1,11 @@+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";++// Epoch 36 callbacks that do not inspect a replacement predecessor remain supported.+export default defineDynamic({+ events: {+ "turn.started": (_event, ctx) =>+ defineInstructions({+ markdown: `Triage the incident reported in session ${ctx.session.id}.`,+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v35.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v35.tsnew file mode 100644index 000000000..3828b3e70--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v35.ts@@ -0,0 +1,13 @@+import { defineDynamic, defineSkill } from "#public/skills/index.js";++// Epoch 35 callbacks that do not inspect a replacement predecessor remain supported.+export default defineDynamic({+ events: {+ "turn.started": (_event, ctx) =>+ defineSkill({+ deferred: true,+ description: "Triage the active incident.",+ markdown: `Triage the incident reported in session ${ctx.session.id}.`,+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v77.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v77.tsnew file mode 100644index 000000000..d9b002e25--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v77.ts@@ -0,0 +1,15 @@+import { defineDynamic, defineTool } from "#public/tools/index.js";++// Epoch 77 callbacks that do not inspect a replacement predecessor remain supported.+export default defineDynamic({+ events: {+ "turn.started": (_event, ctx) => ({+ session: defineTool({+ deferred: true,+ description: "Return the active session identifier.",+ inputSchema: { type: "object", properties: {} },+ execute: () => ({ sessionId: ctx.session.id }),+ }),+ }),+ },+});diff --git a/packages/eve/extension-contracts/compatibility/hook/v43.ts b/packages/eve/extension-contracts/compatibility/hook/v43.tsnew file mode 100644index 000000000..ae3787643--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/hook/v43.ts@@ -0,0 +1,12 @@+import { defineHook } from "#public/hooks/index.js";++// Epoch 43 callbacks that do not inspect a replacement predecessor remain supported.+export default defineHook({+ events: {+ "action.result"(event) {+ const { result } = event.data;+ if (result.kind !== "load-skill-result") return;+ console.info("skill loaded", { callId: result.callId, skill: result.name });+ },+ },+});diff --git a/packages/eve/extension-contracts/compatibility/schedule/v30.ts b/packages/eve/extension-contracts/compatibility/schedule/v30.tsnew file mode 100644index 000000000..74deba3e2--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/schedule/v30.ts@@ -0,0 +1,19 @@+import { defineChannel } from "#public/channels/index.js";+import { defineSchedule } from "#public/schedules/index.js";++// Epoch 30 callbacks that do not inspect a replacement predecessor remain supported.+const reports = defineChannel({+ routes: [],+ receive(input, { from }) {+ return from("nightly-report").send(input.message, { auth: input.auth });+ },+});++export default defineSchedule({+ cron: "0 2 * * *",+ async run({ to, appAuth, waitUntil }) {+ const session = await to(reports, {}).send("Prepare the nightly report.", { auth: appAuth });+ const events = await session.getEventStream({ startIndex: 0 });+ waitUntil(events.cancel());+ },+});diff --git a/packages/eve/extension-contracts/compatibility/state/v12.ts b/packages/eve/extension-contracts/compatibility/state/v12.tsnew file mode 100644index 000000000..5c774760c--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/state/v12.ts@@ -0,0 +1,7 @@+import { defineState } from "#public/context/index.js";++export const visits = defineState("compatibility.visits", () => ({ count: 0 }));+export function recordVisit(): number {+ visits.update((current) => ({ count: current.count + 1 }));+ return visits.get().count;+}diff --git a/packages/eve/extension-contracts/compatibility/subagent/v33.ts b/packages/eve/extension-contracts/compatibility/subagent/v33.tsnew file mode 100644index 000000000..1ff57253d--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/subagent/v33.ts@@ -0,0 +1,8 @@+import { defineAgent } from "#public/index.js";++// Epoch 33 callbacks that do not inspect a replacement predecessor remain supported.+export default defineAgent({+ description: "Research the incidents behind a metric change.",+ model: "openai/gpt-5.6-sol",+ tool: "deferred",+});diff --git a/packages/eve/extension-contracts/compatibility/tool/v84.ts b/packages/eve/extension-contracts/compatibility/tool/v84.tsnew file mode 100644index 000000000..72e3b9ffc--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/tool/v84.ts@@ -0,0 +1,4 @@+import { webSearch } from "#public/tools/web-search.js";++// Epoch 84 tool definitions that do not inspect a replacement predecessor remain supported.+export default webSearch({ provider: "native" });diff --git a/packages/eve/extension-contracts/reports/channel/v58.json b/packages/eve/extension-contracts/reports/channel/v58.jsonnew file mode 100644index 000000000..10486c676--- /dev/null+++ b/packages/eve/extension-contracts/reports/channel/v58.json@@ -0,0 +1,22 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "channel",+ "epoch": 58,+ "sha256": "61f5ab28490a7d8aa1443b9f623092707277dab5d8c91af9737303a01a8606d3",+ "exports": [+ "DELETE",+ "GET",+ "HEAD",+ "OPTIONS",+ "PATCH",+ "POST",+ "PUT",+ "SessionStrandedError",+ "WS",+ "createWebSocketUpgradeServer",+ "defineChannel",+ "disableRoute",+ "isChannel",+ "isDisabledRouteSentinel"+ ]+}diff --git a/packages/eve/extension-contracts/reports/connection/v46.json b/packages/eve/extension-contracts/reports/connection/v46.jsonnew file mode 100644index 000000000..0862d1b85--- /dev/null+++ b/packages/eve/extension-contracts/reports/connection/v46.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "connection",+ "epoch": 46,+ "sha256": "f4c2512542c3278292ada656e282f53c50b3198cc035047a93f57835045e3e93",+ "exports": [+ "ConnectionAuthorizationFailedError",+ "ConnectionAuthorizationRequiredError",+ "defineDynamic",+ "defineInteractiveAuthorization",+ "defineMcpClientConnection",+ "defineOpenAPIConnection",+ "isConnectionAuthorizationFailedError",+ "isConnectionAuthorizationRequiredError"+ ]+}diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v37.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v37.jsonnew file mode 100644index 000000000..2bff6698a--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v37.json@@ -0,0 +1,7 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicInstructions",+ "epoch": 37,+ "sha256": "a67c1f2dde83c8c3cf875740e343d69a645548b2766bad836fd37161b94627d3",+ "exports": ["defineDynamic"]+}diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v36.json b/packages/eve/extension-contracts/reports/dynamicSkill/v36.jsonnew file mode 100644index 000000000..b87289c5d--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v36.json@@ -0,0 +1,7 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicSkill",+ "epoch": 36,+ "sha256": "407a0ff99d9448e6c3d39cdb84a9c318420bc6f65a5851e87f8a8af8836a60f0",+ "exports": ["defineDynamic"]+}diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v78.json b/packages/eve/extension-contracts/reports/dynamicTool/v78.jsonnew file mode 100644index 000000000..b82b6b9ff--- /dev/null+++ b/packages/eve/extension-contracts/reports/dynamicTool/v78.json@@ -0,0 +1,16 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "dynamicTool",+ "epoch": 78,+ "sha256": "a80c16872da9a79b4323ae1dc4ddc51ec364b53e11e67e23eb9c59b77e18eac9",+ "exports": [+ "DynamicToolEntry",+ "DynamicToolEvents",+ "DynamicToolResult",+ "DynamicToolSet",+ "auto",+ "defineDurableCallback",+ "defineDurableSchema",+ "defineDynamic"+ ]+}diff --git a/packages/eve/extension-contracts/reports/hook/v44.json b/packages/eve/extension-contracts/reports/hook/v44.jsonnew file mode 100644index 000000000..19ab5b941--- /dev/null+++ b/packages/eve/extension-contracts/reports/hook/v44.json@@ -0,0 +1,7 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "hook",+ "epoch": 44,+ "sha256": "f83a701859f46d2fad279b42ae278bfd2928a5b13eaac87ca4c10f0dfcd5a3e5",+ "exports": ["defineHook"]+}diff --git a/packages/eve/extension-contracts/reports/schedule/v31.json b/packages/eve/extension-contracts/reports/schedule/v31.jsonnew file mode 100644index 000000000..9a600d8fe--- /dev/null+++ b/packages/eve/extension-contracts/reports/schedule/v31.json@@ -0,0 +1,15 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "schedule",+ "epoch": 31,+ "sha256": "875f59b0c450d015c9beb4326b8db28b23292889a293472b42ec4c80832c3e1a",+ "exports": [+ "ScheduleDefinition",+ "ScheduleHandlerArgs",+ "ScheduleRunHandler",+ "ScheduleToFn",+ "TypedReceiveTarget",+ "defineSchedule",+ "isScheduleAuth"+ ]+}diff --git a/packages/eve/extension-contracts/reports/state/v13.json b/packages/eve/extension-contracts/reports/state/v13.jsonnew file mode 100644index 000000000..e60dcdba8--- /dev/null+++ b/packages/eve/extension-contracts/reports/state/v13.json@@ -0,0 +1,15 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "state",+ "epoch": 13,+ "sha256": "c570703bd335822f85fe8a982c2856d387cdd93e9444d3350ce20e33fbd85147",+ "exports": [+ "Session",+ "SessionAuth",+ "SessionAuthContext",+ "SessionContext",+ "SessionParent",+ "SessionTurn",+ "defineState"+ ]+}diff --git a/packages/eve/extension-contracts/reports/subagent/v34.json b/packages/eve/extension-contracts/reports/subagent/v34.jsonnew file mode 100644index 000000000..822d9ceb4--- /dev/null+++ b/packages/eve/extension-contracts/reports/subagent/v34.json@@ -0,0 +1,23 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "subagent",+ "epoch": 34,+ "sha256": "1643c7ea99162a1f5bbcc42b65bf9eca3c462010382ee2a61889837800e240ef",+ "exports": [+ "AgentCompactionDefinition",+ "AgentDefinition",+ "AgentModelDefinition",+ "AgentStaticModelDefinition",+ "DefinedAgent",+ "DynamicLocalSubagentDefinition",+ "DynamicSubagentDefinition",+ "RemoteAgentDefinition",+ "RemoteAgentDefinitionInput",+ "WorkspaceAgentDefinition",+ "WorkspaceAgentTransport",+ "defineAgent",+ "defineDynamic",+ "defineRemoteAgent",+ "defineWorkspaceAgent"+ ]+}diff --git a/packages/eve/extension-contracts/reports/tool/v85.json b/packages/eve/extension-contracts/reports/tool/v85.jsonnew file mode 100644index 000000000..a65031d22--- /dev/null+++ b/packages/eve/extension-contracts/reports/tool/v85.json@@ -0,0 +1,29 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "tool",+ "epoch": 85,+ "sha256": "fa39d9d1f8a8ed3094e377368bd443e63fb20f25e01d3a4fb0affcacd8d76895",+ "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/client/index.ts b/packages/eve/src/client/index.tsindex b859dc3bc..e9d46d0ab 100644--- a/packages/eve/src/client/index.ts+++ b/packages/eve/src/client/index.ts@@ -9,6 +9,12 @@ export { HealthResponseError } from "#client/health-response-error.js";export { ClientError, ClientSessionStrandedError } from "#client/client-error.js";export { defaultMessageReducer } from "#client/message-reducer.js";export { conversationReducer } from "#client/conversation-reducer.js";+export {+ transcriptReducer,+ type TranscriptData,+ type TranscriptMessage,+ type TranscriptReducerOptions,+} from "#client/transcript-reducer.js";export { openConversationInputs } from "#client/conversation-state.js";export { toolCallState, type ToolCallState, type ToolCallStatus } from "#client/tool-call-state.js";@@ -138,6 +144,7 @@ export type {RuntimeTraceContext,SessionCompletedStreamEvent,SessionFailedStreamEvent,+ SessionPredecessor,SessionStartedStreamEvent,SessionWaitingStreamEvent,MessageStreamEvent,diff --git a/packages/eve/src/client/transcript-reducer.test.ts b/packages/eve/src/client/transcript-reducer.test.tsnew file mode 100644index 000000000..4cfbde51a--- /dev/null+++ b/packages/eve/src/client/transcript-reducer.test.ts@@ -0,0 +1,99 @@+import { describe, expect, it } from "vitest";++import { transcriptReducer } from "#client/transcript-reducer.js";+import {+ createContextClearedEvent,+ createMessageAppendedEvent,+ createMessageCompletedEvent,+ createMessageReceivedEvent,+ createReasoningCompletedEvent,+ createSessionFailedEvent,+ createSessionStartedEvent,+ stampMessageStreamEvent,+ type UnstampedMessageStreamEvent,+} from "#protocol/message.js";++const TURN = { sequence: 0, turnId: "turn_0" };++function received(message: Parameters<typeof createMessageReceivedEvent>[0]["message"]) {+ return createMessageReceivedEvent({ ...TURN, message });+}++function completed(message: string) {+ return createMessageCompletedEvent({ ...TURN, finishReason: "stop", message, stepIndex: 0 });+}++function reduce(+ events: readonly UnstampedMessageStreamEvent[],+ reducer = transcriptReducer(),+): ReturnType<typeof reducer.initial> {+ return events.reduce(+ (data, event) => reducer.reduce(data, stampMessageStreamEvent(event)),+ reducer.initial(),+ );+}++describe("transcriptReducer", () => {+ it("keeps user text and completed assistant text, oldest first", () => {+ expect(+ reduce([+ createSessionStartedEvent(),+ received([+ { text: "Alice shares the venue list.", type: "text" },+ { data: "aGVsbG8=", filename: "venues.pdf", mediaType: "application/pdf", type: "file" },+ ]),+ createReasoningCompletedEvent({ ...TURN, reasoning: "Compare capacity.", stepIndex: 0 }),+ createMessageAppendedEvent({ ...TURN, messageDelta: "The second venue", stepIndex: 0 }),+ completed("The second venue seats everyone."),+ // Output that never completed is partial and never part of the transcript.+ createMessageAppendedEvent({ ...TURN, messageDelta: "Booking it", stepIndex: 1 }),+ ]).messages,+ ).toEqual([+ { role: "user", text: "Alice shares the venue list." },+ { role: "assistant", text: "The second venue seats everyone." },+ ]);+ });++ it("starts over at a clear and at a reset that ended a stranded session", () => {+ expect(+ reduce([+ received("Alice asks about the budget."),+ createContextClearedEvent({ ...TURN, sessionId: "wrun_old" }),+ received("Bob asks about the schedule."),+ ]).messages,+ ).toEqual([{ role: "user", text: "Bob asks about the schedule." }]);++ const ended = (trigger: string) =>+ createSessionFailedEvent({+ code: "session_stranded",+ details: { trigger },+ message: "ended",+ sessionId: "wrun_old",+ usage: undefined,+ });+ expect(reduce([received("Bob asks about the schedule."), ended("reset")]).messages).toEqual([]);+ expect(+ reduce([received("Bob asks about the schedule."), ended("message")]).messages,+ ).toHaveLength(1);+ });++ it("keeps only the newest maxMessages", () => {+ const events = Array.from({ length: 5 }, (_, index) => received(`Note ${index}`));+ expect(reduce(events, transcriptReducer({ maxMessages: 2 })).messages).toEqual([+ { role: "user", text: "Note 3" },+ { role: "user", text: "Note 4" },+ ]);+ });++ it("returns its input unchanged for events it ignores", () => {+ const reducer = transcriptReducer();+ const data = reducer.initial();+ expect(reducer.reduce(data, stampMessageStreamEvent(createSessionStartedEvent()))).toBe(data);+ });++ it.each([0, -1, 1.5])("rejects maxMessages %s", (maxMessages) => {+ expect(() => transcriptReducer({ maxMessages })).toThrow(+ `"maxMessages" must be a positive integer; received ${maxMessages}.`,+ );+ });+});diff --git a/packages/eve/src/client/transcript-reducer.ts b/packages/eve/src/client/transcript-reducer.tsnew file mode 100644index 000000000..bc5459ee2--- /dev/null+++ b/packages/eve/src/client/transcript-reducer.ts@@ -0,0 +1,96 @@+import type { EveAgentReducer, EveAgentReducerEvent } from "#client/reducer.js";++/** One user message or completed assistant message in a {@link TranscriptData}. */+export interface TranscriptMessage {+ readonly role: "assistant" | "user";+ readonly text: string;+}++/** Text-only conversation projected by {@link transcriptReducer}. */+export interface TranscriptData {+ /** Messages since the session's last clear, oldest first. */+ readonly messages: readonly TranscriptMessage[];+}++/** Options for {@link transcriptReducer}. */+export interface TranscriptReducerOptions {+ /**+ * Most recent messages kept; older ones are dropped as new ones arrive.+ * A positive integer. Unbounded when omitted.+ */+ readonly maxMessages?: number;+}++/**+ * Creates a reducer that projects a session's stream into its text+ * conversation: user message text and completed assistant text, oldest+ * first.+ *+ * Reasoning, tool calls and results, attachments, approvals, and assistant+ * output that never completed are left out. A `context.cleared` event, or a+ * reset that ended a stranded session, starts the transcript over, so text+ * the session no longer holds is never returned. Client projection events+ * such as optimistic submissions are ignored; the transcript reflects only+ * durable events.+ *+ * @example+ * ```ts+ * import { transcriptReducer } from "eve/client";+ * import { sessions } from "eve/server";+ *+ * const reducer = transcriptReducer({ maxMessages: 40 });+ * let transcript = reducer.initial();+ * for await (const event of sessions.attach(sessionId).stream({ follow: false })) {+ * transcript = reducer.reduce(transcript, event);+ * }+ * ```+ *+ * @throws When `maxMessages` is not a positive integer.+ */+export function transcriptReducer(+ options: TranscriptReducerOptions = {},+): EveAgentReducer<TranscriptData> {+ const { maxMessages } = options;+ if (maxMessages !== undefined && (!Number.isSafeInteger(maxMessages) || maxMessages <= 0)) {+ throw new TypeError(+ `transcriptReducer: "maxMessages" must be a positive integer; received ${String(maxMessages)}.`,+ );+ }+ const append = (data: TranscriptData, message: TranscriptMessage): TranscriptData => {+ if (message.text.trim().length === 0) return data;+ const messages = [...data.messages, message];+ return {+ messages:+ maxMessages === undefined || messages.length <= maxMessages+ ? messages+ : messages.slice(-maxMessages),+ };+ };+ return {+ initial: () => ({ messages: [] }),+ reduce(data, event) {+ switch (event.type) {+ case "message.received":+ return append(data, { role: "user", text: receivedText(event) });+ case "message.completed":+ return append(data, { role: "assistant", text: event.data.message });+ case "context.cleared":+ return data.messages.length === 0 ? data : { messages: [] };+ case "session.failed":+ return event.data.code === "session_stranded" &&+ event.data.details?.trigger === "reset" &&+ data.messages.length > 0+ ? { messages: [] }+ : data;+ default:+ return data;+ }+ },+ };+}++function receivedText(event: Extract<EveAgentReducerEvent, { type: "message.received" }>): string {+ const { message, parts } = event.data;+ if (parts === undefined) return message;+ return parts.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n");+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 1e3ba83a9..772287745 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -22,9 +22,10 @@ interface ExtensionCapabilityContract {const EXTENSION_CAPABILITY_CONTRACTS = {extension: { current: 1, supported: [1], dropped: {} },tool: {- current: 84,+ current: 85,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,],dropped: {14: "TaskExec.delegated was removed; migrate to workflow-backed background tools",@@ -88,10 +89,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},dynamicTool: {- current: 77,+ current: 78,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 22, 31, 32, 33, 52, 54,- 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 75, 76, 77,+ 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 72, 73, 75, 76, 77, 78,],dropped: {21: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -132,10 +133,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},channel: {- current: 57,+ current: 58,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,+ 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 54, 55, 56, 57, 58,],dropped: {12: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -158,10 +159,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},schedule: {- current: 30,+ current: 31,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,+ 29, 30, 31,],dropped: {5: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -170,9 +171,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},subagent: {- current: 33,+ current: 34,supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 19, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33,+ 34,],dropped: {1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",@@ -186,10 +188,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},connection: {- current: 45,+ current: 46,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,+ 35, 36, 37, 38, 39, 40, 41, 43, 44, 45, 46,],dropped: {9: "Dynamic connection resolvers no longer receive conversation or channel continuation data",@@ -205,8 +207,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},hook: {- current: 43,- supported: [20, 21, 22, 23, 25, 27, 31, 32, 33, 34, 35, 36, 37, 38, 39, 41, 42, 43],+ current: 44,+ supported: [20, 21, 22, 23, 25, 27, 31, 32, 33, 34, 35, 36, 37, 38, 39, 41, 42, 43, 44],dropped: {1: "Model identity moved from session.started runtime metadata to step.started call attribution.",2: "Model identity moved from session.started runtime metadata to step.started call attribution.",@@ -237,10 +239,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},skill: { current: 3, supported: [1, 2, 3], dropped: {} },dynamicSkill: {- current: 35,+ current: 36,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 25, 26, 27, 28, 29, 30,- 31, 32, 33, 34, 35,+ 31, 32, 33, 34, 35, 36,],dropped: {13: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -251,10 +253,10 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},instructions: { current: 2, supported: [1, 2], dropped: {} },dynamicInstructions: {- current: 36,+ current: 37,supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 21, 22, 26, 27, 28, 29, 30,- 31, 32, 33, 34, 35, 36,+ 31, 32, 33, 34, 35, 36, 37,],dropped: {14: "Message and reasoning append events now expose deltas instead of cumulative snapshots.",@@ -265,8 +267,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},config: { current: 1, supported: [1], dropped: {} },state: {- current: 12,- supported: [1, 2, 3, 4, 5, 7, 9, 10, 12],+ current: 13,+ supported: [1, 2, 3, 4, 5, 7, 9, 10, 12, 13],dropped: {6: "Sandbox sessions no longer expose core identity and mutable networking is provider-specific.",8: "SandboxSession no longer exposes setNetworkPolicy; pass the configured environment to ctx.getSandbox(environment) to access network policy capabilities",diff --git a/packages/eve/src/context/accessors.ts b/packages/eve/src/context/accessors.tsindex d9f361c55..4be103917 100644--- a/packages/eve/src/context/accessors.ts+++ b/packages/eve/src/context/accessors.ts@@ -7,6 +7,7 @@ export type {SessionAuth,SessionAuthContext,SessionParent,+ SessionPredecessor,SessionTurn,} from "#context/keys.js";diff --git a/packages/eve/src/context/build-callback-context.ts b/packages/eve/src/context/build-callback-context.tsindex 2bdd3167f..bc418ff8c 100644--- a/packages/eve/src/context/build-callback-context.ts+++ b/packages/eve/src/context/build-callback-context.ts@@ -22,6 +22,7 @@ export function buildCallbackContext(): SessionContext {turn: session.turn,parent: session.parent,schedule: readSessionSchedule(ctx),+ predecessor: session.predecessor,},getSandbox(environment?: SandboxEnvironmentIdentity): Promise<RuntimeSandboxSession> {diff --git a/packages/eve/src/context/dynamic-resolve-context.ts b/packages/eve/src/context/dynamic-resolve-context.tsindex 7bdb649ab..35143637f 100644--- a/packages/eve/src/context/dynamic-resolve-context.ts+++ b/packages/eve/src/context/dynamic-resolve-context.ts@@ -9,6 +9,7 @@ import {SessionIdKey,InitiatorAuthKey,ContinuationTokenKey,+ SessionPredecessorKey,} from "#context/keys.js";import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";import { getAdapterKind } from "#channel/adapter.js";@@ -44,6 +45,7 @@ export function buildResolveContext(current: currentAuth,initiator: initiatorAuth,},+ predecessor: ctx.get(SessionPredecessorKey),},channel: {kind: channelAdapter !== undefined ? getAdapterKind(channelAdapter) : undefined,diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.tsindex 8502a83da..5229e3730 100644--- a/packages/eve/src/context/keys.ts+++ b/packages/eve/src/context/keys.ts@@ -36,6 +36,7 @@ import type { HistoryViewProjector } from "#shared/history-view.js";import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";import type { PreparedRuntimeDelegationTool } from "#runtime/sessions/turn.js";import type { MemoryScope, MemoryTurnContext } from "#public/memory/index.js";+import type { SessionPredecessor } from "#protocol/message.js";// Re-export so consumers don't need a direct channel/ import.export type {@@ -44,6 +45,7 @@ export type {SessionTraceRoot,SessionTurn,} from "#channel/types.js";+export type { SessionPredecessor } from "#protocol/message.js";// ---------------------------------------------------------------------------// Session types (public API surface)@@ -71,6 +73,7 @@ export interface SessionAuth {export interface Session {readonly auth: SessionAuth;readonly parent?: SessionParent;+ readonly predecessor?: SessionPredecessor;readonly sessionId: string;readonly turn: SessionTurn;}@@ -136,6 +139,8 @@ export const ChannelInstrumentationKey = new ContextKey<ChannelInstrumentationPr"eve.channelInstrumentation",);export const ParentSessionKey = new ContextKey<SessionParent>("eve.parentSession");+/** Set only on a session eve started in place of one that could no longer run. */+export const SessionPredecessorKey = new ContextKey<SessionPredecessor>("eve.sessionPredecessor");/** Set only when the trace root differs from `ParentSessionKey`'s root; see {@link SessionTraceRoot}. */export const TraceRootKey = new ContextKey<SessionTraceRoot>("eve.traceRoot");/** Separate from {@link ParentSessionKey} so it stays out of what extensions read. */diff --git a/packages/eve/src/context/providers/session.ts b/packages/eve/src/context/providers/session.tsindex 4dce85739..2814419ad 100644--- a/packages/eve/src/context/providers/session.ts+++ b/packages/eve/src/context/providers/session.ts@@ -5,6 +5,7 @@ import {type Session,SessionIdKey,SessionKey,+ SessionPredecessorKey,} from "#context/keys.js";import type { ContextReader } from "#context/key.js";import type { HarnessSession } from "#harness/types.js";@@ -26,6 +27,7 @@ export const sessionProvider = {initiator: ctx.get(InitiatorAuthKey) ?? currentAuth,},parent: ctx.get(ParentSessionKey),+ predecessor: ctx.get(SessionPredecessorKey),sessionId: ctx.require(SessionIdKey),turn: { id: turnId, sequence: emission.sequence },}),diff --git a/packages/eve/src/context/session-context.ts b/packages/eve/src/context/session-context.tsindex 364667e65..0d7792309 100644--- a/packages/eve/src/context/session-context.ts+++ b/packages/eve/src/context/session-context.ts@@ -4,10 +4,10 @@ import type {RuntimeSandboxSessionFor,SandboxSession,} from "#shared/sandbox-session.js";-import type { SessionAuth, SessionParent, SessionTurn } from "#context/keys.js";+import type { SessionAuth, SessionParent, SessionPredecessor, SessionTurn } from "#context/keys.js";import type { SessionSchedule } from "#context/session-schedule.js";-export type { SessionAuth, SessionParent, SessionTurn, SessionSchedule };+export type { SessionAuth, SessionParent, SessionPredecessor, SessionSchedule, SessionTurn };/*** Shared runtime context available to all authored callbacks that run@@ -28,6 +28,12 @@ export interface SessionContext {readonly parent?: SessionParent;/** Present only for scheduled work; not an application-supplied auth attribute. */readonly schedule?: SessionSchedule;+ /**+ * Present when eve started this session in place of one whose deployment+ * was retired. It names the earlier session, whose recorded stream+ * `sessions.attach(predecessor.sessionId)` from `eve/server` reads.+ */+ readonly predecessor?: SessionPredecessor;};/**diff --git a/packages/eve/src/dynamic/definition.ts b/packages/eve/src/dynamic/definition.tsindex b88768d98..dbe718e6a 100644--- a/packages/eve/src/dynamic/definition.ts+++ b/packages/eve/src/dynamic/definition.ts@@ -1,6 +1,6 @@import type { ModelMessage } from "ai";-import type { SessionAuth } from "#context/keys.js";+import type { SessionAuth, SessionPredecessor } from "#context/keys.js";import { stampDefinitionKey } from "#internal/authored-definition/source-identity.js";import type { UnstampedMessageStreamEvent } from "#protocol/message.js";import type { ConversationContext } from "#shared/conversation-context.js";@@ -54,6 +54,12 @@ export interface DynamicResolveContext {readonly id: string;readonly auth: SessionAuth;readonly schedule?: import("#context/session-schedule.js").SessionSchedule;+ /**+ * Present when eve started this session in place of a stranded session,+ * one that another eve version built. It names the earlier session, whose recorded stream+ * `sessions.attach(predecessor.sessionId)` from `eve/server` reads.+ */+ readonly predecessor?: SessionPredecessor;};/** Channel metadata for the request that triggered this resolve. */readonly channel: {diff --git a/packages/eve/src/execution/session-stranded.integration.test.ts b/packages/eve/src/execution/session-stranded.integration.test.tsindex bff62a9da..c6c12c340 100644--- a/packages/eve/src/execution/session-stranded.integration.test.ts+++ b/packages/eve/src/execution/session-stranded.integration.test.ts@@ -25,7 +25,19 @@ import {sessionCommandInboxWorkflow,} from "#internal/testing/session-inbox-workflow.js";import { startSessionOwner, waitForHook } from "#internal/testing/workflow-test-helpers.js";-import { getWorld, start } from "#internal/workflow/runtime.js";+import { getRun, getWorld, start } from "#internal/workflow/runtime.js";+import {+ createMessageCompletedEvent,+ createMessageReceivedEvent,+ createSessionStartedEvent,+ encodeMessageStreamEvent,+ stampMessageStreamEvent,+ type SessionPredecessor,+ type UnstampedMessageStreamEvent,+} from "#protocol/message.js";+import { transcriptReducer, type TranscriptData } from "#client/transcript-reducer.js";+import { sessions } from "#public/server/index.js";+import { defineDynamic, defineInstructions } from "#public/definitions/instructions.js";import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";/** eve version recorded by the owner an earlier build left parked on the local World. */@@ -101,6 +113,49 @@ async function waitForReceivedMessages(sessionId: string, expected: readonly strreturn [...pending];}+/** The `session.started` event a session publishes before its first turn. */+async function readSessionStarted(sessionId: string) {+ const reader = readSessionEventStream(sessionId).getReader();+ try {+ while (true) {+ const { done, value } = await reader.read();+ if (done) throw new Error(`Session "${sessionId}" ended before it started.`);+ if (value.type === "session.started") return value;+ }+ } finally {+ await reader.cancel().catch(() => {});+ }+}++/** Appends events to a parked session's stream, as its earlier build recorded them. */+async function recordHistory(+ sessionId: string,+ events: readonly UnstampedMessageStreamEvent[],+): Promise<void> {+ const writer = getRun(sessionId).getWritable<Uint8Array>().getWriter();+ try {+ for (const event of events) {+ await writer.write(encodeMessageStreamEvent(stampMessageStreamEvent(event)));+ }+ } finally {+ writer.releaseLock();+ }+}++const TURN = { sequence: 0, turnId: "turn_0" };++/** A short conversation the stranded session recorded before the upgrade. */+const OFFSITE_HISTORY: readonly UnstampedMessageStreamEvent[] = [+ createSessionStartedEvent(),+ createMessageReceivedEvent({ ...TURN, message: "Alice asks for help planning the offsite." }),+ createMessageCompletedEvent({+ ...TURN,+ finishReason: "stop",+ message: "Here is a draft agenda for the offsite.",+ stepIndex: 0,+ }),+];+/** A fresh session claims its address after `createSession` returns. */async function waitForAliasOwner(runtime: Runtime, continuationToken: string): Promise<string> {const deadline = Date.now() + 30_000;@@ -176,6 +231,9 @@ describe("stranded sessions", () => {await expect(waitForReceivedMessages(fresh.id, ["Alice asks for the weekly summary"]),).resolves.toEqual([]);+ // The successor names the session it replaced.+ const started = await readSessionStarted(fresh.id);+ expect(started.data.predecessor).toEqual({ sessionId: anchor.runId });// A remote job can finish after replacement. Its fixed parent inbox// must not route the result into the new conversation.const callback = await handleSessionCallbackRequest(@@ -425,4 +483,86 @@ describe("stranded sessions", () => {}});});++ it("lets a session.started instruction read the replaced conversation", async () => {+ const { reads, test } = await transcriptReadingRuntime("stranded-session-transcript");+ await test.run(async () => {+ const stranded = await parkStrandedOwner("http:stranded-session-transcript");+ await recordHistory(stranded.runId, OFFSITE_HISTORY);+ const runtime = channelRuntime();+ let freshSessionId: string | undefined;+ try {+ const fresh = await httpAddress(runtime, "stranded-session-transcript").send(+ "Alice asks to move the offsite to Friday.",+ { auth: null },+ );+ freshSessionId = fresh.id;++ await expect(reads.wait()).resolves.toEqual([+ {+ messages: [+ { role: "user", text: "Alice asks for help planning the offsite." },+ { role: "assistant", text: "Here is a draft agenda for the offsite." },+ ],+ predecessor: { sessionId: stranded.runId },+ },+ ]);+ } finally {+ await cancelIfActive(stranded);+ await resetSession(runtime, freshSessionId);+ }+ });+ });});++type TranscriptRead = TranscriptData & { readonly predecessor: SessionPredecessor };++/**+ * An app whose `session.started` instruction reads the replaced session's+ * conversation the way the predecessor docs show.+ */+async function transcriptReadingRuntime(name: string) {+ const recorded: TranscriptRead[] = [];+ const test = await createTestRuntime({+ agent: { name },+ modules: [+ {+ logicalPath: "instructions/replaced-conversation.ts",+ loadNamespace: async () => ({+ default: defineDynamic({+ events: {+ "session.started": async (_event, ctx) => {+ const predecessor = ctx.session.predecessor;+ if (predecessor === undefined) return null;+ const reducer = transcriptReducer({ maxMessages: 40 });+ let transcript = reducer.initial();+ for await (const event of sessions.attach(predecessor.sessionId).stream({+ follow: false,+ startIndex: -2000,+ })) {+ transcript = reducer.reduce(transcript, event);+ }+ recorded.push({ ...transcript, predecessor });+ return transcript.messages.length === 0+ ? null+ : defineInstructions({+ content: transcript.messages+ .map((message) => JSON.stringify(message))+ .join("\n"),+ role: "user",+ });+ },+ },+ }),+ }),+ },+ ],+ });+ const reads = {+ async wait(): Promise<readonly TranscriptRead[]> {+ await vi.waitFor(() => expect(recorded).not.toHaveLength(0), { timeout: 30_000 });+ return recorded;+ },+ };+ return { reads, test };+}diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.tsindex 849857a81..7bbac9b51 100644--- a/packages/eve/src/execution/workflow-runtime.ts+++ b/packages/eve/src/execution/workflow-runtime.ts@@ -38,7 +38,8 @@ import {type WorkflowFunction,type WorkflowMetadata,} from "#internal/workflow/runtime.js";-import type { MessageStreamEvent } from "#protocol/message.js";+import type { MessageStreamEvent, SessionPredecessor } from "#protocol/message.js";+import { SessionPredecessorKey } from "#context/keys.js";import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";import { ROOT_RUNTIME_AGENT_NODE_ID } from "#runtime/graph.js";import { normalizeEveAttributes } from "#runtime/attributes/normalize.js";@@ -132,7 +133,11 @@ export function createWorkflowRuntime(config: {readonly dynamicSubagentAgentConfig?: DynamicSubagentAgentConfig;readonly nodeId?: string;}): Runtime {- const startSession = async (input: RunInput): Promise<RunHandle> => {+ /** `predecessor` is set only on a successor of a retired session that has just ended. */+ const startSession = async (+ input: RunInput,+ predecessor?: SessionPredecessor,+ ): Promise<RunHandle> => {const bundle = await getCompiledRuntimeAgentBundle({compiledArtifactsSource: config.compiledArtifactsSource,nodeId: config.nodeId,@@ -145,6 +150,7 @@ export function createWorkflowRuntime(config: {dynamicSubagentAgentConfig: config.dynamicSubagentAgentConfig,run: input,});+ if (predecessor !== undefined) ctx.set(SessionPredecessorKey, predecessor);const effectiveAgent = resolveEffectiveAgentRuntime(bundle, ctx);initializeSessionInstrumentation({agentName: effectiveAgent.turnAgent.id,@@ -251,8 +257,8 @@ export function createWorkflowRuntime(config: {"Its pending requests can no longer be answered; send a new message to start a fresh session.",);}- await endStrandedSession(error, continuationToken, "message");- const started = await startSession(successor);+ const previousSessionId = await endStrandedSession(error, continuationToken, "message");+ const started = await startSession(successor, { sessionId: previousSessionId });return {sessionId: started.sessionId,status: "accepted",diff --git a/packages/eve/src/harness/session-machine/transitions.ts b/packages/eve/src/harness/session-machine/transitions.tsindex 8bcd276b2..9ebbbf228 100644--- a/packages/eve/src/harness/session-machine/transitions.ts+++ b/packages/eve/src/harness/session-machine/transitions.ts@@ -32,6 +32,7 @@ import {type InputResolution,type RuntimeIdentity,type RuntimeTraceContext,+ type SessionPredecessor,type TaskCancelReason,type TaskStartedStreamEvent,type UnstampedMessageStreamEvent,@@ -97,6 +98,8 @@ export function receive(view: SessionView,input: {readonly message?: string | UserContent;+ /** The session this one replaced, when eve started it in place of a stranded one. */+ readonly predecessor?: SessionPredecessor;readonly runtime?: RuntimeIdentity;readonly trace?: RuntimeTraceContext;},@@ -105,7 +108,13 @@ export function receive(const turnId = activeTurnId(position);const events: UnstampedMessageStreamEvent[] = [];if (!position.sessionStarted) {- events.push(createSessionStartedEvent({ runtime: input.runtime, trace: input.trace }));+ events.push(+ createSessionStartedEvent({+ predecessor: input.predecessor,+ runtime: input.runtime,+ trace: input.trace,+ }),+ );}if (position.turnId === "") {events.push(diff --git a/packages/eve/src/harness/step/context.ts b/packages/eve/src/harness/step/context.tsindex c4c1b2bbd..b7973551b 100644--- a/packages/eve/src/harness/step/context.ts+++ b/packages/eve/src/harness/step/context.ts@@ -7,7 +7,7 @@ import {} from "#context/dynamic-instruction-lifecycle.js";import { isDynamicConnectionResolutionError } from "#context/dynamic-connection-lifecycle.js";import { isDynamicModelSelectionError } from "#context/dynamic-model-lifecycle.js";-import { ParentSessionKey, SessionCallbackKey } from "#context/keys.js";+import { ParentSessionKey, SessionCallbackKey, SessionPredecessorKey } from "#context/keys.js";import { drainMemoryCommit, prepareMemoryPreamble } from "#context/memory-lifecycle.js";import { type HarnessModelMessage, validateHarnessModelMessages } from "#harness/messages.js";import {@@ -137,7 +137,12 @@ export async function openTurn(turnId: activeTurnId(position),});await step.apply(- receive(step.view(), { message: opened.message, runtime: config.runtimeIdentity, trace }),+ receive(step.view(), {+ message: opened.message,+ predecessor: ctx?.get(SessionPredecessorKey),+ runtime: config.runtimeIdentity,+ trace,+ }),step.projectHistory([...step.session.history, ...opened.input]),);} catch (error) {diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.tsindex 89e2d8a50..807ffb2ce 100644--- a/packages/eve/src/protocol/message.ts+++ b/packages/eve/src/protocol/message.ts@@ -117,6 +117,18 @@ export interface SubagentSessionInvocationMetadata {readonly name: string;}+/**+ * The session this one replaced. Present on a session eve started in place of+ * one whose deployment was retired, when the next ordinary channel message+ * arrived before the earlier session timed out. This session has its own id,+ * stream, auth, and state, and starts with no history from its predecessor;+ * read the predecessor with `sessions.attach(sessionId)` from `eve/server`.+ */+export interface SessionPredecessor {+ /** Id of the session this one replaced. Its recorded history stays readable. */+ readonly sessionId: string;+}+/*** Runtime identity metadata attached to the `session.started` event.*@@ -176,6 +188,8 @@ export type HandleMessageRequestBody =export interface SessionStartedStreamEvent {data: {invocation?: SubagentSessionInvocationMetadata;+ /** Present when this session replaced one that could no longer run. */+ predecessor?: SessionPredecessor;runtime?: RuntimeIdentity;trace?: RuntimeTraceContext;};@@ -938,6 +952,7 @@ export function isTurnFailureEvent<TEvent extends UnstampedMessageStreamEvent>(*/export function createSessionStartedEvent(input?: {readonly invocation?: SubagentSessionInvocationMetadata;+ readonly predecessor?: SessionPredecessor;readonly runtime?: RuntimeIdentity;readonly trace?: RuntimeTraceContext;}): SessionStartedStreamEvent {@@ -947,6 +962,10 @@ export function createSessionStartedEvent(input?: {data.invocation = input.invocation;}+ if (input?.predecessor !== undefined) {+ data.predecessor = input.predecessor;+ }+if (input?.runtime !== undefined) {data.runtime = input.runtime;}diff --git a/packages/eve/src/public/context/index.ts b/packages/eve/src/public/context/index.tsindex 9e0c10674..589acfe6a 100644--- a/packages/eve/src/public/context/index.ts+++ b/packages/eve/src/public/context/index.ts@@ -15,6 +15,7 @@ export type {SessionAuth,SessionAuthContext,SessionParent,+ SessionPredecessor,SessionTurn,} from "#context/accessors.js";export { defineState, type StateHandle } from "#public/definitions/state.js";diff --git a/packages/eve/src/public/definitions/callback-context.ts b/packages/eve/src/public/definitions/callback-context.tsindex 71ed34a18..8d63512f5 100644--- a/packages/eve/src/public/definitions/callback-context.ts+++ b/packages/eve/src/public/definitions/callback-context.ts@@ -2,5 +2,6 @@ export type {SessionAuth,SessionContext,SessionParent,+ SessionPredecessor,SessionTurn,} from "#context/session-context.js";