eve 0.26.1 → 0.27.0

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

@@ -19,7 +19,7 @@ React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overv
 ## Start a session
 
 ```bash
-curl -X POST http://127.0.0.1:3000/eve/v1/session \
+curl -X POST http://127.0.0.1:2000/eve/v1/session \
   -H 'content-type: application/json' \
   -d '{"message":"Summarize the latest forecast."}'
 ```
@@ -29,7 +29,7 @@ eve responds right away. The JSON body carries a `sessionId` and a `continuation
 ## Stream a session
 
 ```bash
-curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
+curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream
 ```
 
 The stream is newline-delimited JSON (NDJSON), one event per line:
@@ -78,7 +78,7 @@ A delegated subagent publishes progress on its own child-session stream. The par
 Once the session is waiting (you'll see `session.waiting`), POST your follow-up to the session endpoint with `event.data.continuationToken`:
 
 ```bash
-curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
   -H 'content-type: application/json' \
   -d '{"continuationToken":"<token>","message":"Now send the short version."}'
 ```
@@ -100,7 +100,7 @@ For deterministic ordering, send one follow-up at a time and wait for the next `
 POST to the session's cancel endpoint to stop the turn that is currently running. The body is optional; pass `turnId` (stamped on every turn-scoped stream event) to scope the cancel to the turn you observed:
 
 ```bash
-curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId>/cancel
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/cancel
 # {"ok":true,"sessionId":"<sessionId>","status":"accepted"}
 ```
 
@@ -113,13 +113,13 @@ Custom channel routes request the same cancellation without knowing the session
 The stream is durable. Every event is recorded before a step completes, so consumers can reconnect from their cursor when an HTTP connection ends. A nonnegative `startIndex` is an absolute event count: use it to pick up where you dropped off or pass `0` to rewind to the start.
 
 ```bash
-curl "http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream?startIndex=<count>"
+curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<count>"
 ```
 
 A negative `startIndex` reads relative to the stream's current tail. For example, `-1` reads the latest event, which is normally `session.waiting` for a resumable session:
 
 ```bash
-curl "http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream?startIndex=-1"
+curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=-1"
 ```
 
 This gives a consumer that only persisted `sessionId` a lightweight way to recover the current `continuationToken`. Because a tail-relative position does not resolve to an absolute consumed-event count, client tail reads do not automatically reconnect or advance the stored cursor.
@@ -135,7 +135,7 @@ Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basi
 `GET /eve/v1/info` returns a JSON inspection snapshot for the running agent: model, instructions, authored and framework tools, skills, channels, schedules, subagents, sandbox, connections, hooks, workflow, and workspace metadata. It uses the resolved `eveChannel()` route auth when `agent/channels/eve.ts` authors one; otherwise it falls back to the framework default of Vercel OIDC plus local development access.
 
 ```bash
-curl http://127.0.0.1:3000/eve/v1/info
+curl http://127.0.0.1:2000/eve/v1/info
 ```
 
 With the default auth chain (`[vercelOidc(), localDev()]`), a local Vercel OIDC bearer takes precedence and other local requests fall back to development access. A deployed Vercel target requires a valid OIDC bearer, with a same-project bypass for in-deployment callers. See [auth & route protection](../guides/auth-and-route-protection).

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/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/meta.json

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

package/docs/reference/cli.md

@@ -147,7 +147,7 @@ Pass a bare URL and the UI connects to that server instead of booting a local on
 | Flag                                | Type   | Default            | Description                                                                               |
 | ----------------------------------- | ------ | ------------------ | ----------------------------------------------------------------------------------------- |
 | `--host <host>`                     | string | all interfaces     | Host interface to bind                                                                    |
-| `--port <port>`                     | number | `$PORT`, then 3000 | Port to listen on                                                                         |
+| `--port <port>`                     | number | `$PORT`, then 2000 | Port to listen on                                                                         |
 | `-u, --url <url>`                   | string | none               | Connect to an existing server URL instead of starting one                                 |
 | `-H, --header <header>`             | string | none               | Request header for a URL target, in `Name: value` form; repeat for multiple headers       |
 | `--no-ui`                           | flag   | UI on              | Start the server without an interactive UI                                                |

package/docs/schedules.mdx

@@ -90,7 +90,7 @@ A handler-form session runs on the same durable runtime engine as any other sess
 The dev server mounts a one-shot dispatch route that fires a schedule by name, out of band, exactly once. Since `eve dev` never runs schedules on their cron cadence, this is how you trigger one without waiting for the next production tick.
 
 ```sh
-curl -X POST http://localhost:3000/eve/v1/dev/schedules/heartbeat
+curl -X POST http://localhost:2000/eve/v1/dev/schedules/heartbeat
 # -> { "scheduleId": "heartbeat", "sessionIds": ["..."] }
 ```
 

package/docs/skills.mdx

@@ -9,7 +9,7 @@ A skill is a model-loadable procedure that follows the `SKILL.md` convention. It
 
 eve scans the files under `agent/skills/` and exposes each one's description to the model alongside a framework-owned `load_skill` tool. When a request matches a skill's description (or you name the skill outright), the model calls `load_skill`, and eve appends that skill's markdown to the active turn's context.
 
-At runtime, skill package files are placed under `$HOME/.agents/skills/<skill>/`. If `$HOME` is unavailable in a sandbox, eve falls back to `/workspace/skills/<skill>/`. `load_skill` reads `SKILL.md` automatically; any sibling references inside that file, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
+Static skills do not require a sandbox: `load_skill` returns their instructions directly from the compiled agent. Dynamic skills and access to supporting package files require a sandbox. Builds may also prewarm sandbox templates that contain static package files. Supporting files are available under `$HOME/.agents/skills/<skill>/`, with `/workspace/skills/<skill>/` as the fallback when `$HOME` is unavailable. Sibling references inside `SKILL.md`, such as `references/checklist.md`, are relative to the directory containing that specific `SKILL.md`.
 
 The description is a routing hint, not a label. Write it as the task that should trigger activation:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [
@@ -289,9 +289,9 @@
     "@ai-sdk/otel": "^1.0.26",
     "@ai-sdk/provider": "^4.0.3",
     "@ai-sdk/provider-utils": "^5.0.9",
-    "@chat-adapter/slack": "4.31.0",
-    "@chat-adapter/state-memory": "4.31.0",
-    "@chat-adapter/twilio": "4.31.0",
+    "@chat-adapter/slack": "4.34.0",
+    "@chat-adapter/state-memory": "4.34.0",
+    "@chat-adapter/twilio": "4.34.0",
     "@clack/core": "1.3.1",
     "@nuxt/kit": "^4.0.0",
     "@standard-schema/spec": "1.1.0",
@@ -312,7 +312,7 @@
     "@workflow/world-vercel": "5.0.0-beta.31",
     "ai": "^7.0.26",
     "autoevals": "0.0.132",
-    "chat": "4.31.0",
+    "chat": "4.34.0",
     "chokidar": "5.0.0",
     "commander": "14.0.3",
     "emulate": "0.6.0",

package/dist/src/execution/sandbox/bindings/vercel-user-agent.d.ts

@@ -1,6 +0,0 @@
-export declare function eveSandboxUserAgentToken(): string;
-/**
- * Wraps a `fetch` implementation so every request's `user-agent` ends with the
- * {@link eveSandboxUserAgentToken} (e.g.: eve/0.18.1).
- */
-export declare function withEveSandboxUserAgent(inner?: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/src/execution/sandbox/bindings/vercel-user-agent.js

@@ -1 +0,0 @@
-import{resolveInstalledPackageInfo}from"#internal/application/package.js";function eveSandboxUserAgentToken(){let{name:t,version:n}=resolveInstalledPackageInfo();return`${t}/${n}`}function withEveSandboxUserAgent(e=globalThis.fetch){let t=eveSandboxUserAgentToken();return(n,r)=>{let i=new Headers(r?.headers??(typeof n==`object`&&n&&`headers`in n?n.headers:void 0)),a=i.get(`user-agent`);return i.set(`user-agent`,a?`${a} ${t}`:t),e(n,{...r,headers:i})}}export{eveSandboxUserAgentToken,withEveSandboxUserAgent};

package/dist/src/execution/workflow-skill-root.d.ts

@@ -1,6 +0,0 @@
-import type { ContextContainer } from "#context/container.js";
-import type { RuntimeTurnAgent } from "#runtime/agent/bootstrap.js";
-export declare function resolveSessionSkillRoot(input: {
-    readonly ctx: ContextContainer;
-    readonly turnAgent: RuntimeTurnAgent;
-}): Promise<string | undefined>;

package/dist/src/execution/workflow-skill-root.js

@@ -1 +0,0 @@
-import{SandboxKey}from"#context/keys.js";import{resolveSandboxSkillRoot}from"#shared/skill-paths.js";async function resolveSessionSkillRoot(e){if((e.turnAgent.availableSkills?.length??0)===0)return;let t=e.ctx.get(SandboxKey);if(t===void 0)return;let n=await t.get();if(n!==null)return await resolveSandboxSkillRoot({sandbox:n})}export{resolveSessionSkillRoot};

package/dist/src/public/nuxt/vercel-json.d.ts

@@ -1,17 +0,0 @@
-export interface EnsureVercelJsonResult {
-    readonly servicePrefix: string;
-}
-/**
- * Ensure `vercel.json` declares the Nuxt web service and the eve agent
- * service so a Vercel deployment ships both from one project.
- *
- * Existing services are preserved untouched; an already-configured eve
- * service's `routePrefix` wins over {@link input.servicePrefix}. The file is
- * only rewritten when the resulting config differs from what is on disk.
- */
-export declare function ensureEveVercelJson(input: {
-    readonly appRoot: string;
-    readonly eveBuildCommand: string;
-    readonly nuxtRoot: string;
-    readonly servicePrefix: string;
-}): Promise<EnsureVercelJsonResult>;

package/dist/src/public/nuxt/vercel-json.js

@@ -1 +0,0 @@
-import{join,relative}from"node:path";import{readFile,writeFile}from"node:fs/promises";const VERCEL_JSON_FILE_NAME=`vercel.json`;function isRecord(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function resolveRelativeEntrypoint(e,n){let r=relative(e,n);return r.length===0?`.`:r.replaceAll(`\\`,`/`)}function normalizeVercelJsonConfig(e){if(!isRecord(e))throw Error(`${VERCEL_JSON_FILE_NAME} must contain a JSON object.`);let t=e.experimentalServices;if(t!==void 0&&!isRecord(t))throw Error(`${VERCEL_JSON_FILE_NAME} experimentalServices must be a JSON object.`);return e}async function readVercelJsonConfig(e){try{return normalizeVercelJsonConfig(JSON.parse(await readFile(e,`utf8`)))}catch(e){if(e instanceof Error&&`code`in e&&e.code===`ENOENT`)return{};throw e}}function findServiceByFramework(e,t){return Object.values(e).find(e=>e.framework===t)}async function ensureEveVercelJson(t){let n=join(t.nuxtRoot,VERCEL_JSON_FILE_NAME),i=await readVercelJsonConfig(n),a=resolveRelativeEntrypoint(t.nuxtRoot,t.appRoot),o=i.experimentalServices??{},s=findServiceByFramework(o,`eve`),c=findServiceByFramework(o,`nuxtjs`),l=s?.routePrefix??t.servicePrefix,u={...o};c===void 0&&(u.web={entrypoint:`.`,framework:`nuxtjs`,routePrefix:`/`}),s===void 0&&(u.eve={buildCommand:t.eveBuildCommand,entrypoint:a,framework:`eve`,routePrefix:l});let d={...i,$schema:i.$schema??`https://openapi.vercel.sh/vercel.json`,experimentalServices:u};return JSON.stringify(i)!==JSON.stringify(d)&&await writeFile(n,`${JSON.stringify(d,null,2)}\n`),{servicePrefix:l}}export{ensureEveVercelJson};