eve 0.83.3 → 0.84.0

package/docs/concepts/state.md

@@ -81,7 +81,7 @@ automatically.
 
 ## What to read next
 
-- Read state inside dynamic resolvers → [Dynamic capabilities](../guides/dynamic-capabilities)
+- Vary capabilities per session → [Dynamic capabilities](../guides/dynamic-capabilities)
 - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
 - The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
 - Tenant-scoped long-term memory with any provider → [Multi-tenant memory](../patterns/multi-tenant-memory)

package/docs/concepts/upgrade-to-v27-events.md

@@ -0,0 +1,128 @@
+---
+title: "Upgrade to v27 Session Events"
+description: "Update agent definitions, integrations, clients, and evals for the new APIs and v27 session stream."
+---
+
+This guide covers breaking changes to agent definitions, approvals, channels, clients, and evals, including the move from v26 session events to v27 facts. Update custom integrations as well as application code.
+
+## Before you upgrade
+
+- Rebuild and republish installed extensions. Earlier epoch-based distributions cannot be loaded by this release; see [Extensions](../extensions).
+- Keep the deployments that own existing sessions available. This release requires checkpoint version 18 and cannot take over sessions with earlier checkpoint formats. On worlds without deployment routing, follow the [stranded-session recovery guidance](./execution-model-and-durability#stranded-sessions).
+- Update event consumers, frontend persistence, and custom channel handlers using the mappings below. See [Sessions, runs & streaming](./sessions-runs-and-streaming) for the current stream contract.
+
+## Restore saved history
+
+New sessions use v27. Sessions started on an earlier deployment keep their stored stream format, but a current deployment can serve their recorded history as v27 events.
+
+Don't pass event arrays saved before the upgrade as `initialEvents`. When the session's stream is still available, read it again from position 0 and replace what you saved. Saved cursors still count the same stored lines.
+
+When the saved array is the only copy, for example because the stream expired, convert it once and store the result:
+
+```ts
+import { convertLegacyEvents } from "eve/internal/legacy-events";
+
+// One session's saved events, from its `session.started` on, as they were saved.
+const events = convertLegacyEvents(saved);
+```
+
+Save the converted events with their metadata unchanged and pass them as `SessionStore`'s `initialEvents`. Their source positions and coverage metadata determine where reading resumes, including source lines that produced no facts. Do not calculate the resume position from the number of converted events or from another reader's cursor. See [Restore frontend state](../guides/frontend/overview#resumable-sessions) for hydration and replay behavior.
+
+A session saved mid-turn stays unfinished. Convert each session separately: the function throws for an array that doesn't start at `session.started`, that holds a second session, or that holds current events. `convertLegacyEvents` is a migration aid with no compatibility promise and will be removed in a later release.
+
+## Event mapping
+
+| v26                                                               | v27                                                                                                             |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `message.received`                                                | `delivery.consumed`                                                                                             |
+| `message.appended`, `reasoning.appended`                          | `content.delta` (progress; check `kind`)                                                                        |
+| `message.completed`, `reasoning.completed`, `result.completed`    | `content.completed` (check `kind`; text `phase: "reply"` identifies the answer)                                 |
+| `step.started`, `step.completed`, `step.failed`                   | `model.started`, `model.settled` (check `outcome`); `model.requested` precedes model selection                  |
+| `action.input.appended`, `action.partial`                         | `call.input`, `call.progress` (progress)                                                                        |
+| `actions.requested`, `action.result`                              | `call.requested` (one per call), `call.settled`                                                                 |
+| `task.started`, `task.settled`                                    | `task.started`, `task.ended`; each served call also has `call.started` and `call.settled`                       |
+| `agent.started`                                                   | `child.opened`                                                                                                  |
+| `input.requested`, `authorization.required`                       | `interaction.opened` (check `request.kind`, including `"sign-in"`)                                              |
+| `input.resolved`, `authorization.completed`, `approval.settled`   | `interaction.settled` (check `outcome`)                                                                         |
+| `approval.candidate`                                              | `response.submitted`, `response.settled`                                                                        |
+| `compaction.requested`, `compaction.completed`, `context.cleared` | `context.started`, `context.settled` (check `kind`)                                                             |
+| `turn.waiting`, `turn.completed`, `turn.failed`, `turn.cancelled` | `turn.paused` (for interactions), `turn.settled` (check `outcome`)                                              |
+| `session.waiting`, `session.completed`, `session.failed`          | `delivery.settled` for a request, `session.ended` for a terminal session; use `idle(view)` for current idleness |
+
+New facts include `delivery.admitted`, `response.admitted`, `model.retried`, and `usage.recorded`. A turn waiting on tasks remains running; only waiting for human input pauses it. Facts carry `scope` for turn/run/task coordinates. Replace event IDs and step sequence counters with `meta.position` (`line`, `index`); `startIndex` and saved cursors count durable **lines**, not facts. Key persisted events on `(sessionId, line, index)` to handle replay. Failures use `error: { code, message, id?, hint? }`. Usage belongs to `usage.recorded`, not terminal turn or session events.
+
+## Renamed APIs
+
+| Before                                                                 | Now                                                                         |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `InputRequest`, `InputResponse`, `requestId`                           | `Interaction`, `Answer`, `interactionId`                                    |
+| `send({ inputResponses })`, `respond(inputResponses)`                  | `send({ answers })`, `respond(answers)`                                     |
+| `parseInputResponse(s)`, `isInputResponse`                             | `parseAnswer(s)`, `isAnswer`                                                |
+| Response `inputRequests` and `authorizations`                          | `interactions` (including sign-ins)                                         |
+| `ConversationState.inputs`, `openConversationInputs(state)`            | `interactions(view)`, `openInteractions(view)` from `eve/events`            |
+| `conversationReducer`, `defaultMessageReducer`, `EveAgentReducer`      | Query opaque `view`; read `messages` and `agents`                           |
+| `transcriptReducer(options)`                                           | `transcriptOf(events, options)`                                             |
+| `onInputResponse` on Slack, Discord, Teams                             | `onAnswers`                                                                 |
+| Telegram `renderTelegramInputRequest`, `resolveTelegramInputResponses` | `renderTelegramInteraction`, `resolveTelegramAnswers`                       |
+| Workflow `ToolInputRequest`, `ToolInputResponse`                       | `ToolQuestion`, `ToolAnswer`                                                |
+| Approval `request.requestId`                                           | `request.interactionId`                                                     |
+| `MessageResponse`, `MessageResult`                                     | `Delivery`, `DeliveryResult` from `eve/sessions`                            |
+| Creation result `{ session, response }`                                | `{ session, delivery }` when a message is supplied; `{ session }` otherwise |
+| Built-in tool factories `askQuestion()`, `noReply()`, `sleep()`        | Export the definitions `askQuestion`, `noReply`, `sleep` directly           |
+| `decide({ abortSignal })`                                              | `decide({ signal })`; results contain only `answers` and `usage`            |
+| Client and frontend target `host`                                      | `baseUrl` (direct client required; frontend default `""`)                   |
+| `EveAgentStore`                                                        | `SessionStore`                                                              |
+| `StreamOptions`, `GetEventStreamOptions`                               | `SessionStreamOptions` from `eve/sessions`                                  |
+| Evals `inputRequests`, `pendingInputRequests`, `requireInputRequest()` | `interactions`, `pendingInteractions`, `requireInteraction()`               |
+
+Use `APPROVE_OPTION_ID` (`"approve"`) and `DENY_OPTION_ID` (`"deny"`) from `eve/events` for new approval and budget controls; replace checks for the old `"cancel"` decision. Existing posted platform controls retain their routing encodings. Keep a default branch when switching on interaction kinds or outcomes: v27 can add values without changing its stream version.
+
+## Import paths
+
+| Before                                                            | Now                                                              |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `eve/tools/agent-router`                                          | `eve/tools/agent_router`                                         |
+| `eve/computer-use` and its subpaths                               | `eve/extensions/computer-use` and the matching subpaths          |
+| `eve/self-modification`, `eve/self-modification/local`            | `eve/extensions/self-modification/local`                         |
+| `eve/self-modification/remote`                                    | `eve/extensions/self-modification/remote`                        |
+| `eve/self-modification/config`, `eve/setup`, `eve/setup/scaffold` | No public replacement; these are private implementation modules. |
+| `Datadog` from `eve/evals`                                        | `datadogReporter` from `eve/evals`                               |
+
+## Update event consumers
+
+**Hooks** keep `(event, ctx)`. Change their event keys and use `ctx.view` to query the committed state; `ctx.position` identifies the event. Wildcard (`*`) handlers no longer receive progress records. For example, replace a `message.completed` reply handler with:
+
+```ts
+import { defineHook } from "eve/hooks";
+
+export default defineHook({
+  events: {
+    "content.completed"(event) {
+      if (event.data.phase === "reply") console.log(event.data.value);
+    },
+  },
+});
+```
+
+**Channel `events` handlers** now take `(event, ctx)` instead of `(eventData, channel, ctx)`. Read `event.data`, `event.scope`, and `ctx.channel`. Slack renderers take `(event, ctx, next)`; pass a fact to `next(event)` to continue rendering. A `committed` handler can observe the whole committed line. See [Custom channels](../channels/custom) and [Slack rendering](../channels/slack#customize-rendering).
+
+**Instrumentation** uses `session.ended`, `turn.settled`, `call.requested`/`call.settled`, and `interaction.opened`/`interaction.settled`, with terminal `outcome` instead of separate success/failure event names. `channel.delivery.*` becomes `delivery.consumed`/`delivery.settled`; `step.attempt.*` becomes `model.started`/`model.retried`/`model.settled`. See [Instrumentation](/docs/observability/instrumentation#lifecycle-events).
+
+**Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `reset()` retires the server session. Persist events and cursor as they change so paused turns survive reloads. See [Client streaming](../guides/client/streaming) and [Frontend](../guides/frontend/overview).
+
+**Evals** match v27 facts and use `view` queries. Rename `loadedSkill` to `calledSkill`, `calledSubagent` to `calledAgent`, `noFailedActions` to `noFailedCalls`, and `parked()` to `awaitingInput()`. Use `t.target.attach(id)` instead of `attachSession(id)` and `turn.waitForToolCall()` instead of the old action matcher. See [Evals](../evals/overview).
+
+## Other migration points
+
+- Frontend stores and hooks replace `followIdle` with `followWhile(view)`. Omit `followWhile` to keep following between turns, as `followIdle: true` did. For `followIdle: false`, import `activeTurn` and `idle` from `eve/events` and pass `followWhile: (view) => !idle(view) || activeTurn(view) !== undefined`, which also keeps following a turn waiting on a person. See [Frontend](../guides/frontend/overview).
+- Channel CORS options use `allowHeaders`, `exposeHeaders`, and `preflight.statusCode` instead of `allowedHeaders`, `exposedHeaders`, and `preflightStatus`.
+- Authored channel identity is `channel:<name>`, including route-only channels and the default `channel:eve` (formerly `http`). Check visibility and authorization rules. Move visibility classification from `metadata().audience` to `audience(input)`; without it, audience is `unknown`. Channel context factories take `context(state, channel)`, and continuation aliases live on `channel.continuation`. See [Custom channels](../channels/custom).
+- Session readers have `id` and `stream()`; `sessions.attach(id)` returns a read-only `SessionReader`, not command authority. Use `SessionInfo` from `eve/context` for the metadata in `ctx.session`. A command that cannot reach an active session reports `SessionNotActiveError` (HTTP `409 session_not_active`). See [session handles](./sessions-runs-and-streaming#read-a-session-in-process).
+- `approvalKey` and `ApprovalContext.approvedTools` are removed. Use an `approval` policy for input-dependent decisions. `once()` remembers the latest approval or denial per resolved tool for the session; custom policies must return its decision unchanged to reuse or record consent. See [Tool approvals](/docs/human-in-the-loop).
+- Replace connection auth's `credentialOwner` with `principalType: "app" | "user"`. With `getToken` alone, omitted ownership defaults to `"app"`; set `"user"` for per-user tokens. See [connection credential ownership](/docs/connections#choose-app-vs-user-auth).
+- Dynamic capabilities use `defineDynamic(ctx => value)`, not lifecycle event maps. Replace `defineDurableCallback` and `defineDurableSchema` wrappers with ordinary functions and schemas; put external JSON observations in `ctx.memo(key, fn)`. See [Dynamic capabilities](../guides/dynamic-capabilities).
+- Recalled memory stays outside durable conversation history and is recalled before turns, not during compaction. Remove memory `visibility` options; a failed memory capture now prevents compaction. See [Memory providers](../memory/custom-provider).
+- `grep` lists matching files by default. Set `outputMode: "content"` when the caller needs matching lines; see [Built-in tools](./built-in-tools#grep).
+- Replace `eve remote invoke` with `eve remote connect --print <prompt>` for one-shot requests. Use `eve/client` for scripted multi-turn sessions and answers; see the [CLI reference](../reference/cli#eve-remote-connect).
+- MCP's `input_required` now covers sign-ins as well as approvals and questions. Answer non-sign-in interactions using `responses: [{ interactionId, optionId?, text? }]`; complete sign-ins externally. Direct `invokeTool` calls return call-shaped outcomes, not conversational pauses. See [MCP](../channels/mcp).
+- Remote agent protocol 3 supports relaying interactions. A protocol-3 caller relays a protocol-2 remote agent's approvals, questions, and sign-ins, but a protocol-3 remote agent can't relay them to a protocol-2 caller, so upgrade callers before the remote agents they call. Older peers can still exchange results. See [Upgrading callers and remote agents](../guides/remote-agents#upgrading-callers-and-remote-agents).

package/docs/connections/mcp.mdx

@@ -119,7 +119,7 @@ Use the shared `approval` option to gate every tool served by an MCP connection.
 
 ### Gate specific tools by name or input
 
-A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, toolAnnotations, approvedTools, callId, abortSignal }` and returns an approval status, synchronously or as a promise.
+A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, toolAnnotations, callId, abortSignal }` and returns an approval status, synchronously or as a promise.
 
 This connection always gates deletes, gates a publish only when the call actually schedules a post, and lets everything else through:
 
@@ -141,7 +141,7 @@ export default defineMcpClientConnection({
   url: "https://mcp.example.com/mcp",
   description: "Social publishing: draft, schedule, and manage posts.",
   auth: {
-    credentialOwner: "app",
+    principalType: "app",
     getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }),
   },
   approval: ({ toolName, toolInput }) => {
@@ -182,7 +182,7 @@ export default defineMcpClientConnection({
 
 Annotations are hints from the server, not guarantees. Trust them only as far as you trust the server that sent them.
 
-[Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, how `approvedTools` and `session.auth` factor in, and how a gated call pauses and resumes durably.
+[Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, scoped approval state and `session.auth`, and how a gated call pauses and resumes durably.
 
 ## Forward the caller to an eve agent
 
@@ -221,7 +221,7 @@ Requirements:
 
 ### Handle events
 
-Add `experimental_events` to the connection. In this example, a user asks the agent to "watch the support inbox and draft replies to new bug reports". The model subscribes to Bird's `email_mailbox.message_received` event for that mailbox. Each new email then starts a turn in the same conversation, with instructions to triage it:
+Add `experimental: { events: { ... } }` to the connection. In this example, a user asks the agent to "watch the support inbox and draft replies to new bug reports". The model subscribes to Bird's `email_mailbox.message_received` event for that mailbox. Each new email then starts a turn in the same conversation, with instructions to triage it:
 
 ```ts title="agent/connections/bird.ts"
 import { connect } from "@vercel/connect/eve";
@@ -231,19 +231,21 @@ export default defineMcpClientConnection({
   url: "https://mcp.bird.com/",
   description: "Bird: email, SMS, and contacts. Can watch a mailbox for new mail.",
   auth: connect("bird/bird"),
-  experimental_events: {
-    async onEvent({ event, origin, auth, attachSession }) {
-      if (event.name !== "email_mailbox.message_received") return;
-      await attachSession(origin.sessionId).send(
-        [
-          "A new email arrived in the mailbox you are watching:",
-          JSON.stringify(event.data),
-          "If it is a bug report, look up the sender's earlier threads, draft a reply " +
-            "that says what we know and what happens next, and ask me before sending it. " +
-            "Otherwise, summarize it in one line.",
-        ].join("\n\n"),
-        { auth, turnPolicy: "queue" },
-      );
+  experimental: {
+    events: {
+      async onEvent({ event, origin, auth, attachSession }) {
+        if (event.name !== "email_mailbox.message_received") return;
+        await attachSession(origin.sessionId).send(
+          [
+            "A new email arrived in the mailbox you are watching:",
+            JSON.stringify(event.data),
+            "If it is a bug report, look up the sender's earlier threads, draft a reply " +
+              "that says what we know and what happens next, and ask me before sending it. " +
+              "Otherwise, summarize it in one line.",
+          ].join("\n\n"),
+          { auth, turnPolicy: "queue" },
+        );
+      },
     },
   },
 });
@@ -270,23 +272,25 @@ async onEvent({ event, deliveryId }) {
 ### Handle missed events and ended subscriptions
 
 ```ts
-experimental_events: {
-  async onEvent({ event }) {
-    // ...
-  },
-  async onGap({ origin, auth, attachSession }) {
-    // The server could not deliver every event. Re-read the source.
-    await attachSession(origin.sessionId).send(
-      "Some Bird events were missed. Re-check the mailbox.",
-      { auth },
-    );
-  },
-  async onTerminated({ origin, auth, error, attachSession }) {
-    // The upstream subscription ended. The watch ends when this returns.
-    await attachSession(origin.sessionId).send(
-      `The Bird watch ended: ${error.message}`,
-      { auth },
-    );
+experimental: {
+  events: {
+    async onEvent({ event }) {
+      // ...
+    },
+    async onGap({ origin, auth, attachSession }) {
+      // The server could not deliver every event. Re-read the source.
+      await attachSession(origin.sessionId).send(
+        "Some Bird events were missed. Re-check the mailbox.",
+        { auth },
+      );
+    },
+    async onTerminated({ origin, auth, error, attachSession }) {
+      // The upstream subscription ended. The watch ends when this returns.
+      await attachSession(origin.sessionId).send(
+        `The Bird watch ended: ${error.message}`,
+        { auth },
+      );
+    },
   },
 },
 ```

package/docs/connections/openapi.mdx

@@ -18,7 +18,7 @@ export default defineOpenAPIConnection({
   spec: "https://petstore3.swagger.io/api/v3/openapi.json",
   description: "Pet store inventory and orders.",
   auth: {
-    credentialOwner: "app",
+    principalType: "app",
     getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
   },
 });
@@ -108,7 +108,7 @@ export default defineOpenAPIConnection({
   spec: "https://petstore3.swagger.io/api/v3/openapi.json",
   description: "Pet store inventory and orders.",
   auth: {
-    credentialOwner: "app",
+    principalType: "app",
     getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
   },
   operations: { allow: ["getInventory", "placeOrder"] },
@@ -168,6 +168,27 @@ eve removes `default` and `example` annotations when their values conflict with
 
 Generated operations can mutate state like authored tools. Use the shared connection `approval` option for human approval, and combine it with `operations.allow` for the smallest practical surface. See [Per-connection approval](../connections#per-connection-approval) for the helpers and [Human-in-the-loop](../human-in-the-loop#approvals) for policy behavior.
 
+A custom policy sees each operation under its full tool name, `<connection>__<operationId>` (unlike `providedArguments` callbacks, which get the bare `operationId`). Its `toolInput` is the generated operation input: path, query, header, and cookie parameters as top-level properties, and the request body under `body`. To ask a person only for large orders:
+
+```ts title="agent/connections/petstore.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+  spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+  description: "Pet store inventory and orders.",
+  auth: {
+    credentialOwner: "app",
+    getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }),
+  },
+  operations: { allow: ["getInventory", "placeOrder"] },
+  approval: ({ toolName, toolInput }) => {
+    if (toolName !== "petstore__placeOrder") return "not-applicable";
+    const order = toolInput?.body as { quantity?: number } | undefined;
+    return (order?.quantity ?? 0) >= 10 ? "user-approval" : "not-applicable";
+  },
+});
+```
+
 ## What to read next
 
 - [Connections](../connections): shared auth, headers, approval, and per-caller patterns.

package/docs/connections/overview.mdx

@@ -26,30 +26,35 @@ Read [OpenAPI connections](/docs/connections/openapi) for `defineOpenAPIConnecti
 
 Use `defineDynamic` when the connection set depends on the authenticated user,
 tenant, or another runtime lookup. Import it with the connection factories from
-`eve/connections`, then return one connection definition, a map of definitions,
-or `null` from `session.started` or `turn.started`.
+`eve/connections`. The function returns one connection definition, a map, or `null`.
+Use `ctx.memo` for JSON observations that should stay fixed for a key.
 
 ```ts title="agent/connections/accounts.ts"
 import { defineDynamic, defineMcpClientConnection } from "eve/connections";
-import { listAccounts } from "../lib/accounts";
-
-export default defineDynamic({
-  events: {
-    "session.started": async (_event, ctx) => {
-      const accounts = await listAccounts(ctx.session.auth.current);
-      return Object.fromEntries(
-        accounts.map((account) => [
-          account.slug,
-          defineMcpClientConnection({
-            url: account.mcpUrl,
-            description: account.description,
-            instanceKey: account.id,
-            auth: account.auth,
-          }),
-        ]),
-      );
-    },
-  },
+import { accountAuth, listAccounts } from "../lib/accounts";
+
+export default defineDynamic(async (ctx) => {
+  const userId = ctx.session.auth.current?.principalId;
+  if (!userId) return null;
+  const accounts = await ctx.memo(userId, async () =>
+    (await listAccounts(userId)).map(({ description, id, mcpUrl, slug }) => ({
+      description,
+      id,
+      mcpUrl,
+      slug,
+    })),
+  );
+  return Object.fromEntries(
+    accounts.map((account) => [
+      account.slug,
+      defineMcpClientConnection({
+        url: account.mcpUrl,
+        description: account.description,
+        instanceKey: account.id,
+        auth: accountAuth(account.id),
+      }),
+    ]),
+  );
 });
 ```
 
@@ -57,27 +62,17 @@ For a single returned definition, the filename supplies the connection name.
 For a map, each bare map key becomes a connection name. Every entry must use
 `defineMcpClientConnection` or `defineOpenAPIConnection`. Authenticated entries
 must also set `instanceKey` to a stable, non-secret account or tenant identifier.
+Build connections and auth callbacks outside memos; memos keep only JSON observations.
 See [Dynamic capabilities](/docs/guides/dynamic-capabilities#dynamic-connections)
-for event scope, naming, conflicts, and durable recovery behavior.
-
-Tools from a `turn.started` connection can require approval, including an
-`approval.response` policy. When an approval resumes between turns, eve rebuilds
-the connection callbacks before checking the response policy, even in a fresh
-process. This restoration uses the pending request's turn coordinates and the
-current authenticated session context; it does not emit another public
-`turn.started` event. The response policy still receives the authenticated
-responder separately. When one delivery answers requests from different turns,
-eve restores each candidate's originating connection scope before its policy
-check, then prepares the complete batch selected for tool replay. Keep connection
-resolvers idempotent because restoration can run them again.
-
-Restoration uses current resolver results, not a historical connection snapshot.
-If the tool is absent from the persisted tool metadata, or its required response
-policy is unavailable, eve refuses the response and leaves the request pending.
-eve does not reconstruct missing tool metadata from earlier turns. Before replay, eve checks that the
-approved tool is still available and that its connection identity has not
-changed since the call requested approval. A missing or changed connection
-fails the replay rather than sending the call to a replacement destination.
+for when eve evaluates connections, naming, conflicts, and failure behavior.
+
+Tools from a dynamic connection can require approval, including an
+`approval.response` policy. When an approval resumes, even in a fresh process,
+eve rebuilds the connection from its definition with saved memo results and checks the response
+policy. Before the approved call runs, eve
+checks that the connection's identity has not changed since the call requested
+approval. A changed connection fails the call rather than sending it to a
+replacement destination.
 Request a new tool call and approval after correcting the connection. Identity
 includes the endpoint and `instanceKey`; use a distinct `instanceKey` for each
 account or tenant even when they share an endpoint.
@@ -93,7 +88,7 @@ export default defineMcpClientConnection({
   url: "https://mcp.linear.app/mcp",
   description: "Linear workspace.",
   auth: {
-    credentialOwner: "app",
+    principalType: "app",
     getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
   },
 });
@@ -101,7 +96,7 @@ export default defineMcpClientConnection({
 
 If the token has a known TTL, set `expiresAt` (milliseconds since epoch). Once it expires, eve calls `getToken` again before the next request, including requests on an existing MCP client.
 
-When `getToken` is the only auth, `credentialOwner` defaults to `"app"`: one shared credential keyed across all sessions. Set `credentialOwner: "user"` when each end-user carries their own token.
+When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Set `principalType: "user"` when each end-user carries their own token.
 
 eve resolves and caches connection tokens per step; they never land in conversation history or reach the model.
 
@@ -111,13 +106,13 @@ A connection credential can belong to the agent or to the person using it. This
 
 | Credential owner | Use when                                                                       | Auth shape                                                                                                                                                   |
 | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| App              | The agent should use one shared service, bot, installation, or app credential. | `auth: { getToken }` defaults to `credentialOwner: "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: { credentialOwner: "user", getToken }`.            |
+| 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. |
 
-`credentialOwner: "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.
+`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.
 
-`credentialOwner` is eve's field for raw getToken-only connection auth. Existing non-interactive raw `principalType` definitions still work, but are deprecated. Interactive auth and `connect()` from `@vercel/connect/eve` continue to use `principalType: "user"`; that field also remains correct for route-auth session identities.
+`principalType` selects credential ownership for both raw `getToken` auth and `connect()` from `@vercel/connect/eve`. The retired `credentialOwner` field is rejected. This ownership setting is separate from a route-auth session identity, where `principalType` describes the caller.
 
 ## No auth
 
@@ -159,7 +154,7 @@ export default defineOpenAPIConnection({
   spec: "https://warehouse.example.com/openapi.json",
   description: "The caller's tenant-scoped warehouse.",
   auth: (ctx) => ({
-    credentialOwner: "user",
+    principalType: "user",
     getToken: async () => ({
       token: await tenantToken(ctx.session.auth.current),
     }),
@@ -178,7 +173,7 @@ headers: {
 }
 ```
 
-Use `credentialOwner: "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.
+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
 
@@ -198,6 +193,20 @@ 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 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).
 
+To decide per call, pass your own policy. It receives the same context as a tool's approval policy, with `toolName` set to the connection tool's full name, `<connection>__<tool>`, and `toolInput` set to the input the model sent:
+
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace.",
+  auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
+  approval: ({ toolName }) =>
+    toolName === "linear__delete_comment" ? "user-approval" : "not-applicable",
+});
+```
+
 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.
 
 ## Interactive OAuth via Vercel Connect
@@ -227,13 +236,13 @@ 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.
+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, opens a sign-in (`interaction.opened` with `request.kind: "sign-in"`) 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: `eve__search` never asks for sign-in. 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, so `search` lists such a connection as one result named after the connection, such as `linear`. The model asks for sign-in explicitly, one connection at a time, by calling that name with `eve__tool({ name: "linear" })`; once the user signs in, `eve__search({ query: "linear__" })` returns the connection's tools. Calling a tool with `eve__tool` 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.
+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 withdraws the sign-in, its interaction settles `withdrawn`, 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.
 
-When a local subagent needs interactive authorization, eve surfaces the authorization lifecycle on the root session's channel, including through nested subagent chains. The challenge still points to the child session's callback, so completing it resumes the child directly while the parent continues waiting for its result. The parent's turn stays open: it emits `turn.waiting` after the proxied `authorization.required` and resumes under the same `turnId` once the subagent returns.
+When a local subagent needs interactive authorization, eve surfaces the authorization lifecycle on the root session's channel, including through nested subagent chains. The challenge still points to the child session's callback, so completing it resumes the child directly while the parent continues waiting for its result. The parent's turn stays open: the relayed sign-in is the parent's own `interaction.opened`, and the turn resumes under the same `turnId` once the subagent returns.
 
 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"`.
 
@@ -257,14 +266,14 @@ App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app t
 | 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 use `connect({ connector, principalType: "app" })` if the Connect credential 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.                                                                    |
+| A sign-in `interaction.opened` 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.                                  |
 | Sign-in ends on a Vercel login or protection page | The deployment is behind Deployment Protection, and sign-in callback URLs never carry the automation bypass secret.               | Have the user sign in to Vercel with access to the project, or add a Deployment Protection Exception for the domain.                                            |
 
 ## Self-hosted interactive OAuth
 
-To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`; `credentialOwner` applies only to getToken-only auth, and the factory pins the interactive value for you.
+To run your own OAuth, use `defineInteractiveAuthorization` from `eve/connections`, which takes a three-method form and needs no Vercel Connect. eve mints a callback URL, parks (durably suspends) the turn on a framework-owned webhook, and resumes once the token comes back. Interactive auth is always `principalType: "user"`; the factory pins that value for you.
 
 ```ts title="agent/connections/linear.ts"
 import {
@@ -306,7 +315,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-`getToken` runs before every tool call. eve does not store tokens for you: the token returned from `completeAuthorization` is reused only within the current workflow step, so it never lands in durable session state. Save it in `completeAuthorization` (or let your OAuth provider keep it) and read it back in `getToken`. If `getToken` cannot find the token on a later call, eve asks the user to sign in again. `startAuthorization` and `completeAuthorization` are both-or-neither: provide one without the other and you get a definition error. The `challenge` rides along verbatim on the `authorization.required` event. Its fields:
+`getToken` runs before every tool call. eve does not store tokens for you: the token returned from `completeAuthorization` is reused only within the current workflow step, so it never lands in durable session state. Save it in `completeAuthorization` (or let your OAuth provider keep it) and read it back in `getToken`. If `getToken` cannot find the token on a later call, eve asks the user to sign in again. `startAuthorization` and `completeAuthorization` are both-or-neither: provide one without the other and you get a definition error. The `challenge`'s public fields appear on the sign-in's `interaction.opened`, in `request.signIn`. Its fields:
 
 | Field          | Purpose                                                                                   |
 | -------------- | ----------------------------------------------------------------------------------------- |
@@ -331,8 +340,8 @@ channels fall back to title-casing the connection name when neither is set.
 
 Two error classes drive the consent flow. Throw them from `getToken` or `completeAuthorization`; both are exported from `eve/connections`.
 
-- `ConnectionAuthorizationRequiredError(connectionName)`: the user must authorize. Throw it from `getToken` to emit `authorization.required` and kick off the flow.
-- `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: authorization failed. `reason` is a stable machine-readable code (e.g. `"access_denied"`) that shows up on the `authorization.completed` event and the failed tool result. `retryable` defaults to `true`; set it to `false` for terminal cases like user denial. The `authorization.completed` event then carries `retryable: false`, and a later tool call in the same turn that needs the same grant for the same principal fails with that failure instead of asking the user to sign in again. The next turn asks again.
+- `ConnectionAuthorizationRequiredError(connectionName)`: the user must authorize. Throw it from `getToken` to open a sign-in (`interaction.opened` with `request.kind: "sign-in"`) and kick off the flow.
+- `ConnectionAuthorizationFailedError(connectionName, { reason?, retryable? })`: authorization failed. `reason` is a stable machine-readable code (e.g. `"access_denied"`) that shows up as the sign-in's `interaction.settled` reason and on the failed tool result. `retryable` defaults to `true`; set it to `false` for terminal cases like user denial. The sign-in's `interaction.settled` then carries `response.retryable: false`, and a later tool call in the same turn that needs the same grant for the same principal fails with that failure instead of asking the user to sign in again. The next turn asks again.
 
 ```ts
 import { ConnectionAuthorizationFailedError } from "eve/connections";