eve 0.54.5 → 0.56.0

package/docs/channels/eve.mdx

@@ -157,6 +157,45 @@ Neither admits browser users or external clients in production. For a public app
 
 For the full auth model and helper list, see [Auth & route protection](../guides/auth-and-route-protection).
 
+## Audience
+
+The eve channel assigns an observability audience when it creates a session. The
+audience controls whether instrumentation may capture session content:
+
+| Session creator                           | Default audience |
+| ----------------------------------------- | ---------------- |
+| Anonymous caller                          | `unknown`        |
+| `user`, `service`, or `runtime` principal | `private`        |
+| Any other principal type                  | `unknown`        |
+
+Anonymous HTTP surfaces are `unknown` by default because reachability does not establish that their content is safe to record. Authenticated `user`, `service`, and `runtime` sessions are private because they belong to one identified party. Other authenticated principal types also remain `unknown`: trace consumers record metadata but omit content by default in preview and production. Set an explicit `audience: "public"` only for intentionally public traffic.
+
+For a production endpoint whose conversations are all intentionally public,
+set a constant audience:
+
+```ts title="agent/channels/eve.ts"
+import { vercelOidc } from "eve/channels/auth";
+import { eveChannel } from "eve/channels/eve";
+
+export default eveChannel({
+  auth: [vercelOidc()],
+  audience: "public",
+});
+```
+
+`audience` controls observability content capture; it does not change who may
+call the endpoint. `auth` still controls access. For a classification that
+depends on channel state or application-specific verified data, use a [custom
+channel audience](./custom#conversation-audience).
+
+You can also pass a function that receives `caller`, channel, run mode, and
+deployment environment. Classification is fixed at session creation, so a later
+turn from a different caller does not reclassify the session.
+
+For a remote agent, a trusted dispatch can forward the original audience and
+its trace-content ceiling. See [Preserving trace
+content](../guides/remote-agents#preserving-trace-content).
+
 ## Customization
 
 Use `onMessage` to add request-specific context before the agent sees the user message, and `events` to observe stream events from sessions this channel created:

package/docs/channels/linear.mdx

@@ -11,12 +11,16 @@ The Linear channel uses Linear's Agent Session surface rather than ordinary comm
 Run the registry setup from the agent directory:
 
 ```bash
-eve add linear
+eve add channel/linear
 ```
 
-Select **Linear Channel** in the component checklist. **Linear MCP** is also selected by default if you want the agent to search and update Linear through MCP. Run `eve add channel/linear-agent` instead to install only the channel directly.
+To let the agent search and update Linear through MCP, install the separate Linear connection:
 
-The flow signs you in to Vercel when needed, creates or links a Vercel project, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
+```bash
+eve add connection/linear
+```
+
+The channel setup flow signs you in to Vercel when needed, creates or links a Vercel project, reuses a compatible existing connector when available or provisions an app-scoped Linear Connect client, and registers `/eve/v1/linear` as a trigger destination. It then installs `@vercel/connect` and writes `agent/channels/linear.ts` with the connector UID.
 
 Vercel Connect creates the Linear app with the `app:assignable` and `app:mentionable` scopes required for Agent Sessions, receives and verifies `AgentSessionEvent` webhooks, and forwards them to the deployed agent. After deploying, open the Linear app in the Connect dashboard and install it in the workspace where you want to delegate work. Then delegate an issue or mention the agent in a Linear Agent Session.
 

package/docs/channels/overview.mdx

@@ -13,6 +13,19 @@ eve ships a base HTTP channel plus first-class platform channels, and you can au
 
 After a channel normalizes input, eve runs the same agent runtime regardless of where the message came from. Tools and instructions do not need channel-specific logic.
 
+## Audience
+
+When a channel creates a session, it assigns an observability audience:
+`public`, `private`, or `unknown`. The audience controls trace content capture,
+not who may call the channel. Each channel uses the visibility information it
+has; `unknown` is the safe default when it cannot classify a conversation.
+
+Route auth controls access and supplies the session principal. See [Auth &
+route protection](../guides/auth-and-route-protection) for principal types and
+authorization. See the [default eve HTTP channel](./eve#audience) for its
+mapping, or [custom channels](./custom#conversation-audience) to classify your
+own.
+
 ## Overlapping messages
 
 Channels default to `turnPolicy: "steer"`. When an accepted message arrives while a turn is active, eve first durably buffers the message, then cooperatively cancels the active turn and starts a replacement turn. The cancelled turn emits `turn.cancelled` followed by `session.waiting`; the replacement starts with a new turn ID. Output already streamed and completed side effects are not rolled back.

package/docs/channels/slack.mdx

@@ -137,6 +137,14 @@ Check the delivery path in order so you can identify where a Slack event stops:
 | A preview request receives an authentication page or protection error | Check whether the branch domain is exempt or the direct Slack request URL includes `x-vercel-protection-bypass`. Slack cannot complete an interactive Vercel Authentication challenge. | Add a Deployment Protection Exception for the branch domain, or add the automation bypass query parameter to a Slack app that uses environment-variable credentials. |
 | The webhook reaches the deployment but the agent does not reply       | Open the project's Vercel runtime logs, then inspect the session in **Agent Runs** when your team has access.                                                                          | Use the first missing or failed stage to narrow the issue to channel dispatch, the agent run, or outbound Slack delivery.                                            |
 
+## Audience
+
+Slack public channels are `public`; DMs, group DMs, and private channels are
+`private`. When an inbound event does not identify the conversation type, eve
+checks Slack and treats an ambiguous or failed lookup as `private`. The audience
+controls observability content capture, not access to the channel. See
+[Audience](./overview#audience) for the shared channel model.
+
 ## How the channel handles inbound events
 
 ### Message hooks
@@ -453,6 +461,38 @@ export default slackChannel({
 
 The callback receives the `InputRequest` and current `SessionContext`, so it can switch on `kind`, `action`, or presentation properties. Omit it to keep every request in the thread, or return `"direct-message"` unconditionally to make every request private. If eve cannot resolve the triggering Slack user for a direct message, it logs the undelivered request and posts no fallback, so private delivery fails closed. The existing `onInputResponse` or tool approval response policy still decides whether the person who clicks may respond.
 
+An authored `input.requested` handler can extend delivery and then hand the requests back to eve through `defaultDeliver()`. For example, an application can add non-sensitive context to the Slack thread before eve renders the actionable controls. The configured `approvalChannel` still sends sensitive reviews to a DM and keeps ordinary requests in the thread:
+
+```ts title="agent/channels/slack.ts"
+import { slackChannel } from "eve/channels/slack";
+import { isPrivate } from "../lib/review-policy";
+
+export default slackChannel({
+  approvalChannel(request) {
+    return isPrivate(request) ? "direct-message" : "thread";
+  },
+  events: {
+    async "input.requested"(event, channel, _ctx, defaultDeliver) {
+      await channel.thread.post({
+        blocks: [
+          {
+            type: "context",
+            elements: [
+              {
+                type: "mrkdwn",
+                text: "A review is needed before this work can continue.",
+              },
+            ],
+          },
+        ],
+        text: "A review is needed before this work can continue.",
+      });
+      await defaultDeliver(event);
+    },
+  },
+});
+```
+
 Authorization prompts split public status from private credentials. A sign-in challenge (OAuth URL, device code) is a credential. Anyone who completes it binds their identity to the session's connection. The default `authorization.required` handler posts a public, link-free status in the thread, delivers the actual challenge ephemerally to the triggering user, device code included, and then updates that public status when `authorization.completed` fires. The handler receives a private-delivery context with `postEphemeral`, `postDirectMessage` (needs the `im:write` scope), and `state`. There is, intentionally, no public `post` and no raw API access.
 
 ```ts
@@ -469,7 +509,7 @@ The private authorization button uses the label **Sign in**, so long connection
 
 ### Proactive sessions
 
-Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, installationTeamId?, threadTs?, initialMessage? }`. Set `installationTeamId` to the app installation workspace when a function-form bot token must select an installation. This sends turn input to the agent; it is not a direct Slack post.
+Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, installationTeamId?, threadTs?, initialMessage?, audience? }`. It defaults to `unknown`; pass `audience` only when the caller already knows the destination's visibility. Set `installationTeamId` to the app installation workspace when a function-form bot token must select an installation. This sends turn input to the agent; it is not a direct Slack post.
 
 To post without invoking the model, use `ctx.thread.post(...)` in an inbound Slack handler or `channel.thread.post(...)` in an `events` handler. Use `callSlackApi(...)` where no Slack channel context exists. For application-managed retries and deduplication, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
 

package/docs/connections/mcp.mdx

@@ -24,6 +24,20 @@ export default defineMcpClientConnection({
 
 The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: it is the main signal `connection_search` uses when deciding which connection to query.
 
+## Configure protocol discovery
+
+eve discovers the server's MCP protocol by default. If a server requires the older `initialize` handshake, disable discovery for that connection:
+
+```ts
+export default defineMcpClientConnection({
+  url: "https://mcp.example.com/mcp",
+  description: "Search support cases",
+  protocolVersionDiscovery: false,
+});
+```
+
+With `protocolVersionDiscovery: false`, the client skips `server/discover` and starts with `initialize`, proposing `2025-11-25` and negotiating a supported handshake-based version. This is a per-connection setting; omitting it or setting it to `true` keeps discovery enabled. Remove the override when the server supports discovery. The setting also applies to connections returned by dynamic resolvers.
+
 ## Use Vercel Connect for OAuth
 
 For OAuth-backed MCP servers, use the shared [Vercel Connect flow](../connections#interactive-oauth-via-vercel-connect), then pass the returned connector UID to `connect()`. Keep the MCP runtime URL and Connect service identifier distinct. For example, Linear uses `https://mcp.linear.app/mcp` as the MCP endpoint and `mcp.linear.app` when creating the connector.
@@ -111,7 +125,10 @@ const publishesNow = (input: unknown): boolean => {
 export default defineMcpClientConnection({
   url: "https://mcp.example.com/mcp",
   description: "Social publishing: draft, schedule, and manage posts.",
-  auth: { getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }) },
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }),
+  },
   approval: ({ toolName, toolInput }) => {
     if (DELETE_TOOLS.some((t) => toolName.includes(t))) return "user-approval";
     if (PUBLISH_TOOLS.some((t) => toolName.includes(t))) {

package/docs/connections/openapi.mdx

@@ -17,7 +17,10 @@ import { defineOpenAPIConnection } from "eve/connections";
 export default defineOpenAPIConnection({
   spec: "https://petstore3.swagger.io/api/v3/openapi.json",
   description: "Pet store inventory and orders.",
-  auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
+  },
 });
 ```
 
@@ -102,7 +105,10 @@ import { defineOpenAPIConnection } from "eve/connections";
 export default defineOpenAPIConnection({
   spec: "https://petstore3.swagger.io/api/v3/openapi.json",
   description: "Pet store inventory and orders.",
-  auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
+  },
   operations: { allow: ["getInventory", "placeOrder"] },
 });
 ```

package/docs/connections/overview.mdx

@@ -69,6 +69,7 @@ export default defineMcpClientConnection({
   url: "https://mcp.linear.app/mcp",
   description: "Linear workspace.",
   auth: {
+    credentialOwner: "app",
     getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
   },
 });
@@ -76,7 +77,7 @@ export default defineMcpClientConnection({
 
 If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
 
-When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Switch to `principalType: "user"` when each end-user carries their own token.
+When `getToken` is the only auth, `credentialOwner` defaults to `"app"`: one shared credential keyed across all sessions. Set `credentialOwner: "user"` when each end-user carries their own token.
 
 eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
 
@@ -86,11 +87,13 @@ A connection credential can belong to the agent or to the person using it. This
 
 | Credential owner | Use when                                                                       | Auth shape                                                                                                                                                   |
 | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| App              | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `principalType: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect.        |
-| User             | Each end-user should authorize and use their own third-party account.          | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { principalType: "user", getToken }`.              |
+| App              | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `credentialOwner: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect.      |
+| User             | Each end-user should authorize and use their own third-party account.          | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { credentialOwner: "user", getToken }`.            |
 | User from a job  | Background work should use the same user's OAuth grant that started the work.  | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |
 
-`principalType: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.
+`credentialOwner: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.
+
+`credentialOwner` is eve's field for raw getToken-only connection auth. Existing non-interactive raw `principalType` definitions still work, but are deprecated. Interactive auth and `connect()` from `@vercel/connect/eve` continue to use `principalType: "user"`; that field also remains correct for route-auth session identities.
 
 ## No auth
 
@@ -132,7 +135,7 @@ export default defineOpenAPIConnection({
   spec: "https://warehouse.example.com/openapi.json",
   description: "The caller's tenant-scoped warehouse.",
   auth: (ctx) => ({
-    principalType: "user",
+    credentialOwner: "user",
     getToken: async () => ({
       token: await tenantToken(ctx.session.auth.current),
     }),
@@ -151,7 +154,7 @@ headers: {
 }
 ```
 
-Use `principalType: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
+Use `credentialOwner: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
 
 ## Per-connection approval
 
@@ -223,16 +226,16 @@ App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app t
 
 ### Troubleshooting Vercel Connect auth
 
-| Symptom                                      | What it means                                                                                                                     | Fix                                                                                                                                       |
-| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `reason: "principal_required"`               | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or change the connection to `principalType: "app"` if it should be shared.  |
-| `authorization.required` appears but no UI   | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                              |
-| OAuth works locally but fails after deploy   | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`. |
-| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.            |
+| Symptom                                      | What it means                                                                                                                     | Fix                                                                                                                                                             |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reason: "principal_required"`               | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or use `connect({ connector, principalType: "app" })` if the Connect credential should be shared. |
+| `authorization.required` appears but no UI   | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                                                    |
+| OAuth works locally but fails after deploy   | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`.                       |
+| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.                                  |
 
 ## Self-hosted interactive OAuth
 
-To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`, and the factory pins that for you.
+To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`; `credentialOwner` applies only to getToken-only auth, and the factory pins the interactive value for you.
 
 ```ts title="agent/connections/linear.ts"
 import {

package/docs/getting-started.mdx

@@ -156,7 +156,7 @@ Prefer the nested layout because it keeps application files separate from the au
 
 ### Debug file discovery
 
-Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Observability](./guides/instrumentation) and the [CLI](./reference/cli) reference.
+Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Instrumentation](./observability/instrumentation) and the [CLI](./reference/cli) reference.
 
 ## Install manually
 

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

@@ -84,5 +84,5 @@ eve dev https://your_agent.example.com
 Use these guides to secure and observe the deployed agent:
 
 - [Authentication](../auth-and-route-protection): configure the host’s route policy
-- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
 - [Sandbox](../../sandbox): select and secure a sandbox backend

package/docs/guides/deployment/vercel.mdx

@@ -158,12 +158,12 @@ Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before connecting if the deploymen
 
 Vercel detects eve and can add an **Agent Runs** tab under the project’s **Observability** view. Use it to browse sessions and inspect each conversation trace.
 
-The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel representative if the tab doesn’t appear. For third-party tracing backends, configure [OpenTelemetry instrumentation](../instrumentation).
+The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel representative if the tab doesn’t appear. For third-party tracing backends, configure [OpenTelemetry instrumentation](../../observability/instrumentation).
 
 ## Continue configuring production
 
 Use these guides to secure and observe the deployed agent:
 
 - [Authentication](../auth-and-route-protection): configure who can call the deployed agent
-- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
 - [Sandbox](../../sandbox): configure resources, isolation, and network access

package/docs/guides/dev-tui.md

@@ -49,7 +49,7 @@ Pass an item address to `/add` to confirm and install that exact address without
 ```text
 /add channel/slack
 /add extension/agent-browser
-/add linear
+/add channel/linear
 /add @acme/analytics
 ```
 
@@ -77,7 +77,7 @@ By default, the UI shows `stderr` logs. Use `/loglevel <all|stderr|sandbox|none>
 
 Every `eve dev` process writes diagnostic logs to `.eve/logs/`, regardless of the display mode. Read them with [`eve logs`](../reference/cli#eve-logs).
 
-Use `/traces` to inspect traces recorded during local development. See [Instrumentation](instrumentation#local-traces) for trace capture and retention settings.
+Use `/traces` to inspect traces recorded during local development. See [Instrumentation](../observability/instrumentation#local-traces) for trace capture and retention settings.
 
 ## Display options
 
@@ -87,7 +87,7 @@ Use `eve dev` flags to control tool calls, reasoning, subagents, connection auth
 eve dev --tools full --reasoning collapsed --logs all
 ```
 
-Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
+Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. Set `EVE_TUI_RENDER_MARKDOWN=0` to show assistant and subagent responses without Markdown parsing or styling; `1` (the default) enables Markdown rendering. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
 
 ## Connect to a deployment
 
@@ -108,6 +108,6 @@ For a Vercel deployment that needs authentication, run `/vc:login` and follow th
 
 ## What to read next
 
-- [Instrumentation](./instrumentation): traces, OpenTelemetry, and diagnostics.
+- [Instrumentation](../observability/instrumentation): traces, OpenTelemetry, and diagnostics.
 - [CLI](../reference/cli): commands and flags.
 - [Agent Client Protocol (ACP)](../protocols/acp): drive the same agent from ACP clients such as Zed instead of the TUI.

package/docs/guides/dynamic-capabilities.md

@@ -136,9 +136,9 @@ shadows the session selection for that turn, including when the turn handler
 returns `null`. If a resolver throws or returns an invalid definition, eve logs the
 failure and omits the subagent.
 
-The resolved set applies to local and remote direct delegation. Background subagents are not
-exposed inside the model-authored `Workflow` tool. eve
-also checks availability again before starting the child, so a stale or
+The resolved set applies to local and remote direct delegation. An authored workflow tool can
+also call a selected subagent through `ctx.agent`. A generated program can call it through the
+provided `workflow` tool. eve checks availability again before starting the child, so a stale or
 manually constructed call fails with `SUBAGENT_UNAVAILABLE`. Treat conditional
 availability as capability composition, not as the only authorization
 boundary: sensitive child tools still need their own authorization and
@@ -178,7 +178,7 @@ export default defineDynamic({
             description: `${account.label} (${account.accountId})`,
             instanceKey: account.accountId,
             auth: {
-              principalType: "user",
+              credentialOwner: "user",
               getToken: ({ principal }) => mintAccountToken(principal, account),
             },
           }),

package/docs/guides/frontend/nextjs.mdx

@@ -22,7 +22,9 @@ const nextConfig: NextConfig = {};
 export default withEve(nextConfig);
 ```
 
-By default `withEve()` looks for an `agent/` folder inside your Next.js project root. If the agent lives somewhere else, point at it with `eveRoot`:
+By default `withEve()` looks for an `agent/` folder inside your Next.js project root. When the project root is an eve workspace with `agents/<name>/` members, it discovers every member and mounts each at `/eve/agents/<name>/eve/v1/*` instead.
+
+If one agent lives somewhere else, point at it with `eveRoot`:
 
 ```ts
 export default withEve(nextConfig, {
@@ -30,7 +32,7 @@ export default withEve(nextConfig, {
 });
 ```
 
-For multiple agents, use `agents`. String values are agent roots; object values can override the build command or private production service prefix for that agent:
+To mount agents that are not members of the project-level `agents/` workspace, use `agents`. String values are agent roots; object values can override the build command or private production service prefix for that agent:
 
 ```ts
 export default withEve(nextConfig, {
@@ -60,13 +62,13 @@ Generated agent services build with `EVE_PUBLIC_ROUTE_PREFIX` set to the agent's
 
 All fields are optional.
 
-| Option               | Type                  | Default                | Purpose                                                                                                                                                    |
-| -------------------- | --------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eveRoot`            | `string`              | Next.js app root       | Path to one unnamed eve app root, relative to `process.cwd()` unless absolute. Do not combine with `agents`.                                               |
-| `agents`             | `Record<string, ...>` | unset                  | Named eve agents to mount under `/eve/agents/<name>/eve/v1/*`. Each value is a root string or `{ root, buildCommand?, servicePrefix? }`.                   |
-| `eveBuildCommand`    | `string`              | generated              | Build command for generated eve Vercel services. In multi-agent mode this is the default for agents without their own `buildCommand`.                      |
-| `servicePrefix`      | `string`              | `"/_eve_internal/eve"` | Private route namespace for legacy manual Vercel service configs and non-Vercel production proxying. Named agents derive unique defaults from this prefix. |
-| `devServerTimeoutMs` | `number`              | `180000`               | Maximum time to wait for each eve development server to become available.                                                                                  |
+| Option               | Type                  | Default                  | Purpose                                                                                                                                                                                                                                                     |
+| -------------------- | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eveRoot`            | `string`              | Next.js app root         | Path to one unnamed eve app root, relative to `process.cwd()` unless absolute. Do not combine with `agents`.                                                                                                                                                |
+| `agents`             | `Record<string, ...>` | inferred for a workspace | Named eve agents to mount under `/eve/agents/<name>/eve/v1/*`. `withEve()` discovers project-level `agents/<name>/` members when neither `agents` nor `eveRoot` is set; otherwise each value is a root string or `{ root, buildCommand?, servicePrefix? }`. |
+| `eveBuildCommand`    | `string`              | generated                | Build command for generated eve Vercel services. In multi-agent mode this is the default for agents without their own `buildCommand`.                                                                                                                       |
+| `servicePrefix`      | `string`              | `"/_eve_internal/eve"`   | Private route namespace for legacy manual Vercel service configs and non-Vercel production proxying. Named agents derive unique defaults from this prefix.                                                                                                  |
+| `devServerTimeoutMs` | `number`              | `180000`                 | Maximum time to wait for each eve development server to become available.                                                                                                                                                                                   |
 
 For slow cold starts, increase the development timeout:
 
@@ -124,7 +126,7 @@ See [Resumable sessions](./overview#resumable-sessions) for persistence and repl
   });
   ```
 
-- **Local production build.** `next build && next start` serves the eve runtime from its built `.output/server/index.mjs` on a stable local port (`4274`) and proxies the eve routes to it. Run `eve build` first so that output exists. Change the port with `EVE_NEXT_PRODUCTION_PORT`:
+- **Local production build.** `next build && next start` serves the eve runtime from its built `.output/server/index.mjs` on a stable local port (`4274`) and proxies the eve routes to it. Run `eve build` first so that output exists. In an `agents/` workspace, build every member from its `agents/<name>/` directory before starting Next.js. Change the port with `EVE_NEXT_PRODUCTION_PORT`:
 
   ```bash
   EVE_NEXT_PRODUCTION_PORT=5000 npm run build && npm start

package/docs/guides/hooks.md

@@ -50,7 +50,7 @@ export default githubChannel({
 
 A GitHub channel event handler cannot fire for a Slack-owned session, so platform-specific side effects do not depend on an early-return guard. On a built-in channel, an authored handler replaces that channel's default handler for the same event key. Check the channel page before overriding events that deliver replies, progress, errors, or human-input prompts.
 
-Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [Instrumentation](./instrumentation#runtime-context).
+Use `ctx.channel.kind` inside a global hook only when the operation is otherwise agent-wide and conditional handling is intentional. For typed channel metadata in dynamic resolvers or instrumentation, import the channel definition and narrow with `isChannel`; see [Add runtime context](../observability/instrumentation#add-runtime-context).
 
 ## Hook structure and context
 

package/docs/guides/instrumentation/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Observability",
+  "pages": ["overview", "providers", "otel"]
+}

package/docs/guides/instrumentation/otel.mdx

@@ -0,0 +1,149 @@
+---
+title: "OpenTelemetry"
+description: "Configure OpenTelemetry destinations, content capture, and managed exports with Instrumentation Providers."
+url: "/observability/otel"
+---
+
+<Callout type="warning" title="Experimental">
+  This API is experimental and may change without a deprecation period.
+</Callout>
+
+Use the built-in APIs from `eve/instrumentation/otel` to configure eve's
+OpenTelemetry pipeline. This page requires the experimental
+[Instrumentation Providers](./instrumentation-providers) layout.
+
+## Configure OpenTelemetry
+
+OpenTelemetry configuration has two parts:
+
+- `otel()` declares process-wide settings such as the resource, sampler,
+  propagators, and trace capture policy. Declare it at most once.
+- `otelIntegration()` adds one destination. Declare one file per exporter or
+  processor chain.
+
+Add `agent/instrumentation/otel.ts` when you need process-wide settings or
+want to control the content eve writes to OpenTelemetry spans:
+
+```ts title="agent/instrumentation/otel.ts"
+import { otel } from "eve/instrumentation/otel";
+
+export default otel({
+  resource: { "deployment.environment": process.env.VERCEL_ENV ?? "development" },
+  tracePolicy: ({ audience, environment }) => ({
+    emit: true,
+    recordInputs: audience === "public" || environment === "development",
+    recordOutputs: audience === "public" || environment === "development",
+  }),
+});
+```
+
+The OpenTelemetry `tracePolicy` is a capture ceiling shared by every OTel
+destination. A destination cannot restore content excluded by this policy. It
+does not affect lifecycle-event providers created with `defineInstrumentation()`.
+
+## Add an OpenTelemetry destination
+
+Most agents only need a destination:
+
+```ts title="agent/instrumentation/braintrust.ts"
+import { BraintrustExporter } from "@braintrust/otel";
+import { otelIntegration } from "eve/instrumentation/otel";
+
+export default otelIntegration({
+  traceExporter: new BraintrustExporter({ filterAISpans: true }),
+});
+```
+
+Pass `spanProcessors` to `otelIntegration()` when a custom destination needs
+filtering or transformation. `exportPolicy` is for the built-in
+`localTraces()` and `agentRuns()` destinations below.
+
+## Trace topology
+
+OpenTelemetry destinations receive the following trace topology for an ordinary
+agent turn:
+
+```text
+invoke_agent <agent>
+  └── agent.step
+        ├── chat <model>
+        └── agent.action
+              └── execute_tool <tool>
+```
+
+Each turn starts a new trace. The first subagent trace links to its caller with
+`eve.link.type=agent.dispatch`. Use `gen_ai.conversation.id` to find the traces
+for one conversation in your destination's span-search surface.
+
+## Manage built-in destinations
+
+The provider layout has two environment-specific defaults:
+
+- `local` records local traces during `eve dev`.
+- `agent-runs` exports to Vercel Agent Runs in preview and production
+  deployments.
+
+Omitting these files preserves the defaults. Reconfigure a destination by
+exporting `localTraces()` or `agentRuns()` from the matching file. Disable one
+explicitly:
+
+```ts title="agent/instrumentation/local.ts"
+import { disableInstrumentation } from "eve/instrumentation";
+
+export default disableInstrumentation();
+```
+
+## Filter a managed destination
+
+`localTraces()` and `agentRuns()` accept an `exportPolicy`. It filters spans
+and attributes before that destination's processors receive them:
+
+```ts title="agent/instrumentation/agent-runs.ts"
+import { agentRuns } from "eve/instrumentation/otel";
+
+export default agentRuns({
+  exportPolicy: {
+    span: ({ name }) => name !== "internal.cache.refresh",
+    attribute: ({ key }) => (key === "customer.id" ? { action: "drop" } : { action: "keep" }),
+  },
+});
+```
+
+Return `false` from `span` to omit that span from this destination. Return
+`{ action: "keep" }`, `{ action: "drop" }`, or
+`{ action: "replace", value }` from `attribute` to retain, remove, or change
+one attribute.
+
+### Further narrow a built-in destination
+
+Use the content redactors to further narrow what a built-in destination
+receives after the process-wide `otel({ tracePolicy })` has admitted a trace.
+For example, keep the spans in Agent Runs while redacting their inputs and
+outputs unless the session is public:
+
+```ts title="agent/instrumentation/agent-runs.ts"
+import {
+  agentRuns,
+  composeSpanExportPolicies,
+  redactSpanInputs,
+  redactSpanOutputs,
+} from "eve/instrumentation/otel";
+
+export default agentRuns({
+  exportPolicy: composeSpanExportPolicies(
+    redactSpanInputs(({ audience }) => audience !== "public"),
+    redactSpanOutputs(({ audience }) => audience !== "public"),
+  ),
+});
+```
+
+`redactSpanInputs()` removes eve's known prompt, instruction, document, and
+tool-argument attributes. `redactSpanOutputs()` removes response, reasoning,
+tool-result, exception, and status attributes. They narrow only this
+destination; they do not mutate spans sent to another destination.
+
+## What to read next
+
+- [Instrumentation Providers](./instrumentation-providers): add lifecycle-event providers.
+- [Instrumentation](../observability/instrumentation): configure the current single-file API.
+- [Local development](../guides/dev-tui): inspect local traces in the TUI.