eve 0.27.12 → 0.28.0

package/dist/src/shared/dynamic-tool-definition.d.ts

@@ -3,13 +3,13 @@ import type { PublicToolInputSchema, PublicToolOutputSchema, ToolModelOutput } f
 import type { Approval } from "#public/definitions/approval.js";
 import type { ToolContext } from "#public/definitions/tool.js";
 import type { SessionAuth } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
 /**
  * Stream event types allowed for dynamic tool resolvers. Dispatch
  * supports any event; this extract restricts the public surface until
  * more events are validated.
  */
-export type DynamicToolEventName = Extract<HandleMessageStreamEvent["type"], "session.started" | "turn.started" | "step.started">;
+export type DynamicToolEventName = Extract<UnstampedMessageStreamEvent["type"], "session.started" | "turn.started" | "step.started">;
 export declare const ALLOWED_DYNAMIC_TOOL_EVENTS: ReadonlySet<string>;
 /**
  * Instructions and skills are restricted to session/turn boundaries.

package/dist/src/shared/ulid.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ULID-compatible generation, vendored rather than taken from npm: the
+ * `ulid` package's Node build hard-imports `node:crypto`, and this module is
+ * bundled into browser clients, the Nitro server, and the workflow step
+ * sandbox. `ulid.test.ts` pins the encoding against the reference
+ * implementation's golden vectors.
+ */
+/** Character count of a ULID: a 10-char timestamp then a 16-char random tail. */
+export declare const ULID_LENGTH: number;
+/** Mints one ULID. See {@link createUlidFactory}. */
+export type UlidFactory = () => string;
+/**
+ * Creates an independent ULID generator with its own monotonic state.
+ *
+ * Prefer {@link createUlid} unless a caller needs a sequence that unrelated
+ * code cannot perturb. Ids sort in the order one generator produced them:
+ * those minted within a millisecond increment the random tail, and a
+ * backwards clock pins to the last millisecond observed.
+ */
+export declare function createUlidFactory(): UlidFactory;
+/**
+ * Mints a ULID from the process-wide generator: a 48-bit millisecond
+ * timestamp then 80 bits of randomness, in Crockford base32.
+ *
+ * Ids lead with their timestamp, so they are broadly time-ordered. Ordering
+ * holds within one process only — separate processes have independent clocks
+ * and random tails — so a ULID is not a lossless pagination cursor.
+ *
+ * Throws when the clock is outside the 48-bit timestamp range or Web Crypto
+ * is unavailable rather than weakening the randomness.
+ */
+export declare const createUlid: UlidFactory;
+/**
+ * Returns true when `value` is shaped like a ULID: {@link ULID_LENGTH}
+ * characters drawn from the Crockford base32 alphabet.
+ *
+ * Shape-only — this does not prove the value was minted here.
+ */
+export declare function isUlid(value: string): boolean;

package/dist/src/shared/ulid.js

@@ -0,0 +1 @@
+const ENCODING=`0123456789ABCDEFGHJKMNPQRSTVWXYZ`,TIME_MAX=2**48-1,ULID_LENGTH=26;function createUlidFactory(){let e=-1,n=new Uint8Array(10);return function(){let r=Date.now();if(!Number.isInteger(r)||r<0||r>TIME_MAX)throw Error(`Cannot mint a ULID: timestamp must be an integer from 0 to ${TIME_MAX}.`);if(r>e)e=r,randomFill(n);else if(!incrementRandom(n)){if(e===TIME_MAX)throw Error(`Cannot mint a ULID: random component overflowed at the maximum timestamp.`);e+=1,randomFill(n)}return`${encodeTime(e)}${encodeRandom(n)}`}}const createUlid=createUlidFactory();function isUlid(t){if(t.length!==26||ENCODING.indexOf(t[0]??``)>7)return!1;for(let n of t)if(!ENCODING.includes(n))return!1;return!0}function randomFill(e){let t=globalThis.crypto;if(typeof t?.getRandomValues!=`function`)throw Error(`Cannot mint a ULID: globalThis.crypto.getRandomValues is unavailable.`);t.getRandomValues(e)}function encodeTime(t){let n=t,r=``;for(let t=0;t<10;t+=1)r=ENCODING[n%32]+r,n=Math.floor(n/32);return r}function encodeRandom(t){let n=0,r=0,i=``;for(let a of t){for(n=n<<8|a,r+=8;r>=5;)r-=5,i+=ENCODING[n>>>r&31];n&=(1<<r)-1}return i}function incrementRandom(e){for(let t=e.length-1;t>=0;--t){let n=e[t]??0;if(n<255)return e[t]=n+1,e.fill(0,t+1),!0}return!1}export{ULID_LENGTH,createUlid,createUlidFactory,isUlid};

package/dist/src/svelte/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CsSQOKnp.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CZkX_ZTT.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/svelte/use-eve-agent.d.ts

@@ -3,7 +3,7 @@ import { type EveMessageData } from "#client/message-reducer.js";
 import type { EveAgentReducer } from "#client/reducer.js";
 import type { ClientSession } from "#client/session.js";
 import type { ClientAuth, HeadersValue, SendTurnPayload, SessionState } from "#client/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
 export type { PrepareSend };
 /**
  * Session lifecycle phase: `"ready"` (idle), `"submitted"` (request sent,
@@ -30,7 +30,7 @@ export interface UseEveAgentReturn<TData> {
     /** Last transport-level error, or `undefined` when healthy. */
     readonly error: Error | undefined;
     /** Raw server events received during this session (authoritative stream). */
-    readonly events: readonly HandleMessageStreamEvent[];
+    readonly events: readonly MessageStreamEvent[];
     /** Clear all state and start a new session. */
     readonly reset: () => void;
     /** Send a turn with full structured input (message, attachments, input responses). */
@@ -76,8 +76,8 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
      * @default ""
      */
     readonly host?: string;
-    /** Seed events for resuming a prior conversation. */
-    readonly initialEvents?: readonly HandleMessageStreamEvent[];
+    /** Ordered prefix of the session stream used to rehydrate projected state. */
+    readonly initialEvents?: readonly MessageStreamEvent[];
     /** Seed session identity and stream cursor for resuming a prior conversation. */
     readonly initialSession?: SessionState;
     /**

package/dist/src/svelte/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-CsSQOKnp.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-CZkX_ZTT.js";
 
 export { useEveAgent };

package/dist/src/vue/index.js

@@ -1,3 +1,3 @@
-import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-CWYe-vqE.js";
+import { n as defaultMessageReducer, t as useEveAgent } from "../chunks/use-eve-agent-hdPX68_i.js";
 
 export { defaultMessageReducer, useEveAgent };

package/dist/src/vue/use-eve-agent.d.ts

@@ -3,7 +3,7 @@ import { type EveAgentStoreCallbacks, type EveAgentStoreSnapshot, type EveAgentS
 import type { EveAgentReducer } from "#client/reducer.js";
 import type { ClientSession } from "#client/session.js";
 import { type EveMessageData } from "#client/message-reducer.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
 import type { ClientAuth, HeadersValue, SendTurnPayload, SessionState } from "#client/types.js";
 export type { PrepareSend };
 /**
@@ -29,7 +29,7 @@ export interface UseEveAgentReturn<TData> {
     /** Last transport-level error, or `undefined` when healthy. */
     readonly error: ComputedRef<Error | undefined>;
     /** Raw server events from this session (authoritative stream). */
-    readonly events: ComputedRef<readonly HandleMessageStreamEvent[]>;
+    readonly events: ComputedRef<readonly MessageStreamEvent[]>;
     /** Clear all state and start a new session. */
     readonly reset: () => void;
     /** Send a turn with full structured input (message, attachments, input responses). */
@@ -75,8 +75,8 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
      * @default ""
      */
     readonly host?: string;
-    /** Prior stream events to rehydrate the projected state from on mount. */
-    readonly initialEvents?: readonly HandleMessageStreamEvent[];
+    /** Ordered prefix of the session stream used to rehydrate projected state. */
+    readonly initialEvents?: readonly MessageStreamEvent[];
     /** Prior session cursor to resume from on mount. */
     readonly initialSession?: SessionState;
     /**

package/dist/src/vue/use-eve-agent.js

@@ -1,3 +1,3 @@
-import { t as useEveAgent } from "../chunks/use-eve-agent-CWYe-vqE.js";
+import { t as useEveAgent } from "../chunks/use-eve-agent-hdPX68_i.js";
 
 export { useEveAgent };

package/docs/agent-config.md

@@ -131,10 +131,18 @@ export default defineAgent({
   limits: {
     maxInputTokensPerSession: 200_000,
     maxOutputTokensPerSession: 20_000,
+    sessionTimeoutMs: 7 * 24 * 60 * 60 * 1_000,
   },
 });
 ```
 
+`sessionTimeoutMs` sets an absolute lifetime for every session, including
+delegated sessions. It defaults to 30 days, starts at creation, and survives
+restarts and redeployments. At the deadline, eve lets an active turn settle,
+then emits `session.completed` and releases the continuation; the next
+qualifying channel message starts fresh. Set it to `false` to disable the
+timeout. Expiration does not delete stored session data.
+
 Input and output budgets are checked independently. The model call that crosses
 either limit is allowed to finish because providers only report exact token
 usage after a call completes. Before the next model call, eve pauses the
@@ -147,12 +155,14 @@ still over budget, the next message re-raises the prompt. Declining a
 delegated child's prompt cancels the root turn, which cascades to the whole
 delegation tree — the delegating parent never receives an error result it
 could retry against a fresh quota share. A reply that answers neither option
-re-raises the prompt; the reply stays in history and is processed once the
-budget is granted.
+is queued while the existing prompt stays pending; eve does not raise another
+copy. The reply is processed once the budget is granted.
 
 Sessions that cannot reach a human — task-mode runs such as schedules and
 subagents without input proxying — skip the prompt and fail the next model
-call with `SESSION_TOKEN_LIMIT_REACHED`.
+call with `SESSION_TOKEN_LIMIT_REACHED`. A delegated task with no inherited
+quota also fails instead of raising a continuation prompt that could only
+grant another zero-token window.
 
 When `maxInputTokensPerSession` is omitted, root sessions apply a default
 input budget of `40_000_000` provider-reported input tokens.
@@ -161,11 +171,13 @@ to `false` uncaps that axis — the session never stops on it.
 
 Delegated subagent sessions have no fixed default. Each child receives a
 share of the delegating parent's remaining quota at dispatch time — the
-remainder (limit minus accumulated usage) split evenly across the batch's
-local subagent calls — and a completed child's usage counts against the
-parent's quota, so a delegation tree can never outspend the budget configured
-at its root. An authored child limit applies only when it is tighter than the
-parent's grant; an uncapped parent delegates uncapped children.
+remainder in the current budget window split evenly across the batch's local
+subagent calls — and a completed child's usage counts against the parent's
+quota, so a delegation tree can never outspend the budget configured at its
+root. Approving a continuation opens a fresh parent window for later child
+grants without erasing lifetime usage. An authored child limit applies only
+when it is tighter than the parent's grant; an uncapped parent delegates
+uncapped children.
 
 ## Workflow world
 
@@ -208,14 +220,14 @@ installed package must stay external in hosted output, list it in
 
 `defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
 
-| Field          | Type                                    | Default          | Description                                                                                                                                                                                                                                                                |
-| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                                                                              |
-| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                                                                                     |
-| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. `maxInputTokensPerSession` defaults to `40_000_000` for root sessions, and delegated subagent sessions inherit the parent's remaining quota; `maxOutputTokensPerSession` is unset unless configured; `false` uncaps a session token limit. |
-| `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent.                                                              |
-| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                                                                                 |
-| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.                                                                   |
+| Field          | Type                                    | Default          | Description                                                                                                                                                                                                   |
+| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reasoning`    | `AgentReasoningDefinition`              | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.                                                                                                                                 |
+| `modelOptions` | `AgentModelOptionsDefinition`           | none             | Provider option overrides forwarded to the model call.                                                                                                                                                        |
+| `limits`       | `AgentLimitsDefinition`                 | field-specific   | Framework-owned runtime limits. Sessions complete after 30 days by default; token-limit defaults and inheritance are described above. Set a limit to `false` to disable it.                                   |
+| `experimental` | `{ workflow?: { world?: string } }`     | unset            | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
+| `outputSchema` | Standard Schema or a JSON Schema object | none             | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.                                    |
+| `build`        | `{ externalDependencies?: string[] }`   | none             | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.      |
 
 `externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
 

package/docs/channels/linear.mdx

@@ -82,6 +82,10 @@ Turn start posts an ephemeral `thought`, tool calls post ephemeral `action` acti
 
 Human-in-the-loop (HITL) input requests render 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`.
 
+### Connection authorization
+
+When a user-scoped connection needs authorization, the default channel posts Linear's native `auth` elicitation with the provider's sign-in URL, targeted to the Linear user who started the session. URL-less device flows render their instructions and user code as a plain elicitation. After authorization finishes, the channel posts a thought with the outcome; successful authorization indicates that the parked turn is resuming.
+
 ### Proactive sessions
 
 Start a session without an inbound webhook with `receive(linear, { target })`. See [Proactive sessions](#proactive-sessions) below for the target shape and examples.

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

@@ -56,7 +56,7 @@ Provider keys, tool secrets, and MCP, OpenAPI, and connection credentials stay i
 
 ## Resuming after a crash
 
-Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval.
+Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval. Whatever that step already wrote to the session stream stays there, and the re-run emits its events again under new ids, so a stream consumer sees both attempts — see [the event envelope](./sessions-runs-and-streaming#the-event-envelope).
 
 There's nothing to configure. eve owns the workflow lifecycle, and sessions are durable by default.
 

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/extensions.md

@@ -3,7 +3,9 @@ title: "Extensions"
 description: "Package reusable eve capabilities and mount them from npm or a monorepo workspace."
 ---
 
-Extensions package eve tools, connections, skills, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a registry or kept private inside a monorepo workspace.
+Extensions package eve tools, connections, skills, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.
+
+Ready-made extensions can also be distributed through an eve integration registry. See [Install Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
 
 This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
 

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/install-integrations.mdx

@@ -18,6 +18,8 @@ eve add instrumentation/braintrust
 
 Extensions may create a mount under `agent/extensions/`. Connections write their initial definition under `agent/connections/` and install `@vercel/connect` when required. Instrumentation providers write `agent/instrumentation.ts`; because an agent has one instrumentation file, compose multiple exporters there by hand. Configure generated files and required environment variables before running your agent.
 
+When an official item has an interactive setup flow, eve asks whether to run it after installation. Run the printed `eve add <item> --skip-install` command to resume a skipped or cancelled setup later.
+
 ## Find an integration
 
 Browse the [Integrations directory](/integrations) to see the official integrations available from the eve registry.
@@ -44,7 +46,7 @@ eve registry view extension/agent-browser
 
 ## Add a third-party source
 
-Give a registry a namespace and an integration URL template:
+Use the integration URL template provided by the registry publisher and give the source a namespace:
 
 ```bash
 eve registry add @acme=https://registry.acme.com/r/{name}.json
@@ -71,6 +73,79 @@ Install a known integration URL directly when you do not need a namespace:
 eve add https://registry.acme.com/r/analytics.json
 ```
 
+## Contribute an official integration
+
+Community contributions to the official registry are welcome. Open an issue and get maintainer agreement before submitting a pull request, then follow the [registry contribution guide](https://github.com/vercel/eve/blob/main/CONTRIBUTING.md#adding-an-integration-to-the-registry) for the required source files, metadata, validation, and extension requirements.
+
+## Host your own registry
+
+Hosting your own registry is the publishing side of the [third-party source workflow](#add-a-third-party-source). Once it is deployed, other eve projects can give it a namespace and pull integrations from it.
+
+An eve registry is a standard [shadcn registry](https://ui.shadcn.com/docs/registry), so it can be hosted by any service that serves JSON over HTTP. It needs two kinds of endpoint:
+
+- A catalog such as `https://registry.acme.com/r/registry.json` for `eve registry list` and `eve registry search`
+- One JSON document per integration, such as `https://registry.acme.com/r/analytics.json`, for `eve registry view` and `eve add`
+
+Start with a source file for the integration and a `registry.json` that describes where to install it:
+
+```text
+registry.json
+registry/
+└── analytics.ts
+```
+
+```json title="registry.json"
+{
+  "$schema": "https://ui.shadcn.com/schema/registry.json",
+  "name": "acme",
+  "homepage": "https://registry.acme.com",
+  "items": [
+    {
+      "name": "analytics",
+      "type": "registry:item",
+      "title": "Acme Analytics",
+      "description": "Add Acme analytics tools to an eve agent.",
+      "dependencies": ["@acme/eve-analytics"],
+      "envVars": {
+        "ACME_API_KEY": ""
+      },
+      "files": [
+        {
+          "path": "registry/analytics.ts",
+          "type": "registry:file",
+          "target": "agent/extensions/analytics.ts"
+        }
+      ]
+    }
+  ]
+}
+```
+
+`files[].path` is relative to `registry.json`. `files[].target` is relative to the root of the eve project that installs the item. Use `registry:item` with explicit `registry:file` targets for eve integrations so installation does not depend on a UI framework or shadcn project aliases.
+
+Validate the source registry, then build its static JSON:
+
+```bash
+pnpm dlx shadcn@latest registry validate
+pnpm dlx shadcn@latest build
+```
+
+By default, the build writes the catalog to `public/r/registry.json` and each item to `public/r/<name>.json`. Deploy the `public` directory to a static host, or use the shadcn registry APIs to serve the same payloads from dynamic routes.
+
+Before sharing the registry, test its deployed catalog and item endpoints from an eve project:
+
+```bash
+eve registry list --registry https://registry.acme.com/r/registry.json
+eve registry view https://registry.acme.com/r/analytics.json
+```
+
+Share the item URL template with consumers. From another eve project, they can add the hosted registry as a third-party source and pull the integration through its namespace:
+
+```bash
+eve registry add @acme=https://registry.acme.com/r/{name}.json
+eve add @acme/analytics
+```
+
 ## Configure generated files
 
 Integrations add project files. Read the generated mount before you run the agent, then add the configuration the extension requires.