eve 0.83.2 → 0.84.0

package/docs/channels/custom.mdx

@@ -11,6 +11,8 @@ Custom channels live in `agent/channels/` at the root agent or in an [extension]
 
 The channel file stem becomes the channel id, so `agent/channels/internal-webhook.ts` is addressed as `internal-webhook`. Export the channel definition as the module's default export.
 
+Hooks, instrumentation, and `delivery.admitted.data.source.channel` identify an authored channel as `channel:<name>`, including channels that only declare routes. Use `isChannel(ctx.channel, importedChannel)` from `eve/channels` to match a channel in a hook.
+
 ## Define a channel
 
 Pass the platform's conversation identity to each operation:
@@ -28,8 +30,8 @@ export default defineChannel({
         return Response.json(await source.reset({ reason: "User requested /new" }));
       }
 
-      const session = await source.send(body.message, { auth: null });
-      return Response.json({ sessionId: session.id });
+      const delivery = await source.send(body.message, { auth: null });
+      return Response.json(delivery, { status: 202 });
     }),
 
     POST("/threads/:threadId/cancel", async (_request, { from, params }) =>
@@ -42,8 +44,26 @@ export default defineChannel({
       Response.json(await from(params.threadId).clear()),
     ),
 
-    GET("/sessions/:sessionId/stream", async (_request, { attachSession, params }) => {
-      const stream = await attachSession(params.sessionId).getEventStream();
+    GET("/sessions/:sessionId/stream", async (request, { attachSession, params }) => {
+      const iterator = attachSession(params.sessionId)
+        .stream({ signal: request.signal })
+        [Symbol.asyncIterator]();
+      // This custom event-NDJSON route is not the built-in eve/client wire endpoint.
+      // Read before sending headers so stranded-session errors reach the route.
+      const first = await iterator.next();
+      let firstPending = true;
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          const next = firstPending ? first : await iterator.next();
+          firstPending = false;
+          if (next.done) controller.close();
+          else controller.enqueue(encoder.encode(JSON.stringify(next.value) + "\n"));
+        },
+        async cancel() {
+          await iterator.return?.();
+        },
+      });
       return new Response(stream, {
         headers: { "content-type": "application/x-ndjson; charset=utf-8" },
       });
@@ -51,8 +71,8 @@ export default defineChannel({
   ],
 
   events: {
-    "message.completed"(event, _channel, ctx) {
-      console.log(ctx.session.id, event.message);
+    "content.completed"(event, ctx) {
+      if (event.data.phase === "reply") console.log(ctx.session.id, event.data.value);
     },
   },
 });
@@ -68,36 +88,25 @@ Each route receives these operation surfaces:
 - `to(channel, target).send(message, options)` hands work to another authored channel.
 - `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
 - `describe()` returns the agent's name, description, the compiled tools a caller can run outside a turn, with their JSON schemas, and the compiled skills, each with its `name` and `description`, sorted by name. It reads the compiled manifest only, never a skill file, and carries no other paths, config, or inspection detail, so a channel can publish it to its callers. Tools that need a turn (framework tools, workflow and provider tools, tools without `execute`) and tools and skills added by dynamic resolvers or subagents are left out.
-- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox, just-bash, or a custom provider that sets `toolSessions: true`, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It resolves to `completed` with the tool's output, or to `invalid-input`, `denied`, `failed`, `approval-required` when the tool's approval policy asks a person (the tool did not run), or `authorization-required` with the connections the tool needs a sign-in to.
+- `invokeTool(name, input, { auth, key })` runs one of those tools as `auth`, outside any conversation: no model, turn, or workflow run. Authored state starts from its initial value and is not kept. Without `key`, each call gets its own session, and a sandbox the tool opens is deleted when the call ends. With `key` (1 to 512 characters), calls from the same `auth` principal with the same key share a session id and a sandbox, which is kept between calls; this needs Vercel Sandbox, just-bash, or a custom provider that sets `toolSessions: true`, and an authenticated `auth` (a keyed call from the anonymous principal is `denied`); see [MCP tool sessions](./mcp#tool-sessions). When a trusted forwarder asserted `auth`, pass the principal your route verified as `forwardedBy`: it is part of the session, so one user reached through two forwarders gets two sessions. It returns `outcome: "completed"` with output, `"failed"` with an error (including invalid input), or `"rejected"` with a reason (including approval or sign-in requirements); a direct call cannot pause for a person.
 
-  A direct call doesn't go through the AI SDK, so AI SDK telemetry integrations never see it. Conversation tool calls do: an integration that an `agent/instrumentation/*.ts` module registers with `registerTelemetry()` from `ai` receives `onToolExecutionStart` and `onToolExecutionEnd` for each of them. A direct call is traced by eve itself instead. It gets an `execute_tool` span under the caller's trace and emits `tool.call.started` and `tool.call.completed` to instrumentation. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
+  A direct call doesn't go through the AI SDK, so AI SDK telemetry integrations never see it. Conversation tool calls do: an integration that an `agent/instrumentation/*.ts` module registers with `registerTelemetry()` from `ai` receives `onToolExecutionStart` and `onToolExecutionEnd` for each of them. A direct call is traced by eve itself instead. It gets an `execute_tool` span under the caller's trace and emits `call.requested` and `call.settled` to instrumentation, as a conversation's calls do. Over MCP, the caller's trace comes from the request's `_meta` trace context (see [Trace context](./mcp#trace-context)).
 
 - `listSkillFiles(skill)` resolves to the skill's regular files, each with its `path` under the skill root and its `size` in bytes, sorted by path. It rejects a skill the agent does not have.
 - `readSkill(skill, path?)` resolves to one skill file's raw bytes as a `Uint8Array`; decode text yourself, for example with `new TextDecoder().decode(bytes)`. `path` is relative to the skill root, such as `references/api.md`, and defaults to the skill's `SKILL.md`. It rejects absolute paths, paths with `.`, `..`, or empty segments, files the skill does not list, and files over 512 KiB.
 
-Event handlers receive `(eventData, channel, ctx)`. `ctx.session.id` identifies
-the exact session, while `channel.continuation` exposes the current address and
-`alias()` when this channel needs to add another address. `session.failed`
-receives only `(eventData, channel)` because it runs outside session context;
-its event data contains `sessionId` directly.
-
-A failed turn emits `turn.failed`, then either `session.waiting` or
-`session.failed`. `turn.failed` carries `terminal: true` when the failure ends
-the session and `session.failed` follows. The built-in channels skip terminal
-`turn.failed` events, so a person sees one notice: the `session.failed` handler
-tells them to start over instead of to try again. Check `eventData.terminal` the
-same way in a custom channel that posts on both events.
-
-A channel that renders questions and approvals from `input.requested` can handle
-`input.resolved` to learn when each request ends, however it ended: answered from
-the channel, answered by a plain-text reply, or withdrawn. A request that a
-workflow tool run relays, from its own `ctx.ask()` or from a session it opened
-with `ctx.agent`, also resolves as `cancelled` when that run ends before anyone
-answers. Every request relayed from a task, workflow tool call, or subagent does
-the same when the turn is cancelled. Each resolution carries the `requestId` and
-an `outcome` such as `answered`, `approved`, or `cancelled`.
-
-`channel.continuation.token` is always the channel-local address accepted by
+Event handlers receive `(event, ctx)`: the whole fact, with its `type`, `data`, and
+`scope`, and a context. `ctx.session.id` identifies the exact session, `ctx.position`
+and `ctx.view` locate the fact on the stream and expose an opaque snapshot of its whole commit,
+and `ctx.channel` is the channel's own context. `ctx.channel.continuation` exposes the
+current address and `alias()` when this channel needs to add another address. Handlers
+run after the line is written, so they observe facts and never shape them.
+
+Use `committed(line, ctx)` when you need to update a status or card once per committed line, rather than once per fact. It runs after the line's fact handlers, with `line.facts`, `line.position`, and the whole line's snapshot at `ctx.view`.
+
+Handle `interaction.settled` to retire a rendered question or approval, whether it was answered, withdrawn, or interrupted. Match by `interactionId` and check its `outcome`.
+
+`ctx.channel.continuation.token` is always the channel-local address accepted by
 `from()`, `resolveSession()`, and `alias()`. Framework namespace prefixes are not
 part of the authored channel API.
 
@@ -113,8 +122,9 @@ startup to get the winning session's handle.
 ```ts
 const source = from(threadId);
 
-const session = await source.send("Hello", { auth });
-await source.respond(inputResponses, { auth });
+const delivery = await source.send("Hello", { auth });
+const result = await delivery.result();
+await source.respond(answers, { auth });
 await source.cancel({ turnId });
 await source.compact();
 await source.clear();
@@ -132,19 +142,23 @@ produce one fresh session. A `respond()` call, or a `deliver()` that includes in
 carries answers a fresh session has no request for, so it throws `SessionStrandedError` and leaves
 the stranded session in place.
 
-`Session` is fixed: every call targets exactly one durable ID. It never creates,
-follows, or resolves a replacement.
+`Session` from `eve/sessions` is fixed: every call targets exactly one durable ID. It never
+creates, follows, or resolves a replacement. Shared `Delivery`, `DeliveryResult`, `SessionReader`,
+stream/read options, and `SessionNotActiveError` also come from `eve/sessions`, not `eve/channels`.
+Accepted commands return reusable deliveries: call `stream({ signal })` for events or
+`result({ signal })` for a settled summary with its `outcome` and failure `error`. Aborting a read
+does not cancel the command or other readers.
 
 ```ts
 const session = attachSession(sessionId);
 
 await session.send("Follow up", { auth });
-await session.respond(inputResponses, { auth });
+await session.respond(answers, { auth });
 await session.cancel({ turnId });
 await session.compact();
 await session.clear();
 await session.reset({ reason: "Retire this session" });
-await session.getEventStream({ startIndex: 12 });
+for await (const event of session.stream({ startIndex: 12 })) render(event);
 ```
 
 A following `getEventStream()` rejects before it returns a stream when the session does not exist
@@ -152,8 +166,8 @@ or its recorded history has expired, so a route can answer with an error status
 bytes.
 
 For a stranded session, `Session.send()`, `Session.respond()`, and a following
-`Session.getEventStream()` throw `SessionStrandedError` from `eve/channels` and deliver nothing.
-`getEventStream({ follow: false })` still reads the recorded history up to the current tail without
+read through `Session.stream()` throw `SessionStrandedError` from `eve/channels` and deliver nothing.
+`stream({ follow: false })` still reads the recorded history up to the current tail without
 changing the session. `error.owner.eveVersion` names the eve release that built the session when it recorded one. Call
 `reset()` to end the stranded session, then start a new one:
 
@@ -169,15 +183,15 @@ try {
 ```
 
 `respond()` accepts exact response literals directly. If responses have already
-been widened to `InputResponse[]`—for example, after decoding a platform
+been widened to `Answer[]`—for example, after decoding a platform
 payload—validate them with eve's strict schema before delivery. The validated
 type preserves that proof across channel wrappers:
 
 ```ts
-import { parseInputResponses } from "eve/client";
+import { parseAnswers } from "eve/client";
 
-const inputResponses = parseInputResponses(decodedResponses);
-await source.respond(inputResponses, { auth });
+const answers = parseAnswers(decodedResponses);
+await source.respond(answers, { auth });
 ```
 
 Message sends use the channel's `turnPolicy`, which defaults to `"steer"`. Before assistant answer output or local tool execution begins, steering interrupts pending model generation and applies the correction in the same turn. Executing tools finish and checkpoint their results first. After answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output, and interrupted provider-managed search may run again. The turn ID stays the same.
@@ -186,6 +200,23 @@ A sent delivery can interrupt generation before your `deliver` hook runs. If the
 
 Every `send()` and `respond()` delivery passes its `state` option to your channel's `deliver(payload, channel)` hook as `payload.state`, including deliveries to an existing session. Use it for values that belong to one delivery, such as the author of a message. The hook decides what to merge into `channel.state`; eve seeds `channel.state` from `state` only when `send()` creates the session.
 
+The payload is `ChannelDelivery<TState>` from `eve/channels`: `message`, `answers`, `context`, `outputSchema`, and `state?: Partial<TState>`. Return a replacement with `message`, `answers`, `context`, or `outputSchema` to change the delivery, or return nothing to keep it unchanged. Change durable state through `channel.state`, not a `state` field on the replacement. To ignore a delivery, return `{}`. The hook does not return a harness input or accept arbitrary extra fields.
+
+```ts
+import { defineChannel } from "eve/channels";
+
+export default defineChannel({
+  state: { author: "" },
+  deliver(payload) {
+    const author = payload.state?.author;
+    if (author && typeof payload.message === "string") {
+      return { ...payload, message: `${author}: ${payload.message}` };
+    }
+  },
+  routes: [/* your routes */],
+});
+```
+
 Configure `turnPolicy: "queue"` on `defineChannel(...)` when messages should wait for the active turn to finish, or override one send:
 
 ```ts
@@ -204,7 +235,7 @@ export default defineChannel({
 });
 ```
 
-The same override is available on fixed `Session.send(...)` and cross-channel `to(...).send(...)`. `respond(...)` never steers: it delivers only addressed input responses. Use `cancel()` when you need to stop work without a replacement message.
+The same override is available on fixed `Session.send(...)` and cross-channel `to(...).send(...)`. `respond(...)` never steers: it delivers only addressed answers. Use `cancel()` when you need to stop work without a replacement message.
 
 Attaching does no lookup. The first operation reports whether the ID is active.
 Call `resolveSession(address)` only when you explicitly need to snapshot an
@@ -227,16 +258,7 @@ as does the Chat SDK bridge. Keys must contain 1–256 characters and identify o
 delivery. Prefix IDs with the provider or event type if they can overlap.
 Reusing a retained key ignores the new input, even if the message changed.
 
-Each session remembers its last 1,024 distinct keys. Retries do not extend
-retention and can run again after eviction. Aliases share this window; replay
-and owner handoffs preserve it. Other sessions have separate windows, including
-those created after reset, expiration, or replacement. Replicas must share the
-same durable Workflow World.
-
-A known duplicate does not interrupt generation, call `deliver`, or start a
-turn. A keyed send that creates a session waits up to 30 seconds for the winning
-session's handle. Sends to existing sessions return after eve stores the
-delivery, without waiting for a turn or reporting whether it was a duplicate.
+Each session retains its last 1,024 distinct keys; reuse after eviction or in another session can run again. Replicas must share the same durable Workflow World. A known duplicate returns a new receipt settled `ignored`, without repeating the original reply. Use `result()` to read a send's settlement.
 
 Await `send()` before acknowledging a webhook when the provider allows it.
 Acknowledging sooner can lose work. This does not make tool calls, outbound
@@ -296,17 +318,18 @@ Keep each route's `method` and `path` unless you mean to move the endpoint.
 
 ## Operation semantics
 
-- `cancel` cooperatively stops the active turn. Confirm it with `turn.cancelled`
-  followed by `session.waiting`; the session accepts another message afterward.
-- `compact` summarizes model context without adding a synthetic user message. A
-  success emits `compaction.requested`, `compaction.completed`, then `session.waiting`.
+- `cancel` cooperatively stops the active turn. Confirm it with `turn.settled` and
+  `outcome: "cancelled"`; the session accepts another message afterward.
+- `compact` summarizes model context without adding a synthetic user message. It
+  is a context change: `context.started`, then `context.settled` with
+  `kind: "compaction"`.
 - `clear` removes model-message history in place. It preserves the system prompt,
   skills, tools, durable state, limits, address ownership, and session sandbox.
 - `reset` terminally retires the current session. A later address `send()` creates
   a fresh session; a fixed `Session` handle remains pinned to the retired ID.
 
-Control operations never create a session. Unknown or inactive targets return a
-benign no-active status. Authenticate and deduplicate command webhooks before
+Control operations never create a session. Unknown or inactive targets throw
+`SessionNotActiveError`; an accepted no-op cancellation settles with `outcome: "ignored"`. Authenticate and deduplicate command webhooks before
 calling `reset`, because a delayed duplicate can retire a newer address owner.
 
 ## CORS
@@ -422,7 +445,7 @@ For notifications that don't need an agent turn, use the platform's API instead.
 
 ## Channel metadata
 
-A channel can project a subset of its adapter state as metadata, available to instrumentation resolvers, dynamic tool resolvers, and dynamic skill or instruction resolvers. Define a `metadata(state)` function on the channel config:
+A channel can project a subset of its adapter state as metadata, available to instrumentation resolvers and to the `select` of dynamic tools, skills, instructions, and other dynamic capabilities. Define a `metadata(state)` function on the channel config:
 
 ```ts
 import { defineChannel, POST } from "eve/channels";
@@ -453,14 +476,14 @@ export default defineChannel({
     }),
   ],
   events: {
-    "turn.started"(eventData, channel) {
-      channel.state.internalCounter += 1;
+    "turn.started"(_event, ctx) {
+      ctx.channel.state.internalCounter += 1;
     },
   },
 });
 ```
 
-The projection is re-evaluated whenever adapter state changes after channel event handlers run. Dynamic tool resolvers read it via `ctx.channel.metadata` and narrow it with `isChannel`. See [Dynamic capabilities](../guides/dynamic-capabilities) for the full consumption pattern.
+The projection is re-evaluated whenever adapter state changes after channel event handlers run. A dynamic capability's `select` reads it via `ctx.channel.metadata` and narrows it with `isChannel`. See [Dynamic capabilities](../guides/dynamic-capabilities) for the full consumption pattern.
 
 ### Conversation audience
 
@@ -482,17 +505,9 @@ export default defineChannel({
 });
 ```
 
-The input contains the channel's `state`, `caller`, `channel`, and `environment`. A principal caller omits `principalId`, `issuer`, and `subject`, but its `attributes` come from route auth and can still contain identifying values. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`.
+The input contains the channel's `state`, `caller`, `channel`, and `environment`. A principal caller omits `principalId`, `issuer`, and `subject`, but its `attributes` come from route auth and can still contain identifying values. Return `"public"`, `"private"`, or `"unknown"`. Return `"unknown"` when the channel does not have enough evidence to classify confidently; consumers treat it as non-public. A missing, throwing, asynchronous, or malformed classifier also fails closed to `"unknown"`. A `metadata()` projection's `audience` field does not classify visibility; use `audience(input)`.
 
-When you explicitly annotate a callback, use `AudienceContext<TState>`. `AudienceInput<TState>` remains supported for existing callbacks while you migrate.
-
-Existing callbacks can continue using `auth?.principalType` while you migrate:
-
-```ts
-audience({ auth }) {
-  return auth?.principalType === "user" ? "private" : "unknown";
-}
-```
+When you explicitly annotate a callback, use `AudienceContext<TState>`. The retired `AudienceInput`, `AudiencePrincipal`, and `auth` input are not supported; classify the privacy-limited `caller` instead.
 
 Classification is fixed when the session is created. Continuation turns from a different caller do not reclassify an existing session. When a parent dispatches a local subagent, the child inherits the parent's audience while the framework forwards the parent's custom channel metadata separately.
 
@@ -504,8 +519,8 @@ Each channel operation accepts a channel-local token. The framework prepends the
 import { slackContinuationToken } from "eve/channels/slack";
 import { twilioContinuationToken } from "eve/channels/twilio";
 
-slackContinuationToken("C0123ABC", "1800000000.001234"); // "C0123ABC:1800000000.001234"
-twilioContinuationToken("+15551234567", "+15557654321"); // "+15551234567:+15557654321"
+slackContinuationToken({ channelId: "C0123ABC", threadTs: "1800000000.001234" }); // "C0123ABC:1800000000.001234"
+twilioContinuationToken({ from: "+15551234567", to: "+15557654321" }); // "+15551234567:+15557654321"
 ```
 
 Custom channels write their own function that joins the identity fields. The framework derives nothing for you; the channel owns its token format.
@@ -514,7 +529,13 @@ When another identity should address a session, add it with `channel.continuatio
 
 Aliasing adds an address to the current session. Earlier addresses continue to resolve to the same session and accept the same payloads. `reset` terminally retires the current session and makes all its addresses available to later `send()` calls. `cancel` stops only the active turn and leaves the session, history, and continuation-token ownership intact.
 
-The `context(state, session)` config option builds the per-step `channel` argument handed to every event handler. It receives the channel's live adapter `state` and a `SessionHandle`, and returns the channel-owned context (thread handles, API clients, late-bound callbacks). The framework injects [`ChannelContinuationOps`](#define-a-channel) and passes the result as the second positional argument to each handler. Closing over `session` lets the factory register callbacks that add an alias later. State mutations made through the returned context are written back to adapter state.
+The `context(state, channel)` config option builds the per-step context read as `ctx.channel`
+in event handlers. Its second argument is `ChannelContext` from `eve/channels`: live
+`session.id` and `session.auth` information, plus channel-owned `continuation` routing. It does
+not expose session commands or put aliasing on session information. Close over
+`channel.continuation` for late-bound callbacks, or call `ctx.channel.continuation?.alias(token)`
+from an event handler. eve adds `ChannelContinuationOps` to the returned context and writes
+state mutations back to adapter state.
 
 ```ts
 import { defineChannel } from "eve/channels";
@@ -523,18 +544,18 @@ import { mintRef } from "./refs";
 
 defineChannel<{ ref: string | null }>({
   state: { ref: null },
-  context(state, session) {
+  context(state, channel) {
     return {
       state,
       registerAnchor(ref: string) {
         state.ref = ref;
-        session.continuation?.alias(ref);
+        channel.continuation?.alias(ref);
       },
     };
   },
   events: {
-    "message.completed"(eventData, channel) {
-      if (!channel.state.ref) channel.registerAnchor(mintRef());
+    "content.completed"(_event, ctx) {
+      if (!ctx.channel.state.ref) ctx.channel.registerAnchor(mintRef());
     },
   },
   routes: [/* ... */],
@@ -547,9 +568,9 @@ Tokens must be nonempty. A session supports up to 256 addresses, including its s
 
 ## File uploads
 
-`from(address).send()` accepts a `message` containing `string | UserContent`, while
-`Session.send()` accepts `string | UserContent` directly. To include file
-attachments, pass a `UserContent` array mixing text and file parts:
+`from(address).send()` accepts a `message` containing `MessageContent` (a string, or
+text and file parts), while `Session.send()` accepts `MessageContent` directly. To
+include file attachments, pass an array mixing text and file parts:
 
 ```ts
 await from(continuationToken).send(
@@ -561,7 +582,7 @@ await from(continuationToken).send(
 );
 ```
 
-For platforms like Slack where files sit behind authenticated URLs, put a `URL` object in `FilePart.data` and declare `fetchFile` on the channel config:
+For platforms like Slack where files sit behind authenticated URLs, put a `URL` object in the file part's `data` and declare `fetchFile` on the channel config:
 
 ```ts
 defineChannel({

package/docs/channels/discord.mdx

@@ -149,7 +149,7 @@ https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applic
 
 - **Credentials.** Vercel Connect authenticates callers with your project's Vercel OIDC token, which other hosts don't have, so give the relay the bot token directly. The agent can keep using Connect.
 - **URL.** The relay can't read `VERCEL_PROJECT_PRODUCTION_URL`, so pass the agent's URL as `url`.
-- **Auth.** The route's default auth accepts only your Vercel project's own runtime. Use a shared secret instead: `basic()` from `eve/agents/auth` signs the relay's requests, and `httpBasic()` on `gateway.auth` checks them.
+- **Auth.** The route's default auth accepts only your Vercel project's own runtime. Use a shared secret instead: `httpBasic()` from `eve/agents/auth` signs the relay's requests, and `httpBasic()` from `eve/channels/auth` on `gateway.auth` checks them.
 
 Generate a long random secret, for example with `openssl rand -hex 32`, and set it as `DISCORD_RELAY_SECRET` on both the agent's Vercel project and the relay's host. On the agent:
 
@@ -172,13 +172,13 @@ export default discordChannel({
 On the relay, set `DISCORD_BOT_TOKEN` to the token from **Bot** → **Reset Token** in the Discord Developer Portal, and `EVE_URL` to the agent's production URL:
 
 ```ts title="relay/main.ts"
-import { basic } from "eve/agents/auth";
+import { httpBasic } from "eve/agents/auth";
 import { experimental_runDiscordGatewayRelay } from "eve/channels/discord/gateway";
 
 await experimental_runDiscordGatewayRelay({
   // Reads DISCORD_BOT_TOKEN when `credentials` is omitted.
   url: process.env.EVE_URL,
-  auth: basic({ username: "discord-relay", password: process.env.DISCORD_RELAY_SECRET! }),
+  auth: httpBasic({ username: "discord-relay", password: process.env.DISCORD_RELAY_SECRET! }),
 });
 ```
 
@@ -327,7 +327,7 @@ Scale the production daemon to zero while you do this. Every connection receives
 
 The model-visible `<discord_context>` includes `user_id` and the receiving application's `application_id`.
 
-Event handlers receive `(eventData, channel, ctx)`, with Discord platform handles on `channel.discord`:
+Event handlers receive `(event, ctx)`, with Discord platform handles on `ctx.channel.discord`:
 
 ```ts
 import { discordChannel } from "eve/channels/discord";
@@ -342,9 +342,9 @@ export default discordChannel({
     },
   }),
   events: {
-    "message.completed"(eventData, channel, ctx) {
-      if (eventData.finishReason === "tool-calls") return;
-      if (eventData.message) channel.discord.post(eventData.message);
+    "content.completed"(event, ctx) {
+      if (event.data.phase !== "reply" || typeof event.data.value !== "string") return;
+      return ctx.channel.discord.post(event.data.value);
     },
   },
 });
@@ -352,17 +352,17 @@ export default discordChannel({
 
 ### Delivery
 
-The default `message.completed` handler edits the deferred response for the first reply and sends followups after that. If the interaction token is rejected, it falls back to a bot-authenticated channel message. Long text is split to Discord's 2000-char limit, and generated messages default to `allowed_mentions: { parse: [] }`.
+The default `content.completed` handler edits the deferred response for the first reply part and sends followups after that. If the interaction token is rejected, it falls back to a bot-authenticated channel message. Long text is split to Discord's 2000-char limit, and generated messages default to `allowed_mentions: { parse: [] }`.
 
-Typing fires on `turn.started` and `actions.requested`, but only when a bot token is present. In custom hooks, call `channel.discord.startTyping()` yourself.
+Typing fires on `turn.started` and `call.requested`, but only when a bot token is present. In custom handlers, call `ctx.channel.discord.startTyping()` yourself.
 
 ### Human-in-the-loop (HITL)
 
 HITL renders as Discord components. Confirmations and options become buttons, `display: "select"` becomes a string select, and freeform input becomes a button that opens a modal. When the user responds, the parked session (paused awaiting input) resumes.
 
-A press, select, or modal submission answers as the Discord user who made it, with the same `defaultDiscordAuth` principal a command from them gets by default. Approval response policies compare against that principal. Approvals are requester-only by default, so only the person whose command asked can approve. `onInputResponse(ctx, interaction)` decides the answer's `auth`: return `{ auth }` to accept it, or `null` (or throw) to drop it and keep the request pending. `ctx.defaultAuth` is the presser's `defaultDiscordAuth`; it identifies them but doesn't authorize them by itself.
+A press, select, or modal submission answers as the Discord user who made it, with the same `defaultDiscordAuth` principal a command from them gets by default. Approval response policies compare against that principal. Approvals are requester-only by default, so only the person whose command asked can approve. `onAnswers(ctx, interaction)` decides the answer's `auth`: return `{ auth }` to accept it, or `null` (or throw) to drop it and keep the request pending. `ctx.defaultAuth` is the presser's `defaultDiscordAuth`; it identifies them but doesn't authorize them by itself.
 
-If you customize `onCommand`, eve drops every press and submission until you also set `onInputResponse`, and logs a warning saying so. The default Discord principal wouldn't match the principals your `onCommand` returns, so a requester-only approval would refuse the requester. It would also let someone your `onCommand` turns away answer open approvals. Give both hooks the same mapping and gating:
+If you customize `onCommand`, eve drops every press and submission until you also set `onAnswers`, and logs a warning saying so. The default Discord principal wouldn't match the principals your `onCommand` returns, so a requester-only approval would refuse the requester. It would also let someone your `onCommand` turns away answer open approvals. Give both hooks the same mapping and gating:
 
 ```ts
 import { discordChannel } from "eve/channels/discord";
@@ -378,7 +378,7 @@ const auth = (interaction: { user: { id: string } }) => ({
 
 export default discordChannel({
   onCommand: (_ctx, interaction) => auth(interaction),
-  onInputResponse: (_ctx, interaction) => auth(interaction),
+  onAnswers: (_ctx, interaction) => auth(interaction),
 });
 ```
 

package/docs/channels/eve.mdx

@@ -101,8 +101,9 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
 The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
 
 `POST /eve/v1/session/:sessionId` with no body or `{}` prepares an existing session using
-the channel's auth policy. Non-empty bodies retain the message and input-response behavior;
-empty or invalid messages and payloads without either input are rejected. Preparation
+the channel's auth policy, without calling `onMessage` or creating a delivery. Non-empty bodies
+keep the message and answer behavior, including unknown-field validation; empty or invalid
+messages, an empty `answers` array, and payloads with neither input are rejected. Preparation
 returns `{ ok: true, status }`: `ready` when the owner already uses the serving
 deployment, `accepted` (HTTP 202) when a background preparation hint has been queued,
 `unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
@@ -113,13 +114,40 @@ for client usage and deployment routing.
 
 `GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
 
+### Request validation
+
+Session creation, follow-up message and input-response requests, and session controls reject
+unknown top-level JSON fields with `400 Bad Request`. The error names the unknown fields and
+lists the accepted fields for that route. Field names are case-sensitive: `outputschema` is
+not `outputSchema`. Invalid requests do not create sessions, dispatch messages, or apply controls.
+
+Fields accepted on one route are not automatically valid on another. For example, `operationId`
+is accepted on session creation but rejected on follow-up messages.
+
+Follow-up message and input-response requests accept an `idempotencyKey` of 1 to 256 characters,
+for a retry that can't tell whether the first request was accepted. The key names the delivery:
+repeating the request with the same key returns the same `deliveryId`, and the input doesn't run
+again. Unlike a channel's [retried deliveries](./custom#retried-deliveries), whose duplicates get a
+new receipt settled `ignored`, the repeat's receipt is the original's. The session remembers its
+last 1,024 keys, so use a new key for new input. The compact and clear routes
+accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`; reset accepts `reason`.
+
+Open payload objects such as `clientContext` keep their existing contracts. Delegated requests
+with a `callback` accept, and ignore, the retired `activityObserver` field so older senders keep
+working. No other unknown fields are accepted. Authentication and existing value validation still
+apply, including permission checks for forwarded principals and tool stubs.
+
+A newer client sending an unsupported field to an older server with strict validation fails
+rather than silently losing the requested behavior. Correct the field or upgrade the server;
+do not automatically remove behavior-changing options and retry.
+
 ### Start and continue a session
 
 Create a conversation session before its first message with a bodyless request:
 
 ```bash
 curl -X POST https://<deployment>/eve/v1/session
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
+# {"ok":true,"sessionId":"wrun_A"}
 ```
 
 See [Start a session](../concepts/sessions-runs-and-streaming#start-a-session) for the
@@ -135,7 +163,7 @@ Include an initial message to create the session and start its first turn in one
 curl -X POST https://<deployment>/eve/v1/session \
   -H "Content-Type: application/json" \
   -d '{"message":"What is the weather in Paris?"}'
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
+# {"ok":true,"sessionId":"wrun_A","deliveryId":"delivery_A"}
 ```
 
 Authenticated callers that may retry a create request can pass their own `operationId` for
@@ -152,21 +180,21 @@ curl -X POST https://<deployment>/eve/v1/session \
   -H "Authorization: Bearer <token>" \
   -H "Content-Type: application/json" \
   -d '{"message":"What is the weather in Paris?","operationId":"order-4213-research"}'
-# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
+# {"ok":true,"sessionId":"wrun_A","deliveryId":"delivery_A"}
 ```
 
 When the create request includes a message, a follow-up request accepts exactly one of
-`message` or `inputResponses`; use the latter to answer a pending HITL request:
+`message` or `answers`; use the latter to answer a pending HITL request:
 
 ```bash
 curl -X POST https://<deployment>/eve/v1/session/wrun_A \
   -H "Content-Type: application/json" \
-  -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
+  -d '{"answers":[{"interactionId":"req_A","optionId":"approve"}]}'
 ```
 
 Follow-up messages use `turnPolicy: "steer"` by default. Before assistant answer output or local tool execution begins, steering interrupts pending model generation and applies the correction in the same turn. Executing tools finish and checkpoint their results first. After answer output starts, steering waits for the next committed workflow boundary. Reasoning and search progress do not count as answer output; interrupted provider-managed search may run again. The turn ID stays the same.
 
-Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `inputResponses` answer their addressed requests.
+Set `turnPolicy: "queue"` on `eveChannel(...)` when follow-ups should wait for active turns to finish. `answers` answer their addressed requests.
 
 Sending a message to an unknown or terminal session ID returns `409` with
 `{"code":"session_not_active","error":"The session is no longer active.","ok":false}`.
@@ -212,15 +240,19 @@ export default eveChannel({
 
 Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
 
-Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before a reset. A reset attempts to append `session.failed` with code `session_stranded` and close the stream. Existing readers finish when they receive that terminal event.
+Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before a reset. A reset attempts to append its control delivery's `delivery.admitted` (`source: { control: "reset" }`) and `delivery.settled`, then `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }` naming that delivery, then close the stream. Existing readers finish when the stream ends.
+
+A session started by an eve version before v27 stores v26 events. Its stream route serves them as the v27 lines they record, so v27 clients render that history: messages, reasoning, tool calls and results, approvals, questions, sign-ins, subagents, clears, and compactions. Streamed text previews aren't translated, so a v26 session that is still running shows each part once it completes.
+
+Cursors still count stored lines. A stored event with nothing for a v27 reader to fold, such as a streamed delta, is sent as a `position` marker. The route reads these streams from their first line on every request, whatever the cursor. Once no running owner can add to the stream, a follow ends at the tail with `stream.ended`, so clients stop reconnecting.
 
 After a session ends, the World keeps its stream only for its retention period. Reading a stream past that point returns `410 session_expired`. The history is gone, so the TypeScript client fails on the first response with a `ClientError` whose `code` is `"session_expired"`, without retrying.
 
 ### Cancel a turn
 
-Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm the turn boundary on the stream as `turn.cancelled` followed by `session.waiting`.
+Post to `/eve/v1/session/:sessionId/cancel` to request cancellation of the active turn. You can include the observed `turnId` to keep a late request from cancelling a newer turn. Cancellation is asynchronous; confirm it on the stream as `turn.settled` with `outcome: "cancelled"`.
 
-See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for response statuses, HTTP status codes, subagent cancellation, and race behavior.
+See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-the-in-flight-turn) for delivery receipts, HTTP status codes, subagent cancellation, and race behavior.
 
 ### Clear context
 
@@ -266,7 +298,7 @@ export default eveChannel({
   cors: {
     origin: "https://app.example.com",
     methods: ["GET", "POST"],
-    allowedHeaders: ["authorization", "content-type"],
+    allowHeaders: ["authorization", "content-type"],
   },
 });
 ```
@@ -341,8 +373,9 @@ export default eveChannel({
     };
   },
   events: {
-    "message.completed"(eventData, _channel, ctx) {
-      console.log("eve response completed", {
+    "turn.settled"(event, ctx) {
+      console.log("eve turn settled", {
+        outcome: event.data.outcome,
         sessionId: ctx.session.id,
       });
     },
@@ -423,7 +456,7 @@ Each entry has a `role` of `"user"` or `"assistant"`, non-empty `text`, and an o
 
 eve never accepts `history` from a client request body. Resolve it on the server and authorize the caller against the stored conversation.
 
-The stream publishes added entries in `history.imported`, right before the `message.received` of the turn they join. Each event message has the same `role`, `text`, and `id` you passed. `transcriptReducer()` from `eve/client` includes them, so its `{ role, text }` messages can be passed straight back as `history` to branch a session. The default client reducer renders them ahead of that turn's message with `metadata.imported` set and your `id` in `metadata.historyId`, so you can rejoin your own annotations. Message ids stay unique even when a later call reuses an `id`. After that, the entries are ordinary history: compaction, `clear()`, and handoffs treat them like any other turn.
+The stream records the entries on the `delivery.consumed` of the message that brought them, in `data.history`, with the same `role`, `text`, and `id` you passed. History from `create()` is recorded with the first message the channel accepts. When one turn takes in several messages at once, the model reads all of their history before what they sent. `transcriptOf()` from `eve/client` reads the entries in that order, so its `{ role, text }` messages can be passed straight back as `history` to branch a session. Frontend `messages` show them ahead of their message with `metadata.imported` set and your `id` in `metadata.historyId`, so you can rejoin your own annotations. Imported messages have no `metadata.turnId`, so a turn's reply never streams into one, and their message ids stay unique even when a later call reuses an `id`. After that, the entries are ordinary history: compaction, `clear()`, and handoffs treat them like any other turn.
 
 ## Clients
 

package/docs/channels/github.mdx

@@ -101,13 +101,13 @@ When a turn starts, the channel adds an `eyes` reaction to the triggering commen
 
 ### Human-in-the-loop (HITL)
 
-GitHub comments have no interactive button or card affordance. A human-in-the-loop (HITL) `input.requested` event is posted as a comment prompt, and the user's reply comment maps back to the pending input request. Declare an `events["input.requested"]` handler to customize the prompt.
+GitHub comments have no interactive button or card affordance. A human-in-the-loop (HITL) request, an `interaction.opened` fact, is posted as a comment prompt, and the user's reply comment maps back to the pending request. Declare an `events["interaction.opened"]` handler to customize the prompt.
 
 ### Proactive sessions
 
 Start a session without an inbound comment invocation through `to(github, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(github, target).send(message, { auth })` from another channel. The target requires `owner`, `repo`, and exactly one of `issueNumber` or `pullRequestNumber`. This sends turn input to the agent; it is not a direct GitHub comment.
 
-To post without invoking the model, use `channel.thread.post(...)` inside a GitHub event handler. For application-managed retries and deduplication across providers, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
+To post without invoking the model, use `ctx.channel.thread.post(...)` inside a GitHub event handler. For application-managed retries and deduplication across providers, see [Durable cross-channel notifications](../patterns/durable-cross-channel-notifications).
 
 ### Attachments