eve 0.81.1 → 0.82.0

package/docs/channels/linq.mdx

@@ -39,6 +39,57 @@ export default linqChannel({
 
 Set `route` to override the webhook path or `webhookVerifier` to use a different trusted-forwarder verifier.
 
+## Tapbacks
+
+eve ignores tapbacks people send unless you pass `onTapback`. It receives the tapback and returns the same result as `onMessage`, or `null` to ignore it:
+
+```ts title="agent/channels/linq.ts"
+import { connectLinqCredentials } from "@vercel/connect/eve";
+import { defaultLinqAuth, linqChannel } from "eve/channels/linq";
+
+export default linqChannel({
+  credentials: connectLinqCredentials("linq/my-agent"),
+  onTapback(_ctx, tapback) {
+    if (!tapback.added) return null;
+    return { auth: defaultLinqAuth(tapback) };
+  },
+});
+```
+
+The agent reads an accepted tapback as a message in the form iMessage uses when it shows a tapback as text, such as `Tapback: Loved “See you at 7”` or `Tapback: Removed a like tapback from a message`. The quoted text appears when Linq can return the message the tapback is on. `tapback.tapback` is `love`, `like`, `dislike`, `laugh`, `emphasize`, or `question`, or the emoji itself for an emoji tapback. `tapback.messageId` and `tapback.author` identify the message and the person. An accepted tapback starts or steers a turn like any other message, following `turnPolicy`. The agent's own tapbacks never reach `onTapback`. `onTapback` runs instead of `onMessage` for tapbacks, so repeat any sender checks from `onMessage` there. Tapbacks arrive through the `reaction.added` and `reaction.removed` webhook events, which `eve add channel/linq` subscribes to.
+
+To let the agent send tapbacks, export the channel's tapback tool from a file in `agent/tools/`. The file name becomes the tool name:
+
+```ts title="agent/tools/tapback.ts"
+import linq from "../channels/linq";
+
+export default linq.tapbackTool();
+```
+
+The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }`, and eve reacts to the latest message someone sent in the conversation. A standard tapback's own emoji, such as `👍`, sends that tapback. The model can send a tapback alongside a reply. To let a tapback be the whole answer, also add [`no_reply`](../concepts/built-in-tools#no_reply). The tool is never added on its own, and subagents don't receive it. In a session that didn't come through this channel, such as a web chat, or before anyone has sent a message, the call fails with an error the model reads.
+
+### Answer approvals with a tapback
+
+Return `answer` from `onTapback` to answer the input request eve posted in the message the tapback is on. A [tool approval](/docs/human-in-the-loop#approvals) offers the options `approve` and `cancel`, so a like or dislike on the approval prompt can approve or cancel it:
+
+```ts title="agent/channels/linq.ts"
+import { connectLinqCredentials } from "@vercel/connect/eve";
+import { defaultLinqAuth, linqChannel } from "eve/channels/linq";
+
+export default linqChannel({
+  credentials: connectLinqCredentials("linq/my-agent"),
+  onTapback(_ctx, tapback) {
+    if (!tapback.added) return null;
+    const auth = defaultLinqAuth(tapback);
+    if (tapback.tapback === "like") return { auth, answer: "approve" };
+    if (tapback.tapback === "dislike") return { auth, answer: "cancel" };
+    return { auth };
+  },
+});
+```
+
+`answer` settles only the request posted in that message, and only while it is still waiting and offers that option. A tapback on any other message, or on a prompt that was already answered, reaches the agent as an ordinary tapback, such as `Tapback: Liked “Got it”`. The approval's response policy still decides whether the person who sent the tapback may answer. For a [question](/docs/human-in-the-loop#questions), return one of its option ids. To replace the text the agent receives for a tapback, return `message`. Don't set `message` to an option's id, label, or number: eve reads that text like a typed reply, which answers the first waiting approval no matter which message the tapback is on.
+
 ## Other hosts
 
 For a host without Vercel Connect, choose **Use portable credentials** during `eve add channel/linq`. eve writes `LINQ_API_KEY` and `LINQ_WEBHOOK_SECRET` to `.env.local`.

package/docs/channels/photon.mdx

@@ -32,6 +32,10 @@ boundary. See [Overlapping messages](./overview#overlapping-messages).
 
 Set `turnPolicy: "queue"` when every response should finish before Photon starts the next message.
 
+Photon uses inbound message IDs as [delivery idempotency keys](./custom#retried-deliveries).
+Replicas that share a durable Workflow World ignore retries while the ID remains
+in the session's recent-key window.
+
 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. The webhook omits the id
@@ -57,6 +61,66 @@ export default photonIMessageChannel({
 Set `route` to override the webhook path or `webhookVerifier` to use a different
 trusted-forwarder verifier.
 
+## Tapbacks
+
+eve ignores tapbacks people send unless you pass `onTapback`. It receives the
+tapback and returns the same result as `onMessage`, or `null` to ignore it:
+
+```ts title="agent/channels/photon.ts"
+import { connectPhotonCredentials } from "@vercel/connect/eve";
+import { defaultPhotonAuth, photonIMessageChannel } from "eve/channels/photon";
+
+export default photonIMessageChannel({
+  credentials: connectPhotonCredentials("photon/my-agent"),
+  onTapback(_ctx, tapback) {
+    if (!tapback.added) return null;
+    return { auth: defaultPhotonAuth(tapback) };
+  },
+});
+```
+
+The agent reads an accepted tapback as a message in the form iMessage uses when
+it shows a tapback as text, such as `Tapback: Loved “See you at 7”`. Photon
+reports only added tapbacks, so `tapback.added` is always `true` and removing a
+tapback never reaches `onTapback`. The quoted text appears when Photon can return the message the tapback is on. `tapback.tapback` is `love`,
+`like`, `dislike`, `laugh`, `emphasize`, or `question`, or the emoji itself for
+an emoji tapback. `tapback.messageId` and `tapback.author` identify the message
+and the person. An accepted tapback starts or steers a turn like any other
+message, following `turnPolicy`. The agent's own tapbacks never reach `onTapback`. `onTapback` runs instead of `onMessage` for tapbacks, so repeat any sender checks from `onMessage` there.
+
+To let the agent send tapbacks, export the channel's tapback tool from a file in
+`agent/tools/`. The file name becomes the tool name:
+
+```ts title="agent/tools/tapback.ts"
+import photon from "../channels/photon";
+
+export default photon.tapbackTool();
+```
+
+The model calls it with a standard tapback, such as `{ "tapback": "love" }`, or any single emoji, such as `{ "tapback": "🎉" }`, and eve reacts to the latest message someone sent in the conversation. A standard tapback's own emoji, such as `👍`, sends that tapback. The model can send a tapback alongside a reply. To let a tapback be the whole answer, also add [`no_reply`](../concepts/built-in-tools#no_reply). The tool is never added on its own, and subagents don't receive it. In a session that didn't come through this channel, such as a web chat, or before anyone has sent a message, the call fails with an error the model reads.
+
+### Answer approvals with a tapback
+
+Return `answer` from `onTapback` to answer the input request eve posted in the message the tapback is on. A [tool approval](/docs/human-in-the-loop#approvals) offers the options `approve` and `cancel`, so a like or dislike on the approval prompt can approve or cancel it:
+
+```ts title="agent/channels/photon.ts"
+import { connectPhotonCredentials } from "@vercel/connect/eve";
+import { defaultPhotonAuth, photonIMessageChannel } from "eve/channels/photon";
+
+export default photonIMessageChannel({
+  credentials: connectPhotonCredentials("photon/my-agent"),
+  onTapback(_ctx, tapback) {
+    if (!tapback.added) return null;
+    const auth = defaultPhotonAuth(tapback);
+    if (tapback.tapback === "like") return { auth, answer: "approve" };
+    if (tapback.tapback === "dislike") return { auth, answer: "cancel" };
+    return { auth };
+  },
+});
+```
+
+`answer` settles only the request posted in that message, and only while it is still waiting and offers that option. A tapback on any other message, or on a prompt that was already answered, reaches the agent as an ordinary tapback, such as `Tapback: Liked “Got it”`. The approval's response policy still decides whether the person who sent the tapback may answer. For a [question](/docs/human-in-the-loop#questions), return one of its option ids. To replace the text the agent receives for a tapback, return `message`. Don't set `message` to an option's id, label, or number: eve reads that text like a typed reply, which answers the first waiting approval no matter which message the tapback is on.
+
 ## Other hosts
 
 For a host without Vercel Connect, choose **Use portable credentials** during

package/docs/channels/slack.mdx

@@ -100,7 +100,7 @@ controls observability content capture, not access to the channel. See
 
 ### Message hooks
 
-Message hooks return `{ auth }` to dispatch, `null` to drop, or `{ auth, context }` to inject background into history. Public conversations use the returned `title`, or the triggering message text when `title` is omitted. DMs and private channels always use `Private message` so the run title does not expose message details.
+Message hooks return `{ auth }` to dispatch, `null` to drop, `{ auth, context }` to inject background into history, or `{ auth, history }` to add prior conversation as user and assistant turns (see [Start from prior history](./eve#start-from-prior-history)). Public conversations use the returned `title`, or the triggering message text when `title` is omitted. DMs and private channels always use `Private message` so the run title does not expose message details.
 
 - `onMessage(ctx, message)` handles newly posted Slack messages. eve drops messages authored by the installed app before this hook runs, preventing self-reply loops. Messages from other bots remain visible; check `message.author?.isBot` when those should also be ignored. `ctx.isBotMentioned()` and `ctx.isSubscribed()` support mention and active-thread policies.
 - `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth.
@@ -247,6 +247,8 @@ export default slackChannel({
 
 `threadContext` requires the matching Slack history scope. Thread helpers reuse messages already loaded within the same inbound handler, and overlapping refreshes share one `conversations.replies` request. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
 
+When the triggering message starts the thread's session, eve adds those replies as session history instead of a transcript. Replies from this installed app become assistant turns, and replies from people and other bots become user messages with their Slack user ids attached. If the agent posted a report and people replied to it, the new session sees that report as its own earlier turn. Slack shows rendered output rather than the model's original response, so these assistant turns can differ from what the model wrote. Later messages in the same thread keep the transcript behavior above. When a hook returns its own `history`, eve keeps the transcript and does not add thread replies as history.
+
 #### Control overlapping turns
 
 Accepted Slack messages steer by default. Before assistant answer output or local tool execution begins, steering interrupts pending model generation and continues the same turn with the correction. Executing tools finish and checkpoint their results first; after answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output, and interrupted provider-managed search may run again.
@@ -302,7 +304,7 @@ Reset returns `{ status: "reset", previousSessionId }` when the thread had a ses
 
 ### Other Events API callbacks
 
-Use `onEvent` for subscribed events such as `reaction_added`, `team_join`, or `channel_created`. It receives the raw, open-ended Slack event and owns control flow. Call `ctx.send(message, { target, auth, title })` zero, one, or many times to start turns. `title` sets the run title without changing the message sent to the model. Each call returns the resulting session.
+Use `onEvent` for subscribed events such as `reaction_added`, `team_join`, or `channel_created`. It receives the raw, open-ended Slack event and owns control flow. Call `ctx.send(message, { target, auth, title, history })` zero, one, or many times to start turns. `title` sets the run title without changing the message sent to the model, and `history` adds prior conversation before the message (see [Start from prior history](./eve#start-from-prior-history)). Each call returns the resulting session.
 
 ```ts title="agent/channels/slack.ts"
 import { connectSlackCredentials } from "@vercel/connect/eve";

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

@@ -352,7 +352,7 @@ import { askQuestion } from "eve/tools/ask_question";
 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 only pending question. When other questions are also pending, a message does not answer any of them: `ask_question` withdraws its 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 scheduled run, the result is `{ status: "unavailable" }` and the model continues on its own judgment. Remove the file to remove the tool.
+`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.
 
 ### `glob`
 

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

@@ -23,7 +23,7 @@ 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.
 
-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. A successful handoff restarts the session's original configured [`sessionTimeoutMs`](../agent-config#runtime-limits) duration; disabled timeouts stay disabled. Failed or skipped handoffs keep the existing deadline.
+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.
 
@@ -39,7 +39,7 @@ 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. 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.
+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, and continuation addresses, and its [`sessionTimeoutMs`](../agent-config#runtime-limits) idle window still counts from the turn that compacted. 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.
 
@@ -66,6 +66,7 @@ See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
 For a root session, what happens next depends on how the message is addressed:
 
 - **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. 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.
@@ -121,7 +122,7 @@ export default defineDynamic({
 
 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.
+`transcriptReducer()` keeps history added with `history`, 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:
 
@@ -137,7 +138,7 @@ The transcript is context only: tools, approvals, files, sandbox contents, autho
 
 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.
+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 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.
 
@@ -163,7 +164,7 @@ fresh session.
 
 Keep the original deployment available until these sessions end. Their old
 drivers remain waiting to keep the original streams open; the current runtime
-owns subsequent turns. Import restarts the original configured session timeout;
+owns subsequent turns. Import restarts the session's idle window;
 disabled timeouts stay disabled. A driver
 that has not reached its next turn dispatch has not migrated yet.
 
@@ -259,6 +260,12 @@ 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.
 
+Pass a [delivery idempotency key](../channels/custom#retried-deliveries) to prevent
+retried input from interrupting generation or starting another turn. Each session
+remembers its last 1,024 distinct keys across replay and owner handoffs. Keyed
+cold-start sends wait for the winning session's ID; sends without a key can
+return a candidate ID before ownership is settled.
+
 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

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

@@ -21,13 +21,13 @@ whichever session currently owns a platform conversation, such as a Slack thread
 That identity stays behind the channel boundary and is never accepted or returned
 by the eve HTTP session API. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
 
-Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
-`agent.ts`, or set it to `false` to disable the deadline. A successful deployment
-handoff or legacy-session import restarts the original configured duration.
-Ordinary messages, compaction handoffs, and process restarts keep the existing deadline. At expiration, eve
-lets an active turn settle, emits `session.completed`, and releases the
-session's continuation addresses so the next qualifying channel message starts fresh. Stored
-session data is not deleted. See [Agent config](../agent-config#runtime-limits).
+A session completes after 30 idle days by default; configure
+`limits.sessionTimeoutMs` in `agent.ts`, or set it to `false` to disable the
+timeout. The idle window restarts each time a turn settles, and a session never
+expires while a turn is open. At expiration, eve emits `session.completed` and
+releases the session's continuation addresses so the next qualifying channel
+message starts fresh. Stored session data is not deleted. See
+[Agent config](../agent-config#runtime-limits).
 
 React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
 
@@ -70,6 +70,7 @@ 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, and `predecessor` when the session [replaced a stranded one](./execution-model-and-durability#what-a-replacement-session-receives). |
+| `history.imported`        | A delivery added prior conversation with `history`; carries each message's `role`, `content`, and optional `id`. Precedes that delivery's `message.received` in the same turn.                                 |
 | `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.                                                                                                                                                                                            |
@@ -343,7 +344,7 @@ Every stream event runs four steps, in this order:
 3. **Hooks**: authored [hooks](../guides/hooks) subscribed to the event fire.
 4. **Dynamic resolvers**: [dynamic](../guides/dynamic-capabilities) tool, skill, and instruction resolvers fire, and `ctx.channel.metadata` already holds the freshly projected metadata from step 2.
 
-The order is structural, not incidental. By the time a resolver or hook reads channel metadata, the channel has already updated its state and the projection is current.
+The order is structural, not incidental. By the time a dynamic resolver reads `ctx.channel.metadata`, the channel has already updated its state and the projection is current.
 
 ## What to read next
 

package/docs/connections/overview.mdx

@@ -8,7 +8,7 @@ A connection wires an agent into an external server you don't author, either an
 
 Connections live under `agent/connections/`. A static connection's runtime name comes from the filename, so `agent/connections/linear.ts` registers as `"linear"`. A dynamic connection file can instead resolve a caller-specific connection set at session or turn boundaries. The model never sees a connection's URL or credentials. It finds tools with the built-in [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill), where a query such as `linear__` searches one connection's tools, and calls them with `eve__tool`. Stream events, approval policies, and hooks name each call by its qualified name, `<connection>__<tool>` (e.g. `linear__list_issues`).
 
-A connection owns its name and every name that starts with `<name>__`, so `linear__list_issues` always means the `linear` connection's `list_issues` tool. The compiler rejects a tool, subagent, or connection whose name is a static connection's name or starts with its `<name>__` prefix. eve applies the same rule to dynamic connections, tools, and subagents when they resolve. Both errors name the two sides of the conflict; rename either one.
+A connection owns its name and every name that starts with `<name>__`, so `linear__list_issues` always means the `linear` connection's `list_issues` tool. The compiler rejects a tool, subagent, or connection whose name is a static connection's name or starts with its `<name>__` prefix. eve applies the same rule to dynamic connections, tools, and subagents when they resolve, except that a dynamic connection with exactly a static connection's name replaces that static connection; see [Naming and conflicts](/docs/guides/dynamic-capabilities#naming-and-conflicts). Both errors name the two sides of the conflict; rename either one.
 
 ## MCP connections
 

package/docs/experimental/dynamic-schedules.mdx

@@ -0,0 +1,186 @@
+---
+title: "Dynamic Schedules"
+description: "Create and manage creator-owned recurring or one-time schedules at runtime."
+---
+
+<Callout type="info" title="Feature flag required">
+  Dynamic schedules on Vercel are gated by an organization-level feature flag. Contact your Vercel
+  representative to have the feature enabled for your organization.
+</Callout>
+
+Use `defineDynamicSchedules` when users or agents need to create recurring or one-time schedules at runtime. Export the definition from `agent/schedules/`; eve derives its identity from the file path. The definition configures management tools and an occurrence callback. It does not create a schedule or set its timing.
+
+This API is experimental and may change. Import it from `eve/experimental/schedules`. For fixed, code-authored cron jobs, use [`defineSchedule`](../schedules) instead. For a self-hosted alternative with application-owned storage, see [Dynamic scheduling](../patterns/dynamic-scheduling).
+
+## Define scheduled work
+
+The model supplies schema-defined payload. eve captures the authenticated creator separately and resolves current execution auth whenever an occurrence fires.
+
+```ts title="agent/schedules/requests.ts"
+import { byPrincipal, defineDynamicSchedules } from "eve/experimental/schedules";
+import { z } from "zod";
+import slack from "../channels/slack";
+import { resolveCurrentUser } from "../lib/identity";
+import { resolveCreatorDm, resolveAuthorizedTeamChannel } from "../lib/schedule-policy";
+
+export default defineDynamicSchedules({
+  description: "Schedule Slack tasks for the creator's DM or authorized team channel.",
+  inputSchema: z
+    .object({
+      task: z.string().min(1).max(2000),
+      destination: z.enum(["my-dm", "team-channel"]),
+    })
+    .strict(),
+  scope: byPrincipal,
+  auth: ({ principal }) => resolveCurrentUser(principal),
+  async run({ payload, occurrence, to, auth }) {
+    const target =
+      payload.destination === "my-dm"
+        ? await resolveCreatorDm(auth)
+        : await resolveAuthorizedTeamChannel(auth);
+    await to(slack, target).send(
+      `Perform this task now.\nSchedule: ${occurrence.displayName}\nScheduled for: ${occurrence.scheduledAt}\nTask: ${payload.task}`,
+    );
+  },
+});
+```
+
+The identity and destination helpers are application code. `inputSchema`, `auth`, and `run` are required. `provider` is optional and defaults to `vercelScheduleProvider()`. Pass a provider explicitly to use another backend or configure the Vercel endpoint.
+
+`scope` defaults to `byPrincipal`, isolating management by authenticated principal type, authenticator, issuer, and ID, plus application and path-derived definition identity. A custom scope resolver must authorize each operation before returning a namespace; return `null` to deny.
+
+## Revalidate creator identity
+
+`auth({ principal, payload, occurrence })` resolves the stored creator reference to current execution auth. Look up current account status and permissions rather than replaying credentials or roles captured at creation. Return `null` to deny; thrown errors remain eligible for provider retries.
+
+The returned principal type, authenticator, issuer, ID, and subject must match the creator reference. eve does not fall back to app identity. Manual invocation does not replace the creator with the invoker. Tool and connection authorization still applies during execution.
+
+## Prepare payloads and destinations
+
+The generated creation and update tools validate their `payload` field with your `inputSchema`. Without `preparePayload`, eve validates payloads before persistence and again before dispatch. The complete provider envelope is limited to 64 KB; store JSON data and stable references, not credentials or sensitive recipient details.
+
+Optional `preparePayload(input, context)` validates application policy, resolves caller context, and returns the stored shape. It runs on creation and payload replacement, after input validation and scope authorization, before persistence. For model calls, eve prepares before asking for approval and provides the prepared payload to `approval.create` or `approval.update`. It prepares again before writing and rejects the call if the prepared result differs from the approved snapshot. Preparation errors reach the model before a person is asked. Authenticated code calling the client prepares once before writing, without model approval.
+
+`auth`, `run`, and occurrence events infer the prepared return type. Declare `preparePayload` before these callbacks or give it an explicit return type for TypeScript contextual inference. Without preparation, payload type comes from the schema.
+
+The input schema does not describe prepared output. eve bounds and JSON-validates the persisted envelope but does not structurally revalidate prepared application data against the input schema at execution. Authored code owns that persisted contract; validate it explicitly if needed. Preparation may repeat on write retries, so avoid irreversible effects. Reads, timing-only updates, state changes, and occurrences never rerun it.
+
+```ts
+preparePayload(input, context) {
+  const target = resolveDestination(input.destination, context);
+  return { task: input.task, target };
+},
+```
+
+`resolveDestination` is application code. For channel delivery, it can validate trusted caller context and capture channel/workspace references without exposing those fields in the model-facing schema. Reject callers that lack the required channel context, including delegated work when appropriate. Payload replacement recaptures the destination and creator from the updating caller.
+
+Destination IDs are optional. Conditional logic in `run` can derive a DM from creator identity, select an authorized configured channel, or look up a destination using another payload value. A schema may expose explicit IDs when the model can obtain them, but valid IDs do not prove access. Management scope does not authorize sending to every destination. Validate model-selected destinations against the creator's current permissions.
+
+The original creation conversation is not captured automatically. To support “reply in the exact thread where I created this,” persist an authorized thread reference through `preparePayload` or application code. Creator identity alone cannot recover that thread. Runtime lookups can follow changed configuration; persist a destination reference when the destination must stay fixed.
+
+## Expose management tools
+
+Each definition contributes tools for `create`, `get`, `list`, `update`, `enable`, `disable`, `invoke`, and `delete`. Each has its own object-rooted schema, approval policy, and readable action label. For example, `agent/schedules/billing/requests.ts` generates `schedule__billing-requests__create`, `schedule__billing-requests__update`, and the other operation names. There is no combined manage tool or operation field.
+
+Creation takes `{ name, expression, payload }`. Updates take `{ name, expression?, payload? }` and require at least an expression or a complete replacement payload. Listing takes optional `{ cursor, limit }`, with limits from 1 through 100. The remaining tools take `{ name }` using the unique identifier from receipts or reads.
+
+Set `tool: true` (the default) for direct tools, `tool: "deferred"` for catalog-discovered tools, or `tool: false` for code-only scheduling. Deferred operations keep the same names, schemas, approval policies, and authorization checks; the model finds them with `eve__search` and calls them with `eve__tool`. See [Dynamic capabilities](../guides/dynamic-capabilities#dynamic-tools).
+
+Reads need no approval by default; mutations require user approval. Configure top-level `approval`, keyed by operation, with ordinary request/response policies. Separate tool identities keep `once()` grants independent. Create and payload-replacement update policies receive a typed `payload` containing prepared data; `toolInput.payload` also contains prepared rather than raw data. Timing-only update policies receive `payload: undefined`.
+
+```ts
+approval: {
+  create: ({ payload }) => payload.target.audience === "private" ? "not-applicable" : "user-approval",
+  update: ({ payload }) => payload?.target.audience === "private" ? "not-applicable" : "user-approval",
+  delete: always(),
+},
+```
+
+Import `always` from `eve/tools/approval`; `target.audience` above is an application-owned prepared field. Combining `tool: false` with `approval` is rejected by TypeScript and runtime validation: these policies apply only to model calls, not code using `schedules(definition)`. Approvals do not bypass scope authorization or configure tools a future agent session uses.
+
+## Use the authenticated client
+
+```ts title="agent/tools/list-requests.ts"
+import { schedules } from "eve/experimental/schedules";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import requests from "../schedules/requests";
+
+export default defineTool({
+  description: "List the caller's scheduled requests.",
+  inputSchema: z.object({}),
+  async execute() {
+    return await (await schedules(requests)).list({ limit: 20 });
+  },
+});
+```
+
+Call the client inside an active eve context, not at module scope. Client creation accepts `{ name, expression, payload }`. The supplied `name` is a display label and may repeat; it must start with an ASCII letter or digit and contain only letters, digits, `.`, `_`, or `-`, up to 256 characters. eve truncates labels longer than 218 characters and appends `--` plus a UUID to allocate a unique management name.
+
+Receipts and reads include `name` (use this exact value for management) and `displayName`. Callbacks and events keep the unique identifier in `occurrence.name` and expose the readable label as `occurrence.displayName`. Approval applies to the supplied label, timing, and payload before the unique identifier is allocated.
+
+Both generated tools and authored clients check scope authorization on every operation, including during scheduled turns and local delegated work. Scheduled sessions remain unattended: mutation tools that require human approval cannot wait for it. Authorize unattended operations explicitly with `approval` policies, or use an authenticated client in authored code; neither bypasses scope checks.
+
+Authored tools, hooks, and channel events can read `ctx.session.schedule`: `undefined` for ordinary work, or `{ definition, instance?, occurrenceId? }` for scheduled work. Static schedules that run as a user are included; this is framework provenance, not an auth attribute. Custom scope policies can inspect `context.session.schedule` to deny or restrict scheduled callers. A new ordinary inbound message clears scheduled-turn context; approval/input responses preserve it.
+
+## Set timing
+
+For “in one minute,” use `expression: { type: "delay", minutes: 1 }`. eve resolves the time when the approved write executes and rounds up to minute precision, adding up to 59 seconds before provider/execution latency. Delays accept whole minutes from 1 through 525,600. Approval time is not part of the delay. A separate client retry resolves a new time; this is not a mutation-idempotency guarantee.
+
+Use `single` with a `YYYY-MM-DDTHH:mm` local datetime and IANA timezone for absolute times, or `cron` with a five-field expression and timezone for recurring work. Omitted timezones mean UTC. Relative delays do not need a timezone.
+
+```ts
+const client = await schedules(requests);
+const created = await client.create({
+  name: "daily-summary",
+  expression: { type: "cron", cron: "0 9 * * 1-5", timezone: "America/New_York" },
+  payload: { task: "Summarize open issues.", destination: "my-dm" },
+});
+
+await client.update(created.name, {
+  expression: { type: "cron", cron: "0 10 * * 1-5", timezone: "America/New_York" },
+});
+```
+
+Import `schedules` from `eve/experimental/schedules` and `requests` from your definition module. Run this code in an active eve context.
+
+## Update and control schedules
+
+`get` and `list` return identity, timing, state, and timestamps, not payload or creator data. New schedules are active; creation has no state option. Use `disable` to pause future scheduling.
+
+`client.update(name, patch)` changes timing, replaces the complete payload, or does both. Timing-only updates preserve the stored payload and creator and do not call `preparePayload`. Payload replacement validates the complete new input, reruns preparation, and captures the updating caller as the new creator. It is not a partial merge. In a shared scope, authorizing payload replacement therefore also authorizes a change of execution identity.
+
+Updates preserve the management name, schedule ID, state, and dispatch target. They cannot rename a schedule or change its state; use `enable` or `disable` for state changes. Updating an inactive or completed schedule does not activate it.
+
+Updates, enable, disable, and delete affect future scheduling, not emitted callbacks or running sessions. Use delete-and-create only when you need a separate schedule identity; replacement is not atomic.
+
+`invoke(name)` requests an additional occurrence as the stored creator. Inactive schedules may be invoked; completed schedules cannot. Manual invocation does not consume a pending one-time fire. Enqueue acceptance does not prove callback or agent success.
+
+## Handle occurrences and retries
+
+`run` receives `payload`, `occurrence`, `auth`, `to`, and `waitUntil`. It may start zero or several sessions or perform application work directly. `to(channel, target).send(message)` is bound to the resolved creator; no auth argument is needed or accepted. It starts fresh, unattended sessions through an authored channel, even when the target names an existing thread. It does not steer an existing conversation.
+
+eve awaits the callback and its registered `waitUntil` promises before reporting `occurrence.dispatched`. That event includes `sessionIds`; it means dispatch succeeded, not that the agent completed its task or delivered a successful result. Channels own output delivery and session-level failure reporting. Unattended sessions cannot wait for approvals or questions; configure tools accordingly.
+
+Provider retries may repeat the callback and start new sessions. This is an at-least-once callback contract, not exactly-once side effects. Use `occurrence.executionId` together with the schedule/resource identity to deduplicate application effects where the destination supports it. An observer failure can also cause callback retry. `occurrence.failed` reports permanent provider failures or exhaustion of the provider retry budget.
+
+## Choose a provider and test locally
+
+The default `vercelScheduleProvider()` supports these environments:
+
+| Environment                                      | Storage and delivery                                                                                                                               |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Vercel production                                | Requires feature-flag enablement for your organization. Hosted Vercel Schedules delivers occurrences through Vercel Queues.                        |
+| `eve dev` without local Vercel Schedules         | Process-local storage, with no background clock. Call `invoke` through the client to dispatch an occurrence.                                       |
+| `vc dev` with local Schedules and Queues support | Local Vercel Schedules stores timing, and eve polls local Queues to deliver due occurrences automatically.                                         |
+| Vercel preview or self-hosted production         | The default provider rejects operations. Use a different provider or the [application-managed scheduling pattern](../patterns/dynamic-scheduling). |
+
+For automatic local delivery, start eve through `vc dev` with a Vercel CLI that supports local Schedules and Queues. Plain `eve dev` still uses the in-memory fallback. Local queue-delivery errors appear in the dev server logs and retry after five seconds.
+
+Import `vercelScheduleProvider` from `eve/experimental/schedules/vercel` to configure the Vercel endpoint explicitly. The in-memory provider is also available from `eve/experimental/schedules/testing` for code-driven tests.
+
+## What to read next
+
+- [Schedules](../schedules): author fixed cron jobs with `defineSchedule`.
+- [Channels](../channels/overview): deliver schedule output to users.
+- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): inspect a scheduled run.

package/docs/experimental/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Experimental",
+  "pages": ["dynamic-schedules"]
+}

package/docs/guides/client/streaming.mdx

@@ -136,6 +136,7 @@ The most common UI events are:
 
 | Event                   | Use                                                                            |
 | ----------------------- | ------------------------------------------------------------------------------ |
+| `history.imported`      | Render prior conversation a delivery added, before that turn's message.        |
 | `message.received`      | Confirm the user message landed; `data.parts` includes text and file metadata. |
 | `reasoning.appended`    | Render reasoning deltas when the model provides them.                          |
 | `message.appended`      | Render assistant text deltas.                                                  |

package/docs/guides/deployment/self-hosting.md

@@ -34,6 +34,7 @@ You can instead select an installed Workflow world package in the root `agent.ts
 import { defineAgent } from "eve";
 
 export default defineAgent({
+  model: "anthropic/claude-opus-5.5",
   experimental: {
     workflow: {
       world: "@acme/eve-workflow-world",
@@ -105,6 +106,8 @@ You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if y
 
 The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
 
+Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
+
 ## Verify the service
 
 Check the health route after your proxy and authentication configuration are active:

package/docs/guides/hooks.md

@@ -50,7 +50,27 @@ export default githubChannel({
 
 A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts. The [Slack channel](/docs/channels/slack#customize-rendering) takes renderers instead: a renderer's handler keeps Slack's default by calling `next()` and replaces it by skipping `next`.
 
-Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
+Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For a channel with event handlers, such as `githubChannel`, `slackChannel`, and the other built-ins, the kind is the path-derived identity. `agent/channels/github.ts` reports `channel:github`, so `ctx.channel.kind === "github"` never matches. Import the channel definition and compare it with `isChannel` from `eve/channels`:
+
+```ts title="agent/hooks/github-only.ts"
+import { isChannel } from "eve/channels";
+import { defineHook } from "eve/hooks";
+
+import github from "../channels/github";
+
+export default defineHook({
+  events: {
+    async "turn.started"(_event, ctx) {
+      if (!isChannel(ctx.channel, github)) return;
+      // GitHub-owned turns only.
+    },
+  },
+});
+```
+
+A route-only `defineChannel` with no event handlers keeps the kind `"http"`, so `isChannel` does not match it in a hook. Compare `ctx.channel.kind === "http"` for those channels instead.
+
+For typed channel metadata in dynamic resolvers or instrumentation, narrow with `isChannel` the same way; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
 
 ## Hook structure and context
 

package/docs/memory/overview.mdx

@@ -87,7 +87,8 @@ automatically or only through explicit tool calls.
 `fileMemory()` from `eve/memory/file` keeps one bounded document per scope and
 gives the model `save_memory` and `remove_memory` tools. It does not extract
 facts automatically; the model decides what to save. It needs no external
-service in `eve dev` and stores to Vercel Blob when deployed to Vercel, which
+service in `eve dev` and stores to Vercel Blob when deployed to Vercel with Blob
+configured, which
 makes it the shortest path to a working slot.
 
 Read [File memory](/docs/memory/file) for size limits, storage backends, and options.

package/docs/patterns/dynamic-scheduling.md

@@ -3,7 +3,9 @@ title: "Dynamic Scheduling"
 description: "Compose one minute-level eve schedule, proactive channel handoff, and CRUD tools into application-managed schedules."
 ---
 
-Authored eve schedules are static files discovered at build time. You can build dynamic scheduling today by putting schedule rows in your application store and using one authored schedule as a dispatcher:
+Use this pattern when your application needs to own schedule storage and dispatch, including on self-hosted infrastructure. For built-in creator-owned schedules, management tools, and Vercel-backed delivery, see [Experimental dynamic schedules](../experimental/dynamic-schedules).
+
+This pattern uses a static `defineSchedule` file discovered at build time. Put schedule rows in your application store and use that authored schedule as a dispatcher:
 
 1. CRUD tools let the agent create and manage rows for the current tenant;
 2. `defineSchedule({ cron: "* * * * *" })` wakes once a minute;