eve 0.27.13 → 0.28.0

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

@@ -14,6 +14,12 @@ Two handles do two jobs, and mixing them up is the most common mistake. One hand
 
 A session has one active continuation at a time: each follow-up uses the current `continuationToken`, and a stale one is rejected.
 
+Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
+`agent.ts`, or set it to `false` to disable the deadline. At expiration, eve
+lets an active turn settle, emits `session.completed`, and releases the
+continuation so the next qualifying channel message starts fresh. Stored
+session data is not deleted. See [Agent config](../agent-config#runtime-limits).
+
 React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
 
 ## Start a session
@@ -73,6 +79,59 @@ A delegated subagent publishes progress on its own child-session stream. The par
 
 `step.failed` and `turn.failed` carry `{ code, message, details? }` for the failed fragment or turn, and `session.failed` is the terminal session-level variant. `turn.cancelled` is not a failure: the cancelled turn ends without any failure event, `session.waiting` follows, and the session accepts the next message normally — whatever the turn streamed before cancellation stays on the stream, while durable history keeps only what had already settled. When a turn requested an output schema, the finalized payload lands on `result.completed` as `data.result` before the turn boundary. `authorization.required` carries the sign-in challenge (`data.authorization` may include `url`, `userCode`, `expiresAt`, `instructions`), and `authorization.completed` carries `data.outcome` (`"authorized" | "declined" | "failed" | "timed-out"`).
 
+## The event envelope
+
+Alongside `type` and `data`, every event carries a `meta` envelope:
+
+```json
+{
+  "type": "message.completed",
+  "data": {
+    "message": "Sunny and 72°F.",
+    "finishReason": "stop",
+    "sequence": 0,
+    "stepIndex": 0,
+    "turnId": "turn_0"
+  },
+  "meta": { "id": "evt_01KYJBZA88B4M9XN3RTC5FDGHJ", "at": "2026-07-27T18:04:11.912Z" }
+}
+```
+
+- **`meta.id`** uniquely identifies the event. It is an `evt_`-prefixed [ULID](https://github.com/ulid/spec): a millisecond timestamp followed by random bits, so ids are broadly time-ordered.
+- **`meta.at`** is the ISO-8601 time the event was emitted.
+
+`meta.id` is stable. eve mints it once, when the event is written to the durable stream, and stores it with the event. Reconnecting from a cursor, rewinding to `startIndex=0`, or replaying a finished session all return the same id for the same event.
+
+`meta.at` has always been there; `meta.id` arrived in stream version 20. Events written by an earlier version are stored with the envelope but no id inside it, so rewinding into the part of a session that ran before you upgraded yields events whose `meta.id` is absent, even though the type says it is always a string. eve passes those events through rather than dropping them, and they cannot be deduplicated. The exposure ends when the sessions that predate your upgrade do.
+
+That makes it the key for ingesting a stream into a database without duplicating rows when you re-read it:
+
+```sql
+insert into agent_events (id, session_id, type, data, emitted_at)
+values ($1, $2, $3, $4, $5)
+on conflict (id) do nothing;
+```
+
+Because ids lead with a timestamp, a `primary key (id)` stays roughly append-ordered and keeps inserts clustered.
+
+**What the id covers.** Reconnecting is not the only way the same event reaches you twice. Keying on `meta.id` is what makes ingestion correct in all of these:
+
+- Reconnecting mid-turn and overlapping events you already handled.
+- Rewinding with `startIndex=0`, or reading back from the tail with a negative `startIndex`.
+- Restoring a saved event log that overlaps the prefix the live stream replays.
+
+**What it does not cover: a retried step re-emits under new ids.** eve runs each durable step up to four times. If a step is interrupted partway — a crash, a timeout, a model error it retries through — whatever it already wrote stays on the stream, and the new attempt emits its own events with their own ids. Both attempts carry the same `turnId`, `stepIndex`, and `sequence`, because the retry restores that state from the step's input, but they are distinct events and no field records which attempt finished.
+
+Replaying a _completed_ step is a different thing and emits nothing at all: eve serves the recorded result from its journal without re-running the body. Crash recovery, redeploys, and resuming a parked turn therefore add nothing to the stream. Only an interrupted step re-runs.
+
+Three more things to know:
+
+- **Ids are time-ordered, not a total order.** The turn steps of one session can run in different processes, each generating ids from its own clock and its own random bits. Two events emitted in the same millisecond by different steps may sort either way, and clock skew between machines can invert neighbours. Record your own ingestion sequence, or read the stream in order and store the index, when you need an exact ordering to page against — do not use `where id > $cursor` as a lossless cursor. The stream itself is authoritative: `startIndex` is an absolute event count.
+- **Ids identify events, not intent.** Two events with identical payloads — the `step.failed` → `turn.failed` → `session.failed` cascade, or two identical text deltas in one step — are distinct events with distinct ids. Deduplicate on `meta.id` only; matching on content would drop real data.
+- **A subagent's event is re-emitted, not shared.** When a parent forwards a child's event onto its own stream, the parent's copy is a separate event with its own id. Correlate the two streams through `subagent.called.data.childSessionId`.
+
+Authored [hooks](../guides/hooks) receive the same envelope, but observe each event as it is emitted rather than as it is read — so a hook sees a retry as new events, and `meta.id` is a key for a stored row rather than a retry guard. Two things a hook does not have to defend against: a turn that parks for human input resumes without re-emitting anything it already sent, and a retried turn dispatch cannot double-stream a turn, because only one turn run can claim a session's turn inbox.
+
 ## 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`:
@@ -112,6 +171,8 @@ Custom channel routes request the same cancellation without knowing the session
 
 The stream is durable. Every event is recorded before a step completes, so consumers can reconnect from their cursor when an HTTP connection ends. A nonnegative `startIndex` is an absolute event count: use it to pick up where you dropped off or pass `0` to rewind to the start.
 
+If a reconnect overlaps events you already handled, [`meta.id`](#the-event-envelope) identifies the duplicates: it is unchanged across reconnects and rewinds, so a consumer keyed on it can replay safely.
+
 ```bash
 curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<count>"
 ```

package/docs/guides/client/streaming.mdx

@@ -60,13 +60,17 @@ for await (const event of response) {
 
 ## Handle event types
 
-Import event types from `eve/client` when you want exhaustiveness or helpers:
+Import event types from `eve/client` when you want exhaustiveness or helpers. Events read from a stream are `MessageStreamEvent`: the same union, with the `meta` envelope guaranteed present.
+
+`HandleMessageStreamEvent` remains available as a deprecated alias, so existing type imports continue to compile.
 
 ```ts
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
 import { isCurrentTurnBoundaryEvent } from "eve/client";
 
-function handleEvent(event: HandleMessageStreamEvent) {
+function handleEvent(event: MessageStreamEvent) {
+  console.log(event.meta.id, event.meta.at);
+
   if (isCurrentTurnBoundaryEvent(event)) {
     console.log("turn settled:", event.type);
   }
@@ -105,6 +109,8 @@ If you support refresh while an authorization prompt is pending, keep the sessio
 
 HTTP connections can end before a run does. The client reconnects from the number of events already consumed, so long turns continue without replaying events. It stops at a turn boundary, when aborted, or when the stream can no longer make progress.
 
+If your consumer persists events, key on `event.meta.id`. It is stable across reconnects and rewinds, so an overlapping replay is safe to ingest twice. See [the event envelope](../../concepts/sessions-runs-and-streaming#the-event-envelope).
+
 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

package/docs/guides/frontend/overview.mdx

@@ -226,10 +226,10 @@ 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 { HandleMessageStreamEvent, SessionState } from "eve/client";
+import type { SessionState, MessageStreamEvent } from "eve/client";
 
 type SavedEveChat = {
-  events?: readonly HandleMessageStreamEvent[];
+  events?: readonly MessageStreamEvent[];
   session?: SessionState;
 };
 
@@ -255,6 +255,8 @@ 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`.
 
+`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.
+
 For multiple chat threads, keep one saved event log and session cursor per thread. `agent`, `host`, `reducer`, `session`, `initialEvents`, `initialSession`, `auth`, `headers`, and `optimistic` are read when the hook creates its store, so remount the chat component when switching threads, for example with `key={chat.id}`.
 
 If the user can refresh or navigate immediately after pressing send, create your app-level chat row and store the pending user message before calling `send()`. After the request starts, persist the session state as soon as it contains a `sessionId`, then reconnect an interrupted in-flight turn with `session.stream({ startIndex: savedEvents.length })` from the lower-level client.

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

@@ -28,7 +28,7 @@ Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:
 | `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 HandleMessageStreamEvent[]`       | Raw server events for this session.                                       |
+| `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.                                      |

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

@@ -25,16 +25,16 @@ const { data } = useEveAgent();
 
 ## What it returns
 
-| Property  | Type                                               | Description                                                               |
-| --------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
-| `data`    | `ComputedRef<TData>`                               | Projected state. With the default reducer, `EveMessageData` (`messages`). |
-| `status`  | `ComputedRef<UseEveAgentStatus>`                   | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
-| `error`   | `ComputedRef<Error \| undefined>`                  | Last transport-level error.                                               |
-| `events`  | `ComputedRef<readonly HandleMessageStreamEvent[]>` | Raw server events for this session.                                       |
-| `session` | `ComputedRef<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`    | `ComputedRef<TData>`                         | Projected state. With the default reducer, `EveMessageData` (`messages`). |
+| `status`  | `ComputedRef<UseEveAgentStatus>`             | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
+| `error`   | `ComputedRef<Error \| undefined>`            | Last transport-level error.                                               |
+| `events`  | `ComputedRef<readonly MessageStreamEvent[]>` | Raw server events for this session.                                       |
+| `session` | `ComputedRef<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.                                      |
 
 The first five are `ComputedRef`s; the rest are methods. Destructure whatever you need, since refs keep their reactivity through destructuring. Read them with `.value` in `<script>`, and unwrapped in `<template>`.
 

package/docs/guides/hooks.md

@@ -80,15 +80,53 @@ import { search } from "@acme/crm/tools";
 const crmSearch = toolResultFrom(event.data.result, search); // typed; matches crm__search
 ```
 
+### Persist events to your own database
+
+Every event carries a `meta` envelope with `meta.id`, a unique, sortable identifier for that event. It makes a natural primary key for an events table:
+
+```ts title="agent/hooks/persist.ts"
+import { defineHook } from "eve/hooks";
+
+export default defineHook({
+  events: {
+    async "*"(event, ctx) {
+      await db.query(
+        `insert into agent_events (id, session_id, type, data, emitted_at)
+         values ($1, $2, $3, $4, $5)
+         on conflict (id) do nothing`,
+        [
+          event.meta.id,
+          ctx.session.id,
+          event.type,
+          "data" in event ? event.data : null,
+          event.meta.at,
+        ],
+      );
+    },
+  },
+});
+```
+
+`meta.id` is stable for the life of the persisted event, so a consumer that re-reads the stream can ingest the same event twice safely. It is not a retry guard for the hook itself: if a step is interrupted and re-runs, the turn re-emits its events as _new_ events with new ids, and your hook runs again for each one.
+
+What to key on instead depends on what you are protecting:
+
+- **A side effect that must happen once per turn or step** — a charge, an email, a ticket — keys well on the coordinates in `event.data` (`turnId`, `stepIndex`, `sequence`). A retry restores those from the step's input, so the second attempt computes the same key and your gate holds.
+- **Stored content should not key on those coordinates.** The retry re-invokes the model, so one coordinate can carry different text on each attempt. `on conflict (turn_id, step_index, sequence) do nothing` would keep the abandoned attempt and drop the one that finished. Key on `meta.id`, and accept that an interrupted turn leaves both attempts in the table.
+
+Behind that split is an asymmetry worth knowing: durable history keeps only the attempt that completed, while the event stream keeps every attempt, and no field marks which is which. Hooks are at-least-once, and no key collapses a retry.
+
+See [the event envelope](../concepts/sessions-runs-and-streaming#the-event-envelope) for the full contract.
+
 ## Execution order
 
 When a stream event fires, three things happen in order:
 
-1. Emit. The channel adapter handler runs, then the event is written to the durable stream.
+1. Emit. The channel adapter handler runs, the event is stamped with its `meta` envelope, then it is written to the durable stream.
 2. Hooks. Stream-event hooks fire (typed handlers first, then the `*` wildcard). Return values are ignored.
 3. Dynamic tool resolvers. Resolvers subscribed to the event type run and update the tool set.
 
-Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent.
+Hooks always run after the event is durably recorded, so if a hook throws, the stream stays consistent. The persisted event and every hook observe the same `meta.id`.
 
 ## What happens when a hook throws
 

package/docs/guides/instrumentation.md

@@ -15,6 +15,10 @@ The directory is an immutable OTLP/JSON spool and remains available after `eve d
 
 Use `eve trace ls` to list captured traces and `eve trace <trace>` to inspect a session's span tree.
 
+When a model call is served by Vercel AI Gateway, its `agent.step` span also carries the cost the gateway reported: `gen_ai.usage.cost` (raw inference, USD), `gen_ai.usage.gateway_cost` (with the gateway surcharge), `gen_ai.usage.input_cost` / `gen_ai.usage.output_cost` (the split), and `gen_ai.generation.id` for reconciliation with the gateway dashboard. These attributes only exist for gateway-served calls — other providers emit nothing. Cost per turn is the sum across the turn's step spans.
+
+Model and step spans also split token usage when the provider reports details: `gen_ai.usage.cache_read.input_tokens` and `gen_ai.usage.cache_creation.input_tokens` (named for the [OTel GenAI semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)) alongside the `agent.usage.input_tokens` / `agent.usage.output_tokens` totals — cached tokens price differently, so the split makes cost attribution exact. Providers without detailed usage emit only the totals.
+
 The local writer is an internal development default, not a second provider layered over authored instrumentation. When `instrumentation.ts` exists, its setup retains control and the zero-config writer is not installed.
 
 ### Local trace retention

package/docs/tools/human-in-the-loop.md

@@ -102,6 +102,11 @@ Approvals and questions share one protocol:
 3. The turn parks at `session.waiting`, durably, for as long as it takes.
 4. The client answers with `inputResponses` (structured, keyed by `requestId`) or a normal follow-up `message`. A follow-up whose text matches an option ID, option label, or numeric option index resolves automatically, including approval options such as `approve` and `deny`.
 
+Each request includes a `kind` discriminator: `tool-approval`, `question`, or
+`session-limit`. Clients should use `kind` to choose behavior and presentation;
+`toolName` and `requestId` identify the action and request but do not encode its
+semantics.
+
 The run picks back up exactly where it parked. Because the pause is durable, nothing is held in memory while it waits — the process can restart and the parked turn survives.
 
 For approval requests, unrelated follow-up text does not deny the tool call. eve keeps the approval pending and holds that text until the approval is answered, then replays it as the next message in the session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.27.13",
+  "version": "0.28.0",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [