eve 0.5.4 → 0.6.0-beta.3

package/dist/docs/public/channels/linear.mdx

@@ -0,0 +1,168 @@
+---
+title: "Linear"
+description: "Reach your agent through Linear Agent Sessions, with native Agent Activities for progress, questions, and responses."
+type: integration
+---
+
+The Linear channel uses Linear's Agent Session surface rather than ordinary comments. Users delegate work to the agent from Linear, Eve receives `AgentSessionEvent` webhooks at `/eve/v1/linear`, and the channel replies with native Agent Activities: `thought`, `action`, `elicitation`, `response`, and `error`.
+
+## Add the channel
+
+```ts title="agent/channels/linear.ts"
+import { linearChannel } from "eve/channels/linear";
+
+export default linearChannel({
+  credentials: {
+    accessToken: process.env.LINEAR_AGENT_ACCESS_TOKEN,
+    webhookSecret: process.env.LINEAR_WEBHOOK_SECRET,
+  },
+});
+```
+
+```bash
+LINEAR_AGENT_ACCESS_TOKEN=lin_api_... # posts Agent Activities and creates proactive sessions
+LINEAR_WEBHOOK_SECRET=...             # verifies Linear-Signature
+```
+
+If you'd rather not use env vars, pass the same values through `credentials: { accessToken, webhookSecret }`. Both fields also accept lazy resolver functions. The access token falls back to `LINEAR_AGENT_ACCESS_TOKEN`, `LINEAR_ACCESS_TOKEN`, `LINEAR_API_KEY`, or `LINEAR_API_TOKEN`; the webhook secret falls back to `LINEAR_WEBHOOK_SECRET`.
+
+## Configure Linear
+
+Create a Linear OAuth app, enable Agent Session events, and point the webhook URL at:
+
+```text
+https://<deployment>/eve/v1/linear
+```
+
+For Linear's agent surface, configure the OAuth authorize URL with `actor=app` and grant the app scopes that let it appear as an agent in Linear, including `app:assignable` and `app:mentionable`. Subscribe to the `AgentSessionEvent` webhook category so Linear sends `created` events when the agent is delegated or mentioned and `prompted` events when the user continues the session.
+
+Linear sends webhook signatures in `Linear-Signature`; Eve verifies the HMAC over the raw body and rejects stale `webhookTimestamp` values. If a trusted gateway verifies Linear before the request reaches Eve, pass `credentials.webhookVerifier` instead of a webhook secret.
+
+## Affordances
+
+**Agent Session dispatch.** The default hook dispatches `created` and `prompted` Agent Session events. Eve adds a Linear context block with the agent session, issue, comment, and organization identifiers, then continues the same session with `agent-session:<id>`.
+
+**Native progress and replies.** Turn start posts an ephemeral `thought`, tool calls post ephemeral `action` activities, final assistant text posts a durable `response`, and failures post `error` activities. When the model emits text before a tool call, Eve buffers the first non-empty line and uses it as the next ephemeral Linear `thought`, mirroring Slack's typing-status behavior.
+
+**Human input.** Eve input requests are rendered as Linear `elicitation` activities. When the user replies to the Agent Session, the channel resolves that prompt back to the pending Eve input request and resumes with `inputResponses`.
+
+**API handle.** Event handlers receive `channel.linear`, which exposes `createActivity`, `listActivities`, and `updateSession` for custom Agent Activity delivery and Agent Session metadata.
+
+**Proactive sessions.** `receive(linear, { target })` accepts an existing `agentSessionId`, or can create a new Agent Session on an `issueId` or root `commentId` before sending the message.
+
+```ts
+await receive(linear, {
+  auth: null,
+  message: "Summarize the current status and risks.",
+  target: { issueId: "issue-id" },
+});
+```
+
+## Custom hooks
+
+Return `{ auth }` to dispatch, or `null` to acknowledge without waking the agent.
+
+```ts
+import { defaultLinearAuth, linearChannel } from "eve/channels/linear";
+
+export default linearChannel({
+  onAgentSession: (_ctx, event) => {
+    if (event.action !== "created" && event.action !== "prompted") return null;
+    return { auth: defaultLinearAuth(event) };
+  },
+});
+```
+
+Restrict dispatch to a subset of Linear teams or projects by inspecting `event.agentSession.issue` in `onAgentSession`. Add extra context by returning `context` alongside auth.
+
+```ts
+import { defaultLinearAuth, linearChannel } from "eve/channels/linear";
+
+export default linearChannel({
+  onAgentSession: (_ctx, event) => {
+    if (event.agentSession.issue?.identifier?.startsWith("OPS-") !== true) return null;
+    return {
+      auth: defaultLinearAuth(event),
+      context: ["Only make reversible changes unless the issue says otherwise."],
+    };
+  },
+});
+```
+
+Override event delivery when you want more specific Agent Activities.
+
+```ts
+import { linearChannel } from "eve/channels/linear";
+
+export default linearChannel({
+  events: {
+    async "message.completed"(event, channel) {
+      if (event.finishReason === "tool-calls" || !event.message) return;
+      await channel.linear.createActivity({
+        body: `Done.\n\n${event.message}`,
+        type: "response",
+      });
+    },
+    async "input.requested"(event, channel) {
+      await channel.linear.createActivity({
+        body: event.requests.map((request) => request.prompt).join("\n\n"),
+        type: "elicitation",
+      });
+    },
+  },
+});
+```
+
+Add session-level links when your agent creates an external artifact.
+
+```ts
+await channel.linear.updateSession({
+  addedExternalUrls: [{ label: "Run log", url: "https://example.com/runs/123" }],
+});
+```
+
+## Proactive sessions
+
+Use the channel's `receive` target to continue an existing Agent Session or create one from a Linear issue or root comment.
+
+```ts
+import { defineSchedule } from "eve/schedules";
+
+import linear from "../channels/linear.js";
+
+export default defineSchedule({
+  cron: "0 14 * * 1",
+  async run({ receive, waitUntil, appAuth }) {
+    waitUntil(
+      receive(linear, {
+        auth: appAuth,
+        message: "Post a concise status update with blockers and next actions.",
+        target: {
+          issueId: "EVE-123",
+          initialActivity: "Preparing the status update.",
+        },
+      }),
+    );
+  },
+});
+```
+
+Route handlers can use the same target shape through their `receive` helper:
+
+```ts
+await receive(linear, {
+  auth: null,
+  message: "Post a concise status update with blockers and next actions.",
+  target: {
+    issueId: "EVE-123",
+    initialActivity: "Preparing the status update.",
+  },
+});
+```
+
+For issue/comment targets, the channel calls Linear's proactive Agent Session mutations before starting the Eve turn. For an existing `agentSessionId`, it skips session creation and only seeds the continuation token.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Connections](../connections): use the Linear MCP connection when the agent needs to inspect or edit Linear data from another channel

package/dist/docs/public/channels/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Channels",
+  "pages": [
+    "overview",
+    "eve",
+    "slack",
+    "discord",
+    "teams",
+    "telegram",
+    "twilio",
+    "github",
+    "linear",
+    "custom"
+  ]
+}

package/dist/docs/public/channels/overview.mdx

@@ -0,0 +1,53 @@
+---
+title: "Overview"
+description: "How users reach your agent: the channel contract, the base Eve HTTP channel, and authoring custom channels."
+---
+
+A channel is the edge adapter between a platform and your agent, and its job is deliberately small. It does exactly three things: normalizes platform input into a user message, owns the `continuationToken` (the resume handle for a conversation on that surface), and decides delivery (how, where, and whether a response goes back).
+
+Eve ships a base HTTP channel plus first-class platform channels (Slack, Discord, Teams, Telegram, Twilio, GitHub, Linear), and you can author your own.
+
+## Where channels live
+
+Channel files live under `agent/channels/` in the root agent. The file stem is the channel id: `agent/channels/intake.ts` is addressed as `intake`. Export the channel as the module's default export. Local subagents do not declare channels.
+
+```text
+agent/
+  agent.ts
+  channels/
+    eve.ts
+    slack.ts
+    intake.ts
+```
+
+Scaffold a channel file with `eve channels add` (interactive), or pass a kind: `eve channels add slack` or `eve channels add web`. You can also author the file by hand.
+
+## The Eve HTTP channel (default)
+
+Eve's canonical HTTP session API: the routes the terminal UI, [`useEveAgent`](../frontend/overview), and `curl` all talk to. It is enabled by default, even with no `agent/channels/eve.ts` file. Add that file only to override the defaults, most often the route auth policy. See [Eve channel](./eve) for the routes, auth, and customization.
+
+## Custom channels
+
+When Eve doesn't ship a channel for your surface, build one with `defineChannel` from `eve/channels`: 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.
+
+## Which channel?
+
+| You want…                                   | Use                                                 |
+| ------------------------------------------- | --------------------------------------------------- |
+| A web app / browser chat UI                 | Eve channel + [`useEveAgent`](../frontend/overview) |
+| Local tooling, SDK clients, `curl`          | Eve channel (default)                               |
+| Slack mentions, DMs, buttons                | [Slack](./slack)                                    |
+| Discord slash commands, components          | [Discord](./discord)                                |
+| Microsoft Teams messages + Adaptive Cards   | [Teams](./teams)                                    |
+| Telegram bot messages                       | [Telegram](./telegram)                              |
+| SMS or speech-transcribed phone calls       | [Twilio](./twilio)                                  |
+| GitHub @mentions, PR review with checkout   | [GitHub](./github)                                  |
+| Linear issue delegation and Agent Sessions  | [Linear](./linear)                                  |
+| Anything else (internal webhook, WebSocket) | Custom channel (`defineChannel`, above)             |
+
+## What to read next
+
+- [Slack](./slack): the most common platform channel, end to end
+- [Custom channels](./custom): build a channel for any surface with `defineChannel`
+- [Frontend](../frontend/overview): browser chat on the Eve channel with `useEveAgent`
+- [Integrations](/integrations): browse every built-in channel and connection in one gallery

package/dist/docs/public/channels/slack.mdx

@@ -0,0 +1,92 @@
+---
+title: "Slack"
+description: "Reach your agent from Slack app mentions and DMs, with thread anchoring, buttons, and Vercel Connect credentials."
+type: integration
+---
+
+The Slack channel puts your agent inside a workspace: it answers `@mentions` and DMs, replies in threads, shows typing indicators, and turns HITL prompts into buttons. Use it when the conversation should happen where your team already works. Credentials run through [Vercel Connect](../advanced/auth-and-route-protection), which handles both the outbound bot token and inbound webhook verification, so there's no `SLACK_BOT_TOKEN` or `SLACK_SIGNING_SECRET` for you to manage. See [Channels](./overview) for the contract this builds on.
+
+## Set up Connect
+
+Create a Slack Connect client and copy its UID (e.g. `slack/my-agent`), then attach this project as the trigger destination at Eve's Slack route:
+
+```bash
+pnpm i -g vercel@latest && export FF_CONNECT_ENABLED=1
+vercel connect create slack --triggers
+vercel connect detach <uid> --yes
+vercel connect attach <uid> --triggers --trigger-path /eve/v1/slack --yes
+```
+
+`--triggers` turns on Slack Event Subscriptions; without it, Slack never delivers `app_mention` or `message.im`. `--trigger-path /eve/v1/slack` must match the channel route, since Eve doesn't serve the default Connect path. You can also create the client from the [Connect dashboard](https://vercel.com/d?to=/%5Bteam%5D/~/connect&title=Go+to+Connect).
+
+## Add the channel file
+
+Scaffold the channel and its dependency with `eve channels add slack`, or set it up by hand:
+
+```bash
+pnpm add @vercel/connect
+```
+
+```ts title="agent/channels/slack.ts"
+import { connectSlackCredentials } from "@vercel/connect/eve";
+import { slackChannel } from "eve/channels/slack";
+
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
+});
+```
+
+`connectSlackCredentials` returns `{ botToken, webhookVerifier }`. That keeps token rotation, multi-workspace tenancy, and request verification inside Connect rather than your code. Deploy once the trigger destination and channel file are ready:
+
+```bash
+VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1 vercel deploy --prod
+```
+
+## Affordances
+
+**Inbound hooks** decide whether to dispatch a turn and with what `auth`. Return `{ auth }` to dispatch, `null` to drop, or `{ auth, context }` to inject background into history.
+
+- `onAppMention(ctx, message)` handles `app_mention` events. The default derives workspace-scoped auth and posts a `Thinking…` indicator.
+- `onDirectMessage(ctx, message)` handles `message.im` events (needs `im:history` scope). Bot-authored messages and edits are filtered out first.
+- `onInteraction(action, ctx)` handles `block_actions` callbacks not consumed by HITL.
+
+**Thread context.** You get the triggering mention by default, but not the earlier replies in the thread. Pull them in with `loadThreadContextMessages` and return them as `context`, which Eve appends to history as user messages the model sees on every later turn. Use `since: "last-agent-reply"` so repeated mentions in one thread only inject what is new:
+
+```ts
+async onAppMention(ctx, message) {
+  const auth = defaultSlackAuth(message, ctx);
+  const prior = await loadThreadContextMessages(ctx.thread, message, { since: "last-agent-reply" });
+  if (prior.length === 0) return { auth };
+  const transcript = prior.map((m) => `${m.isMe ? "you" : (m.user ?? "user")}: ${m.markdown}`).join("\n");
+  return { auth, context: [`Recent thread messages since your last reply:\n\n${transcript}`] };
+}
+```
+
+**Thread anchoring.** When a session starts without a `threadTs` (say, from a schedule or `args.receive(slack, ...)`), it anchors on the first agent post, 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.
+
+**Typing indicators** post out of the box: `Thinking…` on inbound, `Working…` on `turn.started`, tool status on `actions.requested`. Override any handler to customize.
+
+**HITL** renders as Slack buttons/selects; submissions resume the parked session.
+
+```ts
+import { defaultSlackAuth, slackChannel } from "eve/channels/slack";
+
+export default slackChannel({
+  credentials: connectSlackCredentials("slack/my-agent"),
+  onAppMention: (ctx, message) =>
+    message.author ? { auth: defaultSlackAuth(message, ctx) } : null,
+  events: {
+    "message.completed"(event, ctx) {
+      if (event.finishReason === "tool-calls") return;
+      if (event.message) ctx.thread.post(event.message);
+    },
+  },
+});
+```
+
+Event handlers receive `(eventData, ctx)` with platform handles on `ctx.thread` and `ctx.slack`.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Auth & route protection](../advanced/auth-and-route-protection): authenticating inbound traffic

package/dist/docs/public/channels/teams.mdx

@@ -0,0 +1,55 @@
+---
+title: "Microsoft Teams"
+description: "Reach your agent from Microsoft Teams via the Bot Framework Activity protocol, with Adaptive Card HITL."
+type: integration
+---
+
+The Teams channel lets your agent live inside Microsoft Teams as a bot. It takes Bot Framework Activity POSTs, checks the Bot Connector bearer JWT on each one, and routes message activities to your agent. HITL prompts come back as Adaptive Cards, and replies go out over the Bot Framework Connector REST API. See [Channels](./overview) for the contract this builds on.
+
+## Add the channel
+
+```ts title="agent/channels/teams.ts"
+import { teamsChannel } from "eve/channels/teams";
+
+export default teamsChannel();
+```
+
+```bash
+MICROSOFT_APP_ID=...
+MICROSOFT_APP_PASSWORD=...
+MICROSOFT_TENANT_ID=...   # optional, single-tenant bots
+```
+
+By default the channel mounts at `POST /eve/v1/teams`. Point your Azure Bot or Teams app messaging endpoint at that public URL. To mount somewhere else, pass `route: "/api/teams/activity"`.
+
+## Affordances
+
+**Message dispatch.** The default `onMessage` handles two cases: personal-chat messages, and channel or group-chat messages that mention the bot directly. Ambient resource-specific-consent messages are dropped unless you override it. Before dispatch, Eve strips the mention, adds a `<teams_context>` block, and scopes channel and group threads by root activity id (`replyToId ?? id`).
+
+```ts
+import { defaultTeamsAuth, teamsChannel } from "eve/channels/teams";
+
+export default teamsChannel({
+  onMessage(ctx, message) {
+    if (message.scope !== "personal" && !message.isBotMentioned) return null;
+    return { auth: defaultTeamsAuth(message) };
+  },
+});
+```
+
+**Delivery & HITL.** Replies post as Markdown (`textFormat: "markdown"`), with oversized text split across messages and a typing indicator sent on turn start and action requests. An `input.requested` event renders as an Adaptive Card. Buttons and options map to `Action.Submit`, selects to `Input.ChoiceSet`, and freeform to `Input.Text`. When the user submits, the activity converts to Eve `inputResponses` for you. For invokes that aren't HITL, handle them in `onInvoke(ctx, activity)`.
+
+**Proactive sessions** need an existing conversation reference, because Teams v1 cannot create new chats by AAD user id. Pass `serviceUrl`, `conversationId`, etc. to `receive(teams, { target })`.
+
+**Files** are off by default. Opt in to enable personal-scope downloads and public media URLs:
+
+```ts
+export default teamsChannel({
+  files: { enabled: true, allowedHosts: ["contoso.sharepoint.com"] },
+});
+```
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Auth & route protection](../advanced/auth-and-route-protection): authenticating inbound traffic

package/dist/docs/public/channels/telegram.mdx

@@ -0,0 +1,56 @@
+---
+title: "Telegram"
+description: "Reach your agent from Telegram bot webhooks, with inline-keyboard HITL and attachments."
+type: integration
+---
+
+The Telegram channel puts your agent behind a Telegram bot. It takes Bot API webhooks, checks the `X-Telegram-Bot-Api-Secret-Token` header before it trusts anything, and routes the messages it cares about (private chats plus group messages that address the bot) to a reply over `sendMessage`. See [Channels](./overview) for the contract this builds on.
+
+## Add the channel
+
+```ts title="agent/channels/telegram.ts"
+import { telegramChannel } from "eve/channels/telegram";
+
+export default telegramChannel({
+  botUsername: "my_bot",
+});
+```
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:...        # replies, typing, callbacks, proactive sends
+TELEGRAM_WEBHOOK_SECRET_TOKEN=...    # must match the secret_token you register
+```
+
+You can pass the same values via `credentials: { botToken, webhookSecretToken }`. The channel mounts `POST /eve/v1/telegram`. Register the deployed URL yourself; Eve does not call `setWebhook`:
+
+```bash
+curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://your-app.example.com/eve/v1/telegram",
+       "secret_token":"'"$TELEGRAM_WEBHOOK_SECRET_TOKEN"'",
+       "allowed_updates":["message","callback_query"]}'
+```
+
+## Affordances
+
+**Dispatch.** In a private chat, text, captions, photos, and documents all go through. Groups are stricter. Only three things wake the bot: a command (`/ask`, `/ask@my_bot`), an `@my_bot` mention (when `botUsername` is set), or a reply to one of the bot's own messages. Everything else gets ignored. Forum topics carry `message_thread_id` in the continuation token, so each topic stays on its own thread. Need custom auth or filtering? Override `onMessage`. Group privacy mode itself lives in BotFather, not here.
+
+**Delivery.** The default `message.completed` handler sends plain text via `sendMessage`. It passes no `parse_mode`, so any Markdown shows up literally. Replies longer than Telegram's 4096-char limit get split across messages. Custom handlers reach for `ctx.telegram`.
+
+**HITL** turns option requests into inline-keyboard buttons and freeform requests into `ForceReply`. Telegram caps `callback_data` at 64 bytes, so Eve keeps compact callback ids in channel state instead. It acknowledges its own callbacks with `answerCallbackQuery`; anything it doesn't recognize goes to `onCallbackQuery`.
+
+**Attachments** are inbound photos and documents. Eve fetches them on demand via `getFile`, only when an upload policy allows the type:
+
+```ts
+export default telegramChannel({
+  botUsername: "my_bot",
+  uploadPolicy: { allowedMediaTypes: ["image/*", "application/pdf"], maxBytes: 10 * 1024 * 1024 },
+});
+```
+
+**Proactive sessions** start with `receive(telegram, { message, target, auth })` from a schedule `run` handler, or `args.receive(telegram, ...)` when you're kicking off from another channel. `target.chatId` is required. Add `messageThreadId` to land in a specific forum topic.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Auth & route protection](../advanced/auth-and-route-protection): authenticating inbound traffic

package/dist/docs/public/channels/twilio.mdx

@@ -0,0 +1,62 @@
+---
+title: "Twilio"
+description: "Reach your agent over SMS and speech-transcribed phone calls with Twilio."
+type: integration
+---
+
+The Twilio channel puts your agent on a phone number, so people can text it or call it. Inbound SMS arrives as a webhook. Inbound calls get answered with TwiML `<Gather input="speech">`, and the resulting transcript feeds the same Eve session that SMS uses, so a caller and a texter look identical downstream. Every request is checked against `X-Twilio-Signature` before anything else runs. The raw continuation token is `From:To`. See [Channels](./overview) for the contract this builds on.
+
+## Add the channel
+
+```ts title="agent/channels/twilio.ts"
+import { twilioChannel } from "eve/channels/twilio";
+
+export default twilioChannel({
+  allowFrom: "+15551234567",
+  messaging: { from: "+15557654321" },
+});
+```
+
+```bash
+TWILIO_ACCOUNT_SID=AC...   # required for default outbound SMS
+TWILIO_AUTH_TOKEN=...      # required for inbound signature verification
+```
+
+If you'd rather not use env vars, pass the same values via `credentials: { accountSid, authToken }`. The channel mounts three routes:
+
+- `POST /eve/v1/twilio/messages`: Messaging webhook
+- `POST /eve/v1/twilio/voice`: inbound call webhook
+- `POST /eve/v1/twilio/voice/transcription`: speech transcript callback
+
+Point your Twilio number's Messaging webhook at `/messages` and Voice webhook at `/voice`, using the exact public URL Twilio will call.
+
+## Affordances
+
+**`allowFrom` is required.** It gates who can reach the inbound hooks. Pass a single number, a list, an async resolver, or `"*"`. The wildcard is dangerous: only use it with an explicit check inside `onText`/`onVoice`.
+
+```ts
+export default twilioChannel({ allowFrom: ["+15551234567", "+15557654321"] });
+```
+
+**Hooks.** `onText` and `onVoiceTranscription` decide dispatch and `auth`: return `{ auth }` to proceed, or `null` to drop the message. `onVoice` fires the moment a call comes in. Return `null` to reject it, or return an object to override the spoken prompt, language, `<Say voice>`, and speech-recognition options.
+
+```ts
+export default twilioChannel({
+  allowFrom: ["+15551234567"],
+  onText: (ctx, message) => ({
+    auth: {
+      principalId: message.from,
+      principalType: "user",
+      authenticator: "twilio",
+      attributes: { to: message.to ?? "" },
+    },
+  }),
+});
+```
+
+**Delivery.** The default `message.completed` handler sends the reply as SMS through Twilio's Messages API. A reply to an inbound message can reuse the webhook's `To` as the sender, but a proactive send has nothing to reuse, so it needs `messaging.from` or `messaging.messagingServiceSid`. Behind a proxy, set `webhookUrl` so signature verification matches the exact configured URL, and `publicBaseUrl` so voice TwiML can build absolute callback URLs.
+
+## What to read next
+
+- [Channels overview](./overview): the channel contract and every built-in channel
+- [Auth & route protection](../advanced/auth-and-route-protection): authenticating inbound traffic

package/dist/docs/public/client/continuations.mdx

@@ -0,0 +1,126 @@
+---
+title: "Continuations"
+description: "Persist and resume Eve client sessions with continuation tokens, session IDs, and stream cursors."
+---
+
+Eve hands back two different handles, and mixing them up is the most 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 those fields make a `SessionState`.
+
+## Read and persist state
+
+After a streamed turn finishes, read `session.state`:
+
+```ts
+const session = client.session();
+
+const response = await session.send("Create a launch checklist.");
+await response.result();
+
+await saveSessionState(session.state);
+```
+
+Store the full state object:
+
+```ts
+interface SessionState {
+  continuationToken?: string;
+  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.
+
+## Resume a saved session
+
+Pass the saved state back into `client.session()`:
+
+```ts
+import type { SessionState } from "eve/client";
+
+const saved = (await loadSessionState()) as SessionState;
+const session = client.session(saved);
+
+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();
+```
+
+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
+
+When a turn ends with `session.waiting`, the client preserves the state so the next send continues the conversation.
+
+When a turn ends with `session.completed` or `session.failed`, the client resets its local state. The next send starts a fresh durable session:
+
+```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 }
+}
+```
+
+This matches the runtime contract: only waiting sessions can accept the next user input.
+
+## Multiple sessions
+
+Create a separate `ClientSession` 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();
+
+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`.
+
+## Reconnect an existing stream
+
+If a session already has a `sessionId`, `stream()` attaches to that stream from the saved cursor:
+
+```ts
+const session = client.session(savedState);
+
+for await (const event of session.stream()) {
+  console.log(event.type);
+}
+```
+
+Override the cursor when you want to replay from an earlier point:
+
+```ts
+for await (const event of session.stream({ startIndex: 0 })) {
+  console.log(event.type);
+}
+```
+
+`stream()` is for attaching to an existing run. To send new user input, use `send()`.
+
+## What to read next
+
+- [Streaming](./streaming): stream events and reconnect by index
+- [Sessions, runs & streaming](../advanced/sessions-runs-and-streaming): the raw HTTP contract
+- [Eve channel](../channels/eve): where continuation tokens come from