eve 0.26.2 → 0.27.1

package/docs/channels/slack.mdx

@@ -36,7 +36,11 @@ export default slackChannel({
 });
 ```
 
-`connectSlackCredentials` returns `{ botToken, webhookVerifier }`, keeping token rotation, multi-workspace tenancy, and request verification inside Connect rather than your code. Deploy once the trigger destination and channel file are ready:
+`connectSlackCredentials` returns `{ botToken, webhookVerifier }`, keeping token rotation, multi-workspace tenancy, and request verification inside Connect rather than your code.
+
+### Deploy
+
+Deploy once the trigger destination and channel file are ready:
 
 ```bash
 VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1 vercel deploy --prod
@@ -44,17 +48,79 @@ VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1 vercel deploy --prod
 
 `VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1` lets the Vercel CLI recognize eve as a framework during the build. eve's own setup commands set the same flag.
 
-## How the channel handles messages
+## How the channel handles inbound events
+
+### Message hooks
+
+Message hooks return `{ auth }` to dispatch, `null` to drop, or `{ auth, context }` to inject background into history.
+
+- `onMessage(ctx, message)` handles Slack `message` events. `ctx.isBotMentioned()` and `ctx.isSubscribed()` support mention and active-thread policies; check `message.author?.isBot` when bot messages should be ignored.
+- `onAppMention(ctx, message)` handles only `app_mention` and takes precedence over `onMessage`. Its default derives workspace-scoped auth and posts `Thinking…`.
+- `onDirectMessage(ctx, message)` handles only DMs and takes precedence over `onMessage`. Bot-authored messages and edits are filtered first; Slack requires `message.im` and `im:history`.
+
+| Incoming event         | Handler order                                                       |
+| ---------------------- | ------------------------------------------------------------------- |
+| App mention            | `onAppMention` → `onMessage` → `onEvent` → built-in mention default |
+| Direct message         | `onDirectMessage` → `onMessage` → `onEvent` → built-in DM default   |
+| Other Slack message    | `onMessage` → `onEvent` → ignore                                    |
+| Other Events API event | `onEvent` → ignore                                                  |
+
+Only the first available handler runs. A message hook returning `null` drops the message; it does not continue down the table.
+
+`onInteraction(action, ctx)` separately handles `block_actions` callbacks not consumed by HITL. eve attaches the triggering Slack user id to the same model message as its text, preserving speaker attribution without profile lookups.
+
+#### Continue conversations without repeated mentions
+
+Use `onMessage` to handle explicit mentions and continue replies in threads with an active eve session:
+
+```ts title="agent/channels/slack.ts"
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
+  async onMessage(ctx, message) {
+    if (message.author?.isBot) return null;
+    const isDirectMessage = message.raw.channel_type === "im";
+    return isDirectMessage || ctx.isBotMentioned() || (await ctx.isSubscribed())
+      ? { auth: null }
+      : null;
+  },
+});
+```
+
+`isBotMentioned()` identifies an explicit mention. `isSubscribed()` checks whether the message belongs to a thread with an active eve session. For Vercel Connect, open **Advanced** when creating the connector and add `message.channels` under **Trigger Event Types** and `channels:history` under **Bot Scopes**. Private channels additionally need `message.groups` and `groups:history`.
+
+### Other Events API callbacks
 
-### Dispatch
+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. `ctx.receive(options)` is the current Slack channel's pre-bound form of the schedule API's `receive(slack, options)`: call it zero, one, or many times to start turns. Each call accepts `message`, `target`, and `auth`, and returns the resulting session.
+
+```ts title="agent/channels/slack.ts"
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { slackChannel } from "eve/channels/slack";
+
+const onboardingChannels = ["C0123ABC", "C0456DEF"];
+
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
+  async onEvent({ receive }, event) {
+    if (event.type !== "team_join") return;
+
+    await Promise.all(
+      onboardingChannels.map((channelId) =>
+        receive({
+          message: `A user joined the Slack workspace. Onboard them from this event:\n${JSON.stringify(event)}`,
+          target: { channelId },
+          auth: null,
+        }),
+      ),
+    );
+  },
+});
+```
 
-Inbound hooks decide whether to dispatch a turn and with what `auth`. Return `{ auth }` to dispatch, `null` to drop, or `{ auth, context }` to inject background into history.
+The webhook invocation already keeps an awaited `onEvent` handler alive. Use `ctx.waitUntil(promise)` for deliberately detached work, matching a handler-form schedule. `ctx.slack.request(operation, body)` provides workspace-scoped Slack Web API access, while `ctx.envelope` carries delivery metadata such as `team_id`, `event_id`, and `event_time`. Calls to `ctx.receive` automatically seed the callback's team id into Slack session state.
 
-- `onAppMention(ctx, message)` handles `app_mention` events. The default derives workspace-scoped auth and posts a `Thinking…` indicator.
-- `onDirectMessage(ctx, message)` handles `message.im` events (needs `im:history` scope). Bot-authored messages and edits are filtered out first.
-- `onInteraction(action, ctx)` handles `block_actions` callbacks not consumed by HITL.
+`onEvent` is the raw fallback after the message hooks. If an event is not claimed by `onAppMention`, `onDirectMessage`, or `onMessage`, an authored `onEvent` receives it; otherwise eve applies the built-in mention/DM default or ignores it.
 
-eve attaches the triggering Slack user id to the same model message as the message text. This keeps speaker attribution intact when several people use one thread without making profile lookup requests.
+`onEvent` covers JSON `event_callback` deliveries only. URL verification, slash commands, and interactive payloads do not reach it. Add every desired event and required OAuth scope to the Slack app's Event Subscriptions configuration; eve can only handle events Slack sends.
 
 You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
 
@@ -78,7 +144,7 @@ export default slackChannel({
 
 ### Slack API calls outside a handler
 
-Inside webhook-side handlers (`onAppMention`, `onInteraction`, `events`),
+Inside webhook-side handlers (`onAppMention`, `onEvent`, `onInteraction`, `events`),
 `ctx.slack.request(operation, body)` is the raw-API escape hatch. Outside
 those contexts there is no handle — a schedule resolving reactions on old
 messages, for example, has no inbound Slack request. For that, call the
@@ -105,7 +171,7 @@ when you need the bearer token itself.
 
 ### Delivery
 
-The default handlers reply in-thread and show progress. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and an action label on `actions.requested` — the tool name plus its most telling argument (`grep useEveAgent`, `read_file agent/agent.ts`), the subagent or remote-agent name for dispatched calls, and `+N more` when the model requests several actions at once. The model's own pre-tool narration, when present, takes precedence over the derived label. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use the five-second refresh interval to avoid one Slack request per token. Override `events["reasoning.appended"]` if you prefer generic wording. Override `onAppMention` or the `events` handlers to customize.
+The default handlers reply in-thread and show progress. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and an action label on `actions.requested` — the tool name plus its most telling argument (`grep useEveAgent`, `read_file agent/agent.ts`), the subagent or remote-agent name for dispatched calls, and `+N more` when the model requests several actions at once. The model's own pre-tool narration, when present, takes precedence over the derived label. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use the five-second refresh interval to avoid one Slack request per token. Override `events["reasoning.appended"]` if you prefer generic wording. Override an inbound handler or the `events` handlers to customize.
 
 Outbound text preserves bare `@` tokens as literal text. To mention a user, embed Slack's `<@USER_ID>` syntax directly or use `channel.thread.mentionUser(userId)`.
 

package/docs/channels/teams.mdx

@@ -28,17 +28,24 @@ By default the channel mounts at `POST /eve/v1/teams`. Point your Azure Bot or T
 
 The default `onMessage` handles two cases: personal-chat messages, and channel or group-chat messages that mention the bot directly. Ambient resource-specific-consent messages are dropped unless you override it. Before dispatch, eve strips the mention, adds a `<teams_context>` block, and scopes channel and group threads by root activity id (`replyToId ?? id`).
 
+For example, use the contextual `isSubscribed()` helper to continue active threads without requiring another mention:
+
 ```ts
 import { defaultTeamsAuth, teamsChannel } from "eve/channels/teams";
 
 export default teamsChannel({
-  onMessage(ctx, message) {
-    if (message.scope !== "personal" && !message.isBotMentioned) return null;
-    return { auth: defaultTeamsAuth(message) };
+  async onMessage(ctx, message) {
+    if (message.from.role === "bot" || message.from.id === message.recipient.id) return null;
+    const isDirectMessage = message.scope === "personal";
+    return isDirectMessage || message.isBotMentioned || (await ctx.isSubscribed())
+      ? { auth: defaultTeamsAuth(message) }
+      : null;
   },
 });
 ```
 
+`isSubscribed()` checks whether the conversation has previously involved the agent.
+
 ### Delivery
 
 Replies post as Markdown (`textFormat: "markdown"`), with oversized text split across messages and a typing indicator sent on turn start and action requests.

package/docs/extensions.md

@@ -1,39 +1,48 @@
 ---
 title: "Extensions"
-description: "Package tools, connections, skills, and hooks as a reusable package and mount it into an agent."
+description: "Publish reusable eve capabilities as an npm package, then install and mount them in an agent."
 ---
 
-An extension packages eve capabilities — tools, connections, skills, instructions, hooks — as a reusable npm or local package. You author it as an agent-shaped directory; a consuming agent mounts it under `agent/extensions/`, and its contributions compose into the agent under a namespace. Nothing is copied — upgrades come through the package manager.
+Extensions package eve tools, connections, skills, instruction fragments, and hooks. A publisher builds and distributes a package; a consumer installs it and mounts it in an agent.
 
-## Authoring
+This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
 
-Start from a scaffold:
+## Publisher: create and publish an extension
+
+### Create the package
+
+Start with the extension scaffold:
 
 ```bash
 npx eve@latest extension init my-crm
 ```
 
-This creates the package, installs dependencies, and initializes Git. You get `extension/extension.ts`, TypeScript config, and a `package.json` ready to publish or mount. Add tools, skills, hooks, and connections under `extension/` yourself.
+The command creates the package, installs dependencies, and initializes Git. It includes `extension/extension.ts`, TypeScript configuration, and the package metadata required to build and publish.
 
-An extension is an agent-shaped directory without `agent.ts` or `sandbox` (those belong to the consuming agent). Every slot works as it does in an agent, with names derived from paths.
+An extension uses the same file conventions as an agent for its contributions:
 
 ```
 @acme/crm/
   package.json
   extension/
-    extension.ts        # the extension declaration — see Configuration
+    extension.ts
     tools/search.ts
     connections/api.ts
     skills/triage/SKILL.md
+    instructions.md
     hooks/audit.ts
-    lib/http.ts         # shared helpers, imported as ../lib/http
+    lib/http.ts
 ```
 
-Name tools and connections for what they do (`search`, not `crm_search`) — the mount supplies the namespace. Shared code goes in `extension/lib/`, imported by relative path — eve compiles the source, so relative imports need no `.js` extension.
+Each listed slot accepts the same authored forms as its agent counterpart. Static and dynamic tools, skills, and instructions all work in an extension: `extension/instructions.ts` is as valid as `extension/instructions.md`, and `extension/tools/` can contain `defineDynamic(...)`.
+
+Names come from paths, so call the tool `search`, not `crm_search`; the consumer's mount adds the `crm__` prefix. Keep shared code in `extension/lib/`.
 
-### Configuration
+Keep agent configuration, sandboxes, schedules, and nested extensions in the consumer's agent.
 
-Declare the extension in `extension/extension.ts` with `defineExtension`; its default export is the mount factory a consumer calls. Pass `config` — any [Standard Schema](https://standardschema.dev) (a Zod object here), like a tool's `inputSchema` — to accept consumer settings:
+### Add configuration and contributions
+
+The publisher's `extension/extension.ts` default-exports a `defineExtension` handle. Give it a [Standard Schema](https://standardschema.dev) when consumers need to provide settings:
 
 ```ts title="extension/extension.ts"
 import { defineExtension } from "eve/extension";
@@ -42,40 +51,41 @@ import { z } from "zod";
 export default defineExtension({
   config: z.object({
     apiKey: z.string(),
-    baseUrl: z.string().default("https://api.acme.example"),
+    baseUrl: z.string().url().default("https://api.acme.example"),
   }),
 });
 ```
 
-Config is optional — `defineExtension()` with no schema. Read it off the handle, imported from the declaration; it's typed from the schema:
+Contributions import that handle to read the validated configuration. Defaults have already been applied:
 
 ```ts title="extension/tools/search.ts"
 import { defineTool } from "eve/tools";
+import { z } from "zod";
 
 import extension from "../extension";
 
 export default defineTool({
   description: "Search the CRM.",
-  inputSchema: {/* ... */},
+  inputSchema: z.object({ query: z.string() }),
   async execute({ query }) {
-    const { apiKey, baseUrl } = extension.config; // validated, defaults applied
+    const { apiKey, baseUrl } = extension.config;
+    return { query, baseUrl, authenticated: apiKey.length > 0 };
   },
 });
 ```
 
-Config is bound once when the consumer mounts the extension and stays constant for the session; per-request values belong in connection auth instead.
+If no configuration is needed, export `defineExtension()` and let consumers re-export it directly. Config schemas must validate synchronously.
 
-### State
+`defineState` is automatically scoped to the publisher's package, so the same state name does not collide with the consumer or another extension.
 
-`defineState` is scoped to the extension's package automatically, so identically-named state never collides with the consuming agent or another extension. Author it exactly as in an agent — `defineState("budget", …)`.
+### Build and publish
 
-## Publishing
-
-Declare separate authoring and distribution roots and run `eve extension build` (wired to `build`/`prepare`):
+The scaffold's `package.json` declares separate source and distribution roots:
 
 ```jsonc title="package.json"
 {
-  "name": "@acme/crm",
+  "name": "my-crm",
+  "version": "0.0.0",
   "type": "module",
   "eve": {
     "extension": {
@@ -84,86 +94,105 @@ Declare separate authoring and distribution roots and run `eve extension build`
     },
   },
   "files": ["dist"],
-  "peerDependencies": { "eve": "*" },
-  "devDependencies": { "eve": "x.y.z", "typescript": "^x" },
-  "dependencies": { "zod": "^3" },
-  "scripts": { "build": "eve extension build", "prepare": "eve extension build" },
-}
-```
-
-Author the source with `moduleResolution: "bundler"` — eve compiles it, so relative imports need no `.js` extension:
-
-```jsonc title="tsconfig.json"
-{
-  "compilerOptions": {
-    "module": "esnext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "types": ["node"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs",
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.mjs",
+    },
+  },
+  "scripts": {
+    "build": "eve extension build",
+    "prepare": "eve extension build",
+    "typecheck": "tsc",
+  },
+  "dependencies": {
+    "zod": "^x",
+  },
+  "devDependencies": {
+    "@types/node": "^x",
+    "eve": "x.y.z",
+    "typescript": "^x",
+  },
+  "peerDependencies": {
+    "eve": "*",
+  },
+  "engines": {
+    "node": ">=24",
   },
-  "include": ["extension/**/*.ts"],
 }
 ```
 
-`eve extension build` transforms every JavaScript or TypeScript module into an agent-shaped `dist/extension` tree, copies skill packages and their assets, emits type declarations, and writes `dist/extension/_manifest.json`. The generated package entrypoints (`dist/index.mjs` and `dist/tools/index.mjs`) re-export those same dist modules, and the build fills the `exports` map so you never hand-list it. The published package therefore needs `dist/`, not the author's original TypeScript. Consumers read only `eve.extension.dist`, so a published package may omit `eve.extension.source`; keep `source` declared wherever `eve extension build` runs.
+The scaffold omits `engines` when it creates a workspace package.
 
-The build uses the package `tsconfig.json` when it emits declarations. Its `include` must cover every JavaScript or TypeScript module in the extension source (and JavaScript modules require `allowJs`); the build fails before publishing if any distributed module would be missing its declaration.
+Build the package with `eve extension build`:
 
-The manifest contains only its format, the diagnostic eve build version, and the versions of extension capabilities this package actually uses. It does not contain compiled tools, schemas, names, or executable definitions; the consuming eve still discovers and normalizes the agent-shaped dist tree.
+```bash
+eve extension build
+```
 
-### Workspace development
+`eve extension build` writes an agent-shaped `dist/extension` tree, copies skill assets, emits declarations, and records compatibility metadata. It also manages the package exports for the mount factory (`@acme/crm`) and tool definitions (`@acme/crm/tools`). Publish `dist/`; consumers do not need the publisher's TypeScript source.
 
-During local development, `eve dev` automatically rebuilds mounted workspace extensions when their source changes.
+The exact `eve` development pin controls the publisher's authoring API and build tooling. The wildcard peer lets the consumer provide the runtime copy of eve. At consumption time, eve checks generated metadata, not the npm peer range. Do not add eve to regular `dependencies`.
 
-### Dependencies
+Put runtime packages such as `zod` or an SDK in `dependencies`. If a dependency cannot be bundled, such as a native addon, tell consumers to add it to `build.externalDependencies` in `agent.ts`.
 
-`eve` is a required wildcard **peer** dependency: one eve lives in the consuming app and the extension's `eve/*` imports resolve to it. The extension's concrete eve version belongs in `devDependencies` for authoring types and build tooling. npm peer semver does not decide extension compatibility; eve validates the generated per-capability requirements. Do not mark the eve peer optional and do not add eve to regular `dependencies`.
+Consumers can now add the built package to an agent.
 
-`eve extension init` pins `devDependencies.eve` to the exact eve release that created the scaffold:
+## Consumer: install and mount an extension
 
-```jsonc title="package.json"
-{
-  "peerDependencies": { "eve": "*" },
-  "devDependencies": { "eve": "0.25.0" },
-}
-```
-
-The exact pin makes builds reproducible. Keep it until the extension intentionally upgrades its eve authoring API. `eve extension build` records the capability contracts required by the build, and each consuming eve validates those requirements before it runs the extension.
+A mount gives the publisher's contributions a namespace. Updating the package updates the mounted extension; nothing is copied into the consumer's agent.
 
-If the extension must support an older eve release, replace the development pin with that exact version, then typecheck and build with it. Test the same dist against both the oldest and latest supported consumers; rebuilding with each consumer would produce and test different artifacts.
+### Install the package
 
-Everything else the extension imports at execution time (SDKs, `zod`, …) goes in `dependencies`; each extension resolves its own versions. Build-only and test-only packages go in `devDependencies`.
+Install the extension in the consumer's agent project:
 
-Those deps resolve from `node_modules` under `eve dev`/`eve eval` and are bundled into the deployable by the consuming agent's `eve build`. A dependency that can't be bundled (a native addon) must be listed in the **consuming agent's** `build.externalDependencies` — an extension can't declare build config, so note it in your README.
+```bash
+npm install @acme/crm
+```
 
-## Mounting
+### Mount it
 
-A consuming agent mounts an extension under `agent/extensions/` — a single file, or a directory when it needs [overrides](#overrides). The namespace is the file basename or directory name; contributions compose as `<namespace>__<name>` (`crm__search`, `crm__api`).
+Create a file under `agent/extensions/`. Its filename becomes the mount namespace. Call the publisher's default export when the extension needs configuration:
 
 ```ts title="agent/extensions/crm.ts"
 import crm from "@acme/crm";
 
-export default crm({ apiKey: process.env.CRM_API_KEY });
+export default crm({ apiKey: process.env.CRM_API_KEY! });
 ```
 
-A no-config extension takes no factory call — mount it with a bare re-export:
+Set `CRM_API_KEY` in the consumer's environment, such as `.env.local` for local development.
+
+The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, and `connections/api.ts` becomes `crm__api`.
+
+For a publisher with no configuration, mount its default export directly:
 
 ```ts title="agent/extensions/gizmo.ts"
 export { default } from "@acme/gizmo";
 ```
 
-### Overrides
+The same mount shape works with an npm package, a workspace dependency, or a linked local package.
+
+### Override a contribution
 
-To override a mounted extension's contributions, author the mount as a directory: the declaration in `extension.ts`, override slots alongside it.
+Use a directory mount to replace or remove a publisher contribution. Put the mount declaration in `extension.ts` and add overrides beside it:
 
 ```
 agent/extensions/crm/
-  extension.ts         # export default crm({ apiKey: process.env.CRM_API_KEY })
-  tools/search.ts      # composes as crm__search, shadowing the extension's own
+  extension.ts
+  tools/search.ts
 ```
 
-A file in an override slot composes under the mount namespace and wins on a name collision. Name it for the bare contribution name (`search`, not `crm__search`) — the directory supplies the prefix. To tweak the extension's own definition, import and re-define it:
+```ts title="agent/extensions/crm/extension.ts"
+import crm from "@acme/crm";
+
+export default crm({ apiKey: process.env.CRM_API_KEY! });
+```
+
+A same-named consumer tool, connection, or skill wins. To adjust a publisher tool, import it from the package's `./tools` export and define it again:
 
 ```ts title="agent/extensions/crm/tools/search.ts"
 import { search } from "@acme/crm/tools";
@@ -173,7 +202,7 @@ import { always } from "eve/tools/approval";
 export default defineTool({ ...search, approval: always() });
 ```
 
-Or drop it entirely by opting out of the slot with `disableTool()`:
+To remove a publisher tool, use `disableTool()` in its matching slot:
 
 ```ts title="agent/extensions/crm/tools/search.ts"
 import { disableTool } from "eve/tools";
@@ -181,13 +210,13 @@ import { disableTool } from "eve/tools";
 export default disableTool();
 ```
 
-An override targets one slot, matched by name and kind: a static file replaces the extension's static tool, a dynamic file replaces its dynamic resolver, and `disableTool()` removes whichever the extension put there. Because a dynamic tool wins over a same-named static one at runtime, replace or disable a dynamic tool through its own slot — a static file of the same name won't shadow it.
+Hooks and instruction fragments are additive, so they cannot be replaced. To replace a dynamic tool, use a dynamic definition in the same slot; dynamic tools win over same-named static tools at runtime. `disableTool()` removes either kind.
 
-Overrides only work here — the `<namespace>__` prefix is reserved, so an agent-root contribution named `crm__…` is a build error and an extension can't be shadowed from outside its mount.
+The `crm__` prefix is reserved for this directory mount. A consumer cannot override the extension from `agent/tools/`, `agent/connections/`, or another agent-root slot.
 
-### Typed tool results
+### Use a publisher tool result in a hook
 
-A consuming agent can narrow a mounted extension's tool result in a hook: import the tool from the extension's `./tools` export and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results). It matches the namespaced result (`crm__search`) because identity keys off the tool definition, not its name.
+To retain a publisher tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/guides/hooks#narrowing-tool-results):
 
 ```ts title="agent/hooks/narrow-crm.ts"
 import { defineHook } from "eve/hooks";
@@ -198,14 +227,23 @@ export default defineHook({
   events: {
     "action.result"(event) {
       const match = toolResultFrom(event.data.result, search);
-      if (match) console.log(match.output); // typed as search's output
+      if (match) console.log(match.output);
     },
   },
 });
 ```
 
-Matching keys off the tool's description, so keep extension tool descriptions distinct — one shared with another tool makes the identity ambiguous and `toolResultFrom` stops matching.
+`toolResultFrom` recognizes the mounted `crm__search` result from the original definition, not the namespaced string. Publishers should keep tool descriptions distinct so eve can assign each definition an unambiguous identity.
+
+### Compatibility
+
+At build time, eve checks the publisher's generated capability metadata. If the extension needs an unsupported capability contract, upgrade eve or install a compatible extension release.
 
-## Limits
+## What to read next
 
-An extension cannot declare a `sandbox`, agent config, schedules, or limits, and cannot mount other extensions — those are the consuming agent's to own (background scheduling, for instance, runs on the agent's deployment under its limits). An extension's tools run within the consuming agent's per-session limits.
+- [Tools](/docs/tools): static tools, approval, and tool output
+- [Dynamic capabilities](/docs/guides/dynamic-capabilities): dynamic tools, skills, and instructions
+- [Instructions](/docs/instructions): static and TypeScript instructions
+- [Skills](/docs/skills): package procedures and supporting files
+- [Connections](/docs/connections): integrate external services
+- [Hooks](/docs/guides/hooks): observe agent events

package/docs/guides/auth-and-route-protection.md

@@ -41,7 +41,7 @@ export default eveChannel({
 - returns `null` / `undefined`: skip to the next entry
 - **throws**: reject with a specific status
 
-If every entry skips, the request gets a `401`. An empty array `auth: []` rejects everything.
+If every entry skips, the request gets a `401` whose `WWW-Authenticate` header advertises the challenge scheme(s) the configured entries declare — `Basic` for `httpBasic()`, `Bearer` for the token-based helpers (`jwtHmac`, `jwtEcdsa`, `oidc`, `vercelOidc`), both when you mix them, and `Bearer` as a fallback for entries that don't declare a scheme (custom `AuthFn`s, or an empty array). See [`withAuthChallenges`](#custom-verifiers) to declare a scheme on a custom `AuthFn`.
 
 ```ts
 import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
@@ -96,6 +96,8 @@ Any other thrown error follows the normal channel failure path. When building a
 | `jwtEcdsa(...)`  | You verify asymmetric JWTs minted by another system.                      |
 | `oidc(...)`      | You want eve to verify OIDC-issued tokens from an arbitrary issuer.       |
 
+`httpBasic(credentials, { realm })` accepts an optional `realm`, rendered on the `WWW-Authenticate: Basic` challenge (e.g. `Basic realm="agent", charset="UTF-8"`) so browsers label their native login prompt. It defaults to `"eve"`, ensuring every Basic challenge includes the required realm. Usernames and passwords are normalized to Unicode NFC before comparison, matching the advertised UTF-8 credential encoding.
+
 Exercise caution for agents that process non-public, sensitive, regulated, or production data unless you have implemented other access controls.
 
 ### `localDev()`
@@ -131,6 +133,17 @@ vercelOidc({
 
 When none of the shipped helpers fit, write your own `AuthFn` (the array example above) or call the low-level verifiers directly. Each verifier is the pure function sitting behind the matching strategy helper, and returns `{ ok: true, sessionAuth }` or `{ ok: false }`:
 
+A custom `AuthFn` doesn't declare a `WWW-Authenticate` scheme by default, so `routeAuth` falls back to `Bearer` for it. Wrap it with `withAuthChallenges(fn, challenges)` to declare the scheme(s) it actually satisfies, so a mixed `auth` array produces an accurate 401:
+
+```ts
+import { withAuthChallenges, type AuthFn } from "eve/channels/auth";
+
+const apiKeyAuth: AuthFn<Request> = withAuthChallenges(
+  (request) => (isValidApiKey(request) ? apiKeySessionAuth : null),
+  [{ scheme: "Bearer" }],
+);
+```
+
 | Verifier                               | Behind         | Input                            |
 | -------------------------------------- | -------------- | -------------------------------- |
 | `verifyHttpBasic(header, credentials)` | `httpBasic()`  | raw `Authorization` header value |

package/docs/guides/deployment/vercel.mdx

@@ -60,7 +60,7 @@ eve deploy
 Vercel uses the generated output to configure these services:
 
 - **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
-- **Vercel Workflow**: persists and resumes durable runs
+- **Vercel Workflow**: persists and resumes durable runs, with optimistic replay preconditions enabled so stale event-log snapshots reload before they can commit
 - **Vercel Cron**: invokes authored schedules
 - **Vercel Sandbox**: runs sandbox sessions selected by `defaultBackend()`
 

package/docs/guides/frontend/nuxt.mdx

@@ -74,7 +74,7 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
 ## Dev vs deploy topology
 
 - **Local dev.** `npm run dev` starts the eve dev server next to `nuxt dev` and proxies the eve routes through it. As far as the browser knows, everything is the Nuxt origin.
-- **Vercel.** A single Vercel project carries both the Nuxt app and the eve runtime. The web app stays public; the runtime sits behind it on the same origin. Set `eveBuildCommand` when the agent needs its own build step:
+- **Vercel.** The web app and the eve runtime deploy as a single project. On Vercel builds the module adds Build Output [`services`](https://vercel.com/docs/services) for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Nuxt app itself remains the default app. No `vercel.json` is required. By default the generated service runs the installed eve binary from the agent root, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:
 
   ```ts
   export default defineNuxtConfig({
@@ -92,6 +92,27 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
   EVE_NUXT_PRODUCTION_PORT=5000 npm run build && npm run preview
   ```
 
+## Managing vercel.json yourself
+
+When `vercel.json` declares [`services`](https://vercel.com/docs/services), the module generates nothing and your configuration owns routing. It must include the eve service (`framework: "eve"`) and a rewrite that exposes the eve transport, or the module fails the build:
+
+```json title="vercel.json"
+{
+  "services": {
+    "web": { "root": ".", "framework": "nuxtjs" },
+    "eve": { "root": "agent", "framework": "eve", "buildCommand": "eve build" }
+  },
+  "rewrites": [{ "source": "/eve/v1/(.*)", "destination": { "service": "eve" } }]
+}
+```
+
+### Migrating from experimentalServices
+
+Earlier versions of the module wrote the legacy `experimentalServices` field into `vercel.json`. Vercel no longer routes that model — deployments build both services but every `/eve/v1/*` request returns a platform NOT_FOUND — so the module now ignores the field and warns when it sees one. Migrate either way:
+
+- **Generated (default).** Delete `vercel.json` (or just its `experimentalServices` block) and set the project's Framework Preset back to Nuxt.js. The module generates the eve service and its routing on every Vercel build.
+- **Hand-maintained.** Replace `experimentalServices` with the stable `services` and `rewrites` shown above, and keep the "Services" Framework Preset.
+
 ## What to read next
 
 - [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API

package/docs/guides/frontend/overview.mdx

@@ -100,6 +100,8 @@ Assistant text, reasoning, tool calls, and tool results stream into `data` as th
 
 `stop()` is local: turns are resumable across disconnects, so detaching the stream never cancels the work — the turn keeps running and billing on the server. To stop the turn itself, POST the session's [cancel route](../../channels/eve#routes); the turn then settles on the stream as `turn.cancelled` followed by `session.waiting`.
 
+A chat UI with a Stop button should own the `ClientSession` passed to `useEveAgent`, create it with `preserveCompletedSessions: true`, and call `session.cancel({ turnId })` after observing that turn's `turn.started` event. The `turnId` guard makes a late click a harmless no-op instead of cancelling a newer turn. Keep the stream open until the cancellation boundary arrives; do not use `stop()` for this interaction.
+
 After eve confirms an attachment turn with `message.received`, the default reducer projects each
 received attachment as a `file` part on the user message. The part includes `mediaType`, optional
 `filename` and `size`, and a `url` only when the original attachment was browser-resolvable.

package/docs/meta.json

@@ -9,6 +9,7 @@
     "skills",
     "channels",
     "connections",
+    "extensions",
     "sandbox",
     "subagents",
     "schedules",