eve 0.13.8 → 0.15.0

package/docs/agent-config.md

@@ -1,6 +1,6 @@
 ---
 title: "agent.ts"
-description: "Set the agent's runtime config in agent.ts with defineAgent, including the model and compaction."
+description: "Set the agent's runtime config in agent.ts with defineAgent, including the model, reasoning effort, and compaction."
 ---
 
 An agent's `agent.ts` calls `defineAgent` (from `eve`) to set its runtime config.
@@ -33,12 +33,33 @@ import { anthropic } from "@ai-sdk/anthropic";
 import { defineAgent } from "eve";
 
 export default defineAgent({
-  model: anthropic("claude-opus-4.8"),
+  model: anthropic("claude-opus-4-8"),
 });
 ```
 
+Direct provider model ids use the provider's native format. For Anthropic, the
+version uses hyphens (`claude-opus-4-8`), while the Gateway id above uses a dot
+(`anthropic/claude-opus-4.8`).
+
 Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct `LanguageModel`.
 
+## Reasoning effort
+
+Set `reasoning` to control the model's reasoning effort through AI SDK's
+provider-agnostic option:
+
+```ts title="agent/agent.ts"
+export default defineAgent({
+  model: "openai/gpt-5.5",
+  reasoning: "high",
+});
+```
+
+Supported values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`,
+`"medium"`, `"high"`, and `"xhigh"`. The selected model and provider determine
+which levels are available and how they map to provider-native settings. Use
+`modelOptions.providerOptions` when you need provider-specific reasoning controls.
+
 ## Compaction
 
 Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. Lower `thresholdPercent` to compact sooner:
@@ -75,24 +96,33 @@ 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
 
 `defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
 
-| Field          | Type                                                    | Default     | Description                                                                                                                                                                                                                                                                                                                                                                       |
-| -------------- | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `modelOptions` | `AgentModelOptionsDefinition`                           | none        | Provider option overrides forwarded to the model call.                                                                                                                                                                                                                                                                                                                            |
-| `experimental` | `{ codeMode?: boolean; workflow?: { world?: string } }` | flags unset | Opt-in flags that can change or disappear in any release. Treat them as unstable. `codeMode` routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the [sandbox](./sandbox). `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
-| `outputSchema` | Standard Schema or a JSON Schema object                 | none        | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                                                                                                                                                                                        |
-| `build`        | `{ externalDependencies?: string[] }`                   | none        | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                                                                                                                                          |
-
-`codeMode` is experimental and may change or be removed.
+| Field          | Type                                    | Default          | Description                                                                                                                                                                                                   |
+| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                 |
+| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                        |
+| `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
+| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                    |
+| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.      |
 
 `externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
 

package/docs/channels/custom.mdx

@@ -46,7 +46,7 @@ export default defineChannel({
 
 Declare routes with the `POST()` and `GET()` helpers. Each route handler receives the raw `Request` and a helpers object:
 
-- `send(message, { auth, continuationToken, state? })` starts or resumes a session. Returns a `Session`.
+- `send(message, { auth, continuationToken, state?, title? })` starts or resumes a session. `title` overrides the new workflow session's display title without changing the model message. Returns a `Session`.
 - `getSession(sessionId)` looks up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming.
 - `receive(channel, ...)` hands inbound work to a different channel for cross-channel hand-off.
 - `params` holds route parameters extracted from the path pattern.
@@ -182,7 +182,7 @@ When a parent agent dispatches a subagent, the framework forwards the parent's c
 
 ## Continuation tokens
 
-Each call to `send(message, { auth, continuationToken, state? })` from a channel route addresses a session by its channel-local raw token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
+Each call to `send(message, { auth, continuationToken, state?, title? })` from a channel route addresses a session by its channel-local raw token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
 
 ```ts
 import { slackContinuationToken } from "eve/channels/slack";

package/docs/channels/slack.mdx

@@ -54,28 +54,22 @@ Inbound hooks decide whether to dispatch a turn and with what `auth`. Return `{
 - `onDirectMessage(ctx, message)` handles `message.im` events (needs `im:history` scope). Bot-authored messages and edits are filtered out first.
 - `onInteraction(action, ctx)` handles `block_actions` callbacks not consumed by HITL.
 
-You get the triggering mention by default, but not the earlier replies in the thread. Pull them in with `loadThreadContextMessages` and return them as `context`, which eve appends to history as user messages the model sees on every later turn. Use `since: "last-agent-reply"` so repeated mentions in one thread inject only what is new:
+eve attaches the triggering Slack user id to the same model message as the message text. This keeps speaker attribution intact when several people use one thread without making profile lookup requests.
+
+You get the triggering mention by default, but not the earlier replies in the thread. Enable `threadContext` to fetch and inject them with every message attributed by stable Slack user id. Use `since: "last-agent-reply"` so repeated mentions inject only what is new:
 
 ```ts
-import { defaultSlackAuth, loadThreadContextMessages, slackChannel } from "eve/channels/slack";
+import { slackChannel } from "eve/channels/slack";
 import { connectSlackCredentials } from "@vercel/connect/eve";
 
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  async onAppMention(ctx, message) {
-    const auth = defaultSlackAuth(message, ctx);
-    const prior = await loadThreadContextMessages(ctx.thread, message, {
-      since: "last-agent-reply",
-    });
-    if (prior.length === 0) return { auth };
-    const transcript = prior
-      .map((m) => `${m.isMe ? "you" : (m.user ?? "user")}: ${m.markdown}`)
-      .join("\n");
-    return { auth, context: [`Recent thread messages since your last reply:\n\n${transcript}`] };
-  },
+  threadContext: { since: "last-agent-reply" },
 });
 ```
 
+`threadContext` performs one `conversations.replies` request for each triggering thread reply and requires the matching Slack history scope. Omit it when the agent should see only direct mentions. `loadThreadContextMessages` remains available when you need custom filtering or non-model processing of the raw thread messages.
+
 ### Delivery
 
 The default handlers reply in-thread and show progress. Typing indicators post automatically: `Thinking…` on inbound, `Working…` on `turn.started`, a truncated reasoning snippet on `reasoning.appended`, and tool status on `actions.requested`. Reasoning snippets build progressively: extensions of at least four characters appear immediately, while smaller streamed deltas use the five-second refresh interval to avoid one Slack request per token. Override `events["reasoning.appended"]` if you prefer generic wording. Override `onAppMention` or the `events` handlers to customize.

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/mcp.mdx

@@ -48,8 +48,8 @@ Use `allow` for the smallest safe surface, especially on MCP servers that expose
 
 MCP connections support the shared connection options:
 
-- `auth` for static tokens, Vercel Connect, or self-hosted interactive OAuth.
-- `headers` for API-key schemes or extra server configuration.
+- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
+- `headers` for static or per-caller API-key schemes and extra server configuration.
 - `approval` for human-in-the-loop gates before connection tools run.
 
 See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.

package/docs/connections/openapi.mdx

@@ -34,6 +34,41 @@ OpenAPI connections use the shared connection fields from [Connections](/docs/co
 
 Use `baseUrl` when the spec's `servers` list is absent, points at the wrong environment, or needs to be pinned for this agent.
 
+## Path parameters
+
+When an operation path contains dynamic segments, declare each segment as an OpenAPI path parameter. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
+
+```ts title="agent/connections/cart.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  baseUrl: "https://api.example.com",
+  description: "Cart and checkout API.",
+  spec: {
+    openapi: "3.0.3",
+    info: { title: "Cart API", version: "1.0.0" },
+    paths: {
+      "/api/{dynamicsegment}/somethingelse": {
+        get: {
+          operationId: "getSomethingElse",
+          parameters: [
+            {
+              name: "dynamicsegment",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+            },
+          ],
+          responses: { "200": { description: "OK" } },
+        },
+      },
+    },
+  },
+});
+```
+
+The parameter `name` must exactly match the placeholder inside the path. If the spec omits the `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
+
 ## Operation filters
 
 To narrow which generated tools the model sees, set exactly one of `operations.allow` or `operations.block`:
@@ -55,8 +90,8 @@ Filters match `operationId`. If an operation does not declare one, use the deter
 
 OpenAPI connections support the shared connection options:
 
-- `auth` for static tokens, Vercel Connect, or self-hosted interactive OAuth.
-- `headers` for API-key schemes or extra server configuration.
+- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
+- `headers` for static or per-caller API-key schemes and extra server configuration.
 - `approval` for human-in-the-loop gates before generated operation tools run.
 
 See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.

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:
@@ -57,6 +69,38 @@ export default defineMcpClientConnection({
 });
 ```
 
+## Per-caller auth and headers
+
+When credentials or routing depend on the caller, make `auth` or `headers` a function. eve calls it inside the active turn and passes the same session context exposed to tools and hooks:
+
+```ts title="agent/connections/warehouse.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://warehouse.example.com/openapi.json",
+  description: "The caller's tenant-scoped warehouse.",
+  auth: (ctx) => ({
+    principalType: "user",
+    getToken: async () => ({
+      token: await tenantToken(ctx.session.auth.current),
+    }),
+  }),
+  headers: (ctx) => ({
+    "X-Tenant-Id": tenantId(ctx.session.auth.current),
+  }),
+});
+```
+
+An `auth` resolver returns the same provider object accepted by static `auth`, including a `connect(...)` provider for interactive OAuth. The resolver itself can be async. Header callbacks can return the whole map, as above, or resolve individual values:
+
+```ts
+headers: {
+  "X-Tenant-Id": (ctx) => tenantId(ctx.session.auth.current),
+}
+```
+
+Use `principalType: "user"` for per-user tokens so eve rejects unauthenticated callers and keys its step-local token cache by user. The resolver supplements route auth; it does not authenticate the inbound request. Static auth objects and header maps remain available when every caller shares the same configuration.
+
 ## Per-connection approval
 
 To put every tool a connection serves behind a human, use the helpers from `eve/tools/approval`:
@@ -92,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.