eve 0.55.0 → 0.56.0

package/docs/channels/custom.mdx

@@ -312,27 +312,37 @@ The projection is re-evaluated whenever adapter state changes after channel even
 
 ### Conversation audience
 
-Use `audience(input)` to classify who can observe the conversation. The hook runs after route authentication and before the session is created:
+Use `audience(input)` to assign an observability audience. The audience controls
+whether instrumentation may capture conversation content. The hook runs after
+route authentication and before the session is created:
 
 ```ts
 import { defineChannel, POST } from "eve/channels";
 
 export default defineChannel({
   state: { visibility: "workspace" as "workspace" | "private" | "unknown" },
-  audience({ state, auth }) {
+  audience({ state, caller }) {
     if (state.visibility === "workspace") return "public";
-    if (auth?.principalType === "user") return "private";
+    if (caller.type === "principal" && caller.principal.kind === "user") return "private";
     return "unknown";
   },
   routes: [POST("/webhook", async () => new Response("ok"))],
 });
 ```
 
-The input contains the channel's `state`, authenticated `auth` principal, `channel`, `mode`, and `environment`. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`.
+The input contains the channel's `state`, `caller`, `channel`, `mode`, and `environment`. A principal caller omits `principalId`, `issuer`, and `subject`, but its `attributes` come from route auth and can still contain identifying values. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`.
 
-Classification is fixed when the session is created. Continuation turns from a different caller do not reclassify an existing session. When a parent dispatches a local subagent, the child inherits the parent's audience while the framework forwards the parent's custom channel metadata separately.
+When you explicitly annotate a callback, use `AudienceContext<TState>`. `AudienceInput<TState>` remains supported for existing callbacks while you migrate.
+
+Existing callbacks can continue using `auth?.principalType` while you migrate:
+
+```ts
+audience({ auth }) {
+  return auth?.principalType === "user" ? "private" : "unknown";
+}
+```
 
-`metadata(state)` remains a channel-owned projection of custom observability fields. It no longer carries a reserved `audience` key. Channel extensions built before channel epoch 20 can still use that key; eve accepts it as a deprecated fallback and warns once, then authors should move classification to `audience(input)`.
+Classification is fixed when the session is created. Continuation turns from a different caller do not reclassify an existing session. When a parent dispatches a local subagent, the child inherits the parent's audience while the framework forwards the parent's custom channel metadata separately.
 
 ## Continuation tokens
 

package/docs/channels/eve.mdx

@@ -159,42 +159,42 @@ For the full auth model and helper list, see [Auth & route protection](../guides
 
 ## Audience
 
-The eve channel classifies who can observe a session when that session is created:
+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                          | `public`         |
+| Anonymous caller                          | `unknown`        |
 | `user`, `service`, or `runtime` principal | `private`        |
 | Any other principal type                  | `unknown`        |
 
-Anonymous HTTP surfaces are public because anyone who can reach the surface can read it. Authenticated `user`, `service`, and `runtime` sessions are private because they belong to one identified party. Other authenticated principal types remain `unknown`: trace consumers record metadata but omit content by default in preview and production.
+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.
 
-Pass a constant or a function to override the default:
+For a production endpoint whose conversations are all intentionally public,
+set a constant audience:
 
 ```ts title="agent/channels/eve.ts"
-import { none, vercelOidc } from "eve/channels/auth";
+import { vercelOidc } from "eve/channels/auth";
 import { eveChannel } from "eve/channels/eve";
 
 export default eveChannel({
   auth: [vercelOidc()],
-  audience: "private",
+  audience: "public",
 });
 ```
 
-```ts title="agent/channels/eve.ts"
-import { vercelOidc } from "eve/channels/auth";
-import { eveChannel } from "eve/channels/eve";
+`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).
 
-export default eveChannel({
-  auth: [vercelOidc(), none()],
-  audience({ auth, environment }) {
-    if (auth === null) return environment === "development" ? "public" : "unknown";
-    return "private";
-  },
-});
-```
+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.
 
-The function receives the authenticated principal, channel, run mode, and deployment environment. Classification is fixed at session creation; a continuation turn from a different caller does not reclassify the session. When another eve deployment forwards a request without an accepted forwarded trace assertion, the calling deployment's principal is used for classification, so the session remains `private`. A custom [trace policy](../guides/instrumentation-providers#control-inputs-and-outputs) can still admit or deny content independently.
+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
 

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
@@ -501,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

@@ -125,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/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.