eve 0.61.0 → 0.62.0

package/docs/guides/evaluate.md

@@ -151,6 +151,10 @@ You can also call `evaluate` outside a tool; it does not require an active eve
 session. Each call performs its own evaluation. `auto` uses this function
 and adds the per-turn routing behavior described below.
 
+## Judge eval results
+
+Eval authors can use `t.judge(...)` to turn evaluation answers into scored assertions, including batches of questions sharing one state. It uses this same `evaluate` implementation and default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
+
 ## Evaluate tool approvals
 
 Use `auto({ model? })` when an evaluation model should decide whether a

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 [Add runtime context](../observability/instrumentation#add-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 [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
 
 ## Hook structure and context
 

package/docs/guides/instrumentation/{providers.mdx → instrumentation.mdx}

@@ -1,42 +1,30 @@
 ---
-title: "Instrumentation Providers"
-description: "Configure experimental instrumentation providers, handle lifecycle events, and control the content each provider receives."
-url: "/observability/instrumentation-providers"
+title: "Instrumentation"
+description: "Configure lifecycle instrumentation, handle runtime events, and control the content each destination receives."
+url: "/observability/instrumentation"
 ---
 
-<Callout type="warning" title="Experimental">
-  This API is experimental and may change without a deprecation period.
-</Callout>
+Add lifecycle instrumentation as files under `agent/instrumentation/`. Each
+file handles eve runtime events independently. Configure trace exporters and
+shared span settings with the [built-in OpenTelemetry APIs](./otel).
 
-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).
+The instrumentation directory replaces `agent/instrumentation.ts`. See
+[Migrate instrumentation](/docs/observability/instrumentation-migration) when
+upgrading from `eve < 0.62.0`.
 
-Enable it explicitly in `agent.ts`:
+## Add instrumentation
 
-```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()`.
+The filename identifies the instrumentation slot. A lifecycle-event file must
+default-export `defineInstrumentation(...)` or `disableInstrumentation()`.
 See [OpenTelemetry](./otel) for the supported OTel declarations.
 
 ```text
 agent/instrumentation/
-  audit.ts  lifecycle event provider
+  audit.ts  lifecycle instrumentation
 ```
 
-This provider records action timing and identity without receiving tool arguments or results:
+This instrumentation records action timing and identity without receiving tool
+arguments or results:
 
 ```ts title="agent/instrumentation/audit.ts"
 import { defineInstrumentation } from "eve/instrumentation";
@@ -60,12 +48,15 @@ export default defineInstrumentation({
 });
 ```
 
-`ctx.state` is JSON storage scoped to this provider and operation. It survives durable suspension and is released after the terminal event.
+`ctx.state` is JSON storage scoped to this file 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.
+Each lifecycle file created with `defineInstrumentation(...)` has an
+independent `tracePolicy`. It decides whether that file receives a trace and
+whether its events include input or output content. OpenTelemetry destinations
+share the process-wide policy declared by `otel(...)`.
 
 ```ts title="agent/instrumentation/audit.ts"
 import { defineInstrumentation } from "eve/instrumentation";
@@ -92,8 +83,8 @@ The function receives `agentName`, `channel`, `audience`, `mode`,
 `"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:
+Without a policy, or when it returns `true`, eve sends metadata for every
+trace. It includes input and output content in these cases:
 
 | Environment           | Audience               | Content            |
 | --------------------- | ---------------------- | ------------------ |
@@ -101,20 +92,21 @@ for every trace. It includes input and output content in these cases:
 | 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
+Return `{ emit: false }` to not sample the trace for this file. 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.
+requests for user input, model 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. See [Audience](../channels/overview#audience) for
 how the channel derives `public`, `private`, and `unknown`.
 
-## Redact fields in a custom provider
+## Redact fields
 
-Lifecycle events are immutable snapshots. Copy the fields you need into a destination-specific payload and redact that copy before sending it:
+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";
@@ -145,7 +137,7 @@ function redactApiKey(value: unknown): unknown {
 }
 
 async function sendAuditRecord(record: unknown): Promise<void> {
-  // Send the sanitized record to your provider.
+  // Send the sanitized record to your destination.
   void record;
 }
 ```
@@ -154,15 +146,19 @@ Prefer `recordInputs: false` or `recordOutputs: false` when the destination does
 
 ## 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.
+Instrumentation 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.
+Handlers from different files run concurrently and are failure-isolated. Do
+not depend on 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.
+- [Migrate instrumentation](/docs/observability/instrumentation-migration): replace `agent/instrumentation.ts`.
+- [OpenTelemetry](/docs/observability/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
+- [Hooks](../guides/hooks): react to runtime events outside the instrumentation lifecycle

package/docs/guides/instrumentation/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Observability",
   "defaultOpen": false,
-  "pages": ["overview", "providers", "otel"]
+  "pages": ["instrumentation", "otel", "migration"]
 }

package/docs/guides/instrumentation/migration.md

@@ -0,0 +1,97 @@
+---
+title: "Migrate Instrumentation"
+description: "Move a single instrumentation.ts configuration into lifecycle instrumentation and OpenTelemetry destinations."
+url: "/observability/instrumentation-migration"
+---
+
+Replace `agent/instrumentation.ts` with path-named files under
+`agent/instrumentation/`. Remove
+`experimental.instrumentationProviders` from `agent.ts`; instrumentation
+discovery is now always enabled.
+
+## Preserve metadata-only capture
+
+In the removed API, omitted `recordInputs` and `recordOutputs` settings both
+defaulted to `false`. Once an OpenTelemetry destination is present, the new
+default includes content during development and for public conversations.
+
+Add `agent/instrumentation/otel.ts` with an explicit metadata-only policy
+before moving exporters:
+
+```ts title="agent/instrumentation/otel.ts"
+import { otel } from "eve/instrumentation/otel";
+
+export default otel({
+  functionId: "support-agent",
+  traceChannelRequests: true,
+  tracePolicy: () => ({
+    emit: true,
+    recordInputs: false,
+    recordOutputs: false,
+  }),
+});
+```
+
+After verifying each destination's retention and access controls, widen
+`recordInputs` or `recordOutputs` deliberately if needed.
+
+## Move an OpenTelemetry exporter
+
+Move each exporter into its own destination file and replace startup
+`registerOTel(...)` calls with `otelIntegration(...)`. Install `@vercel/otel`
+if the exporter comes from that package:
+
+```bash
+pnpm add @vercel/otel
+```
+
+```ts title="agent/instrumentation/honeycomb.ts"
+import { OTLPHttpProtoTraceExporter } from "@vercel/otel";
+import { otelIntegration } from "eve/instrumentation/otel";
+
+export default otelIntegration({
+  exportPolicy: {
+    span: () => ({ redact: true, inputs: true, outputs: true }),
+  },
+  traceExporter: new OTLPHttpProtoTraceExporter({
+    url: "https://api.honeycomb.io/v1/traces",
+    headers: {
+      "x-honeycomb-team": process.env.HONEYCOMB_API_KEY!,
+    },
+  }),
+});
+```
+
+The destination policy preserves metadata-only export even if the shared
+OpenTelemetry policy is widened later. Add another file for each additional
+destination; eve combines them into one pipeline.
+
+## Move runtime context and lifecycle events
+
+Use this mapping when splitting the old definition:
+
+| `agent/instrumentation.ts` field | New location                                 |
+| -------------------------------- | -------------------------------------------- |
+| `setup` with `registerOTel`      | One `otelIntegration()` file per destination |
+| `functionId`                     | `otel({ functionId })`                       |
+| `recordInputs`, `recordOutputs`  | `otel({ tracePolicy })`                      |
+| `traceChannelRequests`           | `otel({ traceChannelRequests })`             |
+| `events["step.started"]`         | `otelIntegration({ runtimeContext })`        |
+
+Move `events["step.started"]` to the destination that needs those attributes;
+see [Add runtime context](/docs/observability/otel#add-runtime-context). For
+eve lifecycle events, create a separate file with `defineInstrumentation(...)`;
+see
+[Instrumentation](/docs/observability/instrumentation).
+
+## Verify the migration
+
+Run `eve build`. A remaining `agent/instrumentation.ts` fails the build with a
+message directing you to the instrumentation directory.
+
+Before verifying a Vercel deployment, configure trace sampling. A deployed eve
+project needs at least one sampling rule with a rate above 0%; we recommend
+setting the rate to 100%. See
+[Enable tracing on Vercel](/docs/observability/otel#enable-tracing-on-vercel).
+
+Then run the agent and verify each destination independently.

package/docs/guides/instrumentation/otel.mdx

@@ -1,25 +1,22 @@
 ---
 title: "OpenTelemetry"
-description: "Configure OpenTelemetry destinations, content capture, and managed exports with Instrumentation Providers."
+description: "Configure OpenTelemetry destinations, content capture, and managed exports."
 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.
+eve configures its built-in OpenTelemetry destinations automatically.
+`eve dev` records local traces, and preview and production deployments export
+to Vercel Agent Runs by default. You do not need `otel()` or
+`otelIntegration()` to use these defaults.
 
 ## Configure OpenTelemetry
 
-OpenTelemetry configuration has two parts:
+`otel()` and `otelIntegration()` are optional:
 
-- `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.
+- Use `otel()` only when you need process-wide settings such as the resource,
+  sampler, propagators, or trace capture policy. Declare it at most once.
+- Use `otelIntegration()` only when adding a third-party OpenTelemetry
+  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:
@@ -39,26 +36,67 @@ export default otel({
 
 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()`.
+does not affect lifecycle instrumentation created with `defineInstrumentation()`.
 See [Audience](../channels/overview#audience) for how channels classify the
 conversation passed to this policy.
 
 ## Add an OpenTelemetry destination
 
-Most agents only need a destination:
+Use this section when sending traces to a third-party destination. Install
+`@vercel/otel` before using its exporters:
+
+```bash
+pnpm add @vercel/otel
+```
 
-```ts title="agent/instrumentation/braintrust.ts"
-import { BraintrustExporter } from "@braintrust/otel";
+```ts title="agent/instrumentation/honeycomb.ts"
+import { OTLPHttpProtoTraceExporter } from "@vercel/otel";
 import { otelIntegration } from "eve/instrumentation/otel";
 
 export default otelIntegration({
-  traceExporter: new BraintrustExporter({ filterAISpans: true }),
+  exportPolicy: {
+    span: () => ({ redact: true, inputs: true, outputs: true }),
+  },
+  traceExporter: new OTLPHttpProtoTraceExporter({
+    url: "https://api.honeycomb.io/v1/traces",
+    headers: {
+      "x-honeycomb-team": process.env.HONEYCOMB_API_KEY!,
+    },
+  }),
 });
 ```
 
 Pass `spanProcessors` to `otelIntegration()` when a custom destination needs
-filtering or transformation. `exportPolicy` is for the built-in
-`localTraces()` and `agentRuns()` destinations below.
+filtering or transformation. The example's `exportPolicy` preserves span
+metadata while removing inputs and outputs from this destination.
+
+## Add runtime context
+
+Use `runtimeContext` to add JSON values to AI SDK spans for each model attempt.
+For typed channel metadata, import the channel definition and narrow with
+`isChannel`:
+
+```ts title="agent/instrumentation/support.ts"
+import { isChannel } from "eve/instrumentation";
+import { otelIntegration } from "eve/instrumentation/otel";
+
+import supportChannel from "../channels/support";
+
+export default otelIntegration({
+  runtimeContext(input) {
+    if (!isChannel(input.channel, supportChannel)) return undefined;
+
+    return {
+      "support.channel_id": input.channel.metadata.channelId ?? "",
+      "support.user_id": input.channel.metadata.triggeringUserId ?? "",
+    };
+  },
+});
+```
+
+The resolver receives the channel, session, final model input, step, and turn.
+Keys beginning with `eve.` are reserved. Content excluded by
+`otel({ tracePolicy })` is not available to the resolver.
 
 ## Trace topology
 
@@ -82,15 +120,13 @@ destination's span-search surface.
 
 ## Manage built-in destinations
 
-The provider layout has two environment-specific defaults:
+Instrumentation has two environment-specific defaults.
 
-- `local` records local traces during `eve dev`.
-- `agent-runs` exports to Vercel Agent Runs in preview and production
-  deployments.
+### Local traces
 
-Omitting these files preserves the defaults. Reconfigure a destination by
-exporting `localTraces()` or `agentRuns()` from the matching file. Disable one
-explicitly:
+`eve dev` records local traces by default. Omitting
+`agent/instrumentation/local.ts` preserves that default. Export
+`localTraces(...)` from that file to reconfigure it, or disable it explicitly:
 
 ```ts title="agent/instrumentation/local.ts"
 import { disableInstrumentation } from "eve/instrumentation";
@@ -98,11 +134,37 @@ import { disableInstrumentation } from "eve/instrumentation";
 export default disableInstrumentation();
 ```
 
-## Filter a managed destination
+### Vercel Agent Runs
+
+Preview and production deployments export to Vercel Agent Runs by default.
+Omitting `agent/instrumentation/agent-runs.ts` preserves that default. Export
+`agentRuns(...)` from that file to reconfigure it, or export
+`disableInstrumentation()` to disable it.
+
+## Enable tracing on Vercel
+
+A deployed eve project needs at least one
+[sampling rule with a rate above 0%](https://vercel.com/docs/tracing/always-on-tracing#enable-always-on-tracing)
+before Vercel collects traces. We recommend setting the rate to **100%** for
+eve projects so every matching request is traced.
+
+Select your team and project, then open
+[**Settings → Tracing**](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Ftracing&title=Go+to+Tracing+settings):
+
+1. Select **Add Sampling Rule**.
+2. Choose **All Environments**, **Production**, or **Preview**.
+3. Set **Rate** to `100%`.
+4. Select **Save**.
+
+Tracing starts as soon as you save the rule. You can also manage sampling
+rules with [`vercel traces config`](https://vercel.com/docs/cli/traces#manage-trace-sampling-rules).
+The CLI accepts rates from 1 to 100%; add a 0% rule from the dashboard.
+
+## Filter a destination
 
-`localTraces()` and `agentRuns()` accept one `exportPolicy` object or an array
-applied in order. Each policy filters spans and attributes before that
-destination's processors receive them:
+`otelIntegration()`, `localTraces()`, and `agentRuns()` accept one
+`exportPolicy` object or an array applied in order. Each policy filters spans
+and attributes before that destination's processors receive them:
 
 ```ts title="agent/instrumentation/agent-runs.ts"
 import { agentRuns } from "eve/instrumentation/otel";
@@ -153,6 +215,6 @@ before it.
 
 ## What to read next
 
-- [Instrumentation Providers](./instrumentation-providers): add lifecycle-event providers.
-- [Instrumentation](../observability/instrumentation): configure the current single-file API.
+- [Instrumentation](/docs/observability/instrumentation): handle eve lifecycle events.
+- [Migrate instrumentation](/docs/observability/instrumentation-migration): replace `agent/instrumentation.ts`.
 - [Local development](../guides/dev-tui): inspect local traces in the TUI.

package/docs/install-integrations.mdx

@@ -23,7 +23,7 @@ Web Chat installs a project-level Next.js application. It cannot be added to an
 
 If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search <query>`.
 
-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.
+Extensions may create a mount under `agent/extensions/`. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation integrations write one destination file under `agent/instrumentation/`, so you can install and configure multiple exporters independently. Configure generated files and required environment variables before running your agent.
 
 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.
 

package/docs/reference/agent-files.md

@@ -13,7 +13,7 @@ In a single-agent project, the agent directory is `agent/`. In an eve agent work
 agent/
 ├── agent.ts
 ├── instructions.md
-├── instrumentation.ts
+├── instrumentation/
 ├── channels/
 ├── connections/
 ├── extensions/
@@ -50,7 +50,7 @@ Paths below are relative to the agent directory. Root agents can use every path;
 | ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `agent.ts`                                              | Runtime config                            | Yes                    | Model, model options, compaction, build, and experimental settings. See [Agents](/docs/agent-config).                                   |
 | `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Yes                    | A flat file or directory of `.md` and `.ts` files. Required on the root, optional on subagents. See [Instructions](/docs/instructions). |
-| `instrumentation.ts`                                    | Telemetry config                          | No                     | Auto-discovered and run before agent code. See [Instrumentation](/docs/observability/instrumentation).                                  |
+| `instrumentation/`                                      | Telemetry providers and destinations      | No                     | One path-named provider per file. See [Instrumentation](/docs/observability/instrumentation).                                           |
 | `channels/`                                             | HTTP and messaging entry points           | No                     | See [Channels](/docs/channels/overview).                                                                                                |
 | `connections/`                                          | External MCP and OpenAPI services         | Yes                    | Static files define path-named connections; dynamic sources can resolve caller-specific connections.                                    |
 | `extensions/`                                           | Mounted reusable capabilities             | Yes                    | File or directory mounts. See [Extensions](/docs/extensions).                                                                           |

package/docs/reference/cli.md

@@ -272,7 +272,7 @@ Local dev records the last ready URL per resolved app root in `.eve/dev-server-s
 
 Local dev keeps immutable runtime generations under `.eve/dev-runtime/snapshots/` so in-flight turns hold a consistent code revision while new turns pick up rebuilds. Each generation contains the compiled authored module graph and runtime resources rather than a recursive copy of the app or workspace. The terminal REPL keeps its logical session across successful rebuilds, so the next turn continues the conversation on the latest generation; `/new` terminally retires that session before clearing the transcript, and the next prompt starts a fresh session with a new session-scoped sandbox on first sandbox use. After a generation is superseded, `eve dev` retains it for at least 30 minutes and also retains the five most recently superseded generations, regardless of the configured Workflow World. The active generation is never pruned. Old runtime snapshots and local sandbox templates are pruned in the background. For manual cleanup, stop `eve dev` before deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`. A turn that remains unfinished beyond the automatic retention window can no longer resume after its generation is pruned.
 
-When no authored `agent/instrumentation.ts` exists, local dev also records traces under `.eve/traces/`, and bounds that store by age, size, and a keep-newest floor. Configure it with `EVE_TRACES*` in `.env.local`; see [`eve traces`](#retention) for the rules and defaults.
+Local development records traces under `.eve/traces/` by default and bounds that store by age, size, and a keep-newest floor. Configure it with `EVE_TRACES*` in `.env.local`, or disable the destination with `agent/instrumentation/local.ts`; see [`eve traces`](#retention) for the rules and defaults.
 
 ## `eve logs`
 

package/docs/reference/typescript-api.md

@@ -49,7 +49,8 @@ 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](../observability/instrumentation)    |
+| `defineInstrumentation`                               | `eve/instrumentation`                                                   | `agent/instrumentation/<name>.ts`                                                      | [Instrumentation](../observability/instrumentation)    |
+| `otel`, `otelIntegration`                             | `eve/instrumentation/otel`                                              | `agent/instrumentation/<destination>.ts`                                               | [OpenTelemetry](../observability/otel)                 |
 | `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)                             |
@@ -108,7 +109,7 @@ import template from "../../prompts/template.txt?raw";
 | `ctx.getToken(provider)`    | Resolve a bearer token for an inline auth provider such as `connect("...")`  |
 | `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` |
 
-Tool definitions accept `availableInSubagents: false` to restrict the tool to top-level root sessions. Authored workflow tools also receive `ctx.agents`, a replay-stable map of callable-agent metadata, and `ctx.agent(name, input)` for invocation. The root-copy `agent` entry has an empty description when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
+Tool definitions accept `availableInSubagents: false` to restrict the tool to top-level root sessions. Authored workflow bodies also receive `ctx.agents`, a replay-stable map of callable-agent metadata, and `ctx.agent(name, input)` for invocation. A `"use step"` helper that receives the context directly should type it as `WorkflowStepToolContext`, which excludes `agents`, `agent`, and `ask`. The root-copy `agent` entry has an empty description when the root omits `description`. See [Workflows as tools](../tools/workflows#delegate-work-ctxagent) for the workflow-only context.
 
 ## Imports at a glance
 
@@ -136,7 +137,8 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
 | `eve/memory/file/vercel`                                                    | `vercelBlob` and Vercel Blob backend options                                                                                   |
 | `eve/context`                                                               | `defineState`, session and state types                                                                                         |
 | `eve/sandbox`                                                               | `defineSandbox`, backends                                                                                                      |
-| `eve/instrumentation`                                                       | `defineInstrumentation`, `isChannel`                                                                                           |
+| `eve/instrumentation`                                                       | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types                                       |
+| `eve/instrumentation/otel`                                                  | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types                                              |
 | `eve/local-dev`                                                             | `getLocalDevCapability`, `LocalDevCapability`                                                                                  |
 | [`eve/models`](../guides/evaluate)                                          | Automatic model selection with `auto`                                                                                          |
 | `eve/models/openai`                                                         | `openai`, `chatgpt`, deprecated `experimental_chatgpt`                                                                         |

package/docs/tools/workflows.mdx

@@ -79,14 +79,16 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
   `start`, `getRun`, and `resumeHook` from `workflow/api` belong in steps. Your app does not install
   the SDK; for types, new projects list `eve/workflow-modules` in the tsconfig `types`.
 - In the body, `ctx` has `session`, `callId`, `toolName`, `abortSignal`, `agent`, `agents`, and `ask`.
-  `getToken` and `requireAuth` work inside a `"use step"` helper that receives `ctx` as a direct argument;
-  they throw in the workflow body. `getSandbox` and `getSkill` remain unavailable.
+  A `"use step"` helper that receives `ctx` directly gets a restricted `WorkflowStepToolContext` with
+  `session`, `callId`, `toolName`, `abortSignal`, `getToken`, and `requireAuth`. Read `ctx.agents`, call
+  `ctx.agent()`, and call `ctx.ask()` in the workflow body; pass only the serializable values the step needs.
+  `getSandbox` and `getSkill` remain unavailable.
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
   not tools returned from `defineDynamic` resolvers.
 
-`ctx.agent`, `ctx.agents`, and `ctx.ask` are available only on `WorkflowToolContext`. Ordinary tools, channel
-handlers, and schedule handlers do not receive these methods. A shared helper may accept
-`WorkflowToolContext` from `eve/tools` and use the context supplied by a workflow tool body.
+`ctx.agent`, `ctx.agents`, and `ctx.ask` are available only on `WorkflowToolContext` in the workflow body.
+Ordinary tools, channel handlers, schedule handlers, and workflow steps do not receive these methods. Type
+step helpers with `WorkflowStepToolContext` from `eve/tools` when they need step-safe context capabilities.
 
 Workflow executors require `defineWorkflowTool`. Adding `"use workflow"` to `defineTool`, a bare
 tool object, a channel handler, or a schedule handler fails the build. To start a session from a
@@ -217,9 +219,9 @@ The provider declaration and the API request both stay inside the step:
 
 ```ts
 import { connect } from "@vercel/connect/eve";
-import type { WorkflowToolContext } from "eve/tools";
+import type { WorkflowStepToolContext } from "eve/tools";
 
-async function readRepository(ctx: WorkflowToolContext, repository: string) {
+async function readRepository(ctx: WorkflowStepToolContext, repository: string) {
   "use step";
   const provider = connect("github/my-agent");
   const { token } = await ctx.getToken(provider);
@@ -360,23 +362,24 @@ Define the model-visible router under `agent/tools/`. Build the JEV criteria fro
 
 ```ts title="agent/tools/agent-router.ts"
 import { evaluate } from "eve/ai";
-import { defineWorkflowTool, type WorkflowToolContext } from "eve/tools";
+import { defineWorkflowTool } from "eve/tools";
 import { z } from "zod";
 
-async function chooseTarget(task: string, ctx: WorkflowToolContext) {
+async function chooseTarget(
+  task: string,
+  criteria: Record<"researcher" | "operator", string>,
+  abortSignal: AbortSignal,
+) {
   "use step";
 
   const result = await evaluate({
-    abortSignal: ctx.abortSignal,
+    abortSignal,
     state: { task },
     questions: {
       route: {
         type: "choice",
         instructions: "Which specialist should handle this task?",
-        criteria: {
-          researcher: ctx.agents.researcher.description,
-          operator: ctx.agents.operator.description,
-        },
+        criteria,
       },
     },
   });
@@ -390,7 +393,14 @@ export default defineWorkflowTool({
   async execute({ task }, ctx) {
     "use workflow";
 
-    const target = await chooseTarget(task, ctx);
+    const target = await chooseTarget(
+      task,
+      {
+        researcher: ctx.agents.researcher.description,
+        operator: ctx.agents.operator.description,
+      },
+      ctx.abortSignal,
+    );
 
     return ctx.agent(target, { message: task });
   },
@@ -411,7 +421,9 @@ import { agentRouter } from "eve/tools/agent-router";
 export default agentRouter();
 ```
 
-Its input is `{ message: string, outputSchema?: object }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to JEV, then invokes the selected name through `ctx.agent()`. It invokes a sole target without evaluation and forwards an optional `outputSchema`. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
+Its input is `{ message: string, outputSchema?: object }`. `agentRouter()` ignores entries without a non-empty description. With two or more described targets, it sends the message and effective descriptions to JEV, then invokes the selected name through `ctx.agent()`. It invokes a sole target without evaluation and forwards an optional `outputSchema` unchanged. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
+
+When an authored tool accepts a JSON Schema supplied by the model, represent that input with a permissive object such as `z.looseObject({})`. Avoid `z.record(z.string(), z.json())`: its generated JSON Schema uses `propertyNames`, which OpenAI does not support. Validate the supplied value at the point where your tool consumes it.
 
 This pattern controls specialist selection, not whether the parent model delegates at all. Route before the parent model runs if every incoming request must go through JEV.