eve 0.55.0 → 0.56.0

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/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/reference/cli.md

@@ -123,7 +123,7 @@ Commands for installing and discovering [shadcn registry](https://ui.shadcn.com/
 
 ```bash
 eve add extension/agent-browser
-eve add linear
+eve add channel/linear
 eve add channel/slack --skip-install
 eve add https://example.com/r/my-extension.json --overwrite
 eve registry add @acme=https://example.com/r/{name}.json
@@ -134,11 +134,11 @@ eve registry view @acme/my-extension
 eve add @acme/my-extension
 ```
 
-`eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Product-level packages can offer independently installable components: `eve add linear` lets you select the Linear Channel, Linear MCP, or both, with both selected by default. Interactive Vercel-backed setup signs in and creates or links a project when needed instead of stopping with a prerequisite. `--yes` installs a package's default components and accepts detected or recommended setup answers.
+`eve add` asks before running setup declared by an official item and runs multiple declared flows in declaration order. Interactive Vercel-backed setup signs in and creates or links a project when needed instead of stopping with a prerequisite. `--yes` accepts detected or recommended setup answers.
 
-Coding agents should use `eve add <item> --non-interactive`, adding `--yes` to accept recommended setup values and reduce setup round trips. Explicit `--answer` values take precedence. This mode never opens an eve prompt. When a component or setup decision is missing, the NDJSON terminal event includes a stable question key and a safe continuation command; add the requested answer to that command. Supply answers with repeatable `--answer 'key=<JSON value>'` options. Follow a reported `eve link` prerequisite before retrying Vercel Connect setup. Do not put secrets in command-line answers; use the integration's documented environment variable or secret store.
+Coding agents should use `eve add <item> --non-interactive`, adding `--yes` to accept recommended setup values and reduce setup round trips. Explicit `--answer` values take precedence. This mode never opens an eve prompt. When a setup decision is missing, the NDJSON terminal event includes a stable question key and a safe continuation command; add the requested answer to that command. Supply answers with repeatable `--answer 'key=<JSON value>'` options. Follow a reported `eve link` prerequisite before retrying Vercel Connect setup. Do not put secrets in command-line answers; use the integration's documented environment variable or secret store.
 
-When setup is skipped, cancelled, or needs more input after installation, eve prints or returns the matching `eve add <item> --skip-install` continuation. It reruns the selected components' declared flows without reinstalling registry files.
+When setup is skipped, cancelled, or needs more input after installation, eve prints or returns the matching `eve add <item> --skip-install` continuation. It reruns the item's declared flows without reinstalling registry files.
 
 `eve registry add` records configured sources in `package.json#registries`. `eve registry list` aggregates the official catalog and all configured sources by default. `eve registry search` also includes [skills.sh](https://skills.sh), available without configuration at `@skills`, and groups results by source with each source's available result count. Search returns up to 10 matches per source by default; pass `--limit <count>` to request between 1 and 100. Either command can browse one supplied URL or namespace. Official and other universal items with explicit file targets do not require shadcn project configuration.
 
@@ -317,7 +317,7 @@ A durable conversation produces one bounded trace per turn. Worker replacements
 
 Every span carries a real duration. A turn's root `invoke_agent` span is written when the turn settles, so a running turn shows only its steps.
 
-Model, `execute_tool`, and memory spans omit their content by default. Set `EVE_TRACES_CONTENT=on` to capture system prompts, prompt messages, and response text for models; call arguments and results for tools; and recalled memory records. Each captured value is capped at 32 KB.
+Model, `execute_tool`, and memory spans retain their content by default. Set `EVE_TRACES_CONTENT=off` to omit system prompts, prompt messages, and response text for models; call arguments and results for tools; and recalled memory records. Each captured value is capped at 32 KB.
 
 Step spans carry token counts under `agent.usage.*`, and cost when Vercel AI Gateway served the call. Model spans also expose `gen_ai.usage.*` token counters. The CLI sums step-level counters only, so model and delegated-call totals are not counted twice.
 
@@ -325,13 +325,13 @@ Step spans carry token counts under `agent.usage.*`, and cost when Vercel AI Gat
 
 eve sweeps the store when an activation's writes finish, when a session finishes, and when the dev server starts. An open conversation does not pin every completed turn's trace. Sweeps evict oldest-first past the bounds below, except that active traces, the newest traces, and anything written in the last five minutes are kept. A sweep can therefore exceed the size budget. Set the bounds in `.env.local`, which `eve dev` loads automatically; each accepts `off` to disable it individually.
 
-| Variable                     | Default              | Effect                                                                                              |
-| ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------- |
-| `EVE_TRACES`                 | on                   | `off` stops writing traces and stops sweeping                                                       |
-| `EVE_TRACES_CONTENT`         | off                  | `on` captures model prompt/response, tool input/output, and memory-record attributes on local spans |
-| `EVE_TRACES_MAX_AGE_MS`      | `604800000` (7d)     | Age after which a trace may be evicted                                                              |
-| `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store                                                                     |
-| `EVE_TRACES_RETAIN_COUNT`    | `20`                 | Newest traces kept regardless of age or size                                                        |
+| Variable                     | Default              | Effect                                                                                            |
+| ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
+| `EVE_TRACES`                 | on                   | `off` stops writing traces and stops sweeping                                                     |
+| `EVE_TRACES_CONTENT`         | on                   | `off` omits model prompt/response, tool input/output, and memory-record attributes on local spans |
+| `EVE_TRACES_MAX_AGE_MS`      | `604800000` (7d)     | Age after which a trace may be evicted                                                            |
+| `EVE_TRACES_MAX_TOTAL_BYTES` | `536870912` (512 MB) | Size budget for the whole store                                                                   |
+| `EVE_TRACES_RETAIN_COUNT`    | `20`                 | Newest traces kept regardless of age or size                                                      |
 
 ## `eve link`
 
@@ -399,10 +399,10 @@ Lists the user-authored channels in the current project.
 4. `eve build` before shipping.
 5. `eve start` to smoke-test the built output locally.
 
-Related: [Project layout](../getting-started#project-layout) · [instrumentation.ts](../guides/instrumentation).
+Related: [Project layout](../getting-started#project-layout) · [Instrumentation](../observability/instrumentation).
 
 ## What to read next
 
 - [Project layout](../getting-started#project-layout): what `eve info` discovers
-- [instrumentation.ts](../guides/instrumentation): tracing and the error catalog
+- [Instrumentation](../observability/instrumentation): tracing and the error catalog
 - [Deployment](../guides/deployment/overview): `eve build` and `eve start` in production

package/docs/reference/typescript-api.md

@@ -48,16 +48,16 @@ export default defineTool({
 | `defineSchedule`                                      | `eve/schedules`                                                         | `agent/schedules/<name>.ts`                                                            | [Schedules](../schedules)                              |
 | `defineState`                                         | `eve/context`                                                           | tools, hooks, lifecycle                                                                | [Session context](../guides/session-context)           |
 | `defineSandbox`                                       | `eve/sandbox`                                                           | `agent/sandbox.ts`                                                                     | [Sandbox](../sandbox)                                  |
-| `defineInstrumentation`                               | `eve/instrumentation`                                                   | `agent/instrumentation.ts`                                                             | [instrumentation.ts](../guides/instrumentation)        |
+| `defineInstrumentation`                               | `eve/instrumentation`                                                   | `agent/instrumentation.ts`                                                             | [Instrumentation](../observability/instrumentation)    |
 | `defineRemoteAgent`                                   | `eve`                                                                   | `agent/subagents/<id>/agent.ts`                                                        | [Remote agents](../guides/remote-agents)               |
 | `defineEval`                                          | `eve/evals`                                                             | `evals/*.eval.ts`                                                                      | [Evals](../evals/overview)                             |
 | `defineEvalConfig`                                    | `eve/evals`                                                             | `evals/evals.config.ts`                                                                | [Evals](../evals/overview)                             |
 | `mockModel`                                           | `eve/evals`                                                             | Deterministic fixture agent models                                                     | [Evals](../evals/overview)                             |
 | `useEveAgent`                                         | `eve/react`, `eve/vue`, `eve/svelte`                                    | frontend                                                                               | [Frontend](../guides/frontend/overview)                |
 
-Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `experimental_workflow` comes from `eve/tools/workflow`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
+Tool-wide authoring helpers and types such as `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDynamic`, `disableTool`, and `ToolLabelDefinition` come from `eve/tools`. Capability-specific definitions and helpers use their own subpaths (see [Built-in tools](../concepts/built-in-tools)): reusable definitions such as `bash` and `glob` come from `eve/tools/<name>`, `webSearch` comes from `eve/tools/web_search`, `sleep` comes from `eve/tools/sleep`, and approval policies and types come from `eve/tools/approval`. The route verbs `GET`/`HEAD`/`POST`/`PUT`/`PATCH`/`DELETE`/`OPTIONS`/`WS` plus `disableRoute` come from `eve/channels`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` come from `eve/channels/auth`.
 
-`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `ExperimentalWorkflowToolInput` is exported from `eve/tools/workflow`; `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
+`AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentLimitsDefinition` is exported for `defineAgent({ limits })`. `AgentWorkflowDefinition`, `AgentWorkflowRetentionDefinition`, and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape. `WebSearchToolInput` and `WebSearchProvider` are exported from `eve/tools/web_search`.
 
 `defineInstructions` accepts `{ content: string, role?: "system" | "user" }`; omitted `role` means `"system"`. Its `eve/instructions` version of `defineDynamic` accepts only `session.started` and `turn.started` handlers returning `defineInstructions(...)` or `null`. The legacy `{ markdown: string }` definition remains available as a deprecated system-role form.
 
@@ -74,11 +74,11 @@ cross resolved instances.
 
 eve evaluates TypeScript definition modules during compilation so it can validate and normalize the agent. Within one agent node, each module namespace loads at most once during that compile. The resolved definition then determines whether the module is also an entry in the runtime bundle:
 
-| Lifecycle           | Authored definitions                                                                                                                                                                                                                            |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Compile only        | Static instructions and skills, prompt-form TypeScript schedules, static Gateway or default agent config, provider-managed web search, `Workflow` configuration, fully shadowed channels, and a child sandbox that selects its parent's sandbox |
-| Compile and runtime | Dynamic instructions, skills, tools, models, and subagents; executable tools; effective channels; connections; hooks; memory; handler schedules; direct-provider models; independent sandboxes; and remote subagents                            |
-| Runtime only        | Instrumentation modules and extension mount initialization                                                                                                                                                                                      |
+| Lifecycle           | Authored definitions                                                                                                                                                                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Compile only        | Static instructions and skills, prompt-form TypeScript schedules, static Gateway or default agent config, provider-managed web search, Workflow SDK configuration, fully shadowed channels, and a child sandbox that selects its parent's sandbox |
+| Compile and runtime | Dynamic instructions, skills, tools, models, and subagents; executable tools; effective channels; connections; hooks; memory; handler schedules; direct-provider models; independent sandboxes; and remote subagents                              |
+| Runtime only        | Instrumentation modules and extension mount initialization                                                                                                                                                                                        |
 
 A compile-only module is not imported when the deployed runtime starts. For example, eve stores the resolved content from a static `instructions.ts` in the compiled manifest. A compile-and-runtime module is evaluated during compilation and imported again when a runtime process loads the module map. Keep module-top-level work deterministic, and put request- or session-specific work in the definition's runtime callbacks.
 
@@ -116,7 +116,7 @@ import template from "../../prompts/template.txt?raw";
 | `eve/tools/{bash,read_file,write_file,todo,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions                                                                    |
 | `eve/tools/approval`                                                        | Approval types and `always`, `once`, `never`                                                            |
 | `eve/tools/web_search`                                                      | Provider-managed `webSearch` configuration                                                              |
-| `eve/tools/workflow`                                                        | Experimental `Workflow` tool definition                                                                 |
+| `eve/tools/workflow`                                                        | Runtime-generated `workflow` tool factory                                                               |
 | `eve/tools/sleep`                                                           | Opt-in durable `sleep` tool                                                                             |
 | `eve/connections`                                                           | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic`                                 |
 | `eve/channels`                                                              | `defineChannel`, `disableRoute`, route verbs                                                            |

package/docs/subagents/index.mdx

@@ -32,7 +32,7 @@ The root session receives `agent` by default. The model calls it to delegate a t
 }
 ```
 
-The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent` and `Workflow`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` always runs in the background and needs no configuration: each call returns `{ status: "working", taskId, agentId }`, then task notifications wake the parent with completion, failure, or cancellation. Give parallel children non-overlapping write scopes.
+The copy uses the root's instructions, connections, auth, and sandbox. It receives the same tools except for the root-only `agent`, and starts with fresh conversation history and fresh state. Its file writes are immediately visible to the root. The built-in `agent` always runs in the background and needs no configuration: each call returns `{ status: "working", taskId, agentId }`, then task notifications wake the parent with completion, failure, or cancellation. Give parallel children non-overlapping write scopes.
 
 `agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
 
@@ -199,7 +199,7 @@ eve lowers every subagent visible to the current agent (the root built-in copy,
 
 Declared subagents can call nested subagents defined under their own directories. eve does not apply a separate depth limit; nesting ends where the authored directory tree ends. The built-in `agent` follows the stricter root-only rule above, so `limits.maxSubagentDepth` no longer exists.
 
-Child sessions can still call their own declared or remote subagents, but they receive neither `Workflow` nor the built-in `agent`. Background subagents run through the model tool loop and are not available inside a model-authored `Workflow` program.
+Child sessions can still call their own declared or remote subagents, but they do not receive the built-in `agent`. Authored workflow tools use the same subagent availability and authorization checks as direct delegation.
 
 A directly declared subagent's tool name is the bare path-derived name, with no prefix. `agent/subagents/researcher/` registers as the tool `researcher`. A subagent supplied by a mounted extension includes the mount namespace, such as `crm__reviewer`. The model, approvals, logs, and evals reference the resulting name. Its input schema is: