eve 0.55.0 → 0.57.0

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.

package/docs/guides/instrumentation/overview.md

@@ -0,0 +1,199 @@
+---
+title: "Instrumentation"
+description: "Trace an agent with OpenTelemetry in instrumentation.ts, read the workflow run tags eve emits, and debug discovery with eve info and the common-failures table."
+url: "/observability/instrumentation"
+---
+
+Use `agent/instrumentation.ts` to configure OpenTelemetry for an eve agent.
+eve discovers this file and runs it at server startup before agent code.
+
+## Configure OpenTelemetry
+
+Export `defineInstrumentation(...)` as the default export from
+`agent/instrumentation.ts`. eve discovers the file and runs its `setup`
+callback at server startup, before agent code runs.
+
+```ts title="agent/instrumentation.ts"
+import { BraintrustExporter } from "@braintrust/otel";
+import { defineInstrumentation } from "eve/instrumentation";
+import { registerOTel } from "@vercel/otel";
+
+export default defineInstrumentation({
+  setup: ({ agentName }) =>
+    registerOTel({
+      serviceName: agentName,
+      traceExporter: new BraintrustExporter({
+        parent: `project_name:${agentName}`,
+        filterAISpans: true,
+      }),
+    }),
+});
+```
+
+Use `setup` to register your OTel provider. eve supplies the resolved agent
+name, so you do not need to hard-code a service name. Any OTel-compatible
+backend works; install and configure the exporter it requires.
+
+eve records metadata without model, tool, or memory-record content by default.
+After reviewing the exporter's destination and retention path, opt in to the
+content you need:
+
+- `recordInputs` records message history and recalled memory records. It
+  defaults to `false`.
+- `recordOutputs` records model outputs. It defaults to `false`.
+- `functionId` overrides the function name on spans. It defaults to the agent
+  name.
+
+The session's channel audience is a second gate on content capture. In
+Vercel's preview and production deployments, eve records inputs and outputs
+only for `public` sessions. During local development, local tracing retains all
+content. See [Local traces](#local-traces) to learn more.
+
+For the default eve HTTP channel, the audience is:
+
+| Session creator                                      | Audience  |
+| ---------------------------------------------------- | --------- |
+| Anonymous caller                                     | `unknown` |
+| Authenticated `user`, `service`, or `runtime` caller | `private` |
+| Any other principal type                             | `unknown` |
+
+Set `audience: "public"` only for intentionally public traffic. Other
+built-in channels classify their own conversations. See
+[Audience](../channels/eve#audience) for the `eve` channel or
+[Conversation audience](../channels/custom#conversation-audience) for a
+custom channel.
+
+## Add runtime context
+
+Use `events["step.started"]` to add values to the AI SDK runtime context for a
+model attempt. The AI SDK carries the returned values onto the model-call span
+and its children.
+
+```ts title="agent/instrumentation.ts"
+import { defineInstrumentation, isChannel } from "eve/instrumentation";
+import supportChannel from "./channels/support";
+
+export default defineInstrumentation({
+  events: {
+    "step.started"(input) {
+      if (!isChannel(input.channel, supportChannel)) return undefined;
+
+      return {
+        runtimeContext: {
+          "support.channel_id": input.channel.metadata.channelId ?? "",
+          "support.user_id": input.channel.metadata.triggeringUserId ?? "",
+        },
+      };
+    },
+  },
+});
+```
+
+The callback receives the session, turn, step, channel, and final model input.
+For an authored channel, import its definition and use `isChannel` before
+accessing its typed metadata. Runtime instrumentation receives only the
+metadata a channel explicitly exposes; it never falls back to raw channel
+state.
+
+## Trace topology
+
+When `agent/instrumentation.ts` registers an OTel provider, each turn produces
+this hierarchy:
+
+```text
+ai.eve.turn  {eve.session.id}
+  +-- invoke_agent <model>                    gen_ai.operation.name=invoke_agent
+        +-- step 1                            gen_ai.operation.name=agent_step
+        |     +-- chat <model>                gen_ai.operation.name=chat
+        |     +-- execute_tool search         gen_ai.operation.name=execute_tool
+        +-- step 2
+        |     +-- chat <model>
+        |     +-- execute_tool read
+        +-- step 3 (final text)
+              +-- chat <model>
+```
+
+eve creates the `ai.eve.turn` parent span and passes telemetry to the
+[AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/telemetry), which traces model
+calls and tool executions. The AI SDK names those spans according to the
+OpenTelemetry GenAI semantic conventions.
+
+Set `traceChannelRequests: true` to create one OTel `SERVER` span for each
+inbound channel HTTP request. The span parents the turn tree and any
+`hook.resume` or outgoing HTTP spans. It defaults to `false`.
+
+```text
+POST /eve/v1/session/:sessionId
+  └── hook.resume
+        ├── GET hooks/by-token
+        └── POST hook_received
+```
+
+The request span uses a route template in `http.route` and the method in
+`http.request.method`; it does not record concrete URLs, session IDs, tokens,
+headers, bodies, or query parameters. It adopts an incoming `traceparent` when
+present.
+
+## Local traces
+
+Without `agent/instrumentation.ts`, `eve dev` records one bounded trace per
+turn under `.eve/traces/`. View traces with
+[`/traces`](../guides/dev-tui#logs-and-traces) in the dev TUI or
+[`eve traces`](../reference/cli#eve-traces) after `eve dev` exits.
+
+Local traces retain model, tool, and memory-record content by default. Set
+`EVE_TRACES_CONTENT=off` in `.env.local` to omit it. Writing
+`agent/instrumentation.ts` replaces local tracing; its `recordInputs` and
+`recordOutputs` settings control content in the OTel provider you register.
+
+## Workflow run tags
+
+Separately from OpenTelemetry, eve tags every Workflow run with reserved
+`$eve.*` attributes. These framework-owned attributes are queryable in the
+Workflow dashboard, not on OTel spans. eve emits them for every session, turn,
+and subagent run, whether or not `agent/instrumentation.ts` exists.
+
+Structural tags describe a run's place in its tree:
+
+- `$eve.type`: `"session"`, `"turn"`, or `"subagent"`.
+- `$eve.parent`: the immediate parent session ID.
+- `$eve.root`: the root session ID for the tree.
+- `$eve.subagent`: the compiled graph node ID for a subagent run.
+- `$eve.trigger`: the channel kind that started the run.
+- `$eve.schedule`: the schedule that created the session.
+- `$eve.title`: a truncated title from the first user message.
+- `$eve.trace_id`: a sampled trace seed. Use it as a trace link, not a
+  conversation-wide identity.
+
+Each turn also accumulates `$eve.model`, `$eve.input_tokens`,
+`$eve.output_tokens`, `$eve.cache_read_tokens`, and `$eve.tool_count`. These
+tags power the **Agent Runs** tab in Vercel's **Observability** view. See
+[Deploy to Vercel](../guides/deployment/vercel#inspect-agent-runs) for
+enablement.
+
+## Debug discovery
+
+Run `eve info` to see the instrumentation eve discovered and any diagnostics.
+eve also writes these inspectable artifacts under `.eve/`:
+
+| Artifact                        | Tells you                           |
+| ------------------------------- | ----------------------------------- |
+| `agent-discovery-manifest.json` | What eve found on disk.             |
+| `diagnostics.json`              | Authored-shape errors and warnings. |
+| `compiled-agent-manifest.json`  | The surface eve loads at runtime.   |
+| `module-map.mjs`                | Compiled module entry points.       |
+
+### Common failures
+
+| Symptom                               | Next action                                                                                       |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Instrumentation is not discovered.    | Run `eve info`, confirm the file is in the expected slot, and read `.eve/diagnostics.json`.       |
+| A tool is not discovered.             | Confirm it is under `agent/tools/`, default-exports `defineTool(...)`, and appears in `eve info`. |
+| `eve build` reports discovery errors. | Read the printed diagnostics and `.eve/diagnostics.json`.                                         |
+
+## Instrumentation Providers
+
+[Instrumentation Providers](./instrumentation-providers) is an experimental
+multi-file alternative. It cannot be used with `agent/instrumentation.ts`.
+Use it when you need independent lifecycle-event providers, OpenTelemetry
+destinations, directional content capture, or per-destination redaction.

package/docs/guides/instrumentation/providers.mdx

@@ -0,0 +1,169 @@
+---
+title: "Instrumentation Providers"
+description: "Configure experimental instrumentation providers, handle lifecycle events, and control the content each provider receives."
+url: "/observability/instrumentation-providers"
+---
+
+<Callout type="warning" title="Experimental">
+  This API is experimental and may change without a deprecation period.
+</Callout>
+
+Instrumentation providers split observability into files under `agent/instrumentation/`. Each provider handles eve lifecycle events without owning the rest of the telemetry pipeline. Configure OpenTelemetry destinations with the [built-in OpenTelemetry APIs](./otel).
+
+Enable it explicitly in `agent.ts`:
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+
+export default defineAgent({
+  model: "anthropic/claude-sonnet-5",
+  experimental: {
+    instrumentationProviders: true,
+  },
+});
+```
+
+The provider directory replaces `agent/instrumentation.ts`; the two layouts cannot be used together. See [Instrumentation](../observability/instrumentation) for the current single-file API.
+
+## Add a provider
+
+The filename identifies the provider slot. A lifecycle-event provider file
+must default-export `defineInstrumentation(...)` or `disableInstrumentation()`.
+See [OpenTelemetry](./otel) for the supported OTel declarations.
+
+```text
+agent/instrumentation/
+  audit.ts  lifecycle event provider
+```
+
+This provider records action timing and identity without receiving tool arguments or results:
+
+```ts title="agent/instrumentation/audit.ts"
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation({
+  events: {
+    "action.started": (event, ctx) => {
+      ctx.state.set({ name: event.name, startedAt: Date.now() });
+    },
+    "action.completed": (event, ctx) => {
+      const started = ctx.state.get() as { name: string; startedAt: number } | undefined;
+      if (started === undefined) return;
+
+      console.log({
+        action: started.name,
+        durationMs: Date.now() - started.startedAt,
+        outcome: event.outcome,
+      });
+    },
+  },
+});
+```
+
+`ctx.state` is JSON storage scoped to this provider and operation. It survives durable suspension and is released after the terminal event.
+
+## Control inputs and outputs
+
+Each provider has an independent `tracePolicy`. It decides whether the provider
+receives a trace and whether its events include input or output content.
+
+```ts title="agent/instrumentation/audit.ts"
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation({
+  tracePolicy: ({ audience, environment }) => ({
+    emit: true,
+    recordInputs: audience === "public" || environment === "development",
+    recordOutputs: audience === "public" || environment === "development",
+  }),
+  events: {
+    "model.call.started": (event) => {
+      console.log("input", event.input);
+    },
+    "model.call.completed": (event) => {
+      console.log("output", event.content);
+    },
+  },
+});
+```
+
+The function receives `agentName`, `channel`, `audience`, `mode`,
+`environment`, and `principalType`. `audience` is `"public"`, `"private"`, or
+`"unknown"`; `environment` is `"development"`, `"preview"`, or
+`"production"`.
+
+Without a policy, or when it returns `true`, eve sends the provider metadata
+for every trace. It includes input and output content in these cases:
+
+| Environment           | Audience               | Content            |
+| --------------------- | ---------------------- | ------------------ |
+| Development           | Any                    | Inputs and outputs |
+| Preview or production | `public`               | Inputs and outputs |
+| Preview or production | `private` or `unknown` | Metadata only      |
+
+Return `{ emit: false }` to not sample the trace for this provider. Return
+`{ emit: true, recordInputs, recordOutputs }` to choose the two content
+directions explicitly. Inputs include model prompts, tool arguments, channel
+input, and user responses. Outputs include model responses, tool results,
+requests for user input, provider metadata, and error details. Omitted content
+fields are unavailable to the handler.
+
+The channel assigns the audience once when it creates the session. It controls
+content capture, not access. Configure it in the [default eve HTTP
+channel](../channels/eve#audience) or a [custom
+channel](../channels/custom#conversation-audience).
+
+## Redact fields in a custom provider
+
+Lifecycle events are immutable snapshots. Copy the fields you need into a destination-specific payload and redact that copy before sending it:
+
+```ts title="agent/instrumentation/audit.ts"
+import { defineInstrumentation } from "eve/instrumentation";
+
+export default defineInstrumentation({
+  tracePolicy: () => ({
+    emit: true,
+    recordInputs: true,
+    recordOutputs: false,
+  }),
+  events: {
+    "action.started": async (event) => {
+      await sendAuditRecord({
+        id: event.idempotencyKey,
+        input: redactApiKey(event.input),
+        kind: event.kind,
+        name: event.name,
+      });
+    },
+  },
+});
+
+function redactApiKey(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+
+  const record = value as Record<string, unknown>;
+  return "apiKey" in record ? { ...record, apiKey: "[redacted]" } : record;
+}
+
+async function sendAuditRecord(record: unknown): Promise<void> {
+  // Send the sanitized record to your provider.
+  void record;
+}
+```
+
+Prefer `recordInputs: false` or `recordOutputs: false` when the destination does not need an entire content direction. Use field-level redaction only when the destination needs part of that content.
+
+## Lifecycle events
+
+Providers can handle session, channel delivery, turn, model attempt, model call, action, input request, and tool call events. Start and terminal events share an `idempotencyKey`, which can serve as a destination row ID.
+
+An ordinary tool emits both `action.*` and `tool.call.*` events. Use `action.*` for eve's durable dispatch lifecycle, including tools, skills, subagents, and remote agents. Use `tool.call.*` only when you need the AI SDK's in-process tool execution boundary.
+
+Handlers for different providers run concurrently and are failure-isolated. Do not depend on provider execution order. Use `flush` to drain buffered records and `shutdown` to release resources.
+
+## What to read next
+
+- [Instrumentation](../observability/instrumentation): configure the current single-file API
+- [OpenTelemetry](./otel): configure OTel destinations and managed exports.
+- [Local development](../guides/dev-tui): inspect local traces in the TUI
+- [Hooks](../guides/hooks): react to runtime events outside the instrumentation provider API

package/docs/guides/meta.json

@@ -4,7 +4,6 @@
     "deployment",
     "auth-and-route-protection",
     "instrumentation",
-    "instrumentation-providers",
     "hooks",
     "session-context",
     "dynamic-capabilities",

package/docs/guides/remote-agents.md

@@ -139,26 +139,22 @@ Identity forwarding does not make a persistent session private to one caller. Co
 
 Forwarding is explicit on both sides. The receiver names which forwarders it trusts with `eveChannel({ trustedForwarders })` (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); a receiver that refuses the forwarder — or has no `trustedForwarders` at all — rejects with a 403 and the dispatch fails.
 
-Remote tracing uses [W3C Trace Context](https://www.w3.org/TR/trace-context/). `traceparent` identifies the immediate HTTP parent, while eve's `eve=<caller-span-id>` vendor entry in `tracestate` preserves the dispatching caller when an intermediary advances `traceparent` to its own request span. The receiver uses the eve entry for the child's `agent.dispatch` link and the transport context for request correlation. Older senders and missing or malformed eve entries fall back to `traceparent`. Trace context is not an authorization grant: it cannot assert eve parent lineage, change `rootSessionId`, or remove the normal root-session token cap.
+## Trace propagation
 
-eve also carries the original `gen_ai.conversation.id` in `eve.conversation.id` baggage so you can find related traces across local and remote agents. This observability identifier does not require principal forwarding or shared execution lineage; it grants no session access and does not change trace-content policy. Session execution establishes this ID even without an instrumentation runtime. Only session-create requests with a callback may supply this baggage; top-level requests ignore it and establish their own conversation ID. Callback metadata is caller-supplied correlation, not verified identity.
-
-eve replaces configured `traceparent` and conversation baggage only when it has a framework value to send. It replaces its own `tracestate` entry while preserving other valid vendor entries; without a valid caller context, eve removes only its entry. Incoming baggage has an 8 KiB limit; the audience and conversation readers share whitespace, percent-decoding, and duplicate-key validation. Conversation IDs are limited to 1 KiB and exclude control characters and line separators. If adding an audience assertion or conversation ID would exceed 8 KiB, eve rejects the dispatch before sending a request instead of dropping the member. Reduce `remote.headers.baggage` to leave room for these framework values.
-
-In the [provider trace contract](./instrumentation#agent-trace-contract), each
-child activation starts a separate trace. The first activation uses the
-caller preserved in W3C `tracestate`, falling back to incoming `traceparent`,
-as an `agent.dispatch` span link rather than adopting the caller's trace ID.
-
-> ⚠️ **Upgrade both deployments before resuming persistent remote sessions.** A sender with continuation forwarding includes `forwardedPrincipal` on each authenticated follow-up. A receiver that supports forwarding only on session creation rejects that continuation with HTTP 400. eve does not retry without the field because that would run the follow-up as the transport service principal and silently change caller authority. The parent retains the child handle after this failure, so you can retry the same session after upgrading the receiver.
-
-A receiver on an eve version that predates all principal forwarding may instead drop the unknown field and run the session as your app's service identity; per-user connections there fail with `principal_required`. On remote requests where the dispatching turn has no auth, the field is omitted and the call proceeds on transport trust alone.
+Each remote turn starts a new trace. eve links the child trace to the
+dispatching turn and carries `gen_ai.conversation.id` so you can find the
+traces for one conversation. Trace context is observability metadata, not an
+authorization grant. See [OpenTelemetry](../observability/otel#trace-topology)
+for the trace topology.
 
 ## Preserving trace content
 
-With `forwardPrincipal: true`, a sampled trace carries its original audience and the maximum content the next hop may record. For example, `eve.audience=private;ceiling=i0o1` allows outputs but not inputs. eve sends this as [W3C Baggage](https://www.w3.org/TR/baggage/).
+With `forwardPrincipal: true`, a sampled remote dispatch forwards its original
+audience and the maximum input and output content the next hop may record. eve
+sends this policy as [W3C Baggage](https://www.w3.org/TR/baggage/).
 
-The receiver uses it only after `trustedForwarders` accepts the authenticated calling deployment:
+The receiving deployment uses the policy only after it trusts the calling
+deployment:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
@@ -171,13 +167,15 @@ export default eveChannel({
 });
 ```
 
-The request must also include a callback and a valid sampled `traceparent`. Those fields identify a remote call, but they do not establish trust. `trustedForwarders` is the authorization boundary.
-
-The receiver combines the incoming ceiling with its own trace policy. Each hop may narrow the result, but it cannot restore inputs or outputs removed earlier. The original audience stays the same across remote and local subagent hops. Public origins may include content by default. Private and unknown origins stay metadata-only in preview and production unless both deployments explicitly allow them; a receiver running in development still applies the development content default.
-
-The live delivery audience still matters. An unknown callback delivery, or one matching the origin, uses the session decision. A different explicit audience applies its own hard ceiling, so a private delivery stays redacted even when the trace began in public.
+The request must include a callback and a valid sampled `traceparent`.
+`trustedForwarders` is the authorization boundary. When the assertion is
+accepted, the receiver uses the forwarded audience instead of reclassifying
+the child session with its local channel.
 
-Missing, malformed, duplicate, unsampled, untrusted, and mixed-version assertions fall back to metadata-only tracing. Dropped traces use only the unsampled trace flag. The decision is fixed when the remote session starts and reused by continuations. Agent Runs shows Workflow content only when both inputs and outputs are allowed.
+The receiver combines the forwarded ceiling with its own trace policy. Each
+hop may narrow content capture, but cannot restore inputs or outputs removed by
+an earlier hop. Missing, malformed, unsampled, or untrusted assertions do not
+widen capture and use metadata-only tracing.
 
 ## How remote dispatch and callbacks work
 

package/docs/install-integrations.mdx

@@ -12,7 +12,7 @@ Run `eve add` from an eve agent project. This installs the integration's depende
 
 ```bash
 eve add extension/agent-browser
-eve add linear
+eve add channel/linear
 eve add instrumentation/braintrust
 eve add memory/file
 ```
@@ -25,9 +25,7 @@ If you do not know an item name yet, run `eve add` without an argument. Its help
 
 Extensions may create a mount under `agent/extensions/`. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation providers write `agent/instrumentation.ts`; because an agent has one instrumentation file, compose multiple exporters there by hand. Configure generated files and required environment variables before running your agent.
 
-Some integrations package several independently installable components. For example, `eve add linear` lets you choose the Linear Channel, Linear MCP, or both; both are selected by default. The specific `eve add channel/linear-agent` and `eve add connection/linear` commands remain available.
-
-When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the selected components' declared flows from the beginning.
+When an official item declares an interactive setup flow or flows, eve asks whether to run them after installation and runs multiple flows in declaration order. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later; it reruns the item's declared flows from the beginning.
 
 For example, `eve add memory/file` can provision its required storage through the same setup flow. After **Install and set up**, eve creates or reuses a dedicated private Vercel Blob store, connects production, preview, and development with namespaced credentials, pulls the environment, and offers to deploy. The review and setup transcript show the project, store, primary function region, environments, and possible Blob usage charges before provisioning.
 

package/docs/memory/custom-provider.md

@@ -175,7 +175,7 @@ turn recalls the same data again.
 - A throwing or invalid `recall["turn.started"]` fails the turn before the
   model call. No slot's recall results are committed. If the turn's
   `abortSignal` is already aborted, eve treats the error as cancellation and
-  continues with any queued steering replacement. An `AbortError` with an active
+  continues with any queued follow-up. An `AbortError` with an active
   signal still fails the turn.
 - A throwing `capture["compaction.requested"]` leaves history unchanged.
 - A throwing `recall["compaction.completed"]` fails an automatic turn. For

package/docs/patterns/multi-tenant-auth.md

@@ -91,7 +91,7 @@ eve to require the authenticated user from route auth, key the step-local token
 cache by that user, and pass the projected principal into `getToken`:
 
 ```ts title="agent/lib/tenant-connection-auth.ts"
-import type { ConnectionPrincipal, NonInteractiveAuthorizationDefinition } from "eve/connections";
+import type { ConnectionAuthProvider, ConnectionPrincipal } from "eve/connections";
 import { tenantCredentials, type TenantService } from "./tenant-credentials";
 
 function requireTenantPrincipal(principal: ConnectionPrincipal): {
@@ -107,9 +107,9 @@ function requireTenantPrincipal(principal: ConnectionPrincipal): {
   return { tenantId, userId: principal.id };
 }
 
-export function tenantBearerAuth(service: TenantService): NonInteractiveAuthorizationDefinition {
+export function tenantBearerAuth(service: TenantService): ConnectionAuthProvider {
   return {
-    principalType: "user",
+    credentialOwner: "user",
     async getToken({ principal }) {
       const { tenantId, userId } = requireTenantPrincipal(principal);
       const credential = await tenantCredentials.getBearer(tenantId, service, { userId });

package/docs/protocols/acp.md

@@ -15,7 +15,7 @@ Without a URL, the client starts one process from the eve application root. It s
 eve acp https://agent.example.com
 ```
 
-For a recognized Vercel deployment, eve verifies the exact origin and resolves a short-lived project-scoped OIDC token from the local Vercel session. If login or a Trusted Sources change is required, run `eve dev <url>` and complete `/vc:login` before launching ACP. `VERCEL_AUTOMATION_BYPASS_SECRET` remains available for deployments configured with a Protection Bypass for Automation token.
+For a recognized Vercel deployment, eve verifies the exact origin and resolves a short-lived project-scoped OIDC token from the local Vercel session. Remote access requires an existing authorized Vercel session; account login runs during local deployment. Configure required Trusted Sources access in the target project before launching ACP. `VERCEL_AUTOMATION_BYPASS_SECRET` remains available for deployments configured with a Protection Bypass for Automation token.
 
 ## Configure Zed