eve 0.30.8 → 0.31.0

package/docs/channels/overview.mdx

@@ -6,7 +6,7 @@ description: "How users reach your agent: the channel contract, the base eve HTT
 A channel is the edge adapter between a platform and your agent. It does three things:
 
 - Normalizes platform input into a user message.
-- Owns the `continuationToken`, the resume handle for a conversation on that surface.
+- Owns the channel-local address that maps a platform conversation to its current durable session.
 - Decides delivery, meaning how, where, and whether a response goes back.
 
 eve ships a base HTTP channel plus first-class platform channels, and you can author your own. Browse the full set in the [Integrations](/integrations) gallery and choose the Channels filter.
@@ -36,7 +36,7 @@ The eve channel is the framework's default HTTP session API, the routes the term
 
 ## Custom channels
 
-When eve doesn't ship a channel for your surface, build one with `defineChannel` from `eve/channels`. A custom channel declares route handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `WS`), an `events` map, and a `send` call inside a handler to start or resume a session. See [Custom channels](./custom) for the full walkthrough, including WebSocket routes, cross-channel hand-off, channel metadata, continuation tokens, and file uploads.
+When eve doesn't ship a channel for your surface, build one with `defineChannel` from `eve/channels`. A custom channel declares route handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `WS`), an `events` map, and uses `send(address, input)` to start or resume a session. See [Custom channels](./custom) for the full walkthrough, including WebSocket routes, cross-channel hand-off, channel metadata, address tokens, and file uploads.
 
 ## Relationship to the Chat SDK
 

package/docs/channels/slack.mdx

@@ -108,7 +108,7 @@ Like `threadContext`, this helper calls `conversations.replies` and requires the
 
 #### Cancel an active turn
 
-Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) receive a thread-bound `ctx.cancel({ turnId? })` helper. Call it before returning `{ auth }` to stop the current turn and queue the new Slack message as replacement input, producing a debounce-like experience:
+Message hooks (`onMessage`, `onAppMention`, and `onDirectMessage`) receive thread-bound session operations directly on `ctx`. Call `ctx.cancel({ turnId? })` before returning `{ auth }` to stop the current turn and queue the new Slack message as replacement input, producing a debounce-like experience:
 
 ```ts title="agent/channels/slack.ts"
 export default slackChannel({
@@ -123,11 +123,28 @@ export default slackChannel({
 });
 ```
 
-`"accepted"` means the cancellation request was consumed; `"no_active_turn"` means the thread had no cancellable turn. Both are successful outcomes, so the hook can still return `{ auth }` to deliver the replacement message. Cancellation never sends input itself. A custom `onInteraction` handler receives the same bound helper, which is useful for a Stop button that should cancel without replacement input.
+`"accepted"` means the live thread session durably queued the cancellation request. A parked session consumes it as a no-op; `"no_active_turn"` means the thread has no active session owner. Both are successful outcomes, so the hook can still return `{ auth }` to deliver the replacement message. Cancellation never sends input itself. A custom `onInteraction` handler receives the same flat operations, which is useful for a Stop button that should cancel without replacement input.
+
+Message and interaction hooks expose every current-owner operation directly on `ctx`:
+
+```ts
+async onAppMention(ctx) {
+  await ctx.send("Run a separate turn.");
+  await ctx.respond(inputResponses);
+  await ctx.cancel();
+  await ctx.compact();
+  await ctx.clear();
+  await ctx.reset({ reason: "Start over" });
+  const session = await ctx.resolveSession();
+  return { auth: null };
+}
+```
+
+These calls are independent examples; a handler normally chooses one. `ctx.send()` is the only method that can create a session when the thread is unowned. It derives Slack auth from the inbound user unless `auth` is supplied explicitly. Use `await ctx.resolveSession()` only when later work must stay pinned to the currently owning durable session ID.
 
 #### Reset a conversation
 
-Use the thread-bound `ctx.reset({ reason? })` helper when the conversation should start over instead. Reset terminally retires the session that currently owns the thread, including any in-flight turn. The next delivered message starts a new session with fresh history, state, and a new session-scoped sandbox:
+Use the thread-bound `ctx.reset({ reason? })` method when the conversation should start over instead. Reset terminally retires the session that currently owns the thread, including any in-flight turn. The next delivered message starts a new session with fresh history, state, and a new session-scoped sandbox:
 
 ```ts title="agent/channels/slack.ts"
 export default slackChannel({
@@ -142,11 +159,11 @@ export default slackChannel({
 });
 ```
 
-Reset returns `{ status: "reset", previousSessionId }` when the thread had a session, or `{ status: "no_active_session" }` when it was already free. Both outcomes are successful. Returning `null` after reset consumes the triggering message as a command; return `{ auth }` instead to deliver that message as the first turn of the fresh session. Custom `onInteraction` handlers receive the same bound reset helper, which is useful for a New conversation button.
+Reset returns `{ status: "reset", previousSessionId }` when the thread had a session, or `{ status: "no_active_session" }` when it was already free. Both outcomes are successful. Returning `null` after reset consumes the triggering message as a command; return `{ auth }` instead to deliver that message as the first turn of the fresh session. Custom `onInteraction` handlers receive the same flat operations, which is useful for a New conversation button.
 
 ### Other Events API callbacks
 
-Use `onEvent` for subscribed events such as `reaction_added`, `team_join`, or `channel_created`. It receives the raw, open-ended Slack event and owns control flow. `ctx.receive(options)` is the current Slack channel's pre-bound form of the schedule API's `receive(slack, options)`: call it zero, one, or many times to start turns. Each call accepts `message`, `target`, and `auth`, and returns the resulting session.
+Use `onEvent` for subscribed events such as `reaction_added`, `team_join`, or `channel_created`. It receives the raw, open-ended Slack event and owns control flow. Call `ctx.send(message, { target, auth })` zero, one, or many times to start turns. Each call returns the resulting session.
 
 ```ts title="agent/channels/slack.ts"
 import { connectSlackCredentials } from "@vercel/connect/eve";
@@ -156,25 +173,39 @@ const onboardingChannels = ["C0123ABC", "C0456DEF"];
 
 export default slackChannel({
   credentials: connectSlackCredentials("slack/my-agent"),
-  async onEvent({ receive }, event) {
+  async onEvent(ctx, event) {
     if (event.type !== "team_join") return;
 
     await Promise.all(
       onboardingChannels.map((channelId) =>
-        receive({
-          message: `A user joined the Slack workspace. Onboard them from this event:\n${JSON.stringify(event)}`,
-          target: { channelId },
-          auth: null,
-        }),
+        ctx.send(
+          `A user joined the Slack workspace. Onboard them from this event:\n${JSON.stringify(event)}`,
+          {
+            target: { channelId },
+            auth: null,
+          },
+        ),
       ),
     );
   },
 });
 ```
 
-The webhook invocation already keeps an awaited `onEvent` handler alive. Use `ctx.waitUntil(promise)` for deliberately detached work, matching a handler-form schedule. `ctx.slack.request(operation, body)` provides workspace-scoped Slack Web API access, while `ctx.envelope` carries delivery metadata such as `team_id`, `event_id`, and `event_time`. Calls to `ctx.receive` automatically seed the callback's team id into Slack session state.
+The webhook invocation already keeps an awaited `onEvent` handler alive. Use `ctx.waitUntil(promise)` for deliberately detached work, matching a handler-form schedule. `ctx.slack.request(operation, body)` provides workspace-scoped Slack Web API access, while `ctx.envelope` carries delivery metadata such as `team_id`, `event_id`, and `event_time`. Calls to `ctx.send` automatically seed the callback's team id into Slack session state.
+
+Because a generic event is not necessarily tied to one thread, put the target in each operation's input:
 
-Because a generic event is not necessarily tied to one thread, its session helpers take the target explicitly: `ctx.cancel({ channelId, threadTs, turnId? })` stops in-flight work while retaining the session, and `ctx.reset({ channelId, threadTs, reason? })` retires the session. Pair either one with `ctx.receive(...)` when an event should deliver replacement input, or call it alone to stop or reset the thread.
+```ts
+const target = { channelId, threadTs };
+
+await ctx.send("Follow up", { auth: null, target });
+await ctx.respond(inputResponses, { auth: null, target });
+await ctx.cancel({ target, turnId });
+await ctx.compact({ target });
+await ctx.clear({ target });
+await ctx.reset({ reason: "Start over", target });
+const session = await ctx.resolveSession({ target });
+```
 
 `onEvent` is the raw fallback after the message hooks. If an event is not claimed by `onAppMention`, `onDirectMessage`, or `onMessage`, an authored `onEvent` receives it; otherwise eve applies the built-in mention/DM default or ignores it.
 
@@ -233,7 +264,7 @@ The default handlers reply in-thread and show progress. Typing indicators post a
 
 Outbound text preserves bare `@` tokens as literal text. To mention a user, embed Slack's `<@USER_ID>` syntax directly or use `channel.thread.mentionUser(userId)`.
 
-When a session starts without a `threadTs` (say, from a schedule or `receive(slack, ...)`), eve gives it a unique temporary continuation token. The first agent post anchors the session to the Slack message timestamp, and later posts and mentions resume that same session. Pass `initialMessage` with a `Card` to land a structured anchor first instead. `threadTs` and `initialMessage` are mutually exclusive.
+When a session starts without a `threadTs` (say, from a schedule's `to(slack, target).send(...)`), eve gives it a unique temporary continuation token. The first agent post anchors the session to the Slack message timestamp, and later posts and mentions resume that same session. Pass `initialMessage` with a `Card` to land a structured anchor first instead. `threadTs` and `initialMessage` are mutually exclusive.
 
 The example below overrides `onAppMention` to gate on an authored message and posts the completed reply to the thread. Event handlers receive `(eventData, channel, ctx)`, with Slack platform handles on `channel.thread` and `channel.slack`:
 
@@ -272,7 +303,7 @@ events: {
 
 ### Proactive sessions
 
-Start a session without an inbound message through `receive(slack, { message, target, auth })` from a schedule `run` handler, or `args.receive(slack, ...)` from another channel. The proactive target shape is `{ channelId }`.
+Start a session without an inbound message through `ctx.to(slack, target).send(message, { auth })` from another channel, or `to(slack, target).send(message, { auth })` from a schedule `run` handler. The proactive target shape is `{ channelId, threadTs?, initialMessage? }`.
 
 ### Attachments
 

package/docs/channels/telegram.mdx

@@ -51,7 +51,7 @@ Human-in-the-loop (HITL) turns option requests into inline-keyboard buttons and
 
 ### Proactive sessions
 
-Start a session without an inbound message through `receive(telegram, { message, target, auth })` from a schedule `run` handler, or `args.receive(telegram, ...)` from another channel. `target.chatId` is required. Add `messageThreadId` to land in a specific forum topic.
+Start a session without an inbound message through `to(telegram, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(telegram, target).send(message, { auth })` from another channel. `target.chatId` is required. Add `messageThreadId` to land in a specific forum topic.
 
 Private proactive chats stay keyed to the chat, or to the chat plus `messageThreadId` when you target a topic. Group and supergroup proactive sends anchor to the bot message id returned by Telegram, so replies to different bot messages can resume different sessions in the same chat. If Telegram does not return a recognized chat type for an outbound send, eve keeps the session unanchored instead of guessing.
 

package/docs/channels/twilio.mdx

@@ -66,7 +66,7 @@ SMS and voice have no native button or card affordance, so HITL prompts do not r
 
 ### Proactive sessions
 
-Start a session without an inbound message through `receive(twilio, { message, target, auth })` from a schedule `run` handler, or `args.receive(twilio, ...)` from another channel. `target.phoneNumber` is required, and the channel needs `messaging.from` or `messaging.messagingServiceSid` for the outbound sender.
+Start a session without an inbound message through `to(twilio, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(twilio, target).send(message, { auth })` from another channel. `target.phoneNumber` is required, and the channel needs `messaging.from` or `messaging.messagingServiceSid` for the outbound sender.
 
 ### Attachments
 

package/docs/concepts/default-harness.md

@@ -20,9 +20,17 @@ export default defineAgent({
 
 Compaction also preserves the framework's own tool state automatically. It resets read-before-write tracking (so a write afterward re-reads the file whose read evidence was summarized away) and re-injects the active todo list, so the model keeps its task list across the summary. There is no per-tool hook to configure.
 
-Clients and channels can also request compaction between turns. Call `ClientSession.compact()` or a custom route's `compact({ continuationToken })` helper. The request does not append a user message; if a turn is running, eve queues it until that turn settles. A successful manual compaction emits the same `compaction.requested` and `compaction.completed` events as automatic compaction, followed by `session.waiting`.
-
-To discard model-message history instead of summarizing it, call `ClientSession.clear()` or a custom route's `clear({ continuationToken })` helper. Clearing preserves the session identity, system prompt, configured tools and skills, durable state, limits, and sandbox. Its stream boundary is `context.cleared` followed by `session.waiting`.
+Clients and channels can also request compaction between turns. Call
+`ClientSession.compact()`, a channel route's `compact(address)`, or
+`attachSession(sessionId).compact()`. The request does not append a user message;
+if a turn is running, eve queues it until that turn settles. A successful manual
+compaction emits the same `compaction.requested` and `compaction.completed`
+events as automatic compaction, followed by `session.waiting`.
+
+To discard model-message history instead of summarizing it, call the corresponding
+`clear()` method on any of those handles. Clearing preserves the session identity,
+system prompt, configured tools and skills, durable state, limits, and sandbox.
+Its stream boundary is `context.cleared` followed by `session.waiting`.
 
 ## Built-in tools
 

package/docs/concepts/execution-model-and-durability.mdx

@@ -68,11 +68,23 @@ Some work has to wait, including a human approving a [tool](../tools), an intera
 
 ## Message delivery and queueing
 
-eve does not maintain a durable FIFO queue of user messages for a session. The `continuationToken` is a resume handle for the session's current workflow hook, not a general message-queue address.
-
-Only one active session can own a continuation token. When a session starts with a token, eve commits the park hook before processing its first turn and fails a competing session if another run already owns that token. A tokenless session claims its token after the first turn establishes one. Competing input is not forwarded to the owner.
-
-When a session is waiting, a delivery to the current continuation token wakes the session and starts the next turn. When a turn is already active, the hook may accept additional deliveries, but the runtime only drains them at specific workflow boundaries. If more than one delivery is ready when the driver checks, eve may fold them into the next turn; that drain is best-effort and depends on workflow and transport timing.
+eve does not maintain a durable FIFO queue of user messages for a session. An
+ID-addressed HTTP delivery and a channel-address delivery both target the
+session's current command inbox; neither is a general message queue.
+
+Only one active session can own a channel continuation token. A channel-created
+session commits both its stable session-ID alias and its channel alias before
+processing the first turn, and fails creation if another run already owns the
+channel alias. Rekeying replaces only that channel alias. An HTTP-created
+session has the stable ID alias and no channel continuation token. Competing
+channel input is not forwarded to the owner.
+
+When a session is waiting, a delivery through its ID or current channel address
+wakes the session and starts the next turn. When a turn is already active, the
+inbox may accept additional deliveries, but the runtime only drains them at
+specific workflow boundaries. If more than one delivery is ready when the driver
+checks, eve may fold them into the next turn; that drain is best-effort and
+depends on workflow and transport timing.
 
 So don't rely on concurrent sends to the same session behaving like a typical ordered chat queue. For deterministic behavior, send one user turn at a time and wait for `session.waiting` before sending the next message to the same session. If your channel can receive bursts while the agent is working, keep your own per-session queue in the channel or app layer, then deliver the next message after the session parks again. Separate sessions still run independently.
 

package/docs/concepts/sessions-runs-and-streaming.md

@@ -1,18 +1,20 @@
 ---
 title: "Sessions, Runs & Streaming"
-description: "The session and run contract you touch: continuation tokens, stream handles, the NDJSON event stream, and reconnecting."
+description: "The ID-addressed session contract: messages, controls, the NDJSON event stream, and reconnecting."
 ---
 
 Every eve app speaks the same stable HTTP API to a [durable session](./execution-model-and-durability). This page is the contract you hold: the handles you get back, the events you stream, and how to reconnect.
 
-## The two handles
+## Identity by surface
 
-Two handles do two jobs, and mixing them up is the most common mistake. One handle creates and resumes a session; a different one streams and inspects it.
+The HTTP API and TypeScript client use one durable `sessionId` for messages,
+controls, and streams. Every operation targets that exact session; none follows
+or creates a replacement implicitly.
 
-- **`continuationToken`**: the resume handle. Use it to send a follow-up message to the same conversation. Owned by the channel.
-- **`sessionId` / `runId`**: the stream-and-inspect handle. Use it to attach to the event stream and watch a run. Owned by the runtime.
-
-A session has one active continuation at a time: each follow-up uses the current `continuationToken`, and a stale one is rejected.
+Authored channels also have channel-local continuation tokens. A token addresses
+whichever session currently owns a platform conversation, such as a Slack thread.
+That identity stays behind the channel boundary and is never accepted or returned
+by the eve HTTP session API. See [Custom channels](../channels/custom#address-and-session-handles).
 
 Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
 `agent.ts`, or set it to `false` to disable the deadline. At expiration, eve
@@ -30,7 +32,8 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session \
   -d '{"message":"Summarize the latest forecast."}'
 ```
 
-eve responds right away. The JSON body carries a `sessionId` and a `continuationToken`, and the `x-eve-session-id` header names the durable session to stream.
+eve responds right away with the durable `sessionId` in the JSON body and
+`x-eve-session-id` header.
 
 ## Stream a session
 
@@ -66,7 +69,7 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | `turn.completed`          | The turn finished.                                                                                               |
 | `turn.failed`             | The turn failed; carries `{ code, message, details? }`.                                                          |
 | `turn.cancelled`          | The turn was cancelled before finishing; always followed by `session.waiting`.                                   |
-| `session.waiting`         | The session parked for the next input; carries the current channel-owned `continuationToken`.                    |
+| `session.waiting`         | The session parked and is ready for the next message.                                                            |
 | `session.failed`          | The session failed.                                                                                              |
 | `session.completed`       | The session reached a terminal end.                                                                              |
 
@@ -137,12 +140,12 @@ Authored [hooks](../guides/hooks) receive the same envelope, but observe each ev
 
 ## Send a follow-up message
 
-Once the session is waiting (you'll see `session.waiting`), POST your follow-up to the session endpoint with `event.data.continuationToken`:
+Once the session is waiting (you'll see `session.waiting`), POST your follow-up to its ID-addressed messages endpoint:
 
 ```bash
 curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
   -H 'content-type: application/json' \
-  -d '{"continuationToken":"<token>","message":"Now send the short version."}'
+  -d '{"message":"Now send the short version."}'
 ```
 
 The follow-up reuses the same durable session: same history, same state.
@@ -166,9 +169,30 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/cancel
 # {"ok":true,"sessionId":"<sessionId>","status":"accepted"}
 ```
 
-`"accepted"` means a cancellation hook accepted the request. Confirm cancellation on the stream as `turn.cancelled` followed by `session.waiting`; the session then accepts the next message normally. If the turn is waiting on active local or remote subagents, eve also requests cancellation of every adopted child, recursively, before settling the parent. Each child reports its own cancellation boundary on its child-session stream; the parent does not emit `subagent.completed` for cancelled work. `"no_active_turn"` means no resumable cancellation target exists, including an unknown session or an already-settled turn. Both statuses are success, so clients can fire and forget. See the [eve channel](../channels/eve) for the full route contract.
+`"accepted"` means the live session durably queued the request. Confirm an actual cancellation on the stream as `turn.cancelled` followed by `session.waiting`; the session then accepts the next message normally. If the turn is waiting on active local or remote subagents, eve also requests cancellation of every adopted child, recursively, before settling the parent. Each child reports its own cancellation boundary on its child-session stream; the parent does not emit `subagent.completed` for cancelled work. A live but already-parked session also returns `"accepted"` and consumes the command as a no-op. `"no_active_turn"` means the session or channel address is unknown or terminal. Both statuses are success, so clients can fire and forget. See the [eve channel](../channels/eve) for the full route contract.
+
+The HTTP route returns `202` for `"accepted"` and `200` for
+`"no_active_turn"`. Only the accepted result includes `sessionId`.
+
+Custom channel routes request the same cancellation through
+`from(address).cancel()` or `attachSession(sessionId).cancel()`. See
+[custom channels](../channels/custom#channel-operations-and-session-handles).
+
+## Compact, clear, and reset
+
+All session controls are ID-addressed and accept no continuation token:
+
+```bash
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/compact
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/clear
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
+  -H 'content-type: application/json' \
+  -d '{"reason":"Start over"}'
+```
 
-Custom channel routes request the same cancellation without knowing the session id: the `cancel` route helper is addressed by the channel-local continuation token, and `Session.cancel()` by session id. See [custom channels](../channels/custom#cancel-a-turn).
+Compaction summarizes context, clear removes model-message history in place,
+and reset terminally retires the session. A reset ID never becomes a new session;
+create another session explicitly for a fresh conversation.
 
 ## Reconnect and rewind
 
@@ -186,7 +210,9 @@ A negative `startIndex` reads relative to the stream's current tail. For example
 curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=-1"
 ```
 
-This gives a consumer that only persisted `sessionId` a lightweight way to recover the current `continuationToken`. Because a tail-relative position does not resolve to an absolute consumed-event count, client tail reads do not automatically reconnect or advance the stored cursor.
+Because a tail-relative position does not resolve to an absolute consumed-event
+count, client tail reads do not automatically reconnect or advance the stored
+cursor.
 
 For a catch-up read that stops instead of following the live stream, pass `includeTailIndex=1`. The response then carries the `x-eve-stream-tail-index` header: the zero-based index of the last durably recorded event, or `-1` before the first. Read from your cursor until it passes that tail, then disconnect — reconnecting from the updated cursor if the connection drops first:
 
@@ -201,7 +227,7 @@ The lookup is opt-in; requests without the parameter get no header. The TypeScri
 
 For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
 
-Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basic usage, sending messages, continuations, streaming, and per-turn `outputSchema` results.
+Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
 
 ## Inspect the agent over HTTP
 
@@ -227,6 +253,6 @@ The order is structural, not incidental. By the time a resolver or hook reads ch
 ## What to read next
 
 - [Execution model & durability](./execution-model-and-durability): what makes a session durable and how parked work resumes.
-- [Channels](../channels/overview): what owns the continuation token and delivery.
+- [Channels](../channels/overview): how platform addresses map to durable sessions.
 - [TypeScript SDK](../guides/client/overview): call these routes from scripts and server-side code.
 - [Frontend](../guides/frontend/overview): `useEveAgent` instead of raw routes.

package/docs/evals/cases.mdx

@@ -101,12 +101,12 @@ export default defineEval({
 
 `t` drives the primary session; `t.newSession()` returns an independent `EveEvalSession` against the same target, whose events feed the same run-level assertions.
 
-- `t.send(input)` sends a turn and waits for it to settle. It accepts the same input as `ClientSession.send()` (a string or a structured message) and resolves to a turn carrying `.message` and `.expectOk()`.
-- `t.start(input)` starts a turn but returns as soon as the server accepts it. The returned live turn exposes `.sessionId`, `.waitForEvent(...)`, `.cancel()`, and `.result()` for coordinating with work that is still running.
+- `t.send(message, options?)` sends a turn and waits for it to settle. It matches `ClientSession.send()` and resolves to a turn carrying `.message` and `.expectOk()`.
+- `t.start(message)` starts a text turn but returns as soon as the server accepts it. The returned live turn exposes `.sessionId`, `.waitForEvent(...)`, `.cancel()`, and `.result()` for coordinating with work that is still running.
 - `t.cancel()` requests cooperative cancellation of the primary session's active turn. Both `accepted` and `no_active_turn` are successful outcomes.
 - `t.sendFile(text, path, mediaType?)` attaches a local file as a data URL.
 - `t.requireInputRequest(filter?)` records a gate, requires exactly one pending request, and returns it. Filters match tool name, action input, prompt, display, and option ids.
-- `t.respond(...responses)` answers specific pending input requests and sends them as the next turn.
+- `t.respond(responses, options?)` answers specific pending input requests and sends them as the next turn.
 - `t.respondAll(optionId)` answers every pending input request with the same option and sends the responses as the next turn.
 - `t.reply` is the last assistant message (or `null`); `t.sessionId` is the current session id; `t.events` is the full typed event stream captured so far.
 

package/docs/evals/targets.mdx

@@ -24,7 +24,7 @@ export default defineEval({
 
 - `t.target.fetch(path, init)` performs an authenticated fetch against the target, useful for channel and webhook ingress. See [Authentication](#authentication) for how the runner authenticates.
 - `t.target.dispatchSchedule(id)` triggers a [schedule](../schedules) through the dev-only schedule route and returns the session ids it created. It works only against a target with dev routes enabled (the local `eve eval` dev server, or a deployment running in development mode), and throws otherwise.
-- `t.target.attachSession(sessionId, { startIndex? })` consumes one turn from a session created outside the eval, by a channel or a schedule, so its events feed the run-level assertions. `startIndex` skips events before that position, so a session already partway through its stream resumes from where you left off rather than replaying from the start. When the consumed turn parks (`session.waiting`), the attached session recovers the current continuation token from the stream, so `session.send(...)` and `session.respond(...)` continue the same durable session.
+- `t.target.attachSession(sessionId, { startIndex? })` consumes one turn from a session created outside the eval, by a channel or a schedule, so its events feed the run-level assertions. `startIndex` skips events before that position, so a session already partway through its stream resumes from where you left off rather than replaying from the start. The attached session stays bound to that exact ID, so `session.send(...)` and `session.respond(...)` continue it after the turn parks (`session.waiting`).
 - `t.target.watchTurn(sessionId, { startIndex? })` starts consuming an externally-created turn immediately and returns a live-turn handle. Use `waitForEvent(...)` to coordinate with mid-turn work, `cancel()` to request cancellation, and `result()` to consume through the boundary. The live turn's `.session` is the attached `EveEvalSession` for follow-up sends after settlement.
 
 Sessions attached this way are full `EveEvalSession`s: you can keep driving them and assert directly on that session (`session.succeeded()`, `session.calledTool(...)`). Aggregate assertions on `t` continue to read the whole run, including every attached session.

package/docs/guides/auth-and-route-protection.md

@@ -16,6 +16,7 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
 
 - `POST /eve/v1/session`
 - `POST /eve/v1/session/:sessionId`
+- `POST /eve/v1/session/:sessionId/{cancel,compact,clear,reset}`
 - `GET /eve/v1/session/:sessionId/stream`
 
 These routes are protected by the channel's auth policy. eve fails closed by default: production traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
@@ -181,7 +182,7 @@ import { createUnauthorizedResponse } from "eve/channels/auth";
 
 export default defineChannel({
   routes: [
-    POST("/message", async (req, { send }) => {
+    POST("/message", async (req) => {
       if (!isAllowed(req)) {
         return createUnauthorizedResponse({
           status: 403, // defaults to 401; code defaults to "forbidden" / "unauthorized"

package/docs/guides/client/continuations.mdx

@@ -1,137 +1,110 @@
 ---
-title: "Continuations"
-description: "Persist and resume eve client sessions with continuation tokens, session IDs, and stream cursors."
+title: "Session State"
+description: "Persist and resume eve client sessions with durable session IDs and stream cursors."
 ---
 
-Every eve client turn returns two handles, and mixing them up is a common mistake. The TypeScript client tracks both for you:
-
-- `continuationToken`: the resume handle. Use it to send the next user turn.
-- `sessionId`: the stream-and-inspect handle. Use it to attach to event history.
-
-`ClientSession` also tracks `streamIndex`, the count of events already consumed. Together these three fields make a `SessionState`.
+The TypeScript client uses one durable session ID for messages, controls, and
+streams. A `ClientSession` adds a local `streamIndex` cursor so reconnects do not
+replay events already consumed by that handle.
 
 ## Read and persist state
 
-After a streamed turn finishes, read `session.state`:
+Create the session with its first turn, then persist `session.state` after
+consuming the response:
 
 ```ts
-const session = client.session();
+const { session, response } = await client.sessions.create({
+  message: "Create a launch checklist.",
+});
 
-const response = await session.send("Create a launch checklist.");
 await response.result();
-
 await saveSessionState(session.state);
 ```
 
-As soon as `send()` returns, `session.state.sessionId` identifies the accepted in-flight turn for cancellation or stream reconnection. Consume the response before saving a fully advanced cursor: the continuation token and `streamIndex` update as events reach the turn boundary.
-
-Store the full state object:
+The state is deliberately small:
 
 ```ts
-interface SessionState {
-  continuationToken?: string;
-  sessionId?: string;
+interface ClientSessionState {
+  sessionId: string;
   streamIndex: number;
 }
 ```
 
-The continuation token resumes the conversation. The session ID and stream index let the client reconnect to the right stream position without replaying events it already consumed.
-
-`SessionState` is a cursor, not a chat transcript. If your app shows historical messages, persist the stream events separately and store them under your own chat or thread ID. On reload, pass the saved `SessionState` back to `client.session(savedState)` or `useEveAgent({ initialSession })`, and pass the saved events to your renderer or `useEveAgent({ initialEvents })`.
+It is a remote stream cursor, not a transcript. Persist events separately when
+your application renders chat history.
 
 ## Resume a saved session
 
-Pass the saved state back into `client.session()`:
+Attach a fixed handle to the saved ID and restore its cursor:
 
 ```ts
-import type { SessionState } from "eve/client";
+import type { ClientSessionState } from "eve/client";
 
-const saved = (await loadSessionState()) as SessionState;
-const session = client.session(saved);
+const saved = (await loadSessionState()) as ClientSessionState;
+const session = client.sessions.attach(saved.sessionId, {
+  streamIndex: saved.streamIndex,
+});
 
 const response = await session.send("Now shorten it.");
-const result = await response.result();
-console.log(result.message);
-```
-
-If all you have is a continuation token, pass it as shorthand:
-
-```ts
-const session = client.session(continuationToken);
-const response = await session.send("Continue where we left off.");
-await response.result();
+console.log((await response.result()).message);
 ```
 
-The shorthand can send a follow-up, but it doesn't know the previous stream cursor. Prefer full `SessionState` when you control persistence.
-
-## Waiting, completed, and failed sessions
+`attach()` performs no request. Every later operation targets exactly
+`saved.sessionId`; it never follows or creates a replacement.
 
-When a turn ends with `session.waiting`, the event carries the current channel-owned `data.continuationToken` and the client preserves the state so the next send continues the conversation.
+## Waiting, completed, and reset sessions
 
-When a turn ends with `session.completed` or `session.failed`, the client resets its local state. The next send starts a fresh durable session:
+A session that emits `session.waiting` accepts another message through the same
+handle. A terminal or reset session does not. Start a fresh conversation
+explicitly with another `client.sessions.create(firstTurn)` call.
 
 ```ts
-const response = await session.send("Do this one-shot task.");
-const result = await response.result();
-
-if (result.status === "completed") {
-  // session.state is now a fresh cursor: { streamIndex: 0 }
-}
+const reset = await session.reset({ reason: "Start over" });
+const { session: fresh, response } = await client.sessions.create({ message: "Begin again." });
 ```
 
-This matches the runtime contract, where only waiting sessions can accept the next user input.
+The old `session` remains pinned to its retired ID; `fresh` owns a different ID.
 
 ## Multiple sessions
 
-Create a separate `ClientSession` per conversation:
+Create one handle per conversation:
 
 ```ts
-const research = client.session();
-const support = client.session();
-
-const researchResponse = await research.send("Research competitors.");
-await researchResponse.result();
-
-const supportResponse = await support.send("Draft a support reply.");
-await supportResponse.result();
-
+const { session: research, response: researchResponse } = await client.sessions.create({
+  message: "Research competitors.",
+});
+const { session: support, response: supportResponse } = await client.sessions.create({
+  message: "Draft a support reply.",
+});
+
+await Promise.all([researchResponse.result(), supportResponse.result()]);
 await save("research", research.state);
 await save("support", support.state);
 ```
 
-The shared `Client` only owns host, auth, headers, and reconnect settings. Conversation state lives on each `ClientSession`.
-
-For a multi-chat UI, this usually means one application row per chat with two eve fields: the latest `SessionState` and the ordered event log for rendering. Do not reuse one `ClientSession` across sidebar conversations, and do not treat `streamIndex` as your database row index; it is only the remote stream cursor for that eve session.
+The shared `Client` owns host, auth, headers, and redirect policy. Each
+`ClientSession` owns its fixed ID and stream cursor.
 
 ## Reconnect an existing stream
 
-When a session already has a `sessionId`, `session.stream()` reattaches to its stream from the saved cursor. Resuming a saved `SessionState` after a restart is the common reason to do this:
+`stream()` starts from the handle's saved cursor and advances it as events are
+read:
 
 ```ts
-const session = client.session(savedState);
+const session = client.sessions.attach(saved.sessionId, {
+  streamIndex: saved.streamIndex,
+});
 
 for await (const event of session.stream()) {
   console.log(event.type);
 }
 ```
 
-`stream()` attaches to an existing run; to send new user input, use `send()`. For overriding the cursor with `startIndex` and the full reconnection model, see [Streaming](./streaming#open-a-stream-manually).
-
-If you only persisted `sessionId`, read the latest durable event to recover the current token from a waiting session:
-
-```ts
-const session = client.session({ sessionId, streamIndex: 0 });
-
-for await (const event of session.stream({ startIndex: -1 })) {
-  if (event.type === "session.waiting") {
-    await saveContinuationToken(event.data.continuationToken);
-  }
-  break;
-}
-```
+Use `send()` for new input. For explicit cursors, tail-relative reads, and
+bounded catch-up, see [Streaming](./streaming#open-a-stream-manually).
 
 ## What to read next
 
 - [Streaming](./streaming): stream events and reconnect by index
 - [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): the raw HTTP contract
-- [eve channel](../../channels/eve): where continuation tokens come from
+- [eve channel](../../channels/eve): the ID-addressed routes