eve 0.83.2 → 0.84.0

package/docs/guides/hooks.md

@@ -15,8 +15,9 @@ export default defineHook({
     async "session.started"(_event, ctx) {
       console.info("session started", { sessionId: ctx.session.id });
     },
-    async "message.completed"(event) {
-      console.info("model finished", { length: event.data.message?.length ?? 0 });
+    async "content.completed"(event) {
+      if (event.data.phase !== "reply" || event.data.kind !== "text") return;
+      console.info("reply part", { length: String(event.data.value ?? "").length });
     },
   },
 });
@@ -26,7 +27,7 @@ The slug is the path-relative basename. `agent/hooks/audit.ts` becomes `"audit"`
 
 `defineHook`, `HookDefinition`, and `HookContext` live on `eve/hooks`.
 
-A hook file declares stream-event subscribers under the `events` map, keyed by event type, with `*` matching every event. Subscribe to any event in the runtime stream vocabulary documented in [Sessions, runs and streaming](../concepts/sessions-runs-and-streaming), including the lifecycle events `session.started`, `turn.completed`, `message.completed`, `action.partial`, and `action.result`. Handlers are observe-only. They cannot inject model context. To contribute runtime model messages, use `defineDynamic` and `defineInstructions` in `agent/instructions/`.
+A hook file declares stream-event subscribers under the `events` map, keyed by fact type, with `*` matching every fact. Subscribe to any fact in the v27 catalog documented in [Sessions, runs and streaming](../concepts/sessions-runs-and-streaming), such as `session.started`, `turn.settled`, `content.completed`, and `call.settled`. Progress records (`content.delta`, `call.input`, `call.progress`) reach only handlers keyed on their type, never `*`. Handlers can call external services and cancel the running turn. They cannot inject model context. To contribute runtime model messages, use `defineDynamic` and `defineInstructions` in `agent/instructions/`.
 
 ## Scope side effects to a channel
 
@@ -37,11 +38,12 @@ import { githubChannel } from "eve/channels/github";
 
 export default githubChannel({
   events: {
-    async "turn.completed"(event, channel, ctx) {
-      console.info("GitHub turn completed", {
-        repository: channel.repository.fullName,
+    async "turn.settled"(event, ctx) {
+      console.info("GitHub turn settled", {
+        outcome: event.data.outcome,
+        repository: ctx.channel.repository.fullName,
         sessionId: ctx.session.id,
-        turnId: event.turnId,
+        turnId: event.data.turnId,
       });
     },
   },
@@ -68,7 +70,7 @@ export default defineHook({
 });
 ```
 
-A route-only `defineChannel` with no event handlers keeps the kind `"http"`, so `isChannel` does not match it in a hook. Compare `ctx.channel.kind === "http"` for those channels instead.
+Route-only channels use the same path-derived identity, even when they have no event handlers. Use `isChannel` with the authored channel definition rather than checking for the former `"http"` kind.
 
 For typed channel metadata in dynamic resolvers or instrumentation, narrow with `isChannel` the same way; see [OpenTelemetry runtime context](../observability/otel#add-runtime-context).
 
@@ -81,7 +83,15 @@ helpers documented in [Session context](./session-context):
 interface HookContext extends SessionContext {
   readonly agent: { readonly name: string; readonly nodeId?: string };
   readonly channel: { readonly kind?: string; readonly continuationToken?: string };
-  cancel(): void;
+  /** Where the event sits on the stream: its line, and its index in that line. */
+  readonly position: { readonly line: number; readonly index: number };
+  /** Immutable session snapshot as of the whole commit the event is in. */
+  readonly view: SessionView;
+  readonly turn: DynamicTurn | null;
+  readonly now: Date;
+  readonly occurrence: { readonly idempotencyKey: string; readonly abortSignal: AbortSignal };
+  readonly memo: Memo;
+  cancel(reason?: string): void;
 }
 ```
 
@@ -93,7 +103,7 @@ import { defineHook } from "eve/hooks";
 
 export default defineHook({
   events: {
-    async "turn.completed"(_event, ctx) {
+    async "turn.settled"(_event, ctx) {
       const sandbox = await ctx.getSandbox();
       await sandbox.stop();
     },
@@ -107,35 +117,45 @@ handle can also automatically resume on later I/O. A hook failure, including a
 failed stop, follows the normal
 [hook failure behavior](#what-happens-when-a-hook-throws).
 
-For `task.started`, `task.settled`, and `agent.started`, `ctx.session.id`
+`ctx.turn` is the latest turn, including a settled one, or `null` before the first turn. `ctx.now` is the commit time. `ctx.memo(key, fn)` follows the [dynamic-value memo rules](./dynamic-capabilities#memo-rules). Hooks do not receive assembled conversation history.
+
+`ctx.view` is the session's state as of the event's whole commit, folded by the same code as
+`eve/events`. Read what changed from the event, and where things stand from the view: for
+example, `call(ctx.view, event.data.callId)` from `eve/events` on a `call.settled` returns its
+name, kind, input, output, and state. The view has no public tables; queries return immutable
+observations. A retained snapshot stays unchanged after later events.
+
+For `task.started`, `task.ended`, and `child.opened`, `ctx.session.id`
 identifies the session that started the task or opened the subagent session.
 Typed handlers and `*` handlers receive this context even when the event
 arrives between turns. These hooks can use `ctx.getSandbox()` against that
 session. Session state and sandbox changes they make are kept for the
-session's next turn. `agent.started` appears when the child session opens, or
-when the parent's current model step ends if one is running.
+session's next turn. `child.opened` appears when the child session opens.
 
 ### Narrowing tool results
 
-`toolResultFrom` narrows an `action.result` event to a specific authored tool or connection (MCP or OpenAPI) and returns typed output. Import it from `eve/tools`:
+`toolResultFrom` narrows a settled call to a specific authored tool or connection (MCP or OpenAPI) and returns typed output. Pass it the observation from `call(ctx.view, callId)`, which carries the call's name, kind, state, and output. Import it from `eve/tools`:
 
 ```ts
 import { defineHook } from "eve/hooks";
 import { toolResultFrom } from "eve/tools";
+import { call } from "eve/events";
 import getWeather from "../tools/get-weather";
 import linear from "../connections/linear";
 
 export default defineHook({
   events: {
-    "action.result"(event) {
+    "call.settled"(event, ctx) {
+      const observed = call(ctx.view, event.data.callId);
+
       // Authored tool: output is typed as the tool's return type
-      const weather = toolResultFrom(event.data.result, getWeather);
+      const weather = toolResultFrom(observed, getWeather);
       if (weather) {
         console.log(weather.output.temperature);
       }
 
       // Connection: output is unknown, toolName is qualified
-      const linearResult = toolResultFrom(event.data.result, linear);
+      const linearResult = toolResultFrom(observed, linear);
       if (linearResult) {
         console.log(linearResult.connectionToolName, linearResult.output);
       }
@@ -144,22 +164,23 @@ export default defineHook({
 });
 ```
 
-Returns `undefined` when the result doesn't match, or when `isError` is `true`. For authored tools the return includes `{ output, toolName, callId }` with `output` typed as the tool's `TOutput`. For connections it includes `{ output, toolName, connectionToolName, callId }` with `output` as `unknown`.
+Returns `undefined` when the call doesn't match, or when it didn't complete. For authored tools the return includes `{ output, toolName, callId }` with `output` typed as the tool's `TOutput`. For connections it includes `{ output, toolName, connectionToolName, callId }` with `output` as `unknown`.
 
-This works for a mounted extension's tools too — import the tool from the extension's `./tools` export and pass it. `toolResultFrom` matches the namespaced result (`crm__search`) because it keys off the tool definition, not the name:
+This works for a mounted extension's tools too — import the tool from the extension's `./tools` export and pass it. `toolResultFrom` matches the namespaced call (`crm__search`) because it keys off the tool definition, not the name:
 
 ```ts
 import { search } from "@acme/crm/tools";
+import { call } from "eve/events";
 
-// inside "action.result":
-const crmSearch = toolResultFrom(event.data.result, search); // typed; matches crm__search
+// inside "call.settled":
+const crmSearch = toolResultFrom(call(ctx.view, event.data.callId), search); // typed; matches crm__search
 ```
 
-When one definition is mounted under more than one tool name, for example when a subagent re-exports an extension tool, `toolResultFrom` matches results from every mounted name.
+When one definition is mounted under more than one tool name, for example when a subagent re-exports an extension tool, `toolResultFrom` matches calls from every mounted name.
 
 ### Persist events to your own database
 
-Every event carries a `meta` envelope with `meta.id`, a unique, sortable identifier for that event. It makes a natural primary key for an events table:
+Every event a hook receives has its stream position as `ctx.position`. A position never changes, so `(session, line, index)` makes a natural primary key for an events table:
 
 ```ts title="agent/hooks/persist.ts"
 import { defineHook } from "eve/hooks";
@@ -168,53 +189,44 @@ export default defineHook({
   events: {
     async "*"(event, ctx) {
       await db.query(
-        `insert into agent_events (id, session_id, type, data, emitted_at)
+        `insert into agent_events (session_id, line, index, type, data)
          values ($1, $2, $3, $4, $5)
-         on conflict (id) do nothing`,
-        [
-          event.meta.id,
-          ctx.session.id,
-          event.type,
-          "data" in event ? event.data : null,
-          event.meta.at,
-        ],
+         on conflict (session_id, line, index) do nothing`,
+        [ctx.session.id, ctx.position.line, ctx.position.index, event.type, event.data],
       );
     },
   },
 });
 ```
 
-`meta.id` is stable for the life of the persisted event, so a consumer that re-reads the stream can ingest the same event twice safely. It is not a retry guard for the hook itself: if a step is interrupted and re-runs, the turn re-emits its events as _new_ events with new ids, and your hook runs again for each one.
+A consumer that re-reads the stream gets the same positions, so the key above deduplicates ingestion. If a step is interrupted after publishing but before checkpointing, its retry does not run hooks again for what it already published. New recovery facts run their hooks normally. Some handlers may already have run while others never ran; this is not an exactly-once effect guarantee.
 
-What to key on instead depends on what you are protecting:
+Pass `ctx.occurrence.idempotencyKey` to services that support idempotency. It identifies this handler's fact position. For one effect per turn or call, use that resource's identity instead, such as `turnId` or `callId`. Effects such as one alert per session still need author-managed durable state. `ctx.memo` caches observations, not effect receipts; its records can be discarded on deployment changes.
 
-- **A side effect that must happen once per turn or step** — a charge, an email, a ticket — keys well on the coordinates in `event.data` (`turnId`, `stepIndex`, `sequence`). A retry restores those from the step's input, so the second attempt computes the same key and your gate holds.
-- **Stored content should not key on those coordinates.** The retry re-invokes the model, so one coordinate can carry different text on each attempt. `on conflict (turn_id, step_index, sequence) do nothing` would keep the abandoned attempt and drop the one that finished. Key on `meta.id`, and accept that an interrupted turn leaves both attempts in the table.
-
-Behind that split is an asymmetry worth knowing: durable history keeps only the attempt that completed, while the event stream keeps every attempt, and no field marks which is which. Hooks are at-least-once, and no key collapses a retry.
-
-See [the event envelope](../concepts/sessions-runs-and-streaming#the-event-envelope) for the full contract.
+See [Positions](../concepts/sessions-runs-and-streaming#positions) for the full contract.
 
 ## Execution order
 
-When a session publishes a stream event while it runs, the step that owns the session does four things in order:
+Each committed line is published in this order:
 
-1. Channel delivery. The channel adapter handler runs.
-2. Write. The event is stamped with its `meta` envelope, then written to the durable stream.
+1. Write. The line is written to the durable stream.
+2. Channel delivery. The channel adapter handler runs for each fact.
 3. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
-4. Model preparation, for model lifecycle events. Dynamic resolvers subscribed to those events update the model context. Subagent notifications do not run model preparation.
+4. Cancellation requests queued by `ctx.cancel()` take effect after the handlers return.
+
+Before an ordinary model call, dynamic functions compute the model and capabilities from the latest committed session. They do not subscribe to events.
 
-Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent. The persisted event and every hook observe the same `meta.id`.
+Hooks always run after the line is durably recorded, so if a hook throws, the stream stays consistent.
 
 ## What happens when a hook throws
 
-eve logs a thrown or rejected handler with the hook slug, subscription, event type, event ID, and session ID, then runs the remaining subscribers in order. The current turn, subagent notification, and session continue. This applies to every stream-event hook, including `turn.started`, `step.started`, and failure events. Throwing from a hook does not reject work or veto a turn. To stop the running turn, call [`ctx.cancel()`](#cancel-the-running-turn-from-a-hook).
+An unhandled error fails the running turn before its next model call or as it would settle. Between turns there is no active turn to fail, so eve logs the error without changing an earlier outcome. Catch errors from optional audit or metrics work if the turn should continue. To stop without a failure, call [`ctx.cancel(reason?)`](#cancel-the-running-turn-from-a-hook).
 
-A hook failure does not trigger a retry. State changes and external side effects made before the exception are not rolled back. If a side effect needs retries or compensation, handle that inside the hook. Runtime failures outside the authored handler, such as failures setting up context or persisting state, still propagate. If persisting state after a `task.started`, `task.settled`, or `agent.started` event fails, the workflow runtime retries the publishing step, which can publish the event again.
+A hook failure does not trigger a retry. State changes and external side effects made before the exception are not rolled back. If a side effect needs retries or compensation, handle that inside the hook. Runtime failures outside the authored handler, such as failures setting up context or persisting state, still propagate. If a published fact outlives its step's checkpoint, the step's retry does not run the hook again.
 
 ## Cancel the running turn from a hook
 
-Call `ctx.cancel()` when a hook finds that the turn cannot proceed. For example, a `turn.started` hook that cannot load the caller's credentials can stop the turn before the model runs, instead of letting every tool call fail:
+Call `ctx.cancel(reason?)` when a hook finds that the turn cannot proceed. For example, a `turn.started` hook that cannot load the caller's credentials can stop the turn before the model runs, instead of letting every tool call fail:
 
 ```ts title="agent/hooks/require-credentials.ts"
 import { defineHook } from "eve/hooks";
@@ -230,28 +242,28 @@ export default defineHook({
           error,
           sessionId: ctx.session.id,
         });
-        ctx.cancel();
+        ctx.cancel("Workspace credentials are unavailable.");
       }
     },
   },
 });
 ```
 
-The remaining subscribers for the event still run. Then eve cancels the turn the same way [`session.cancel()`](./client/streaming) does: in-flight model and tool work is aborted, delegated child turns are cancelled, and the turn ends with `turn.cancelled` followed by `session.waiting`. No failure event is emitted. A cancel from `turn.started` or `step.started` takes effect before that model call. In a conversation, the next message starts a new turn. A delegated task reports the cancellation to its caller.
+The remaining subscribers for the event still run. Then eve cancels the turn the same way [`session.cancel()`](./client/streaming) does: in-flight model and tool work is aborted, delegated child turns are cancelled, and the turn settles with `outcome: "cancelled"` and `cause: { hook }` naming the hook. No failure is recorded. A cancel from `turn.started` or `model.requested` takes effect before that model call. In a conversation, the next message starts a new turn. A delegated task reports the cancellation to its caller.
 
-A plain-text message that answers a pending question, such as one from `ask_question`, is recorded as `message.received` before eve delivers it. Calling `ctx.cancel()` from that event's hook cancels the turn instead: the question resolves as `cancelled`, and the waiting tool call never receives the text.
+A plain-text message that answers a pending question, such as one from `ask_question`, is recorded as `delivery.consumed` before eve delivers it. Calling `ctx.cancel()` from that event's hook cancels the turn instead: the question settles as `interrupted`, and the waiting tool call never receives the text.
 
-The same goes for the `action.partial` a workflow tool reports while the turn waits on it: `ctx.cancel()` from its hook cancels the turn, and the run's result never reaches the model.
+The same goes for the `call.progress` a workflow tool reports while the turn waits on it: `ctx.cancel()` from its hook cancels the turn, and the run's result never reaches the model.
 
-`ctx.cancel()` returns `void` rather than a promise. The turn stops after the hook returns, so there is nothing to await. Call it before the handler's promise settles: eve ignores a call from work the handler does not await and logs a warning.
+`ctx.cancel()` returns `void` rather than a promise. The turn stops after the hook returns, so there is nothing to await. Call it before the handler's promise settles: a call from work the handler did not await throws. A cancel counts only if the handler returns: a handler that calls `ctx.cancel()` and then throws fails the turn instead.
 
-`ctx.cancel()` only stops a running turn. eve logs a warning and ignores the call on `step.failed`, `turn.completed`, `turn.failed`, `turn.cancelled`, `turn.waiting`, `session.waiting`, `session.completed`, `session.failed`, `context.cleared`, `task.started`, `task.settled`, and `agent.started`, and during clear or compact requests.
+`ctx.cancel()` targets the turn being processed, including while its input is being admitted. Calls between turns without an incoming turn do nothing. Repeated requests cancel that turn only once; they never cancel a later turn. Hook-side `ctx.compact` and `ctx.once` are not available. Client and channel session compaction APIs are unchanged.
 
 ## Subagent isolation
 
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks fire only inside the subagent scope. Parent-agent hooks do not fire for subagent turns, and subagent hooks see only the subagent's own context.
 
-Interactive events such as `input.requested` and `authorization.required` are also published on the parent stream. Parent hooks observe these events after the parent channel handler and stream write, with the parent's session, agent, and channel context. The event retains the child's turn coordinates, so `event.data.turnId` can differ from `ctx.session.turn.id`. A proxied `input.requested` also carries `event.data.callId`, the parent call that waits on it. The parent follows a proxied `input.requested` or `authorization.required` with `turn.waiting` for its own open turn, which stays open until the running call finishes. A proxied `authorization.completed` is not followed by a parent turn event. These parent events also invoke parent hooks; they do not resolve pending input requests.
+A subagent's approvals, questions, and sign-ins are also relayed to the parent stream, as the parent's own `interaction.opened` facts. Parent hooks observe them after the stream write, with the parent's session, agent, and channel context. A relayed interaction's `subject` names the parent call that waits on it, and its `origin` names the child session and request that asked, with `origin.call` naming the child's call. When the parent's turn is paused on that child, the relayed request pauses it on the person too. The child's settlement is relayed as the parent's `interaction.settled`.
 
 ## Hook vs tool vs provider
 

package/docs/guides/instrumentation/instrumentation.mdx

@@ -23,18 +23,18 @@ agent/instrumentation/
   audit.ts  lifecycle instrumentation
 ```
 
-This instrumentation records tool timing and identity without receiving tool
-arguments or results:
+This instrumentation measures the time from a call being requested until it
+settles, including any approval wait, without receiving arguments or results:
 
 ```ts title="agent/instrumentation/audit.ts"
 import { defineInstrumentation } from "eve/instrumentation";
 
 export default defineInstrumentation({
   events: {
-    "tool.call.started": (event, ctx) => {
+    "call.requested": (event, ctx) => {
       ctx.state.set({ name: event.toolName, startedAt: Date.now() });
     },
-    "tool.call.completed": (event, ctx) => {
+    "call.settled": (event, ctx) => {
       const started = ctx.state.get() as { name: string; startedAt: number } | undefined;
       if (started === undefined) return;
 
@@ -76,8 +76,8 @@ export default defineInstrumentation({
     "model.call.started": (event) => {
       console.log("input", event.input);
     },
-    "model.call.completed": (event) => {
-      console.log("output", event.content);
+    "model.call.settled": (event) => {
+      if (event.outcome === "completed") console.log("output", event.content);
     },
   },
 });
@@ -99,8 +99,9 @@ trace. It includes input and output content in these cases:
 
 Return `{ emit: false }` to not sample the trace for this file. Return
 `{ emit: true, recordInputs, recordOutputs }` to choose the two content
-directions explicitly. Inputs include model prompts, tool arguments, channel
-input, and user responses. Outputs include model responses, tool results,
+directions explicitly. Inputs include model prompts, tool arguments, call labels,
+channel input, and user responses. Labels follow the input policy because they can contain
+input-derived text. Outputs include model responses, tool results,
 requests for user input, model provider metadata, and error details. Omitted
 content fields are unavailable to the handler.
 
@@ -123,11 +124,11 @@ export default defineInstrumentation({
     recordOutputs: false,
   }),
   events: {
-    "tool.call.started": async (event) => {
+    "call.requested": async (event) => {
       await sendAuditRecord({
         id: event.idempotencyKey,
         input: redactApiKey(event.input),
-        kind: event.kind,
+        kind: event.capability.kind,
         name: event.toolName,
       });
     },
@@ -151,28 +152,33 @@ Prefer `recordInputs: false` or `recordOutputs: false` when the destination does
 
 ## Lifecycle events
 
-`defineInstrumentation({ events })` supports the following event names. A
-start and its terminal event share an `idempotencyKey`; use it as a stable
-operation key when upserting records across replays.
+Lifecycle events derived from session facts use the same names and outcomes as
+the stream. For example, `turn.settled` carries the turn's `outcome`. Match an
+operation's start and terminal events by their shared `idempotencyKey` when
+upserting records across replays.
 
-| Lifecycle        | Events                                                                                                            | Meaning                                                                                                                                                                                |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session          | `session.started`, `session.waiting`, `session.completed`, `session.failed`                                       | Track a session from creation through suspension or termination. `session.waiting` is resumable; `session.completed` and `session.failed` are terminal.                                |
-| Turn             | `turn.started`, `turn.completed`, `turn.cancelled`, `turn.failed`                                                 | Track one turn. Cancellation is not a failure and commonly leaves the session waiting for another turn.                                                                                |
-| Channel delivery | `channel.delivery.started`, `channel.delivery.completed`, `channel.delivery.cancelled`, `channel.delivery.failed` | Track an inbound channel delivery while eve processes its turn. These events are emitted when the channel provides delivery metadata.                                                  |
-| Step attempt     | `step.attempt.started`, `step.attempt.completed`, `step.attempt.failed`, `step.attempt.metadata`                  | Track each model-step attempt; retries have separate attempts. `step.attempt.metadata` is emitted after a step only when the AI SDK supplies provider metadata.                        |
-| Model call       | `model.call.started`, `model.call.completed`, `model.call.failed`                                                 | Track an individual call to the model provider. Completion includes usage and finish reason; content fields follow the trace policy.                                                   |
-| Tool call        | `tool.call.started`, `tool.call.completed`, `tool.call.failed`                                                    | Track a tool, skill load, local subagent, or remote-agent call through durable settlement. A failed event's `outcome` distinguishes failure, rejection, cancellation, and abandonment. |
-| User input       | `input.requested`, `input.resolved`                                                                               | Track a question, tool approval, or session-limit request and its resolution. The resolution includes an outcome such as `answered`, `approved`, `denied`, or `cancelled`.             |
-| Memory operation | `memory.operation.started`, `memory.operation.completed`, `memory.operation.failed`                               | Track a memory-store search or write. Events include the operation name, phase, and memory slot; completion may include a record count and records.                                    |
+| Lifecycle        | Events                                                 | Meaning                                                                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session          | `session.started`, `session.ended`                     | Session creation and end. `session.ended.outcome` is `completed` or `failed`.                                                                                                                                    |
+| Turn             | `turn.started`, `turn.settled`                         | Turn work. `outcome` is `completed`, `cancelled`, or `failed`; a cancelled turn is not a failure.                                                                                                                |
+| Delivery         | `delivery.consumed`, `delivery.settled`                | The committed delivery facts. Settlement includes `outcome`: `handled`, `awaiting-input`, `applied`, `ignored`, `refused`, or `failed`. Channel metadata is on consumption when available.                       |
+| Model run        | `model.started`, `model.retried`, `model.settled`      | Each attempt of a model run. `model.retried` ends a failed attempt before another try; `model.settled.outcome` is `completed`, `failed`, `interrupted`, `abandoned`, or `cancelled` when the turn was cancelled. |
+| Provider call    | `model.call.started`, `model.call.settled`             | An individual provider call; one model attempt can make several. Settlement has `outcome: "completed"` or `"failed"`; completion carries usage, finish reason, and optional `providerMetadata`.                  |
+| Call             | `call.requested`, `call.settled`                       | A tool, skill, or agent call, including direct `invokeTool` calls. `capability` identifies its kind and name. Settlement carries `completed`, `failed`, `rejected`, `interrupted`, or `abandoned`.               |
+| User input       | `interaction.opened`, `interaction.settled`            | A question, approval, or budget prompt, keyed by `interactionId`. Settlement includes the interaction's `outcome` and, when recorded, its `answer`.                                                              |
+| Memory operation | `memory.operation.started`, `memory.operation.settled` | A memory search or write, with operation name, phase, and slot. Settlement has `outcome: "completed"` or `"failed"`.                                                                                             |
 
-Each call emits one `tool.call.*` lifecycle to authored providers. SDK execution callbacks do not emit a second lifecycle. Tool calls can remain open across approvals, parked turns, and worker replacement.
+A delivery that pauses for a person settles `awaiting-input`; resumed work belongs to the answer's delivery. OTel attributes a turn to a delivery only when exactly one delivery was consumed. Event `scope` includes session and run coordinates; `turnId` can be absent for compaction or direct calls. Treat `idempotencyKey` as opaque.
 
-For local and remote subagents, `tool.call.completed` and `tool.call.failed` include the child turn's `usage` directly. Token counts are always present when the child reports usage; `usage.costUsd` is present only when the model provider reports a price.
+Use `InstrumentationEvent<"model.call.settled">` from `eve/instrumentation` when typing a
+standalone handler. Model input content is `unknown`: the messages are the provider's request
+messages, not an eve conversation-message schema. Narrow that content before reading it.
 
-When a tool throws and outputs are recorded, `tool.call.failed` carries an `Error` with the thrown error's `name` and `message`, so a provider can classify the failure by `error.name`. It is rebuilt from the durable session record rather than being the object the tool threw, so `instanceof` checks against your own error classes do not match.
+Each call emits one `call.*` lifecycle; SDK callbacks do not duplicate it. A subagent's `call.settled` includes its reported usage. A thrown tool error is reconstructed from the durable record, so don't use `instanceof` to classify it; inspect `error.name` instead.
 
-When upgrading, replace `action.started`, `action.completed`, and `action.failed` handlers with their `tool.call.*` equivalents. Read `event.toolName` instead of `event.name` on start events. The OpenTelemetry trace schema remains version 4.
+When upgrading, use each operation's terminal event and inspect its `outcome` instead of subscribing to separate completion and failure events. See the [v27 event mapping](/docs/concepts/upgrade-to-v27-events#event-mapping). Provider metadata moved to `model.call.settled`. Replace step indices and encoded attempt IDs with `runId` and `attempt`; use `capability` for call kind and name. Channel types and `isChannel` now come from `eve/channels`. Runtime-context resolvers receive `run: { id, attempt }` instead of `step.index`.
+
+The OpenTelemetry trace schema remains version 4: span names, attributes, and span events are unchanged.
 
 Handlers from different files run concurrently and are failure-isolated. Do
 not depend on execution order. Use `flush` to drain buffered records and

package/docs/guides/instrumentation/otel.mdx

@@ -138,7 +138,7 @@ For typed channel metadata, import the channel definition and narrow with
 `isChannel`:
 
 ```ts title="agent/instrumentation/support.ts"
-import { isChannel } from "eve/instrumentation";
+import { isChannel } from "eve/channels";
 import { otelIntegration } from "eve/instrumentation/otel";
 
 import supportChannel from "../channels/support";
@@ -155,7 +155,9 @@ export default otelIntegration({
 });
 ```
 
-The resolver receives the channel, session, final model input, step, and turn.
+The resolver receives the channel, session, final model input, `run: { id, attempt }`, and
+optional turn. Its input type is `InstrumentationModelStartedInput` from `eve/instrumentation`.
+Model input content is `unknown`; narrow provider-specific messages before reading them.
 Keys beginning with `eve.` are reserved. Content excluded by
 `otel({ tracePolicy })` is not available to the resolver.