eve 0.80.1 → 0.81.1

package/docs/agent-config.md

@@ -67,6 +67,28 @@ 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.
 
+AI Gateway also uses this ID for
+[session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity),
+which tries the provider that served the session's previous call first, among
+the providers your routing settings allow, so that provider can read the prompt
+from its cache. The conversation
+appears as one session in the AI Gateway logs Sessions view. Affinity can move
+the pinned provider ahead of your `order`. To keep `order` exactly, set
+`sessionAffinity: false`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
+  modelOptions: {
+    providerOptions: {
+      gateway: { order: ["bedrock", "anthropic"], sessionAffinity: false },
+    },
+  },
+});
+```
+
 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

package/docs/channels/chat-sdk.mdx

@@ -140,7 +140,7 @@ This policy controls overlapping eve turns. Chat SDK's separate `concurrency` op
 
 The default handlers post the agent's reply back to the thread — no `events` override required. Completed assistant messages are posted as markdown (`{ markdown: … }`) so adapters render rich text and email HTML rather than a raw string.
 
-Streaming is on by default: the channel posts an initial message and edits it as tokens arrive (`message.appended`), throttled by `streamingEditIntervalMs` (default `1000`). Set `streaming: false` for surfaces that deliver one message per turn — email, for example — so the reply posts once on completion instead of editing:
+Streaming is on by default: the channel posts an initial message and edits it as tokens arrive (`message.appended`), throttled by `streamingEditIntervalMs` (default `1000`). Set `streaming: false` for surfaces that deliver one message per turn or can't edit sent messages — email and WhatsApp, for example — so the reply posts once on completion instead of editing:
 
 ```ts
 chatSdkChannel({
@@ -245,7 +245,9 @@ bot.onNewMention(async (thread, message) => {
 });
 ```
 
-When the adapter can download an attachment (it sets `fetchData`, as the Slack, Google Chat, WhatsApp, and Twilio adapters do), eve downloads it with the adapter's credentials when the turn runs, not in the webhook, and passes the bytes. Platform file URLs usually need those credentials, so the model provider couldn't open them. eve rebuilds the download with the adapter's `rehydrateAttachment`; an adapter without one can't download after the webhook returns, so its files reach the agent as a short note. A failed download, or a file over 25 MB, also becomes a note. An attachment with only a URL is downloaded by eve when the URL is public `https:`; otherwise it becomes a note.
+When the adapter can download an attachment (it sets `fetchData`, as the Slack, Google Chat, WhatsApp, and Twilio adapters do), eve downloads it with the adapter's credentials when the turn runs, not in the webhook, and passes the bytes. Platform file URLs usually need those credentials, so the model provider couldn't open them. eve rebuilds the download with the adapter's `rehydrateAttachment`; an adapter without one can't download after the webhook returns, so its files reach the agent as a short note. A failed download, or a file over 25 MB, also becomes a note. An attachment with only a URL is downloaded by eve when the URL is public `https:`; otherwise it becomes a note. An attachment with neither a download nor a URL also becomes a note, so the agent still knows a file was sent.
+
+Audio attachments, such as voice notes, reach the model as a file label, not as sound. To answer them, give the agent a transcription tool; see [Voice notes](../patterns/voice-notes).
 
 See [File uploads](./custom#file-uploads) for how eve stages remote file URLs before the model call.
 

package/docs/channels/eve.mdx

@@ -341,6 +341,33 @@ export default eveChannel({
 
 `onMessage` must return an auth result. Return `title` alongside `auth` to set the title when the dispatch creates a session or sends the first message to a prewarmed session. A successful canonical eve HTTP message always dispatches and therefore always produces or continues a session.
 
+### Turn context
+
+`context` strings become user messages in durable session history. For context that applies to one turn only, return `clientContext` instead. It replaces the request's [`clientContext`](../guides/client/messages) for that turn: it reaches every model call in the turn and is not kept in session history.
+
+`ctx.eve.clientContext` holds the request's `clientContext` exactly as the client sent it, or `undefined` when it sent none. Use it to check or correct client-supplied state before the model sees it:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel, defaultEveAuth } from "eve/channels/eve";
+import { vercelOidc } from "eve/channels/auth";
+
+import { getVerifiedPlan } from "../lib/billing";
+
+export default eveChannel({
+  auth: [vercelOidc()],
+  async onMessage(ctx) {
+    const auth = defaultEveAuth(ctx);
+    const plan = await getVerifiedPlan(auth);
+    return { auth, clientContext: [`The user's plan is ${plan}.`] };
+  },
+});
+```
+
+- Omit `clientContext` to keep the request's context. Return `[]` to drop it.
+- The returned value takes the same shape as request `clientContext` (`ClientContextValue`, exported from `eve/channels/eve`): a string, an array of strings, or a JSON object. eve turns it into model messages the same way.
+- eve labels client-supplied entries `Client context:` for the model. Returned context is sent without the label.
+- `onMessage` runs only for requests with a message. An input response keeps the context its request sent.
+
 ## Clients
 
 The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.

package/docs/channels/photon.mdx

@@ -34,8 +34,10 @@ Set `turnPolicy: "queue"` when every response should finish before Photon starts
 
 Images and other files people send reach the agent as file parts. Photon's
 webhook lists each file without its bytes, so eve downloads it from Photon by
-its attachment id with the project's credentials. A failed download, or a file
-over 25 MB, reaches the agent as a short note.
+its attachment id with the project's credentials. The webhook omits the id
+for voice notes, so eve refetches those messages from Photon to get it. A
+failed download, a file over 25 MB, or a file eve can't find an id for reaches
+the agent as a short note.
 
 Customize inbound dispatch with `onMessage`. Return `null` to ignore a message, or return `title` alongside `auth` to set the title when the dispatch starts a run:
 

package/docs/channels/slack.mdx

@@ -645,6 +645,8 @@ The callback receives the `InputRequest` and current `SessionContext`, so it can
 
 When a tool approval resolves, eve retires the messages it posted for it. The card loses its buttons and shows the answer and who gave it, the separate tool-input post is deleted, and a direct-message request's `Waiting on approval` note in the thread changes to the outcome. This also happens when the approval ends without a click, for example when the person replies in the thread instead, in which case the card reads `No longer needed`.
 
+A click on any request whose session is no longer active, for example because its run was cancelled outside eve, can never be answered. eve removes the card's buttons, marks it `No longer active`, and tells the person who clicked, in an ephemeral message, to send a new message.
+
 A renderer's `input.requested` handler can extend delivery and then hand the requests on to eve with `next()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
 
 ```ts title="agent/channels/slack.ts"
@@ -748,6 +750,8 @@ The agent receives the files attached to the message that reaches it. When a men
 
 Images, PDFs, audio, video, and other files all reach the agent. See [Inbound attachments](../sandbox#inbound-attachments) for which files the model reads directly and which it opens with tools. Files shared through an integration such as Google Drive or Dropbox are links to the other service, not Slack files, so eve skips them; their link stays in the message text. A download that fails or takes longer than 30 seconds reaches the model as a note.
 
+Slack voice clips reach the model as an audio file label, not as sound. To answer them, give the agent a transcription tool; see [Voice notes](../patterns/voice-notes).
+
 Private file downloads resolve credentials from the session's app installation workspace and require the Slack bot token's `files:read` scope. Add the scope and reinstall the Slack app before sending attachments.
 
 Downloads cover Slack's own file hosts plus URLs under a configured [`api.fileBaseUrl`](#point-the-channel-at-a-different-slack-api-host), and travel on `api.fetch` when one is configured.

package/docs/channels/teams.mdx

@@ -85,7 +85,7 @@ A human-in-the-loop (HITL) `input.requested` event renders as an Adaptive Card.
 
 By default, submissions use the Teams identity of the user who clicked the card. If you customize `onMessage` for an allowlist, configure the same policy in `onInputResponse`; eve otherwise rejects HITL submissions rather than bypassing the message gate.
 
-When a tool approval settles, eve replaces its Adaptive Card with the outcome and responder name. A response rejected by an approval policy leaves the shared card unchanged.
+When a tool approval settles, eve replaces its Adaptive Card with the outcome and responder name. A response rejected by an approval policy leaves the shared card unchanged. A submission to a card whose session is no longer active, for example because its run was cancelled outside eve, replaces the card with its prompt and `No longer active`, and the invoke response tells the person who submitted to send a new message.
 
 ### Connection sign-ins
 

package/docs/channels/telegram.mdx

@@ -49,7 +49,7 @@ The default `message.completed` handler sends plain text via `sendMessage`. It p
 
 ### Human-in-the-loop (HITL)
 
-Human-in-the-loop (HITL) turns option requests into inline-keyboard buttons and freeform requests into `ForceReply`. Telegram caps `callback_data` at 64 bytes, so eve keeps compact callback ids in channel state instead. It acknowledges its own callbacks with `answerCallbackQuery`; anything it doesn't recognize goes to `onCallbackQuery`.
+Human-in-the-loop (HITL) turns option requests into inline-keyboard buttons and freeform requests into `ForceReply`. Telegram caps `callback_data` at 64 bytes, so eve keeps compact callback ids in channel state instead. It acknowledges its own callbacks with `answerCallbackQuery`; anything it doesn't recognize goes to `onCallbackQuery`. A press on a prompt whose session is no longer active replaces the keyboard with `No longer active`, and the acknowledgement tells the person to send a new message.
 
 A text reply to a bot message is sent as a normal message, with the replied-to message id in `state.replyToBotMessageId`. When that id matches a pending `ForceReply` prompt, the channel's `deliver` hook turns the reply into the answer. Otherwise the reply reaches the agent as a message, and starts a new session when none owns the thread.
 

package/docs/code-extension.mdx

@@ -98,12 +98,13 @@ export default git({});
 
 Configure `github` to broker GitHub access through Connect instead. The extension then adds the authenticated `git__gh` tool, tells the agent to use it for every authenticated GitHub operation, and switches `git__pr` to `gh-signed-commit` for repositories that require verified signatures.
 
-| Option             | Required      | Effect                                                                                     |
-| ------------------ | ------------- | ------------------------------------------------------------------------------------------ |
-| `github.connector` | With `github` | Connector that mints a GitHub token                                                        |
-| `github.org`       | With `github` | Organization whose repositories the `gh` tool can access                                   |
-| `github.broker`    | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules |
-| `github.authorize` | No            | `authorize({ auth, repository, token })` callback that allows or denies each `gh` tool invocation |
+| Option               | Required      | Effect                                                                                            |
+| -------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
+| `github.connector`   | With `github` | Connector that mints a GitHub token                                                               |
+| `github.org`         | With `github` | Organization whose repositories the `gh` tool can access                                          |
+| `github.broker`      | With `github` | `broker(sandbox, rules)` callback that installs, then removes, the GitHub credential rules        |
+| `github.authorize`   | No            | `authorize({ auth, repository, token })` callback that allows or denies each `gh` tool invocation |
+| `github.attribution` | No            | `attribution(ctx)` callback that returns the `{ name, email }` co-author for this turn            |
 
 The `gh` tool requests a token scoped to exactly one repository in `github.org` for each invocation. The sandbox process receives a placeholder `GH_TOKEN`, and the firewall exchanges it on matching GitHub requests. Your `github.broker` callback receives the header-transform rules for the command, then `null` to remove the lease. The callback must preserve your other network rules. GitHub authentication has no command-delivery option.
 
@@ -134,6 +135,19 @@ export default git({
 });
 ```
 
+Commits made by the `gh` tool are authored by the GitHub App. To credit the person a turn works for, return them from `github.attribution`. The callback receives the tool's context, so it can read the verified caller from `ctx.session.auth.current` or resolve their linked accounts with `ctx.getToken`. The `gh` tool then ends every `gh-signed-commit` message, and every `gh pr create` body passed with `--body` or `--body-file`, with `Co-authored-by: <name> <email>`. Return `null` to publish without a co-author. `Co-authored-by` lines the agent writes itself are kept, and the trailer joins their block so they still count. Pull requests created without a body flag, such as with `--fill` or `--template`, and other paths, such as `gh api`, are not attributed.
+
+```ts
+git({
+  github: {
+    connector: "github",
+    org: "acme",
+    broker,
+    attribution: (ctx) => coAuthorFor(ctx.session.auth.current),
+  },
+});
+```
+
 ### Migrate from `code({ github })`
 
 `code({ github })` is deprecated. While it is set, the code extension still contributes `code__gh`, its GitHub instructions, and the signed-commit `code__pr` skill. Without it, the code extension contributes no GitHub tool, instructions, or pull request skill. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.

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

@@ -27,7 +27,11 @@ When a Vercel production deployment changes, a new delivery to an idle session h
 
 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.
 
-If the target deployment rejects the session, the previous owner keeps it and processes the triggering delivery. When the target deployment cannot read the checkpoint, its Vercel runtime logs show a `session handoff refused` warning with the checkpoint version and the reason. Owners on this release or later also write a `session handoff failed` warning to their own runtime logs, with the target deployment and the reason.
+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.
+
+The previous owner forwards the messages it accepted as soon as the new owner has taken over the session. Until they arrive, the new owner holds back everything it receives itself, including replies to tool runs and subagents that its first turn started, and processes it afterwards. A cancel still stops the new owner's running turn as soon as it arrives. If either run ends before the handoff settles, the other stops waiting for it.
+
+If the target deployment rejects the session, the previous owner keeps it and processes the triggering delivery, followed by any messages that arrived during the attempt. When the target deployment cannot read the checkpoint, its Vercel runtime logs show a `session handoff refused` warning with the checkpoint version and the reason. Owners on this release or later also write a `session handoff failed` warning to their own runtime logs, with the target deployment and the reason.
 
 eve does not move live work between deployments. A session with a running turn, pending human input or authorization, queued messages, or active tasks and subagents stays on its current deployment. After that work settles, a later delivery can move the idle session; the earlier deployment signal is not remembered.
 
@@ -35,7 +39,9 @@ eve does not move live work between deployments. A session with a running turn,
 
 Every workflow run records each step it executes, so a session that ran on one run for weeks would carry its whole history in that run. To bound this, eve moves a session to a fresh run on its current deployment after [compaction](./default-harness#compaction) rewrites the conversation history. This applies to automatic compaction during a turn and to a client or channel compaction request.
 
-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.
+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. A message that is already waiting when the turn settles runs on the current run first, and the session moves at the next point where nothing is waiting. A message that arrives after the move starts is accepted right away and runs once, 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.
+
+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
 
@@ -253,11 +259,14 @@ the returned handle. That identity lookup does not block workflow resumption.
 ID-addressed delivery already knows the session ID and needs no hook metadata
 lookup. An ambiguous delivery failure does not trigger session creation.
 
-While a handoff is in progress, the session's addresses are briefly unowned.
-The releasing owner leaves a short-lived marker for each address, so a
-delivery that lands in that interval retries until the successor claims the
-address instead of being reported as an inactive session. A channel therefore
-never starts a replacement session for an address that is mid-handoff.
+A handoff never leaves the session's addresses without an owner. The previous
+owner keeps every address until the new run takes all of them over, so a
+delivery during a handoff is accepted immediately and is never reported as an
+inactive session. An owner still running an earlier eve release gives up its
+addresses briefly during a handoff and leaves a short-lived marker for each
+one; a delivery that lands in that interval retries until the successor
+claims the address. Either way, a channel never starts a replacement session
+for an address that is changing owners.
 
 When a session is waiting, a delivery through its ID or any claimed channel address wakes it and starts the next turn. Message sends default to `turnPolicy: "steer"`. Before assistant output begins, the session owner signals pending model generation to stop, then applies the correction within the same turn and with the same turn ID. This includes model requests that perform provider-managed search before answering; interrupted search work may run again. Reasoning and search progress do not count as assistant output.
 

package/docs/connections/mcp.mdx

@@ -53,6 +53,10 @@ eve asks the user to sign in only when the MCP server asks for it. When a connec
 
 After the user signs in, the turn resumes and the model makes the call again. eve reconnects with the token and reloads the tool list, which may now include tools the server hides from anonymous callers. A connection that already has a token sends it on every request, as before.
 
+eve resolves credentials before each MCP HTTP request, including requests on an existing client. When the cached token's `expiresAt` has passed, eve calls the token provider again. If the server rejects a bearer with HTTP `401`, eve evicts the cached token, asks the provider for another token, and retries the request once before asking for sign-in.
+
+Eviction clears eve's cached access token and calls the provider's optional `evict` hook. The provider controls whether it retains a refresh grant for silent renewal. Missing grants and rejected replacement tokens still use the normal authorization flow; HTTP `403` permission failures do not trigger token refresh or retries.
+
 A server that leaves protected tools out of its anonymous `tools/list` never triggers sign-in, because the model cannot find those tools. Servers that support anonymous use should list every tool and refuse the protected calls.
 
 ## Static tokens and headers

package/docs/connections/overview.mdx

@@ -99,7 +99,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
+If the token has a known TTL, set `expiresAt` (milliseconds since epoch). Once it expires, eve calls `getToken` again before the next request, including requests on an existing MCP client.
 
 When `getToken` is the only auth, `credentialOwner` defaults to `"app"`: one shared credential keyed across all sessions. Set `credentialOwner: "user"` when each end-user carries their own token.
 
@@ -332,7 +332,7 @@ channels fall back to title-casing the connection name when neither is set.
 Two error classes drive the consent flow. Throw them from `getToken` or `completeAuthorization`; both are exported from `eve/connections`.
 
 - `ConnectionAuthorizationRequiredError(connectionName)`: the user must authorize. Throw it from `getToken` to emit `authorization.required` and kick off the flow.
-- `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: authorization failed. `reason` is a stable machine-readable code (e.g. `"access_denied"`) that shows up on the `authorization.completed` event and the failed tool result. `retryable` defaults to `true`; set it to `false` for terminal cases like user denial so the runtime stops re-prompting.
+- `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: authorization failed. `reason` is a stable machine-readable code (e.g. `"access_denied"`) that shows up on the `authorization.completed` event and the failed tool result. `retryable` defaults to `true`; set it to `false` for terminal cases like user denial. The `authorization.completed` event then carries `retryable: false`, and a later tool call in the same turn that needs the same grant for the same principal fails with that failure instead of asking the user to sign in again. The next turn asks again.
 
 ```ts
 import { ConnectionAuthorizationFailedError } from "eve/connections";

package/docs/evals/assertions.mdx

@@ -187,6 +187,27 @@ t.eventsSatisfy("assistant reply includes the marker", (events) =>
 );
 ```
 
+### Assert and score reasoning
+
+When the provider exposes reasoning, eve captures each completed block as a `reasoning.completed` event. Assert on its text with `turn.event(...)`, or join the blocks and pass them to a judge:
+
+```ts
+turn.event("reasoning.completed", {
+  data: { reasoning: /checks? the units/i },
+});
+
+const reasoning = turn.events
+  .filter((event) => event.type === "reasoning.completed")
+  .map((event) => event.data.reasoning)
+  .join("\n\n");
+
+t.judge("The reasoning checks its assumptions before concluding.", {
+  on: reasoning,
+}).atLeast(0.8);
+```
+
+A provider that does not expose reasoning emits no `reasoning.completed` event, so the `turn.event` gate fails and the judge grades an empty string. Reasoning the provider keeps hidden cannot be graded. The default judge input and `session.transcript` exclude reasoning, which is why the example passes it with `on`.
+
 ## Required preconditions
 
 Recorded assertions never throw and are not awaitable. When later control flow depends on a value, use `await t.require(value, assertion)`. It records a gate, returns the original value when it passes, and stops the test body without adding a duplicate execution error when it fails:

package/docs/guides/instrumentation/otel.mdx

@@ -188,6 +188,26 @@ Gateway-routed model calls propagate the configured OpenTelemetry context at
 each provider request. Eve-owned baggage is removed before forwarding. Gateway
 controls whether its spans are sampled and which destinations receive them.
 
+When AI Gateway reports
+[session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity)
+for a model call, the `agent.step` span records it. These attributes appear even
+when the trace content policy omits outputs.
+
+`vercel.ai_gateway.client_session_id` is the session ID AI Gateway used for
+affinity. It is not the eve session ID that `vercel.session_id` records. It
+equals `gen_ai.conversation.id` unless you set `gateway.sessionId` yourself or
+the ID is longer than 256 characters, in which case AI Gateway hashes it. An
+authored `gateway.sessionId` is recorded verbatim, so don't put personal data in
+it.
+
+| Attribute                                       | Value                                                           |
+| ----------------------------------------------- | --------------------------------------------------------------- |
+| `vercel.ai_gateway.client_session_id`           | Session ID AI Gateway used                                      |
+| `vercel.ai_gateway.client_session_id_source`    | `explicit`, `agent`, or `fingerprint`                           |
+| `vercel.ai_gateway.affinity.outcome`            | What affinity did, such as `promoted`, `confirmed`, or `no_pin` |
+| `vercel.ai_gateway.affinity.pinned_provider`    | Provider the session's pin named                                |
+| `vercel.ai_gateway.affinity.displaced_provider` | Provider that would have gone first, when the pin moved it      |
+
 ## Local traces
 
 `eve dev` records local traces by default. Omitting

package/docs/patterns/meta.json

@@ -6,6 +6,7 @@
     "durable-cross-channel-notifications",
     "multi-tenant-auth",
     "multi-tenant-approvals",
+    "voice-notes",
     "../protocols/ucp"
   ]
 }

package/docs/patterns/voice-notes.md

@@ -0,0 +1,67 @@
+---
+title: "Voice Notes"
+description: "Transcribe voice notes, voice messages, and other audio attachments with an AI Gateway transcription model so an eve agent can answer them."
+---
+
+Voice notes and other audio files reach your agent, but by default the model does not transcribe them. To give your agent the ability to answer a voice note, you will need to add a tool that transcribes the staged file.
+
+This works for any channel that delivers audio as a file, such as iMessage voice notes through [Photon](../channels/photon), [Slack](../channels/slack#attachments) voice clips, and files sent through the [eve](../channels/eve) and [Chat SDK](../channels/chat-sdk#attachments) channels. See [Inbound attachments](../sandbox#inbound-attachments) for how eve stages files.
+
+## Add a transcription tool
+
+```ts title="agent/tools/transcribe_audio.ts"
+import { posix } from "node:path";
+import { transcribe } from "ai";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+const TRANSCRIPTION_MODEL = "openai/whisper-1";
+const ATTACHMENTS_DIR = "/workspace/.eve/attachments/";
+
+export default defineTool({
+  description:
+    "Transcribe an audio attachment, such as a voice note, to text. Pass the path from its `Attached file` label.",
+  inputSchema: z.object({
+    path: z.string().describe(`Attachment path under ${ATTACHMENTS_DIR}`),
+  }),
+  outputSchema: z.object({ transcript: z.string() }),
+  async execute({ path }, ctx) {
+    const file = posix.normalize(path);
+    if (!file.startsWith(ATTACHMENTS_DIR)) {
+      throw new Error(`Only attachments under ${ATTACHMENTS_DIR} can be transcribed.`);
+    }
+
+    const sandbox = await ctx.getSandbox();
+    const audio = await sandbox.readBinaryFile({ path: file, abortSignal: ctx.abortSignal });
+    if (!audio) {
+      throw new Error(`Attachment not found: ${file}. Ask the user to send the voice note again.`);
+    }
+
+    try {
+      const { text } = await transcribe({
+        model: TRANSCRIPTION_MODEL,
+        audio,
+        abortSignal: ctx.abortSignal,
+      });
+      return { transcript: text.trim() };
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Transcription failed (${reason}). Tell the user you couldn't understand the voice note and ask them to type it.`,
+      );
+    }
+  },
+});
+```
+
+`transcribe()` uses the same credentials as your eve agent.
+
+## Tell the agent when to transcribe
+
+```md title="agent/instructions.md"
+When a message has an audio attachment (`Attached file ... (audio/...)`), such as a voice note, call `transcribe_audio` with its path first and treat the transcript as what the user said. Do not mention the transcription step unless it fails.
+```
+
+## When transcription fails
+
+When `execute` throws, eve gives the error to the model as a tool error, which it can relay to the user. See [When a tool throws](../tools#when-a-tool-throws). A file over the channel's upload limit, 25 MB by default, or a file eve can't download reaches the agent as a short note instead of a file.

package/docs/sandbox/index.mdx

@@ -162,6 +162,8 @@ Before every model call, eve reads the referenced files back from the sandbox. E
 
 Other files, such as CSV, HEIC, audio, and video, reach the model as the label alone. eve checks image and PDF media types against the file's bytes when it stages the file. A file whose bytes don't match its declared image or PDF type is staged as `application/octet-stream`, so a provider never receives bytes it would reject.
 
+To let the agent answer voice notes and other audio, add a tool that transcribes the staged file. See [Voice notes](/docs/patterns/voice-notes).
+
 If a referenced file is missing, or its bytes no longer match what eve staged because something in the sandbox overwrote it, the model receives a `FileNotFound` note in its place.
 
 A file that eve can't stage never enters session history. When a channel's `fetchFile` fails, or a file part's `data` is not bytes, base64, a `data:` URL, or a URL, the model receives a note that names the file instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.80.1",
+  "version": "0.81.1",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [