eve 0.76.0 → 0.76.2

package/docs/agent-config.md

@@ -67,6 +67,14 @@ Gateway, share that ID so their Gateway generations can be found together.
 Direct-provider calls do not receive the option. An authored `gateway.sessionId`
 takes precedence; AI Gateway hashes IDs longer than 256 characters.
 
+For direct OpenAI and `chatgpt()` model calls, eve sets
+`providerOptions.openai.promptCacheKey` to a SHA-256 hash of the session ID,
+which helps OpenAI route a session's calls to the cache that holds its prompt
+prefix. Each subagent session gets its own key. An authored
+`openai.promptCacheKey` takes precedence. `chatgpt()` calls also send the key
+in the `session-id` header, which the Codex backend uses for cache routing.
+Gateway-routed calls do not receive the option.
+
 ### Choose the model dynamically
 
 To select a model from the incoming prompt with an AI SDK decision model, use
@@ -144,6 +152,29 @@ the agent-level setting for that selection. Omitting it inherits the agent setti
 
 Run `eve set model --reasoning high` to update this field from the command line.
 
+## Prompt caching
+
+eve caches prompts automatically for AI Gateway models and for Anthropic models
+it recognizes by provider or model id. Set `modelOptions.promptCache` on a
+directly called model to mark an unrecognized model as Anthropic (such as a
+Bedrock application inference profile) or to use a 1-hour cache:
+
+```ts title="agent/agent.ts"
+import { bedrock } from "@ai-sdk/amazon-bedrock";
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: bedrock(process.env.BEDROCK_INFERENCE_PROFILE_ARN!),
+  modelContextWindowTokens: 200_000,
+  modelOptions: {
+    promptCache: { anthropic: { ttl: "1h" } }, // or { anthropic: {} } for the default 5m
+  },
+});
+```
+
+Not every Claude model supports a 1-hour cache. eve rejects `promptCache` on
+Gateway models; use `providerOptions.gateway.caching` instead.
+
 ## Compaction
 
 Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. eve adds the estimated fixed checkpoint-prompt envelope to the trigger count, so compaction starts sooner than the conversation-only estimate. Lower `thresholdPercent` to compact sooner:
@@ -361,7 +392,7 @@ it falls back to the World's default retention period.
 | Field          | Type                                  | Default          | Description                                                                                                                                                                                                                                                                                                                          |
 | -------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `reasoning`    | `AgentReasoningDefinition`            | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                                                                                                                                        |
-| `modelOptions` | `AgentModelOptionsDefinition`         | none             | Provider option overrides forwarded to the model call.                                                                                                                                                                                                                                                                               |
+| `modelOptions` | `AgentModelOptionsDefinition`         | none             | Provider option overrides forwarded to the model call, and [`promptCache`](#prompt-caching) settings.                                                                                                                                                                                                                                |
 | `limits`       | `AgentLimitsDefinition`               | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                                                                                                                                          |
 | `experimental` | `AgentExperimentalDefinition`         | unset            | Unstable opt-ins. `workflow.world` selects the Workflow world package on the root agent; `workflow.modelCallsPerStep` batches sequential model calls into a wider replay unit; `workflow.retention` controls how long the durable runtime keeps run data.                                                                            |
 | `build`        | `{ externalDependencies?: string[] }` | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                                                                                             |

package/docs/channels/custom.mdx

@@ -116,6 +116,15 @@ await source.reset({ reason: "Start over" });
 const currentSession = await resolveSession(threadId);
 ```
 
+When the session at an address is
+[stranded](../concepts/execution-model-and-durability#stranded-sessions) because another eve version
+built it, `send()` ends that session and starts a fresh one. The message becomes the fresh
+session's first turn, and the fresh session can read recent text from the earlier conversation;
+see [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives). Concurrent sends to the same stranded address still
+produce one fresh session. A `respond()` call, or a `deliver()` that includes input responses,
+carries answers a fresh session has no request for, so it throws `SessionStrandedError` and leaves
+the stranded session in place.
+
 `Session` is fixed: every call targets exactly one durable ID. It never creates,
 follows, or resolves a replacement.
 
@@ -131,6 +140,23 @@ await session.reset({ reason: "Retire this session" });
 await session.getEventStream({ startIndex: 12 });
 ```
 
+For a stranded session, `Session.send()`, `Session.respond()`, and a following
+`Session.getEventStream()` throw `SessionStrandedError` from `eve/channels` and deliver nothing.
+`getEventStream({ follow: false })` still reads the recorded history up to the current tail without
+changing the session. `error.owner.eveVersion` names the eve release that built the session when it recorded one. Call
+`reset()` to end the stranded session, then start a new one:
+
+```ts
+import { SessionStrandedError } from "eve/channels";
+
+try {
+  await attachSession(sessionId).send(text, { auth });
+} catch (error) {
+  if (!SessionStrandedError.is(error)) throw error;
+  await attachSession(sessionId).reset({ reason: "Session was stranded by an upgrade" });
+}
+```
+
 `respond()` accepts exact response literals directly. If responses have already
 been widened to `InputResponse[]`—for example, after decoding a platform
 payload—validate them with eve's strict schema before delivery. The validated

package/docs/channels/eve.mdx

@@ -21,7 +21,8 @@ export default eveChannel({
 ## Web Chat with Sign in with Vercel
 
 Run `eve add channel/web`, or select **Web Chat** from the terminal UI's channel
-picker. Choose a hosting layout, then **Sign in with Vercel**. Setup uses a
+picker. Choose **Next.js**, a hosting layout, then **Sign in with Vercel**. Sign
+in with Vercel is available only for the Next.js Web Chat app. Setup uses a
 linked Vercel project and creates a Vercel App that only members of that
 project's team can sign in to.
 
@@ -159,13 +160,15 @@ Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for a
 Sending a message to an unknown or terminal session ID returns `409` with
 `{"code":"session_not_active","error":"The session is no longer active.","ok":false}`.
 An existing workflow whose inbox is not yet available returns `409 session_not_ready` instead.
-TypeScript clients expose the stable code as `ClientError.code`. The route never
-creates or follows a replacement session.
+A session that another eve version built returns `409 session_stranded` with the `eveVersion`
+that built it.
 
 ### Stream events
 
 Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
 
+Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before a reset. A reset attempts to append `session.failed` with code `session_stranded` and close the stream. Existing readers finish when they receive that terminal event.
+
 ### Cancel a turn
 
 Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm the turn boundary on the stream as `turn.cancelled` followed by `session.waiting`.
@@ -174,7 +177,7 @@ See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-t
 
 ### Clear context
 
-Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
+Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. A stranded session cannot run the clear, so the route returns `409 session_stranded` and changes nothing; post to the `reset` route to end it instead. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ### Compact context
 
@@ -182,7 +185,7 @@ Post to `/eve/v1/session/:sessionId/compact` to summarize context without sendin
 
 ### Reset a session
 
-Post to `/eve/v1/session/:sessionId/reset` to terminally retire that session. Reset never replaces the ID automatically; create a new session explicitly for a fresh conversation. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
+Post to `/eve/v1/session/:sessionId/reset` to terminally retire that session. Reset never replaces the ID automatically; create a new session explicitly for a fresh conversation. Reset also works on a stranded session: eve cancels the stranded workflow run directly instead of delivering the command to it. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
 
 ## Replace or disable the defaults
 

package/docs/concepts/built-in-tools.md

@@ -240,6 +240,23 @@ export default webSearch({ provider: "native", fallback: "exa" });
 
 The `provider` setting applies only to AI Gateway models. Direct OpenAI, Anthropic, and Gemini 3 and later models always use their native search; other direct models omit `web_search`.
 
+eve identifies a direct model's vendor by its AI SDK provider name, so a `createOpenAI()` model pointed at an OpenAI-compatible endpoint, such as Amazon Bedrock's, gets OpenAI web search. When the endpoint rejects it, eve retries the step without `web_search`, so each step makes one rejected call first. To skip it, give the provider its own name:
+
+```ts title="agent/agent.ts"
+import { createOpenAI } from "@ai-sdk/openai";
+import { defineAgent } from "eve";
+
+const mantle = createOpenAI({
+  name: "mantle",
+  baseURL: "https://bedrock-mantle.us-east-1.api.aws/openai/v1",
+  apiKey: process.env.BEDROCK_API_KEY,
+});
+
+export default defineAgent({ model: mantle("openai.gpt-5.6-sol") });
+```
+
+The agent then gets no `web_search`, the same as other direct models without native search.
+
 Replace provider-managed search with an authored implementation:
 
 ```ts title="agent/tools/web_search.ts"

package/docs/concepts/execution-model-and-durability.mdx

@@ -37,6 +37,106 @@ Every workflow run records each step it executes, so a session that ran on one r
 
 The move happens once the turn settles and nothing else is waiting: no queued messages, running tasks or subagents, or pending human input. The new run receives the compacted history and settled state, then waits for the next message. If a single message reaches an otherwise idle session before the move completes, eve moves the session with that message, and the message's turn runs on the new run. If work is still pending, eve tries again after a later turn settles. The session keeps its ID, event stream, continuation addresses, and deadline; compaction never extends [`sessionTimeoutMs`](../agent-config#runtime-limits). If the new run cannot take ownership, the current run keeps the session, writes a `session handoff failed` warning to its runtime logs, and tries again later.
 
+### Stranded sessions
+
+A session is stranded when another eve version built the workflow run that owns it. A run can only be replayed by the eve version that started it, so the conversation is still stored, but nothing on the current deployment can process a new message. On worlds without per-deployment routing, eve checks the owner before delivering channel messages and input responses, rather than committing them to a session that cannot answer.
+
+eve treats every world other than Vercel Workflow as running one eve version at a time, so a stranded session can never run again:
+
+| World                        | When a session is stranded                                                                                                                                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Vercel Workflow              | eve does not check. Each run keeps executing on the deployment that started it, and handoff moves idle sessions to newer deployments.                                                                                                 |
+| Local world with `eve start` | After any upgrade that changes the eve version. Sessions created before eve recorded its version on the run are treated the same way.                                                                                                 |
+| Postgres and other worlds    | Same as the local world. Serve one world from one eve version at a time: a deployment running another version cannot replay these sessions, and eve does not route runs between deployments.                                          |
+| `eve dev`                    | After an eve version change. A session from a previous dev server invocation built by the same eve version is not stranded: it stays dormant until you restart `eve dev` with [`--resume`](../reference/cli#local-workflow-recovery). |
+
+eve ends a stranded session without running any of its code. When that happens depends on the kind of run:
+
+- **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, a reset ends it, or its session timeout elapses, whichever comes first.
+- **A subagent session or workflow tool run**, including a task, is cancelled the next time the world delivers work to it, for example when the local world or Postgres recovers active runs at startup. No later message could resume its interrupted work, so eve does not wait.
+
+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. 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.
+- **Reset** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. Reset the session instead.
+- **Session timeouts** end a stranded session the same way a reset does; see [How a stranded session ends](#how-a-stranded-session-ends).
+
+A reset ends the stranded session without running any of its code. eve cancels the session's owner run and, after a handoff, the original run that anchors its event stream, then waits until the world releases the session's addresses. If another run has taken over the session since eve inspected it, the reset ends nothing and fails so the request can be retried. The stranded session's `session.completed` and `session.failed` hooks do not run; the fresh session runs `session.started` as usual. Before cancelling, eve attempts to append a `session.failed` event with code `session_stranded` and close the old stream, without invoking authored hooks. Stream publication is best effort and waits at most 5 seconds: missing payload keys, unavailable storage, or a stalled write do not prevent reset. Each step tolerates an earlier attempt having completed it, so a reset that fails part way can be retried.
+
+Each 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. 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 ends
+
+A stranded root session ends on its next channel message, a reset, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
+
+The timeout is the session's own durable timer, armed for the deadline `sessionTimeoutMs` sets from the session's creation or latest deployment handoff (30 days by default; compaction handoffs keep the deadline). The timer is a separate workflow run that keeps working after the upgrade, and when it fires on a stranded session it ends the session the same way a reset does, without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or a reset, just as a healthy one would stay open.
+
+Ending a root session does not find or cancel its subagent sessions and workflow tool runs. Each one is cancelled when a delivery for it reaches the current deployment, with the cancellation reason `Run retired: its eve deployment is no longer available`, and eve logs a `Retired stranded descendant run` warning. A run that never receives a delivery, such as one parked in a dormant `eve dev` generation, can stay active; cancel it in your Workflow world if you need to. Cancellation does not run authored cleanup or lifecycle hooks, undo side effects, or stop independent external jobs, and results and approvals do not carry over to a replacement session.
+
+Runs that recorded no eve version, including every run from a release before eve recorded versions, are treated as stranded.
+
 ### Upgrading sessions from the former execution model
 
 You can upgrade directly from a release that used a session driver and separate

package/docs/concepts/project-structure.mdx

@@ -32,7 +32,7 @@ project/
 
 Create the agent with [Getting Started](/docs/getting-started). The [Agent Files reference](/docs/reference/agent-files) lists supported paths. Keep agent-only helpers in `agent/lib/`; share reusable capabilities through [extensions](/docs/extensions).
 
-For a generated Next.js chat UI, run `eve add channel/web` from the project root. For an existing browser app, follow your [framework integration guide](/docs/guides/frontend/overview#per-framework-integration).
+For a generated chat UI, run `eve add channel/web` from the project root and choose Next.js or TanStack Start. For an existing browser app, follow your [framework integration guide](/docs/guides/frontend/overview#per-framework-integration).
 
 ## Several root agents
 
@@ -79,7 +79,7 @@ Choose how the frontend and agents run together independently of how many agents
 
 `apps/web/` is an organizational convention, not an eve filesystem slot. Deployment configuration owns peer services; eve discovers only the agents. Both Vercel integrations deploy the services together, not as independent releases.
 
-Run `eve add channel/web` from a standalone agent or select a workspace agent with `--agent <name>`. The installer creates a Next.js frontend under `apps/web/`. Choose **Vercel** to configure separate Vercel services and run them with `pnpm dev:all`; you don't need to link a Vercel project to run them locally. Choose **Other** to let Next.js host the agents and run the application with `pnpm dev:web`. Use `pnpm dev` or `pnpm dev:eve` when you only want one agent and the eve terminal UI.
+Run `eve add channel/web` from a standalone agent or select a workspace agent with `--agent <name>`. The installer asks which framework to use and creates a Next.js or TanStack Start frontend under `apps/web/`. Choose **Vercel services** to configure separate Vercel services and run them with `pnpm dev:all`; you don't need to link a Vercel project to run them locally. Choose **Next.js** or **TanStack Start** to let the frontend host the agent and run the application with `pnpm dev:web`. Use `pnpm dev` or `pnpm dev:eve` when you only want one agent and the eve terminal UI.
 
 ## Add a second root agent
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -67,39 +67,39 @@ curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream
 
 The 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.
 
@@ -265,6 +265,8 @@ Clear removes model-message history in place, including static and dynamic user-
 
 Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
 
+A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands. Reset still works: eve cancels the stranded workflow run and returns `"reset"`. Clear is refused with `409 session_stranded` (`SessionStrandedError` from a `Session` handle), because it would keep a session that cannot run. Compact returns `"no_active_session"` and cancel returns `"no_active_turn"`.
+
 ## Reconnect and rewind
 
 The stream is durable. Every event is recorded before a step completes, so consumers can reconnect from their cursor when an HTTP connection ends. A nonnegative `startIndex` is an absolute event count: use it to pick up where you dropped off or pass `0` to rewind to the start.
@@ -294,7 +296,7 @@ curl -i "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<cou
 # x-eve-stream-tail-index: <tail>
 ```
 
-The lookup is opt-in; requests without the parameter get no header. The TypeScript client wraps this into `stream({ follow: false })`.
+The lookup is opt-in; requests without the parameter get no header. Passing `follow=false` instead bounds the response at the durable tail on the server and implies the header. A bounded read only reads recorded history, so it also works for a [stranded session](./execution-model-and-durability#stranded-sessions), whose live stream returns `409 session_stranded`. The TypeScript client wraps this into `stream({ follow: false })`.
 
 ## Use the client from TypeScript
 

package/docs/guides/client/messages.mdx

@@ -40,7 +40,16 @@ When the stream includes `session.failed`, the turn returns `status: "failed"` r
 seconds when a durable run has been accepted but its command inbox is still starting. The caller's
 abort signal cancels the wait. Other errors, `session.respond()`, control methods, and raw HTTP
 requests do not use this retry. An unknown
-or terminal session throws `ClientError` immediately with `session_not_active`. The client never creates a replacement session.
+or terminal session throws `ClientError` immediately with `session_not_active`. A
+[stranded](../../concepts/execution-model-and-durability#stranded-sessions) session throws
+`ClientSessionStrandedError`, a `ClientError` with `code: "session_stranded"` and the
+`eveVersion` that built the session when it recorded one. It is never retried automatically. Call
+`session.reset()` and create a new session.
+The client never creates a replacement session. Following or reconnecting to a stranded session's
+stream reports the same typed error without retrying, including when you were waiting for a
+response to a message accepted before the upgrade. That accepted message is not redelivered.
+`session.clear()` throws the same error, because clearing would keep a session that cannot run.
+`session.stream({ follow: false })` and `session.snapshot()` still read the recorded history.
 
 ## Send a full turn payload
 

package/docs/guides/deployment/overview.md

@@ -14,7 +14,7 @@ Choose where the eve runtime will run:
 | [Vercel](./vercel)             | `.vercel/output`       | Vercel Workflow                | Vercel Sandbox                  | You want Vercel to operate the runtime services       |
 | [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker, microsandbox, or custom | You operate your own Node or container infrastructure |
 
-eve is frontend agnostic and can be deployed within Next.js, Nuxt, or SvelteKit applications. See [Frontend integrations](../frontend/overview) for more details.
+eve is frontend agnostic and can be deployed within Next.js, Nuxt, SvelteKit, or TanStack Start applications. See [Frontend integrations](../frontend/overview) for more details.
 
 ## Prepare for production
 
@@ -58,4 +58,4 @@ Follow the guide for your deployment platform or application topology:
 
 - [Deploy to Vercel](./vercel): use Vercel Build Output, Workflow, Sandbox, Cron, and observability
 - [Self-host eve](./self-hosting): run the Nitro Node server with infrastructure you manage
-- [Frontend integrations](../frontend/overview): mount eve alongside Next.js, Nuxt, or SvelteKit
+- [Frontend integrations](../frontend/overview): mount eve alongside Next.js, Nuxt, SvelteKit, or TanStack Start

package/docs/guides/dev-tui.md

@@ -35,6 +35,8 @@ Before your first message, the empty composer may suggest asking your local agen
 | `/help`     | List available commands.                                                                                                                                     |
 | `/exit`     | Quit the UI.                                                                                                                                                 |
 
+When a message or stream reconnection reaches a [stranded session](../concepts/execution-model-and-durability#stranded-sessions), the TUI says why and which eve version built it, when known. New messages and approvals are not delivered. Run `/new` to end the stranded session; your next message starts a fresh one. `/clear` is refused, because it would keep the stranded session. A session from a previous `eve dev` invocation that the same eve version built is not stranded; see [local workflow recovery](../reference/cli#local-workflow-recovery). A message accepted before the upgrade is not redelivered.
+
 `/login`, `/model`, `/add`, `/deploy`, `/info`, and `/traces` are available when `eve dev` runs locally. They are unavailable when the UI connects through `eve remote connect`.
 
 ## Set up a new agent

package/docs/guides/frontend/meta.json

@@ -1,5 +1,13 @@
 {
   "title": "Frontend Frameworks",
   "defaultOpen": false,
-  "pages": ["overview", "nextjs", "nuxt", "sveltekit", "use-eve-agent-vue", "use-eve-agent-svelte"]
+  "pages": [
+    "overview",
+    "nextjs",
+    "nuxt",
+    "sveltekit",
+    "tanstack",
+    "use-eve-agent-vue",
+    "use-eve-agent-svelte"
+  ]
 }

package/docs/guides/frontend/nextjs.mdx

@@ -15,7 +15,7 @@ Use this integration when Next.js owns the application's development and deploym
 
 ## Add the generated Web Chat app
 
-Install the generated Next.js Web Chat app from a standalone agent project:
+Install the generated Web Chat app from a standalone agent project, and choose **Next.js** when the installer asks which framework to use:
 
 ```bash
 eve add channel/web

package/docs/guides/frontend/overview.mdx

@@ -9,10 +9,10 @@ Use this guide when you already have a browser application and need to connect i
 
 A browser UI is a client of the agent's HTTP routes (the [eve channel](../../channels/overview)). Two layers wire it up:
 
-- **Routing** makes the agent reachable from the browser. A framework integration can mount eve on your app's origin: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), or [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin). If the frontend and agents are peer services, use your deployment platform or reverse proxy instead. The hook works with either setup; pass `host` for a different origin or a named path mount.
+- **Routing** makes the agent reachable from the browser. A framework integration can mount eve on your app's origin: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin), or [TanStack Start](./tanstack) (the `eveTanStack` Vite plugin). If the frontend and agents are peer services, use your deployment platform or reverse proxy instead. The hook works with either setup; pass `host` for a different origin or a named path mount.
 - **The hook** (`useEveAgent`) holds the session state, streaming, errors, and composer status. It defaults to same-origin eve routes such as `/eve/v1/session`.
 
-The framework pages walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), and [SvelteKit](./sveltekit). See [Project Structure](../../concepts/project-structure#configure-a-web-deployment) to choose between a framework integration and peer services.
+The framework pages walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), [SvelteKit](./sveltekit), and [TanStack Start](./tanstack). See [Project Structure](../../concepts/project-structure#configure-a-web-deployment) to choose between a framework integration and peer services.
 
 For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [Client SDK](../client/overview) directly.
 
@@ -437,12 +437,13 @@ const support = useEveAgent({ agent: "support" });
 
 ## Per-framework integration
 
-| Framework | Integration                          | Hook                                             |
-| --------- | ------------------------------------ | ------------------------------------------------ |
-| Next.js   | [`withEve`](./nextjs)                | [`useEveAgent` (React)](#basic-chat-react)       |
-| Nuxt      | [`eve/nuxt` module](./nuxt)          | [`useEveAgent` (Vue)](./use-eve-agent-vue)       |
-| SvelteKit | [`eveSvelteKit` plugin](./sveltekit) | [`useEveAgent` (Svelte)](./use-eve-agent-svelte) |
-| Any React | same-origin or `host`                | [`useEveAgent` (React)](#basic-chat-react)       |
+| Framework      | Integration                          | Hook                                             |
+| -------------- | ------------------------------------ | ------------------------------------------------ |
+| Next.js        | [`withEve`](./nextjs)                | [`useEveAgent` (React)](#basic-chat-react)       |
+| Nuxt           | [`eve/nuxt` module](./nuxt)          | [`useEveAgent` (Vue)](./use-eve-agent-vue)       |
+| SvelteKit      | [`eveSvelteKit` plugin](./sveltekit) | [`useEveAgent` (Svelte)](./use-eve-agent-svelte) |
+| TanStack Start | [`eveTanStack` plugin](./tanstack)   | [`useEveAgent` (React)](#basic-chat-react)       |
+| Any React      | same-origin or `host`                | [`useEveAgent` (React)](#basic-chat-react)       |
 
 ## What to read next