eve 0.83.2 → 0.84.0

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

@@ -202,7 +202,9 @@ eve add tool/web_search
 ```
 
 ```ts title="agent/tools/web_search.ts"
-export { default } from "eve/tools/web_search";
+import { webSearch } from "eve/tools/web_search";
+
+export default webSearch({ provider: "exa" });
 ```
 
 Override the provider-managed configuration for AI Gateway:
@@ -340,7 +342,7 @@ Entries the agent declares count from the session's first step. An entry a dynam
 - `eve__tool({ name, input? })` calls the entry named `name` with `input`, which defaults to `{}`. A connection tool's name is `<connection>__<tool>`, such as `linear__list_issues`. eve checks `input` against the entry's input schema. An invalid input fails with the entry's signature, an unknown name fails with the closest names, and a skill's name fails with a reminder to load it with `eve__skill`. When the server asks for the user's authorization, the call asks the user to sign in and parks until sign-in completes. A connection tool call the server doesn't answer within 5 minutes is cancelled and fails with an error such as `"linear" did not answer list_issues within 5 minutes. It may still have run, so check before you retry.` The server may finish the call after eve stops waiting, so a tool that changes data may already have made the change.
 - `eve__skill({ name })` loads the named skill, deferred or not, and returns its instructions. An unknown name fails with the closest skill names, a tool's name fails with a reminder to call it with `eve__tool` or directly, and a name that matches a connection says to find its tools with `eve__search({ query: "<connection>__" })`.
 
-After `eve__tool` or `eve__skill` resolves its entry, the call runs exactly like a direct call to that entry. A skill load reports a `load-skill` action and a `load-skill-result`, both with the skill's `name`, and an `execute_tool eve:load-skill` span. Approval policies and `approvedTools`, workflow tools and tasks, agents, `endsTurn`, `toModelOutput`, hooks, and stream events all see the entry's own name and input, such as `linear__list_issues`. Only model history records the call as `eve__tool` or `eve__skill`.
+After `eve__tool` or `eve__skill` resolves its entry, the call runs exactly like a direct call to that entry. A skill load publishes `call.requested` with `capability: { kind: "skill", name }`, followed by `call.settled` for its outcome. Approval policies, workflow tools and tasks, agents, `endsTurn`, `toModelOutput`, hooks, and stream events all see the entry's own name and input, such as `linear__list_issues`. Only model history records the call as `eve__tool` or `eve__skill`.
 
 eve tells the model what it can reach in an append-only context message rather than in the system prompt: which kinds of deferred entries exist, up to 20 namespaces (the first `__` segment of deferred names, such as `sre` for `sre__list_alerts`), and up to 20 connections with their descriptions. It never names a deferred entry, so deferred entries stay out of context until `eve__search` finds them. A later step appends the listing again only when that changes; a deferred entry added to a listed namespace, or without one, changes nothing. After the session first reaches each kind of entry, adding or removing entries, signing in, or resolving more dynamic connections doesn't change the catalog tools, so the cached prompt prefix holds.
 
@@ -350,8 +352,8 @@ The tools eve adds itself all live in the `eve` namespace: `eve__search`, `eve__
 
 eve adds `eve__task_wait` and `eve__task_cancel` when the agent has a tool that runs its calls as [tasks](/docs/tools/tasks): any agent tool, including the built-in `agent` tool, declared subagents, and remote agents, or a tool such as `agentRouter()`, the `workflow` tool, or an authored workflow tool that defines `task(input, ctx)` or `serve(receive, ctx)`. There is no add command, and the tools are not workflow tools. Like every `eve__` name, both are reserved.
 
-- `eve__task_wait({ timeoutSeconds? })` parks the turn until any task has a result, a new message arrives, or `timeoutSeconds` pass, and returns at once when a result is already waiting. While it waits, the stream reports `turn.waiting` for the open turn. Results arrive in a `<task_result>` message right after it returns. Waiting never stops a task.
-- `eve__task_cancel({ taskId })` stops a task's current work and says so, or says the task had no work to stop when it already finished or is an idle [resumable task](/docs/tools/workflows#resumable-tasks-serve). An id that names no task fails with `UNKNOWN_TASK`. A resumable task stays available after a cancel.
+- `eve__task_wait({ timeoutSeconds? })` parks the turn until any task has a result, a new message arrives, or `timeoutSeconds` pass, and returns at once when a result is already waiting. While it waits, the turn stays running rather than pausing, since `turn.paused` only reports interactions. Results arrive in a `<task_result>` message right after it returns. Waiting never stops a task.
+- `eve__task_cancel({ taskId })` stops a task's current work and says so, or says the task had no work to stop when it already finished or is an idle [resumable task](/docs/tools/workflows#resumable-tasks-serve). An id that names no task fails with `UNKNOWN_TASK`. Cancelling an agent task ends it; other resumable tasks stay available after a cancel.
 
 Review these tools before production use. Disable, wrap, restrict, or require approval for any tool that can access the filesystem, network, shell, or sensitive data.
 
@@ -372,7 +374,7 @@ eve add tool/ask_question
 ```ts title="agent/tools/ask_question.ts"
 import { askQuestion } from "eve/tools/ask_question";
 
-export default askQuestion();
+export default askQuestion;
 ```
 
 `ask_question` is a [workflow tool](/docs/tools/workflows) that calls `ctx.ask()`. The model receives `{ status: "answered", answer }`, where `answer` is the chosen option's label or the user's own words. A plain follow-up message answers the question too when it is the first open request and the message matches an option or the question allows free text; see [Several requests at once](/docs/human-in-the-loop#several-requests-at-once). A steering message that doesn't answer it withdraws the question: `ask_question` resolves as `{ interrupted: true }`, which the model reads as `Stopped early because a new message arrived.`, and the model reads the message next. In a session that cannot request input, such as a [markdown schedule](/docs/schedules#markdown-form-fire-and-forget), the result is `{ status: "unavailable" }` and the model continues on its own judgment. Remove the file to remove the tool.
@@ -405,7 +407,7 @@ Remove the file to remove the tool. `disableTool()` is unnecessary because `glob
 
 ### `grep`
 
-`grep` searches sandbox file contents with a regular expression. It searches the workspace root unless the model passes a directory or file, which accepts the same paths as `read_file`. Add it:
+`grep` searches file contents inside the sandbox workspace with a regular expression. It searches the workspace root unless the model passes a directory or file inside the workspace. It is also the implementation of the code extension's `code__grep` tool. Add it:
 
 ```sh
 eve add tool/grep
@@ -429,6 +431,16 @@ export default defineTool({
 
 Remove the file to remove the tool. `disableTool()` is unnecessary because `grep` is not added by default.
 
+Inputs are `pattern`, optional `path`, `glob`, `ignoreCase`, `literal`, `context`, `limit`, and
+`outputMode`. `files_with_matches` is the default and lists paths; `content` returns matching
+lines and `count` returns per-file totals. Identifier-like patterns use literal matching unless
+`literal: false` is explicit. The default limit is 50 rows, capped at 200, with additional byte
+and line bounds. Relative paths resolve against the workspace root; `$HOME` paths, parent traversal, and symlinks
+outside it are rejected. Ripgrep respects `.gitignore`; the POSIX fallback does not.
+
+Results contain `content`, `matchCount`, `outputMode`, `path`, and `truncated`. Use
+`outputMode: "content"` to return matching lines.
+
 ### `no_reply`
 
 `no_reply` ends the turn without a reply. Use it when a scheduled check finds nothing to report, or when an action the agent already took is the whole answer. The model calls it with an optional `{ reason }`, which stays in the session history and traces and is never sent. The turn completes without a final message, so channels and schedule sends post nothing, and later turns see that the agent chose to stay quiet. Add it:
@@ -440,7 +452,7 @@ eve add tool/no_reply
 ```ts title="agent/tools/no_reply.ts"
 import { noReply } from "eve/tools/no_reply";
 
-export default noReply();
+export default noReply;
 ```
 
 `no_reply` is a `defineTool` tool with [`endsTurn: true`](/docs/tools#end-the-turn-after-a-tool-call), so the turn ends only when no other tool runs in the same step. Only root sessions receive it. Slack clears the thread status when the turn completes. Remove the file to remove the tool.
@@ -458,7 +470,7 @@ eve add tool/sleep
 ```ts title="agent/tools/sleep.ts"
 import { sleep } from "eve/tools/sleep";
 
-export default sleep();
+export default sleep;
 ```
 
 Customize it by wrapping the framework definition:
@@ -468,7 +480,7 @@ import { defineWorkflowTool } from "eve/tools";
 import { sleep } from "eve/tools/sleep";
 
 export default defineWorkflowTool({
-  ...sleep(),
+  ...sleep,
   description: "Pause before checking an external operation again.",
 });
 ```

package/docs/concepts/context-control.md

@@ -52,22 +52,19 @@ See [Subagents](../subagents) for the distinction between root-agent copies and
 
 ## Dynamic context with `defineDynamic`
 
-Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the active principal, tenant, channel, or feature state. Dynamic resolvers can read session auth and channel metadata before returning the capabilities available to that session.
+Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the active principal, tenant, channel, conversation, or feature state. The function reads the committed session and returns the capability or `null`. eve evaluates it before each ordinary model call; `ctx.memo(key, fn)` keeps JSON observations across evaluations.
 
-See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API, supported slots, and execution order.
+See [Dynamic capabilities](../guides/dynamic-capabilities) for the context, memo rules, supported folders, and evaluation timing.
 
 ## Compaction and clear
 
-Before a model call, eve checks the projected history together with the effective system instructions and advertised tool schemas. The check runs after `step.started` resolves dynamic capabilities. When the provider reports input usage, eve adds estimates for new messages and growth in the instructions and tool catalog to that count; unchanged schemas are not counted again.
+Before a model call, eve checks the projected history together with the effective system instructions and advertised tool schemas. The check runs after eve evaluates dynamic capabilities for that call. When the provider reports input usage, eve adds estimates for new messages and growth in the instructions and tool catalog to that count; unchanged schemas are not counted again.
 
 Compaction reserves space for those instructions and tools while reducing conversation history. It cannot shrink the instructions or tool catalog themselves, so keep them within the selected model's context window.
 
-User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without rerunning their static definitions or dynamic resolvers. System-role instructions remain outside history and continue to apply after either operation.
+User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without reinserting unchanged instructions. System-role instructions remain outside history and continue to apply after either operation.
 
-Recalled memory also uses user-role messages, but eve keeps their attribution
-separate. Compaction excludes them from the summary, preserves their canonical
-records, and recalls again after the checkpoint. Clear removes those session
-records without deleting the provider's external data.
+Recalled memory stays outside history too. eve recalls before the first model call of each turn, and every later model call reads that turn's recall just ahead of the turn's input. Compaction does not summarize it; a provider can capture before compaction rewrites history. Clear drops what earlier turns recalled, though not the provider's external data, and the next turn recalls again.
 
 ## What to read next
 

package/docs/concepts/default-harness.md

@@ -7,7 +7,7 @@ The default harness is eve's built-in agent loop. It manages model calls, compac
 
 ## Compaction
 
-The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `thresholdPercent` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
+The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `thresholdPercent` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
 
 ```ts title="agent/agent.ts"
 export default defineAgent({
@@ -24,17 +24,16 @@ input token count plus an estimate of new messages. A smaller character estimate
 alone cannot satisfy compaction triggered by a higher provider count. If trimming
 cannot free enough space, eve summarizes the older history.
 
-First-class [memory](../memory) participates in a separate lifecycle. eve asks
-providers to capture before compaction, excludes attributed recalled records
-from the summarizer, keeps their canonical latest values, and recalls again
-after the checkpoint.
+First-class [memory](../memory) stays outside history, so the summarizer never
+sees it. eve asks providers to capture before compaction rewrites history, and
+what earlier turns recalled follows the checkpoint.
 
 Clients and channels can also request compaction between turns. Call
 `ClientSession.compact()`, a channel route's `compact(address)`, or
 `attachSession(sessionId).compact()`. The request does not append a user message;
-if a turn is running, eve queues it until that turn settles. A successful manual
-compaction emits the same `compaction.requested` and `compaction.completed`
-events as automatic compaction, followed by `session.waiting`.
+if a turn is running, eve queues it until that turn settles. A manual compaction is
+the same context change as automatic compaction: `context.started` and
+`context.settled` with `kind: "compaction"`.
 
 After either kind of compaction, eve moves the idle session to a fresh workflow
 run on the same deployment, so a long session's run history does not keep
@@ -45,7 +44,7 @@ To discard model-message history instead of summarizing it, call the correspondi
 system prompt, configured tools and skills, durable state, limits, and sandbox.
 It removes recalled memory records and framework memory bookkeeping, but it
 does not delete data from a memory provider's external store.
-Its stream boundary is `context.cleared` followed by `session.waiting`.
+On the stream it is a context change with `kind: "clear"`: `context.started`, then `context.settled`.
 
 ## What to read next
 

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

@@ -23,15 +23,9 @@ replay unit.
 
 The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds deployment-aware routing and dashboard run metadata.
 
-<span id="stranded-sessions" />
-<span id="what-a-replacement-session-receives" />
-<span id="how-a-stranded-session-ends" />
-
-On Vercel, workflow runs continue on the deployment that started them, and idle sessions can move to a newer deployment on their next delivery. Self-hosted worlds without per-deployment routing can resume persisted sessions after a process restart with the same eve version, but cannot resume session runs built by another eve version. See [Recover a stranded session](../guides/deployment/self-hosting#recover-a-stranded-session) for recovery and optional conversation context in a replacement session.
-
 When a Vercel production deployment changes, a new delivery to an idle session hands the session's settled state to the exact deployment that accepted the request. This applies whether the delivery arrives through the session ID or through any channel continuation address the session has claimed. The session keeps its original ID and event stream, while the next model turn uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. As with any turn, the triggering delivery restarts the session's [`sessionTimeoutMs`](../agent-config#runtime-limits) idle window, whether or not the handoff succeeds; disabled timeouts stay disabled.
 
-Before taking ownership, the target deployment upgrades the checkpoint when an older eve release wrote it, then checks that no pending work remains. A deployment accepts checkpoints from eve 0.66.0 and later, so upgrading eve does not leave long-lived sessions, such as a Slack thread, on their old deployment. An older release cannot read a newer checkpoint: after a rollback, a session that already moved to the newer deployment stays there. Extension state saved before eve 0.69 moves to its mount when exactly one mount of that extension package defines that state. State that the target deployment no longer defines, such as a removed `defineState` key, is dropped, and the target deployment's runtime logs show a `dropping unknown context key during deserialization` warning. When two or more mounts of one extension package define that state, eve cannot choose an owner, and the session stays on its current deployment. Idle subagent sessions that eve 0.66–0.68 kept for later reuse are stopped after the handoff. Authored session state remains opaque to this validation.
+Before taking ownership, the target deployment checks checkpoint compatibility and that no pending work remains. A session with an incompatible checkpoint stays on its current deployment; see the [migration guide](./upgrade-to-v27-events#before-you-upgrade) for this release's requirements. An older release cannot read a newer checkpoint: after a rollback, a session that already moved to the newer deployment stays there. State that the target deployment no longer defines, such as a removed `defineState` key, is dropped, and the runtime logs identify the unknown key. Authored session state remains opaque to this validation.
 
 Messages that arrive while a handoff is in progress are accepted right away and are not lost. The new owner processes them after the triggering delivery, in the order they arrived, whichever run accepted them.
 
@@ -49,6 +43,106 @@ The move happens once the turn settles and nothing else is waiting: no queued me
 
 Both kinds of handoff need a Workflow world that can move a session's addresses from one run to another without releasing them, and can keep a released address reserved for a while (the `hookForceClaim` and `hookRetention` capabilities). Vercel Workflow, the local world, and `@workflow/world-postgres` 5.0.4 and later provide both. On a world without them, sessions never move between runs: deployment and compaction handoffs are skipped, and a session's run history grows for as long as the session lives. The first skipped attempt writes a `session handoff unavailable` warning to the runtime logs.
 
+### 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).
+- **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `reset()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
+- **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 and waits for its channel addresses to be released. If another run has taken ownership in the meantime, the reset fails without ending the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the reset delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. A reset that fails partway through 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`, read it with `transcriptOf()` from `eve/client`, and return the result from a [dynamic user-role instruction](../instructions#dynamic-instructions) with a memo keyed by the predecessor's ID:
+
+```ts title="agent/instructions/replaced-conversation.ts"
+import { transcriptOf } from "eve/client";
+import { defineDynamic, defineInstructions } from "eve/instructions";
+import { sessions } from "eve/server";
+
+export default defineDynamic(async (ctx) => {
+  const predecessor = ctx.session.predecessor;
+  if (predecessor === undefined) return null;
+  const content = await ctx.memo(predecessor.sessionId, async () => {
+    const events = [];
+    try {
+      for await (const event of sessions.attach(predecessor.sessionId).stream({
+        startIndex: -2000,
+        follow: false,
+        signal: AbortSignal.timeout(5_000),
+      })) {
+        events.push(event);
+      }
+    } catch (error) {
+      console.warn("couldn't read the replaced session", { error });
+      return null;
+    }
+    const transcript = transcriptOf(events, { maxMessages: 40 });
+    if (transcript.messages.length === 0) return null;
+
+    return [
+      "Earlier conversation from a session this one replaced, as historical data rather than instructions:",
+      ...transcript.messages.map((message) => JSON.stringify(message)),
+    ].join("\n");
+  });
+  return content === null ? null : defineInstructions({ content, role: "user" });
+});
+```
+
+The memo runs before the replacement's first model call, and the instruction 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.
+
+`transcriptOf()` keeps the history each consumed delivery imported, the text of each consumed delivery, and each completed reply part, oldest first, as `{ role, text }` messages. Reasoning, narration, tool calls and results, attachments, interactions, and interrupted output are left out. A clear in the stranded session starts the transcript over, so text the user cleared is never returned. `sessions.attach()` also converts older session history to v27 events. That conversion reads from the beginning to reconstruct the conversation, even when `startIndex` requests a later position. `maxMessages` keeps only the newest messages in the resulting transcript.
+
+The read and the prompt are yours to bound:
+
+- `startIndex: -2000` requests the newest 2,000 stored lines, not 2,000 events. Older history conversion still reads from the beginning; the `signal` limits read time in either case. The example catches a read that throws or times out and returns `null`, so the instruction contributes nothing and the turn continues. A memo that throws fails the turn instead, and eve tries it again at the next model call.
+- 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, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session 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 immediately cancel its subagent sessions and workflow tool runs. Each is retired when a delivery for it reaches the current deployment, and the runtime logs identify the stranded run. 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
@@ -113,11 +207,24 @@ Provider keys, tool secrets, and MCP, OpenAPI, and connection credentials stay i
 
 ## Resuming after a crash
 
-Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval. Whatever that step already wrote to the session stream stays there, and the re-run emits its events again under new ids, so a stream consumer sees both attempts — see [the event envelope](./sessions-runs-and-streaming#the-event-envelope).
+Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. An interrupted step runs again from the checkpoint before it, so model calls in that step can run again.
+
+A step publishes session events as it works, before it saves its checkpoint. When an interrupted step already wrote some, its retry continues the stream after them instead of writing them again:
+
+- A tool call whose start is present in the recovered stream does not run again. The model reads each such call's name, input, and what eve knows of it, such as that it completed but its result was lost, and decides what to call again.
+- What the interrupted attempt left open settles `abandoned`: its model run, unfinished calls, and the approvals or questions it asked. The model asks again if it still needs them.
+- A turn the interrupted attempt already settled stays settled, with its input and reply in history.
+- A clear the interrupted attempt finished still empties history. An unfinished clear or compaction change settles `interrupted`; its control delivery settles `failed` instead of running again. A completed compaction keeps its recorded outcome, but its lost private summary is not reconstructed. The checkpoint history remains available for a later compaction.
+- Hooks and channel handlers do not run again for the events the interrupted attempt wrote. New recovery facts use normal hooks and instrumentation.
+
+A turn fails with `STEP_INTERRUPTED` after more than three interrupted steps, or with `STEP_FAILED` when one of its steps fails on every retry. The session stays open for the next message.
+
+Terminal cleanup preserves recorded outcomes and closes any remaining work. Its final publication does not run authored hooks; channel notification depends on whether the channel context can be restored. Do not rely on a terminal hook for guaranteed external cleanup: a hook interrupted after publication may have completed its side effect, partly completed it, or never run.
+
+These are durable-step retries, not the model provider's retry loop or ordinary tool errors handled within a step. Recovery does not make external effects exactly-once. A call's start record may not be durable when execution begins, so a crash can lose that record. A call whose start had not reached the stream when the step was interrupted can run again, a call reported as interrupted may have taken effect, and the model can call a tool again. A world that redelivers a step while its earlier attempt is still running can also run both. Give tools with irreversible effects a stable operation ID, or have them check whether the action already happened.
 
 With `experimental.workflow.modelCallsPerStep` greater than `1`, an
-interrupted Workflow step can also repeat earlier model calls and inline tool
-executions from the same batch. Approval, input, and blocking coordination
+interrupted step can repeat earlier model calls from the same batch. Approval, input, and blocking coordination
 boundaries still force a checkpoint before eve waits.
 
 Steering can interrupt pending model generation before assistant output begins.
@@ -186,7 +293,7 @@ An executing eve tool finishes and commits its result before steering reaches th
 
 Once eve publishes an input request or begins publishing turn completion or failure, eve finishes committing that boundary before applying new messages.
 
-`turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the owner checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `inputResponses` deliveries do not steer; they remain available to the pending request they address.
+`turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the owner checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `answers` deliveries do not steer; they remain available to the pending request they address.
 
 Every built-in and custom channel accepts a default `turnPolicy`, and imperative message sends can override it. The policy is part of the same durable delivery command as the message, so concurrent senders cannot separate replacement ownership from cancellation intent. Separate sessions still run independently.
 
@@ -196,7 +303,7 @@ A turn can hand work off to a [subagent](../subagents). Each subagent gets its o
 
 ## How eve orders session history
 
-Conversation history within a session is append-only. Static user-role instructions lead fresh-session history. Dynamic user-role instructions land at their session or turn boundary before the current delivery. Turns follow in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see messages in the order they happened.
+Conversation history within a session is append-only. Static user-role instructions lead fresh-session history. Dynamic user-role instructions are added before a model call when their content changes. Turns follow in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see messages in the order they happened.
 
 ## What to read next
 

package/docs/concepts/meta.json

@@ -5,6 +5,7 @@
     "project-structure",
     "execution-model-and-durability",
     "sessions-runs-and-streaming",
+    "upgrade-to-v27-events",
     "state",
     "default-harness",
     "built-in-tools",