eve 0.82.0 → 0.83.1

package/dist/src/tools/provided/write-file.js

@@ -1,2 +1,2 @@
-import{frameworkTool}from"./framework-tool.js";import{defineJsonSchema}from"#tools/schema.js";import{defineTool}from"#tools/definition.js";import{toolLabel}from"#tools/tool-label.js";import{executeWriteFileOnSandbox}from"#execution/sandbox/write-file.js";const WRITE_FILE_INPUT_SCHEMA=defineJsonSchema({type:`object`,properties:{content:{type:`string`,description:`Complete replacement file contents.`},filePath:{type:`string`,description:`The absolute path to the file to write. A leading $HOME is supported.`}},required:[`content`,`filePath`],additionalProperties:!1}),WRITE_FILE_OUTPUT_SCHEMA=defineJsonSchema({type:`object`,properties:{existed:{type:`boolean`},path:{type:`string`}},required:[`existed`,`path`],additionalProperties:!1}),writeFile=frameworkTool(defineTool({label:{start:e=>toolLabel(`Write`,e.filePath)},description:[`Writes a file to the local filesystem.`,``,`Usage:`,`- This tool will overwrite the existing file if there is one at the provided path.`,`- If this is an existing file, you MUST use the read_file tool first to read the file's contents. This tool will fail if you did not read the file first.`,`- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.`,`- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.`,`- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`].join(`
+import{frameworkTool}from"./framework-tool.js";import{defineJsonSchema}from"#tools/schema.js";import{defineTool}from"#tools/definition.js";import{toolLabel}from"#tools/tool-label.js";import{executeWriteFileOnSandbox}from"#execution/sandbox/write-file.js";const WRITE_FILE_INPUT_SCHEMA=defineJsonSchema({type:`object`,properties:{content:{type:`string`,description:`Complete replacement file contents.`},filePath:{type:`string`,description:`The path to the file to write: absolute, relative to the workspace root, or beginning with $HOME/.`}},required:[`content`,`filePath`],additionalProperties:!1}),WRITE_FILE_OUTPUT_SCHEMA=defineJsonSchema({type:`object`,properties:{existed:{type:`boolean`},path:{type:`string`}},required:[`existed`,`path`],additionalProperties:!1}),writeFile=frameworkTool(defineTool({label:{start:e=>toolLabel(`Write`,e.filePath)},description:[`Writes a file to the local filesystem.`,``,`Usage:`,`- This tool will overwrite the existing file if there is one at the provided path.`,`- If this is an existing file, you MUST use the read_file tool first to read the file's contents. This tool will fail if you did not read the file first.`,`- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.`,`- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.`,`- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.`].join(`
 `),async execute(e,t){return await executeWriteFileOnSandbox(await t.getSandbox(),e)},inputSchema:WRITE_FILE_INPUT_SCHEMA,outputSchema:WRITE_FILE_OUTPUT_SCHEMA}));export{WRITE_FILE_INPUT_SCHEMA,WRITE_FILE_OUTPUT_SCHEMA,writeFile as default,writeFile};

package/dist/src/tools/workflow-definition.d.ts

@@ -22,8 +22,19 @@ export interface AgentSessionOptions {
     /** Override the model for every turn in this local agent session. */
     readonly model?: AgentSessionModelSelection;
 }
-/** Context capabilities available inside an authored `"use step"` helper. */
-export type WorkflowStepToolContext = Pick<ToolContext, "abortSignal" | "callId" | "session" | "toolName" | "getToken" | "requireAuth">;
+/**
+ * Context capabilities available inside an authored `"use step"` helper.
+ *
+ * `getSandbox()` opens the sandbox of the session that made the call, the
+ * same sandbox its turns use. If the session had not recorded its sandbox
+ * when it called the tool, the step opens it with the sandbox definition of
+ * the session that owns it (the parent's, for a session that shares its
+ * parent's sandbox), so make that definition safe to run again. The step does not own the sandbox: eve lets go of the
+ * step's handle when the step ends and never stops or deletes the sandbox for
+ * it, and `stop()` and `delete()` throw. The session deletes it when the
+ * session ends. Steps can retry, so make sandbox writes safe to repeat.
+ */
+export type WorkflowStepToolContext = Pick<ToolContext, "abortSignal" | "callId" | "session" | "toolName" | "getSandbox" | "getToken" | "requireAuth">;
 /** Options for one message to a `ctx.agent` session. */
 export interface AgentSendOptions<TOutput = unknown> {
     /** Structured output for the turn, as on the client's `send`. */
@@ -61,8 +72,12 @@ export interface AgentSession {
      */
     send<TOutput = unknown>(message: string, options?: AgentSendOptions<TOutput>): Promise<AgentResponse<TOutput>>;
 }
-/** Members the context of every workflow tool entry point shares. */
-export type WorkflowSharedContext = Pick<ToolContext, "session" | "toolName" | "getToken" | "requireAuth"> & {
+/**
+ * Members the context of every workflow tool entry point shares.
+ * `getSandbox`, `getToken`, and `requireAuth` work only after `ctx` is passed
+ * to a `"use step"` helper; the workflow body throws when it calls them.
+ */
+export type WorkflowSharedContext = Pick<ToolContext, "session" | "toolName" | "getSandbox" | "getToken" | "requireAuth"> & {
     /**
      * Returns a new session with the agent of this invocation name. Nothing
      * starts until the first `send`.

package/dist/src/vue/index.js

@@ -1,4 +1,4 @@
-import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DTu78IAF.js";
+import { a as conversationProjection, i as openConversationInputs, n as conversationReducer, o as callStatus, r as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-DnbG9c7c.js";
 
 //#region src/client/tool-call-state.ts
 function toolCallState(conversation, callId, options = {}) {

package/dist/src/vue/use-eve-agent.d.ts

@@ -110,7 +110,7 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
      * on the next send, answer, or resume. @default true
      */
     readonly followIdle?: boolean;
-    /** Prewarm an owned session on mount and after reset. @default false */
+    /** Create a session or prepare its existing idle owner on mount and after reset. @default false */
     readonly prewarm?: boolean;
     /**
      * Projects stream events into `TData`.

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-DTu78IAF.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-DnbG9c7c.js";
 
 export { useEveAgent };

package/docs/channels/custom.mdx

@@ -68,7 +68,7 @@ Each route receives these operation surfaces:
 - `to(channel, target).send(message, options)` hands work to another authored channel.
 - `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
 - `describe()` returns the agent's name, description, the compiled tools a caller can run outside a turn, with their JSON schemas, and the compiled skills, each with its `name` and `description`, sorted by name. It reads the compiled manifest only, never a skill file, and carries no other paths, config, or inspection detail, so a channel can publish it to its callers. Tools that need a turn (framework tools, workflow and provider tools, tools without `execute`) and tools and skills added by dynamic resolvers or subagents are left out.
-- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox or just-bash, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
+- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox, just-bash, or a custom provider that sets `toolSessions: true`, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
 
   A direct call doesn't go through the AI SDK, so AI SDK telemetry integrations never see it. Conversation tool calls do: an integration that an `agent/instrumentation/*.ts` module registers with `registerTelemetry()` from `ai` receives `onToolExecutionStart` and `onToolExecutionEnd` for each of them. A direct call is traced by eve itself instead. It gets an `execute_tool` span under the caller's trace and emits `tool.call.started` and `tool.call.completed` to instrumentation. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
 
@@ -124,10 +124,10 @@ const currentSession = await resolveSession(threadId);
 ```
 
 When the session at an address is
-[stranded](../concepts/execution-model-and-durability#stranded-sessions) because another eve version
+[stranded](../guides/deployment/self-hosting#recover-a-stranded-session) because another eve version
 built it, `send()` ends that session and starts a fresh one. The message becomes the fresh
 session's first turn, and the fresh session can read recent text from the earlier conversation;
-see [What a replacement session receives](../concepts/execution-model-and-durability#what-a-replacement-session-receives). Concurrent sends to the same stranded address still
+see [Recover a stranded session](../guides/deployment/self-hosting#recover-a-stranded-session). Concurrent sends to the same stranded address still
 produce one fresh session. A `respond()` call, or a `deliver()` that includes input responses,
 carries answers a fresh session has no request for, so it throws `SessionStrandedError` and leaves
 the stranded session in place.

package/docs/channels/discord.mdx

@@ -1,10 +1,10 @@
 ---
 title: "Discord"
-description: "Reach your agent from Discord HTTP Interactions, including slash commands, components, and modals."
+description: "Reach your agent from Discord messages, DMs, and mentions, and from slash commands, components, and modals."
 type: integration
 ---
 
-The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel acknowledges the command right away and runs the eve work in the background. Credentials and inbound request verification run through [Vercel Connect](../guides/auth-and-route-protection), so Discord's bot token stays out of your environment and Connect verifies Discord's signature before forwarding an interaction to eve. See [Channels](./overview) for the contract this builds on.
+The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel acknowledges the command right away and runs the eve work in the background. Credentials and inbound request verification run through [Vercel Connect](../guides/auth-and-route-protection), so Discord's bot token stays out of your environment and Connect verifies Discord's signature before forwarding an interaction to eve. To also answer DMs and mentions, add a [Discord Gateway relay](#reply-to-dms-and-mentions-experimental). See [Channels](./overview) for the contract this builds on.
 
 ## Set up Discord
 
@@ -14,19 +14,24 @@ Run the guided setup from your eve project:
 pnpm eve add channel/discord
 ```
 
-The setup guides you through creating a Discord application and bot, then:
+The setup first asks how people should reach the agent: through **DMs, mentions, and threads**, or through **a slash command**. It then guides you through creating a Discord application and bot, and:
 
 - signs you in to Vercel and creates or links a project when needed;
 - validates the bot token;
 - creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
-- registers an application command with a required `message` option and an optional `file` attachment option;
-- configures the Discord application's Interactions Endpoint URL;
+- configures the Discord application's Interactions Endpoint URL, which buttons such as HITL choices and sign-ins use either way;
+- for DMs, mentions, and threads, writes the [Gateway relay](#run-the-relay-as-a-vercel-daemon) in `daemon/`, registers it in `vercel.json` in the project's first function region, and turns on the bot's Message Content intent when Discord allows it;
+- for a slash command, registers it with a required `message` option and an optional `file` attachment option;
 - scaffolds the channel with Connect-managed credentials; and
 - prints the bot installation URL.
 
-The command defaults to `/ask` with the description **Ask the eve agent**. You can edit both during setup. Discord global commands can take up to an hour to appear after registration.
+The slash command defaults to `/ask` with the description **Ask the eve agent**. You can edit both during setup. Discord global commands can take up to an hour to appear after registration. A bot that answers messages can take slash commands too: register one as described in [Configure Discord manually](#configure-discord-manually), and the channel handles it.
 
-The generated channel looks like this:
+In a non-interactive run, answer `discord-messages` with `"gateway"` for DMs, mentions, and threads, or `"commands"` for a slash command. `--yes` picks the slash command, because the relay is experimental and runs as an always-on Vercel Daemon.
+
+If your project configures Vercel in `vercel.ts`, setup leaves it alone and prints the `daemons` entry to add to it.
+
+The generated channel looks like this, plus `gateway: {}` when the agent answers messages:
 
 ```ts title="agent/channels/discord.ts"
 import { connectDiscordCredentials } from "@vercel/connect/eve";
@@ -53,6 +58,267 @@ curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/co
 
 Then configure the public `https://…/eve/v1/discord` route as the application's Interactions Endpoint URL. Pass `credentials: { applicationId, botToken, publicKey }` to `discordChannel`, or set the corresponding `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, and `DISCORD_PUBLIC_KEY` environment variables.
 
+## Reply to DMs and mentions (experimental)
+
+Discord sends ordinary messages, such as DMs, mentions, and thread replies, only over its [Gateway WebSocket](https://discord.com/developers/docs/events/gateway), not as HTTP Interactions. Gateway support is experimental, and its API may change. To receive them, run `experimental_runDiscordGatewayRelay` from `eve/channels/discord/gateway` in a process that stays connected, and enable the matching route on the channel. The relay forwards each `MESSAGE_CREATE` dispatch to the agent unchanged, and the channel replies through the same handlers it uses for commands, including HITL buttons and error messages.
+
+```text
+Discord Gateway ── WebSocket ──▶ relay (Vercel Daemon) ── POST /eve/v1/discord/gateway ──▶ agent ── REST ──▶ Discord
+```
+
+### Enable the Gateway route
+
+Add `gateway` to the channel. It mounts `POST /eve/v1/discord/gateway`. Because each forwarded message names its author, the route by default accepts only `localDev()` and Vercel OIDC tokens from the same project and environment, which excludes preview deployments calling production:
+
+```ts title="agent/channels/discord.ts"
+import { connectDiscordCredentials } from "@vercel/connect/eve";
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  credentials: connectDiscordCredentials("discord/my-agent"),
+  gateway: {},
+});
+```
+
+Vercel Connect is optional here too: without `credentials`, the channel reads `DISCORD_APPLICATION_ID` and `DISCORD_BOT_TOKEN`, and the relay reads `DISCORD_BOT_TOKEN`. Pass `gateway.auth` to accept a relay that [runs outside Vercel](#run-the-relay-outside-vercel), and `gateway.route` to change the path. Whoever passes `gateway.auth` can send messages as any Discord user, so keep it as narrow as the default.
+
+### Run the relay as a Vercel Daemon
+
+A Vercel Daemon keeps the relay connected. Vercel Daemons are in beta. When you choose to answer messages, `eve add channel/discord` writes these files for you. To add them yourself, put the relay in its own directory with the same credentials as the agent:
+
+```ts title="daemon/main.ts"
+import { connectDiscordCredentials } from "@vercel/connect/eve";
+import { experimental_runDiscordGatewayRelay } from "eve/channels/discord/gateway";
+
+await experimental_runDiscordGatewayRelay({
+  credentials: connectDiscordCredentials("discord/my-agent"),
+  messageContent: false,
+  url: process.env.EVE_URL,
+});
+```
+
+```json title="daemon/package.json"
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@vercel/connect": "<same version as your agent>",
+    "eve": "<same version as your agent>"
+  }
+}
+```
+
+The image installs from `package-lock.json` too, if you commit one in `daemon/`:
+
+```dockerfile title="daemon/Dockerfile"
+FROM node:24-slim
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package*.json ./
+RUN npm install --omit=dev --no-audit --no-fund
+COPY main.ts ./
+USER node
+CMD ["node", "main.ts"]
+```
+
+Register the daemon in `vercel.json` with exactly one instance:
+
+```json title="vercel.json"
+{
+  "daemons": {
+    "discord-gateway": {
+      "root": "daemon",
+      "entrypoint": "Dockerfile",
+      "instances": { "iad1": 1 }
+    }
+  }
+}
+```
+
+On Vercel, the relay sends messages to `https://$VERCEL_PROJECT_PRODUCTION_URL` and signs each request with the project's Vercel OIDC token, so the agent and relay need no shared secret. Set `url` to send them elsewhere.
+
+The bot needs the **Send Messages in Threads** permission to reply in threads, in addition to **View Channels** and **Send Messages**, and **Create Public Threads** to [start threads](#reply-in-threads). This install URL grants all four plus **Read Message History**; replace `<APPLICATION_ID>`:
+
+```text
+https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applications.commands&permissions=309237713920
+```
+
+### Run the relay outside Vercel
+
+`experimental_runDiscordGatewayRelay` runs on any host that keeps a Node.js 24 process up, such as a VM, a container platform, or a home server, while the agent stays on Vercel. Run exactly one relay per bot. Three things change off Vercel:
+
+- **Credentials.** Vercel Connect authenticates callers with your project's Vercel OIDC token, which other hosts don't have, so give the relay the bot token directly. The agent can keep using Connect.
+- **URL.** The relay can't read `VERCEL_PROJECT_PRODUCTION_URL`, so pass the agent's URL as `url`.
+- **Auth.** The route's default auth accepts only your Vercel project's own runtime. Use a shared secret instead: `basic()` from `eve/agents/auth` signs the relay's requests, and `httpBasic()` on `gateway.auth` checks them.
+
+Generate a long random secret, for example with `openssl rand -hex 32`, and set it as `DISCORD_RELAY_SECRET` on both the agent's Vercel project and the relay's host. On the agent:
+
+```ts title="agent/channels/discord.ts"
+import { connectDiscordCredentials } from "@vercel/connect/eve";
+import { httpBasic, localDev } from "eve/channels/auth";
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  credentials: connectDiscordCredentials("discord/my-agent"),
+  gateway: {
+    auth: [
+      localDev(),
+      httpBasic({ username: "discord-relay", password: process.env.DISCORD_RELAY_SECRET! }),
+    ],
+  },
+});
+```
+
+On the relay, set `DISCORD_BOT_TOKEN` to the token from **Bot** → **Reset Token** in the Discord Developer Portal, and `EVE_URL` to the agent's production URL:
+
+```ts title="relay/main.ts"
+import { basic } from "eve/agents/auth";
+import { experimental_runDiscordGatewayRelay } from "eve/channels/discord/gateway";
+
+await experimental_runDiscordGatewayRelay({
+  // Reads DISCORD_BOT_TOKEN when `credentials` is omitted.
+  url: process.env.EVE_URL,
+  auth: basic({ username: "discord-relay", password: process.env.DISCORD_RELAY_SECRET! }),
+});
+```
+
+The relay's `package.json` needs only `eve`. Build the image from the same Dockerfile as the [daemon](#run-the-relay-as-a-vercel-daemon), then run it with a restart policy so a crash or host reboot brings it back:
+
+```bash
+docker run -d --restart unless-stopped \
+  -e DISCORD_BOT_TOKEN -e DISCORD_RELAY_SECRET -e EVE_URL=https://my-agent.vercel.app \
+  discord-relay
+```
+
+The relay stops on `SIGTERM` after delivering what it has in flight. It exits with an error when Discord refuses the bot token or intents, and restarting it won't help until you fix the configuration. If Deployment Protection covers the URL the relay posts to, create a Protection Bypass for Automation secret, and pass `auth` a function that returns the Basic `authorization` header together with an `x-vercel-protection-bypass` header carrying that secret.
+
+### Who the bot answers
+
+By default the channel answers a message when it is a DM, mentions the bot, replies to one of the bot's messages, or arrives in a thread where the bot already has a conversation. It strips the bot's mention from the text, and it never answers messages from bots, including its own. Messages group into sessions this way:
+
+| Message                              | Session                                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------------------- |
+| A DM                                 | One per DM channel                                                                     |
+| A message in a thread                | One per thread                                                                         |
+| A mention in a text channel          | A new [thread](#reply-in-threads) started from the message, one session for the thread |
+| A reply to the bot in a text channel | The session that posted the replied-to message                                         |
+
+A mention in a text channel starts a thread, as the Slack channel does, so each conversation stays out of the channel and two people, or one person's unrelated questions, don't share context. Every message the bot posts continues its session when someone replies to it, including slash command responses in the channel. A reply to a bot message that no live session owns starts a new thread.
+
+Mention the bot's user, not the role with the same name that Discord creates for it. Discord's autocomplete offers both, and a role mention doesn't address the bot.
+
+Discord sends the text of messages that neither mention the bot nor arrive as a DM only to bots with the privileged **Message Content** intent. Without it, thread follow-ups that skip the mention, and replies whose author turned off the reply ping, arrive empty and are ignored. `eve add channel/discord` turns the intent on and sets `messageContent: true` when Discord allows it, which it does for bots in fewer than 100 servers. Otherwise, enable **Message Content Intent** under **Bot** in the Discord Developer Portal, then pass `messageContent: true` to `experimental_runDiscordGatewayRelay`. Discord refuses the relay's connection if you request the intent before enabling it, and the relay stops with an error naming the close code.
+
+To choose which messages run the agent, under what `auth`, or which session they join, set `gateway.onMessage(ctx, message)`. It runs for every message from a person and returns `{ auth }` to dispatch or `null` to ignore. `message.addressed` reports whether the default would answer, and `message.referencedMessageId` names the message it replies to. `defaultDiscordMessageAuth(message)` gives the author the same principal `defaultDiscordAuth` gives them for commands and button presses, so requester-only approvals work across both:
+
+```ts
+import { defaultDiscordMessageAuth, discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  gateway: {
+    onMessage: (_ctx, message) =>
+      message.addressed && message.guildId === "123456789012345678"
+        ? { auth: defaultDiscordMessageAuth(message) }
+        : null,
+  },
+});
+```
+
+Return `conversation` to change how messages group. Messages with the same key share a session within their Discord channel. A message ID is the key of the session that owns that message, `"channel"` is one session for the whole channel, and any other string is your own grouping. Omit it to keep the default above. For example, to give each person one ongoing session per channel:
+
+```ts
+import { defaultDiscordMessageAuth, discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  gateway: {
+    onMessage: (_ctx, message) =>
+      message.addressed
+        ? { auth: defaultDiscordMessageAuth(message), conversation: `user:${message.author.id}` }
+        : null,
+  },
+});
+```
+
+### Reply in threads
+
+By default, the bot answers a mention in a text channel in a new thread. The channel starts a public thread from the person's message, named after its first line, and adds the person to it. The thread holds one session, so later messages in it continue the conversation. Threads apply only to messages that would start a new session in a text channel. DMs, messages already in a thread, and replies that continue a session stay where they are. If Discord refuses to create the thread, for example because the bot lacks **Create Public Threads**, the bot answers in the channel instead.
+
+To answer in the channel instead, set `gateway.startThread` to `false`. A mention then starts a session in the channel, and replies to the bot's messages continue it:
+
+```ts title="agent/channels/discord.ts"
+import { connectDiscordCredentials } from "@vercel/connect/eve";
+import { discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  credentials: connectDiscordCredentials("discord/my-agent"),
+  gateway: { startThread: false },
+});
+```
+
+`onMessage` can decide per message by returning `startThread`, which overrides `gateway.startThread`. Return `false` to answer in the channel, `true` for a thread, or options to name the thread and set how long Discord waits before archiving it:
+
+```ts
+import { defaultDiscordMessageAuth, discordChannel } from "eve/channels/discord";
+
+export default discordChannel({
+  gateway: {
+    onMessage: (_ctx, message) =>
+      message.addressed
+        ? {
+            auth: defaultDiscordMessageAuth(message),
+            startThread: message.attachments.length > 0 && {
+              name: `Review: ${message.attachments[0]!.filename}`,
+              autoArchiveMinutes: 1440,
+            },
+          }
+        : null,
+  },
+});
+```
+
+### Forward messages from your own relay
+
+The route accepts any relay that holds a Gateway connection, such as an existing discord.js bot, so you don't have to run `experimental_runDiscordGatewayRelay`. Forward each Gateway dispatch payload unchanged, as the JSON body of a `POST` to `/eve/v1/discord/gateway`:
+
+```json
+{
+  "op": 0,
+  "t": "MESSAGE_CREATE",
+  "s": 42,
+  "d": { "id": "…", "channel_id": "…", "author": { "…": "…" } }
+}
+```
+
+The route handles `MESSAGE_CREATE` and acknowledges other dispatch types without acting on them. Authenticate the request as `gateway.auth` requires; by default, that is a Vercel OIDC token from the same project and environment. The relay needs the `GUILD_MESSAGES` (`1 << 9`) and `DIRECT_MESSAGES` (`1 << 12`) intents, plus `MESSAGE_CONTENT` (`1 << 15`) for messages that don't mention the bot. Use the response status to decide whether to retry:
+
+| Status | Meaning                                                                                                                                | Relay should                               |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `202`  | A turn started. The body is `{ accepted: true, sessionId }`.                                                                           | Stop.                                      |
+| `200`  | Ignored on purpose. The body is `{ accepted: false, reason }`, for example `not_accepted`.                                             | Stop.                                      |
+| `400`  | The body is not JSON.                                                                                                                  | Not retry.                                 |
+| `401`  | Authentication failed.                                                                                                                 | Fix credentials, not retry.                |
+| `413`  | The body is over 1 MB.                                                                                                                 | Not retry.                                 |
+| `429`  | Rate limited before the route ran.                                                                                                     | Retry with backoff.                        |
+| `5xx`  | Unknown. The route answers `500` before dispatch when `onMessage` throws, but a platform `502` or `504` can come after a turn started. | Not retry, unless your relay deduplicates. |
+
+eve does not deduplicate messages. If the relay retries after eve already started a turn, for example because the response was lost, the agent answers twice. `experimental_runDiscordGatewayRelay` retries only a `429`, or a connection that failed before the request reached eve.
+
+### Run the relay locally
+
+Pull a development OIDC token with `vercel env pull .env.local`, start `eve dev`, then run the relay against it from another terminal:
+
+```bash
+EVE_URL=http://localhost:2000 node --env-file=.env.local daemon/main.ts
+```
+
+Scale the production daemon to zero while you do this. Every connection receives every message, so two relays make the agent answer twice.
+
+### Limitations
+
+- Run one relay per bot. Each connection receives every message. Bots large enough to need Discord's sharding are out of scope.
+- Messages sent while no relay is connected are not delivered. On a deploy, Vercel sends `SIGTERM` to the old daemon and starts the new one at the same time. The old relay disconnects right away, so messages sent while the new daemon boots and connects, usually a few seconds, are lost. A crash or restart leaves the same gap. The relay does not resume the previous Gateway session in a new process, so Discord does not replay these messages.
+- `experimental_runDiscordGatewayRelay` drops a message, rather than retrying it, when eve answers with a `5xx`, takes longer than 30 seconds to accept it, or the connection fails after the request is sent. eve may have started the turn already, and a retry could answer twice. The relay logs each dropped message.
+
 ## How the channel handles messages
 
 ### Dispatch
@@ -116,6 +382,12 @@ export default discordChannel({
 });
 ```
 
+### Connection sign-ins
+
+When a connection needs the person to sign in, the default `authorization.required` handler posts it to the conversation. In a DM, the message includes a link button to the sign-in page and any confirmation code. In a server, the shared message only says who has to sign in and has a **Sign in** button. When someone presses it, eve identifies them the same way it does for HITL presses (`onInputResponse`). If that's the person who has to sign in, eve answers with an ephemeral message holding the link and code, which only they can see. Anyone else gets an ephemeral note that they can't open it. That way another member can't finish the sign-in with their own account and have it saved under the requester's identity. Once the sign-in completes or is cancelled, eve edits the message to say so and removes its button.
+
+If `onCommand` or `gateway.onMessage` gives people principals other than the default, set `onInputResponse` to the same mapping. Otherwise eve can't match a press to the person who has to sign in, and nobody can open the sign-in in a server.
+
 ### Proactive sessions
 
 Start a session without an inbound interaction through `to(discord, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(discord, target).send(message, { auth })` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs a bot token, supplied by Connect or `DISCORD_BOT_TOKEN`.

package/docs/channels/eve.mdx

@@ -91,7 +91,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
 - `GET /eve/v1/health` (check whether the application is reachable)
 - `GET /eve/v1/info` (inspect the agent)
 - `POST /eve/v1/session` (create a session, optionally sending its first message)
-- `POST /eve/v1/session/:sessionId` (send a follow-up)
+- `POST /eve/v1/session/:sessionId` (send a follow-up, respond to an input request, or prepare an idle session with an empty body)
 - `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
 - `POST /eve/v1/session/:sessionId/clear` (clear the session's model history)
 - `POST /eve/v1/session/:sessionId/compact` (compact the session's context)
@@ -100,6 +100,17 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
 
 The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
 
+`POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session using
+the channel's auth policy. Non-empty bodies retain the message and input-response behavior;
+empty or invalid messages and payloads without either input are rejected. Preparation
+returns `{ ok: true, status }`: `ready` when the owner already uses the serving
+deployment, `accepted` (HTTP 202) when a background preparation hint has been queued,
+`unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
+owner exists. Other successful statuses use HTTP 200. Acceptance does not mean the handoff
+has completed. Idle preparation preserves the session ID, stream, history, and expiry;
+active work is not interrupted. See the [frontend guide](../guides/frontend/overview#returned-state)
+for client usage and deployment routing.
+
 `GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
 
 ### Start and continue a session
@@ -402,7 +413,7 @@ export default defineChannel({
 
 The client then resumes that session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when a session already owned the address, or another `create()` or `send()` claimed it first. That session comes back unchanged and your `history` was not added, so check `created` before treating the session as seeded. Use a new address for each new conversation or branch.
 
-When the session at the address is [stranded](../concepts/execution-model-and-durability#stranded-sessions), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `reset()` on the address, then `create()` again.
+When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `reset()` on the address, then `create()` again.
 
 `create()` returns once the new session claims its address, so a `send()` right after it reaches that session. It throws if no session claims the address within 15 seconds.
 

package/docs/channels/linq.mdx

@@ -16,7 +16,7 @@ export default linqChannel({
 });
 ```
 
-The default webhook route is `/eve/v1/linq`. The channel verifies forwarded webhooks with same-project Vercel OIDC by default, derives user auth from each message author, marks accepted messages as read, and continues the same eve session for every message in a Linq conversation. A new accepted message steers the active turn. Before answer output or local tool execution begins, steering can interrupt pending model generation. Executing tools finish first; after answer output starts, steering waits for the next committed workflow boundary. See [Overlapping messages](./overview#overlapping-messages).
+The default webhook route is `/eve/v1/linq`. The channel verifies forwarded webhooks with Vercel OIDC from the same project and environment by default, derives user auth from each message author, marks accepted messages as read, and continues the same eve session for every message in a Linq conversation. A new accepted message steers the active turn. Before answer output or local tool execution begins, steering can interrupt pending model generation. Executing tools finish first; after answer output starts, steering waits for the next committed workflow boundary. See [Overlapping messages](./overview#overlapping-messages).
 
 Set `turnPolicy: "queue"` when every response should finish before Linq starts the next message.
 
@@ -37,7 +37,7 @@ export default linqChannel({
 });
 ```
 
-Set `route` to override the webhook path or `webhookVerifier` to use a different trusted-forwarder verifier.
+Set `route` to override the webhook path or `webhookVerifier` to use a different trusted-forwarder verifier. A verifier rejects a webhook by throwing or returning a falsy value such as `null` or `false`.
 
 ## Tapbacks
 

package/docs/channels/mcp.mdx

@@ -308,13 +308,13 @@ Tool sessions need an authenticated caller. With `auth: none()` every request is
 In a tool session:
 
 - The sandbox opens on the first `ctx.getSandbox()` and is kept for later calls with the same key. Concurrent first calls share one sandbox.
-- The sandbox belongs to the agent's current sandbox definition. A deploy that changes it (the template, its snapshot, or the open options in `sandbox.ts` and its resources) starts a fresh, empty sandbox for the same key; the old one expires as below.
+- The sandbox is found from the session id alone. A deploy that changes the sandbox definition (the template, its snapshot, the open options in `sandbox.ts`, or its resources) keeps using the existing sandbox for the key; the current definition applies only when a sandbox is created, such as after the old one expires as below. Deployments that share a sandbox namespace, such as preview and production deployments of one Vercel project, also share the sandbox for the same principal and key.
 - `ctx.session.id` is the same for every call with the key.
 - Traces still show each call as its own run. Its `agent.run.id` and `gen_ai.conversation.id` are a fresh id for that call, not `ctx.session.id`, so traces do not link calls that share a key.
 - Authored state still starts from its initial value on every call, and updates are not kept. Keep data that must outlive a call in the sandbox.
 - Calls may still run in parallel, and nothing orders them.
 
-Tool sessions need a sandbox provider that finds the session's sandbox again: Vercel Sandbox or just-bash. On another provider, a call with a key fails with a `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` error when the tool opens its sandbox. Tools that never open a sandbox still run. just-bash keeps its sandboxes on the local disk, so on Vercel Functions a just-bash tool session lasts only as long as the function instance.
+Tool sessions need a sandbox provider whose kept sandboxes stay bounded: Vercel Sandbox, just-bash, or a [custom provider](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls) that sets `toolSessions: true`. On another provider, a call with a key fails with a `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` error when the tool opens its sandbox. Tools that never open a sandbox still run. just-bash keeps its sandboxes on the local disk, so on Vercel Functions a just-bash tool session lasts only as long as the function instance.
 
 A tool session has no end, so eve bounds how long its sandbox is kept. On Vercel Sandbox, a tool-session sandbox's saved filesystem expires a day after its last use, and each call that resumes it restarts that day. The next call with the key after that replaces it with a fresh, empty sandbox. If two calls with the key find the expired filesystem at the same time, each can replace the sandbox, and files the first one writes can be lost. Vercel only keeps the latest snapshot of the sandbox. Tool sessions use this one-day expiry whatever `snapshotExpiration` `sandbox.ts` sets; sessions that conversations start keep the authored setting.
 

package/docs/channels/overview.mdx

@@ -98,7 +98,7 @@ eve's first-class channels use eve-owned runtimes for webhook handling, verifica
 | Slack mentions, DMs, buttons                | [Slack](./slack)                                           |
 | iMessage and SMS                            | [Linq](./linq)                                             |
 | iMessage                                    | [Photon](./photon)                                         |
-| Discord slash commands, components          | [Discord](./discord)                                       |
+| Discord messages, DMs, slash commands       | [Discord](./discord)                                       |
 | Microsoft Teams messages + Adaptive Cards   | [Teams](./teams)                                           |
 | Telegram bot messages                       | [Telegram](./telegram)                                     |
 | SMS or speech-transcribed phone calls       | [Twilio](./twilio)                                         |

package/docs/channels/photon.mdx

@@ -22,7 +22,7 @@ export default photonIMessageChannel({
 ```
 
 The default webhook route is `/eve/v1/photon`. The channel verifies forwarded
-webhooks with same-project Vercel OIDC by default, derives user auth from each
+webhooks with Vercel OIDC from the same project and environment by default, derives user auth from each
 message author, marks accepted messages as read, and continues the same eve
 session for every message in an iMessage conversation. A new accepted message
 steers the active turn. Steering can interrupt pending model generation before

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

@@ -81,7 +81,7 @@ export default disableTool();
 
 ### `read_file`
 
-`read_file` reads text files from the sandbox with line-numbered output, and shows PNG, JPEG, GIF, and WebP images up to 3 MiB and 8000 pixels per side, and PDFs up to 20 MiB, to the model as files. Images and PDFs are detected from their bytes, so a missing or mismatched filename extension does not matter, and other text files are always read as text. It accepts absolute paths and paths beginning with `$HOME/`.
+`read_file` reads text files from the sandbox with line-numbered output, and shows PNG, JPEG, GIF, and WebP images up to 3 MiB and 8000 pixels per side, and PDFs up to 20 MiB, to the model as files. Images and PDFs are detected from their bytes, so a missing or mismatched filename extension does not matter, and other text files are always read as text. It accepts absolute paths, paths relative to the workspace root where `bash` commands start, and paths beginning with `$HOME/`. Results and errors name the resolved absolute path.
 
 ```sh
 eve add tool/read_file
@@ -113,7 +113,7 @@ export default disableTool();
 
 ### `write_file`
 
-`write_file` writes complete files in the sandbox. It enforces read-before-write and stale-read detection, and accepts absolute paths and paths beginning with `$HOME/`.
+`write_file` writes complete files in the sandbox. It enforces read-before-write and stale-read detection, and accepts the same paths as `read_file`.
 
 ```sh
 eve add tool/write_file
@@ -131,10 +131,15 @@ import { writeFile } from "eve/tools/write_file";
 
 export default defineTool({
   ...writeFile,
-  description: "Write approved project files in the sandbox.",
+  description: "Write notes in the sandbox's notes directory.",
   async execute(input, ctx) {
-    if (!input.filePath.startsWith("/workspace/")) {
-      throw new Error("write_file is limited to /workspace");
+    const sandbox = await ctx.getSandbox();
+    const notes = `${sandbox.resolvePath("notes")}/`;
+    if (
+      input.filePath.startsWith("$HOME") ||
+      !sandbox.resolvePath(input.filePath).startsWith(notes)
+    ) {
+      throw new Error("write_file is limited to the notes directory");
     }
     return writeFile.execute(input, ctx);
   },
@@ -291,7 +296,25 @@ eve add tool/agent
 export { default } from "eve/tools/agent";
 ```
 
-An authored tool at `agent/tools/agent.ts` replaces the framework behavior. Re-export the definition above to restore direct root-copy delegation, export another tool such as `agentRouter()` to change the model-facing behavior, or disable the slot. `agentRouter()` runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task), which adds `eve__task_wait` and `eve__task_cancel`:
+To let the model choose an AI Gateway model for each root-copy task, export `agentWithModel` from the same slot:
+
+```ts title="agent/tools/agent.ts"
+export { agentWithModel as default } from "eve/tools/agent";
+```
+
+This is a separate workflow tool that calls `ctx.agent("agent", { model })`. The default `agent` tool remains unchanged and does not gain a `model` parameter. The opt-in definition accepts:
+
+```ts
+{
+  message: string;
+  model: string; // AI Gateway model id for the child session
+  taskId?: string;
+}
+```
+
+It otherwise has the default tool's task behavior: a call returns a receipt, the result arrives later, and `taskId` continues the same root-copy session. The selected model applies to every turn in that session. A continuation must repeat the original model; start a new task to use another one. Because the parent model controls this value, use this tool only when it may choose among every model your AI Gateway credentials and policies allow.
+
+An authored tool at `agent/tools/agent.ts` replaces the framework behavior. Re-export the default definition above to restore direct root-copy delegation, export `agentWithModel` to expose model selection, export another tool such as `agentRouter()` to change the model-facing behavior, or disable the slot. `agentRouter()` runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task), which adds `eve__task_wait` and `eve__task_cancel`:
 
 ```ts title="agent/tools/agent.ts"
 import { disableTool } from "eve/tools";
@@ -356,7 +379,7 @@ export default askQuestion();
 
 ### `glob`
 
-`glob` finds sandbox files by glob pattern. Add it:
+`glob` finds sandbox files by glob pattern. It searches the workspace root unless the model passes a directory, which accepts the same paths as `read_file`. Add it:
 
 ```sh
 eve add tool/glob
@@ -382,7 +405,7 @@ Remove the file to remove the tool. `disableTool()` is unnecessary because `glob
 
 ### `grep`
 
-`grep` searches sandbox file contents with a regular expression. Add it:
+`grep` searches sandbox file contents with a regular expression. It searches the workspace root unless the model passes a directory or file, which accepts the same paths as `read_file`. Add it:
 
 ```sh
 eve add tool/grep