eve 0.30.8 → 0.31.0

package/docs/guides/client/messages.mdx

@@ -3,7 +3,7 @@ title: "Messages"
 description: "Send text, full turn payloads, client context, attachments, and HITL responses with eve/client."
 ---
 
-`ClientSession` sends one turn at a time. A fresh session starts on the first send; later sends continue the same conversation as long as the previous turn left the session waiting.
+Create a session with its first turn, then use the returned `ClientSession` for follow-ups. Each handle targets one durable session ID.
 
 ## Send text
 
@@ -13,12 +13,12 @@ Pass a string to `send()` for plain text:
 import { Client } from "eve/client";
 
 const client = new Client({ host: "http://127.0.0.1:2000" });
-const session = client.session();
-
-const response = await session.send("What is the weather in Brooklyn?");
+const { session, response } = await client.sessions.create({
+  message: "What is the weather in Brooklyn?",
+});
 
 // Metadata is available as soon as the POST succeeds.
-console.log(response.sessionId, response.continuationToken);
+console.log(response.sessionId);
 
 const result = await response.result();
 console.log(result.status, result.message);
@@ -38,10 +38,10 @@ When the stream includes `session.failed`, the turn returns `status: "failed"` r
 
 ## Send a full turn payload
 
-Use `send()` when you need more than plain text:
+Pass the full payload to `create()` for the first turn or `send()` for a follow-up:
 
 ```ts
-const response = await session.send({
+const { session, response } = await client.sessions.create({
   message: "What should I do on this screen?",
   clientContext: {
     route: "/billing",
@@ -60,17 +60,15 @@ await response.result();
 `send()` accepts AI SDK `UserContent`, so a message can mix text and file parts:
 
 ```ts
-const response = await session.send({
-  message: [
-    { type: "text", text: "Summarize this report." },
-    {
-      type: "file",
-      data: reportDataUrl,
-      mediaType: "application/pdf",
-      filename: "report.pdf",
-    },
-  ],
-});
+const response = await session.send([
+  { type: "text", text: "Summarize this report." },
+  {
+    type: "file",
+    data: reportDataUrl,
+    mediaType: "application/pdf",
+    filename: "report.pdf",
+  },
+]);
 
 await response.result();
 ```
@@ -83,17 +81,15 @@ import { readFile } from "node:fs/promises";
 const bytes = await readFile("report.pdf");
 const reportDataUrl = `data:application/pdf;base64,${bytes.toString("base64")}`;
 
-const response = await session.send({
-  message: [
-    { type: "text", text: "Summarize this report." },
-    {
-      type: "file",
-      data: reportDataUrl,
-      mediaType: "application/pdf",
-      filename: "report.pdf",
-    },
-  ],
-});
+const response = await session.send([
+  { type: "text", text: "Summarize this report." },
+  {
+    type: "file",
+    data: reportDataUrl,
+    mediaType: "application/pdf",
+    filename: "report.pdf",
+  },
+]);
 
 await response.result();
 ```
@@ -119,17 +115,17 @@ for await (const event of response) {
   }
 }
 
-const resumed = await session.send({
-  inputResponses: pendingRequests.map((request) => ({
+const resumed = await session.respond(
+  pendingRequests.map((request) => ({
     requestId: request.requestId,
     optionId: "approve",
   })),
-});
+);
 
 await resumed.result();
 ```
 
-You can send `message`, `inputResponses`, and `clientContext` together when the resumed turn needs both a human answer and follow-up text.
+`send(message, options)` and `respond(inputResponses, options)` are separate operations. Put `clientContext`, `outputSchema`, headers, or stream options in the second argument to either method.
 
 ## Single-use responses
 

package/docs/guides/client/output-schema.mdx

@@ -27,9 +27,7 @@ const outputSchema = {
 } as const;
 
 const client = new Client({ host: "http://127.0.0.1:2000" });
-const session = client.session();
-
-const response = await session.send<Summary>({
+const { session, response } = await client.sessions.create<Summary>({
   message: "Summarize this turn.",
   outputSchema,
 });
@@ -56,8 +54,7 @@ const summarySchema = z.object({
 
 type Summary = z.infer<typeof summarySchema>;
 
-const response = await session.send<Summary>({
-  message: "Summarize this turn.",
+const response = await session.send<Summary>("Summarize this turn.", {
   outputSchema: summarySchema,
 });
 
@@ -71,8 +68,7 @@ The server is authoritative for validation. The client types `MessageResult.data
 If you consume events manually, read `result.completed`:
 
 ```ts
-const response = await session.send<Summary>({
-  message: "Summarize this turn.",
+const response = await session.send<Summary>("Summarize this turn.", {
   outputSchema,
 });
 
@@ -88,11 +84,10 @@ If more than one `result.completed` appears in the consumed event list, `result(
 
 ## Send payloads with output schema
 
-`outputSchema` works with string shorthand and object-form sends. Use object form when you need schema, headers, signal, context, attachments, or HITL responses:
+Pass `outputSchema` in the second argument to `send()` or `respond()` alongside headers, signal, or client context:
 
 ```ts
-const response = await session.send<Summary>({
-  message: "Summarize this PDF.",
+const response = await session.send<Summary>("Summarize this PDF.", {
   clientContext: { reportId: "rpt_123" },
   outputSchema,
 });
@@ -103,9 +98,7 @@ const result = await response.result();
 It also works on follow-up turns and HITL response turns:
 
 ```ts
-const response = await session.send({
-  inputResponses: [{ requestId, optionId: "approve" }],
-  message: "Return the approved action as structured output.",
+const response = await session.respond([{ requestId, optionId: "approve" }], {
   outputSchema,
 });
 
@@ -117,7 +110,7 @@ const result = await response.result();
 Client `outputSchema` is scoped to the turn that sends it. It doesn't become a permanent setting for the conversation:
 
 ```ts
-const response = await session.send({ message: "Return a structured summary.", outputSchema });
+const response = await session.send("Return a structured summary.", { outputSchema });
 await response.result();
 
 const followUpResponse = await session.send("Now answer normally.");

package/docs/guides/client/overview.mdx

@@ -100,8 +100,7 @@ Set `redirect` to `"manual"` or `"error"` on credential-bearing clients so fetch
 Per-request headers can be attached to an individual turn:
 
 ```ts
-const response = await session.send({
-  message: "Run the check.",
+const response = await session.send("Run the check.", {
   headers: { "x-request-id": requestId },
 });
 
@@ -112,23 +111,53 @@ Per-request headers override client-level values with the same name. For example
 
 ## Sessions
 
-Create a `ClientSession` for each conversation:
+For an ID-addressed session, create it explicitly with the first message:
 
 ```ts
-const session = client.session();
+const { session, response } = await client.sessions.create({ message: "Summarize account A." });
+await response.result();
+
+await (await session.send("Now list the risks.")).result();
+await session.compact();
+await session.clear();
+```
+
+If you already know the durable ID, attach a fixed handle without performing I/O:
+
+```ts
+const session = client.sessions.attach("wrun_A");
 ```
 
-A client can own many sessions at once. Each session tracks its own `sessionId`, `continuationToken`, and stream cursor:
+The fixed client handle exposes the full lifecycle around that ID. The calls below show the available shapes independently:
 
 ```ts
-const alice = client.session();
-const bob = client.session();
+const response = await session.send("Continue the analysis.");
+await response.result();
+
+await session.cancel({ turnId: "turn_123" });
+await session.compact();
+await session.clear();
 
-const aliceResponse = await alice.send("Summarize account A.");
-await aliceResponse.result();
+for await (const event of session.stream({ follow: false })) {
+  console.log(event.type);
+}
+
+await session.reset({ reason: "User requested a fresh session" });
+```
+
+`client.sessions` stores only the session ID and stream cursor. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and reset leaves the handle pinned to the retired ID.
+
+A client can own many independent fixed sessions at once:
+
+```ts
+const { session: alice, response: aliceResponse } = await client.sessions.create({
+  message: "Summarize account A.",
+});
+const { session: bob, response: bobResponse } = await client.sessions.create({
+  message: "Summarize account B.",
+});
 
-const bobResponse = await bob.send("Summarize account B.");
-await bobResponse.result();
+await Promise.all([aliceResponse.result(), bobResponse.result()]);
 ```
 
 The next pages cover the session lifecycle:

package/docs/guides/client/streaming.mdx

@@ -5,18 +5,22 @@ description: "Consume eve client stream events live, reconnect by event index, a
 
 Every `ClientSession.send()` call posts the turn, then reads the session's NDJSON (newline-delimited JSON) event stream. `MessageResponse` gives you two ways to consume that stream, aggregating it with `result()` or iterating it live.
 
-Once `send()` is accepted, the session exposes its assigned `sessionId` and can request cooperative cancellation with `session.cancel()`, even while the response stream is still running. The result status is `accepted` when the active turn accepted the signal or `no_active_turn` when it already settled:
+Once `send()` is accepted, the session exposes its assigned `sessionId` and can request cooperative cancellation with `session.cancel()`, even while the response stream is still running. The result status is `accepted` when the live session durably queued the command, including when a parked session consumes it as a no-op. An unknown or terminal session returns `no_active_turn`:
 
 ```ts
-const session = client.session();
-const response = await session.send("Run the long operation.");
+const { session, response } = await client.sessions.create({ message: "Run the long operation." });
 
 const cancellation = await session.cancel();
-console.log(cancellation.status);
+if (cancellation.status === "accepted") {
+  console.log(cancellation.sessionId);
+}
 
 const result = await response.result();
 ```
 
+The cancellation result is discriminated by `status`: only `accepted` includes
+`sessionId`; `no_active_turn` has no session identity field.
+
 Cancellation does not replace stream consumption. Continue reading the response to observe its terminal `turn.cancelled` and `session.waiting` boundary and to advance the client session cursor normally.
 
 Between turns, `session.compact()` queues context compaction without sending model input. An accepted request reports the session id; consume the durable stream through the following `session.waiting` boundary before sending the next turn. `compaction.completed` confirms that summarization succeeded; without it, eve preserves the previous history. A never-started session returns `no_active_session` as a successful no-op.
@@ -103,7 +107,7 @@ The most common UI events are:
 | `action.result`      | Show tool call results.                                                        |
 | `input.requested`    | Pause the UI for approval or a question answer.                                |
 | `result.completed`   | Read structured output from an [output schema](./output-schema).               |
-| `session.waiting`    | Enable the composer and read the current `data.continuationToken`.             |
+| `session.waiting`    | Enable the composer; the same fixed session handle accepts the next message.   |
 | `session.completed`  | Mark the conversation terminal.                                                |
 | `session.failed`     | Mark the conversation failed.                                                  |
 
@@ -129,8 +133,7 @@ If your consumer persists events, key on `event.meta.id`. It is stable across re
 Set `streamReconnectPolicy: { reconnect: false }` when a relay or proxy owns the cursor and reconnection policy. This makes a single stream GET attempt and returns when that connection ends; it does not stop the server-side turn:
 
 ```ts
-const response = await session.send({
-  message: "Run the long operation.",
+const response = await session.send("Run the long operation.", {
   streamReconnectPolicy: { reconnect: false },
 });
 
@@ -146,9 +149,7 @@ The same option is available on manual attachments as `session.stream({ streamRe
 Use `session.stream()` when you already have a session cursor and only need to attach to the existing stream:
 
 ```ts
-const session = client.session({
-  continuationToken: "eve:6c8b1f2e-3d4a-4b9c-8e21-9f0a1b2c3d4e",
-  sessionId: "wrun_01ARYZ6S41TSV4RRFFQ69G5FAV",
+const session = client.sessions.attach("wrun_01ARYZ6S41TSV4RRFFQ69G5FAV", {
   streamIndex: 10,
 });
 
@@ -169,9 +170,7 @@ Nonnegative values are absolute event indexes. Negative values read relative to
 
 ```ts
 for await (const event of session.stream({ startIndex: -1 })) {
-  if (event.type === "session.waiting") {
-    console.log(event.data.continuationToken);
-  }
+  console.log(event.type);
   break;
 }
 ```
@@ -193,15 +192,13 @@ The first connection pins the bound to the tail the server reports at open time;
 
 Because a tail-relative cursor cannot be bounded, `follow: false` throws when combined with a negative `startIndex`. It also fails if the server does not report the durable tail (an agent running an older eve version).
 
-`stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
-
 ## Snapshot a session
 
 Use `snapshot()` when you need the complete event prefix and its matching cursor
 as one value, such as when hydrating a server-rendered chat:
 
 ```ts
-const session = client.session({ sessionId, streamIndex: 0 });
+const session = client.sessions.attach(sessionId);
 const snapshot = await session.snapshot();
 
 // snapshot.events contains event indexes 0 through snapshot.session.streamIndex - 1.
@@ -213,11 +210,9 @@ The read pins the durable tail when it opens, just like
 continue. `snapshot()` always reads from index `0`; use a bounded stream directly
 when you only need the unread suffix from an existing cursor.
 
-Unlike `stream()`, `snapshot()` does not advance or reset the originating
-`ClientSession`. Its returned session includes a continuation token only when
-the captured prefix ends in `session.waiting`, or when completed sessions are
-explicitly preserved by the client. Active and terminal snapshots remain
-inspectable at their returned stream cursor but cannot accept another turn.
+Unlike `stream()`, `snapshot()` does not advance the originating
+`ClientSession`. Its returned cursor contains the fixed session ID and the exact
+stream index after the captured prefix.
 
 ## Abort a request
 
@@ -229,8 +224,7 @@ Arm the timeout before awaiting `send()` so it covers the POST as well as the st
 const controller = new AbortController();
 const timeout = setTimeout(() => controller.abort(), 10_000);
 
-const response = await session.send({
-  message: "Run a long analysis.",
+const response = await session.send("Run a long analysis.", {
   signal: controller.signal,
 });
 

package/docs/guides/frontend/nuxt.mdx

@@ -48,7 +48,7 @@ async function handleSubmit() {
   const text = message.value.trim();
   if (!text || isBusy.value) return;
   message.value = "";
-  await send({ message: text });
+  await send(text);
 }
 </script>
 

package/docs/guides/frontend/overview.mdx

@@ -36,7 +36,7 @@ export function Chat() {
         const form = new FormData(event.currentTarget);
         const message = String(form.get("message") ?? "").trim();
         if (message.length > 0) {
-          void agent.send({ message });
+          void agent.send(message);
         }
       }}
     >
@@ -61,16 +61,17 @@ export function Chat() {
 
 `useEveAgent()` returns the current UI state plus commands:
 
-| Field     | What it is                                                                     |
-| --------- | ------------------------------------------------------------------------------ |
-| `data`    | Projected UI state from the reducer. Defaults to `{ messages }`.               |
-| `status`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. Drives the composer.    |
-| `error`   | The last `Error` thrown, if any.                                               |
-| `events`  | Raw eve stream events for this session.                                        |
-| `session` | Serializable session cursor (`sessionId`, `continuationToken`, `streamIndex`). |
-| `send`    | Send text or the full turn payload (multi-part messages, HITL responses).      |
-| `stop`    | Abort the client's in-flight stream. The server-side turn keeps running.       |
-| `reset`   | Clear local events, data, errors, and the local session cursor.                |
+| Field     | What it is                                                                  |
+| --------- | --------------------------------------------------------------------------- |
+| `data`    | Projected UI state from the reducer. Defaults to `{ messages }`.            |
+| `status`  | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`. Drives the composer. |
+| `error`   | The last `Error` thrown, if any.                                            |
+| `events`  | Raw eve stream events for this session.                                     |
+| `session` | Serializable fixed session cursor (`sessionId`, `streamIndex`).             |
+| `send`    | Send text or a multi-part message, with per-turn options.                   |
+| `respond` | Answer pending HITL input requests, with per-turn options.                  |
+| `stop`    | Abort the client's in-flight stream. The server-side turn keeps running.    |
+| `reset`   | Clear local events, data, errors, and the local session cursor.             |
 
 Most chat UIs only need `data.messages` and `status`. Drop down to `events` when you need the authoritative wire events directly, for example to persist an audit log or build a custom projection.
 
@@ -78,29 +79,31 @@ Most chat UIs only need `data.messages` and `status`. Drop down to `events` when
 
 ## Sending and streaming
 
-Pass an object to `send()` for text, multi-part messages, attachments, HITL responses, and per-turn context:
+Pass the message first and optional per-turn settings second. Use `respond()` for HITL answers:
 
 ```tsx
-await agent.send({ message: "Summarize this session." });
-
-await agent.send({
-  message: [
-    { type: "text", text: "What is in this file?" },
-    {
-      type: "file",
-      data: fileDataUrl, // base64 data URL
-      mediaType: "application/pdf",
-      filename: "report.pdf",
-    },
-  ],
-});
+await agent.send("Summarize this session.");
+
+await agent.send([
+  { type: "text", text: "What is in this file?" },
+  {
+    type: "file",
+    data: fileDataUrl, // base64 data URL
+    mediaType: "application/pdf",
+    filename: "report.pdf",
+  },
+]);
 ```
 
 Assistant text, reasoning, tool calls, and tool results stream into `data` as they arrive, and `status` moves from `ready` to `submitted` to `streaming` and back. Call `stop()` to abort the client's in-flight stream, and `reset()` to clear local state so the next send starts a fresh durable session.
 
 `stop()` is local: turns are resumable across disconnects, so detaching the stream never cancels the work — the turn keeps running and billing on the server. To stop the turn itself, POST the session's [cancel route](../../channels/eve#routes); the turn then settles on the stream as `turn.cancelled` followed by `session.waiting`.
 
-A chat UI with a Stop button should own the `ClientSession` passed to `useEveAgent`, create it with `preserveCompletedSessions: true`, and call `session.cancel({ turnId })` after observing that turn's `turn.started` event. The `turnId` guard makes a late click a harmless no-op instead of cancelling a newer turn. Keep the stream open until the cancellation boundary arrives; do not use `stop()` for this interaction.
+A chat UI with a server-side Cancel button can use the `sessionId` exposed by the
+hook, attach a fixed `ClientSession`, and call `session.cancel({ turnId })` after
+observing that turn's `turn.started` event. The `turnId` guard makes a late click
+a harmless no-op instead of cancelling a newer turn. Keep the stream open until
+the cancellation boundary arrives; do not use `stop()` for this interaction.
 
 After eve confirms an attachment turn with `message.received`, the default reducer projects each
 received attachment as a `file` part on the user message. The part includes `mediaType`, optional
@@ -108,7 +111,7 @@ received attachment as a `file` part on the user message. The part includes `med
 
 ## Human-in-the-loop prompts
 
-Tools opt into approval with `approval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:
+Tools opt into approval with `approval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `respond()`:
 
 ```tsx
 const request = agent.data.messages
@@ -117,9 +120,7 @@ const request = agent.data.messages
   ?.toolMetadata?.eve?.inputRequest;
 
 if (request) {
-  await agent.send({
-    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
-  });
+  await agent.respond([{ requestId: request.requestId, optionId: "approve" }]);
 }
 ```
 
@@ -159,11 +160,10 @@ For fully custom state machines, `authorization.required` and `authorization.com
 
 ## Attach page context per turn
 
-`clientContext` adds ephemeral context for the next model call only. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, so it never dispatches a turn on its own and never lands in durable session history. Pass it directly to `send()`:
+`clientContext` adds ephemeral context for the next model call only. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, so it never dispatches a turn on its own and never lands in durable session history. Pass it in the second argument to `send()` or `respond()`:
 
 ```tsx
-await agent.send({
-  message: "What should I do on this screen?",
+await agent.send("What should I do on this screen?", {
   clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
 });
 ```
@@ -226,11 +226,11 @@ const agent = useEveAgent({ reducer: toolCounter });
 The browser conversation lives durably on the server. Persist both the rendered event log and the `session` cursor to pick it back up after a reload:
 
 ```tsx
-import type { SessionState, MessageStreamEvent } from "eve/client";
+import type { ClientSessionState, MessageStreamEvent } from "eve/client";
 
 type SavedEveChat = {
   events?: readonly MessageStreamEvent[];
-  session?: SessionState;
+  session?: ClientSessionState;
 };
 
 const [saved] = useState<SavedEveChat>(() => {
@@ -253,7 +253,11 @@ const agent = useEveAgent({
 });
 ```
 
-Store the full `session` object (`sessionId`, `continuationToken`, `streamIndex`), not a single field. The session cursor lets eve continue the durable conversation; the event log lets your UI render historical messages without replaying the whole stream. A database-backed chat app should usually persist stream events as they arrive with `onEvent` and then save a final snapshot in `onFinish`.
+Store the full `session` object (`sessionId`, `streamIndex`). The session cursor
+lets eve continue the exact durable conversation; the event log lets your UI
+render historical messages without replaying the whole stream. A database-backed
+chat app should usually persist stream events as they arrive with `onEvent` and
+then save a final snapshot in `onFinish`.
 
 `initialEvents` must be an ordered prefix of the same session's stream, but its endpoint does not have to line up exactly with where the stream resumes. Every event carries a stable [`meta.id`](/docs/concepts/sessions-runs-and-streaming#the-event-envelope), and the store drops any event whose id it has already applied — so a saved log that overlaps the replayed prefix renders once, and `onEvent` only fires for events your UI has not seen.
 

package/docs/guides/frontend/sveltekit.mdx

@@ -56,7 +56,7 @@ With the plugin in `vite.config.ts`, components call [`useEveAgent`](./use-eve-a
     const text = message.trim();
     if (!text || isBusy) return;
     message = "";
-    await agent.send({ message: text });
+    await agent.send(text);
   }
 </script>
 

package/docs/guides/frontend/use-eve-agent-svelte.mdx

@@ -23,16 +23,17 @@ Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:
 
 ## What it returns
 
-| Property  | Type                                        | Description                                                               |
-| --------- | ------------------------------------------- | ------------------------------------------------------------------------- |
-| `data`    | `TData`                                     | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status`  | `UseEveAgentStatus`                         | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
-| `error`   | `Error \| undefined`                        | Last transport-level error.                                               |
-| `events`  | `readonly MessageStreamEvent[]`             | Raw server events for this session.                                       |
-| `session` | `SessionState`                              | Snapshot of session state.                                                |
-| `send`    | `(input: SendTurnPayload) => Promise<void>` | Send text or a full turn (multi-part, attachments, HITL responses).       |
-| `stop`    | `() => void`                                | Abort the client's in-flight stream.                                      |
-| `reset`   | `() => void`                                | Clear state and start a new session.                                      |
+| Property  | Type                                          | Description                                                               |
+| --------- | --------------------------------------------- | ------------------------------------------------------------------------- |
+| `data`    | `TData`                                       | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `UseEveAgentStatus`                           | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `Error \| undefined`                          | Last transport-level error.                                               |
+| `events`  | `readonly MessageStreamEvent[]`               | Raw server events for this session.                                       |
+| `session` | `ClientSessionState \| undefined`             | Fixed session ID and stream cursor.                                       |
+| `send`    | `(message, options?) => Promise<void>`        | Send text or a multi-part message.                                        |
+| `respond` | `(inputResponses, options?) => Promise<void>` | Answer pending HITL input requests.                                       |
+| `stop`    | `() => void`                                  | Abort the client's in-flight stream.                                      |
+| `reset`   | `() => void`                                  | Clear state and start a new session.                                      |
 
 These state fields are reactive getters, so read them straight from templates, `$derived`, or `$effect`. They are not stores, so don't prefix them with `$`.
 
@@ -49,7 +50,7 @@ These state fields are reactive getters, so read them straight from templates, `
     const text = message.trim();
     if (!text) return;
     message = "";
-    await agent.send({ message: text });
+    await agent.send(text);
   }
 </script>
 
@@ -68,17 +69,15 @@ When a turn is more than plain text, reach for `send()`. Attachments follow the
 const bytes = new Uint8Array(await file.arrayBuffer());
 const base64 = btoa(String.fromCodePoint(...bytes));
 
-await agent.send({
-  message: [
-    { type: "text", text: "Describe this image." },
-    { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
-  ],
-});
+await agent.send([
+  { type: "text", text: "Describe this image." },
+  { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
+]);
 ```
 
 ## Human-in-the-loop prompts
 
-A tool opts into approval with `approval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `agent.send({ inputResponses })`:
+A tool opts into approval with `approval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `agent.respond(inputResponses)`:
 
 ```ts
 import type { EveDynamicToolPart, EveMessagePart } from "eve/svelte";
@@ -93,9 +92,7 @@ const request = agent.data.messages
   .find((value) => value !== undefined);
 
 if (request) {
-  await agent.send({
-    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
-  });
+  await agent.respond([{ requestId: request.requestId, optionId: "approve" }]);
 }
 ```
 
@@ -133,8 +130,7 @@ const agent = useEveAgent({
 `clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it to `send()`:
 
 ```ts
-await agent.send({
-  message: "What should I do on this screen?",
+await agent.send("What should I do on this screen?", {
   clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
 });
 ```