eve 0.30.8 → 0.31.0

package/docs/channels/custom.mdx

@@ -13,152 +13,120 @@ The channel file stem becomes the channel id, so `agent/channels/internal-webhoo
 
 ## Define a channel
 
-```ts
+Pass the platform's conversation identity to each operation:
+
+```ts title="agent/channels/support.ts"
 import { defineChannel, GET, POST } from "eve/channels";
 
 export default defineChannel({
   routes: [
-    POST("/message", async (req, { send }) => {
-      const body = await req.json();
-      const session = await send(body.message, {
-        auth: null,
-        continuationToken: body.token,
-      });
+    POST("/threads/:threadId/messages", async (request, { from, params }) => {
+      const body = await request.json();
+      const source = from(params.threadId);
+
+      if (body.message === "/new") {
+        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 });
     }),
-    GET("/sessions/:sessionId/stream", async (_req, { getSession, params }) => {
-      const session = getSession(params.sessionId);
-      const stream = await session.getEventStream();
 
+    POST("/threads/:threadId/cancel", async (_request, { from, params }) =>
+      Response.json(await from(params.threadId).cancel()),
+    ),
+    POST("/threads/:threadId/compact", async (_request, { from, params }) =>
+      Response.json(await from(params.threadId).compact()),
+    ),
+    POST("/threads/:threadId/clear", async (_request, { from, params }) =>
+      Response.json(await from(params.threadId).clear()),
+    ),
+
+    GET("/sessions/:sessionId/stream", async (_request, { attachSession, params }) => {
+      const stream = await attachSession(params.sessionId).getEventStream();
       return new Response(stream, {
         headers: { "content-type": "application/x-ndjson; charset=utf-8" },
       });
     }),
   ],
+
   events: {
-    "message.completed"(event, channel, ctx) {
-      // deliver completed messages back to the surface that owns this channel
+    "message.completed"(event, _channel, ctx) {
+      console.log(ctx.session.id, event.message);
     },
   },
 });
 ```
 
-Declare routes with the `POST()` and `GET()` helpers. Each route handler receives the raw `Request` and a helpers object:
-
-- `send(message, { auth, continuationToken, state?, title? })` starts or resumes a session. `title` overrides the new workflow session's display title without changing the model message. Returns a `Session`.
-- `cancel({ continuationToken, turnId? })` requests cancellation of the active turn on the session that owns the token. See [Cancel a turn](#cancel-a-turn).
-- `clear({ continuationToken })` removes the model-message history while preserving the session and its durable resources. See [Clear session context](#clear-session-context).
-- `compact({ continuationToken })` queues context compaction for the session that owns the token without sending model input. See [Compact a session](#compact-a-session).
-- `reset({ continuationToken, reason? })` retires the session that owns the token so the next `send()` starts a fresh session. See [Reset a session](#reset-a-session).
-- `getSession(sessionId)` looks up an existing session. The returned `Session` exposes `getEventStream({ startIndex? })` for streaming, `getStreamTailIndex()` for resolving the durable tail when a route wants to serve bounded reads, and `cancel({ turnId? })` for session-id-addressed cancellation.
-- `receive(channel, ...)` hands inbound work to a different channel for cross-channel hand-off.
-- `params` holds route parameters extracted from the path pattern.
-- `waitUntil(promise)` extends the request lifetime for background work.
-- `requestIp` is the client IP, or `null` when the host cannot provide it.
-
-Event handlers like `"message.completed"` are declared under the `events` key. They receive `(eventData, channel, ctx)`, where `eventData` is the event payload, `channel` carries platform handles and session continuation operations, and `ctx` is the eve `SessionContext`. Every channel kind shares this signature. The one exception is `session.failed`, which receives only `(eventData, channel)` with no `ctx`.
-
-## Cancel a turn
-
-A stop route cancels a session's in-flight turn with the `cancel` helper, addressed by the same channel-local continuation token used with `send()`:
-
-```ts
-import { defineChannel, POST } from "eve/channels";
-
-export default defineChannel({
-  routes: [
-    POST("/threads/:threadId/stop", async (_req, { cancel, params }) => {
-      const result = await cancel({ continuationToken: params.threadId });
-      return Response.json(result);
-    }),
-  ],
-});
-```
-
-Both result statuses are successful. `"accepted"` means the cancellation request was consumed, not that the observed turn will cancel; confirmation is `turn.cancelled` followed by `session.waiting` on the event stream. `"no_active_turn"` covers an unknown token and a session with nothing to cancel — idle, parked, or already completed.
+Each route receives these operation surfaces:
 
-Semantics:
+- `from(address)` binds `send`, `respond`, `cancel`, `compact`, `clear`, and `reset` to a channel-local continuation address.
+- `resolveSession(address)` snapshots the session currently owning a channel-local continuation address.
+- `attachSession(sessionId)` creates an I/O-free handle pinned to one durable session ID.
+- `to(channel, target).send(message, options)` hands work to another authored channel.
+- `params`, `waitUntil`, and `requestIp` provide request metadata and lifetime control.
 
-- `cancel` never starts a session, sends input, or clears history. The session parks and accepts the next message normally.
-- Pass `turnId` (stamped on every turn-scoped stream event) to guard against stale stop requests. A mismatched guard is consumed as a benign no-op and cannot cancel a newer turn.
-- The helper addresses only this channel's sessions; it cannot cancel a session owned by another channel.
-- Cancellation stops work without replacement input. Partial streamed output and completed side effects remain observable, and active local or remote subagents receive cancellation recursively.
-- The route owns authentication of the inbound stop request, exactly as for `send()`.
+Event handlers receive `(eventData, channel, ctx)`. `ctx.session.id` identifies
+the exact session, while `channel.continuation` exposes the current address and
+`rekey()` when this channel needs to move it. `session.failed` receives only
+`(eventData, channel)` because it runs outside session context; its event data
+contains `sessionId` directly.
 
-When you already hold a `Session` — returned by `send()` or `getSession(sessionId)` — call `session.cancel({ turnId? })` to request the same cancellation addressed by session id.
+`channel.continuation.token` is always the channel-local address accepted by
+`from()`, `resolveSession()`, and `rekey()`. Framework namespace prefixes are not
+part of the authored channel API.
 
-## Clear session context
+## Channel operations and session handles
 
-Call `clear` with the channel-local continuation token to remove a session's durable model-message history without replacing the session:
+Channel operations are dynamic: every call targets whichever session currently
+owns the address. Only `send()` can create a session when the address is unowned.
 
 ```ts
-import { defineChannel, POST } from "eve/channels";
+const source = from(threadId);
 
-export default defineChannel({
-  routes: [
-    POST("/threads/:threadId/clear", async (_req, { clear, params }) => {
-      const result = await clear({ continuationToken: params.threadId });
-      return Response.json(result);
-    }),
-  ],
-});
-```
-
-`"accepted"` means the clear was queued. The stream emits `context.cleared` followed by `session.waiting`, after which the next ordinary message resumes the same session with no prior model messages. The system prompt, configured tools and skills, durable state, limits, continuation-token ownership, and session-scoped sandbox remain. `"no_active_session"` means the token has no current owner.
-
-## Compact a session
-
-Call `compact` with the channel-local continuation token to summarize durable conversation history without delivering a command to the model:
-
-```ts
-import { defineChannel, POST } from "eve/channels";
+const session = await source.send("Hello", { auth });
+await source.respond(inputResponses, { auth });
+await source.cancel({ turnId });
+await source.compact();
+await source.clear();
+await source.reset({ reason: "Start over" });
 
-export default defineChannel({
-  routes: [
-    POST("/threads/:threadId/compact", async (_req, { compact, params }) => {
-      const result = await compact({ continuationToken: params.threadId });
-      return Response.json(result);
-    }),
-  ],
-});
+const currentSession = await resolveSession(threadId);
 ```
 
-`"accepted"` means the durable session queued the operation. A successful compaction emits `compaction.requested` followed by `compaction.completed`, then the operation returns through `session.waiting`. If summarization fails, the stream returns through `session.waiting` without `compaction.completed` and preserves the previous history. If a turn is active, eve runs the compaction after that turn settles; it does not cancel the turn. `"no_active_session"` means the token has no current owner. Both outcomes are successful, and compaction never starts a session or appends a synthetic user message.
-
-## Reset a session
-
-Identity-addressed channels can consume commands such as `/new` in their route, without sending the command to the model. Call `reset` with the same channel-local continuation token used by `send()`:
+`Session` is fixed: every call targets exactly one durable ID. It never creates,
+follows, or resolves a replacement.
 
 ```ts
-import { defineChannel, POST } from "eve/channels";
-
-export default defineChannel({
-  routes: [
-    POST("/messages", async (request, { reset, send }) => {
-      const body = await request.json();
+const session = attachSession(sessionId);
+
+await session.send("Follow up", { auth });
+await session.respond(inputResponses, { auth });
+await session.cancel({ turnId });
+await session.compact();
+await session.clear();
+await session.reset({ reason: "Retire this session" });
+await session.getEventStream({ startIndex: 12 });
+```
 
-      if (body.message.trim().toLowerCase() === "/new") {
-        await reset({
-          continuationToken: body.conversationId,
-          reason: "User requested /new",
-        });
-        return Response.json({ message: "Started a new conversation." });
-      }
+Attaching does no lookup. The first operation reports whether the ID is active.
+Call `resolveSession(address)` only when you explicitly need to snapshot an
+address's current owner as a fixed handle.
 
-      const session = await send(body.message, {
-        auth: null,
-        continuationToken: body.conversationId,
-      });
-      return Response.json({ sessionId: session.id });
-    }),
-  ],
-});
-```
+## Operation semantics
 
-`reset` returns `{ status: "reset", previousSessionId }` when it observed an owner, or `{ status: "no_active_session" }` when the token was already free. Both outcomes are successful. It terminally cancels the observed workflow run and waits until its non-retained continuation hook no longer blocks reuse, so the next `send()` using the same token creates a new session with fresh history and state.
+- `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`.
+- `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.
 
-The replacement session owns a new session-scoped sandbox. eve initializes it lazily on that session's first sandbox use, so it never reuses the prior session's workspace or sandbox state. Resetting does not clear history in place, roll back tool calls, or delete the previous run or its sandbox; normal retention and backend cleanup policies still apply. Side effects or partial output that were already committed remain committed. Authenticate and deduplicate inbound command webhooks before calling this helper: a delayed duplicate `/new` can otherwise reset a newer session that has already reclaimed the same token.
+Control operations never create a session. Unknown or inactive targets return a
+benign no-active status. Authenticate and deduplicate command webhooks before
+calling `reset`, because a delayed duplicate can retire a newer address owner.
 
 ## CORS
 
@@ -188,19 +156,19 @@ import { defineChannel, WS } from "eve/channels";
 
 export default defineChannel({
   routes: [
-    WS("/voice/ws", async (_req, { send }) => ({
+    WS("/voice/ws", async (_req, { from }) => ({
       async message(_peer, message) {
-        await send(message.text(), {
-          auth: null,
-          continuationToken: "voice-demo",
-        });
+        await from("voice-demo").send(message.text(), { auth: null });
       },
     })),
   ],
 });
 ```
 
-`WS()` handlers receive the same helpers as HTTP route handlers: `send`, `cancel`, `clear`, `compact`, `reset`, `getSession`, `receive`, `params`, `waitUntil`, and `requestIp`. The returned hooks are eve-owned structural types compatible with Nitro/H3 websocket routing, including `upgrade`, `open`, `message`, `close`, and `error`.
+`WS()` handlers receive the same `from`, `to`, and `attachSession` operations,
+`params`, `waitUntil`, and `requestIp` arguments as HTTP route handlers. The
+returned hooks are eve-owned structural types compatible with Nitro/H3 websocket
+routing, including `upgrade`, `open`, `message`, `close`, and `error`.
 
 ### Node upgrade server escape hatch
 
@@ -222,7 +190,7 @@ The bridge server does not listen on its own port. It receives only upgrade even
 
 ## Cross-channel hand-off
 
-Route handlers can start a session on a different channel via `args.receive(channel, ...)`. Use this when an inbound request on one channel should pivot the conversation onto another, such as an incident webhook that opens an investigation thread in Slack.
+Route handlers can start a session on a different channel via `ctx.to(channel, target).send(message, options)`. Use this when an inbound request on one channel should pivot the conversation onto another, such as an incident webhook that opens an investigation thread in Slack.
 
 ```ts
 import { defineChannel, POST } from "eve/channels";
@@ -230,20 +198,20 @@ import slack from "./slack";
 
 export default defineChannel({
   routes: [
-    POST("/incident", async (req, args) => {
+    POST("/incident", async (req, ctx) => {
       const incident = await req.json();
 
-      args.waitUntil(
-        args.receive(slack, {
-          message: `Investigate ${incident.reference}: ${incident.title}`,
-          target: { channelId: "C0123ABC" },
-          auth: {
-            authenticator: "incidentio",
-            principalType: "service",
-            principalId: incident.actor.id,
-            attributes: { reference: incident.reference, severity: incident.severity },
-          },
-        }),
+      ctx.waitUntil(
+        ctx
+          .to(slack, { channelId: "C0123ABC" })
+          .send(`Investigate ${incident.reference}: ${incident.title}`, {
+            auth: {
+              authenticator: "incidentio",
+              principalType: "service",
+              principalId: incident.actor.id,
+              attributes: { reference: incident.reference, severity: incident.severity },
+            },
+          }),
       );
 
       return new Response("ok");
@@ -254,9 +222,9 @@ export default defineChannel({
 
 Semantics:
 
-- The target channel's authored `receive(input, { send })` hook owns the continuation-token format and initial state. Callers supply only `{ message, target, auth }`.
+- The target channel's authored `receive(input, { from })` hook owns the continuation-token format and initial state. Callers supply the target to `to(...)`, then the message and auth to `send(...)`.
 - `auth` flows through to `session.auth.initiator` so the target's event handlers and the agent's tools can read who started the session.
-- Calling `args.receive(...)` does not also start a session on the current channel. The inbound channel's response is whatever the route handler returns explicitly.
+- Calling `ctx.to(...).send(...)` does not also start a session on the current channel. The inbound channel's response is whatever the route handler returns explicitly.
 - The first argument is the target channel module's default export. Import it directly from `agent/channels/<name>.ts`. Identity is matched by reference.
 
 ## Channel metadata
@@ -281,11 +249,10 @@ export default defineChannel({
   },
 
   routes: [
-    POST("/start", async (req, { send }) => {
+    POST("/start", async (req, { from }) => {
       const body = await req.json();
-      await send(body.message, {
+      await from(body.token).send(body.message, {
         auth: null,
-        continuationToken: body.token,
         state: { topic: body.topic, contextMessages: body.context, internalCounter: 0 },
       });
 
@@ -306,7 +273,7 @@ When a parent agent dispatches a subagent, the framework forwards the parent's c
 
 ## Continuation tokens
 
-Each call to `send(message, { auth, continuationToken, state?, title? })` from a channel route addresses a session by its channel-local raw token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
+Each channel operation accepts a channel-local token. The framework prepends the channel name, derived from the file stem under `agent/channels/`, before handing the token to the runtime.
 
 ```ts
 import { slackContinuationToken } from "eve/channels/slack";
@@ -318,11 +285,11 @@ twilioContinuationToken("+15551234567", "+15557654321"); // "+15551234567:+15557
 
 Custom channels write their own function that joins the identity fields. The framework derives nothing for you; the channel owns its token format.
 
-When the identity that should address a session is not known until later, the channel can re-key the parked session by calling `session.setContinuationToken(...)`. Pass the channel-local raw token; the runtime preserves the current channel namespace.
+When the identity that should address a session is not known until later, re-key the live address with `channel.continuation?.rekey(rawToken)`. The runtime preserves the current channel namespace.
 
 Re-keying changes the address of the current session. `reset` is different: it terminally retires the current session and makes its existing address available to a later `send()`. `cancel` is narrower still: it 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 [`ChannelSessionOps`](#define-a-channel) and passes the result as the second positional argument to each handler. Closing over `session` lets the factory register callbacks that re-key the session later. State mutations made through the returned context are written back to adapter state.
+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 re-key the address later. State mutations made through the returned context are written back to adapter state.
 
 ```ts
 import { defineChannel } from "eve/channels";
@@ -336,7 +303,7 @@ defineChannel<{ ref: string | null }>({
       state,
       registerAnchor(ref: string) {
         state.ref = ref;
-        session.setContinuationToken(ref);
+        session.continuation?.rekey(ref);
       },
     };
   },
@@ -353,15 +320,17 @@ At the next workflow boundary, the runtime claims the new park hook before relea
 
 ## File uploads
 
-`send()` accepts `string | UserContent`. To include file attachments, pass a `UserContent` array mixing text and file parts:
+`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:
 
 ```ts
-await send(
+await from(continuationToken).send(
   [
     { type: "text", text: body.message },
     { type: "file", data: imageBytes, mediaType: "image/png" },
   ],
-  { auth, continuationToken },
+  { auth },
 );
 ```
 
@@ -377,8 +346,8 @@ defineChannel({
   },
 
   routes: [
-    POST("/webhook", async (req, { send }) => {
-      await send(
+    POST("/webhook", async (req, { from }) => {
+      await from(continuationToken).send(
         [
           { type: "text", text: message.text },
           ...message.attachments.map((a) => ({
@@ -387,7 +356,10 @@ defineChannel({
             mediaType: a.mediaType,
           })),
         ],
-        { auth, continuationToken, state },
+        {
+          auth,
+          state,
+        },
       );
     }),
   ],

package/docs/channels/discord.mdx

@@ -90,7 +90,7 @@ HITL renders as Discord components. Confirmations and options become buttons, `d
 
 ### Proactive sessions
 
-Start a session without an inbound interaction through `receive(discord, { message, target, auth })` from a schedule `run` handler, or `args.receive(discord, ...)` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs a bot token, supplied by Connect or `DISCORD_BOT_TOKEN`.
+Start a session without an inbound interaction through `to(discord, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(discord, target).send(message, { auth })` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs a bot token, supplied by Connect or `DISCORD_BOT_TOKEN`.
 
 ### Attachments
 

package/docs/channels/eve.mdx

@@ -20,68 +20,112 @@ export default eveChannel({
 
 ## Routes
 
-The application exposes a health route plus eve channel routes that inspect the agent, create sessions, send follow-ups, cancel turns, compact or reset sessions, and stream events:
+The application exposes a health route plus eve channel routes that inspect the agent, create sessions, send follow-ups, control sessions, and stream events:
 
-- `GET /eve/v1/health`
-- `GET /eve/v1/info`
-- `POST /eve/v1/session` (start a session)
+- `GET /eve/v1/health` (check whether the application is reachable)
+- `GET /eve/v1/info` (inspect the agent)
+- `POST /eve/v1/session` (start a session and send its first message)
 - `POST /eve/v1/session/:sessionId` (send a follow-up)
 - `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
-- `POST /eve/v1/session/clear` (clear the continuation owner's model history)
-- `POST /eve/v1/session/compact` (compact the continuation owner's context)
-- `POST /eve/v1/session/reset` (retire the continuation owner)
-- `GET /eve/v1/session/:sessionId/stream` (stream events, NDJSON)
+- `POST /eve/v1/session/:sessionId/clear` (clear the session's model history)
+- `POST /eve/v1/session/:sessionId/compact` (compact the session's context)
+- `POST /eve/v1/session/:sessionId/reset` (retire the session)
+- `GET /eve/v1/session/:sessionId/stream` (stream events as NDJSON)
 
-Start a session with a minimal body. The response returns `sessionId` and the `continuationToken` you reuse for follow-ups:
+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.
+
+### Start and continue a session
 
 ```bash
 curl -X POST https://<deployment>/eve/v1/session \
   -H "Content-Type: application/json" \
   -d '{"message":"What is the weather in Paris?"}'
-# {"continuationToken":"eve:7f3c...","ok":true,"sessionId":"ses_01h..."}
+# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
+
+curl -X POST https://<deployment>/eve/v1/session/wrun_A \
+  -H "Content-Type: application/json" \
+  -d '{"message":"How about tomorrow?"}'
+```
+
+The first request requires `message`. A follow-up request accepts exactly one of
+`message` or `inputResponses`; 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"}]}'
 ```
 
-Stream that session's events as newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:
+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}`.
+TypeScript clients expose the stable code as `ClientError.code`. The route never
+creates or follows a replacement session.
+
+### Stream events
+
+Stream responses are newline-delimited JSON (`application/x-ndjson; charset=utf-8`), one event object per line:
 
 ```bash
-curl -N https://<deployment>/eve/v1/session/ses_01h.../stream
+curl -N https://<deployment>/eve/v1/session/wrun_A/stream
 # {"type":"turn.started",...}
 # {"type":"message.appended","data":{"messageDelta":"It is ",...}}
 # {"type":"message.completed",...}
 ```
 
+### Cancel a turn
+
 Cancel a session's in-flight turn with an empty body, or scope the cancel to the turn you observed by passing the `turnId` stamped on that turn's stream events:
 
 ```bash
-curl -X POST https://<deployment>/eve/v1/session/ses_01h.../cancel
-# {"ok":true,"sessionId":"ses_01h...","status":"accepted"}
+curl -X POST https://<deployment>/eve/v1/session/wrun_A/cancel
+# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
+```
+
+Cancellation is asynchronous: `"accepted"` means the live session durably queued the request. Confirm an actual cancellation on the stream as `turn.cancelled` followed by `session.waiting`—never as a failure. Active local and remote subagents are cancelled recursively before the parent settles. Content emitted before cancellation stays on the event stream, while durable model history keeps only content that had already settled. The session accepts the next message normally.
+
+An accepted cancellation returns HTTP `202` with `sessionId`. An inactive target
+returns HTTP `200` with `{"ok":true,"status":"no_active_turn"}`.
+
+A live session also returns `"accepted"` when it is already parked; the driver consumes that late or duplicate cancel as a no-op. An unknown or terminal session returns `"no_active_turn"`. A `turnId` naming any other turn is likewise accepted and consumed as a no-op, so a guarded cancel racing a turn boundary cannot stop a turn the caller never saw.
+
+### Clear context
+
+Clear one session's model-message history without replacing the session:
+
+```bash
+curl -X POST https://<deployment>/eve/v1/session/wrun_A/clear
+# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
 ```
 
-Cancellation is asynchronous: `"accepted"` means a cancellation hook accepted the request. Confirm the effective outcome on the stream as `turn.cancelled` followed by `session.waiting` — never as a failure. Active local and remote subagents are cancelled recursively before the parent settles; their own streams carry their cancellation boundaries, and cancelled work does not emit `subagent.completed` on the parent. Content emitted before the cancel stays on the event stream, while durable model history keeps only content that had already settled. The session accepts the next message normally. When there is no resumable cancellation target (including an unknown session, a settled turn, or a duplicate cancel), the route responds with `"no_active_turn"` — also a success, so a stop button can fire and forget. A `turnId` naming any other turn is accepted and consumed as a no-op, so a guarded cancel racing a turn boundary cannot stop a turn the caller never saw.
+An accepted clear emits `context.cleared` followed by `session.waiting`. The next message uses the same session without prior model messages; the system prompt, tools, skills, durable state, limits, and session-scoped sandbox remain.
+
+### Compact context
 
-Clear the model-message history of the session that owns a continuation token:
+Compact one session's context without sending a message:
 
 ```bash
-curl -X POST https://<deployment>/eve/v1/session/clear \
-  -H "Content-Type: application/json" \
-  -d '{"continuationToken":"eve:7f3c..."}'
-# {"ok":true,"sessionId":"ses_01h...","status":"accepted"}
+curl -X POST https://<deployment>/eve/v1/session/wrun_A/compact
+# {"ok":true,"sessionId":"wrun_A","status":"accepted"}
 ```
 
-An accepted clear emits `context.cleared` followed by `session.waiting`. The next message resumes the same session without prior model messages; the system prompt, tools and skills, durable state, limits, and session-scoped sandbox remain.
+Compaction is asynchronous. A successful operation emits `compaction.requested` and `compaction.completed`, then returns through `session.waiting`. When a turn is active, compaction waits for it to settle. If summarization fails, the session still returns to `session.waiting` with its previous history.
 
-Compact the session that owns a continuation token without sending a message:
+### Reset a session
+
+Reset terminally retires the exact session ID:
 
 ```bash
-curl -X POST https://<deployment>/eve/v1/session/compact \
+curl -X POST https://<deployment>/eve/v1/session/wrun_A/reset \
   -H "Content-Type: application/json" \
-  -d '{"continuationToken":"eve:7f3c..."}'
-# {"ok":true,"sessionId":"ses_01h...","status":"accepted"}
+  -d '{"reason":"Start over"}'
+# {"ok":true,"previousSessionId":"wrun_A","status":"reset"}
 ```
 
-Compaction is asynchronous. A successful operation emits `compaction.requested` and `compaction.completed`, then returns through `session.waiting`; when a turn is active, the operation waits for it to settle. If summarization fails, the session still returns to `session.waiting` with its previous history. `"no_active_session"` is the successful no-op response when the token has no owner.
+After reset, the old ID cannot accept another message. Start a replacement explicitly with `POST /eve/v1/session`.
+
+The control routes never create sessions. `compact`, `clear`, and `reset` return `"no_active_session"` when the ID is already inactive. Session message and control request/response bodies do not accept or return continuation tokens. For compatibility, the streamed `session.waiting` event retains `data.continuationToken`: it is the channel-local token for a channel-addressed session and the immutable session ID for an ID-only session. New clients should continue through their fixed session handle instead of reading this field.
 
-See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the full request and stream flow, including the complete event set.
+See [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming) for the complete event set, operation results, and cursor behavior.
 
 ## CORS
 
@@ -137,9 +181,8 @@ export default eveChannel({
     };
   },
   events: {
-    "message.completed"(eventData, channel, ctx) {
+    "message.completed"(eventData, _channel, ctx) {
       console.log("eve response completed", {
-        continuationToken: channel.continuationToken,
         sessionId: ctx.session.id,
       });
     },
@@ -147,11 +190,14 @@ export default eveChannel({
 });
 ```
 
+`onMessage` must return an auth result. A successful canonical eve HTTP message
+always dispatches and therefore always produces or continues a session.
+
 ## Clients
 
 The browser side of this API lives in the [Frontend](../guides/frontend/overview) docs, where `useEveAgent` drives the eve channel from React UI.
 
-For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript SDK](../guides/client/overview). It wraps the session routes, continuation token, stream cursor, and reconnect loop.
+For scripts, server-to-server calls, evals, tests, and custom clients, use the [TypeScript SDK](../guides/client/overview). It wraps the ID-addressed session routes, stream cursor, and reconnect loop.
 
 ## What to read next
 

package/docs/channels/github.mdx

@@ -103,7 +103,7 @@ GitHub comments have no interactive button or card affordance. A human-in-the-lo
 
 ### Proactive sessions
 
-Start a session without an inbound comment invocation through `receive(github, { message, target, auth })` from a schedule `run` handler, or `args.receive(github, ...)` from another channel. The target requires `owner`, `repo`, and exactly one of `issueNumber` or `pullRequestNumber`.
+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`.
 
 ### Attachments
 

package/docs/channels/linear.mdx

@@ -160,7 +160,7 @@ await channel.linear.updateSession({
 
 ## Proactive sessions
 
-Use the channel's `receive` target to continue an existing Agent Session or create one from a Linear issue or root comment. The target accepts an existing `agentSessionId`, or an `issueId` or root `commentId` to create a new session before sending the message. The example below runs from a schedule; a route handler uses the same target shape through its own `receive` helper.
+Use the channel's proactive target to continue an existing Agent Session or create one from a Linear issue or root comment. The target accepts an existing `agentSessionId`, or an `issueId` or root `commentId` to create a new session before sending the message. The example below runs from a schedule; a route handler uses the same target shape through `ctx.to(...)`.
 
 ```ts
 import { defineSchedule } from "eve/schedules";
@@ -169,15 +169,13 @@ import linear from "../channels/linear";
 
 export default defineSchedule({
   cron: "0 14 * * 1",
-  async run({ receive, waitUntil, appAuth }) {
+  async run({ to, waitUntil, appAuth }) {
     waitUntil(
-      receive(linear, {
+      to(linear, {
+        issueId: "EVE-123",
+        initialActivity: "Preparing the status update.",
+      }).send("Post a concise status update with blockers and next actions.", {
         auth: appAuth,
-        message: "Post a concise status update with blockers and next actions.",
-        target: {
-          issueId: "EVE-123",
-          initialActivity: "Preparing the status update.",
-        },
       }),
     );
   },