eve 0.14.0 → 0.15.0

package/docs/agent-config.md

@@ -96,11 +96,21 @@ export default defineAgent({
 ```
 
 Install that package in your app. It should export a default factory or
-`createWorld()` function.
+`createWorld()` function. Pin a version built against the same `@workflow/*`
+line as your eve release (currently the `5.0.0-beta` line):
+
+```bash
+pnpm add @workflow/world-postgres@5.0.0-beta.x
+```
+
+The npm `latest` tag can lag behind that line, so an unpinned install may pull
+an incompatible major that fails with `ZodError: invalid_union` at run replay.
 
 Put credentials and host-specific options in runtime environment variables read
-by the world package, not in `agent.ts`. If the installed package must stay
-external in hosted output, list it in `build.externalDependencies`.
+by the world package, not in `agent.ts`. For the Postgres world, that means
+putting the connection string or credentials in the env vars it reads. If the
+installed package must stay external in hosted output, list it in
+`build.externalDependencies`.
 
 ## Other defineAgent fields
 

package/docs/concepts/execution-model-and-durability.md

@@ -36,7 +36,7 @@ export default defineAgent({
 });
 ```
 
-The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. See [agent.ts](../agent-config#workflow-world) and [Workflow Worlds](https://workflow-sdk.dev/worlds).
+The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. The selected world must match eve's bundled `@workflow/*` line (currently the `5.0.0-beta` line); pin it explicitly, since a mismatched world fails with a `ZodError: invalid_union` during run replay. See the [deployment guide](../guides/deployment#8-deploy-without-vercel) for the install command, plus [agent.ts](../agent-config#workflow-world) and [Workflow Worlds](https://workflow-sdk.dev/worlds).
 
 ## Resuming after a crash
 

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

@@ -40,7 +40,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | `turn.started`            | A new turn began.                                                                                                |
 | `message.received`        | An inbound user message was accepted.                                                                            |
 | `step.started`            | A model step began.                                                                                              |
-| `actions.requested`       | The model requested tool calls.                                                                                  |
+| `actions.requested`       | The model requested one or more actions, including tool calls; calls stream before execution.                    |
 | `action.result`           | A tool call returned.                                                                                            |
 | `input.requested`         | The run paused for human input ([HITL](/docs/human-in-the-loop) approval or `ask_question`); carries `requests`. |
 | `subagent.called`         | A subagent was delegated; carries `childSessionId` to attach to.                                                 |

package/docs/connections/overview.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Connections"
+title: "Overview"
 description: "Expose external MCP and OpenAPI servers to the model, with connection tokens the model never sees."
 url: /connections
 ---
@@ -28,6 +28,18 @@ When `getToken` is the only auth, `principalType` defaults to `"app"`: one share
 
 eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
 
+## Choose app vs. user auth
+
+A connection credential can belong to the agent or to the person using it. This choice is separate from route auth, but user-scoped connection auth depends on route auth: eve can only resolve a user token when the active session has `ctx.session.auth.current?.principalType === "user"`.
+
+| Credential owner | Use when                                                                                                  | Auth shape                                                                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| App              | The agent should use one shared service, bot, installation, or app credential.                             | `auth: { getToken }` defaults to `principalType: "app"`, or use `connect({ connector: "linear/myagent", principalType: "app" })` with Vercel Connect.       |
+| User             | Each end-user should authorize and use their own third-party account.                                      | `connect("linear/myagent")`, `connect({ connector: "linear/myagent", principalType: "user" })`, or `auth: { principalType: "user", getToken }`.             |
+| User from a job  | Background work should use the same user's OAuth grant that started the work.                              | Start or resume the session through a channel whose route auth resolved that user, or pass an explicit user auth context when dispatching through a channel. |
+
+`principalType: "user"` does not mean "ask any human later." It means "key this credential to the authenticated user already attached to the eve session." If the run was started by a schedule, a same-project runtime token, `localDev()`, or another internal runtime path without an end-user principal, a user-scoped connection fails with `reason: "principal_required"` instead of starting OAuth. In that case, either authenticate the inbound channel as a user or configure the connection as app-scoped.
+
 ## No auth
 
 Drop `auth` entirely for servers that need no token, such as a localhost server during development or a public one:
@@ -124,7 +136,33 @@ export default defineMcpClientConnection({
 });
 ```
 
-`"linear/myagent"` is the UID you chose when registering the Connect client. Connect-managed OAuth is user-scoped by default, so the runtime resolves the per-user token before each tool call. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).
+`"linear/myagent"` is the UID you chose when registering the Connect client. `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.
+
+That means the channel that creates or continues the session must authenticate a real user. For a web app, configure `agent/channels/eve.ts` so your app session maps to `principalType: "user"`; for platform channels, use the built-in channel auth that maps the sender to a user principal. If no authenticated user is attached to the session, the first user-scoped connection call fails with `reason: "principal_required"`.
+
+If the remote service should act as the agent itself instead of the end-user, make the Connect connection app-scoped:
+
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace: issues, projects, cycles, and comments.",
+  auth: connect({ connector: "linear/myagent", principalType: "app" }),
+});
+```
+
+App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).
+
+### Troubleshooting Vercel Connect auth
+
+| Symptom                                      | What it means                                                                                                                    | Fix                                                                                                                                          |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reason: "principal_required"`               | A user-scoped connection ran without an authenticated user on the active session.                                                 | Return `principalType: "user"` from the channel's route auth, or change the connection to `principalType: "app"` if it should be shared.     |
+| `authorization.required` appears but no UI   | eve parked the turn for OAuth, but the channel or frontend is not rendering the challenge.                                        | Render the challenge from the stream event and continue the same session after the callback.                                                  |
+| OAuth works locally but fails after deploy   | The project may not be linked to the Connect client, or the deployed runtime may not have the expected Vercel OIDC/project scope. | Run Connect setup from the consuming project directory, link the project, deploy again, and verify the connector UID in `connect("...")`.     |
+| A scheduled or internal run needs user OAuth | Schedules and runtime callers do not automatically carry an end-user principal.                                                   | Dispatch through a user-authenticated channel when work is user-owned, or use app-scoped auth for agent-owned background work.                |
 
 ## Self-hosted interactive OAuth
 

package/docs/evals/assertions.mdx

@@ -1,39 +1,51 @@
 ---
 title: "Assertions"
-description: "Run-level methods, t.check value assertions, the matcher mini-language, and gate vs soft severity."
+description: "Scoped methods, value assertions, the matcher mini-language, and gate vs soft severity."
 ---
 
-Assertions are how an eval grades what its `test(t)` function produced. Each one **records** a result onto `t` and returns a chainable handle. The runner reads the recorded results to compute the verdict, so a single run reports every failing assertion rather than dying on the first. There are two deterministic surfaces: run-level methods on `t`, and `t.check` for grading a specific value. For model-graded assertions, see [Judge](./judge).
+Assertions are how an eval grades what its `test(t)` function produced. Each one records a result and returns a chainable handle. The runner reads every recorded result to compute the verdict, so a single run reports every failing assertion rather than dying on the first. There are two deterministic surfaces: scoped methods and `t.check` for grading a specific value. For model-graded assertions, see [Judge](./judge).
 
-## Run-level assertions
+## Scoped assertions
 
-Run-level assertions read the whole run, so they take no value. They are methods on `t` and gate by default. Several key off whether a run **parked**: paused on an unanswered human-in-the-loop (HITL) input request, waiting for an approval or answer before it can continue.
+Scoped assertions take no explicit value and gate by default. Assertions on `t` inspect the whole run after `test` finishes. Session assertions snapshot that session when called, and turn assertions inspect one immutable response. A scope is **parked** when it paused on unanswered human-in-the-loop (HITL) input.
 
-| Assertion                                           | Asserts                                                                                 |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `t.completed()`                                     | The run did not fail and did not park on unanswered HITL input                          |
-| `t.didNotFail()`                                    | No terminal failure and no `turn.failed`/`step.failed` events (parked runs pass)        |
-| `t.waiting()`                                       | The run parked on HITL input (for approval-shaped evals)                                |
-| `t.messageIncludes(token)`                          | Joined assistant text contains `token` (string or RegExp)                               |
-| `t.outputEquals(value)` / `t.outputMatches(schema)` | Deep equality or Standard Schema (e.g. Zod) validation of the agent's structured output |
-| `t.calledTool(name, opts?)`                         | A matching tool call happened (`input`, `output`, `isError`, `times` constraints)       |
-| `t.loadedSkill(skill, opts?)`                       | Sugar for `t.calledTool("load_skill", { input: { skill }, ...opts })`                   |
-| `t.notCalledTool(name)`                             | No call to `name`                                                                       |
-| `t.toolOrder([...names])`                           | Tool names appear in order (other calls may interleave)                                 |
-| `t.usedNoTools()`                                   | No tool calls at all                                                                    |
-| `t.maxToolCalls(n)`                                 | At most `n` tool calls                                                                  |
-| `t.noFailedActions()`                               | No tool, subagent, or skill action reported a failure                                   |
-| `t.calledSubagent(name, opts?)`                     | A subagent delegation happened (`remoteUrl`, `output` constraints)                      |
-| `t.event(predicate, label)`                         | Escape hatch: any predicate over the typed event stream                                 |
+| Assertion                                             | Asserts                                                                       |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `t.succeeded()`                                       | The run did not fail and did not park on unanswered HITL input                |
+| `t.parked()`                                          | The run cleanly parked on HITL input                                          |
+| `t.messageIncludes(token)`                            | Joined assistant text contains `token` (string or RegExp)                     |
+| `turn.outputEquals(value)` / `.outputMatches(schema)` | Deep equality or Standard Schema validation of turn/session structured output |
+| `t.calledTool(name, opts?)`                           | A matching tool call completed (`input`, `output`, `status`, `count`)         |
+| `t.loadedSkill(skill, opts?)`                         | Sugar for `t.calledTool("load_skill", { input: { skill }, ...opts })`         |
+| `t.notCalledTool(name)`                               | No request for `name` in any lifecycle state                                  |
+| `t.toolOrder([...names])`                             | Tool requests appear in order                                                 |
+| `t.usedNoTools()`                                     | No tool calls at all                                                          |
+| `t.maxToolCalls(n)`                                   | At most `n` tool calls                                                        |
+| `t.noFailedActions()`                                 | No tool, subagent, or skill action reported a failure                         |
+| `t.calledSubagent(name, opts?)`                       | A subagent delegation happened (`remoteUrl`, `output` constraints)            |
+| `t.event(type, opts?)` / `t.notEvent(type, opts?)`    | Typed event presence, data, and count matching                                |
+| `t.eventOrder([...matchers])`                         | Matching event groups occur in order                                          |
+| `t.eventsSatisfy(label, predicate)`                   | Escape hatch: any predicate over the typed event stream                       |
 
-`t.completed()` subsumes `t.didNotFail()`, so reach for `completed` unless you specifically want to allow a parked run. The structured output that `t.outputEquals` and `t.outputMatches` read is the agent's structured output (see the [output schema guide](../guides/client/output-schema)).
+`succeeded()` accepts both a closed session and a healthy session left open for the next user message; it rejects protocol failures and unanswered HITL. `parked()` requires a clean HITL park. Structured output assertions live on turns and independent sessions, where the output is unambiguous (see the [output schema guide](../guides/client/output-schema)).
 
 ```ts
 await t.send("What is the weather in Brooklyn?");
-t.completed();
+t.succeeded();
 t.calledTool("get_weather");
 ```
 
+The same vocabulary narrows naturally in multi-turn and externally-created session evals:
+
+```ts
+const first = await t.send("Call get_weather for Brooklyn");
+first.calledTool("get_weather", { count: 1 });
+
+const attached = await t.target.attachSession(sessionId);
+attached.succeeded();
+attached.messageIncludes("Sunny");
+```
+
 `t.calledTool` and `t.usedNoTools` are mutually exclusive; assert one or the other, never both in the same run.
 
 ## Value assertions with `t.check`
@@ -41,52 +53,98 @@ t.calledTool("get_weather");
 `t.check(value, assertion)` grades an explicit value against a builder from `eve/evals/expect`. The value can be `t.reply`, a turn's `.message`, parsed JSON, or any local you computed:
 
 ```ts
-import { includes, equals, matches, similarity } from "eve/evals/expect";
+import { includes, equals, matches, satisfies, similarity } from "eve/evals/expect";
 
-t.check(t.reply, includes("sunny")); // substring (gate)
+t.check(t.reply, includes(/sunny/i)); // substring or RegExp (gate)
 t.check(parsed, equals({ city: "Brooklyn" })); // deep structural equality (gate)
 t.check(parsed, matches(WeatherSchema)); // Standard Schema, e.g. Zod (gate)
 t.check(t.reply, similarity("Sunny, 72F")); // fuzzy 0–1 Levenshtein (soft)
+t.check(
+  latencyMs,
+  satisfies((value) => value < 1_000, "latency under one second"),
+);
 ```
 
-| Builder                | Scores                                           | Default |
-| ---------------------- | ------------------------------------------------ | ------- |
-| `includes(substring)`  | value (coerced to string) contains `substring`   | gate    |
-| `equals(value)`        | deep structural equality                         | gate    |
-| `matches(schema)`      | validates against a Standard Schema              | gate    |
-| `similarity(expected)` | normalized Levenshtein similarity, 1 = identical | soft    |
+| Builder                | Scores                                                  | Default |
+| ---------------------- | ------------------------------------------------------- | ------- |
+| `includes(value)`      | coerced string contains a substring or matches a RegExp | gate    |
+| `equals(value)`        | deep structural equality                                | gate    |
+| `matches(schema)`      | validates against a Standard Schema                     | gate    |
+| `similarity(expected)` | normalized Levenshtein similarity, 1 = identical        | soft    |
+| `satisfies(fn, label)` | custom boolean predicate                                | gate    |
 
 Pick the cheapest builder that captures what "correct" means. When exact match is too strict but a judge model is overkill, `similarity` is the middle ground. For nuanced grading, reach for the [judge](./judge).
 
 ## The matcher mini-language
 
-`t.calledTool` and `t.calledSubagent` take a matcher object: `{ input, output, isError, times }` for tools, `{ remoteUrl, output }` for subagents. Each field accepts a literal (objects partial-deep-match), a RegExp, or a function. A matcher function receives the value and returns either a boolean (acts as a predicate) or an expected value to compare against (handy for runner-assigned values like environment-provided URLs):
+`t.calledTool` and `t.calledSubagent` take matcher objects. Tools accept `{ input, output, status, count }`; subagents accept `{ remoteUrl, output, status, count }`. Calls match `status: "completed"` by default; use `"pending"`, `"failed"`, or `"rejected"` explicitly for lifecycle checks. `count` is the exact number of calls matching every supplied constraint.
+
+Matcher values accept a literal (objects partial-deep-match), a RegExp, or a predicate function that returns a boolean:
 
 ```ts
-t.calledTool("bash", { input: { command: /^pwd/ }, isError: false, times: 1 });
+t.calledTool("bash", { input: { command: /^pwd/ }, count: 1 });
 
 t.calledTool("echo", { output: (value) => String(value).includes(marker) });
 
+parked.calledTool("guarded", { status: "pending", count: 1 });
+t.calledTool("guarded", { output: /approved/, count: 1 });
+
 t.calledSubagent("weather", {
-  remoteUrl: () => process.env.WEATHER_AGENT_URL!,
+  remoteUrl: (value) => value === process.env.WEATHER_AGENT_URL,
   output: /72F/,
 });
 ```
 
+`requireInputRequest` uses the same matcher language for `input`, `prompt`, and `display`. Its `optionIds` matcher receives option ids in request order; a literal array must match that complete ordered list exactly:
+
+```ts
+const request = session.requireInputRequest({
+  toolName: "ask_question",
+  optionIds: ["red", "blue"],
+});
+```
+
 ## Run state and derived facts
 
-Beyond the raw `t.events` stream, the runner derives typed facts the assertions read: tool calls (name, input, output, error state), subagent calls, and HITL input requests. A turn that leaves the session open for a next message is the normal end state of a successful turn; parking on unanswered HITL input is tracked separately, and that is what `t.completed()` and `t.waiting()` key off.
+Beyond the raw `t.events` stream, the runner derives typed facts the assertions read: tool calls (name, input, output, lifecycle status), subagent calls, and HITL input requests. A turn that leaves the session open for a next message is the normal end state of a successful turn; parking on unanswered HITL input is tracked separately.
 
-The built-in assertions cover almost everything. When you need to read the stream directly, `t.event(predicate, label)` is the escape hatch:
+Typed event matching covers presence, absence, exact counts, partial event data, and ordering:
 
 ```ts
-t.event(
-  (events) =>
-    events.some((e) => e.type === "message.completed" && e.data.message?.includes(marker)),
-  "assistant reply includes the marker",
+turn.notEvent("result.completed");
+turn.eventOrder([
+  { type: "subagent.called", data: { name: "researcher" }, count: 2 },
+  { type: "subagent.completed", data: { subagentName: "researcher" }, count: 2 },
+]);
+```
+
+When a protocol invariant needs cross-event correlation, `eventsSatisfy` remains the escape hatch:
+
+```ts
+t.eventsSatisfy("assistant reply includes the marker", (events) =>
+  events.some((e) => e.type === "message.completed" && e.data.message?.includes(marker)),
 );
 ```
 
+## Required preconditions
+
+Recorded assertions never throw and are not awaitable. When later control flow depends on a value, use `await t.require(value, assertion)`. It records a gate, returns the original value when it passes, and stops the test body without adding a duplicate execution error when it fails:
+
+```ts
+await t.require(
+  sessionIds,
+  satisfies((ids) => ids.length > 0, "dispatch started a session"),
+);
+await t.target.attachSession(sessionIds[0]!);
+```
+
+Use the matching `require*` lookups when dependent code needs protocol data:
+
+```ts
+const call = turn.requireToolCall("search");
+const request = session.requireInputRequest({ toolName: "guarded" });
+```
+
 ## Severity
 
 Every assertion returns a chainable handle. Severity rides on the assertion, so there is no separate thresholds map to keep in sync.

package/docs/evals/cases.mdx

@@ -5,6 +5,14 @@ description: "Author single-turn and multi-turn evals with test(t), and fan one
 
 Each eval file is one graded case by default, and a single file can fan out over a dataset by default-exporting an array (covered below). The runner executes each `test(t)` function against the target, captures every event, and computes a verdict from the [assertions](./assertions) you recorded. Every eval shares one shape, whether single-turn, multi-turn, human-in-the-loop (HITL), or dataset-driven: one `async test(t)` function that drives the agent and asserts inline.
 
+Before adding a case, create the required config at the root of `evals/`. An empty config is enough when you do not need shared judge, reporter, concurrency, or timeout settings:
+
+```ts title="evals/evals.config.ts"
+import { defineEvalConfig } from "eve/evals";
+
+export default defineEvalConfig({});
+```
+
 ## Single-turn evals
 
 The common case sends one turn and asserts on the reply. `t.send(input)` resolves once the turn settles, and `t.reply` is the last assistant message:
@@ -16,7 +24,7 @@ import { includes } from "eve/evals/expect";
 export default defineEval({
   async test(t) {
     await t.send("What is the weather in Brooklyn?");
-    t.completed();
+    t.succeeded();
     t.check(t.reply, includes("Sunny"));
   },
 });
@@ -30,7 +38,7 @@ import { defineEval } from "eve/evals";
 export default defineEval({
   async test(t) {
     await t.send("Hello!");
-    t.completed();
+    t.succeeded();
     t.notCalledTool("get_weather");
   },
 });
@@ -42,6 +50,7 @@ Identity is the file path, so directories are the grouping mechanism. `evals/wea
 
 ```text
 evals/
+├── evals.config.ts
 ├── weather/
 │   ├── shared.ts                    # helpers, not an eval
 │   ├── brooklyn-forecast.eval.ts
@@ -69,25 +78,21 @@ export default defineEval({
 });
 ```
 
-For a precondition no built-in assertion expresses, `throw`. A thrown error marks the eval `failed` with the message in the result:
+Use scoped assertions for intermediate turns. When later control flow depends on a value-level check, `t.require` records a gate and stops the script if it fails:
 
 ```ts title="evals/session-continuity.eval.ts"
 import { defineEval } from "eve/evals";
-import { includes } from "eve/evals/expect";
+import { equals } from "eve/evals/expect";
 
 export default defineEval({
   async test(t) {
-    await t.send("My favorite word is marigold.");
-    const firstSessionId = t.sessionId;
+    const first = await t.send("My favorite word is marigold.");
 
     const second = await t.send("Thanks for remembering.");
-    second.expectOk();
-    if (t.sessionId !== firstSessionId) {
-      throw new Error(`Expected one session; got ${firstSessionId} then ${t.sessionId}.`);
-    }
+    await t.require(second.sessionId, equals(first.sessionId));
 
-    t.completed();
-    t.check(second.message, includes("Thanks for remembering."));
+    t.succeeded();
+    second.messageIncludes("Thanks for remembering.");
   },
 });
 ```
@@ -98,12 +103,16 @@ export default defineEval({
 
 - `t.send(input)` sends a turn and waits for it to settle. It accepts the same input as `ClientSession.send()` (a string or a structured message) and resolves to a turn carrying `.message` and `.expectOk()`.
 - `t.sendFile(text, path, mediaType?)` attaches a local file as a data URL.
-- `t.expectInputRequests(filter?)` asserts the previous turn parked on HITL input and returns the pending requests.
+- `t.requireInputRequest(filter?)` records a gate, requires exactly one pending request, and returns it. Filters match tool name, action input, prompt, display, and option ids.
 - `t.respond(...responses)` answers specific pending input requests and sends them as the next turn.
 - `t.respondAll(optionId)` answers every pending input request with the same option and sends the responses as the next turn.
 - `t.reply` is the last assistant message (or `null`); `t.sessionId` is the current session id; `t.events` is the full typed event stream captured so far.
 
-Each `send` (and `respond`/`respondAll`) resolves to a turn whose `expectOk()` throws only when the turn ended failed. A session left open for a next message is the normal end state of a successful turn.
+Each `send` (and `respond`/`respondAll`) resolves to an immutable turn with `.message`, `.data`, `.events`, `.inputRequests`, `.toolCalls`, `.sessionId`, `.status`, and `.expectOk()`. Use `.sessionId` to relate turns or attach follow-up work to the session that produced a specific turn. `expectOk()` throws only when the turn ended failed; a session left open for a next message is the normal end state of a successful turn.
+
+Use `expectOk()` only when the next operation depends on that intermediate turn succeeding. A final `t.succeeded()` already records a complete-run gate.
+
+To intentionally omit an eval for the current target, call `t.skip(reason)` before sending messages or recording assertions. Skipped evals are reported separately and do not affect the exit code.
 
 Events from every session are captured in the result and artifacts. `t.log(message)` records debug lines into the eval artifact; `--verbose` also streams them to stdout as evals run. `t.signal` is an `AbortSignal` that fires on timeout.
 
@@ -126,7 +135,7 @@ export default rows.map((row) =>
     description: row.task,
     async test(t) {
       await t.send(row.prompt);
-      t.completed();
+      t.succeeded();
       t.check(t.reply, equals(row.sql));
     },
   }),

package/docs/evals/judge.mdx

@@ -11,7 +11,7 @@ import { defineEval } from "eve/evals";
 export default defineEval({
   async test(t) {
     await t.send("Explain quantum tunneling to a 10-year-old.");
-    t.completed();
+    t.succeeded();
     t.judge.autoevals.closedQA("uses no math beyond arithmetic").atLeast(0.8);
   },
 });
@@ -52,7 +52,7 @@ t.judge.autoevals.closedQA("cites a source").atLeast(0.6); // soft, fails under
 t.judge.autoevals.factuality(reference).gate(0.8); // hard gate at 0.8
 ```
 
-A judge runs once per assertion and burns tokens, so reach for one only when nothing deterministic will do. Several slow judge calls in one eval can fan out with `await Promise.all([...])`.
+A judge runs once per assertion and burns tokens, so reach for one only when nothing deterministic will do. Judge calls start when recorded, and the runner waits for all of them during finalization; assertion handles themselves are intentionally not awaitable.
 
 ## Configuring the judge model
 

package/docs/evals/overview.mdx

@@ -33,7 +33,7 @@ export default defineEval({
   description: "Basic message and tool-usage coverage for the weather agent.",
   async test(t) {
     await t.send("What is the weather in Brooklyn?");
-    t.completed();
+    t.succeeded();
     t.calledTool("get_weather");
     t.check(t.reply, includes("Sunny"));
   },
@@ -62,14 +62,14 @@ Everything is optional. `judge` sets the default model for [LLM-as-judge](./judg
 
 `t` is both the driver and the assertion surface. There are no separate `input`, `run`, `checks`, or `scores` fields. You write ordinary control flow, sending turns and asserting inline.
 
-- **Drive** the agent: `t.send(...)`, `t.respond(...)`, `t.respondAll(...)`, `t.sendFile(...)`, `t.expectInputRequests(...)`, `t.newSession()`. Read what came back with `t.reply` (the last assistant message), `t.sessionId`, and `t.events`. See [Cases](./cases).
+- **Drive** the agent: `t.send(...)`, `t.respond(...)`, `t.respondAll(...)`, `t.sendFile(...)`, `t.requireInputRequest(...)`, `t.newSession()`. Read what came back with `t.reply` (the last assistant message), `t.sessionId`, and `t.events`. See [Cases](./cases).
 - **Assert** with three surfaces, covered next.
 
 ## Three assertion surfaces
 
 Each surface matches a genuinely different kind of judgment:
 
-- **Run-level methods** read the whole run, like `t.completed()`, `t.calledTool("get_weather")`, `t.usedNoTools()`, and `t.toolOrder([...])`. They take no value because they observe the run itself. See [Assertions](./assertions).
+- **Scoped methods** read the final whole run on `t`, snapshot one independent session when invoked there, or inspect one immutable `EveEvalTurn`. See [Assertions](./assertions).
 - **`t.check(value, assertion)`** grades an explicit value with a deterministic builder from `eve/evals/expect`, such as `t.check(t.reply, includes("sunny"))`. Grade `t.reply`, an intermediate draft, parsed JSON, or anything else. See [Assertions](./assertions).
 - **`t.judge.autoevals.*`** is the LLM-as-judge surface, like `t.judge.autoevals.closedQA("cites a source")`. It grades `t.reply` by default and uses the configured judge model, never the agent under test. See [Judge](./judge).
 
@@ -83,12 +83,14 @@ Every assertion returns a chainable handle, so severity rides on the assertion i
 Override per assertion: `.gate(threshold?)` promotes to a hard gate, `.soft(threshold?)` demotes to tracked, and `.atLeast(threshold)` is a soft assertion with a bar.
 
 ```ts
-t.completed(); // gate
+t.succeeded(); // gate
 t.calledTool("get_weather").soft(); // record as a metric, don't gate
 t.judge.autoevals.closedQA("cites a source"); // soft, tracked (no threshold)
 t.judge.autoevals.factuality(reference).atLeast(0.7); // soft, gated under --strict at 0.7
 ```
 
+Use `await t.require(value, assertion)` for a gate that must pass before the script can safely continue. Use `t.skip(reason)` as the first operation for an intentionally unsupported target capability.
+
 ## Run evals with eve eval
 
 ```bash
@@ -101,7 +103,7 @@ Exit code `0` means every eval passed its gates. See [Running evals](./running)
 
 ## A good baseline
 
-Most apps do fine with a few small smoke evals. Assert behavior with `t.completed()` plus one or two content checks, keep dataset fixtures in `evals/data/`, and reach for a judge or Braintrust only when you need fuzzy grading or shared result review. In CI, run `eve eval --strict` so soft threshold misses fail the build too.
+Most apps do fine with a few small smoke evals. Assert behavior with `t.succeeded()` plus one or two content checks, keep dataset fixtures in `evals/data/`, and reach for a judge or Braintrust only when you need fuzzy grading or shared result review. In CI, run `eve eval --strict` so soft threshold misses fail the build too.
 
 ## What to read next
 

package/docs/evals/reporters.mdx

@@ -33,7 +33,7 @@ export default defineEval({
   reporters: [Braintrust({ projectName: "weather-agent" })],
   async test(t) {
     await t.send("What is the weather in Brooklyn?");
-    t.completed();
+    t.succeeded();
   },
 });
 ```
@@ -52,7 +52,7 @@ Braintrust needs its SDK installed in the app and credentials in the environment
 eve eval --strict --junit .eve/junit.xml
 ```
 
-Each eval becomes one `<testcase>` named by its path-derived id; failed gates and execution errors land as failure messages on the matching test case, so CI surfaces them inline.
+Each eval becomes one `<testcase>` named by its path-derived id; failed gates and execution errors become failures, while `t.skip(reason)` produces a JUnit `<skipped>` result.
 
 ## Custom reporters
 

package/docs/evals/running.mdx

@@ -26,10 +26,12 @@ Positional ids match exactly or by directory prefix: `eve eval weather` runs `ev
 
 | Code | Means                                                                           |
 | ---- | ------------------------------------------------------------------------------- |
-| `0`  | Every eval passed its gates (and soft thresholds, under `--strict`)             |
+| `0`  | Every non-skipped eval passed its gates (and soft thresholds, under `--strict`) |
 | `1`  | Any eval failed (a failed gate, an execution error, or a strict threshold miss) |
 | `2`  | Configuration error                                                             |
 
+An eval that calls `t.skip(reason)` is reported as skipped, does not count as passed or failed, and never changes the exit code.
+
 ## Artifacts
 
 Each run drops artifacts under `.eve/evals/<timestamp>/`: a run `summary.json`, a `results.jsonl` index, and per-eval assertion results, verdicts, captured event streams, and `t.log` lines under `evals/`. The console output stays tight on purpose; when an eval fails, the artifact has the full story.

package/docs/evals/targets.mdx

@@ -16,7 +16,7 @@ export default defineEval({
   async test(t) {
     const { sessionIds } = await t.target.dispatchSchedule("heartbeat");
     await t.target.attachSession(sessionIds[0]!);
-    t.completed();
+    t.succeeded();
     t.calledTool("send_report");
   },
 });
@@ -26,7 +26,7 @@ export default defineEval({
 - `t.target.dispatchSchedule(id)` triggers a [schedule](../schedules) through the dev-only schedule route and returns the session ids it created. It works only against a target with dev routes enabled (the local `eve eval` dev server, or a deployment running in development mode), and throws otherwise.
 - `t.target.attachSession(sessionId, { startIndex? })` consumes one turn from a session created outside the eval, by a channel or a schedule, so its events feed the run-level assertions. `startIndex` skips events before that position, so a session already partway through its stream resumes from where you left off rather than replaying from the start.
 
-Sessions attached this way are full `EveEvalSession`s: you can keep driving them with `send` and read their event streams. The run-level assertions on `t` (`t.completed()`, `t.calledTool(...)`) read the whole run, including attached sessions.
+Sessions attached this way are full `EveEvalSession`s: you can keep driving them and assert directly on that session (`session.succeeded()`, `session.calledTool(...)`). Aggregate assertions on `t` continue to read the whole run, including every attached session.
 
 ## Authentication
 

package/docs/guides/auth-and-route-protection.md

@@ -224,6 +224,53 @@ Route auth does not enforce session ownership. If multiple users or tenants can
 
 Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Connections declare `auth` on the connection definition. Tools should resolve providers inline with `ctx.getToken(provider)` and call `ctx.requireAuth(provider)` only when a downstream service rejects a token; eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
 
+The principal for user-scoped tool and connection auth comes from route auth. `connect("...")` from `@vercel/connect/eve` defaults to `principalType: "user"`, so the active session must have `ctx.session.auth.current.principalType === "user"` before the first token lookup can start OAuth. If the session is anonymous, local-dev-only, runtime-scoped, or service-scoped, eve fails fast with `reason: "principal_required"` because there is no end-user identity to bind the OAuth grant to.
+
+Use app-scoped auth when the external service should act as the agent itself:
+
+```ts
+auth: connect({ connector: "linear/myagent", principalType: "app" });
+```
+
+Use user-scoped auth when the external service should act as the signed-in person:
+
+```ts
+auth: connect("linear/myagent");
+```
+
+For user-scoped auth in a browser app, the route-auth entry for the eve channel should verify your app session and return a user principal:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, type AuthFn } from "eve/channels/auth";
+import { getSession } from "@/lib/auth";
+
+function appSession(): AuthFn<Request> {
+  return async (request) => {
+    const session = await getSession(request);
+    if (!session) return null;
+
+    return {
+      authenticator: "app",
+      principalId: session.userId,
+      principalType: "user",
+      attributes: {
+        email: session.email,
+        teamId: session.teamId,
+      },
+    };
+  };
+}
+
+export default eveChannel({
+  auth: [appSession(), localDev()],
+});
+```
+
+Keep `principalId` stable for the same person, and include an `issuer` when the same app may accept users from multiple identity providers. The connection token cache keys user credentials by issuer and principal id so two providers cannot accidentally share a grant.
+
+Built-in platform channels that identify a human sender, such as Slack, Discord, Teams, Telegram, Twilio, Linear, and GitHub, attach a user principal for that sender by default. A Slack mention, DM, or button click can therefore authorize a user-scoped connection for the Slack user who sent it without adding a separate browser-session auth function.
+
 ### On a connection
 
 Attach `connect()` from `@vercel/connect/eve` to the connection:
@@ -241,7 +288,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-The first call that needs the connection kicks off an OAuth sign-in, surfaced as an authorization challenge (a URL the caller visits). [Vercel Connect](https://vercel.com/docs/connect) brokers the flow and holds the credentials, which are resolved and cached per workflow step, never serialized into history, and never shown to the model. For non-interactive connections, pass a static token in place of `connect()`. [Connections](../connections) covers both shapes.
+The first call that needs a user-scoped connection kicks off an OAuth sign-in, surfaced as an authorization challenge (a URL the caller visits). [Vercel Connect](https://vercel.com/docs/connect) brokers the flow and holds the credentials, which are resolved and cached per workflow step, never serialized into history, and never shown to the model. For non-interactive connections, pass a static token or `connect({ connector, principalType: "app" })` in place of user-scoped `connect()`. [Connections](../connections) covers both shapes.
 
 ### On a single tool
 

package/docs/guides/client/streaming.mdx

@@ -66,7 +66,7 @@ The most common UI events are:
 | `message.received`   | Confirm the user message landed.                                 |
 | `reasoning.appended` | Render reasoning deltas when the model provides them.            |
 | `message.appended`   | Render assistant text deltas.                                    |
-| `actions.requested`  | Show tool calls requested by the model.                          |
+| `actions.requested`  | Show tool calls as the model requests them, before execution.    |
 | `action.result`      | Show tool call results.                                          |
 | `input.requested`    | Pause the UI for approval or a question answer.                  |
 | `result.completed`   | Read structured output from an [output schema](./output-schema). |