eve 0.71.3 → 0.72.1

package/docs/concepts/built-in-tools.md

@@ -208,6 +208,18 @@ import { webSearch } from "eve/tools/web_search";
 export default webSearch({ provider: "parallel" });
 ```
 
+Select Browserbase Search in the same slot:
+
+```ts title="agent/tools/web_search.ts"
+import { webSearch } from "eve/tools/web_search";
+
+export default webSearch({ provider: "browserbase" });
+```
+
+Use a [Gateway model ID](../agent-config#set-the-model) to route searches through Browserbase. AI Gateway executes the search using `AI_GATEWAY_API_KEY` or Vercel project OIDC credentials; no `BROWSERBASE_API_KEY` is needed. See [Browserbase Search on AI Gateway](https://vercel.com/docs/ai-gateway/models-and-providers/web-search#using-browserbase-search).
+
+The `provider` setting applies only to AI Gateway models. Unsupported direct providers omit `web_search`.
+
 Replace provider-managed search with an authored implementation:
 
 ```ts title="agent/tools/web_search.ts"
@@ -286,9 +298,9 @@ export default disableTool();
 
 `connection_search` and `connection_execute` give the model every tool from the agent's [connections](../connections) without adding each tool to the model's tool list. eve adds both when the agent has a static connection or a dynamic connection resolver, even when `defaultTools` is `false`, so there is no add command.
 
-- `connection_search({ query?, connection?, signIn?, limit?, offset? })` returns matching tools with their connection, name, description, and a TypeScript signature rendered from the tool's schemas. Omit `query` to list every tool, or pair it with `connection` to list one connection's tools. A plain search never asks the user to sign in. For a connection the user has not signed in to, the result tells the model that sign-in is needed before its tools can be listed: the connection appears under `unavailable` with `requiresSignIn: true` and an error that points to `signIn: true`. Tools from the other connections are still returned.
+- `connection_search({ query?, connection?, signIn?, limit?, offset? })` returns matching tools with their connection, name, description, and a TypeScript signature rendered from the tool's schemas. Omit `query` to list every tool, or pair it with `connection` to list one connection's tools. A plain search never asks the user to sign in. For a connection whose server will not list its tools until the user signs in, the result tells the model that sign-in is needed: the connection appears under `unavailable` with `requiresSignIn: true` and an error that points to `signIn: true`. Tools from the other connections are still returned.
 - `connection_search({ connection, signIn: true, query? })` asks the user to sign in to that one connection when they have not yet, then returns its matching tools. Without `connection` it fails, so the user is asked about one service at a time.
-- `connection_execute({ connection, tool, input })` checks `input` against the tool's input schema, calls the tool, and returns its result. When the connection needs the user's authorization, it also asks the user to sign in and the call parks until sign-in completes. The stream reports the call as a nested action named `<connection>__<tool>`, such as `linear__list_issues`, whose `parentCallId` is the `connection_execute` call id.
+- `connection_execute({ connection, tool, input })` checks `input` against the tool's input schema, calls the tool, and returns its result. When the server asks for the user's authorization, it also asks the user to sign in and the call parks until sign-in completes. The stream reports the call as a nested action named `<connection>__<tool>`, such as `linear__list_issues`, whose `parentCallId` is the `connection_execute` call id.
 
 The definitions of both tools never change during a session. eve lists connection names and descriptions in append-only context messages rather than in the system prompt, so finding a tool, signing in, or resolving a dynamic connection keeps the cached prompt prefix.
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -127,11 +127,11 @@ A question or sign-in from inside a running call does not end the turn. This cov
 
 ### Task events
 
-A call to a tool that runs as a task, such as an agent tool, `agentRouter()`, the `workflow` tool, or a workflow tool that defines [`task(input, ctx)`](/docs/tools/workflows#run-calls-as-tasks-task) or [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve), returns a receipt as its `action.result` and keeps working. `task.started` reports the task's `taskId` for the call's `callId` and `turnId`, both when a call starts a task and when a call reaches a resumable task by its `taskId`, before any event the task's run publishes for that call. `task.settled` comes once per call, with the same `turnId`, `name`, and `kind` as its `task.started`, `status` `"completed"`, `"failed"`, or `"cancelled"`, and the call's `output` when it completed or `error.message` when it failed. Events recorded by earlier eve versions omit `name` and `kind` on `task.settled`, so match them to their `task.started` by `callId` when those fields are missing. Results reach the model as a message in its history, not as a stream event, so read outcomes from `task.settled`. A session the task's run opens with `ctx.agent` is announced with `agent.started` carrying the `taskId`. An `input.requested`, `authorization.required`, or `authorization.completed` event from a task's run carries its `taskId`. Each of these events names the call the task is serving when it happens: a resumable task's later call brings its own `callId` and `turnId`, which may belong to a later turn than the call that started the task.
+A call to a tool that runs as a task, such as an agent tool, `agentRouter()`, the `workflow` tool, or a workflow tool that defines [`task(input, ctx)`](/docs/tools/workflows#run-calls-as-tasks-task) or [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve), returns a receipt as its `action.result` and keeps working. `task.started` reports the task's `taskId` for the call's `callId` and `turnId`, both when a call starts a task and when a call reaches a resumable task by its `taskId`, before any event the task's run publishes for that call. `task.settled` comes once per call, with the same `turnId`, `name`, and `kind` as its `task.started`, `status` `"completed"`, `"failed"`, or `"cancelled"`, and the call's `output` when it completed or `error.message` when it failed. Events recorded by earlier eve versions omit `name` and `kind` on `task.settled`, so match them to their `task.started` by `callId` when those fields are missing. Results reach the model as a message in its history, not as a stream event, so read outcomes from `task.settled`. A session the task's run opens with `ctx.agent` is announced with `agent.started` carrying the `taskId`. An `input.requested`, `authorization.required`, or `authorization.completed` event from a task's run carries its `taskId`. Each of these events names the call the task is serving when it happens: a resumable task's later call brings its own `callId` and `turnId`, which may belong to a later turn than the call that started the task. An `input.requested` relayed from a subagent or a workflow tool run also carries `callId`, the call in this session that the request serves. The request keeps the coordinates it was raised with, and a relayed approval's `request.action.callId` still names the asking run's call, not one of this session's.
 
 A turn doesn't end while tasks are working. When the model ends its text early, eve holds the turn and the stream emits `turn.waiting` for it; the turn continues once a result arrives or its caller writes. In a root session, that text completes as an ordinary `message.completed`. In a child session or a schedule's session, it reports `finishReason: "tool-calls"`, so channels post only the final reply. When the model calls `task_wait` and no result is ready yet, the stream also emits `turn.waiting`. Either way, the next `step.started` for the same `turnId` means the turn resumed, and `session.waiting` comes only after the turn ends. See [Tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
 
-`step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, and discards incomplete assistant output. Tool calls the cancellation stopped stay in history, each answered as cancelled, so the model sees that the work started and stopped instead of a request left unanswered. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`). Both carry `data.principalId` when a session principal started the sign-in. It holds the same value as `responderPrincipalId` on approval events, so a channel can deliver the challenge privately to that person even after someone else starts a later turn.
+`step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally. Whatever the turn streamed before cancellation stays on the stream. Durable history keeps the accepted user input and previously settled work, and discards incomplete assistant output. Tool calls the cancellation stopped stay in history, each answered as cancelled, so the model sees that the work started and stopped instead of a request left unanswered. Before `turn.cancelled`, the stream reports requests the cancel strands as `cancelled` in `input.resolved`. These include the turn's own questions, the session-limit prompt, and requests relayed from the work it stops. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`). Both carry `data.principalId` when a session principal started the sign-in. It holds the same value as `responderPrincipalId` on approval events, so a channel can deliver the challenge privately to that person even after someone else starts a later turn.
 
 A provider response ending with `content-filter` fails with `MODEL_CALL_FAILED`,
 `details.semanticErrorId: "model-response-content-filtered"`, and
@@ -261,7 +261,7 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
 
 Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. Attributed [memory](../memory) records are excluded from the summary, canonicalized, and recalled again after the checkpoint. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails before a checkpoint, the session returns to waiting with its previous history.
 
-Clear removes model-message history in place, including static and dynamic user-role instructions and recalled memory records, while preserving the session identity, system-role instructions, tools, skills, application-defined durable state, limits, and sandbox. It clears framework memory locks and replay bookkeeping but does not delete data from a provider's external store. It does not rerun instruction definitions or resolvers. It emits `context.cleared` followed by `session.waiting`.
+Clear removes model-message history in place, including static and dynamic user-role instructions and recalled memory records, while preserving the session identity, system-role instructions, tools, skills, application-defined durable state, limits, and sandbox. It clears framework memory locks and replay bookkeeping but does not delete data from a provider's external store. It does not rerun instruction definitions or resolvers. Approvals, the session-limit prompt, and sign-ins the cleared history asked for are withdrawn: each resolves as `cancelled` in `input.resolved` or `declined` in `authorization.completed`. Requests relayed from tasks that keep running stay answerable. It then emits `context.cleared` followed by `session.waiting`.
 
 Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
 

package/docs/connections/mcp.mdx

@@ -44,6 +44,17 @@ For OAuth-backed MCP servers, use the shared [Vercel Connect flow](../connection
 
 `connect("...")` is user-scoped by default and requires an authenticated user on the active eve session. Use `connect({ connector, principalType: "app" })` when the server should act as the agent instead. The connections overview covers connector setup, session requirements, app and user scope, callback behavior, and troubleshooting.
 
+## When eve asks for sign-in
+
+eve asks the user to sign in only when the MCP server asks for it. When a connection has `auth` but no token yet, because its `getToken` throws `ConnectionAuthorizationRequiredError`, eve connects without an `Authorization` header and lists the server's tools. Any other error from `getToken` still fails the connection.
+
+- **The server rejects every request without a token.** Most hosted OAuth servers, such as Linear, GitHub, and Notion, answer `initialize` or `tools/list` with HTTP `401`. A plain `connection_search` lists the connection under `unavailable` with `requiresSignIn: true`. Calling `connection_search({ connection, signIn: true })` or any of its tools with `connection_execute` asks the user to sign in.
+- **The server lists tools without a token.** `connection_search` returns its tools with no prompt, and `connection_execute` runs tools the server answers anonymously. Sign-in starts only when a tool call comes back with HTTP `401`, or with an error result that carries a `WWW-Authenticate` challenge in `_meta["mcp/www_authenticate"]`.
+
+After the user signs in, the call that asked for it runs again. eve reconnects with the token and reloads the tool list, which may now include tools the server hides from anonymous callers. A connection that already has a token sends it on every request, as before.
+
+A server that leaves protected tools out of its anonymous `tools/list` never triggers sign-in, because the model cannot find those tools. Servers that support anonymous use should list every tool and refuse the protected calls.
+
 ## Static tokens and headers
 
 MCP connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.

package/docs/connections/overview.mdx

@@ -194,7 +194,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-`never()` lets every call through, `once()` asks for approval the first time in a session, `always()` asks every time, and `auto()` uses an evaluation model to allow routine calls and ask about dangerous or unclear effects. The pause and resume is the same human-in-the-loop flow covered in [Tools](/docs/tools).
+`never()` lets every call through, `once()` asks for approval the first time in a session, `always()` asks every time, and `auto()` uses a decision model to allow routine calls and ask about dangerous or unclear effects. The pause and resume is the same human-in-the-loop flow covered in [Tools](/docs/tools).
 
 For connection tools that can create, modify, delete, transmit, purchase, message, or access sensitive data, use approval, allow-lists, or other safeguards appropriate to the action.
 
@@ -227,7 +227,7 @@ export default defineMcpClientConnection({
 
 Use the connector UID returned by `vercel connect create`; the display name passed to `--name` is not the UID. `connect("linear/myagent")` is shorthand for a user-scoped interactive OAuth connection: eve resolves a token for the active user before each tool call, emits `authorization.required` when that user has not authorized yet, and resumes the parked turn after the callback completes.
 
-Discovering tools never posts a sign-in prompt for a service the answer does not need. A plain `connection_search` lists connections the user has not authorized yet under `unavailable` with `requiresSignIn: true`. Most OAuth MCP servers reject even tool listing without the user's token, so the model asks for sign-in explicitly, one connection at a time, with `connection_search({ connection, signIn: true })`, which returns that connection's tools once the user signs in. Calling a tool with `connection_execute` on a connection the user has not authorized also asks for sign-in.
+Discovering tools never posts a sign-in prompt for a service the answer does not need. Before the user signs in, eve connects to an MCP server without a token, so a server that lists its tools anonymously is searched like any other connection, and sign-in starts only when one of its tools asks for it (see [When eve asks for sign-in](/docs/connections/mcp#when-eve-asks-for-sign-in)). Most OAuth MCP servers reject even tool listing without the user's token. A plain `connection_search` lists those connections under `unavailable` with `requiresSignIn: true`, and the model asks for sign-in explicitly, one connection at a time, with `connection_search({ connection, signIn: true })`, which returns that connection's tools once the user signs in. Calling a tool with `connection_execute` on such a connection also asks for sign-in.
 
 A sign-in holds the turn open until the user connects, the turn is cancelled, or the user sends another message. That message steers the turn: eve cancels the sign-in, reports `authorization.completed` with `outcome: "declined"`, and the model reads the message next. Messages from other people in a shared thread wait until the turn ends, and the completed sign-in resumes the turn as the person who started it.
 

package/docs/dynamic-configuration/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Dynamic Capabilities",
   "defaultOpen": false,
-  "pages": ["../guides/dynamic-capabilities", "../guides/evaluate"]
+  "pages": ["../guides/dynamic-capabilities", "../guides/decide"]
 }

package/docs/evals/judge.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Judge"
-description: "Grade evals with evaluation models using criteria, typed questions, or batches, and set thresholds on each assertion."
+description: "Grade evals with decision models using criteria, typed questions, or batches, and set thresholds on each assertion."
 ---
 
-Use `t.judge(...)` when a deterministic [assertion](./assertions) cannot capture what a good response looks like. It calls [`evaluate` from `eve/ai`](../guides/evaluate#evaluate-inside-a-tool) and defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev evaluation model](https://vercel.com/i/what-is-jev). The judge is separate from the agent under test and is used only for scoring.
+Use `t.judge(...)` when a deterministic [assertion](./assertions) cannot capture what a good response looks like. It calls [`decide` from `eve/ai`](../guides/decide#decide-inside-a-tool) and defaults to `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). The judge is separate from the agent under test and is used only for scoring.
 
 ```ts
 import { defineEval } from "eve/evals";
@@ -17,7 +17,7 @@ export default defineEval({
 });
 ```
 
-No judge configuration is required. Configure credentials for the evaluator as described under [Configuring the judge model](#configuring-the-judge-model).
+No judge configuration is required. Configure credentials for the decider as described under [Configuring the judge model](#configuring-the-judge-model).
 
 ## The graders
 
@@ -41,11 +41,11 @@ t.judge({
   .atLeast(0.75);
 ```
 
-Choice questions require an `expected` option key. eve uses that expectation locally for scoring; it does not send it to the evaluator. Instructions and rubric descriptions accept strings, JSON objects, or JSON arrays. Descriptions can also be `null`.
+Choice questions require an `expected` option key. eve uses that expectation locally for scoring; it does not send it to the decider. Instructions and rubric descriptions accept strings, JSON objects, or JSON arrays. Descriptions can also be `null`.
 
 ## Choose the value to grade
 
-By default, the evaluator receives `{ input, output }`: the latest prompt and assistant message from the session whose turn most recently settled. Approval responses and stream reads preserve that prompt. For multipart messages, including `session.sendFile()`, the prompt contains the text parts.
+By default, the decider receives `{ input, output }`: the latest prompt and assistant message from the session whose turn most recently settled. Approval responses and stream reads preserve that prompt. For multipart messages, including `session.sendFile()`, the prompt contains the text parts.
 
 Pass `on` to replace the output. JSON values stay structured rather than being converted to strings:
 
@@ -66,9 +66,9 @@ t.judge("The assistant remembers the user's favorite word across turns.", {
 
 The transcript contains user and assistant messages in turn order, excluding reasoning, tool calls, and tool results. See [Multi-turn evals](./cases#multi-turn-evals).
 
-## Evaluate several questions together
+## Decide several questions together
 
-A batch makes one evaluation request against one shared state. Pass `state` to replace the default `{ input, output }` completely. Batch calls use `state` instead of `on`.
+A batch makes one decision request against one shared state. Pass `state` to replace the default `{ input, output }` completely. Batch calls use `state` instead of `on`.
 
 ```ts
 const judgments = t.judge({
@@ -120,9 +120,9 @@ Model settings resolve in this order:
 1. Per-call: `t.judge("…", { model, modelOptions })`.
 2. Per-eval: `defineEval({ judge: { model, modelOptions }, test })`.
 3. Project default: `defineEvalConfig({ judge: { model, modelOptions } })`.
-4. The default model used by `evaluate`, currently `typesafe-ai/jev`.
+4. The default model used by `decide`, currently `typesafe-ai/jev`.
 
-A per-eval `judge` replaces the project's judge configuration. Per-call fields override the resolved configuration. `judge` and its `model` are optional; deterministic evals make no evaluation requests.
+A per-eval `judge` replaces the project's judge configuration. Per-call fields override the resolved configuration. `judge` and its `model` are optional; deterministic evals make no decision requests.
 
 ```ts title="evals/evals.config.ts"
 import { defineEvalConfig } from "eve/evals";
@@ -132,30 +132,30 @@ export default defineEvalConfig({
 });
 ```
 
-String IDs resolve through the AI SDK default provider, or Vercel AI Gateway when none is configured. Gateway uses `AI_GATEWAY_API_KEY` or Vercel OIDC credentials; eve's existing local Gateway connection is also honored by `evaluate`. An explicit provider evaluation model uses that provider's credentials:
+String IDs resolve through the AI SDK default provider, or Vercel AI Gateway when none is configured. Gateway uses `AI_GATEWAY_API_KEY` or Vercel OIDC credentials; eve's existing local Gateway connection is also honored by `decide`. An explicit provider decision model uses that provider's credentials:
 
 ```ts
 import { openai } from "@ai-sdk/openai";
 
 t.judge("The response addresses the request.", {
-  model: openai.evaluationModel("gpt-6-luna"),
+  model: openai.decisionModel("gpt-6-luna"),
   modelOptions: { providerOptions: { openai: { reasoningEffort: "high" } } },
 });
 ```
 
-Use the provider's `evaluationModel` factory, not a language model instance. AI SDK supplies evaluation adapters for supported language models. Provider support and the evaluation contract are experimental; see [AI SDK evaluation](https://ai-sdk.dev/docs/ai-sdk-core/evaluation).
+Use the provider's `decisionModel` factory, not a language model instance. AI SDK supplies decision adapters for supported language models. Provider support and the decision contract are experimental; see [AI SDK decision](https://ai-sdk.dev/docs/ai-sdk-core/decisions).
 
-String model IDs resolve through the default provider's evaluation API. Gateway accepts native evaluation models such as `typesafe-ai/jev`; passing a language model ID such as `openai/gpt-6-luna` does not automatically select the OpenAI adapter. Use an evaluation-model instance as shown above for language models.
+String model IDs resolve through the default provider's decision API. Gateway accepts native decision models such as `typesafe-ai/jev`; passing a language model ID such as `openai/gpt-6-luna` does not automatically select the OpenAI adapter. Use a decision-model instance as shown above for language models.
 
-Missing credentials, invalid answers, unsupported question types, and provider errors become failed gates even for tracked-only judgments. They do not silently skip the eval or select another model. Validation, authentication, and retries use the shared `evaluate` implementation.
+Missing credentials, invalid answers, unsupported question types, and provider errors become failed gates even for tracked-only judgments. They do not silently skip the eval or select another model. Validation, authentication, and retries use the shared `decide` implementation.
 
 ## Diagnostics and migration
 
-Reports use `judge.boolean`, `judge.score`, and `judge.choice`; batch assertion names also include their question key. Diagnostics include the captured state, question, and raw answer. Assertion metadata retains the normalized score, model identity, token usage, warnings, and available provider and response metadata. Usage for a batch is marked as shared across its assertions, not a separate charge for each question. Evaluation models do not promise a prose rationale.
+Reports use `judge.boolean`, `judge.score`, and `judge.choice`; batch assertion names also include their question key. Diagnostics include the captured state, question, and raw answer. Assertion metadata retains the normalized score, model identity, token usage, warnings, and available provider and response metadata. Usage for a batch is marked as shared across its assertions, not a separate charge for each question. Decision models do not promise a prose rationale.
 
 The autoevals graders have been removed. Replace `t.judge.autoevals.closedQA(criteria, options)` with `t.judge(criteria, options)`. Scores now represent a probability rather than a binary yes/no answer, so review thresholds against your examples. For factuality, summaries, or SQL equivalence, write an explicit question and include the reference in shared state. No old grader buckets are preserved.
 
-Change configured language model instances to evaluation model instances. `modelOptions.providerOptions`, assertion labels, and threshold methods remain available. [Braintrust reporting](./reporters) continues to accept judge scores independently of the grader implementation.
+Change configured language model instances to decision model instances. `modelOptions.providerOptions`, assertion labels, and threshold methods remain available. [Braintrust reporting](./reporters) continues to accept judge scores independently of the grader implementation.
 
 ## What to read next
 

package/docs/evals/overview.mdx

@@ -56,7 +56,7 @@ export default defineEvalConfig({
 });
 ```
 
-Everything is optional. `judge` sets the default model for [LLM-as-judge](./judge) assertions (`t.judge(...)`); omit it to use the default evaluator, `typesafe-ai/jev`. Deterministic evals make no judge requests. `reporters`, `maxConcurrency`, and `timeoutMs` round out the defaults. Config `reporters` observe every eval in the run, so set one `Braintrust()` here instead of adding it to each eval. CLI flags (`--max-concurrency`, `--timeout`) and per-eval values take precedence over the config defaults.
+Everything is optional. `judge` sets the default model for [LLM-as-judge](./judge) assertions (`t.judge(...)`); omit it to use the default decider, `typesafe-ai/jev`. Deterministic evals make no judge requests. `reporters`, `maxConcurrency`, and `timeoutMs` round out the defaults. Config `reporters` observe every eval in the run, so set one `Braintrust()` here instead of adding it to each eval. CLI flags (`--max-concurrency`, `--timeout`) and per-eval values take precedence over the config defaults.
 
 ### Run setup and teardown
 

package/docs/guides/{evaluate.md → decide.md}

@@ -1,21 +1,21 @@
 ---
 title: Automatic Model Selection
-description: "Choose agent models automatically or evaluate typed questions in your tools and application code."
+description: "Choose agent models automatically or ask typed questions in your tools and application code."
 ---
 
 Use `auto` from `eve/models` to choose an agent model from an allowlist before
-inference begins. It uses the [AI SDK evaluation API](https://ai-sdk.dev/docs/ai-sdk-core/evaluation),
-so the evaluator can be a Vercel AI Gateway model ID or an evaluation model from
-an installed provider. Use `evaluate` from `eve/ai` to ask typed questions in
+inference begins. It uses the [AI SDK decision API](https://ai-sdk.dev/docs/ai-sdk-core/decisions),
+so the decider can be a Vercel AI Gateway model ID or a decision model from
+an installed provider. Use `decide` from `eve/ai` to ask typed questions in
 your own tools or application code.
 
-The AI SDK evaluation model specification is experimental and can change in
+The AI SDK decision model specification is experimental and can change in
 patch releases.
 
 ## Choose from Gateway models
 
-By default, `auto` evaluates with `typesafe-ai/jev`, TypeSafe AI's
-[Jev evaluation model](https://vercel.com/i/what-is-jev). Like other AI SDK
+By default, `auto` decides with `typesafe-ai/jev`, TypeSafe AI's
+[Jev decision model](https://vercel.com/i/what-is-jev). Like other AI SDK
 model strings, it uses Vercel AI Gateway unless the application has configured a
 different global default provider.
 
@@ -35,13 +35,13 @@ export default defineAgent({
 
 Configure Gateway authentication as you would for any other AI SDK model. eve
 does not add a TypeSafe credential or transport layer. During `eve dev`, a
-Gateway evaluator uses the same connection selected through `/login` as Gateway
+Gateway decider uses the same connection selected through `/login` as Gateway
 language models. A configured AI SDK default provider still owns string model
 resolution during development. The TUI footer displays `dynamic model` when the
 agent uses `auto`, then adds the resolved model for the current turn, such as
 `dynamic model · openai/gpt-6-luna`.
 
-Set `fallback` to keep the turn running when the evaluator is unavailable or
+Set `fallback` to keep the turn running when the decider is unavailable or
 returns an error. The fallback can be a Gateway model ID, an AI SDK language
 model instance, or an object with `model` and a `reasoning` override:
 
@@ -60,15 +60,15 @@ export default defineAgent({
 });
 ```
 
-The fallback applies only to evaluator failures. eve logs a warning with the
-evaluator error and fallback identity when it switches models. Invalid prompts,
+The fallback applies only to decider failures. eve logs a warning with the
+decider error and fallback identity when it switches models. Invalid prompts,
 including requests without user text or with a latest message over the routing
-limit, still fail before evaluator I/O. Cancelling the turn also aborts routing
+limit, still fail before decider I/O. Cancelling the turn also aborts routing
 instead of selecting the fallback.
 
 ## Use a provider directly
 
-Install the provider package yourself and pass its evaluation model. The provider
+Install the provider package yourself and pass its decision model. The provider
 owns its credentials and settings.
 
 ```sh
@@ -82,7 +82,7 @@ import { auto } from "eve/models";
 
 export default defineAgent({
   model: auto({
-    model: typeSafeAi.evaluationModel("jev-latest"),
+    model: typeSafeAi.decisionModel("jev-latest"),
     options: {
       "openai/gpt-6-sol": "Difficult reasoning and engineering tasks",
       "openai/gpt-6-luna": "Routine tasks where fast completion matters",
@@ -91,12 +91,12 @@ export default defineAgent({
 });
 ```
 
-Any provider that implements the AI SDK `Experimental_EvaluationModel` contract
+Any provider that implements the AI SDK `Experimental_DecisionModel` contract
 works here.
 
 ## Route to provider models and set reasoning
 
-An option's key is the value shown to the evaluator. A string value describes a
+An option's key is the value shown to the decider. A string value describes a
 Gateway model whose ID is the key. Use the object form when the selected model is
 a provider instance, an alias, or needs a reasoning override.
 
@@ -120,7 +120,7 @@ export default defineAgent({
 });
 ```
 
-The evaluator sees option keys, descriptions, and recent text messages. It never
+The decider sees option keys, descriptions, and recent text messages. It never
 receives provider credentials or serialized language model instances. When it
 selects `my_secret_model`, eve resolves the key back to the authored Anthropic
 model.
@@ -129,16 +129,16 @@ Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`,
 `"low"`, `"medium"`, `"high"`, and `"xhigh"`. An omitted value inherits the
 agent's reasoning setting.
 
-## Evaluate inside a tool
+## Decide inside a tool
 
-Use `evaluate` to ask choice, score, or boolean questions about the state you pass to it.
+Use `decide` to ask choice, score, or boolean questions about the state you pass to it.
 It defaults to `typesafe-ai/jev` and uses the same authentication as `auto`,
 including the Gateway connection selected through `/login` during `eve dev`.
-Pass `model` to use another evaluation model ID or a provider instance. A configured
+Pass `model` to use another decision model ID or a provider instance. A configured
 AI SDK default provider takes precedence over the local Gateway connection.
 
 ```ts title="agent/tools/classify-request.ts"
-import { evaluate } from "eve/ai";
+import { decide } from "eve/ai";
 import { defineTool } from "eve/tools";
 import { z } from "zod";
 
@@ -146,7 +146,7 @@ export default defineTool({
   description: "Choose the team that can help with a customer request.",
   inputSchema: z.object({ request: z.string().min(1).max(8000) }),
   async execute({ request }, ctx) {
-    const result = await evaluate({
+    const result = await decide({
       state: { request },
       questions: {
         team: {
@@ -169,23 +169,23 @@ The choice above is typed as `"billing" | "support"`. Each question appears unde
 its authored key in `result.answers`. Results also include token usage, warnings,
 provider metadata, and response metadata. To use that choice to delegate while keeping specialist subagents out of the parent model's tools, see [Route to a hidden subagent with Jev](/docs/tools/workflows#route-to-a-hidden-subagent-with-jev).
 
-`evaluate` accepts AI SDK evaluation options, including `maxRetries`, `headers`,
+`decide` accepts AI SDK decision options, including `maxRetries`, `headers`,
 and `providerOptions`. Pass an `abortSignal` to cancel the request. Input and
 answer validation, retries, and provider errors follow AI SDK semantics.
 
-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
+You can also call `decide` outside a tool; it does not require an active eve
+session. Each call performs its own decision. `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.
+Eval authors can use `t.judge(...)` to turn decision answers into scored assertions, including batches of questions sharing one state. It uses this same `decide` implementation and default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
 
-## Evaluate tool approvals
+## Decide tool approvals
 
-Use `auto({ model? })` when an evaluation model should decide whether a
+Use `auto({ model? })` when a decision model should decide whether a
 tool call can run automatically or needs human approval. It accepts the same
-AI SDK evaluation model strings and provider instances described above and
+AI SDK decision model strings and provider instances described above and
 defaults to `typesafe-ai/jev`:
 
 ```ts title="agent/tools/deploy.ts"
@@ -201,7 +201,7 @@ export default defineTool({
 });
 ```
 
-The evaluation model reviews the tool name and input for dangerous effects. A
+The decision model reviews the tool name and input for dangerous effects. A
 caution, failed review, or incomplete input requires human approval. See
 [Human-in-the-loop approvals](/docs/human-in-the-loop#approvals) for classifier
 options and data handling, and the
@@ -210,17 +210,17 @@ guide for an end-to-end walkthrough.
 
 ## Runtime behavior
 
-`auto` evaluates at the first `step.started` event, after the incoming prompt
+`auto` decides at the first `step.started` event, after the incoming prompt
 is available and before the selected language model runs. It reuses that choice
 for later tool-loop steps in the same turn. A new turn makes a new choice, and
 child sessions route from their own prompts.
 
-The evaluator receives up to eight recent user and assistant text messages,
+The decider receives up to eight recent user and assistant text messages,
 capped at 16,000 characters. Requests without user text and latest messages over
 the limit fail before provider I/O.
 
-Evaluation validation, retries, provider errors, and model resolution follow AI
-SDK semantics. Without `fallback`, an evaluator error fails the turn. With
+Decision validation, retries, provider errors, and model resolution follow AI
+SDK semantics. Without `fallback`, a decider error fails the turn. With
 `fallback`, eve uses and retains that model for the rest of the turn. Cancelling
-the active turn aborts evaluation and prevents a routed or fallback choice from
+the active turn aborts decision and prevents a routed or fallback choice from
 being retained.

package/docs/guides/dynamic-capabilities.md

@@ -362,7 +362,7 @@ A dynamic connection, tool, or skill whose name matches an **authored** one **ov
 
 At `turn.started`, model, tool, skill, and subagent resolvers receive the visible conversation history and incoming message in `ctx.messages`, oldest first. Request context is included, and history projection still applies. Read these messages from the handler's second argument; the event itself contains turn metadata. Instruction resolvers use the separate snapshot described under [Dynamic instructions](#dynamic-instructions).
 
-A message that steers a held turn, or waits behind its session-limit prompt, joins that turn instead of starting one, as does a completed sign-in, so `turn.started` resolvers do not see it; `step.started` resolvers do. When memory recall runs, its results appear in the projected snapshot before incoming input.
+A message that steers a held turn joins it without another `turn.started`, as does a completed sign-in, so `turn.started` resolvers do not see it; `step.started` resolvers do. A message sent while a session-limit prompt waits starts its own turn, so `turn.started` resolvers see it, and that turn waits for the prompt's answer before the model runs. When memory recall runs, its results appear in the projected snapshot before incoming input.
 
 ### Execution order
 

package/docs/guides/frontend/overview.mdx

@@ -174,7 +174,9 @@ supplied `session` remains externally owned and is never replaced by prewarming
 
 Common text, reasoning, file, and dynamic-tool parts follow the [AI SDK `UIMessage`](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message) rendering convention, but the types are not interchangeable. eve also exposes authorization and HITL metadata, and a file part's URL can be absent. Adapt those parts before passing messages to an API typed as `UIMessage[]`.
 
-When the root agent delegates, its stream emits `task.started` for the call, `agent.started` with the child's `sessionId`, and `task.settled` with the call's result, failure, or cancellation. The default reducer settles the subagent's tool part from `task.settled`, so the part shows the call's outcome rather than its start receipt. `data.tasks[taskId].calls[callId]` records each call's `status`, `output`, and `error`, and `data.agents[sessionId]` records each session a call opened, with its `taskId` and opening `callId`. These records come from the root stream alone.
+A tool part's `state` comes from the shared lifecycle interpretation of the event stream. Its events supply input, output, and error text. A call waiting on an approval or a question reads `approval-requested` until the stream settles the request. An answer you submit doesn't change the part until then. `toolCallState(conversation, callId)` reads tool-call status, including task cancellation and calls interrupted without a result. The full event projection remains internal; `ConversationState` retains its messages, turns, inputs, tasks, and agent sessions.
+
+When the root agent delegates, its stream emits `task.started` for the call, `agent.started` with the child's `sessionId`, and `task.settled` with the call's result, failure, or cancellation. The default reducer keeps the subagent's tool part running until `task.settled` arrives and then settles it with the call's outcome; the start receipt never settles it. `data.tasks[taskId].calls[callId]` records each call's `status`, `output`, and `error`, and `data.agents[sessionId]` records each session a call opened, with its `taskId` and opening `callId`. These records come from the root stream alone.
 
 Detailed child progress lives on the child session's stream, not in the root `data.messages`. Pass `followSubagents: true` to follow the session each subagent call reaches while the component is mounted; following is off by default. Narrow `data.agents[sessionId].observation.status` before reading its `conversation`: `"not-followed"` has no child detail, `"following"` has live detail, and `"idle"` has everything the calls so far produced and resumes when another call reaches the task. `"unavailable"` means the stream failed, not that the child failed. Calls that continue a task with its `taskId` reach the same session, so one session's `conversation.messages`, `inputs`, and `turns` span all of them. Sessions that a custom task opens with `ctx.agent` are recorded but not followed.
 

package/docs/guides/hooks.md

@@ -227,7 +227,7 @@ The remaining subscribers for the event still run. Then eve cancels the turn the
 
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
 
-Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
+Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. A proxied `input.requested` also carries `event.data.callId`, the parent call that waits on it. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
 
 ## Hook vs tool vs provider
 

package/docs/guides/instrumentation/instrumentation.mdx

@@ -23,7 +23,7 @@ agent/instrumentation/
   audit.ts  lifecycle instrumentation
 ```
 
-This instrumentation records action timing and identity without receiving tool
+This instrumentation records tool timing and identity without receiving tool
 arguments or results:
 
 ```ts title="agent/instrumentation/audit.ts"
@@ -31,15 +31,15 @@ import { defineInstrumentation } from "eve/instrumentation";
 
 export default defineInstrumentation({
   events: {
-    "action.started": (event, ctx) => {
-      ctx.state.set({ name: event.name, startedAt: Date.now() });
+    "tool.call.started": (event, ctx) => {
+      ctx.state.set({ name: event.toolName, startedAt: Date.now() });
     },
-    "action.completed": (event, ctx) => {
+    "tool.call.completed": (event, ctx) => {
       const started = ctx.state.get() as { name: string; startedAt: number } | undefined;
       if (started === undefined) return;
 
       console.log({
-        action: started.name,
+        tool: started.name,
         durationMs: Date.now() - started.startedAt,
         outcome: event.outcome,
       });
@@ -123,12 +123,12 @@ export default defineInstrumentation({
     recordOutputs: false,
   }),
   events: {
-    "action.started": async (event) => {
+    "tool.call.started": async (event) => {
       await sendAuditRecord({
         id: event.idempotencyKey,
         input: redactApiKey(event.input),
         kind: event.kind,
-        name: event.name,
+        name: event.toolName,
       });
     },
   },
@@ -155,21 +155,22 @@ Prefer `recordInputs: false` or `recordOutputs: false` when the destination does
 start and its terminal event share an `idempotencyKey`; use it as a stable
 operation key when upserting records across replays.
 
-| Lifecycle        | Events                                                                                                            | Meaning                                                                                                                                                                          |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session          | `session.started`, `session.waiting`, `session.completed`, `session.failed`                                       | Track a session from creation through suspension or termination. `session.waiting` is resumable; `session.completed` and `session.failed` are terminal.                          |
-| Turn             | `turn.started`, `turn.completed`, `turn.cancelled`, `turn.failed`                                                 | Track one turn. Cancellation is not a failure and commonly leaves the session waiting for another turn.                                                                          |
-| Channel delivery | `channel.delivery.started`, `channel.delivery.completed`, `channel.delivery.cancelled`, `channel.delivery.failed` | Track an inbound channel delivery while eve processes its turn. These events are emitted when the channel provides delivery metadata.                                            |
-| Step attempt     | `step.attempt.started`, `step.attempt.completed`, `step.attempt.failed`, `step.attempt.metadata`                  | Track each model-step attempt; retries have separate attempts. `step.attempt.metadata` is emitted after a step only when the AI SDK supplies provider metadata.                  |
-| Model call       | `model.call.started`, `model.call.completed`, `model.call.failed`                                                 | Track an individual call to the model provider. Completion includes usage and finish reason; content fields follow the trace policy.                                             |
-| Action           | `action.started`, `action.completed`, `action.failed`                                                             | Track eve's durable dispatch of a tool, skill load, local subagent, or remote agent. A failed event's `outcome` distinguishes failure, rejection, cancellation, and abandonment. |
-| Tool call        | `tool.call.started`, `tool.call.completed`, `tool.call.failed`                                                    | Track the AI SDK's in-process tool execution boundary, including its input and result when allowed by the trace policy.                                                          |
-| User input       | `input.requested`, `input.resolved`                                                                               | Track a question, tool approval, or session-limit request and its resolution. The resolution includes an outcome such as `answered`, `approved`, `denied`, or `cancelled`.       |
-| Memory operation | `memory.operation.started`, `memory.operation.completed`, `memory.operation.failed`                               | Track a memory-store search or write. Events include the operation name, phase, and memory slot; completion may include a record count and records.                              |
-
-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.
-
-For local and remote subagents, `action.completed` and `action.failed` include the child turn's `usage` directly. Token counts are always present when the child reports usage; `usage.costUsd` is present only when the model provider reports a price. Without the action-level usage, consumers would have to correlate child model events through trace lineage and sum their provider metadata, which is harder to do reliably across retries and parked turns.
+| Lifecycle        | Events                                                                                                            | Meaning                                                                                                                                                                                |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session          | `session.started`, `session.waiting`, `session.completed`, `session.failed`                                       | Track a session from creation through suspension or termination. `session.waiting` is resumable; `session.completed` and `session.failed` are terminal.                                |
+| Turn             | `turn.started`, `turn.completed`, `turn.cancelled`, `turn.failed`                                                 | Track one turn. Cancellation is not a failure and commonly leaves the session waiting for another turn.                                                                                |
+| Channel delivery | `channel.delivery.started`, `channel.delivery.completed`, `channel.delivery.cancelled`, `channel.delivery.failed` | Track an inbound channel delivery while eve processes its turn. These events are emitted when the channel provides delivery metadata.                                                  |
+| Step attempt     | `step.attempt.started`, `step.attempt.completed`, `step.attempt.failed`, `step.attempt.metadata`                  | Track each model-step attempt; retries have separate attempts. `step.attempt.metadata` is emitted after a step only when the AI SDK supplies provider metadata.                        |
+| Model call       | `model.call.started`, `model.call.completed`, `model.call.failed`                                                 | Track an individual call to the model provider. Completion includes usage and finish reason; content fields follow the trace policy.                                                   |
+| Tool call        | `tool.call.started`, `tool.call.completed`, `tool.call.failed`                                                    | Track a tool, skill load, local subagent, or remote-agent call through durable settlement. A failed event's `outcome` distinguishes failure, rejection, cancellation, and abandonment. |
+| User input       | `input.requested`, `input.resolved`                                                                               | Track a question, tool approval, or session-limit request and its resolution. The resolution includes an outcome such as `answered`, `approved`, `denied`, or `cancelled`.             |
+| Memory operation | `memory.operation.started`, `memory.operation.completed`, `memory.operation.failed`                               | Track a memory-store search or write. Events include the operation name, phase, and memory slot; completion may include a record count and records.                                    |
+
+Each call emits one `tool.call.*` lifecycle to authored providers. SDK execution callbacks do not emit a second lifecycle. Tool calls can remain open across approvals, parked turns, and worker replacement.
+
+For local and remote subagents, `tool.call.completed` and `tool.call.failed` include the child turn's `usage` directly. Token counts are always present when the child reports usage; `usage.costUsd` is present only when the model provider reports a price.
+
+When upgrading, replace `action.started`, `action.completed`, and `action.failed` handlers with their `tool.call.*` equivalents. Read `event.toolName` instead of `event.name` on start events. The OpenTelemetry trace schema remains version 4.
 
 Handlers from different files run concurrently and are failure-isolated. Do
 not depend on execution order. Use `flush` to drain buffered records and

package/docs/guides/instrumentation/otel.mdx

@@ -126,6 +126,10 @@ 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.
 
+Authored values appear under `ai.settings.context.*`. Framework channel, session,
+step, turn, and version identifiers use structural span attributes instead of
+runtime-context copies. `ai.settings.context.eve.environment` remains available.
+
 ## Trace topology
 
 OpenTelemetry destinations receive the following trace topology for an ordinary
@@ -135,8 +139,7 @@ agent turn:
 invoke_agent <agent>
   └── agent.step
         ├── chat <model>
-        └── agent.action
-              └── execute_tool <tool>
+        └── execute_tool <tool>
 ```
 
 Each root agent turn starts a new trace. If eve receives a local caller's trace
@@ -146,6 +149,14 @@ context, the first subagent turn starts a new trace. Later turns in the child
 session start new traces. They do not use the original dispatch span as their
 parent.
 
+Use `gen_ai.tool.call.id` to correlate tool and approval spans. Tool failures use
+`error.type`. These attributes replace the duplicate `agent.action.call_id` and
+`agent.action.error.code` fields without changing trace schema version 4.
+
+Model and activation spans record token counts under `gen_ai.usage.*`, without
+duplicate `agent.usage.*` token fields. Step and tool spans retain `agent.usage.*`.
+Cost values remain unchanged.
+
 A remote child starts a separate trace with a root `invoke_agent` span. Its first
 turn links to the caller with `eve.link.type=agent.dispatch`. The receiving
 deployment applies its sampler. Queries for local dispatches must use