eve 0.30.7 → 0.31.0

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

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.
@@ -99,10 +103,11 @@ The most common UI events are:
 | `reasoning.appended` | Render reasoning deltas when the model provides them.                          |
 | `message.appended`   | Render assistant text deltas.                                                  |
 | `actions.requested`  | Show tool calls as the model requests them, before execution.                  |
+| `action.partial`     | Update a generator tool's provisional output snapshot.                         |
 | `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.                                                  |
 
@@ -128,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 },
 });
 
@@ -145,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,
 });
 
@@ -168,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;
 }
 ```
@@ -192,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.
@@ -212,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
 
@@ -228,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>