Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): stamp every stream event with a stable id (#1239)

Andrew Barba7ff4f7797a43
diff --git a/.changeset/stable-stream-event-ids.md b/.changeset/stable-stream-event-ids.md
new file mode 100644
index 000000000..6c40ce97d
--- /dev/null
+++ b/.changeset/stable-stream-event-ids.md
@@ -0,0 +1,7 @@
+---
+"eve": minor
+---
+
+Every session stream event now carries a stable, `evt_`-prefixed ULID in `meta.id`, and stream consumers use it to drop re-delivery without collapsing distinct events. Retried steps re-emit under new ids, while reconnects, rewinds, and saved-log overlap preserve the original id.
+
+**Breaking:** `MessageStreamEvent` is now the canonical public type for events read from a stream, with `meta.id` and `meta.at` required. `HandleMessageStreamEvent` remains as a deprecated alias, so existing imports continue to compile; code that constructs unstamped events under that type must add the envelope. Client, channel, hook, frontend, and eval APIs carry `MessageStreamEvent` end to end, so consumers can read `meta.id` without guards. Events persisted by an earlier version carry `meta.at` but no `meta.id`, so rewinding into a session that started before this release yields events whose id is absent despite the type. eve passes those through rather than dropping them, and they cannot be deduplicated; the exposure ends when those sessions do.
diff --git a/apps/docs/registry/channel/web/app/_components/agent-chat.tsx b/apps/docs/registry/channel/web/app/_components/agent-chat.tsx
index 11aff0c09..c13a477f7 100644
--- a/apps/docs/registry/channel/web/app/_components/agent-chat.tsx
+++ b/apps/docs/registry/channel/web/app/_components/agent-chat.tsx
@@ -1,7 +1,7 @@
"use client";
import type { UserContent } from "ai";
-import { Client, type HandleMessageStreamEvent } from "eve/client";
+import { Client, type MessageStreamEvent } from "eve/client";
import { useEveAgent } from "eve/react";
import { AlertCircleIcon } from "lucide-react";
import { useCallback, useRef, useState } from "react";
@@ -63,7 +63,7 @@ export function AgentChat() {
);
const handleEvent = useCallback(
- (event: HandleMessageStreamEvent) => {
+ (event: MessageStreamEvent) => {
if (event.type !== "turn.started") {
return;
}
diff --git a/apps/frameworks/next/app/_chat/trace-reducer.ts b/apps/frameworks/next/app/_chat/trace-reducer.ts
index 06353ab66..1ccdc4d22 100644
--- a/apps/frameworks/next/app/_chat/trace-reducer.ts
+++ b/apps/frameworks/next/app/_chat/trace-reducer.ts
@@ -1,11 +1,11 @@
import type { EveAgentReducer, EveAgentReducerEvent } from "eve/react";
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
import { buildTraceTurnsFromTranscript } from "./trace";
import type { TraceStep, TraceTurn, TranscriptStreamEvent } from "./types";
export interface TraceProjection {
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly turns: readonly TraceTurn[];
}
@@ -70,9 +70,7 @@ function reduceTraceProjection(
}
}
-function buildTraceTurnsFromEvents(
- events: readonly HandleMessageStreamEvent[],
-): readonly TraceTurn[] {
+function buildTraceTurnsFromEvents(events: readonly MessageStreamEvent[]): readonly TraceTurn[] {
return buildTraceTurnsFromTranscript(events as readonly TranscriptStreamEvent[]);
}
diff --git a/docs/concepts/execution-model-and-durability.mdx b/docs/concepts/execution-model-and-durability.mdx
index 33fe0b55f..7b2e28f8b 100644
--- a/docs/concepts/execution-model-and-durability.mdx
+++ b/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.
diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.md
index 6e2a9fbb7..84ee18092 100644
--- a/docs/concepts/sessions-runs-and-streaming.md
+++ b/docs/concepts/sessions-runs-and-streaming.md
@@ -73,6 +73,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 +165,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>"
```
diff --git a/docs/guides/client/streaming.mdx b/docs/guides/client/streaming.mdx
index 0fdc6625d..3442e847c 100644
--- a/docs/guides/client/streaming.mdx
+++ b/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
diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdx
index 06ee672bb..209339c20 100644
--- a/docs/guides/frontend/overview.mdx
+++ b/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.
diff --git a/docs/guides/frontend/use-eve-agent-svelte.mdx b/docs/guides/frontend/use-eve-agent-svelte.mdx
index 99127adf4..6e78c1d3d 100644
--- a/docs/guides/frontend/use-eve-agent-svelte.mdx
+++ b/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. |
diff --git a/docs/guides/frontend/use-eve-agent-vue.mdx b/docs/guides/frontend/use-eve-agent-vue.mdx
index 2cb6adab6..a6332efe5 100644
--- a/docs/guides/frontend/use-eve-agent-vue.mdx
+++ b/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>`.
diff --git a/docs/guides/hooks.md b/docs/guides/hooks.md
index 6a8132b91..1b6898bbc 100644
--- a/docs/guides/hooks.md
+++ b/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
diff --git a/e2e/fixtures/agent-basic-runtime/evals/runtime/stream-event-ids.eval.ts b/e2e/fixtures/agent-basic-runtime/evals/runtime/stream-event-ids.eval.ts
new file mode 100644
index 000000000..14d98fd48
--- /dev/null
+++ b/e2e/fixtures/agent-basic-runtime/evals/runtime/stream-event-ids.eval.ts
@@ -0,0 +1,38 @@
+import { defineEval } from "eve/evals";
+import { equals, satisfies } from "eve/evals/expect";
+
+/** `evt_` followed by a 26-character Crockford base32 ULID. */
+const EVENT_ID = /^evt_[0-9ABCDEFGHJKMNPQRSTVWXYZ]{26}$/;
+
+/**
+ * Core session-route runtime behavior: durable stream event ids.
+ *
+ * Module tests cover the stamping seam in process; this is the only check
+ * that the id survives the wire and a rewind.
+ */
+export default defineEval({
+ description: "Session runtime smoke: stream event ids are stamped and stable across a rewind.",
+
+ async test(t) {
+ const turn = await t.send('Reply with exactly the text "id smoke" and nothing else.');
+ t.succeeded();
+
+ const ids = turn.events.map((event) => event.meta.id);
+
+ await t.require(
+ ids,
+ satisfies<readonly string[]>(
+ (value) => value.length > 0 && value.every((id) => EVENT_ID.test(id)),
+ "every event carries a well-formed evt_ id",
+ ),
+ );
+
+ // Re-reading the durable stream is not a new emission.
+ const replay = await t.target.watchTurn(turn.sessionId, { startIndex: 0 }).result();
+
+ await t.require(
+ replay.events.map((event) => event.meta.id),
+ equals(ids),
+ );
+ },
+});
diff --git a/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-curl-fanout.eval.ts b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-curl-fanout.eval.ts
index 9958e5029..33ff985d5 100644
--- a/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-curl-fanout.eval.ts
+++ b/e2e/fixtures/agent-tools-sandbox/evals/sandbox/bash-curl-fanout.eval.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
import { defineEval } from "eve/evals";
import { FANOUT_BARRIER_SERVER_URL } from "./shared";
@@ -62,7 +62,7 @@ function commandFor(request: (typeof REQUESTS)[number]): string {
function curlCallsReachBarrier(input: {
readonly barrierSize: number;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly expectedRequests: readonly { readonly label: string; readonly query: string }[];
readonly minimumCalls: number;
}): boolean {
@@ -85,9 +85,7 @@ function curlCallsReachBarrier(input: {
);
}
-function curlBarrierResults(
- events: readonly HandleMessageStreamEvent[],
-): readonly CurlBarrierResult[] {
+function curlBarrierResults(events: readonly MessageStreamEvent[]): readonly CurlBarrierResult[] {
return events.flatMap((event) => {
if (event.type !== "action.result" || event.data.result.kind !== "tool-result") return [];
if (event.data.result.toolName !== BASH_TOOL) return [];
@@ -119,7 +117,7 @@ function parseCurlBarrierResult(value: unknown): readonly CurlBarrierResult[] {
return [];
}
-function formatCurlFanoutTrace(events: readonly HandleMessageStreamEvent[]): string {
+function formatCurlFanoutTrace(events: readonly MessageStreamEvent[]): string {
return JSON.stringify({
calls: curlBarrierResults(events),
});
diff --git a/e2e/fixtures/agent-tools/evals/channel-events/pre-tool-narration.eval.ts b/e2e/fixtures/agent-tools/evals/channel-events/pre-tool-narration.eval.ts
index 638b428a9..7998ff4db 100644
--- a/e2e/fixtures/agent-tools/evals/channel-events/pre-tool-narration.eval.ts
+++ b/e2e/fixtures/agent-tools/evals/channel-events/pre-tool-narration.eval.ts
@@ -1,6 +1,6 @@
import { randomBytes } from "node:crypto";
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
import { defineEval, type EveEvalTargetHandle } from "eve/evals";
import { satisfies } from "eve/evals/expect";
@@ -18,7 +18,7 @@ function firstNonEmptyLine(message: string): string | undefined {
return undefined;
}
-function preToolNarration(events: readonly HandleMessageStreamEvent[]): string | undefined {
+function preToolNarration(events: readonly MessageStreamEvent[]): string | undefined {
const actionRequestIndex = events.findIndex(
(event) =>
event.type === "actions.requested" &&
@@ -41,7 +41,7 @@ function preToolNarration(events: readonly HandleMessageStreamEvent[]): string |
return undefined;
}
-function narratedStreamedActionOrder(events: readonly HandleMessageStreamEvent[]): boolean {
+function narratedStreamedActionOrder(events: readonly MessageStreamEvent[]): boolean {
const requests = events.flatMap((event, eventIndex) => {
if (event.type !== "actions.requested") return [];
diff --git a/e2e/fixtures/agent-tools/evals/static-tools/fanout.ts b/e2e/fixtures/agent-tools/evals/static-tools/fanout.ts
index c5ae8ffde..421719cc6 100644
--- a/e2e/fixtures/agent-tools/evals/static-tools/fanout.ts
+++ b/e2e/fixtures/agent-tools/evals/static-tools/fanout.ts
@@ -1,10 +1,10 @@
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
export const FANOUT_SIZE = 10;
/** A serialized executor cannot release the fixture tool's concurrency barrier. */
export function fanoutExecutionsReachBarrier(input: {
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly labels: readonly string[];
readonly toolName: string;
}): boolean {
diff --git a/e2e/fixtures/agent-tools/evals/static-tools/streamed-action.eval.ts b/e2e/fixtures/agent-tools/evals/static-tools/streamed-action.eval.ts
index 5664fb88e..88c231ced 100644
--- a/e2e/fixtures/agent-tools/evals/static-tools/streamed-action.eval.ts
+++ b/e2e/fixtures/agent-tools/evals/static-tools/streamed-action.eval.ts
@@ -1,12 +1,10 @@
-import type { ActionResultStreamEvent, HandleMessageStreamEvent } from "eve/client";
+import type { ActionResultStreamEvent, MessageStreamEvent } from "eve/client";
import { defineEval } from "eve/evals";
const TOOL_NAME = "streamed-action";
const LABEL = "streaming-e2e";
-function streamedBeforeLocalExecutionCompletes(
- events: readonly HandleMessageStreamEvent[],
-): boolean {
+function streamedBeforeLocalExecutionCompletes(events: readonly MessageStreamEvent[]): boolean {
const matchingRequests = events.flatMap((event) => {
if (event.type !== "actions.requested") return [];
@@ -24,7 +22,7 @@ function streamedBeforeLocalExecutionCompletes(
}
const result = events.find(
- (event): event is ActionResultStreamEvent =>
+ (event): event is ActionResultStreamEvent & MessageStreamEvent =>
event.type === "action.result" &&
event.data.result.kind === "tool-result" &&
event.data.result.callId === request.action.callId,
@@ -33,7 +31,7 @@ function streamedBeforeLocalExecutionCompletes(
return false;
}
- const requestAt = parseTimestamp(request.event.meta?.at);
+ const requestAt = parseTimestamp(request.event.meta.at);
const executionCompletedAt = readExecutionCompletedAt(result.data.result.output);
return (
requestAt !== undefined &&
@@ -42,9 +40,7 @@ function streamedBeforeLocalExecutionCompletes(
);
}
-function parseTimestamp(value: string | undefined): number | undefined {
- if (value === undefined) return undefined;
-
+function parseTimestamp(value: string): number | undefined {
const timestamp = Date.parse(value);
return Number.isFinite(timestamp) ? timestamp : undefined;
}
diff --git a/e2e/fixtures/agent-tools/evals/static-tools/to-model-output-content-parts.eval.ts b/e2e/fixtures/agent-tools/evals/static-tools/to-model-output-content-parts.eval.ts
index cab2a09d0..dcf53e558 100644
--- a/e2e/fixtures/agent-tools/evals/static-tools/to-model-output-content-parts.eval.ts
+++ b/e2e/fixtures/agent-tools/evals/static-tools/to-model-output-content-parts.eval.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
import { defineEval } from "eve/evals";
const TOOL_NAME = "render-stripes";
@@ -50,7 +50,7 @@ function isRenderStripesOutput(value: unknown): boolean {
);
}
-function renderedColors(events: readonly HandleMessageStreamEvent[]): readonly string[] {
+function renderedColors(events: readonly MessageStreamEvent[]): readonly string[] {
for (const event of events) {
if (event.type !== "action.result" || event.data.result.kind !== "tool-result") continue;
if (event.data.result.toolName !== TOOL_NAME) continue;
@@ -63,7 +63,7 @@ function renderedColors(events: readonly HandleMessageStreamEvent[]): readonly s
}
/** Final (non-tool-call) assistant messages, in turn order. */
-function assistantAnswers(events: readonly HandleMessageStreamEvent[]): readonly string[] {
+function assistantAnswers(events: readonly MessageStreamEvent[]): readonly string[] {
return events.flatMap((event) =>
event.type === "message.completed" &&
event.data.finishReason !== "tool-calls" &&
@@ -74,7 +74,7 @@ function assistantAnswers(events: readonly HandleMessageStreamEvent[]): readonly
);
}
-function namesColorsInOrder(events: readonly HandleMessageStreamEvent[], answer: string): boolean {
+function namesColorsInOrder(events: readonly MessageStreamEvent[], answer: string): boolean {
const colors = renderedColors(events);
if (colors.length === 0) return false;
const pattern = new RegExp(colors.map((color) => `\\b${color}\\b`).join("[\\s\\S]*"), "iu");
diff --git a/e2e/fixtures/agent-tools/evals/static-tools/web-search-ordering.ts b/e2e/fixtures/agent-tools/evals/static-tools/web-search-ordering.ts
index a4cf0bdc4..b5123dc9a 100644
--- a/e2e/fixtures/agent-tools/evals/static-tools/web-search-ordering.ts
+++ b/e2e/fixtures/agent-tools/evals/static-tools/web-search-ordering.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
export const WEB_SEARCH_TOOL_NAME = "web_search";
@@ -7,7 +7,7 @@ interface WebSearchEventOrder {
readonly resultIndex: number;
}
-export function narratedWebSearchOrder(events: readonly HandleMessageStreamEvent[]): boolean {
+export function narratedWebSearchOrder(events: readonly MessageStreamEvent[]): boolean {
const order = webSearchEventOrder(events);
return (
order !== undefined &&
@@ -16,7 +16,7 @@ export function narratedWebSearchOrder(events: readonly HandleMessageStreamEvent
);
}
-export function unNarratedWebSearchOrder(events: readonly HandleMessageStreamEvent[]): boolean {
+export function unNarratedWebSearchOrder(events: readonly MessageStreamEvent[]): boolean {
const order = webSearchEventOrder(events);
return (
order !== undefined &&
@@ -26,7 +26,7 @@ export function unNarratedWebSearchOrder(events: readonly HandleMessageStreamEve
}
function webSearchEventOrder(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly MessageStreamEvent[],
): WebSearchEventOrder | undefined {
const requests = events.flatMap((event, eventIndex) => {
if (event.type !== "actions.requested") return [];
@@ -58,7 +58,7 @@ function webSearchEventOrder(
}
function preToolNarrationExists(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly MessageStreamEvent[],
requestIndex: number,
): boolean {
return events
@@ -73,7 +73,7 @@ function preToolNarrationExists(
}
function finalMessageFollowsResult(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly MessageStreamEvent[],
resultIndex: number,
): boolean {
return events
diff --git a/e2e/fixtures/agent-tools/evals/static-tools/web-search-parallel.eval.ts b/e2e/fixtures/agent-tools/evals/static-tools/web-search-parallel.eval.ts
index 5a9bc7a15..e826d8136 100644
--- a/e2e/fixtures/agent-tools/evals/static-tools/web-search-parallel.eval.ts
+++ b/e2e/fixtures/agent-tools/evals/static-tools/web-search-parallel.eval.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
import { defineEval } from "eve/evals";
const TOOL_NAME = "web_search";
@@ -9,7 +9,7 @@ const EXPECTED_WINNERS =
"2023 Denver Nuggets; 2022 Golden State Warriors; 2021 Milwaukee Bucks; " +
"2020 Los Angeles Lakers; 2019 Toronto Raptors.";
-function completedToolResultCount(events: readonly HandleMessageStreamEvent[], toolName: string) {
+function completedToolResultCount(events: readonly MessageStreamEvent[], toolName: string) {
const callIds = new Set<string>();
for (const event of events) {
if (
diff --git a/e2e/fixtures/agent-tools/evals/static-tools/web-search.eval.ts b/e2e/fixtures/agent-tools/evals/static-tools/web-search.eval.ts
index d587ee634..ecf4e2189 100644
--- a/e2e/fixtures/agent-tools/evals/static-tools/web-search.eval.ts
+++ b/e2e/fixtures/agent-tools/evals/static-tools/web-search.eval.ts
@@ -1,9 +1,9 @@
-import type { HandleMessageStreamEvent } from "eve/client";
+import type { MessageStreamEvent } from "eve/client";
import { defineEval } from "eve/evals";
const TOOL_NAME = "web_search";
-function providerRequestsPrecedeResults(events: readonly HandleMessageStreamEvent[]): boolean {
+function providerRequestsPrecedeResults(events: readonly MessageStreamEvent[]): boolean {
const requestIndexByCallId = new Map<string, number>();
const resultIndexByCallId = new Map<string, number>();
let requestCount = 0;
diff --git a/packages/eve/extension-contracts/compatibility/dynamicInstructions/v1.ts b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v1.ts
new file mode 100644
index 000000000..57f2bcdbd
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicInstructions/v1.ts
@@ -0,0 +1,16 @@
+import { defineDynamic, defineInstructions } from "#public/instructions/index.js";
+
+/**
+ * Epoch 1 resolves the per-session system prompt from `session.started`,
+ * reading only the resolve context. The event envelope stays invisible to it.
+ */
+export default defineDynamic({
+ events: {
+ "session.started": (_event, ctx) => {
+ const plan = ctx.session.auth.current?.attributes.plan ?? "free";
+ return defineInstructions({
+ markdown: `The caller is on the ${String(plan)} plan. Match the depth of your answers to it.`,
+ });
+ },
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicSkill/v1.ts b/packages/eve/extension-contracts/compatibility/dynamicSkill/v1.ts
new file mode 100644
index 000000000..75a3d9b28
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicSkill/v1.ts
@@ -0,0 +1,20 @@
+import { defineDynamic, defineSkill } from "#public/skills/index.js";
+
+/**
+ * Epoch 1 resolves a per-principal skill from `session.started` and
+ * `turn.started`, ignoring the event body entirely.
+ */
+export default defineDynamic({
+ events: {
+ "session.started": (_event, ctx) => {
+ const team = ctx.session.auth.current?.attributes.team;
+ return typeof team === "string"
+ ? defineSkill({
+ description: `Escalation playbook for the ${team} team.`,
+ markdown: `# ${team} playbook\n\nFollow the ${team} escalation path.`,
+ })
+ : null;
+ },
+ "turn.started": () => null,
+ },
+});
diff --git a/packages/eve/extension-contracts/compatibility/dynamicTool/v4.ts b/packages/eve/extension-contracts/compatibility/dynamicTool/v4.ts
new file mode 100644
index 000000000..6c2095895
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/dynamicTool/v4.ts
@@ -0,0 +1,36 @@
+import {
+ defineDynamic,
+ defineTool,
+ type DynamicToolEvents,
+ type DynamicToolResult,
+} from "#public/tools/index.js";
+
+/**
+ * Epoch 4 resolvers take the stream event as `unknown` — `meta.id` predates
+ * epoch 5 — and shape model-facing output with `toModelOutput`.
+ */
+const events = {
+ "session.started": (_event, ctx): DynamicToolResult => ({
+ summarize_report: defineTool({
+ description: "Summarize a report for the model",
+ inputSchema: { type: "object", properties: {} },
+ async execute(_input, toolContext) {
+ return {
+ internal: "details",
+ resolverSessionId: ctx.session.id,
+ sessionId: toolContext.session.id,
+ summary: "Report generated",
+ };
+ },
+ toModelOutput(output) {
+ return {
+ type: "text",
+ value: (output as { summary: string }).summary,
+ };
+ },
+ }),
+ }),
+ "step.started": (): DynamicToolResult => null,
+} satisfies DynamicToolEvents;
+
+export default defineDynamic({ events });
diff --git a/packages/eve/extension-contracts/compatibility/hook/v2.ts b/packages/eve/extension-contracts/compatibility/hook/v2.ts
new file mode 100644
index 000000000..1ebc2bb11
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/hook/v2.ts
@@ -0,0 +1,31 @@
+import { defineHook } from "#public/hooks/index.js";
+
+/**
+ * Epoch 2 authors keyed their own bookkeeping off the turn coordinates in
+ * `data` and read `meta` defensively. Both patterns must keep compiling.
+ */
+export default defineHook({
+ events: {
+ "turn.started"(event, ctx) {
+ console.info("turn started", {
+ agentName: ctx.agent.name,
+ sequence: event.data.sequence,
+ sessionId: ctx.session.id,
+ turnId: event.data.turnId,
+ });
+ },
+ "action.result"(event) {
+ console.info("tool call settled", {
+ status: event.data.status,
+ stepIndex: event.data.stepIndex,
+ });
+ },
+ "*"(event, ctx) {
+ console.info("stream event", {
+ at: event.meta?.at,
+ channelKind: ctx.channel.kind,
+ type: event.type,
+ });
+ },
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/dynamicInstructions/v2.json b/packages/eve/extension-contracts/reports/dynamicInstructions/v2.json
new file mode 100644
index 000000000..9f396c969
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicInstructions/v2.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicInstructions",
+ "epoch": 2,
+ "sha256": "963233139c1047afb2bf960bdd213eb6d2ee6a5f43991fe131f874afd75aa7de",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicSkill/v2.json b/packages/eve/extension-contracts/reports/dynamicSkill/v2.json
new file mode 100644
index 000000000..4aa7f8173
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicSkill/v2.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicSkill",
+ "epoch": 2,
+ "sha256": "963233139c1047afb2bf960bdd213eb6d2ee6a5f43991fe131f874afd75aa7de",
+ "exports": ["defineDynamic"]
+}
diff --git a/packages/eve/extension-contracts/reports/dynamicTool/v5.json b/packages/eve/extension-contracts/reports/dynamicTool/v5.json
new file mode 100644
index 000000000..e56c3c537
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/dynamicTool/v5.json
@@ -0,0 +1,13 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "dynamicTool",
+ "epoch": 5,
+ "sha256": "1b684cf701385b715dec2bc04dd95609000b4226f2282db66b0dfa9bb3275ba0",
+ "exports": [
+ "DynamicToolEntry",
+ "DynamicToolEvents",
+ "DynamicToolResult",
+ "DynamicToolSet",
+ "defineDynamic"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/hook/v3.json b/packages/eve/extension-contracts/reports/hook/v3.json
new file mode 100644
index 000000000..5a0e4de6a
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/hook/v3.json
@@ -0,0 +1,7 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "hook",
+ "epoch": 3,
+ "sha256": "c47abcda171019dfa8fb9dd2eb1d1392679fdbcd0c8e98c7d16cddbb70458bef",
+ "exports": ["defineHook"]
+}
diff --git a/packages/eve/src/channel/adapter.ts b/packages/eve/src/channel/adapter.ts
index e74219cfa..8cb3ca96d 100644
--- a/packages/eve/src/channel/adapter.ts
+++ b/packages/eve/src/channel/adapter.ts
@@ -1,7 +1,7 @@
import type { ContextAccessor } from "#context/key.js";
import type { StepInput } from "#harness/types.js";
import { createLogger } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { SessionHandle } from "#channel/session.js";
import type { DeliverPayload } from "#channel/types.js";
import type { FetchFileResult, FetchFileFunction } from "#shared/channel-definition.js";
@@ -61,15 +61,15 @@ type StateOf<TCtx> = TCtx extends ChannelAdapterContext<infer S> ? S : Record<st
* Extracts the `data` field type from a stream event by its `type` discriminant.
* Events that carry no `data` field (e.g. `session.completed`) resolve to `undefined`.
*/
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/**
* A single outbound event handler. Receives the event's `data` (not the full
* envelope) and the adapter context. Void return — side effects only.
*/
type EventHandler<
- T extends HandleMessageStreamEvent["type"],
+ T extends UnstampedMessageStreamEvent["type"],
TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext,
> = (data: EventData<T>, ctx: TCtx) => void | Promise<void>;
@@ -80,7 +80,7 @@ type EventHandler<
*/
export type ChannelEventHandlers<TCtx extends ChannelAdapterContext<any> = ChannelAdapterContext> =
{
- [K in HandleMessageStreamEvent["type"]]?: EventHandler<K, TCtx>;
+ [K in UnstampedMessageStreamEvent["type"]]?: EventHandler<K, TCtx>;
};
// ---------------------------------------------------------------------------
@@ -232,9 +232,9 @@ export function getAdapterKind(adapter: ChannelAdapter): string {
*/
export async function callAdapterEventHandler(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: ChannelAdapterContext,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
const handler = adapter[event.type] as
| ((data: unknown, ctx: ChannelAdapterContext) => void | Promise<void>)
| undefined;
diff --git a/packages/eve/src/channel/schedule.test.ts b/packages/eve/src/channel/schedule.test.ts
index f27bf0e2b..fa4c68f96 100644
--- a/packages/eve/src/channel/schedule.test.ts
+++ b/packages/eve/src/channel/schedule.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
import { CHANNEL_SENTINEL, type CompiledChannel } from "#channel/compiled-channel.js";
import { isCompiledChannel } from "#channel/compiled-channel.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import {
SCHEDULE_ADAPTER,
SCHEDULE_ADAPTER_KIND,
@@ -17,7 +17,7 @@ import type { ResolvedChannelDefinition } from "#runtime/types.js";
function createMockRunHandle(): RunHandle {
return {
continuationToken: "slack:C0123ABC:",
- events: new ReadableStream<HandleMessageStreamEvent>(),
+ events: new ReadableStream<MessageStreamEvent>(),
sessionId: "mock-session-id",
};
}
@@ -28,7 +28,7 @@ function createMockRuntime(): Runtime {
deliver: vi.fn().mockRejectedValue(new RuntimeNoActiveSessionError("schedule:token")),
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
- getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getEventStream: vi.fn().mockResolvedValue(new ReadableStream<MessageStreamEvent>()),
getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
diff --git a/packages/eve/src/channel/send.test.ts b/packages/eve/src/channel/send.test.ts
index 3ddc8194e..17c078cb0 100644
--- a/packages/eve/src/channel/send.test.ts
+++ b/packages/eve/src/channel/send.test.ts
@@ -4,12 +4,12 @@ import type { ChannelAdapter } from "#channel/adapter.js";
import { createSendFn } from "#channel/send.js";
import type { RunHandle, Runtime } from "#channel/types.js";
import { RuntimeNoActiveSessionError } from "#execution/runtime-errors.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
function createMockRunHandle(): RunHandle {
return {
continuationToken: "test:token",
- events: new ReadableStream<HandleMessageStreamEvent>(),
+ events: new ReadableStream<MessageStreamEvent>(),
sessionId: "mock-session-id",
};
}
@@ -20,7 +20,7 @@ function createRuntime(deliverError: unknown): Runtime {
deliver: vi.fn().mockRejectedValue(deliverError),
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
- getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getEventStream: vi.fn().mockResolvedValue(new ReadableStream<MessageStreamEvent>()),
getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
@@ -84,7 +84,7 @@ describe("createSendFn", () => {
deliver: vi.fn().mockResolvedValue({ sessionId: "existing-session-id" }),
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
- getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getEventStream: vi.fn().mockResolvedValue(new ReadableStream<MessageStreamEvent>()),
getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
@@ -119,7 +119,7 @@ describe("createSendFn", () => {
deliver: vi.fn().mockResolvedValue({ sessionId: "existing-session-id" }),
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
- getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getEventStream: vi.fn().mockResolvedValue(new ReadableStream<MessageStreamEvent>()),
getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
@@ -149,7 +149,7 @@ describe("createSendFn", () => {
deliver: vi.fn().mockResolvedValue({ sessionId: "existing-session-id" }),
resolveSession: vi.fn(),
run: vi.fn().mockResolvedValue(createMockRunHandle()),
- getEventStream: vi.fn().mockResolvedValue(new ReadableStream<HandleMessageStreamEvent>()),
+ getEventStream: vi.fn().mockResolvedValue(new ReadableStream<MessageStreamEvent>()),
getStreamTailIndex: vi.fn().mockResolvedValue(-1),
terminateSession: vi.fn(),
};
diff --git a/packages/eve/src/channel/session.ts b/packages/eve/src/channel/session.ts
index b95383de3..6cd95fa64 100644
--- a/packages/eve/src/channel/session.ts
+++ b/packages/eve/src/channel/session.ts
@@ -1,5 +1,5 @@
import type { ContextAccessor } from "#context/key.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { CancelTurnResult, Runtime } from "#channel/types.js";
import type { SessionAuth } from "#context/keys.js";
import { AuthKey, ContinuationTokenKey, InitiatorAuthKey, SessionIdKey } from "#context/keys.js";
@@ -27,9 +27,7 @@ export interface Session {
* Opens the durable event stream. Negative start indexes read relative to
* the current tail (`-1` starts at the latest event).
*/
- getEventStream(options?: {
- startIndex?: number;
- }): Promise<ReadableStream<HandleMessageStreamEvent>>;
+ getEventStream(options?: { startIndex?: number }): Promise<ReadableStream<MessageStreamEvent>>;
/**
* Resolves the durable tail of the event stream: the zero-based index of
* the last recorded event, or `-1` before the first.
diff --git a/packages/eve/src/channel/types.ts b/packages/eve/src/channel/types.ts
index f8c3e89e6..add8a380d 100644
--- a/packages/eve/src/channel/types.ts
+++ b/packages/eve/src/channel/types.ts
@@ -1,6 +1,6 @@
import type { UserContent } from "ai";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent, MessageStreamEvent } from "#protocol/message.js";
import type { CancelTurnStatus } from "#protocol/cancel-turn.js";
import type { RunMode } from "#shared/run-mode.js";
import type { RuntimeActionResult } from "#runtime/actions/types.js";
@@ -104,7 +104,7 @@ export interface SessionAuthContext {
* Backed by `getWritable()` in the workflow runtime. Not part of the adapter
* interface: the runtime always writes events itself.
*/
-export type EventEmitFn = (event: HandleMessageStreamEvent) => Promise<void>;
+export type EventEmitFn = (event: UnstampedMessageStreamEvent) => Promise<void>;
// ---------------------------------------------------------------------------
// Deliver payload
@@ -189,7 +189,7 @@ export interface SubagentInputRequestHookPayload {
/** Authorization lifecycle event forwarded from a delegated child. */
export type SubagentAuthorizationEvent = Extract<
- HandleMessageStreamEvent,
+ UnstampedMessageStreamEvent,
{ type: "authorization.required" | "authorization.completed" }
>;
@@ -371,7 +371,7 @@ export type RunResult =
*/
export interface RunHandle {
readonly continuationToken: string;
- readonly events: ReadableStream<HandleMessageStreamEvent>;
+ readonly events: ReadableStream<MessageStreamEvent>;
/**
* Runtime-owned identifier for this session. Stream and inspection APIs
* key on it: workflow-backed runs expose the workflow run id.
@@ -425,7 +425,7 @@ export interface Runtime {
getEventStream(
sessionId: string,
options?: GetEventStreamOptions,
- ): Promise<ReadableStream<HandleMessageStreamEvent>>;
+ ): Promise<ReadableStream<MessageStreamEvent>>;
/**
* Resolves the durable tail of a session's event stream: the zero-based
diff --git a/packages/eve/src/cli/dev/tui/runner.test.ts b/packages/eve/src/cli/dev/tui/runner.test.ts
index 2a82253fc..c41588fb8 100644
--- a/packages/eve/src/cli/dev/tui/runner.test.ts
+++ b/packages/eve/src/cli/dev/tui/runner.test.ts
@@ -6,9 +6,11 @@ import {
MessageResponse,
type AgentInfoResult,
type ClientSession,
- type HandleMessageStreamEvent,
+ type MessageStreamEvent,
} from "#client/index.js";
+import { stampTestEvent } from "#internal/testing/events.js";
import { resolveTestVercelTarget } from "#internal/testing/verified-vercel-target.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { createDevelopmentCredentialGate } from "#services/dev-client/credential-gate.js";
import type { VercelDeploymentResolution } from "#setup/vercel-deployment.js";
@@ -54,17 +56,28 @@ function stubSession(): ClientSession {
return stubClient().session();
}
-/** Wraps literal stream events in a real `MessageResponse`. */
+/**
+ * Wraps literal stream events in a real `MessageResponse`. Each literal is
+ * stamped as its own emission; pass the same stamped event twice to model a
+ * re-delivery.
+ */
function messageResponseOf(events: readonly unknown[]): MessageResponse {
+ const stamped = events.map((event, index) =>
+ isStamped(event) ? event : stampTestEvent(event as UnstampedMessageStreamEvent, index),
+ );
return new MessageResponse({
continuationToken: "eve:test",
createStream: async function* () {
- for (const event of events) yield event as HandleMessageStreamEvent;
+ for (const event of stamped) yield event;
},
sessionId: "session_test",
});
}
+function isStamped(event: unknown): event is MessageStreamEvent {
+ return typeof (event as MessageStreamEvent).meta?.id === "string";
+}
+
const AGENT_INFO: AgentInfoResult = {
agent: {
agentRoot: "/tmp/weather-agent/agent",
@@ -558,7 +571,15 @@ describe("EveTUIRunner development session continuity", () => {
start(controller) {
controller.enqueue(
encoder.encode(
- '{"type":"session.waiting","data":{"continuationToken":"token-session-1","wait":"next-user-message"}}\n',
+ `${JSON.stringify(
+ stampTestEvent({
+ type: "session.waiting",
+ data: {
+ continuationToken: "token-session-1",
+ wait: "next-user-message",
+ },
+ } as UnstampedMessageStreamEvent),
+ )}\n`,
),
);
controller.close();
@@ -965,14 +986,14 @@ describe("EveTUIRunner connection authorization", () => {
{ type: "session.waiting", data: { wait: "connection-authorization" } },
]);
vi.spyOn(session, "stream").mockImplementation(async function* () {
- yield {
+ yield stampTestEvent({
type: "authorization.completed",
data: { name: "linear", outcome: "authorized" },
- } as HandleMessageStreamEvent;
- yield {
+ } as UnstampedMessageStreamEvent);
+ yield stampTestEvent({
type: "session.waiting",
data: { wait: "next-user-message" },
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent);
});
const renderer: AgentTUIRenderer = {
readPrompt: vi.fn(async () => prompts.shift()),
@@ -1159,6 +1180,57 @@ describe("EveTUIRunner reused step indexes", () => {
});
describe("EveTUIRunner replay guards", () => {
+ it("renders a re-delivered chunk once even after the next step reuses its key", async () => {
+ // Coordinates alone cannot tell a re-delivered chunk apart from a fresh
+ // model call reusing `stepIndex`; only the id can.
+ const appended = stampTestEvent(
+ {
+ type: "message.appended",
+ data: {
+ messageDelta: "Sunny.",
+ messageSoFar: "Sunny.",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ },
+ } as UnstampedMessageStreamEvent,
+ 1,
+ );
+ const prompts: Array<string | undefined> = ["weather", undefined];
+ const emitted: AgentTUIStreamEvent[] = [];
+ const session = sessionYielding([
+ { type: "step.started", data: { sequence: 0, stepIndex: 0, turnId: "turn_0" } },
+ appended,
+ {
+ type: "message.completed",
+ data: {
+ finishReason: "stop",
+ message: "Sunny.",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn_0",
+ },
+ },
+ { type: "step.started", data: { sequence: 1, stepIndex: 0, turnId: "turn_0" } },
+ appended,
+ { type: "session.waiting", data: { wait: "next-user-message" } },
+ ]);
+ const renderer: AgentTUIRenderer = {
+ readPrompt: vi.fn(async () => prompts.shift()),
+ renderStream: vi.fn(async (result) => {
+ for await (const event of result.events as AsyncIterable<AgentTUIStreamEvent>) {
+ emitted.push(event);
+ }
+ }),
+ };
+
+ const runner = new EveTUIRunner({ session, renderer, name: "Weather Agent" });
+ await runner.run();
+
+ const deltas = emitted.filter((event) => event.type === "assistant-delta");
+ expect(deltas).toEqual([{ type: "assistant-delta", id: "text:turn_0:0", delta: "Sunny." }]);
+ });
+
it("deduplicates repeated call IDs and divergent text attempts in one turn", async () => {
const prompts: Array<string | undefined> = ["weather", undefined];
const emitted: AgentTUIStreamEvent[] = [];
@@ -1907,20 +1979,26 @@ describe("EveTUIRunner renderer teardown", () => {
vi.spyOn(client, "session").mockReturnValue(childSession);
vi.spyOn(childSession, "stream").mockImplementation(() => ({
async *[Symbol.asyncIterator]() {
- yield {
- type: "message.completed",
- data: {
- finishReason: "stop",
- message: "final answer",
- sequence: 0,
- stepIndex: 0,
- turnId: "turn-child",
- },
- } as HandleMessageStreamEvent;
- yield {
- type: "session.waiting",
- data: { wait: "next-user-message" },
- } as HandleMessageStreamEvent;
+ yield stampTestEvent(
+ {
+ type: "message.completed",
+ data: {
+ finishReason: "stop",
+ message: "final answer",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn-child",
+ },
+ } as UnstampedMessageStreamEvent,
+ 0,
+ );
+ yield stampTestEvent(
+ {
+ type: "session.waiting",
+ data: { wait: "next-user-message" },
+ } as UnstampedMessageStreamEvent,
+ 1,
+ );
},
}));
@@ -1997,10 +2075,13 @@ describe("EveTUIRunner renderer teardown", () => {
await new Promise<void>((resolve) => {
signal.addEventListener("abort", () => resolve(), { once: true });
});
- yield {
- type: "session.waiting",
- data: { wait: "next-user-message" },
- } as HandleMessageStreamEvent;
+ yield stampTestEvent(
+ {
+ type: "session.waiting",
+ data: { wait: "next-user-message" },
+ } as UnstampedMessageStreamEvent,
+ 1,
+ );
},
};
});
@@ -2829,12 +2910,24 @@ describe("EveTUIRunner mid-turn message queue", () => {
new MessageResponse({
continuationToken: "eve:test",
createStream: async function* () {
- yield { type: "turn.started", data: { turnId: "turn-1", sequence: 1 } } as never;
+ yield stampTestEvent(
+ {
+ type: "turn.started",
+ data: { turnId: "turn-1", sequence: 1 },
+ } as UnstampedMessageStreamEvent,
+ 0,
+ );
// Hold the stream mid-turn until the retry loop has proven both
// attempts, then settle the turn as cancelled.
await gate.promise;
- yield { type: "turn.cancelled", data: { turnId: "turn-1", sequence: 2 } } as never;
- yield { type: "session.waiting" } as never;
+ yield stampTestEvent(
+ {
+ type: "turn.cancelled",
+ data: { turnId: "turn-1", sequence: 2 },
+ } as UnstampedMessageStreamEvent,
+ 1,
+ );
+ yield stampTestEvent({ type: "session.waiting" } as UnstampedMessageStreamEvent, 2);
},
sessionId: "session_test",
}),
diff --git a/packages/eve/src/cli/dev/tui/runner.ts b/packages/eve/src/cli/dev/tui/runner.ts
index ec49bfdb3..ba9ba9dde 100644
--- a/packages/eve/src/cli/dev/tui/runner.ts
+++ b/packages/eve/src/cli/dev/tui/runner.ts
@@ -5,7 +5,6 @@ import {
type AuthorizationCompletedStreamEvent,
type ConnectionAuthorizationOutcome,
type AuthorizationRequiredStreamEvent,
- type HandleMessageStreamEvent,
type InputOption,
type InputRequest,
type InputRequestedStreamEvent,
@@ -14,6 +13,7 @@ import {
type ReasoningAppendedStreamEvent,
type SessionFailedStreamEvent,
type StepCompletedStreamEvent,
+ type MessageStreamEvent,
type SubagentCalledStreamEvent,
type SubagentCompletedStreamEvent,
Client,
@@ -21,6 +21,7 @@ import {
} from "#client/index.js";
import { loadDevelopmentEnvironmentFiles } from "#cli/dev/environment.js";
import { subscribeDevelopmentSandboxPrewarmLogs } from "#execution/sandbox/development-prewarm.js";
+import { createEventDeduper } from "#protocol/event-dedupe.js";
import {
createDevelopmentRuntimeArtifactRefresher,
type DevelopmentRuntimeArtifactRefresher,
@@ -1184,7 +1185,7 @@ export class EveTUIRunner {
}
#createTUIStreamResult(
- events: AsyncIterable<HandleMessageStreamEvent>,
+ events: AsyncIterable<MessageStreamEvent>,
abort: () => void,
): AgentTUIStreamResult {
const turnState = createTurnState();
@@ -1632,7 +1633,7 @@ function formatAgentUpdateNotice(
}
type EveStreamTranslatorInput = {
- events: AsyncIterable<HandleMessageStreamEvent>;
+ events: AsyncIterable<MessageStreamEvent>;
pendingInputRequests: Map<string, InputRequest>;
turnState: AgentTUITurnState;
onSubagentCalled?: (event: SubagentCalledStreamEvent) => void;
@@ -1671,11 +1672,13 @@ async function* eveEventsToTUIStream(
} = input;
const textParts = new Map<string, StreamPartState>();
const reasoningParts = new Map<string, StreamPartState>();
+ // Dropping re-delivered events here means every case below is a new emission.
+ const seenEvents = createEventDeduper();
// Counts `step.started` events. The harness reuses `stepIndex` across the
// model calls of one turn (e.g. the post-subagent call restarts at the same
- // index), so a part key alone cannot distinguish "new message under a
- // reused key" from "replayed events of the finished message". A fresh
- // `step.started` since the part completed is the discriminator.
+ // index), so a part key alone cannot distinguish a new message under a
+ // reused key from a re-emission. A fresh `step.started` since the part
+ // completed is the discriminator.
let stepEpoch = 0;
const knownToolCalls = new Set<string>();
const seenInputRequestIds = new Set<string>();
@@ -1688,6 +1691,10 @@ async function* eveEventsToTUIStream(
let latestStepUsage: StepCompletedStreamEvent["data"]["usage"] | undefined;
for await (const event of events) {
+ if (!seenEvents.admit(event)) {
+ continue;
+ }
+
if (visibleTurnCompleted && isPostTurnVisibleEvent(event)) {
continue;
}
@@ -1726,10 +1733,7 @@ async function* eveEventsToTUIStream(
const next = appended.data.messageSoFar;
if (state.completed) {
- // Replays of the finished message re-stream prefixes of it — drop.
- if (state.text.startsWith(next)) break;
- // Divergent text without an intervening `step.started` is a retry
- // of the same model call — drop it rather than mixing attempts.
+ // No intervening `step.started`: a retry of the same model call.
if (stepEpoch <= state.completedEpoch) break;
// A fresh model call reusing this part key (the harness restarts
// `stepIndex` after a park/resume, e.g. post-subagent): open a new
@@ -1755,7 +1759,7 @@ async function* eveEventsToTUIStream(
const message = event.data.message;
if (state.completed) {
- if (message === null || message === state.text) break;
+ if (message === null) break;
if (stepEpoch <= state.completedEpoch) break;
// Channels that skip per-delta events: a new full message under a
// reused key after a fresh model call.
@@ -1802,7 +1806,6 @@ async function* eveEventsToTUIStream(
const next = appended.data.reasoningSoFar;
if (state.completed) {
- if (state.text.startsWith(next)) break;
if (stepEpoch <= state.completedEpoch) break;
state.generation += 1;
state.text = "";
@@ -1825,7 +1828,7 @@ async function* eveEventsToTUIStream(
const next = event.data.reasoning;
if (state.completed) {
- if (next.length === 0 || next === state.text || state.text.startsWith(next)) break;
+ if (next.length === 0) break;
if (stepEpoch <= state.completedEpoch) break;
state.generation += 1;
state.text = next;
@@ -1996,8 +1999,8 @@ async function* eveEventsToTUIStream(
break;
case "subagent.called": {
- // Run creation (idempotent for SSE-resume re-entries) lives in the
- // pump's begin().
+ // Re-delivery within this translator was filtered above; run creation
+ // and re-entry from a later translator live in the pump's begin().
onSubagentCalled?.(event as SubagentCalledStreamEvent);
break;
}
@@ -2144,7 +2147,7 @@ function* closeOpenParts(
}
}
-function isPostTurnVisibleEvent(event: HandleMessageStreamEvent): boolean {
+function isPostTurnVisibleEvent(event: MessageStreamEvent): boolean {
switch (event.type) {
case "actions.requested":
case "authorization.completed":
diff --git a/packages/eve/src/cli/dev/tui/subagent-pump.test.ts b/packages/eve/src/cli/dev/tui/subagent-pump.test.ts
index d425c5089..169551f09 100644
--- a/packages/eve/src/cli/dev/tui/subagent-pump.test.ts
+++ b/packages/eve/src/cli/dev/tui/subagent-pump.test.ts
@@ -1,7 +1,8 @@
import { describe, expect, it, vi } from "vitest";
-import { Client, type HandleMessageStreamEvent } from "#client/index.js";
-import type { SubagentCalledStreamEvent } from "#protocol/message.js";
+import { Client, type MessageStreamEvent } from "#client/index.js";
+import { stampTestEvent } from "#internal/testing/events.js";
+import type { UnstampedMessageStreamEvent, SubagentCalledStreamEvent } from "#protocol/message.js";
import { SubagentPump, type SubagentView } from "./subagent-pump.js";
@@ -21,17 +22,17 @@ function fakeView(): SubagentView {
* the pump must never reach the view.
*/
function pushableChildStream() {
- const queue: HandleMessageStreamEvent[] = [];
+ const queue: MessageStreamEvent[] = [];
let wake: (() => void) | undefined;
let aborted = false;
return {
- push(event: HandleMessageStreamEvent) {
+ push(event: MessageStreamEvent) {
queue.push(event);
wake?.();
wake = undefined;
},
- stream(options?: { signal?: AbortSignal }): AsyncIterable<HandleMessageStreamEvent> {
+ stream(options?: { signal?: AbortSignal }): AsyncIterable<MessageStreamEvent> {
const signal = options?.signal;
return {
async *[Symbol.asyncIterator]() {
@@ -72,17 +73,27 @@ function subagentCalled(callId: string): SubagentCalledStreamEvent {
} as SubagentCalledStreamEvent;
}
-function reasoningEvent(delta: string): HandleMessageStreamEvent {
- return {
- type: "reasoning.appended",
- data: {
- reasoningDelta: delta,
- reasoningSoFar: delta,
- sequence: 2,
- stepIndex: 0,
- turnId: "child-turn",
- },
- } as HandleMessageStreamEvent;
+function reasoningEvent(delta: string, index = 0): MessageStreamEvent {
+ return stampTestEvent(
+ {
+ type: "reasoning.appended",
+ data: {
+ reasoningDelta: delta,
+ reasoningSoFar: delta,
+ sequence: 2,
+ stepIndex: 0,
+ turnId: "child-turn",
+ },
+ } as UnstampedMessageStreamEvent,
+ index,
+ );
+}
+
+function boundaryEvent(index: number): MessageStreamEvent {
+ return stampTestEvent(
+ { type: "session.waiting", data: { wait: "next-user-message" } } as UnstampedMessageStreamEvent,
+ index,
+ );
}
async function settleAsyncWork(): Promise<void> {
@@ -100,7 +111,7 @@ describe("SubagentPump.settleAll", () => {
const pump = new SubagentPump({ client, view, formatActionResultError: () => "failed" });
pump.begin(subagentCalled("call-1"));
- child.push(reasoningEvent("**Searching for current events**"));
+ child.push(reasoningEvent("**Searching for current events**", 0));
await settleAsyncWork();
expect(view.upsertStep).toHaveBeenCalledWith(
expect.objectContaining({ callId: "call-1", finalized: false }),
@@ -115,7 +126,7 @@ describe("SubagentPump.settleAll", () => {
// A child still flushing output after the cancel paints nothing.
const updatesAfterSettle = vi.mocked(view.upsertStep).mock.calls.length;
- child.push(reasoningEvent("stale output"));
+ child.push(reasoningEvent("stale output", 1));
await settleAsyncWork();
expect(vi.mocked(view.upsertStep).mock.calls.length).toBe(updatesAfterSettle);
@@ -125,3 +136,43 @@ describe("SubagentPump.settleAll", () => {
expect(vi.mocked(view.complete).mock.calls.length).toBe(completions);
});
});
+
+describe("SubagentPump child stream replay", () => {
+ it("folds a replayed child transcript in once when the pump restarts", async () => {
+ const transcript = [reasoningEvent("looked up the forecast", 0), boundaryEvent(1)];
+ let opened = 0;
+ const client = new Client({ host: "http://localhost:3000" });
+ vi.spyOn(client, "session").mockReturnValue({
+ stream: () => {
+ opened += 1;
+ return {
+ async *[Symbol.asyncIterator]() {
+ for (const event of transcript) yield event;
+ },
+ };
+ },
+ } as never);
+ const view = fakeView();
+ const pump = new SubagentPump({ client, view, formatActionResultError: () => "failed" });
+
+ const called = subagentCalled("call-1");
+ pump.begin(called);
+ await settleAsyncWork();
+ pump.begin(called);
+ await settleAsyncWork();
+
+ expect(opened).toBe(2);
+ const reasoning = vi
+ .mocked(view.upsertStep)
+ .mock.calls.map(([update]) => update.reasoning)
+ .filter((text): text is string => text !== undefined && text.length > 0);
+ expect(reasoning.length).toBeGreaterThan(0);
+ for (const text of reasoning) {
+ expect(text).toBe("looked up the forecast");
+ }
+ const sectionKeys = new Set(
+ vi.mocked(view.upsertStep).mock.calls.map(([update]) => update.sectionKey),
+ );
+ expect(sectionKeys.size).toBe(1);
+ });
+});
diff --git a/packages/eve/src/cli/dev/tui/subagent-pump.ts b/packages/eve/src/cli/dev/tui/subagent-pump.ts
index 9fa8d4205..a7096a084 100644
--- a/packages/eve/src/cli/dev/tui/subagent-pump.ts
+++ b/packages/eve/src/cli/dev/tui/subagent-pump.ts
@@ -7,10 +7,11 @@
*/
import type { Client } from "#client/index.js";
+import { createEventDeduper, type EventDeduper } from "#protocol/event-dedupe.js";
import {
isCurrentTurnBoundaryEvent,
type ActionResultStreamEvent,
- type HandleMessageStreamEvent,
+ type MessageStreamEvent,
type SubagentCalledStreamEvent,
} from "#protocol/message.js";
import { toErrorMessage } from "#shared/errors.js";
@@ -87,6 +88,11 @@ export type SubagentRun = {
/** Monotonic counter for new section keys. */
nextSectionKey: number;
tools: Map<string, SubagentToolState>;
+ /**
+ * Child events already folded into this run. A restarted pump replays the
+ * child stream from `streamIndex: 0` while this run's state survives.
+ */
+ seenChildEvents: EventDeduper;
};
export type SubagentStepUpdate = {
@@ -134,8 +140,8 @@ export class SubagentPump {
* placeholder — subagent dispatches never upgrade one, since their
* actions are not tool-call kind). Without this the placeholder is
* swept at the step boundary and nothing shows until the child's first
- * content arrives. Idempotent for SSE-resume re-entries, which only
- * refresh the name.
+ * content arrives. A later parent-stream translator may replay the call;
+ * re-entry only refreshes the name.
*/
begin(called: SubagentCalledStreamEvent): void {
const callId = called.data.callId;
@@ -148,6 +154,7 @@ export class SubagentPump {
currentSectionKey: null,
nextSectionKey: 0,
tools: new Map(),
+ seenChildEvents: createEventDeduper(),
});
} else {
existing.name = called.data.name;
@@ -358,9 +365,10 @@ export class SubagentPump {
}
}
- #applyChildEvent(callId: string, event: HandleMessageStreamEvent) {
+ #applyChildEvent(callId: string, event: MessageStreamEvent) {
const run = this.#runs.get(callId);
if (!run) return;
+ if (!run.seenChildEvents.admit(event)) return;
// A child event after settle is a HITL-parked turn resuming: reopen the
// run explicitly (begin clears the header's Done mark) instead of
// mutating a completed section by accident.
diff --git a/packages/eve/src/cli/invoke/invoke.ts b/packages/eve/src/cli/invoke/invoke.ts
index 609a32cd2..b784275ce 100644
--- a/packages/eve/src/cli/invoke/invoke.ts
+++ b/packages/eve/src/cli/invoke/invoke.ts
@@ -2,7 +2,7 @@ import {
Client,
ClientError,
type ClientSession,
- type HandleMessageStreamEvent,
+ type MessageStreamEvent,
type SendTurnPayload,
type SessionState,
} from "#client/index.js";
@@ -136,7 +136,7 @@ async function createInvokeClient(input: RunInvokeInput): Promise<{
async function observeSafely(
input: RunInvokeInput,
session: ClientSession,
- response: AsyncIterable<HandleMessageStreamEvent>,
+ response: AsyncIterable<MessageStreamEvent>,
deploymentResolution?: VercelDeploymentResolution,
): Promise<InvokeResult> {
try {
@@ -156,7 +156,7 @@ async function observeSafely(
async function observeInvocation(
target: DevelopmentTarget,
session: ClientSession,
- response: AsyncIterable<HandleMessageStreamEvent>,
+ response: AsyncIterable<MessageStreamEvent>,
): Promise<InvokeResult> {
const summary = summarizeTurnEvents(await collectTurnEvents(response));
if (summary.boundary === undefined) return runningResult(target, session.state);
diff --git a/packages/eve/src/client/eve-agent-store.test.ts b/packages/eve/src/client/eve-agent-store.test.ts
new file mode 100644
index 000000000..60d5fd711
--- /dev/null
+++ b/packages/eve/src/client/eve-agent-store.test.ts
@@ -0,0 +1,149 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { EveAgentStore } from "#client/eve-agent-store.js";
+import { defaultMessageReducer } from "#client/message-reducer.js";
+import { stampTestEvents } from "#internal/testing/events.js";
+import {
+ createMessageCompletedEvent,
+ createMessageReceivedEvent,
+ createSessionWaitingEvent,
+ EVE_SESSION_ID_HEADER,
+ type UnstampedMessageStreamEvent,
+ type MessageStreamEvent,
+} from "#protocol/message.js";
+
+function turnEvents(): MessageStreamEvent[] {
+ return stampTestEvents([
+ createMessageReceivedEvent({ message: "Hello", sequence: 0, turnId: "turn_1" }),
+ createMessageCompletedEvent({
+ finishReason: "stop",
+ message: "Hi there.",
+ sequence: 1,
+ stepIndex: 0,
+ turnId: "turn_1",
+ }),
+ createSessionWaitingEvent("http:session_1"),
+ ] as UnstampedMessageStreamEvent[]);
+}
+
+function startedResponse(): Response {
+ return new Response(
+ JSON.stringify({ continuationToken: "http:session_1", ok: true, sessionId: "session_1" }),
+ {
+ headers: { "content-type": "application/json", [EVE_SESSION_ID_HEADER]: "session_1" },
+ status: 202,
+ },
+ );
+}
+
+function streamResponse(events: readonly MessageStreamEvent[]): Response {
+ const encoder = new TextEncoder();
+ return new Response(
+ new ReadableStream<Uint8Array>({
+ start(controller) {
+ for (const event of events) {
+ controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+ }
+ controller.close();
+ },
+ }),
+ );
+}
+
+function preV20MessageCompletedEvent(): MessageStreamEvent {
+ return {
+ ...createMessageCompletedEvent({
+ finishReason: "stop",
+ message: "Legacy response.",
+ sequence: 1,
+ stepIndex: 0,
+ turnId: "turn_legacy",
+ }),
+ meta: { at: "2026-07-27T18:04:11.912Z" },
+ } as MessageStreamEvent;
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+});
+
+describe("EveAgentStore stream overlap", () => {
+ it("folds an initialEvents prefix that the live stream re-delivers in once", async () => {
+ const events = turnEvents();
+ vi.spyOn(globalThis, "fetch")
+ .mockResolvedValueOnce(startedResponse())
+ // The server-rendered prefix is replayed ahead of the live tail.
+ .mockResolvedValueOnce(streamResponse(events));
+
+ const store = new EveAgentStore({
+ initialEvents: events.slice(0, 2),
+ reducer: defaultMessageReducer(),
+ });
+
+ const seen: MessageStreamEvent[] = [];
+ store.setCallbacks({ onEvent: (event) => seen.push(event) });
+
+ await store.send({ message: "Hello" });
+
+ // Only the events the prefix did not already carry reach subscribers.
+ expect(seen.map((event) => event.meta.id)).toEqual([events[2]?.meta.id]);
+ expect(store.snapshot.events.map((event) => event.meta.id)).toEqual(
+ events.map((event) => event.meta.id),
+ );
+
+ const assistant = store.snapshot.data.messages.filter(
+ (message) => message.role === "assistant",
+ );
+ expect(assistant).toHaveLength(1);
+ expect(assistant[0]?.parts).toEqual([
+ { type: "step-start" },
+ { state: "done", stepIndex: 0, text: "Hi there.", type: "text" },
+ ]);
+ });
+
+ it("applies a pre-v20 event whose envelope has no id", async () => {
+ const legacy = preV20MessageCompletedEvent();
+ const boundary = stampTestEvents([createSessionWaitingEvent("http:session_1")])[0]!;
+ vi.spyOn(globalThis, "fetch")
+ .mockResolvedValueOnce(startedResponse())
+ .mockResolvedValueOnce(streamResponse([legacy, boundary]));
+
+ const store = new EveAgentStore({ reducer: defaultMessageReducer() });
+ const seen: MessageStreamEvent[] = [];
+ store.setCallbacks({ onEvent: (event) => seen.push(event) });
+
+ await store.send({ message: "Hello" });
+
+ expect(seen).toEqual([legacy, boundary]);
+ expect(store.snapshot.events).toEqual([legacy, boundary]);
+ const assistant = store.snapshot.data.messages.find((message) => message.role === "assistant");
+ expect(assistant?.parts).toEqual([
+ { type: "step-start" },
+ { state: "done", stepIndex: 0, text: "Legacy response.", type: "text" },
+ ]);
+ });
+
+ it("re-admits events after reset clears the window", async () => {
+ const events = turnEvents();
+ const store = new EveAgentStore({
+ initialEvents: events,
+ reducer: defaultMessageReducer(),
+ });
+ expect(store.snapshot.events).toHaveLength(3);
+
+ store.reset();
+ expect(store.snapshot.events).toHaveLength(0);
+
+ vi.spyOn(globalThis, "fetch")
+ .mockResolvedValueOnce(startedResponse())
+ .mockResolvedValueOnce(streamResponse(events));
+
+ await store.send({ message: "Hello" });
+
+ // A fresh session must not have the retired ids held against it.
+ expect(store.snapshot.events.map((event) => event.meta.id)).toEqual(
+ events.map((event) => event.meta.id),
+ );
+ });
+});
diff --git a/packages/eve/src/client/eve-agent-store.ts b/packages/eve/src/client/eve-agent-store.ts
index 72c3e0edf..9e3e30b86 100644
--- a/packages/eve/src/client/eve-agent-store.ts
+++ b/packages/eve/src/client/eve-agent-store.ts
@@ -1,7 +1,8 @@
import { Client } from "#client/client.js";
import type { EveAgentReducer, EveAgentReducerEvent } from "#client/reducer.js";
import type { ClientSession } from "#client/session.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { createEventDeduper } from "#protocol/event-dedupe.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { toError } from "#shared/errors.js";
import type { ClientAuth, HeadersValue, SendTurnPayload, SessionState } from "#client/types.js";
import type { UserContent } from "ai";
@@ -30,7 +31,7 @@ export type PrepareSend = (input: SendTurnPayload) => SendTurnPayload | Promise<
export interface EveAgentStoreSnapshot<TData> {
readonly data: TData;
readonly error: Error | undefined;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly session: SessionState;
readonly status: EveAgentStoreStatus;
}
@@ -44,7 +45,7 @@ export interface EveAgentStoreSnapshot<TData> {
*/
export interface EveAgentStoreCallbacks<TData> {
readonly onError?: (error: Error) => void;
- readonly onEvent?: (event: HandleMessageStreamEvent) => void;
+ readonly onEvent?: (event: MessageStreamEvent) => void;
readonly onFinish?: (snapshot: EveAgentStoreSnapshot<TData>) => void;
readonly onSessionChange?: (session: SessionState) => void;
readonly prepareSend?: PrepareSend;
@@ -61,12 +62,15 @@ export interface EveAgentStoreCallbacks<TData> {
* server confirms them. `host` defaults to `""`. `initialEvents` and
* `initialSession` seed prior state on construction. Passing `session` makes
* `reset()` reuse that external session rather than create a new one.
+ * `initialEvents` must be an ordered prefix of the same session's stream; its
+ * endpoint may overlap the cursor because repeated ids are applied once.
*/
export interface EveAgentStoreInit<TData> {
readonly auth?: ClientAuth;
readonly headers?: HeadersValue;
readonly host?: string;
- readonly initialEvents?: readonly HandleMessageStreamEvent[];
+ /** Ordered prefix of the session stream used to rehydrate projected state. */
+ readonly initialEvents?: readonly MessageStreamEvent[];
readonly initialSession?: SessionState;
readonly optimistic?: boolean;
readonly reducer: EveAgentReducer<TData>;
@@ -97,11 +101,14 @@ export class EveAgentStore<TData> {
readonly #reducer: EveAgentReducer<TData>;
readonly #subscribers = new Set<() => void>();
+ /** Ids already folded into the projection: `initialEvents` and a reconnect can overlap. */
+ #seenEvents = createEventDeduper();
+
#abortController: AbortController | undefined;
#callbacks: EveAgentStoreCallbacks<TData> = {};
#data: TData;
#error: Error | undefined;
- #events: readonly HandleMessageStreamEvent[];
+ #events: readonly MessageStreamEvent[];
#operationId = 0;
#pendingMessageSubmission: PendingMessageSubmission | undefined;
#projectionEvents: readonly EveAgentReducerEvent[];
@@ -118,7 +125,13 @@ export class EveAgentStore<TData> {
headers: init.headers,
host: init.host ?? "",
}).session(init.initialSession);
- this.#events = [...(init.initialEvents ?? [])];
+ // Seed the deduper from the saved log so a live stream that replays the
+ // same prefix does not double-apply it.
+ const initialEvents: MessageStreamEvent[] = [];
+ for (const event of init.initialEvents ?? []) {
+ if (this.#seenEvents.admit(event)) initialEvents.push(event);
+ }
+ this.#events = initialEvents;
this.#projectionEvents = [...this.#events];
this.#optimistic = init.optimistic ?? true;
this.#reducer = init.reducer;
@@ -182,6 +195,10 @@ export class EveAgentStore<TData> {
this.#status = "streaming";
}
+ if (!this.#seenEvents.admit(event)) {
+ continue;
+ }
+
this.#events = [...this.#events, event];
this.#applyServerEvent(event);
this.#callbacks.onEvent?.(event);
@@ -228,6 +245,7 @@ export class EveAgentStore<TData> {
this.#abortController = undefined;
this.#session = this.#createSession?.() ?? this.#session;
this.#events = [];
+ this.#seenEvents = createEventDeduper();
this.#pendingMessageSubmission = undefined;
this.#projectionEvents = [];
this.#data = this.#reducer.initial();
@@ -293,7 +311,7 @@ export class EveAgentStore<TData> {
});
}
- #applyServerEvent(event: HandleMessageStreamEvent): void {
+ #applyServerEvent(event: MessageStreamEvent): void {
if (event.type === "message.received" && this.#pendingMessageSubmission !== undefined) {
const submissionId = this.#pendingMessageSubmission.id;
this.#pendingMessageSubmission = undefined;
@@ -309,7 +327,7 @@ export class EveAgentStore<TData> {
this.#appendProjectionEvent(event);
}
- #applyTerminalStreamFailure(event: HandleMessageStreamEvent): void {
+ #applyTerminalStreamFailure(event: MessageStreamEvent): void {
const error = toTerminalStreamFailureError(event);
if (error === undefined) {
return;
@@ -439,7 +457,7 @@ function isAbortError(error: unknown): boolean {
return error instanceof Error && error.name === "AbortError";
}
-function toTerminalStreamFailureError(event: HandleMessageStreamEvent): Error | undefined {
+function toTerminalStreamFailureError(event: MessageStreamEvent): Error | undefined {
if (event.type !== "session.failed") {
return undefined;
}
diff --git a/packages/eve/src/client/index.ts b/packages/eve/src/client/index.ts
index fa0c477b7..798a3a258 100644
--- a/packages/eve/src/client/index.ts
+++ b/packages/eve/src/client/index.ts
@@ -97,6 +97,7 @@ export type {
ConnectionAuthorizationOutcome,
AuthorizationRequiredStreamEvent,
HandleMessageStreamEvent,
+ MessageStreamEventMeta,
InputRequestedStreamEvent,
MessageAppendedStreamEvent,
MessageCompletedStreamEvent,
@@ -109,6 +110,7 @@ export type {
SessionFailedStreamEvent,
SessionStartedStreamEvent,
SessionWaitingStreamEvent,
+ MessageStreamEvent,
StepCompletedStreamEvent,
StepFailedStreamEvent,
StepStartedStreamEvent,
diff --git a/packages/eve/src/client/message-reducer.test.ts b/packages/eve/src/client/message-reducer.test.ts
index 1bde0298f..ee14f2e3a 100644
--- a/packages/eve/src/client/message-reducer.test.ts
+++ b/packages/eve/src/client/message-reducer.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { defaultMessageReducer } from "#client/message-reducer.js";
+import { stampTestEvents } from "#internal/testing/events.js";
import {
createActionResultEvent,
createActionsRequestedEvent,
@@ -14,8 +15,21 @@ import {
createResultCompletedEvent,
createStepStartedEvent,
createTurnCancelledEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
+function reduceServerEvents(
+ reducer: ReturnType<typeof defaultMessageReducer>,
+ data: ReturnType<ReturnType<typeof defaultMessageReducer>["initial"]>,
+ events: readonly UnstampedMessageStreamEvent[],
+) {
+ let next = data;
+ for (const event of stampTestEvents(events)) {
+ next = reducer.reduce(next, event);
+ }
+ return next;
+}
+
describe("defaultMessageReducer", () => {
it("projects messages, reasoning, and actions into UIMessage-compatible parts", () => {
const reducer = defaultMessageReducer();
@@ -29,17 +43,13 @@ describe("defaultMessageReducer", () => {
},
type: "client.message.submitted",
});
- data = reducer.reduce(
- data,
+ data = reduceServerEvents(reducer, data, [
createReasoningCompletedEvent({
reasoning: "Need the weather tool.",
sequence: 1,
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createActionsRequestedEvent({
actions: [
{
@@ -53,9 +63,6 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createActionResultEvent({
result: {
callId: "call_1",
@@ -67,7 +74,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -116,8 +123,7 @@ describe("defaultMessageReducer", () => {
it("projects an action result without a preceding action request", () => {
const reducer = defaultMessageReducer();
- const data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createActionResultEvent({
result: {
callId: "call_1",
@@ -129,7 +135,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -163,8 +169,7 @@ describe("defaultMessageReducer", () => {
it("projects denied tool output distinctly from generic failures", () => {
const reducer = defaultMessageReducer();
- const data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createActionResultEvent({
result: {
callId: "call_1",
@@ -179,7 +184,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -219,15 +224,14 @@ describe("defaultMessageReducer", () => {
const reducer = defaultMessageReducer();
let data = reducer.initial();
- data = reducer.reduce(
- data,
+ data = reduceServerEvents(reducer, data, [
createResultCompletedEvent({
result: { title: "Done" },
sequence: 0,
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -245,8 +249,7 @@ describe("defaultMessageReducer", () => {
it("projects authorization prompts into assistant message parts", () => {
const reducer = defaultMessageReducer();
- const data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createAuthorizationRequiredEvent({
authorization: {
expiresAt: "2026-06-26T12:00:00.000Z",
@@ -261,7 +264,7 @@ describe("defaultMessageReducer", () => {
turnId: "turn_1",
webhookUrl: "https://agent.example.com/eve/v1/connections/notion/callback/hook",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -295,8 +298,7 @@ describe("defaultMessageReducer", () => {
it("updates the pending authorization part when authorization completes", () => {
const reducer = defaultMessageReducer();
- let data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createAuthorizationRequiredEvent({
authorization: {
displayName: "Notion",
@@ -310,10 +312,6 @@ describe("defaultMessageReducer", () => {
turnId: "turn_1",
webhookUrl: "https://agent.example.com/eve/v1/connections/notion/callback/hook",
}),
- );
-
- data = reducer.reduce(
- data,
createAuthorizationCompletedEvent({
authorization: {
displayName: "Notion",
@@ -325,7 +323,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_2",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -359,8 +357,7 @@ describe("defaultMessageReducer", () => {
it("projects input requests onto tool approval parts", () => {
const reducer = defaultMessageReducer();
- const data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createInputRequestedEvent({
requests: [
{
@@ -383,7 +380,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -429,8 +426,7 @@ describe("defaultMessageReducer", () => {
it("marks input requests as responded when the client submits a response", () => {
const reducer = defaultMessageReducer();
- let data = reducer.reduce(
- reducer.initial(),
+ let data = reduceServerEvents(reducer, reducer.initial(), [
createInputRequestedEvent({
requests: [
{
@@ -453,7 +449,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
data = reducer.reduce(data, {
data: {
@@ -508,8 +504,7 @@ describe("defaultMessageReducer", () => {
it("merges resumed approval results back into the requested tool part", () => {
const reducer = defaultMessageReducer();
- let data = reducer.reduce(
- reducer.initial(),
+ let data = reduceServerEvents(reducer, reducer.initial(), [
createInputRequestedEvent({
requests: [
{
@@ -532,7 +527,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_0",
}),
- );
+ ]);
data = reducer.reduce(data, {
data: {
@@ -541,16 +536,12 @@ describe("defaultMessageReducer", () => {
},
type: "client.input.responded",
});
- data = reducer.reduce(
- data,
+ data = reduceServerEvents(reducer, data, [
createStepStartedEvent({
sequence: 1,
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createActionResultEvent({
result: {
callId: "call_1",
@@ -562,7 +553,7 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
+ ]);
const toolParts = data.messages.flatMap((message) =>
message.parts.filter((part) => part.type === "dynamic-tool"),
@@ -602,26 +593,20 @@ describe("defaultMessageReducer", () => {
it("keeps text from separate steps as separate parts", () => {
const reducer = defaultMessageReducer();
- let data = reducer.initial();
-
- data = reducer.reduce(
- data,
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createMessageCompletedEvent({
message: "First step.",
sequence: 0,
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createMessageCompletedEvent({
message: "Second step.",
sequence: 1,
stepIndex: 1,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages).toEqual([
{
@@ -657,10 +642,7 @@ describe("defaultMessageReducer", () => {
// text parts by stepIndex alone drops the first run and reorders the second
// ahead of the tool call.
const reducer = defaultMessageReducer();
- let data = reducer.initial();
-
- data = reducer.reduce(
- data,
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createMessageAppendedEvent({
messageDelta: "Checking Vienna",
messageSoFar: "Checking Vienna",
@@ -668,9 +650,6 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_0",
}),
- );
- data = reducer.reduce(
- data,
createMessageCompletedEvent({
finishReason: "tool-calls",
message: "Checking Vienna first.",
@@ -678,9 +657,6 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_0",
}),
- );
- data = reducer.reduce(
- data,
createActionsRequestedEvent({
actions: [
{
@@ -694,9 +670,6 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_0",
}),
- );
- data = reducer.reduce(
- data,
createMessageAppendedEvent({
messageDelta: "Now Berlin",
messageSoFar: "Now Berlin",
@@ -704,16 +677,13 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_0",
}),
- );
- data = reducer.reduce(
- data,
createMessageCompletedEvent({
message: "Now checking Berlin.",
sequence: 4,
stepIndex: 0,
turnId: "turn_0",
}),
- );
+ ]);
const assistant = data.messages.find((message) => message.id === "turn_0:assistant");
expect(
@@ -725,8 +695,7 @@ describe("defaultMessageReducer", () => {
it("finalizes partial streamed message and reasoning when the turn is cancelled", () => {
const reducer = defaultMessageReducer();
- let data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createReasoningAppendedEvent({
reasoningDelta: "Thinking",
reasoningSoFar: "Thinking",
@@ -734,9 +703,6 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createMessageAppendedEvent({
messageDelta: "Partial",
messageSoFar: "Partial",
@@ -744,8 +710,8 @@ describe("defaultMessageReducer", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(data, createTurnCancelledEvent({ sequence: 2, turnId: "turn_1" }));
+ createTurnCancelledEvent({ sequence: 2, turnId: "turn_1" }),
+ ]);
expect(data.messages).toEqual([
{
@@ -776,17 +742,13 @@ describe("defaultMessageReducer", () => {
it("removes streamed text for a null message completion", () => {
const reducer = defaultMessageReducer();
- let data = reducer.reduce(
- reducer.initial(),
+ const data = reduceServerEvents(reducer, reducer.initial(), [
createMessageCompletedEvent({
message: "Earlier step.",
sequence: 0,
stepIndex: 0,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createMessageAppendedEvent({
messageDelta: "<eve-empty-delivery/>",
messageSoFar: "<eve-empty-delivery/>",
@@ -794,16 +756,13 @@ describe("defaultMessageReducer", () => {
stepIndex: 1,
turnId: "turn_1",
}),
- );
- data = reducer.reduce(
- data,
createMessageCompletedEvent({
message: null,
sequence: 1,
stepIndex: 1,
turnId: "turn_1",
}),
- );
+ ]);
expect(data.messages[0]?.parts).toEqual([
{ type: "step-start" },
@@ -819,24 +778,26 @@ describe("defaultMessageReducer", () => {
it("projects structured file parts from message.received onto the user message", () => {
const reducer = defaultMessageReducer();
- const data = reducer.reduce(reducer.initial(), {
- data: {
- message: "describe this\n[file: report.pdf (application/pdf)]",
- parts: [
- { text: "describe this", type: "text" },
- {
- filename: "report.pdf",
- mediaType: "application/pdf",
- size: 4,
- type: "file",
- url: "https://files.example.com/report.pdf",
- },
- ],
- sequence: 1,
- turnId: "turn_1",
+ const data = reduceServerEvents(reducer, reducer.initial(), [
+ {
+ data: {
+ message: "describe this\n[file: report.pdf (application/pdf)]",
+ parts: [
+ { text: "describe this", type: "text" },
+ {
+ filename: "report.pdf",
+ mediaType: "application/pdf",
+ size: 4,
+ type: "file",
+ url: "https://files.example.com/report.pdf",
+ },
+ ],
+ sequence: 1,
+ turnId: "turn_1",
+ },
+ type: "message.received",
},
- type: "message.received",
- });
+ ]);
const userMessage = data.messages.find((message) => message.role === "user");
expect(userMessage?.parts).toEqual([
@@ -853,10 +814,12 @@ describe("defaultMessageReducer", () => {
it("falls back to a single text part when message.received omits parts", () => {
const reducer = defaultMessageReducer();
- const data = reducer.reduce(reducer.initial(), {
- data: { message: "hello there", sequence: 1, turnId: "turn_1" },
- type: "message.received",
- });
+ const data = reduceServerEvents(reducer, reducer.initial(), [
+ {
+ data: { message: "hello there", sequence: 1, turnId: "turn_1" },
+ type: "message.received",
+ },
+ ]);
const userMessage = data.messages.find((message) => message.role === "user");
expect(userMessage?.parts).toEqual([{ state: "done", text: "hello there", type: "text" }]);
diff --git a/packages/eve/src/client/message-response.ts b/packages/eve/src/client/message-response.ts
index 544a76fbb..f8c68392c 100644
--- a/packages/eve/src/client/message-response.ts
+++ b/packages/eve/src/client/message-response.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { extractCompletedResult } from "#client/output-schema.js";
import { summarizeTurnEvents } from "#client/session-utils.js";
import type { MessageResult } from "#client/types.js";
@@ -8,7 +8,7 @@ import type { MessageResult } from "#client/types.js";
*/
interface MessageResponseInput {
readonly continuationToken?: string;
- readonly createStream: () => AsyncGenerator<HandleMessageStreamEvent>;
+ readonly createStream: () => AsyncGenerator<MessageStreamEvent>;
readonly sessionId: string;
}
@@ -19,7 +19,7 @@ interface MessageResponseInput {
* token) as soon as the POST completes. Collect the event stream via
* {@link result} or iterate it with `for await...of`.
*/
-export class MessageResponse<TOutput = unknown> implements AsyncIterable<HandleMessageStreamEvent> {
+export class MessageResponse<TOutput = unknown> implements AsyncIterable<MessageStreamEvent> {
/**
* Continuation token returned by the server for follow-up messages.
*/
@@ -31,7 +31,7 @@ export class MessageResponse<TOutput = unknown> implements AsyncIterable<HandleM
readonly sessionId: string;
#consumed = false;
- readonly #createStream: () => AsyncGenerator<HandleMessageStreamEvent>;
+ readonly #createStream: () => AsyncGenerator<MessageStreamEvent>;
/** @internal */
constructor(input: MessageResponseInput) {
@@ -45,7 +45,7 @@ export class MessageResponse<TOutput = unknown> implements AsyncIterable<HandleM
* {@link MessageResult}.
*/
async result(): Promise<MessageResult<TOutput>> {
- const events: HandleMessageStreamEvent[] = [];
+ const events: MessageStreamEvent[] = [];
for await (const event of this) {
events.push(event);
@@ -67,7 +67,7 @@ export class MessageResponse<TOutput = unknown> implements AsyncIterable<HandleM
*
* Each response can only be consumed once.
*/
- [Symbol.asyncIterator](): AsyncIterator<HandleMessageStreamEvent> {
+ [Symbol.asyncIterator](): AsyncIterator<MessageStreamEvent> {
if (this.#consumed) {
throw new Error("MessageResponse has already been consumed.");
}
diff --git a/packages/eve/src/client/ndjson.ts b/packages/eve/src/client/ndjson.ts
index 3187a369a..317c391c1 100644
--- a/packages/eve/src/client/ndjson.ts
+++ b/packages/eve/src/client/ndjson.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
/**
* Returns true when an error looks like a stream socket disconnection that
@@ -27,7 +27,7 @@ export function isStreamDisconnectError(error: unknown): boolean {
/**
* Reads newline-delimited JSON events from a `ReadableStream<Uint8Array>`.
*
- * Yields one parsed {@link HandleMessageStreamEvent} per complete NDJSON line.
+ * Yields one parsed {@link MessageStreamEvent} per complete NDJSON line.
* Handles partial lines across chunks via an internal buffer.
*
* All read errors — including socket disconnections — propagate to the caller.
@@ -35,7 +35,7 @@ export function isStreamDisconnectError(error: unknown): boolean {
*/
export async function* readNdjsonStream(
body: ReadableStream<Uint8Array>,
-): AsyncGenerator<HandleMessageStreamEvent> {
+): AsyncGenerator<MessageStreamEvent> {
const reader = body.getReader();
const decoder = new TextDecoder();
let buffer = "";
@@ -63,7 +63,7 @@ export async function* readNdjsonStream(
buffer = buffer.slice(newlineIndex + 1);
if (line.length > 0) {
- yield JSON.parse(line) as HandleMessageStreamEvent;
+ yield JSON.parse(line) as MessageStreamEvent;
}
newlineIndex = buffer.indexOf("\n");
@@ -73,7 +73,7 @@ export async function* readNdjsonStream(
// Yield any trailing content without a final newline.
const trailing = buffer.trim();
if (trailing.length > 0) {
- yield JSON.parse(trailing) as HandleMessageStreamEvent;
+ yield JSON.parse(trailing) as MessageStreamEvent;
}
} finally {
if (!reachedEof) {
diff --git a/packages/eve/src/client/open-stream.ts b/packages/eve/src/client/open-stream.ts
index c3039b443..1637b435c 100644
--- a/packages/eve/src/client/open-stream.ts
+++ b/packages/eve/src/client/open-stream.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { EVE_STREAM_TAIL_INDEX_HEADER } from "#protocol/message.js";
import { createEveMessageStreamRoutePath } from "#protocol/routes.js";
import { ClientError } from "#client/client-error.js";
@@ -106,7 +106,7 @@ interface OpenStreamInput extends FollowStreamInput {
*/
export async function* followStreamIterable(
input: FollowStreamInput,
-): AsyncGenerator<HandleMessageStreamEvent> {
+): AsyncGenerator<MessageStreamEvent> {
if (input.follow === false && input.startIndex < 0) {
throw new Error(
"stream({ follow: false }) requires a nonnegative startIndex; a tail-relative cursor cannot be bounded.",
diff --git a/packages/eve/src/client/output-schema.test.ts b/packages/eve/src/client/output-schema.test.ts
index ad2bd0fe7..41edb9a32 100644
--- a/packages/eve/src/client/output-schema.test.ts
+++ b/packages/eve/src/client/output-schema.test.ts
@@ -4,12 +4,12 @@ import { extractCompletedResult } from "#client/output-schema.js";
import {
createResultCompletedEvent,
createTurnCompletedEvent,
- type HandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
describe("output schema client helpers", () => {
it("extracts the most recent completed structured result", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
createResultCompletedEvent({
result: { title: "First" },
sequence: 0,
diff --git a/packages/eve/src/client/output-schema.ts b/packages/eve/src/client/output-schema.ts
index f0e48cbde..f0c65cfab 100644
--- a/packages/eve/src/client/output-schema.ts
+++ b/packages/eve/src/client/output-schema.ts
@@ -1,10 +1,10 @@
-import type { HandleMessageStreamEvent, ResultCompletedStreamEvent } from "#protocol/message.js";
+import type { ResultCompletedStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";
/**
* Extracts the most recent finalized structured result from a turn event list.
*/
export function extractCompletedResult<TOutput>(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly UnstampedMessageStreamEvent[],
): TOutput | undefined {
let result: TOutput | undefined;
@@ -18,7 +18,7 @@ export function extractCompletedResult<TOutput>(
}
function isResultCompletedEvent(
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
): event is ResultCompletedStreamEvent {
return event.type === "result.completed";
}
diff --git a/packages/eve/src/client/reducer.ts b/packages/eve/src/client/reducer.ts
index e2c745775..1318cb588 100644
--- a/packages/eve/src/client/reducer.ts
+++ b/packages/eve/src/client/reducer.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { InputResponse } from "#runtime/input/types.js";
/**
@@ -55,7 +55,7 @@ export type EveAgentReducerEvent =
| ClientInputRespondedEvent
| ClientMessageFailedEvent
| ClientMessageSubmittedEvent
- | HandleMessageStreamEvent;
+ | MessageStreamEvent;
/**
* Projects eve stream events into accumulated consumer data.
diff --git a/packages/eve/src/client/session-utils.test.ts b/packages/eve/src/client/session-utils.test.ts
index a7fe1283c..c12e3909d 100644
--- a/packages/eve/src/client/session-utils.test.ts
+++ b/packages/eve/src/client/session-utils.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { collectTurnEvents, summarizeTurnEvents } from "./session-utils.js";
@@ -35,7 +35,7 @@ describe("summarizeTurnEvents", () => {
type: "session.waiting",
data: { continuationToken: "eve:next", wait: "next-user-message" },
},
- ] satisfies HandleMessageStreamEvent[];
+ ] satisfies UnstampedMessageStreamEvent[];
expect(summarizeTurnEvents(events)).toMatchObject({
boundary: { type: "session.waiting" },
@@ -66,7 +66,7 @@ describe("summarizeTurnEvents", () => {
type: "session.waiting",
data: { continuationToken: "eve:next", wait: "next-user-message" },
},
- ] satisfies HandleMessageStreamEvent[];
+ ] satisfies UnstampedMessageStreamEvent[];
expect(summarizeTurnEvents(events)).toMatchObject({
failure: { type: "turn.failed", data: { message: "Unavailable" } },
@@ -78,7 +78,7 @@ describe("summarizeTurnEvents", () => {
describe("collectTurnEvents", () => {
it("stops at the current-turn boundary", async () => {
- async function* stream(): AsyncGenerator<HandleMessageStreamEvent> {
+ async function* stream(): AsyncGenerator<UnstampedMessageStreamEvent> {
yield {
type: "session.waiting",
data: { continuationToken: "eve:next", wait: "next-user-message" },
diff --git a/packages/eve/src/client/session-utils.ts b/packages/eve/src/client/session-utils.ts
index ce87cd625..708a36d6f 100644
--- a/packages/eve/src/client/session-utils.ts
+++ b/packages/eve/src/client/session-utils.ts
@@ -1,8 +1,8 @@
import type {
AuthorizationRequiredStreamEvent,
- HandleMessageStreamEvent,
MessageCompletedStreamEvent,
TurnFailureStreamEvent,
+ UnstampedMessageStreamEvent,
} from "#protocol/message.js";
import { isCurrentTurnBoundaryEvent, isTurnFailureEvent } from "#protocol/message.js";
import type { SessionState } from "#client/types.js";
@@ -25,7 +25,7 @@ export function createInitialSessionState(): SessionState {
*/
export function advanceSession(input: {
readonly continuationToken?: string;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly UnstampedMessageStreamEvent[];
readonly preserveCompletedSessions?: boolean;
readonly sessionId: string;
readonly session: SessionState;
@@ -68,7 +68,7 @@ export interface PendingAuthorization {
/** Canonical projection of the lifecycle state represented by one turn's events. */
export interface TurnEventSummary {
- readonly boundary: HandleMessageStreamEvent | undefined;
+ readonly boundary: UnstampedMessageStreamEvent | undefined;
readonly failure: TurnFailureStreamEvent | undefined;
readonly inputRequests: readonly InputRequest[];
readonly message: string | undefined;
@@ -77,8 +77,10 @@ export interface TurnEventSummary {
}
/** Reduces one turn's protocol events into their client-facing lifecycle state. */
-export function summarizeTurnEvents(events: readonly HandleMessageStreamEvent[]): TurnEventSummary {
- let boundary: HandleMessageStreamEvent | undefined;
+export function summarizeTurnEvents(
+ events: readonly UnstampedMessageStreamEvent[],
+): TurnEventSummary {
+ let boundary: UnstampedMessageStreamEvent | undefined;
let failure: TurnFailureStreamEvent | undefined;
let message: string | undefined;
const inputRequests: InputRequest[] = [];
@@ -114,9 +116,9 @@ export function summarizeTurnEvents(events: readonly HandleMessageStreamEvent[])
/** Collects one segment of an event stream through its current-turn boundary. */
export async function collectTurnEvents(
- stream: AsyncIterable<HandleMessageStreamEvent>,
-): Promise<readonly HandleMessageStreamEvent[]> {
- const events: HandleMessageStreamEvent[] = [];
+ stream: AsyncIterable<UnstampedMessageStreamEvent>,
+): Promise<readonly UnstampedMessageStreamEvent[]> {
+ const events: UnstampedMessageStreamEvent[] = [];
for await (const event of stream) {
events.push(event);
if (isCurrentTurnBoundaryEvent(event)) break;
@@ -125,8 +127,8 @@ export async function collectTurnEvents(
}
function findBoundaryEvent(
- events: readonly HandleMessageStreamEvent[],
-): HandleMessageStreamEvent | undefined {
+ events: readonly UnstampedMessageStreamEvent[],
+): UnstampedMessageStreamEvent | undefined {
for (let i = events.length - 1; i >= 0; i--) {
const event = events[i];
if (event !== undefined && isCurrentTurnBoundaryEvent(event)) return event;
@@ -135,7 +137,7 @@ function findBoundaryEvent(
}
function isFinalMessageCompleted(
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
): event is MessageCompletedStreamEvent {
return event.type === "message.completed" && event.data.finishReason !== "tool-calls";
}
diff --git a/packages/eve/src/client/session.ts b/packages/eve/src/client/session.ts
index 0880cdd58..c1f92cde8 100644
--- a/packages/eve/src/client/session.ts
+++ b/packages/eve/src/client/session.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { EVE_SESSION_ID_HEADER, isCurrentTurnBoundaryEvent } from "#protocol/message.js";
import { CancelTurnResponseSchema } from "#protocol/cancel-turn.js";
import { ResetResponseSchema } from "#protocol/reset-session.js";
@@ -236,7 +236,7 @@ export class ClientSession {
* @throws {Error} If the session has no session ID (no message has been sent
* yet), or if `follow: false` is combined with a negative `startIndex`.
*/
- stream(options?: StreamOptions): AsyncIterable<HandleMessageStreamEvent> {
+ stream(options?: StreamOptions): AsyncIterable<MessageStreamEvent> {
const sessionId = this.#state.sessionId;
if (!sessionId) {
@@ -312,8 +312,8 @@ export class ClientSession {
continuationToken: string | undefined,
initialState: SessionState,
input: SendTurnPayload,
- ): AsyncGenerator<HandleMessageStreamEvent> {
- const events: HandleMessageStreamEvent[] = [];
+ ): AsyncGenerator<MessageStreamEvent> {
+ const events: MessageStreamEvent[] = [];
try {
for await (const event of followStreamIterable({
@@ -346,10 +346,10 @@ export class ClientSession {
async *#streamAndAdvance(
sessionId: string,
options?: StreamOptions,
- ): AsyncGenerator<HandleMessageStreamEvent> {
+ ): AsyncGenerator<MessageStreamEvent> {
const initialState = this.#state;
const streamIndex = options?.startIndex ?? initialState.streamIndex;
- const events: HandleMessageStreamEvent[] = [];
+ const events: MessageStreamEvent[] = [];
try {
for await (const event of followStreamIterable({
diff --git a/packages/eve/src/client/types.ts b/packages/eve/src/client/types.ts
index ae278ab05..d95a91fce 100644
--- a/packages/eve/src/client/types.ts
+++ b/packages/eve/src/client/types.ts
@@ -1,7 +1,7 @@
import type { UserContent } from "ai";
import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { CancelTurnStatus } from "#protocol/cancel-turn.js";
import type { ResetStatus } from "#protocol/reset-session.js";
import type { InputRequest, InputResponse } from "#runtime/input/types.js";
@@ -269,7 +269,7 @@ export interface MessageResult<TOutput = unknown> {
/**
* All events received during this turn.
*/
- readonly events: HandleMessageStreamEvent[];
+ readonly events: MessageStreamEvent[];
/**
* HITL input requests emitted during this turn.
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index fd3151903..8f44e6ecf 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -22,13 +22,13 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
tool: { current: 3, supported: [1, 2, 3], dropped: {} },
- dynamicTool: { current: 4, supported: [1, 2, 3, 4], dropped: {} },
+ dynamicTool: { current: 5, supported: [1, 2, 3, 4, 5], dropped: {} },
connection: { current: 2, supported: [1, 2], dropped: {} },
- hook: { current: 2, supported: [1, 2], dropped: {} },
+ hook: { current: 3, supported: [1, 2, 3], dropped: {} },
skill: { current: 1, supported: [1], dropped: {} },
- dynamicSkill: { current: 1, supported: [1], dropped: {} },
+ dynamicSkill: { current: 2, supported: [1, 2], dropped: {} },
instructions: { current: 1, supported: [1], dropped: {} },
- dynamicInstructions: { current: 1, supported: [1], dropped: {} },
+ dynamicInstructions: { current: 2, supported: [1, 2], dropped: {} },
config: { current: 1, supported: [1], dropped: {} },
state: { current: 2, supported: [1, 2], dropped: {} },
} as const satisfies Record<string, ExtensionCapabilityContract>;
diff --git a/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts b/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts
index 17869dfcf..c13f11abe 100644
--- a/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-instruction-lifecycle.test.ts
@@ -18,7 +18,7 @@ import {
SessionIdKey,
} from "#context/keys.js";
import type { ResolvedDynamicInstructionsResolver } from "#runtime/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
function createResolver(
slug: string,
@@ -45,8 +45,8 @@ function createCtx(): ContextContainer {
return ctx;
}
-function makeEvent(type: string): HandleMessageStreamEvent {
- return { type, data: {} } as HandleMessageStreamEvent;
+function makeEvent(type: string): UnstampedMessageStreamEvent {
+ return { type, data: {} } as UnstampedMessageStreamEvent;
}
describe("dispatchDynamicInstructionEvent", () => {
diff --git a/packages/eve/src/context/dynamic-instruction-lifecycle.ts b/packages/eve/src/context/dynamic-instruction-lifecycle.ts
index d19f928ef..54646273b 100644
--- a/packages/eve/src/context/dynamic-instruction-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-instruction-lifecycle.ts
@@ -5,7 +5,7 @@ import {
isBrandedInstructionsEntry,
} from "#shared/dynamic-tool-definition.js";
import type { InstructionsDefinition } from "#public/definitions/instructions.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { ResolvedDynamicInstructionsResolver } from "#runtime/types.js";
import { createLogger } from "#internal/logging.js";
import { toErrorMessage } from "#shared/errors.js";
@@ -58,7 +58,7 @@ export function buildDynamicInstructionMessages(ctx: {
export async function dispatchDynamicInstructionEvent(input: {
readonly ctx: ContextContainer;
readonly resolvers: readonly ResolvedDynamicInstructionsResolver[];
- readonly event: HandleMessageStreamEvent;
+ readonly event: UnstampedMessageStreamEvent;
readonly messages: readonly ModelMessage[];
}): Promise<void> {
const { ctx, resolvers, event, messages } = input;
diff --git a/packages/eve/src/context/dynamic-model-lifecycle.ts b/packages/eve/src/context/dynamic-model-lifecycle.ts
index 4b9366d0a..76e4886b2 100644
--- a/packages/eve/src/context/dynamic-model-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-model-lifecycle.ts
@@ -10,7 +10,7 @@ import {
type LiveDynamicModelSelection,
} from "#context/keys.js";
import { createLogger } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type {
RuntimeDynamicModelReference,
RuntimeModelReference,
@@ -76,7 +76,7 @@ export function getActiveDynamicModelSelection(ctx: {
export async function dispatchDynamicModelEvent(input: {
readonly ctx: AlsContext;
readonly dynamicModel: RuntimeDynamicModelReference | undefined;
- readonly event: HandleMessageStreamEvent;
+ readonly event: UnstampedMessageStreamEvent;
readonly fallback: RuntimeModelReference;
readonly messages: readonly ModelMessage[];
readonly scope: RuntimeModelResolutionScope;
diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts b/packages/eve/src/context/dynamic-skill-lifecycle.test.ts
index a2cf12f65..7c7b938e5 100644
--- a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-skill-lifecycle.test.ts
@@ -7,7 +7,7 @@ import {
} from "#context/dynamic-skill-lifecycle.js";
import { DynamicSkillManifestKey, SessionIdKey, SandboxKey } from "#context/keys.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { defineSkill } from "#public/definitions/skill.js";
import { BundleKey, type CompiledBundle } from "#runtime/sessions/runtime-context-keys.js";
import type { ResolvedDynamicSkillResolver } from "#runtime/types.js";
@@ -69,8 +69,8 @@ function createResolver(
};
}
-function makeEvent(): HandleMessageStreamEvent {
- return { type: "session.started", data: {} } as HandleMessageStreamEvent;
+function makeEvent(): UnstampedMessageStreamEvent {
+ return { type: "session.started", data: {} } as UnstampedMessageStreamEvent;
}
function makeSkill(description: string, markdown = description): SkillPackageDefinition {
diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.ts b/packages/eve/src/context/dynamic-skill-lifecycle.ts
index 26b730745..1861bb100 100644
--- a/packages/eve/src/context/dynamic-skill-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-skill-lifecycle.ts
@@ -11,7 +11,7 @@ import {
removeSkillPackageFromSandbox,
writeSkillPackageToSandbox,
} from "#shared/skill-package.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { ResolvedDynamicSkillResolver } from "#runtime/types.js";
import { formatAvailableSkillsSection } from "#execution/skills/instructions.js";
import { createLogger } from "#internal/logging.js";
@@ -109,7 +109,7 @@ export const PendingSkillAnnouncementKey = new ContextKey<string>("eve.pendingSk
export async function dispatchDynamicSkillEvent(input: {
readonly ctx: ContextContainer;
readonly resolvers: readonly ResolvedDynamicSkillResolver[];
- readonly event: HandleMessageStreamEvent;
+ readonly event: UnstampedMessageStreamEvent;
readonly messages: readonly ModelMessage[];
}): Promise<void> {
const { ctx, resolvers, event, messages } = input;
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index 0f68218e5..335cadf61 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
@@ -29,7 +29,7 @@ import {
TurnDynamicToolMetadataKey,
} from "#context/keys.js";
import type { ResolvedDynamicToolResolver } from "#runtime/types.js";
-import { createSessionStartedEvent, type HandleMessageStreamEvent } from "#protocol/message.js";
+import { createSessionStartedEvent, type UnstampedMessageStreamEvent } from "#protocol/message.js";
// Re-implement the naming logic here to test it independently
// (the production function is unexported — testing via the public behavior)
@@ -472,8 +472,8 @@ function createApprovalContext(input: {
} as ApprovalContext;
}
-function makeEvent(type: string): HandleMessageStreamEvent {
- return { type, data: {} } as HandleMessageStreamEvent;
+function makeEvent(type: string): UnstampedMessageStreamEvent {
+ return { type, data: {} } as UnstampedMessageStreamEvent;
}
const registrySym = Symbol.for("@workflow/core//registeredSteps");
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.ts
index 8905064eb..5b05c591b 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts
@@ -3,7 +3,7 @@ import type { ModelMessage } from "ai";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { ApprovalContext } from "#public/definitions/approval.js";
import type { DynamicToolEntry } from "#shared/dynamic-tool-definition.js";
-import type { HandleMessageStreamEvent, SessionStartedStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent, SessionStartedStreamEvent } from "#protocol/message.js";
import {
ALLOWED_DYNAMIC_TOOL_EVENTS,
isBrandedToolEntry,
@@ -205,7 +205,7 @@ interface ResolveResult {
async function resolveToolsFromEvent(
ctx: ContextContainer,
resolvers: readonly ResolvedDynamicToolResolver[],
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
messages: readonly ModelMessage[],
): Promise<ResolveResult> {
const outcomes = await Promise.allSettled(
@@ -332,7 +332,7 @@ async function resolveToolsFromEvent(
export async function dispatchDynamicToolEvent(input: {
readonly ctx: ContextContainer;
readonly resolvers: readonly ResolvedDynamicToolResolver[];
- readonly event: HandleMessageStreamEvent;
+ readonly event: UnstampedMessageStreamEvent;
readonly messages: readonly ModelMessage[];
}): Promise<void> {
const { ctx, resolvers, event, messages } = input;
diff --git a/packages/eve/src/context/hook-lifecycle.integration.test.ts b/packages/eve/src/context/hook-lifecycle.integration.test.ts
index d52f33aca..22395cebe 100644
--- a/packages/eve/src/context/hook-lifecycle.integration.test.ts
+++ b/packages/eve/src/context/hook-lifecycle.integration.test.ts
@@ -2,7 +2,8 @@ import { describe, expect, it } from "vitest";
import { createRuntimeHookRegistry } from "#runtime/hooks/registry.js";
import type { ResolvedHookDefinition } from "#runtime/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import { stampTestEvent } from "#internal/testing/events.js";
import { ContextContainer, contextStorage } from "./container.js";
import { dispatchStreamEventHooks } from "./hook-lifecycle.js";
import {
@@ -66,7 +67,7 @@ describe("dispatchStreamEventHooks", () => {
hook("metrics", {
events: {
"*": async (event) => {
- calls.push(`wildcard:${(event as HandleMessageStreamEvent).type}`);
+ calls.push(`wildcard:${(event as UnstampedMessageStreamEvent).type}`);
},
},
}),
@@ -77,7 +78,7 @@ describe("dispatchStreamEventHooks", () => {
dispatchStreamEventHooks({
ctx,
registry,
- event: { type: "session.completed" } satisfies HandleMessageStreamEvent,
+ event: stampTestEvent({ type: "session.completed" }),
}),
);
expect(calls).toEqual(["typed", "wildcard:session.completed"]);
@@ -96,7 +97,7 @@ describe("dispatchStreamEventHooks", () => {
dispatchStreamEventHooks({
ctx,
registry: brokenRegistry,
- event: { type: "session.completed" } satisfies HandleMessageStreamEvent,
+ event: stampTestEvent({ type: "session.completed" }),
}),
),
).rejects.toThrow(/event hook boom/);
diff --git a/packages/eve/src/context/hook-lifecycle.ts b/packages/eve/src/context/hook-lifecycle.ts
index ea6ead904..70f2655ea 100644
--- a/packages/eve/src/context/hook-lifecycle.ts
+++ b/packages/eve/src/context/hook-lifecycle.ts
@@ -1,5 +1,5 @@
import { getAdapterKind } from "#channel/adapter.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { HookContext } from "#public/definitions/hook.js";
import type { RuntimeHookRegistry } from "#runtime/hooks/registry.js";
import { buildCallbackContext } from "#context/build-callback-context.js";
@@ -16,7 +16,7 @@ import { ContinuationTokenKey } from "./keys.js";
export async function dispatchStreamEventHooks(input: {
readonly ctx: ContextContainer;
readonly registry: RuntimeHookRegistry;
- readonly event: HandleMessageStreamEvent;
+ readonly event: MessageStreamEvent;
}): Promise<void> {
const typed = input.registry.streamEventsByType.get(input.event.type) ?? [];
const wildcard = input.registry.streamEventsWildcard;
diff --git a/packages/eve/src/evals/assertions/run.test.ts b/packages/eve/src/evals/assertions/run.test.ts
index 87950f584..403b30bb9 100644
--- a/packages/eve/src/evals/assertions/run.test.ts
+++ b/packages/eve/src/evals/assertions/run.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import { stampTestEvents } from "#internal/testing/events.js";
import { createEmptyDerivedFacts } from "#evals/runner/derive-run-facts.js";
import type {
EveEvalDerivedFacts,
@@ -12,7 +13,7 @@ import * as Run from "#evals/assertions/run.js";
function makeResult(overrides: {
status?: EveEvalTaskResult["status"];
- events?: readonly HandleMessageStreamEvent[];
+ events?: readonly UnstampedMessageStreamEvent[];
derived?: Partial<EveEvalDerivedFacts>;
output?: unknown;
}): EveEvalTaskResult {
@@ -20,7 +21,7 @@ function makeResult(overrides: {
output: overrides.output ?? null,
finalMessage: null,
status: overrides.status ?? "completed",
- events: overrides.events ?? [],
+ events: stampTestEvents(overrides.events ?? []),
derived: { ...createEmptyDerivedFacts(), ...overrides.derived },
};
}
@@ -44,16 +45,16 @@ function subagentCall(name: string, status: EveEvalSubagentCall["status"]): EveE
};
}
-function message(text: string): HandleMessageStreamEvent {
+function message(text: string): UnstampedMessageStreamEvent {
return {
type: "message.completed",
data: { finishReason: "stop", message: text, sequence: 1, stepIndex: 0, turnId: "t1" },
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent;
}
function actionsRequested(
actions: readonly { readonly callId: string; readonly toolName: string }[],
-): HandleMessageStreamEvent {
+): UnstampedMessageStreamEvent {
return {
type: "actions.requested",
data: {
@@ -65,7 +66,7 @@ function actionsRequested(
};
}
-function actionResult(callId: string, toolName: string): HandleMessageStreamEvent {
+function actionResult(callId: string, toolName: string): UnstampedMessageStreamEvent {
return {
type: "action.result",
data: {
@@ -82,7 +83,7 @@ function failedSubagentResult(input: {
callId: string;
output: unknown;
subagentName: string;
-}): HandleMessageStreamEvent {
+}): UnstampedMessageStreamEvent {
return {
type: "action.result",
data: {
@@ -124,7 +125,7 @@ describe("run assertions", () => {
stepIndex: 0,
turnId: "t1",
},
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent;
expect(
(await Run.succeeded().evaluate(makeResult({ status: "completed", events: [failedEvent] })))
@@ -323,11 +324,11 @@ describe("run assertions", () => {
turnId: "t",
workflowId: "w",
},
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent;
const completed = {
type: "subagent.completed",
data: { callId: "c", output: "ok", sequence: 2, subagentName: "child", turnId: "t" },
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent;
const result = makeResult({ events: [called, called, completed] });
expect(
@@ -396,11 +397,11 @@ describe("run assertions", () => {
turnId: "t",
workflowId: "w",
},
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent;
const completed = {
type: "subagent.completed",
data: { callId: "c", output: "ok", sequence: 2, subagentName: "child", turnId: "t" },
- } as HandleMessageStreamEvent;
+ } as UnstampedMessageStreamEvent;
const result = makeResult({ events: [called, completed, called] });
expect(
diff --git a/packages/eve/src/evals/assertions/run.ts b/packages/eve/src/evals/assertions/run.ts
index b51eae7cd..d908c208a 100644
--- a/packages/eve/src/evals/assertions/run.ts
+++ b/packages/eve/src/evals/assertions/run.ts
@@ -1,5 +1,5 @@
import type { StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import {
deepEquals,
eventMatches,
@@ -18,7 +18,7 @@ import type { AssertionOutcome, RunAssertion } from "#evals/assertions/collector
/** Minimal captured scope consumed by deterministic eval assertions. */
export interface EveEvalAssertionSubject {
readonly derived: import("#evals/types.js").EveEvalDerivedFacts;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly output: unknown;
readonly status: "completed" | "failed" | "waiting";
}
@@ -204,7 +204,7 @@ export function noFailedActions(): RunAssertion {
name: "noFailedActions",
evaluate(result) {
const failed = result.events.filter(
- (evt): evt is Extract<HandleMessageStreamEvent, { type: "action.result" }> =>
+ (evt): evt is Extract<MessageStreamEvent, { type: "action.result" }> =>
evt.type === "action.result" &&
(evt.data.status === "failed" || evt.data.result.isError === true),
);
@@ -263,7 +263,7 @@ export function calledSubagent(
*/
export function eventsSatisfy(
label: string,
- predicate: (events: readonly HandleMessageStreamEvent[]) => boolean,
+ predicate: (events: readonly MessageStreamEvent[]) => boolean,
): RunAssertion {
return {
name: `eventsSatisfy(${label})`,
@@ -364,7 +364,7 @@ export function outputMatches(schema: StandardSchemaV1): RunAssertion {
};
}
-function joinCompletedMessages(events: readonly HandleMessageStreamEvent[]): string {
+function joinCompletedMessages(events: readonly MessageStreamEvent[]): string {
const parts: string[] = [];
for (const evt of events) {
if (evt.type === "message.completed" && evt.data.message !== null) {
@@ -379,7 +379,7 @@ function failureDetail(prefix: string, code: string | undefined): string {
}
function formatFailedActionResult(
- event: Extract<HandleMessageStreamEvent, { type: "action.result" }>,
+ event: Extract<MessageStreamEvent, { type: "action.result" }>,
): string {
const { result, status } = event.data;
const parts = [
@@ -394,7 +394,7 @@ function formatFailedActionResult(
}
function actionResultLabel(
- result: Extract<HandleMessageStreamEvent, { type: "action.result" }>["data"]["result"],
+ result: Extract<MessageStreamEvent, { type: "action.result" }>["data"]["result"],
): string {
switch (result.kind) {
case "tool-result":
@@ -411,7 +411,7 @@ function runFailure(result: EveEvalAssertionSubject): AssertionOutcome | undefin
return fail(failureDetail("run failed", result.derived.failureCode));
}
const failedEvent = result.events.find(
- (event): event is Extract<HandleMessageStreamEvent, { type: "step.failed" | "turn.failed" }> =>
+ (event): event is Extract<MessageStreamEvent, { type: "step.failed" | "turn.failed" }> =>
event.type === "turn.failed" || event.type === "step.failed",
);
return failedEvent === undefined
@@ -471,7 +471,7 @@ interface ToolRequestEntry {
readonly name: string;
}
-function requestedTools(events: readonly HandleMessageStreamEvent[]): readonly ToolRequestEntry[] {
+function requestedTools(events: readonly MessageStreamEvent[]): readonly ToolRequestEntry[] {
const entries: ToolRequestEntry[] = [];
const seenCallIds = new Set<string>();
const append = (callId: string, name: string): void => {
diff --git a/packages/eve/src/evals/match.ts b/packages/eve/src/evals/match.ts
index a2a24c4cc..e7a63547a 100644
--- a/packages/eve/src/evals/match.ts
+++ b/packages/eve/src/evals/match.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { InputRequest } from "#runtime/input/types.js";
import type { JsonObject, JsonValue } from "#shared/json.js";
import type { EveEvalSubagentCall, EveEvalToolCall } from "#evals/types.js";
@@ -88,16 +88,14 @@ export interface EveEvalInputRequestMatchOptions {
/** One typed stream-event matcher used by scoped event assertions. */
export type EveEvalEventMatch<
- TType extends HandleMessageStreamEvent["type"] = HandleMessageStreamEvent["type"],
-> = TType extends HandleMessageStreamEvent["type"]
+ TType extends MessageStreamEvent["type"] = MessageStreamEvent["type"],
+> = TType extends MessageStreamEvent["type"]
? {
/** Stream-event type to match. */
readonly type: TType;
/** Partial-deep matcher over the event data. */
readonly data?: EveEvalDeepMatcher<
- Extract<HandleMessageStreamEvent, { type: TType }> extends { data: infer TData }
- ? TData
- : never
+ Extract<MessageStreamEvent, { type: TType }> extends { data: infer TData } ? TData : never
>;
/** Constraint over the matching event count. Defaults to "at least one". */
readonly count?: EveEvalCountMatcher;
@@ -199,7 +197,7 @@ export function inputRequestMatches(
}
/** Returns true when one stream event satisfies a typed event matcher. */
-export function eventMatches(event: HandleMessageStreamEvent, matcher: EveEvalEventMatch): boolean {
+export function eventMatches(event: MessageStreamEvent, matcher: EveEvalEventMatch): boolean {
return (
event.type === matcher.type &&
(matcher.data === undefined ||
diff --git a/packages/eve/src/evals/runner/derive-run-facts.test.ts b/packages/eve/src/evals/runner/derive-run-facts.test.ts
index c3d2c7d6d..af0838926 100644
--- a/packages/eve/src/evals/runner/derive-run-facts.test.ts
+++ b/packages/eve/src/evals/runner/derive-run-facts.test.ts
@@ -1,16 +1,30 @@
import { describe, expect, it } from "vitest";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { JsonObject } from "#shared/json.js";
-import { createEmptyDerivedFacts, deriveRunFacts } from "#evals/runner/derive-run-facts.js";
+import { stampTestEvents } from "#internal/testing/events.js";
+import {
+ createEmptyDerivedFacts,
+ deriveRunFacts,
+ type DeriveRunFactsOptions,
+} from "#evals/runner/derive-run-facts.js";
+import type { EveEvalDerivedFacts } from "#evals/types.js";
+
+/** Fixtures are authored without envelopes; stamp them the way the wire would. */
+function derive(
+ events: readonly UnstampedMessageStreamEvent[],
+ options?: DeriveRunFactsOptions,
+): EveEvalDerivedFacts {
+ return deriveRunFacts(stampTestEvents(events), options);
+}
-function turnStarted(turnId: string, sequence: number): HandleMessageStreamEvent {
+function turnStarted(turnId: string, sequence: number): UnstampedMessageStreamEvent {
return { type: "turn.started", data: { turnId, sequence } };
}
function actionsRequested(
actions: readonly { callId: string; toolName: string; input?: JsonObject }[],
-): HandleMessageStreamEvent {
+): UnstampedMessageStreamEvent {
return {
type: "actions.requested",
data: {
@@ -33,7 +47,7 @@ function actionResult(input: {
output?: unknown;
status?: "completed" | "failed" | "rejected";
isError?: boolean;
-}): HandleMessageStreamEvent {
+}): UnstampedMessageStreamEvent {
return {
type: "action.result",
data: {
@@ -57,7 +71,7 @@ function subagentResult(input: {
subagentName: string;
output: unknown;
status: "completed" | "failed" | "rejected";
-}): HandleMessageStreamEvent {
+}): UnstampedMessageStreamEvent {
return {
type: "action.result",
data: {
@@ -75,7 +89,7 @@ function subagentResult(input: {
};
}
-function inputRequested(requestIds: readonly string[]): HandleMessageStreamEvent {
+function inputRequested(requestIds: readonly string[]): UnstampedMessageStreamEvent {
return {
type: "input.requested",
data: {
@@ -98,12 +112,12 @@ function inputRequested(requestIds: readonly string[]): HandleMessageStreamEvent
describe("deriveRunFacts", () => {
it("returns empty facts for no events", () => {
- const facts = deriveRunFacts([]);
+ const facts = derive([]);
expect(facts).toEqual({ ...createEmptyDerivedFacts(), failureCode: undefined });
});
it("pairs tool calls with their results by call id", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
actionsRequested([
{ callId: "c1", toolName: "get_weather", input: { city: "Brooklyn" } },
@@ -118,7 +132,7 @@ describe("deriveRunFacts", () => {
}),
];
- const facts = deriveRunFacts(events, { sessionId: "s1" });
+ const facts = derive(events, { sessionId: "s1" });
expect(facts.toolCalls).toEqual([
{
@@ -142,17 +156,17 @@ describe("deriveRunFacts", () => {
});
it("uses the normalized failed lifecycle status for error results", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
actionsRequested([{ callId: "c1", toolName: "bash" }]),
actionResult({ callId: "c1", toolName: "bash", isError: true }),
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.toolCalls[0]?.status).toBe("failed");
});
it("distinguishes pending, completed, failed, and rejected tool calls", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
actionsRequested([
{ callId: "pending", toolName: "pending" },
{ callId: "completed", toolName: "completed" },
@@ -164,7 +178,7 @@ describe("deriveRunFacts", () => {
actionResult({ callId: "rejected", toolName: "rejected", status: "rejected" }),
];
- expect(deriveRunFacts(events).toolCalls.map((call) => call.status)).toEqual([
+ expect(derive(events).toolCalls.map((call) => call.status)).toEqual([
"pending",
"completed",
"failed",
@@ -173,7 +187,7 @@ describe("deriveRunFacts", () => {
});
it("derives pending tool calls from HITL input requests", () => {
- const facts = deriveRunFacts([turnStarted("t1", 0), inputRequested(["approval"])]);
+ const facts = derive([turnStarted("t1", 0), inputRequested(["approval"])]);
expect(facts.toolCalls).toEqual([
{
@@ -188,7 +202,7 @@ describe("deriveRunFacts", () => {
});
it("pairs HITL tool calls with resumed results by call id", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
inputRequested(["approval"]),
turnStarted("t2", 1),
@@ -199,7 +213,7 @@ describe("deriveRunFacts", () => {
}),
];
- expect(deriveRunFacts(events).toolCalls).toEqual([
+ expect(derive(events).toolCalls).toEqual([
{
name: "bash",
input: {},
@@ -212,7 +226,7 @@ describe("deriveRunFacts", () => {
});
it("derives resolved tool calls from result-only turn events", () => {
- const facts = deriveRunFacts([
+ const facts = derive([
turnStarted("t2", 1),
actionResult({ callId: "approval-call", toolName: "bash", status: "rejected" }),
]);
@@ -230,17 +244,17 @@ describe("deriveRunFacts", () => {
});
it("deduplicates tool calls surfaced by request and HITL events", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
actionsRequested([{ callId: "approval-call", toolName: "bash" }]),
inputRequested(["approval"]),
];
- expect(deriveRunFacts(events).toolCalls).toHaveLength(1);
+ expect(derive(events).toolCalls).toHaveLength(1);
});
it("stamps the turn index from turn.started boundaries", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
actionsRequested([{ callId: "c1", toolName: "first_tool" }]),
actionResult({ callId: "c1", toolName: "first_tool" }),
@@ -249,12 +263,12 @@ describe("deriveRunFacts", () => {
actionResult({ callId: "c2", toolName: "second_tool" }),
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.toolCalls.map((call) => call.turnIndex)).toEqual([0, 1]);
});
it("counts message.completed events whose step completed without tool calls", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
{
type: "message.completed",
data: { finishReason: "stop", message: "hello", stepIndex: 0, turnId: "t1", sequence: 1 },
@@ -274,12 +288,12 @@ describe("deriveRunFacts", () => {
data: { finishReason: "stop", message: "world", stepIndex: 2, turnId: "t1", sequence: 3 },
},
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.messageCount).toBe(2);
});
it("counts reasoning.completed events", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
{
type: "reasoning.completed",
data: { reasoning: "thinking...", stepIndex: 0, turnId: "t1", sequence: 1 },
@@ -289,12 +303,12 @@ describe("deriveRunFacts", () => {
data: { reasoning: "more thinking...", stepIndex: 1, turnId: "t1", sequence: 2 },
},
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.reasoningBlockCount).toBe(2);
});
it("joins subagent.called with subagent.completed by call id", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
{
type: "subagent.called",
@@ -316,7 +330,7 @@ describe("deriveRunFacts", () => {
},
];
- const facts = deriveRunFacts(events, { sessionId: "s0" });
+ const facts = derive(events, { sessionId: "s0" });
expect(facts.subagentCalls).toEqual([
{
callId: "c1",
@@ -333,7 +347,7 @@ describe("deriveRunFacts", () => {
});
it("derives failed subagent calls from result-only events", () => {
- const facts = deriveRunFacts([
+ const facts = derive([
turnStarted("t1", 0),
subagentResult({
callId: "c1",
@@ -356,18 +370,18 @@ describe("deriveRunFacts", () => {
});
it("extracts inline subagent calls from subagent.started events", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
{
type: "subagent.started",
data: { callId: "c1", subagentName: "inline-agent" },
},
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.subagentCalls.map((call) => call.name)).toEqual(["inline-agent"]);
});
it("records every subagent invocation separately", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
{
type: "subagent.started",
data: { callId: "c1", subagentName: "agent-a" },
@@ -377,13 +391,13 @@ describe("deriveRunFacts", () => {
data: { callId: "c2", subagentName: "agent-a" },
},
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.subagentCalls.map((call) => call.name)).toEqual(["agent-a", "agent-a"]);
expect(facts.subagentCallCount).toBe(2);
});
it("captures failure code from session.failed event", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
{
type: "session.failed",
data: {
@@ -393,18 +407,21 @@ describe("deriveRunFacts", () => {
},
},
];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.failureCode).toBe("TIMEOUT");
});
it("collects HITL input requests", () => {
- const events: HandleMessageStreamEvent[] = [turnStarted("t1", 0), inputRequested(["r1", "r2"])];
- const facts = deriveRunFacts(events);
+ const events: UnstampedMessageStreamEvent[] = [
+ turnStarted("t1", 0),
+ inputRequested(["r1", "r2"]),
+ ];
+ const facts = derive(events);
expect(facts.inputRequests.map((request) => request.requestId)).toEqual(["r1", "r2"]);
});
it("marks the run parked when it ends on unanswered input requests", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
inputRequested(["r1"]),
{ type: "turn.completed", data: { sequence: 1, turnId: "t1" } },
@@ -412,14 +429,14 @@ describe("deriveRunFacts", () => {
type: "session.waiting",
data: { continuationToken: "eve:test", wait: "next-user-message" },
},
- ] as HandleMessageStreamEvent[];
+ ] as UnstampedMessageStreamEvent[];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.parked).toBe(true);
});
it("does not mark the run parked when the turn continued past the input request", () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
turnStarted("t1", 0),
inputRequested(["r1"]),
{
@@ -431,9 +448,9 @@ describe("deriveRunFacts", () => {
type: "session.waiting",
data: { continuationToken: "eve:test", wait: "next-user-message" },
},
- ] as HandleMessageStreamEvent[];
+ ] as UnstampedMessageStreamEvent[];
- const facts = deriveRunFacts(events);
+ const facts = derive(events);
expect(facts.parked).toBe(false);
});
});
diff --git a/packages/eve/src/evals/runner/derive-run-facts.ts b/packages/eve/src/evals/runner/derive-run-facts.ts
index a5d85b8c6..5d6378a33 100644
--- a/packages/eve/src/evals/runner/derive-run-facts.ts
+++ b/packages/eve/src/evals/runner/derive-run-facts.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { InputRequest } from "#runtime/input/types.js";
import type { JsonObject, JsonValue } from "#shared/json.js";
import type { EveEvalDerivedFacts, EveEvalSubagentCall, EveEvalToolCall } from "#evals/types.js";
@@ -36,7 +36,7 @@ export interface DeriveRunFactsOptions {
* before this epilogue is `input.requested`, the run ended parked on
* unanswered HITL input.
*/
-const TURN_EPILOGUE_EVENT_TYPES: ReadonlySet<HandleMessageStreamEvent["type"]> = new Set([
+const TURN_EPILOGUE_EVENT_TYPES: ReadonlySet<MessageStreamEvent["type"]> = new Set([
"turn.completed",
"session.waiting",
"session.completed",
@@ -51,7 +51,7 @@ const TURN_EPILOGUE_EVENT_TYPES: ReadonlySet<HandleMessageStreamEvent["type"]> =
* power checks, scorers, and reporters.
*/
export function deriveRunFacts(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly MessageStreamEvent[],
options?: DeriveRunFactsOptions,
): EveEvalDerivedFacts {
const sessionId = options?.sessionId;
@@ -210,7 +210,7 @@ export function createEmptyDerivedFacts(): EveEvalDerivedFacts {
* (`turn.completed` → `session.waiting`) is `input.requested`: the harness
* surfaced HITL requests and stopped without resolving them.
*/
-function endedParkedOnInput(events: readonly HandleMessageStreamEvent[]): boolean {
+function endedParkedOnInput(events: readonly MessageStreamEvent[]): boolean {
for (let i = events.length - 1; i >= 0; i--) {
const event = events[i];
if (event === undefined || TURN_EPILOGUE_EVENT_TYPES.has(event.type)) continue;
diff --git a/packages/eve/src/evals/runner/execute-task.test.ts b/packages/eve/src/evals/runner/execute-task.test.ts
index 11a7f281c..41a85161d 100644
--- a/packages/eve/src/evals/runner/execute-task.test.ts
+++ b/packages/eve/src/evals/runner/execute-task.test.ts
@@ -1,7 +1,8 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { Client } from "#client/client.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import { stampTestEvents } from "#internal/testing/events.js";
import { executeTask } from "#evals/runner/execute-task.js";
import type { EveEval, EveEvalContext } from "#evals/types.js";
import { createEvalTargetHandle } from "#evals/target.js";
@@ -596,17 +597,17 @@ describe("executeTask", () => {
});
function createScriptedServer(
- turns: readonly { events: readonly HandleMessageStreamEvent[]; sessionId: string }[],
+ turns: readonly { events: readonly UnstampedMessageStreamEvent[]; sessionId: string }[],
options: {
readonly cancelStatus?: "accepted" | "no_active_turn";
readonly streams?: readonly {
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly UnstampedMessageStreamEvent[];
readonly sessionId: string;
}[];
} = {},
) {
const pendingTurns = [...turns];
- const streamQueues = new Map<string, HandleMessageStreamEvent[][]>();
+ const streamQueues = new Map<string, UnstampedMessageStreamEvent[][]>();
const posts: Array<{ body: unknown; method: string; url: string }> = [];
const cancels: string[] = [];
@@ -666,12 +667,12 @@ function createScriptedServer(
};
}
-function streamResponse(events: readonly HandleMessageStreamEvent[]): Response {
+function streamResponse(events: readonly UnstampedMessageStreamEvent[]): Response {
const encoder = new TextEncoder();
return new Response(
new ReadableStream<Uint8Array>({
start(controller) {
- for (const event of events) {
+ for (const event of stampTestEvents(events)) {
controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
}
controller.close();
@@ -680,26 +681,26 @@ function streamResponse(events: readonly HandleMessageStreamEvent[]): Response {
);
}
-function turnStarted(turnId: string): HandleMessageStreamEvent {
+function turnStarted(turnId: string): UnstampedMessageStreamEvent {
return { data: { sequence: 0, turnId }, type: "turn.started" };
}
-function turnCompleted(turnId: string): HandleMessageStreamEvent {
+function turnCompleted(turnId: string): UnstampedMessageStreamEvent {
return { data: { sequence: 3, turnId }, type: "turn.completed" };
}
-function sessionWaiting(continuationToken = "eve:session_1"): HandleMessageStreamEvent {
+function sessionWaiting(continuationToken = "eve:session_1"): UnstampedMessageStreamEvent {
return {
data: { continuationToken, wait: "next-user-message" },
type: "session.waiting",
};
}
-function sessionCompleted(): HandleMessageStreamEvent {
+function sessionCompleted(): UnstampedMessageStreamEvent {
return { type: "session.completed" };
}
-function messageCompleted(message: string, turnId: string): HandleMessageStreamEvent {
+function messageCompleted(message: string, turnId: string): UnstampedMessageStreamEvent {
return {
data: { finishReason: "stop", message, sequence: 1, stepIndex: 0, turnId },
type: "message.completed",
@@ -710,7 +711,7 @@ function inputRequested(
turnId: string,
requestId: string,
toolName: string,
-): HandleMessageStreamEvent {
+): UnstampedMessageStreamEvent {
return {
data: {
requests: [
@@ -734,7 +735,11 @@ function inputRequested(
};
}
-function actionResult(turnId: string, toolName: string, output: string): HandleMessageStreamEvent {
+function actionResult(
+ turnId: string,
+ toolName: string,
+ output: string,
+): UnstampedMessageStreamEvent {
return {
data: {
result: { callId: "call_1", kind: "tool-result", output, toolName },
@@ -751,7 +756,7 @@ function actionsRequested(
turnId: string,
toolName: string,
callId = "call_weather",
-): HandleMessageStreamEvent {
+): UnstampedMessageStreamEvent {
return {
data: {
actions: [{ callId, input: { city: "Lisbon" }, kind: "tool-call", toolName }],
@@ -767,7 +772,7 @@ function subagentCalled(
turnId: string,
childSessionId: string,
name: string,
-): HandleMessageStreamEvent {
+): UnstampedMessageStreamEvent {
return {
data: {
callId: "call_subagent",
diff --git a/packages/eve/src/evals/runner/execute-task.ts b/packages/eve/src/evals/runner/execute-task.ts
index 3c93a823e..6e154989d 100644
--- a/packages/eve/src/evals/runner/execute-task.ts
+++ b/packages/eve/src/evals/runner/execute-task.ts
@@ -1,5 +1,5 @@
import type { Client } from "#client/client.js";
-import type { HandleMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
+import type { MessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
import { toErrorMessage } from "#shared/errors.js";
import type {
AssertionResult,
@@ -141,7 +141,7 @@ function selectPrimarySessionId(sessions: readonly EveEvalSessionResult[]): stri
* in the stream, if present.
*/
function extractRuntimeIdentity(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly MessageStreamEvent[],
): RuntimeIdentity | undefined {
for (const event of events) {
if (event.type === "session.started" && event.data.runtime !== undefined) {
diff --git a/packages/eve/src/evals/session.ts b/packages/eve/src/evals/session.ts
index 76f1a025f..128dbea91 100644
--- a/packages/eve/src/evals/session.ts
+++ b/packages/eve/src/evals/session.ts
@@ -10,7 +10,7 @@ import type {
SendTurnPayload,
SessionState,
} from "#client/types.js";
-import type { HandleMessageStreamEvent, TurnFailureStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent, TurnFailureStreamEvent } from "#protocol/message.js";
import { isCurrentTurnBoundaryEvent, isTurnFailureEvent } from "#protocol/message.js";
import { summarizeTurnEvents } from "#client/session-utils.js";
import { extractCompletedResult } from "#client/output-schema.js";
@@ -40,7 +40,7 @@ import type { EveEvalInputRequestMatchOptions, EveEvalToolCallMatchOptions } fro
* Error thrown by {@link EveEvalTurn.expectOk} when a turn failed.
*/
export class EveEvalTurnFailedError extends Error {
- readonly event: TurnFailureStreamEvent | undefined;
+ readonly event: (TurnFailureStreamEvent & MessageStreamEvent) | undefined;
readonly turn: EveEvalTurn;
constructor(turn: EveEvalTurn) {
@@ -62,7 +62,7 @@ export class EvalSessionDriver implements EveEvalSession {
readonly #session: ClientSession;
readonly #signal: AbortSignal | undefined;
readonly #collector: AssertionCollector;
- readonly #events: HandleMessageStreamEvent[] = [];
+ readonly #events: MessageStreamEvent[] = [];
#lastTurn: EvalTurn | undefined;
#pendingInputRequests: readonly InputRequest[] = [];
@@ -87,7 +87,7 @@ export class EvalSessionDriver implements EveEvalSession {
);
}
- get events(): readonly HandleMessageStreamEvent[] {
+ get events(): readonly MessageStreamEvent[] {
return this.#events;
}
@@ -216,7 +216,7 @@ export class EvalSessionDriver implements EveEvalSession {
#recordTurn(input: {
readonly data: unknown;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly inputRequests: readonly InputRequest[];
readonly message: string | undefined;
readonly sessionId: string;
@@ -241,7 +241,7 @@ export class EvalSessionDriver implements EveEvalSession {
return turn;
}
- #recordObservedTurn(sessionId: string, events: readonly HandleMessageStreamEvent[]): EveEvalTurn {
+ #recordObservedTurn(sessionId: string, events: readonly MessageStreamEvent[]): EveEvalTurn {
const summary = summarizeTurnEvents(events);
return this.#recordTurn({
data: extractCompletedResult(events),
@@ -271,22 +271,22 @@ export class EvalSessionDriver implements EveEvalSession {
}
interface LiveEventWaiter {
- readonly matches: (event: HandleMessageStreamEvent) => boolean;
+ readonly matches: (event: MessageStreamEvent) => boolean;
readonly reject: (error: Error) => void;
- readonly resolve: (event: HandleMessageStreamEvent) => void;
+ readonly resolve: (event: MessageStreamEvent) => void;
}
class EvalLiveTurn implements EveEvalLiveTurn {
readonly session: EveEvalSession;
readonly sessionId: string;
readonly #completion: Promise<EveEvalTurn>;
- readonly #events: HandleMessageStreamEvent[] = [];
+ readonly #events: MessageStreamEvent[] = [];
readonly #waiters = new Set<LiveEventWaiter>();
#waitError: Error | undefined;
constructor(input: {
- readonly events: AsyncIterable<HandleMessageStreamEvent>;
- readonly record: (events: readonly HandleMessageStreamEvent[]) => EveEvalTurn;
+ readonly events: AsyncIterable<MessageStreamEvent>;
+ readonly record: (events: readonly MessageStreamEvent[]) => EveEvalTurn;
readonly session: EveEvalSession;
readonly sessionId: string;
}) {
@@ -296,7 +296,7 @@ class EvalLiveTurn implements EveEvalLiveTurn {
void this.#completion.catch(() => {});
}
- get events(): readonly HandleMessageStreamEvent[] {
+ get events(): readonly MessageStreamEvent[] {
return this.#events;
}
@@ -308,11 +308,11 @@ class EvalLiveTurn implements EveEvalLiveTurn {
return await this.#completion;
}
- async waitForEvent<TType extends HandleMessageStreamEvent["type"]>(
+ async waitForEvent<TType extends MessageStreamEvent["type"]>(
type: TType,
options?: EveEvalWaitForEventOptions<TType>,
): Promise<EveEvalStreamEvent<TType>> {
- const matches = (event: HandleMessageStreamEvent): boolean =>
+ const matches = (event: MessageStreamEvent): boolean =>
event.type === type &&
(options?.data === undefined ||
matchesValue(options.data, "data" in event ? event.data : undefined));
@@ -331,8 +331,8 @@ class EvalLiveTurn implements EveEvalLiveTurn {
}
async #consume(
- source: AsyncIterable<HandleMessageStreamEvent>,
- record: (events: readonly HandleMessageStreamEvent[]) => EveEvalTurn,
+ source: AsyncIterable<MessageStreamEvent>,
+ record: (events: readonly MessageStreamEvent[]) => EveEvalTurn,
): Promise<EveEvalTurn> {
try {
let sawBoundary = false;
@@ -369,7 +369,7 @@ class EvalLiveTurn implements EveEvalLiveTurn {
}
}
- #resolveWaiters(event: HandleMessageStreamEvent): void {
+ #resolveWaiters(event: MessageStreamEvent): void {
for (const waiter of this.#waiters) {
if (!waiter.matches(event)) continue;
this.#waiters.delete(waiter);
@@ -391,7 +391,7 @@ interface EvalTurn extends EveEvalAssertions, EveEvalOutputAssertions {}
class EvalTurn implements EveEvalTurn {
readonly data: unknown;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly inputRequests: readonly InputRequest[];
readonly message: string | undefined;
readonly sessionId: string;
@@ -404,7 +404,7 @@ class EvalTurn implements EveEvalTurn {
readonly collector: AssertionCollector;
readonly data: unknown;
readonly derived: EveEvalDerivedFacts;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly inputRequests: readonly InputRequest[];
readonly message: string | undefined;
readonly sessionId: string;
diff --git a/packages/eve/src/evals/types.ts b/packages/eve/src/evals/types.ts
index 9464fcce8..d06603b38 100644
--- a/packages/eve/src/evals/types.ts
+++ b/packages/eve/src/evals/types.ts
@@ -1,7 +1,7 @@
import type { LanguageModel } from "ai";
import type { StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
-import type { HandleMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
+import type { RuntimeIdentity, MessageStreamEvent } from "#protocol/message.js";
import type { CancelSessionResult, SendTurnInput, SessionState } from "#client/types.js";
import type { InputRequest, InputResponse } from "#runtime/input/types.js";
import type { JsonObject, JsonValue } from "#shared/json.js";
@@ -82,7 +82,7 @@ export interface EveEvalDerivedFacts {
*/
export interface EveEvalSessionResult {
readonly derived: EveEvalDerivedFacts;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly primary: boolean;
readonly sessionId?: string;
readonly state: SessionState;
@@ -107,7 +107,7 @@ export interface EveEvalTaskResult {
*/
readonly status: "completed" | "failed" | "waiting";
/** The captured stream events from the run. */
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
/** Lines written through `t.log` while the eval ran. */
readonly logs?: readonly string[];
/** Facts extracted from the stream (tool calls, message counts, etc.). */
@@ -195,18 +195,18 @@ export interface EveEvalAssertions {
maxToolCalls(max: number): AssertionHandle;
calledSubagent(name: string, options?: EveEvalSubagentCallMatchOptions): AssertionHandle;
noFailedActions(): AssertionHandle;
- event<TType extends HandleMessageStreamEvent["type"]>(
+ event<TType extends MessageStreamEvent["type"]>(
type: TType,
options?: Omit<Extract<EveEvalEventMatch, { type: TType }>, "type">,
): AssertionHandle;
- notEvent<TType extends HandleMessageStreamEvent["type"]>(
+ notEvent<TType extends MessageStreamEvent["type"]>(
type: TType,
options?: Omit<Extract<EveEvalEventMatch, { type: TType }>, "type" | "count">,
): AssertionHandle;
eventOrder(matchers: readonly EveEvalEventMatch[]): AssertionHandle;
eventsSatisfy(
label: string,
- predicate: (events: readonly HandleMessageStreamEvent[]) => boolean,
+ predicate: (events: readonly MessageStreamEvent[]) => boolean,
): AssertionHandle;
}
@@ -218,11 +218,11 @@ export interface EveEvalOutputAssertions {
/** Typed stream event returned by {@link EveEvalLiveTurn.waitForEvent}. */
export type EveEvalStreamEvent<
- TType extends HandleMessageStreamEvent["type"] = HandleMessageStreamEvent["type"],
-> = Extract<HandleMessageStreamEvent, { type: TType }>;
+ TType extends MessageStreamEvent["type"] = MessageStreamEvent["type"],
+> = Extract<MessageStreamEvent, { type: TType }>;
/** Matcher options for waiting until one live turn emits a specific event. */
-export type EveEvalWaitForEventOptions<TType extends HandleMessageStreamEvent["type"]> = Omit<
+export type EveEvalWaitForEventOptions<TType extends MessageStreamEvent["type"]> = Omit<
Extract<EveEvalEventMatch, { type: TType }>,
"count" | "type"
>;
@@ -235,7 +235,7 @@ export type EveEvalWaitForEventOptions<TType extends HandleMessageStreamEvent["t
*/
export interface EveEvalLiveTurn {
/** Events observed on this turn so far. */
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
/** Session driver that started or owns this turn. */
readonly session: EveEvalSession;
/** Durable session id available as soon as the turn is accepted or attached. */
@@ -245,7 +245,7 @@ export interface EveEvalLiveTurn {
/** Wait for the turn boundary and return the recorded immutable result. */
result(): Promise<EveEvalTurn>;
/** Wait until the live stream emits one typed event matching `options`. */
- waitForEvent<TType extends HandleMessageStreamEvent["type"]>(
+ waitForEvent<TType extends MessageStreamEvent["type"]>(
type: TType,
options?: EveEvalWaitForEventOptions<TType>,
): Promise<EveEvalStreamEvent<TType>>;
@@ -254,7 +254,7 @@ export interface EveEvalLiveTurn {
/** Operations and state shared by the primary eval context and independent sessions. */
export interface EveEvalSessionDriver {
/** All events observed on this session so far. */
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
/** Input requests left pending by the last parked turn. */
readonly pendingInputRequests: readonly InputRequest[];
/** Serializable cursor for resuming this session. */
@@ -286,7 +286,7 @@ export interface EveEvalSession
*/
export interface EveEvalTurn extends EveEvalAssertions, EveEvalOutputAssertions {
readonly data: unknown;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly inputRequests: readonly InputRequest[];
readonly message: string | undefined;
readonly sessionId: string;
diff --git a/packages/eve/src/execution/dispatch-runtime-actions-step.ts b/packages/eve/src/execution/dispatch-runtime-actions-step.ts
index 370b11a75..eb6d15222 100644
--- a/packages/eve/src/execution/dispatch-runtime-actions-step.ts
+++ b/packages/eve/src/execution/dispatch-runtime-actions-step.ts
@@ -24,7 +24,7 @@ import {
import {
createSubagentCalledEvent,
encodeMessageStreamEvent,
- timestampHandleMessageStreamEvent,
+ stampMessageStreamEvent,
} from "#protocol/message.js";
import type {
RuntimeActionRequest,
@@ -231,7 +231,7 @@ export async function dispatchRuntimeActionsStep(input: {
}),
adapterCtx,
);
- await writer.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(parentEvent)));
+ await writer.write(encodeMessageStreamEvent(stampMessageStreamEvent(parentEvent)));
}
} finally {
writer.releaseLock();
diff --git a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
index 49fb634ca..ecc076404 100644
--- a/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
+++ b/packages/eve/src/execution/session-limit-cancellation.integration.test.ts
@@ -10,7 +10,7 @@ import {
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { sessionCancelHookToken } from "#execution/turn-cancellation-token.js";
import { workflowEntry } from "#execution/workflow-entry.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
/**
* Declining a session-limit continuation prompt cancels the in-flight turn
@@ -37,7 +37,7 @@ function buildSerializedContext(overrides: {
};
}
-function expectNoFailureEvents(events: readonly HandleMessageStreamEvent[]): void {
+function expectNoFailureEvents(events: readonly UnstampedMessageStreamEvent[]): void {
const types = events.map((event) => event.type);
for (const failureType of FAILURE_EVENT_TYPES) {
expect(types).not.toContain(failureType);
@@ -98,7 +98,7 @@ async function waitForRunCompletion(runId: string, timeout = 15_000): Promise<vo
throw new Error(`Timed out waiting for run "${runId}" to complete.`);
}
-function requestIdFromPromptTurn(events: readonly HandleMessageStreamEvent[]): string {
+function requestIdFromPromptTurn(events: readonly UnstampedMessageStreamEvent[]): string {
const requested = filterEventsByType(events, "input.requested");
expect(requested).toHaveLength(1);
const requestId = requested[0]?.data.requests[0]?.requestId;
diff --git a/packages/eve/src/execution/settle-cancelled-turn-step.ts b/packages/eve/src/execution/settle-cancelled-turn-step.ts
index 35e81bbb4..131a3ff44 100644
--- a/packages/eve/src/execution/settle-cancelled-turn-step.ts
+++ b/packages/eve/src/execution/settle-cancelled-turn-step.ts
@@ -28,8 +28,8 @@ import { getInstrumentationRuntime } from "#harness/instrumentation-runtime.js";
import { clearPendingWorkflowInterrupt } from "#harness/workflow-interrupt-state.js";
import {
encodeMessageStreamEvent,
- type HandleMessageStreamEvent,
- timestampHandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
+ stampMessageStreamEvent,
} from "#protocol/message.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
@@ -77,15 +77,15 @@ export async function settleCancelledTurnStep(input: {
const writer = input.parentWritable.getWriter();
try {
const scoped = await withContextScope(ctx, session, async (enrichedSession) => {
- const baseEmit = async (event: HandleMessageStreamEvent): Promise<void> => {
+ const baseEmit = async (event: UnstampedMessageStreamEvent): Promise<void> => {
const transformed = await callAdapterEventHandler(adapter, event, adapterCtx);
setChannelContext(ctx, { ...adapter, state: { ...adapterCtx.state } });
- await writer.write(
- encodeMessageStreamEvent(timestampHandleMessageStreamEvent(transformed)),
- );
+ // Stamp once: the persisted chunk and the hooks must agree on the id.
+ const stamped = stampMessageStreamEvent(transformed);
+ await writer.write(encodeMessageStreamEvent(stamped));
await dispatchStreamEventHooks({
ctx,
- event: transformed,
+ event: stamped,
registry: bundle.hookRegistry,
});
};
diff --git a/packages/eve/src/execution/subagent-auth-proxy.integration.test.ts b/packages/eve/src/execution/subagent-auth-proxy.integration.test.ts
index de3805ba3..6a6c43c2c 100644
--- a/packages/eve/src/execution/subagent-auth-proxy.integration.test.ts
+++ b/packages/eve/src/execution/subagent-auth-proxy.integration.test.ts
@@ -10,7 +10,7 @@ import { AuthKey, ContinuationTokenKey, SessionIdKey } from "#context/keys.js";
import { emitProxiedSubagentEvent } from "#execution/subagent-event-proxy-step.js";
import { projectToDurableSession } from "#execution/session.js";
import type { HarnessSession } from "#harness/types.js";
-import type { TimedHandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { deserializeRuntimeAdapter } from "#runtime/channels/registry.js";
import { createEmptyHookRegistry } from "#runtime/hooks/registry.js";
import {
@@ -131,8 +131,8 @@ function createCapturingWritable(chunks: Uint8Array[]): WritableStream<Uint8Arra
});
}
-function decodeEvent(chunk: Uint8Array): TimedHandleMessageStreamEvent {
- return JSON.parse(new TextDecoder().decode(chunk).trim()) as TimedHandleMessageStreamEvent;
+function decodeEvent(chunk: Uint8Array): MessageStreamEvent {
+ return JSON.parse(new TextDecoder().decode(chunk).trim()) as MessageStreamEvent;
}
describe("subagent authorization proxy", () => {
diff --git a/packages/eve/src/execution/subagent-event-proxy-step.ts b/packages/eve/src/execution/subagent-event-proxy-step.ts
index 8a6604e6d..7174af75e 100644
--- a/packages/eve/src/execution/subagent-event-proxy-step.ts
+++ b/packages/eve/src/execution/subagent-event-proxy-step.ts
@@ -20,8 +20,8 @@ import { hydrateDurableSession } from "#execution/session.js";
import { emitProxiedInputRequest } from "#execution/subagent-hitl-proxy.js";
import { upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { HarnessSession } from "#harness/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
-import { encodeMessageStreamEvent, timestampHandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
+import { encodeMessageStreamEvent, stampMessageStreamEvent } from "#protocol/message.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
type SubagentEventHookPayload =
@@ -81,9 +81,11 @@ export async function emitProxiedSubagentEvent(input: {
let proxyEntries: ProxyInputRequestEntries | undefined;
let scopedSession: HarnessSession;
try {
- const emit = async (event: HandleMessageStreamEvent): Promise<void> => {
+ // A re-emitted child event is a distinct event on the parent stream, so it
+ // gets its own id rather than the child's.
+ const emit = async (event: UnstampedMessageStreamEvent): Promise<void> => {
const transformed = await callAdapterEventHandler(adapter, event, adapterCtx);
- await writer.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(transformed)));
+ await writer.write(encodeMessageStreamEvent(stampMessageStreamEvent(transformed)));
};
const scopeResult = await withContextScope(ctx, session, async (enrichedSession) => {
diff --git a/packages/eve/src/execution/subagent-hitl-proxy.integration.test.ts b/packages/eve/src/execution/subagent-hitl-proxy.integration.test.ts
index 95b759c6e..0b34eac76 100644
--- a/packages/eve/src/execution/subagent-hitl-proxy.integration.test.ts
+++ b/packages/eve/src/execution/subagent-hitl-proxy.integration.test.ts
@@ -11,7 +11,7 @@ import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js
import { serializeContext } from "#context/serialize.js";
import { hasProxyInputRequests, upsertProxyInputRequests } from "#harness/proxy-input-requests.js";
import type { HarnessEmitFn, HarnessSession } from "#harness/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { InputRequest } from "#runtime/input/types.js";
import { createRuntimeAdapterRegistry } from "#runtime/channels/registry.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
@@ -175,10 +175,10 @@ function buildEmptySession(continuationToken: string, sessionId: string): Harnes
*/
function buildCapturingEmit(ctx: ContextContainer): {
readonly emit: HarnessEmitFn;
- readonly events: HandleMessageStreamEvent[];
+ readonly events: UnstampedMessageStreamEvent[];
readonly persistAdapterState: () => void;
} {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const adapter = ctx.require(ChannelKey);
const adapterCtx = buildAdapterContext(adapter, ctx);
const emit: HarnessEmitFn = async (event) => {
diff --git a/packages/eve/src/execution/terminal-session-failure-step.ts b/packages/eve/src/execution/terminal-session-failure-step.ts
index 080fcea36..69f61baa6 100644
--- a/packages/eve/src/execution/terminal-session-failure-step.ts
+++ b/packages/eve/src/execution/terminal-session-failure-step.ts
@@ -6,7 +6,7 @@ import { createLogger, formatError } from "#internal/logging.js";
import {
createSessionFailedEvent,
encodeMessageStreamEvent,
- timestampHandleMessageStreamEvent,
+ stampMessageStreamEvent,
} from "#protocol/message.js";
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
@@ -71,7 +71,7 @@ export async function emitTerminalSessionFailureStep(input: {
try {
const writer = input.parentWritable.getWriter();
try {
- await writer.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(event)));
+ await writer.write(encodeMessageStreamEvent(stampMessageStreamEvent(event)));
} finally {
writer.releaseLock();
}
diff --git a/packages/eve/src/execution/turn-cancellation.integration.test.ts b/packages/eve/src/execution/turn-cancellation.integration.test.ts
index efa9695f1..705bf08f7 100644
--- a/packages/eve/src/execution/turn-cancellation.integration.test.ts
+++ b/packages/eve/src/execution/turn-cancellation.integration.test.ts
@@ -14,7 +14,7 @@ import { sessionCancelHookToken } from "#execution/turn-cancellation-token.js";
import { workflowEntry } from "#execution/workflow-entry.js";
import { createWorkflowRuntime } from "#execution/workflow-runtime.js";
import { createEveCancelTurnRoutePath } from "#protocol/routes.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { createCancelFn } from "#channel/cancel.js";
import type { RouteHandlerArgs } from "#channel/routes.js";
import { createSession } from "#channel/session.js";
@@ -197,7 +197,7 @@ async function expectNoStepRetries(runId: string): Promise<void> {
expect([...completions.entries()].filter(([, count]) => count > 1)).toEqual([]);
}
-function expectNoFailureEvents(events: readonly HandleMessageStreamEvent[]): void {
+function expectNoFailureEvents(events: readonly UnstampedMessageStreamEvent[]): void {
const types = events.map((event) => event.type);
for (const failureType of FAILURE_EVENT_TYPES) {
expect(types).not.toContain(failureType);
diff --git a/packages/eve/src/execution/workflow-entry.integration.test.ts b/packages/eve/src/execution/workflow-entry.integration.test.ts
index 7fa48d882..f62da641c 100644
--- a/packages/eve/src/execution/workflow-entry.integration.test.ts
+++ b/packages/eve/src/execution/workflow-entry.integration.test.ts
@@ -15,7 +15,8 @@ import { createWorkflowRuntime } from "#execution/workflow-runtime.js";
import { normalizeEveAttributes } from "#runtime/attributes/normalize.js";
import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";
import { ConnectionAuthorizationRequiredError } from "#public/connections/errors.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent, MessageStreamEvent } from "#protocol/message.js";
+import { isEventId } from "#protocol/event-id.js";
import type { ToolContext } from "#public/definitions/tool.js";
import type { AuthorizationDefinition, TokenResult } from "#runtime/connections/types.js";
import type { ResolvedToolDefinition } from "#runtime/types.js";
@@ -295,6 +296,64 @@ describe("workflowEntry integration", () => {
});
});
+ it("stamps every stream event with an id that survives a rewind", async () => {
+ const runtime = createTestRuntime({ agent: { name: "workflow-entry-event-ids" } });
+ const continuationToken = "http:workflow-entry-event-ids";
+
+ await runtime.run(async () => {
+ const run = await start(workflowEntry, [
+ {
+ input: { message: "identify these events" },
+ serializedContext: buildSerializedContext({
+ channelKind: "http",
+ continuationToken,
+ mode: "conversation",
+ }),
+ },
+ ]);
+
+ const stream = captureTurnEvents(run);
+ let firstTurn: readonly MessageStreamEvent[];
+ try {
+ firstTurn = await stream.nextTurn();
+ } finally {
+ stream.dispose();
+ }
+
+ try {
+ expect(firstTurn.length).toBeGreaterThan(1);
+ // No two events share an id, including appends that share
+ // `(turnId, sequence, stepIndex)`.
+ expect(firstTurn.every((event) => isEventId(event.meta.id))).toBe(true);
+ expect(new Set(firstTurn.map((event) => event.meta.id)).size).toBe(firstTurn.length);
+
+ const ids = firstTurn.map((event) => event.meta.id);
+ expect(ids).toEqual([...ids].sort());
+
+ // Re-reading the durable stream returns the same ids.
+ const workflowRuntime = createWorkflowRuntime({
+ compiledArtifactsSource: createBundledRuntimeCompiledArtifactsSource(),
+ });
+ const replayed = await workflowRuntime.getEventStream(run.runId, { startIndex: 0 });
+ const replayedIds: string[] = [];
+ const reader = replayed.getReader();
+ try {
+ while (replayedIds.length < firstTurn.length) {
+ const { done, value } = await reader.read();
+ if (done) break;
+ replayedIds.push(value.meta.id);
+ }
+ } finally {
+ await reader.cancel();
+ }
+
+ expect(replayedIds).toEqual(ids);
+ } finally {
+ await run.cancel();
+ }
+ });
+ });
+
it("fails a competing continuation owner before its first turn", async () => {
const runtime = createTestRuntime({ agent: { name: "workflow-entry-hook-owner" } });
const continuationToken = "http:workflow-entry-hook-owner";
@@ -586,8 +645,8 @@ interface CapturedEventStream {
dispose(): void;
nextUntil(
label: string,
- predicate: (event: HandleMessageStreamEvent) => boolean,
- ): Promise<HandleMessageStreamEvent[]>;
+ predicate: (event: UnstampedMessageStreamEvent) => boolean,
+ ): Promise<UnstampedMessageStreamEvent[]>;
}
function captureEvents(run: Parameters<typeof captureTurnEvents>[0]): CapturedEventStream {
@@ -618,9 +677,9 @@ async function readUntil(
reader: ReadableStreamDefaultReader<Uint8Array>,
decoder: InstanceType<typeof TextDecoder>,
initialBuffer: string,
- predicate: (event: HandleMessageStreamEvent) => boolean,
-): Promise<{ buffer: string; events: HandleMessageStreamEvent[] }> {
- const events: HandleMessageStreamEvent[] = [];
+ predicate: (event: UnstampedMessageStreamEvent) => boolean,
+): Promise<{ buffer: string; events: UnstampedMessageStreamEvent[] }> {
+ const events: UnstampedMessageStreamEvent[] = [];
let buffer = initialBuffer;
while (true) {
@@ -644,7 +703,7 @@ async function readUntil(
continue;
}
- const event = JSON.parse(line) as HandleMessageStreamEvent;
+ const event = JSON.parse(line) as UnstampedMessageStreamEvent;
events.push(event);
if (predicate(event)) {
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 80c55e12f..921af99fd 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -38,7 +38,7 @@ import {
type WorkflowFunction,
type WorkflowMetadata,
} from "#internal/workflow/runtime.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { RuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import { ROOT_RUNTIME_AGENT_NODE_ID } from "#runtime/graph.js";
import { normalizeEveAttributes } from "#runtime/attributes/normalize.js";
@@ -158,11 +158,9 @@ export function createWorkflowRuntime(config: {
throw error;
}
- let events: ReadableStream<HandleMessageStreamEvent> | undefined;
+ let events: ReadableStream<MessageStreamEvent> | undefined;
const getEvents = () => {
- events ??= parseNdjsonStream<HandleMessageStreamEvent>(() =>
- getRun(run.runId).getReadable(),
- );
+ events ??= parseNdjsonStream<MessageStreamEvent>(() => getRun(run.runId).getReadable());
return events;
};
@@ -219,8 +217,8 @@ export function createWorkflowRuntime(config: {
async getEventStream(
sessionId: string,
options?: GetEventStreamOptions,
- ): Promise<ReadableStream<HandleMessageStreamEvent>> {
- return parseNdjsonStream<HandleMessageStreamEvent>(() =>
+ ): Promise<ReadableStream<MessageStreamEvent>> {
+ return parseNdjsonStream<MessageStreamEvent>(() =>
getRun(sessionId).getReadable({ startIndex: options?.startIndex }),
);
},
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index f3aade630..a14c54eee 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -44,8 +44,9 @@ import {
createAuthorizationCompletedEvent,
createSessionStartedEvent,
encodeMessageStreamEvent,
- type HandleMessageStreamEvent,
- timestampHandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
+ stampMessageStreamEvent,
+ type MessageStreamEvent,
} from "#protocol/message.js";
import {
CallbackBaseUrlKey,
@@ -291,15 +292,17 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
const writer = input.parentWritable.getWriter();
- const emit = async (event: HandleMessageStreamEvent): Promise<HandleMessageStreamEvent> => {
+ // Stamp once: the persisted chunk and the hooks below must agree on the id.
+ const emit = async (event: UnstampedMessageStreamEvent): Promise<MessageStreamEvent> => {
const toEmit = await callAdapterEventHandler(adapter, event, adapterCtx);
setChannelContext(ctx, { ...adapter, state: { ...adapterCtx.state } });
- await writer.write(encodeMessageStreamEvent(timestampHandleMessageStreamEvent(toEmit)));
- return toEmit;
+ const stamped = stampMessageStreamEvent(toEmit);
+ await writer.write(encodeMessageStreamEvent(stamped));
+ return stamped;
};
const handleEvent = async (
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
messages?: readonly import("ai").ModelMessage[],
): Promise<void> => {
const emitted = await emit(event);
diff --git a/packages/eve/src/harness/cancelled-turn-emission.test.ts b/packages/eve/src/harness/cancelled-turn-emission.test.ts
index 3f49bf479..c65f47950 100644
--- a/packages/eve/src/harness/cancelled-turn-emission.test.ts
+++ b/packages/eve/src/harness/cancelled-turn-emission.test.ts
@@ -1,11 +1,11 @@
import { describe, expect, it } from "vitest";
import { emitCancelledTurn } from "#harness/cancelled-turn-emission.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
describe("emitCancelledTurn", () => {
it("emits turn.cancelled → session.waiting and no failure events", async () => {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const next = await emitCancelledTurn(
async (event) => {
events.push(event);
@@ -31,7 +31,7 @@ describe("emitCancelledTurn", () => {
// is persisted: the persisted state still has the between-turns
// turnId "", but `turn.started` for `turn_${sequence}` is already on
// the stream.
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const next = await emitCancelledTurn(
async (event) => {
events.push(event);
diff --git a/packages/eve/src/harness/instrumentation-native-events.ts b/packages/eve/src/harness/instrumentation-native-events.ts
index f03fcc639..ff8289cb5 100644
--- a/packages/eve/src/harness/instrumentation-native-events.ts
+++ b/packages/eve/src/harness/instrumentation-native-events.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type {
InstrumentationHooks,
InstrumentationPointEvent,
@@ -33,7 +33,7 @@ export function createInstrumentationHandleEvent(
}
function toLifecycleEvent(
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
input: CreateInstrumentationHandleEventInput,
activeTurnId: string | undefined,
): InstrumentationPointEvent | undefined {
diff --git a/packages/eve/src/harness/ordered-stream-emitter.test.ts b/packages/eve/src/harness/ordered-stream-emitter.test.ts
index d425f1d95..87cb6f947 100644
--- a/packages/eve/src/harness/ordered-stream-emitter.test.ts
+++ b/packages/eve/src/harness/ordered-stream-emitter.test.ts
@@ -6,7 +6,7 @@ import {
createMessageCompletedEvent,
createReasoningAppendedEvent,
} from "#protocol/message.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
function deferred(): { readonly promise: Promise<void>; resolve(): void } {
let resolve!: () => void;
@@ -37,33 +37,30 @@ function reasoning(delta: string, soFar: string) {
}
describe("createOrderedStreamEmitter", () => {
- it("keeps consuming while a write is active and preserves the latest event metadata", async () => {
+ it("keeps consuming while a write is active and preserves the latest event payload", async () => {
const firstWrite = deferred();
- const events: HandleMessageStreamEvent[] = [];
- const emitFn = vi.fn(async (event: HandleMessageStreamEvent) => {
+ const events: UnstampedMessageStreamEvent[] = [];
+ const emitFn = vi.fn(async (event: UnstampedMessageStreamEvent) => {
events.push(event);
if (events.length === 1) await firstWrite.promise;
});
const emitter = createOrderedStreamEmitter(emitFn);
await emitter.emit(message("A", "A"));
- await emitter.emit({ ...message("B", "AB"), meta: { at: "2026-07-10T18:00:00.000Z" } });
- await emitter.emit({ ...message("C", "ABC"), meta: { at: "2026-07-10T18:00:01.000Z" } });
+ await emitter.emit(message("B", "AB"));
+ await emitter.emit(message("C", "ABC"));
expect(emitFn).toHaveBeenCalledTimes(1);
firstWrite.resolve();
await emitter.closeAndDrain();
- expect(events).toEqual([
- message("A", "A"),
- { ...message("BC", "ABC"), meta: { at: "2026-07-10T18:00:01.000Z" } },
- ]);
+ expect(events).toEqual([message("A", "A"), message("BC", "ABC")]);
});
it("treats other event types and stream coordinates as ordering barriers", async () => {
const firstWrite = deferred();
- const events: HandleMessageStreamEvent[] = [];
- const emitFn = vi.fn(async (event: HandleMessageStreamEvent) => {
+ const events: UnstampedMessageStreamEvent[] = [];
+ const emitFn = vi.fn(async (event: UnstampedMessageStreamEvent) => {
events.push(event);
if (events.length === 1) await firstWrite.promise;
});
@@ -117,7 +114,7 @@ describe("createOrderedStreamEmitter", () => {
it("counts merged empty deltas toward the pending-event limit", async () => {
const firstWrite = deferred();
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const emitter = createOrderedStreamEmitter(
async (event) => {
events.push(event);
diff --git a/packages/eve/src/harness/ordered-stream-emitter.ts b/packages/eve/src/harness/ordered-stream-emitter.ts
index 2a282833f..10075178d 100644
--- a/packages/eve/src/harness/ordered-stream-emitter.ts
+++ b/packages/eve/src/harness/ordered-stream-emitter.ts
@@ -1,5 +1,5 @@
import type {
- HandleMessageStreamEvent,
+ UnstampedMessageStreamEvent,
MessageAppendedStreamEvent,
ReasoningAppendedStreamEvent,
} from "#protocol/message.js";
@@ -11,7 +11,7 @@ const MAX_PENDING_DELTA_CHARACTERS = 64 * 1024;
interface PendingEmission {
deltaCharacters: number;
deltaParts?: string[];
- event: HandleMessageStreamEvent;
+ event: UnstampedMessageStreamEvent;
messages?: readonly import("ai").ModelMessage[];
sourceEvents: number;
}
@@ -163,7 +163,7 @@ export function createOrderedStreamEmitter(
function mergeAdjacentAppends(
left: PendingEmission,
- right: HandleMessageStreamEvent,
+ right: UnstampedMessageStreamEvent,
messages: readonly import("ai").ModelMessage[] | undefined,
): boolean {
if (left.event.type === "message.appended" && right.type === "message.appended") {
@@ -187,13 +187,13 @@ function mergeAdjacentAppends(
return false;
}
-function appendDelta(event: HandleMessageStreamEvent): string | undefined {
+function appendDelta(event: UnstampedMessageStreamEvent): string | undefined {
if (event.type === "message.appended") return event.data.messageDelta;
if (event.type === "reasoning.appended") return event.data.reasoningDelta;
return undefined;
}
-function materializeEvent(emission: PendingEmission): HandleMessageStreamEvent {
+function materializeEvent(emission: PendingEmission): UnstampedMessageStreamEvent {
if (emission.deltaParts === undefined) return emission.event;
if (emission.event.type === "message.appended") {
diff --git a/packages/eve/src/harness/runtime-actions.ts b/packages/eve/src/harness/runtime-actions.ts
index 95d853829..a16c0ff14 100644
--- a/packages/eve/src/harness/runtime-actions.ts
+++ b/packages/eve/src/harness/runtime-actions.ts
@@ -1,6 +1,6 @@
import type { ModelMessage, ToolSet, TypedToolCall } from "ai";
-import { createActionResultEvent, type HandleMessageStreamEvent } from "#protocol/message.js";
+import { createActionResultEvent, type UnstampedMessageStreamEvent } from "#protocol/message.js";
import { getRuntimeActionRequestKey, getRuntimeActionResultKey } from "#runtime/actions/keys.js";
import type { RuntimeActionRequest, RuntimeActionResult } from "#runtime/actions/types.js";
import { parseJsonObject, type JsonObject } from "#shared/json.js";
@@ -268,7 +268,7 @@ export async function resolvePendingRuntimeActions(input: {
subagentName: result.subagentName,
},
type: "subagent.completed",
- } satisfies Extract<HandleMessageStreamEvent, { type: "subagent.completed" }>);
+ } satisfies Extract<UnstampedMessageStreamEvent, { type: "subagent.completed" }>);
}
await input.emit(
diff --git a/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts b/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts
index ec72a8b94..5f869bd72 100644
--- a/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-cancellation.integration.test.ts
@@ -2,7 +2,7 @@ import { jsonSchema, type LanguageModel } from "ai";
import { MockLanguageModelV3 } from "ai/test";
import { describe, expect, it, vi } from "vitest";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import { TurnCancelledError } from "#harness/turn-cancellation.js";
import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
@@ -29,9 +29,9 @@ function createSession(): HarnessSession {
function createEventCollector(): {
emit: HarnessEmitFn;
- events: HandleMessageStreamEvent[];
+ events: UnstampedMessageStreamEvent[];
} {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const emit: HarnessEmitFn = async (event) => {
events.push(event);
};
diff --git a/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts b/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts
index e93aa74a8..f4adbe30a 100644
--- a/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-stream-retry.integration.test.ts
@@ -4,7 +4,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import type { HarnessEmitFn, HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
type StreamResult = Awaited<ReturnType<MockLanguageModelV3["doStream"]>>;
type StreamPart = StreamResult["stream"] extends ReadableStream<infer Part> ? Part : never;
@@ -33,9 +33,9 @@ function createSession(): HarnessSession {
function createEventCollector(): {
readonly emit: HarnessEmitFn;
- readonly events: HandleMessageStreamEvent[];
+ readonly events: UnstampedMessageStreamEvent[];
} {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
return {
emit: async (event) => {
events.push(event);
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index fb7a375dd..6a689cf09 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -26,7 +26,7 @@ import {
import { SCHEDULE_APP_AUTH } from "#channel/schedule-auth.js";
import { decodeSandboxRef, isSandboxRefUrl } from "#internal/attachments/sandbox-refs.js";
import { mockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { InstrumentationStepStartedEventInput } from "#public/instrumentation/index.js";
import type { RunMode } from "#shared/run-mode.js";
import { compactMessages, shouldCompact } from "#harness/compaction.js";
@@ -197,16 +197,16 @@ function setDelegatedParent(ctx: ContextContainer): void {
function createEventCollector(): {
emit: HarnessEmitFn;
- events: HandleMessageStreamEvent[];
+ events: UnstampedMessageStreamEvent[];
} {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const emit: HarnessEmitFn = async (event) => {
events.push(event);
};
return { emit, events };
}
-function getCompatibilityEventTypes(events: readonly HandleMessageStreamEvent[]): string[] {
+function getCompatibilityEventTypes(events: readonly UnstampedMessageStreamEvent[]): string[] {
return events
.filter((event) => event.type !== "message.appended" && event.type !== "reasoning.appended")
.map((event) => event.type);
@@ -9004,7 +9004,7 @@ describe("createToolLoopHarness", () => {
});
const order: string[] = [];
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const emit: HarnessEmitFn = async (event) => {
order.push(event.type);
events.push(event);
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 88a4c69d7..9ca153088 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -2,7 +2,7 @@ import type { LanguageModel, ModelMessage, UserContent } from "ai";
import type { SessionCapabilities } from "#channel/types.js";
import type { AlsContext } from "#context/container.js";
-import type { HandleMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
import type { RunMode } from "#shared/run-mode.js";
import type { RuntimeActionResult } from "#runtime/actions/types.js";
import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
@@ -196,7 +196,7 @@ export type HarnessToolMap = ReadonlyMap<string, HarnessToolDefinition>;
* events without knowing about writables or handlers.
*/
export type HarnessEmitFn = (
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
messages?: readonly import("ai").ModelMessage[],
) => Promise<void>;
@@ -209,7 +209,7 @@ export type HarnessEmitFn = (
* and dynamic tool dispatch in one call.
*/
export type HandleEventFn = (
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
messages?: readonly import("ai").ModelMessage[],
) => Promise<void>;
@@ -263,7 +263,7 @@ export interface ToolLoopHarnessConfig {
readonly onCompaction?: () => readonly ModelMessage[];
readonly dispatchDynamicModelEvent?: (input: {
readonly ctx: AlsContext;
- readonly event: HandleMessageStreamEvent;
+ readonly event: UnstampedMessageStreamEvent;
readonly fallback: RuntimeModelReference;
readonly messages: readonly ModelMessage[];
}) => Promise<void>;
diff --git a/packages/eve/src/harness/workflow-lifecycle.test.ts b/packages/eve/src/harness/workflow-lifecycle.test.ts
index ee079ca06..cc1924548 100644
--- a/packages/eve/src/harness/workflow-lifecycle.test.ts
+++ b/packages/eve/src/harness/workflow-lifecycle.test.ts
@@ -6,7 +6,7 @@ import type { HarnessEmissionState } from "#harness/emission.js";
import { createWorkflowLifecycle } from "#harness/workflow-lifecycle.js";
import type { HarnessToolMap } from "#harness/types.js";
import { defineState } from "#public/definitions/state.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
const emissionState: HarnessEmissionState = {
sequence: 2,
@@ -49,7 +49,7 @@ function nestedCall(replayed = false) {
describe("createWorkflowLifecycle", () => {
it("emits nested subagent calls and results as action events", async () => {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const lifecycle = createWorkflowLifecycle({
emit: async (event) => {
events.push(event);
@@ -96,7 +96,7 @@ describe("createWorkflowLifecycle", () => {
});
it("projects rejected child results through the shared result contract", async () => {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const lifecycle = createWorkflowLifecycle({
emit: async (event) => {
events.push(event);
@@ -123,7 +123,7 @@ describe("createWorkflowLifecycle", () => {
});
it("skips replayed calls during continuation", async () => {
- const events: HandleMessageStreamEvent[] = [];
+ const events: UnstampedMessageStreamEvent[] = [];
const lifecycle = createWorkflowLifecycle({
emit: async (event) => {
events.push(event);
diff --git a/packages/eve/src/harness/workflow-lifecycle.ts b/packages/eve/src/harness/workflow-lifecycle.ts
index bd543a82e..f270ca01e 100644
--- a/packages/eve/src/harness/workflow-lifecycle.ts
+++ b/packages/eve/src/harness/workflow-lifecycle.ts
@@ -8,14 +8,14 @@ import { createLogger } from "#internal/logging.js";
import {
createActionResultEvent,
createActionsRequestedEvent,
- type HandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
import { toErrorMessage } from "#shared/errors.js";
import type { WorkflowSandboxLifecycle } from "#shared/workflow-sandbox.js";
const log = createLogger("harness.workflow-lifecycle");
-type EmitWorkflowLifecycleEvent = (event: HandleMessageStreamEvent) => Promise<void>;
+type EmitWorkflowLifecycleEvent = (event: UnstampedMessageStreamEvent) => Promise<void>;
/** Projects sandboxed subagent calls onto eve's existing action event stream. */
export function createWorkflowLifecycle(input: {
diff --git a/packages/eve/src/internal/testing/events.ts b/packages/eve/src/internal/testing/events.ts
index 8f699c96d..387ea9c8b 100644
--- a/packages/eve/src/internal/testing/events.ts
+++ b/packages/eve/src/internal/testing/events.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent, MessageStreamEvent } from "#protocol/message.js";
import { isCurrentTurnBoundaryEvent } from "#protocol/message.js";
/**
@@ -27,7 +27,7 @@ export interface CapturedTurnStream {
* `session.completed`, or `session.failed`) and returns every event
* observed in that turn.
*/
- nextTurn(): Promise<HandleMessageStreamEvent[]>;
+ nextTurn(): Promise<MessageStreamEvent[]>;
/** Releases the reader lock on the underlying `ReadableStream`. */
dispose(): void;
}
@@ -77,8 +77,8 @@ export function captureTurnEvents(
* timing or retries involved.
*/
export function containsEventSequence(
- events: readonly HandleMessageStreamEvent[],
- types: readonly HandleMessageStreamEvent["type"][],
+ events: readonly UnstampedMessageStreamEvent[],
+ types: readonly UnstampedMessageStreamEvent["type"][],
): boolean {
if (types.length === 0) {
return true;
@@ -104,12 +104,12 @@ export function containsEventSequence(
* discriminants. Handy for assertion blocks that only care about a
* subset of the full turn envelope.
*/
-export function filterEventsByType<T extends HandleMessageStreamEvent["type"]>(
- events: readonly HandleMessageStreamEvent[],
+export function filterEventsByType<T extends UnstampedMessageStreamEvent["type"]>(
+ events: readonly UnstampedMessageStreamEvent[],
type: T,
-): Array<Extract<HandleMessageStreamEvent, { type: T }>> {
+): Array<Extract<UnstampedMessageStreamEvent, { type: T }>> {
return events.filter(
- (event): event is Extract<HandleMessageStreamEvent, { type: T }> => event.type === type,
+ (event): event is Extract<UnstampedMessageStreamEvent, { type: T }> => event.type === type,
);
}
@@ -133,8 +133,8 @@ async function readUntilBoundary(
reader: ReadableStreamDefaultReader<Uint8Array>,
state: StreamState,
decoder: InstanceType<typeof TextDecoder>,
-): Promise<HandleMessageStreamEvent[]> {
- const events: HandleMessageStreamEvent[] = [];
+): Promise<MessageStreamEvent[]> {
+ const events: MessageStreamEvent[] = [];
while (true) {
const { done, value } = await reader.read();
@@ -157,7 +157,7 @@ async function readUntilBoundary(
continue;
}
- const event = JSON.parse(line) as HandleMessageStreamEvent;
+ const event = JSON.parse(line) as MessageStreamEvent;
events.push(event);
if (isCurrentTurnBoundaryEvent(event)) {
@@ -166,3 +166,25 @@ async function readUntilBoundary(
}
}
}
+
+/**
+ * Stamps a constructed event so a fixture satisfies the stamped stream
+ * contract without a real emit seam. Ids are sequential and readable; use
+ * `stampMessageStreamEvent` when a test asserts on real id format.
+ */
+export function stampTestEvent(event: UnstampedMessageStreamEvent, index = 0): MessageStreamEvent {
+ return {
+ ...event,
+ meta: {
+ at: new Date(Date.UTC(2026, 0, 1) + index).toISOString(),
+ id: `evt_test_${String(index).padStart(4, "0")}`,
+ },
+ };
+}
+
+/** Stamps every event in a fixture list. See {@link stampTestEvent}. */
+export function stampTestEvents(
+ events: readonly UnstampedMessageStreamEvent[],
+): MessageStreamEvent[] {
+ return events.map((event, index) => stampTestEvent(event, index));
+}
diff --git a/packages/eve/src/protocol/event-dedupe.test.ts b/packages/eve/src/protocol/event-dedupe.test.ts
new file mode 100644
index 000000000..bbd73e20c
--- /dev/null
+++ b/packages/eve/src/protocol/event-dedupe.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import { stampTestEvent } from "#internal/testing/events.js";
+import { createEventDeduper } from "#protocol/event-dedupe.js";
+import { stampMessageStreamEvent, type MessageStreamEvent } from "#protocol/message.js";
+
+function sessionStarted(index: number) {
+ return stampTestEvent({ type: "session.started", data: {} }, index);
+}
+
+describe("createEventDeduper", () => {
+ it("keys on the event id rather than the payload", () => {
+ const deduper = createEventDeduper();
+ const replayed = sessionStarted(0);
+
+ // Re-delivering one event is a duplicate; two emissions of a
+ // byte-identical payload are not.
+ expect(deduper.admit(replayed)).toBe(true);
+ expect(deduper.admit(replayed)).toBe(false);
+ expect(deduper.admit(stampMessageStreamEvent({ type: "session.started", data: {} }))).toBe(
+ true,
+ );
+ expect(deduper.admit(stampMessageStreamEvent({ type: "session.started", data: {} }))).toBe(
+ true,
+ );
+ expect(deduper.size).toBe(3);
+ });
+
+ it("drops the whole replay when a long session rewinds to the start", () => {
+ // Long enough that a bounded window would have evicted its own oldest ids.
+ const stream = Array.from({ length: 25_000 }, (_, index) => sessionStarted(index));
+ const deduper = createEventDeduper();
+
+ const firstRead = stream.filter((event) => deduper.admit(event));
+ const rewound = stream.filter((event) => deduper.admit(event));
+
+ expect(firstRead).toHaveLength(stream.length);
+ expect(rewound).toHaveLength(0);
+ });
+
+ it("admits events written before ids existed", () => {
+ const deduper = createEventDeduper();
+ // Stream version 19 and earlier: envelope present, but only `at`.
+ const preV20 = {
+ type: "session.started",
+ data: {},
+ meta: { at: "2026-07-27T18:04:11.912Z" },
+ } as MessageStreamEvent;
+
+ expect(deduper.admit(preV20)).toBe(true);
+ expect(deduper.admit(preV20)).toBe(true);
+ expect(deduper.size).toBe(0);
+ });
+
+ it("admits events with no envelope at all", () => {
+ const deduper = createEventDeduper();
+ const bare = { type: "session.started", data: {} } as MessageStreamEvent;
+
+ expect(deduper.admit(bare)).toBe(true);
+ expect(deduper.size).toBe(0);
+ });
+});
diff --git a/packages/eve/src/protocol/event-dedupe.ts b/packages/eve/src/protocol/event-dedupe.ts
new file mode 100644
index 000000000..1706e73bb
--- /dev/null
+++ b/packages/eve/src/protocol/event-dedupe.ts
@@ -0,0 +1,45 @@
+import type { MessageStreamEvent } from "#protocol/message.js";
+
+/** Remembers which session-stream events have already been consumed. */
+export type EventDeduper = {
+ /**
+ * Records `event` and returns true when it is new — false when its id was
+ * already admitted, so the caller should drop it.
+ */
+ admit(event: MessageStreamEvent): boolean;
+ /** Number of ids currently remembered. */
+ readonly size: number;
+};
+
+/**
+ * Creates an {@link EventDeduper} keyed on the durable `meta.id`.
+ *
+ * Catches a reconnect that overlaps handled events, a rewind to an earlier
+ * `startIndex`, and a saved log merged with the prefix a live stream replays.
+ * A retried step is not a duplicate: it re-emits under new ids.
+ *
+ * The window is unbounded because a bounded one cannot survive a rewind past
+ * its capacity — the oldest id is already evicted, so re-admitting it evicts
+ * the next and the whole replay cascades back in. Callers here retain an
+ * object per event anyway; one that retains nothing should bound its reads
+ * with the `startIndex` cursor instead.
+ */
+export function createEventDeduper(): EventDeduper {
+ const seen = new Set<string>();
+
+ return {
+ admit(event) {
+ // Absent on the wire for events persisted before stream version 20,
+ // despite being required by `MessageStreamEventMeta`. Admit them:
+ // there is nothing to deduplicate on.
+ const id: string | undefined = event.meta?.id;
+ if (id === undefined) return true;
+ if (seen.has(id)) return false;
+ seen.add(id);
+ return true;
+ },
+ get size() {
+ return seen.size;
+ },
+ };
+}
diff --git a/packages/eve/src/protocol/event-id.test.ts b/packages/eve/src/protocol/event-id.test.ts
new file mode 100644
index 000000000..bb8c1ca50
--- /dev/null
+++ b/packages/eve/src/protocol/event-id.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { createEventId, EVENT_ID_PREFIX, isEventId } from "#protocol/event-id.js";
+import { isUlid } from "#shared/ulid.js";
+
+describe("createEventId", () => {
+ it("prefixes a ULID", () => {
+ const id = createEventId();
+
+ expect(id.startsWith(EVENT_ID_PREFIX)).toBe(true);
+ expect(isUlid(id.slice(EVENT_ID_PREFIX.length))).toBe(true);
+ });
+});
+
+describe("isEventId", () => {
+ it("accepts ids this module mints", () => {
+ expect(isEventId(createEventId())).toBe(true);
+ });
+
+ it("rejects a bare ULID, a wrong length, or a non-Crockford character", () => {
+ const body = createEventId().slice(EVENT_ID_PREFIX.length);
+
+ expect(isEventId(body)).toBe(false);
+ expect(isEventId(`${EVENT_ID_PREFIX}${body.slice(1)}`)).toBe(false);
+ expect(isEventId(`${EVENT_ID_PREFIX}U${body.slice(1)}`)).toBe(false);
+ });
+});
diff --git a/packages/eve/src/protocol/event-id.ts b/packages/eve/src/protocol/event-id.ts
new file mode 100644
index 000000000..aa192b7bf
--- /dev/null
+++ b/packages/eve/src/protocol/event-id.ts
@@ -0,0 +1,24 @@
+import { createUlid, isUlid } from "#shared/ulid.js";
+
+/** Prefix stamped on every eve session stream event id. */
+export const EVENT_ID_PREFIX = "evt_";
+
+/**
+ * Mints the id carried on one session stream event's `meta.id`:
+ * {@link EVENT_ID_PREFIX} followed by a ULID.
+ *
+ * See `#shared/ulid.js` for the ordering guarantee — it holds within a
+ * process, not across the separate steps of one session.
+ */
+export function createEventId(): string {
+ return `${EVENT_ID_PREFIX}${createUlid()}`;
+}
+
+/**
+ * Returns true when `value` has the shape {@link createEventId} produces.
+ *
+ * Shape-only: this does not prove eve minted the id.
+ */
+export function isEventId(value: string): boolean {
+ return value.startsWith(EVENT_ID_PREFIX) && isUlid(value.slice(EVENT_ID_PREFIX.length));
+}
diff --git a/packages/eve/src/protocol/message.test.ts b/packages/eve/src/protocol/message.test.ts
index 7b37347e6..9e1b9a1e5 100644
--- a/packages/eve/src/protocol/message.test.ts
+++ b/packages/eve/src/protocol/message.test.ts
@@ -14,13 +14,14 @@ import {
createStepStartedEvent,
createTurnCancelledEvent,
encodeMessageStreamEvent,
- timestampHandleMessageStreamEvent,
+ stampMessageStreamEvent,
} from "#protocol/message.js";
+import { isEventId } from "#protocol/event-id.js";
import { createEveConnectionCallbackRoutePath } from "#protocol/routes.js";
describe("message stream protocol", () => {
it("pins the stream version for timed session events", () => {
- expect(EVE_MESSAGE_STREAM_VERSION).toBe("19");
+ expect(EVE_MESSAGE_STREAM_VERSION).toBe("20");
});
it("publishes the channel-local continuation token on session.waiting", () => {
@@ -59,24 +60,24 @@ describe("message stream protocol", () => {
});
});
- it("stamps durable timing metadata and preserves it through encoding", () => {
- const timed = timestampHandleMessageStreamEvent(
- createStepStartedEvent({
- sequence: 0,
- stepIndex: 1,
- turnId: "turn_0",
- }),
- "2026-04-17T10:14:22.123Z",
+ it("stamps durable envelope metadata and preserves it through encoding", () => {
+ const stamped = stampMessageStreamEvent(
+ createStepStartedEvent({ sequence: 0, stepIndex: 1, turnId: "turn_0" }),
);
- expect(timed.meta).toEqual({
- at: "2026-04-17T10:14:22.123Z",
- });
+ expect(isEventId(stamped.meta.id)).toBe(true);
+ expect(stamped.meta.at).toBe(new Date(stamped.meta.at).toISOString());
+
+ const encoded = encodeMessageStreamEvent(stamped);
+ const decoded = JSON.parse(new TextDecoder().decode(encoded).trim()) as typeof stamped;
+
+ expect(decoded).toEqual(stamped);
+ });
- const encoded = encodeMessageStreamEvent(timed);
- const decoded = JSON.parse(new TextDecoder().decode(encoded).trim()) as typeof timed;
+ it("mints a distinct id for each emission of an identical payload", () => {
+ const event = createStepStartedEvent({ sequence: 0, stepIndex: 0, turnId: "turn_0" });
- expect(decoded).toEqual(timed);
+ expect(stampMessageStreamEvent(event).meta.id).not.toBe(stampMessageStreamEvent(event).meta.id);
});
it("builds authorization.required with optional challenge and webhookUrl", () => {
diff --git a/packages/eve/src/protocol/message.ts b/packages/eve/src/protocol/message.ts
index d782554f9..97b361c0e 100644
--- a/packages/eve/src/protocol/message.ts
+++ b/packages/eve/src/protocol/message.ts
@@ -6,6 +6,7 @@ import {
isSerializedUrlFilePart,
} from "#internal/attachments/url-refs.js";
import { decodeSandboxRef, isSandboxRefUrl } from "#internal/attachments/sandbox-refs.js";
+import { createEventId } from "#protocol/event-id.js";
import type { ConnectionAuthorizationChallenge } from "#public/connections/errors.js";
import type { RuntimeActionRequest, RuntimeActionResult } from "#runtime/actions/types.js";
import type { InputRequest, InputResponse } from "#runtime/input/types.js";
@@ -18,7 +19,7 @@ export const EVE_STREAM_TAIL_INDEX_HEADER = "x-eve-stream-tail-index";
export const EVE_STREAM_VERSION_HEADER = "x-eve-stream-version";
export const EVE_MESSAGE_STREAM_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
export const EVE_MESSAGE_STREAM_FORMAT = "ndjson";
-export const EVE_MESSAGE_STREAM_VERSION = "19";
+export const EVE_MESSAGE_STREAM_VERSION = "20";
/**
* eve-owned finish reason for one completed assistant step.
@@ -47,11 +48,21 @@ export interface StepCompletedProviderMetadata {
/**
* Durable metadata attached to one persisted session stream event.
*
- * Runtime code stamps this immediately before writing the event to the
- * workflow-owned stream so replay preserves the original timing.
+ * Stamped once, immediately before the event is written to the workflow-owned
+ * stream, and stored with it. Re-reading the stream — reconnecting, rewinding,
+ * or replaying a finished session — yields the same values every time.
*/
-export interface HandleMessageStreamEventMeta {
+export interface MessageStreamEventMeta {
+ /** ISO-8601 emission time. */
readonly at: string;
+ /**
+ * Unique, lexicographically sortable identifier for this event.
+ *
+ * Stamped from stream version 20 on: rewinding into a session that started
+ * before the upgrade yields events whose `id` is absent despite this type,
+ * and those cannot be deduplicated.
+ */
+ readonly id: string;
}
/**
@@ -282,7 +293,7 @@ export interface SubagentStartedStreamEvent {
export interface SubagentChildEventStreamEvent {
data: {
callId: string;
- event: HandleMessageStreamEvent;
+ event: UnstampedMessageStreamEvent;
subagentName: string;
};
type: "subagent.event";
@@ -581,9 +592,12 @@ export interface SessionCompletedStreamEvent {
}
/**
- * Serializable stream event union for the durable message session flow.
+ * Serializable event before eve stamps the durable stream envelope.
+ *
+ * Internal emitters use this type while constructing events. Public stream
+ * consumers receive {@link MessageStreamEvent}.
*/
-export type HandleMessageStreamEvent = (
+export type UnstampedMessageStreamEvent =
| CompactionCompletedStreamEvent
| CompactionRequestedStreamEvent
| AuthorizationCompletedStreamEvent
@@ -611,10 +625,7 @@ export type HandleMessageStreamEvent = (
| TurnCancelledStreamEvent
| TurnCompletedStreamEvent
| TurnFailedStreamEvent
- | TurnStartedStreamEvent
-) & {
- readonly meta?: HandleMessageStreamEventMeta;
-};
+ | TurnStartedStreamEvent;
/**
* Stream events that represent an unrecovered turn/session failure.
@@ -625,22 +636,26 @@ export type TurnFailureStreamEvent =
| TurnFailedStreamEvent;
/**
- * One public session stream event after runtime metadata has been stamped.
+ * One event read from an eve session stream.
*
- * Runtime/execution code owns this stamping boundary. Replays must preserve the
- * original `meta.at` value instead of recomputing it.
+ * eve stamps the durable identity and emission time before writing the event.
*/
-export type TimedHandleMessageStreamEvent = HandleMessageStreamEvent & {
- readonly meta: HandleMessageStreamEventMeta;
+export type MessageStreamEvent = UnstampedMessageStreamEvent & {
+ readonly meta: MessageStreamEventMeta;
};
+/**
+ * @deprecated Use {@link MessageStreamEvent}.
+ */
+export type HandleMessageStreamEvent = MessageStreamEvent;
+
const textEncoder = new TextEncoder();
/**
* Returns true when the current stream has reached a turn boundary or terminal
* session outcome.
*/
-export function isCurrentTurnBoundaryEvent(event: HandleMessageStreamEvent): boolean {
+export function isCurrentTurnBoundaryEvent(event: UnstampedMessageStreamEvent): boolean {
return (
event.type === "session.completed" ||
event.type === "session.failed" ||
@@ -650,10 +665,13 @@ export function isCurrentTurnBoundaryEvent(event: HandleMessageStreamEvent): boo
/**
* Narrows a stream event to the failure events that terminate or poison a turn.
+ *
+ * Generic so narrowing keeps the input's stamping: a
+ * {@link MessageStreamEvent} narrows to a stamped failure event.
*/
-export function isTurnFailureEvent(
- event: HandleMessageStreamEvent,
-): event is TurnFailureStreamEvent {
+export function isTurnFailureEvent<TEvent extends UnstampedMessageStreamEvent>(
+ event: TEvent,
+): event is TEvent & TurnFailureStreamEvent {
return (
event.type === "session.failed" || event.type === "step.failed" || event.type === "turn.failed"
);
@@ -1405,21 +1423,18 @@ export function createSessionCompletedEvent(): SessionCompletedStreamEvent {
}
/**
- * Stamps one session event with durable timing metadata immediately before it
- * is written to the workflow-owned stream.
+ * Stamps one session event with its durable identity and emission time.
*
- * Only runtime/execution code should call this. Keeping one stamping seam
- * ensures every persisted event shares the same clock contract and replay never
- * invents new timestamps.
- */
-export function timestampHandleMessageStreamEvent(
- event: HandleMessageStreamEvent,
- at = new Date().toISOString(),
-): TimedHandleMessageStreamEvent {
+ * Runtime/execution code only, once per event, immediately before the write.
+ * One stamping seam is what makes the persisted stream and authored hooks
+ * observe the same `meta.id`.
+ */
+export function stampMessageStreamEvent(event: UnstampedMessageStreamEvent): MessageStreamEvent {
return {
...event,
meta: {
- at,
+ at: new Date().toISOString(),
+ id: createEventId(),
},
};
}
@@ -1427,7 +1442,7 @@ export function timestampHandleMessageStreamEvent(
/**
* Encodes one message stream event as newline-delimited JSON.
*/
-export function encodeMessageStreamEvent(event: TimedHandleMessageStreamEvent): Uint8Array {
+export function encodeMessageStreamEvent(event: MessageStreamEvent): Uint8Array {
return textEncoder.encode(`${JSON.stringify(event)}\n`);
}
diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts
index 8fde03791..ef4aaf71e 100644
--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts
+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts
@@ -6,7 +6,7 @@ import { isCompiledChannel, type CompiledChannel } from "#channel/compiled-chann
import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
chatSdkChannel,
isNotImplemented,
@@ -70,17 +70,17 @@ const stubAlsContext = (() => {
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(stubAlsContext, () => callAdapterEventHandler(adapter, event, ctx));
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { type, data } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { type, data } as UnstampedMessageStreamEvent;
}
async function firePost(
diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts
index 2e635ad60..ce1411f5b 100644
--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts
+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts
@@ -2,7 +2,7 @@ import type { SessionAuthContext } from "#channel/types.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { ContextKey } from "#context/key.js";
import { createLogger, extractErrorId, formatErrorHint } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { InputRequest } from "#runtime/input/types.js";
import type {
ActionEvent,
@@ -44,8 +44,8 @@ const MAX_TYPING_STATUS = 80;
type ChatSdkAdapters = Record<string, Adapter>;
type ChatSdkSendInput = Parameters<SendFn<ChatSdkChannelState>>[0];
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
interface ActiveWebhookContext {
readonly send: SendFn<ChatSdkChannelState>;
diff --git a/packages/eve/src/public/channels/discord/discordChannel.test.ts b/packages/eve/src/public/channels/discord/discordChannel.test.ts
index 2ac1c4cef..714242a67 100644
--- a/packages/eve/src/public/channels/discord/discordChannel.test.ts
+++ b/packages/eve/src/public/channels/discord/discordChannel.test.ts
@@ -8,7 +8,7 @@ import { isCompiledChannel, type CompiledChannel } from "#channel/compiled-chann
import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
DISCORD_HITL_FREEFORM_TEXT_INPUT_ID,
renderInputRequestComponents,
@@ -45,9 +45,9 @@ const stubAlsContext = (() => {
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(stubAlsContext, () => callAdapterEventHandler(adapter, event, ctx));
}
@@ -73,11 +73,11 @@ function captureAccessor(initialContinuationToken: string): {
};
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { type, data } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { type, data } as UnstampedMessageStreamEvent;
}
function testKeys(): { privateKey: KeyObject; publicKeyHex: string } {
diff --git a/packages/eve/src/public/channels/discord/discordChannel.ts b/packages/eve/src/public/channels/discord/discordChannel.ts
index 1e0386357..da5392438 100644
--- a/packages/eve/src/public/channels/discord/discordChannel.ts
+++ b/packages/eve/src/public/channels/discord/discordChannel.ts
@@ -5,7 +5,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { ChannelSessionOps } from "#public/definitions/channel.js";
import { createLogger, logError } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
callDiscordApi,
createDiscordFollowupMessage,
@@ -52,8 +52,8 @@ import { defineChannel, POST, type Channel, type SendFn } from "#public/definiti
const log = createLogger("discord.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/** Pre-dispatch Discord context passed to inbound command hooks. */
export interface DiscordContext {
@@ -113,7 +113,7 @@ export type DiscordCommandResult = {
/** Sync or async {@link DiscordCommandResult}. */
export type DiscordCommandResultOrPromise = DiscordCommandResult | Promise<DiscordCommandResult>;
-type DiscordEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type DiscordEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: DiscordEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/channels/github/githubChannel.test.ts b/packages/eve/src/public/channels/github/githubChannel.test.ts
index bd72030ce..62c7bc8d6 100644
--- a/packages/eve/src/public/channels/github/githubChannel.test.ts
+++ b/packages/eve/src/public/channels/github/githubChannel.test.ts
@@ -7,7 +7,7 @@ import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SandboxKey, SessionKey } from "#context/keys.js";
import { mockSandbox, type MockSandbox } from "#internal/testing/mocks/mock-sandbox.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
clearGitHubInstallationTokenCache,
seedGitHubInstallationTokenForTests,
@@ -81,21 +81,21 @@ const stubAlsContext = createAlsContext();
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
sandbox?: MockSandbox,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(
sandbox === undefined ? stubAlsContext : createAlsContext(sandbox),
() => callAdapterEventHandler(adapter, event, ctx),
);
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { data, type } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { data, type } as UnstampedMessageStreamEvent;
}
function signedRequest(event: string, payload: Record<string, unknown>): Request {
diff --git a/packages/eve/src/public/channels/github/githubChannel.ts b/packages/eve/src/public/channels/github/githubChannel.ts
index bf41a6397..06c7bbec7 100644
--- a/packages/eve/src/public/channels/github/githubChannel.ts
+++ b/packages/eve/src/public/channels/github/githubChannel.ts
@@ -4,7 +4,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { ChannelSessionOps } from "#public/definitions/channel.js";
import { createLogger } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
buildGitHubBinding,
type GitHubHandle,
@@ -50,8 +50,8 @@ import { defineChannel, POST, type Channel } from "#public/definitions/channel.j
const log = createLogger("github.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/**
* Target accepted by `receive(github, { target })` for proactive sessions.
@@ -112,7 +112,7 @@ export type GitHubInboundResult = {
*/
export type GitHubInboundResultOrPromise = GitHubInboundResult | Promise<GitHubInboundResult>;
-type GitHubEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type GitHubEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: GitHubEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/channels/linear/linearChannel.test.ts b/packages/eve/src/public/channels/linear/linearChannel.test.ts
index eff91db1f..0d3f23366 100644
--- a/packages/eve/src/public/channels/linear/linearChannel.test.ts
+++ b/packages/eve/src/public/channels/linear/linearChannel.test.ts
@@ -6,7 +6,7 @@ import { isCompiledChannel, type CompiledChannel } from "#channel/compiled-chann
import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { linearChannel, type LinearChannelState } from "#public/channels/linear/linearChannel.js";
import { signLinearWebhookBody } from "#public/channels/linear/verify.js";
import type { InputRequest } from "#runtime/input/types.js";
@@ -45,17 +45,17 @@ const stubAlsContext = (() => {
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(stubAlsContext, () => callAdapterEventHandler(adapter, event, ctx));
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { data, type } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { data, type } as UnstampedMessageStreamEvent;
}
function jsonResponse(body: unknown, init?: ResponseInit): Response {
diff --git a/packages/eve/src/public/channels/linear/linearChannel.ts b/packages/eve/src/public/channels/linear/linearChannel.ts
index f0399b8ba..0ba6e6c7f 100644
--- a/packages/eve/src/public/channels/linear/linearChannel.ts
+++ b/packages/eve/src/public/channels/linear/linearChannel.ts
@@ -1,7 +1,7 @@
import type { SessionHandle } from "#channel/session.js";
import type { SessionAuthContext } from "#channel/types.js";
import { createLogger } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
createLinearAgentActivity,
createLinearAgentSessionOnComment,
@@ -39,8 +39,8 @@ import type { JsonObject } from "#shared/json.js";
const log = createLogger("linear.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/** JSON-serializable state for one Linear Agent Session conversation. */
export interface LinearChannelState {
@@ -124,7 +124,7 @@ export interface LinearHandle {
): Promise<{ readonly success: boolean }>;
}
-type LinearEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type LinearEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: LinearEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/channels/slack/slackChannel.test.ts b/packages/eve/src/public/channels/slack/slackChannel.test.ts
index 630e27a9f..7964be8be 100644
--- a/packages/eve/src/public/channels/slack/slackChannel.test.ts
+++ b/packages/eve/src/public/channels/slack/slackChannel.test.ts
@@ -8,7 +8,7 @@ import { isCompiledChannel, type CompiledChannel } from "#channel/compiled-chann
import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { decodeSlackApiBody } from "#public/channels/slack/api-encoding.js";
import {
HITL_ACTION_PREFIX,
@@ -78,9 +78,9 @@ const stubAlsContext = (() => {
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(stubAlsContext, () => callAdapterEventHandler(adapter, event, ctx));
}
@@ -115,11 +115,11 @@ function captureAccessor(initialContinuationToken: string): {
};
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { type, data } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { type, data } as UnstampedMessageStreamEvent;
}
const THREAD_STATE = {
diff --git a/packages/eve/src/public/channels/slack/slackChannel.ts b/packages/eve/src/public/channels/slack/slackChannel.ts
index 7399bf6b9..e64566e71 100644
--- a/packages/eve/src/public/channels/slack/slackChannel.ts
+++ b/packages/eve/src/public/channels/slack/slackChannel.ts
@@ -8,7 +8,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { ChannelSessionOps } from "#public/definitions/channel.js";
import { createLogger, logError } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
buildSlackBinding,
buildSlackWorkspaceHandle,
@@ -69,8 +69,8 @@ import { markEventHandled } from "./utils.js";
const log = createLogger("slack.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/**
* Base Slack context for inbound webhook handlers. These hooks run before the
@@ -111,7 +111,7 @@ export type {
} from "#public/channels/slack/api.js";
export type { SlackWebhookVerifier } from "#public/channels/slack/verify.js";
-type SlackEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type SlackEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: SlackEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/channels/teams/teamsChannel.ts b/packages/eve/src/public/channels/teams/teamsChannel.ts
index 430a8e717..9abcc8eb4 100644
--- a/packages/eve/src/public/channels/teams/teamsChannel.ts
+++ b/packages/eve/src/public/channels/teams/teamsChannel.ts
@@ -5,7 +5,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { ChannelSessionOps } from "#public/definitions/channel.js";
import { createLogger, logError } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
buildTeamsTurnMessage,
collectTeamsFileParts,
@@ -59,8 +59,8 @@ import { defineChannel, POST, type Channel, type SendFn } from "#public/definiti
const log = createLogger("teams.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/** Pre-dispatch Teams context passed to invoke hooks. */
export interface TeamsContext {
@@ -149,7 +149,7 @@ export type TeamsInvokeResult = Record<string, unknown> | Response | null | unde
/** Sync or async {@link TeamsInvokeResult}. */
export type TeamsInvokeResultOrPromise = TeamsInvokeResult | Promise<TeamsInvokeResult>;
-type TeamsEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type TeamsEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: TeamsEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/channels/telegram/telegramChannel.test.ts b/packages/eve/src/public/channels/telegram/telegramChannel.test.ts
index bb9b9ddb7..d7e10e4e3 100644
--- a/packages/eve/src/public/channels/telegram/telegramChannel.test.ts
+++ b/packages/eve/src/public/channels/telegram/telegramChannel.test.ts
@@ -6,7 +6,7 @@ import { isCompiledChannel, type CompiledChannel } from "#channel/compiled-chann
import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { telegramChannel, type TelegramChannelState } from "#public/channels/telegram/index.js";
const SECRET = "telegram-secret";
@@ -41,17 +41,17 @@ const stubAlsContext = (() => {
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(stubAlsContext, () => callAdapterEventHandler(adapter, event, ctx));
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { type, data } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { type, data } as UnstampedMessageStreamEvent;
}
function signedRequest(body: string): Request {
diff --git a/packages/eve/src/public/channels/telegram/telegramChannel.ts b/packages/eve/src/public/channels/telegram/telegramChannel.ts
index 9cc497679..9e6ab0976 100644
--- a/packages/eve/src/public/channels/telegram/telegramChannel.ts
+++ b/packages/eve/src/public/channels/telegram/telegramChannel.ts
@@ -6,7 +6,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { ChannelSessionOps } from "#public/definitions/channel.js";
import { isCompiledChannel } from "#channel/compiled-channel.js";
import { createLogger, logError } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
answerTelegramCallbackQuery,
callTelegramApi,
@@ -57,8 +57,8 @@ import { parseJsonObject, type JsonObject } from "#shared/json.js";
const log = createLogger("telegram.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/** Minimal Telegram context (only `telegram`, no `state` or session ops), passed to `onMessage` and `onCallbackQuery` hooks before a session exists. Event handlers receive the richer {@link TelegramEventContext}. */
export interface TelegramContext {
@@ -113,7 +113,7 @@ export type TelegramInboundResult = {
/** Sync or async {@link TelegramInboundResult}. */
export type TelegramInboundResultOrPromise = TelegramInboundResult | Promise<TelegramInboundResult>;
-type TelegramEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type TelegramEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: TelegramEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/channels/twilio/twilioChannel.test.ts b/packages/eve/src/public/channels/twilio/twilioChannel.test.ts
index c771cdd68..320f58de0 100644
--- a/packages/eve/src/public/channels/twilio/twilioChannel.test.ts
+++ b/packages/eve/src/public/channels/twilio/twilioChannel.test.ts
@@ -6,7 +6,7 @@ import { isCompiledChannel, type CompiledChannel } from "#channel/compiled-chann
import { isHttpRouteDefinition } from "#channel/routes.js";
import { ContextContainer, contextStorage } from "#context/container.js";
import { SessionKey } from "#context/keys.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import type { TwilioTextMessage } from "#public/channels/twilio/inbound.js";
import { twilioChannel, type TwilioContext } from "#public/channels/twilio/twilioChannel.js";
import { signTwilioRequest } from "#public/channels/twilio/verify.js";
@@ -47,17 +47,17 @@ const stubAlsContext = (() => {
function callEvent(
adapter: ChannelAdapter,
- event: HandleMessageStreamEvent,
+ event: UnstampedMessageStreamEvent,
ctx: any,
-): Promise<HandleMessageStreamEvent> {
+): Promise<UnstampedMessageStreamEvent> {
return contextStorage.run(stubAlsContext, () => callAdapterEventHandler(adapter, event, ctx));
}
-function makeEvent<T extends HandleMessageStreamEvent["type"]>(
+function makeEvent<T extends UnstampedMessageStreamEvent["type"]>(
type: T,
data: unknown,
-): HandleMessageStreamEvent {
- return { type, data } as HandleMessageStreamEvent;
+): UnstampedMessageStreamEvent {
+ return { type, data } as UnstampedMessageStreamEvent;
}
function signedFormRequest(path: string, params: URLSearchParams): Request {
diff --git a/packages/eve/src/public/channels/twilio/twilioChannel.ts b/packages/eve/src/public/channels/twilio/twilioChannel.ts
index 1ce70452f..41b4278a3 100644
--- a/packages/eve/src/public/channels/twilio/twilioChannel.ts
+++ b/packages/eve/src/public/channels/twilio/twilioChannel.ts
@@ -5,7 +5,7 @@ import type { SessionContext } from "#public/definitions/callback-context.js";
import type { ChannelSessionOps } from "#public/definitions/channel.js";
import { createLogger } from "#internal/logging.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import {
callTwilioApi,
sendTwilioMessage,
@@ -52,8 +52,8 @@ import {
const log = createLogger("twilio.channel");
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/** Pre-dispatch Twilio context passed to the inbound text, voice, and voice-transcription hooks. */
export interface TwilioContext {
@@ -144,7 +144,7 @@ export type TwilioVoiceResultOrPromise =
| undefined
| Promise<TwilioVoiceResult | null | undefined>;
-type TwilioEventHandler<T extends HandleMessageStreamEvent["type"]> = (
+type TwilioEventHandler<T extends UnstampedMessageStreamEvent["type"]> = (
data: EventData<T>,
channel: TwilioEventContext,
ctx: SessionContext,
diff --git a/packages/eve/src/public/definitions/channel.ts b/packages/eve/src/public/definitions/channel.ts
index a96d8d01d..7e0b09579 100644
--- a/packages/eve/src/public/definitions/channel.ts
+++ b/packages/eve/src/public/definitions/channel.ts
@@ -16,7 +16,7 @@ import type {
RunInput,
} from "#channel/types.js";
import { buildCallbackContext } from "#context/build-callback-context.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent, MessageStreamEvent } from "#protocol/message.js";
import type { SessionContext } from "#public/definitions/callback-context.js";
import type { GenericChannelDefinition, GenericReceiveInput } from "#shared/channel-definition.js";
@@ -160,7 +160,7 @@ export interface Agent {
getEventStream(
sessionId: string,
options?: GetEventStreamOptions,
- ): Promise<ReadableStream<HandleMessageStreamEvent>>;
+ ): Promise<ReadableStream<MessageStreamEvent>>;
}
/**
@@ -201,8 +201,8 @@ export function isDisabledRouteSentinel(value: unknown): value is DisabledRouteS
);
}
-type EventData<T extends HandleMessageStreamEvent["type"]> =
- Extract<HandleMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
+type EventData<T extends UnstampedMessageStreamEvent["type"]> =
+ Extract<UnstampedMessageStreamEvent, { type: T }> extends { data: infer D } ? D : undefined;
/**
* Session operations on the `channel` argument of every channel event handler.
@@ -218,7 +218,7 @@ export interface ChannelSessionOps {
*/
export type ChannelContext<TCtx> = TCtx & ChannelSessionOps;
-type ChannelEventHandler<T extends HandleMessageStreamEvent["type"], TCtx> = (
+type ChannelEventHandler<T extends UnstampedMessageStreamEvent["type"], TCtx> = (
data: EventData<T>,
channel: ChannelContext<TCtx>,
ctx: SessionContext,
diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.ts
index 23a9e0185..0145c2e1b 100644
--- a/packages/eve/src/public/definitions/exact.test.ts
+++ b/packages/eve/src/public/definitions/exact.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, expectTypeOf, it } from "vitest";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { defineAgent } from "#public/definitions/agent.js";
import { none } from "#public/channels/auth.js";
import { eveChannel, defaultEveAuth } from "#public/channels/eve.js";
@@ -42,7 +42,7 @@ describe("definition helper exact inputs", () => {
});
it("keeps the public hook event map aligned with runtime stream events", () => {
- expectTypeOf<keyof HookEventMap>().toEqualTypeOf<HandleMessageStreamEvent["type"]>();
+ expectTypeOf<keyof HookEventMap>().toEqualTypeOf<UnstampedMessageStreamEvent["type"]>();
});
});
diff --git a/packages/eve/src/public/definitions/hook.ts b/packages/eve/src/public/definitions/hook.ts
index 2a9abb4dd..30d256b7c 100644
--- a/packages/eve/src/public/definitions/hook.ts
+++ b/packages/eve/src/public/definitions/hook.ts
@@ -1,9 +1,10 @@
-import type { HandleMessageStreamEvent } from "../../protocol/message.js";
+import type { MessageStreamEvent } from "../../protocol/message.js";
import type { SessionContext } from "./callback-context.js";
import type { ExactDefinition } from "./exact.js";
-type ProtocolEvent<TType extends HandleMessageStreamEvent["type"]> = Extract<
- HandleMessageStreamEvent,
+// Stamped, so a hook can read `event.meta` unguarded.
+type ProtocolEvent<TType extends MessageStreamEvent["type"]> = Extract<
+ MessageStreamEvent,
{ type: TType }
>;
diff --git a/packages/eve/src/react/use-eve-agent.test.ts b/packages/eve/src/react/use-eve-agent.test.ts
index 37fdec7ea..e0d98169a 100644
--- a/packages/eve/src/react/use-eve-agent.test.ts
+++ b/packages/eve/src/react/use-eve-agent.test.ts
@@ -12,8 +12,9 @@ import {
createSessionWaitingEvent,
createStepFailedEvent,
createTurnFailedEvent,
- type HandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
+import { stampTestEvents } from "#internal/testing/events.js";
import type { SessionState } from "#client/types.js";
function createStartedMessageResponse(sessionId: string, continuationToken: string): Response {
@@ -26,13 +27,13 @@ function createStartedMessageResponse(sessionId: string, continuationToken: stri
});
}
-function createEagerStreamResponse(events: readonly HandleMessageStreamEvent[]): Response {
+function createEagerStreamResponse(events: readonly UnstampedMessageStreamEvent[]): Response {
const encoder = new TextEncoder();
return new Response(
new ReadableStream<Uint8Array>({
start(controller) {
- for (const event of events) {
+ for (const event of stampTestEvents(events)) {
controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
}
controller.close();
@@ -163,7 +164,7 @@ describe("useEveAgent", () => {
.mockReturnValueOnce(startResponse.promise)
.mockResolvedValueOnce(createEagerStreamResponse(events));
- const seenEvents: HandleMessageStreamEvent[] = [];
+ const seenEvents: UnstampedMessageStreamEvent[] = [];
const seenSessions: SessionState[] = [];
let helpers: UseEveAgentHelpers<EveMessageData> | undefined;
@@ -199,7 +200,7 @@ describe("useEveAgent", () => {
});
expect(fetchMock).toHaveBeenCalledTimes(2);
- expect(seenEvents).toEqual(events);
+ expect(seenEvents).toEqual(stampTestEvents(events));
expect(seenSessions).toEqual([
{
continuationToken: "http:session_1",
@@ -481,7 +482,7 @@ describe("useEveAgent", () => {
expect(seenErrors.map((error) => error.name)).toEqual(["MODEL_CALL_FAILED"]);
expect(helpers?.status).toBe("error");
expect(helpers?.error?.message).toBe("Bad Request");
- expect(helpers?.events).toEqual(events);
+ expect(helpers?.events).toEqual(stampTestEvents(events));
expect(helpers?.data).toEqual(
completedTurnData({
turnId: "turn_1",
@@ -548,7 +549,7 @@ describe("useEveAgent", () => {
expect(seenErrors).toEqual([]);
expect(helpers?.status).toBe("ready");
expect(helpers?.error).toBeUndefined();
- expect(helpers?.events).toEqual(events);
+ expect(helpers?.events).toEqual(stampTestEvents(events));
});
it("projects input responses before the resumed stream returns", async () => {
diff --git a/packages/eve/src/react/use-eve-agent.ts b/packages/eve/src/react/use-eve-agent.ts
index 5b8e9ffaa..7e9bdc029 100644
--- a/packages/eve/src/react/use-eve-agent.ts
+++ b/packages/eve/src/react/use-eve-agent.ts
@@ -11,7 +11,7 @@ import { resolveEveAgentHost } from "#client/agent-host.js";
import type { EveAgentReducer } from "#client/reducer.js";
import type { ClientSession } from "#client/session.js";
import { defaultMessageReducer, 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 };
@@ -75,7 +75,8 @@ export interface UseEveAgentOptions<TData> extends EveAgentStoreCallbacks<TData>
* @default ""
*/
readonly host?: string;
- readonly initialEvents?: readonly HandleMessageStreamEvent[];
+ /** Ordered prefix of the session stream used to rehydrate projected state. */
+ readonly initialEvents?: readonly MessageStreamEvent[];
readonly initialSession?: SessionState;
/**
* Project submitted user messages before eve confirms them with a
diff --git a/packages/eve/src/runtime/hooks/registry.ts b/packages/eve/src/runtime/hooks/registry.ts
index b223a7c68..99db43c21 100644
--- a/packages/eve/src/runtime/hooks/registry.ts
+++ b/packages/eve/src/runtime/hooks/registry.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { StreamEventHook } from "../../public/definitions/hook.js";
import type { ResolvedHookDefinition } from "../types.js";
@@ -10,7 +10,7 @@ import type { ResolvedHookDefinition } from "../types.js";
*/
interface RuntimeStreamEventHookEntry {
readonly slug: string;
- readonly handler: StreamEventHook<HandleMessageStreamEvent>;
+ readonly handler: StreamEventHook<MessageStreamEvent>;
readonly eventType: string;
}
diff --git a/packages/eve/src/runtime/resolve-hook.ts b/packages/eve/src/runtime/resolve-hook.ts
index 2e22fa685..2fffa508f 100644
--- a/packages/eve/src/runtime/resolve-hook.ts
+++ b/packages/eve/src/runtime/resolve-hook.ts
@@ -1,7 +1,7 @@
import type { CompiledHookDefinition } from "../compiler/manifest.js";
import type { CompiledModuleMap } from "../compiler/module-map.js";
import { expectFunction, expectObjectRecord } from "../internal/authored-module.js";
-import type { HandleMessageStreamEvent } from "../protocol/message.js";
+import type { MessageStreamEvent } from "../protocol/message.js";
import type { StreamEventHook } from "../public/definitions/hook.js";
import { toErrorMessage } from "../shared/errors.js";
import { loadResolvedModuleExport, ResolveAgentError } from "./resolve-helpers.js";
@@ -33,7 +33,7 @@ export async function resolveHookDefinition(
describe(definition, "to return an object"),
);
- const events: Record<string, StreamEventHook<HandleMessageStreamEvent>> = {};
+ const events: Record<string, StreamEventHook<MessageStreamEvent>> = {};
const eventsRaw = resolvedRecord.events;
if (eventsRaw !== undefined) {
@@ -47,7 +47,7 @@ export async function resolveHookDefinition(
value,
describe(definition, `to provide a function for "events.${key}"`),
);
- events[key] = handler as StreamEventHook<HandleMessageStreamEvent>;
+ events[key] = handler as StreamEventHook<MessageStreamEvent>;
}
}
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index 8e10abea7..fc8771bbe 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -3,7 +3,7 @@ import type { CompiledChannel } from "#channel/compiled-channel.js";
import type { NormalizedChannelCorsOptions } from "#channel/cors.js";
import type { HeadersValue } from "#client/types.js";
import type { DiscoverDiagnosticsSummary } from "#discover/diagnostics.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { ChannelRouteMethod, RouteContext } from "#public/definitions/channel.js";
import type { RouteHandler, WebSocketRouteHandler } from "#channel/routes.js";
import type { OutboundAuthFn } from "#public/agents/auth.js";
@@ -210,7 +210,7 @@ export interface ResolvedHookDefinition extends ResolvedModuleSourceRef {
* wildcard if declared. Unknown keys are accepted at resolve time
* and ignored at dispatch time.
*/
- readonly events: Readonly<Record<string, StreamEventHook<HandleMessageStreamEvent>>>;
+ readonly events: Readonly<Record<string, StreamEventHook<MessageStreamEvent>>>;
}
/**
diff --git a/packages/eve/src/setup/scaffold/create/web-template.ts b/packages/eve/src/setup/scaffold/create/web-template.ts
index d0f09469b..f70d6721d 100644
--- a/packages/eve/src/setup/scaffold/create/web-template.ts
+++ b/packages/eve/src/setup/scaffold/create/web-template.ts
@@ -5,7 +5,7 @@ export const WEB_APP_TEMPLATE_FILES = {
"agent/channels/eve.ts":
'import { eveChannel } from "eve/channels/eve";\nimport { localDev, placeholderAuth, vercelOidc } from "eve/channels/auth";\n\nexport default eveChannel({\n auth: [\n // Lets the eve TUI and your Vercel deployments reach the deployed agent.\n vercelOidc(),\n // Open on localhost for `eve dev` and the REPL; ignored in production.\n localDev(),\n // This placeholder will not allow browser requests in production.\n // Replace it with your app\'s auth provider, like Auth.js or Clerk,\n // or use none() for a public demo.\n placeholderAuth(),\n ],\n});\n',
"app/_components/agent-chat.tsx":
- '"use client";\n\nimport type { UserContent } from "ai";\nimport { Client, type HandleMessageStreamEvent } from "eve/client";\nimport { useEveAgent } from "eve/react";\nimport { AlertCircleIcon } from "lucide-react";\nimport { useCallback, useRef, useState } from "react";\nimport {\n Conversation,\n ConversationContent,\n ConversationScrollButton,\n} from "@/components/ai-elements/conversation";\nimport {\n PromptInput,\n type PromptInputMessage,\n PromptInputSubmit,\n PromptInputTextarea,\n} from "@/components/ai-elements/prompt-input";\nimport { cn } from "@/lib/utils";\nimport { AgentMessage } from "./agent-message";\n\nconst AGENT_NAME = "__EVE_INIT_APP_NAME__";\n\ntype AgentStatus = ReturnType<typeof useEveAgent>["status"];\ntype CancellationState = "idle" | "requested" | "cancelling";\n\ntype Cancellation = {\n requested: boolean;\n sentTurnId?: string;\n turnId?: string;\n};\n\nexport function AgentChat() {\n const [session] = useState(() =>\n new Client({ host: "", preserveCompletedSessions: true }).session(),\n );\n const cancellationRef = useRef<Cancellation>({ requested: false });\n const [cancellationError, setCancellationError] = useState<string>();\n const [cancellationState, setCancellationState] = useState<CancellationState>("idle");\n\n const cancelTurn = useCallback(\n (turnId: string) => {\n const cancellation = cancellationRef.current;\n if (!cancellation.requested || cancellation.sentTurnId === turnId) {\n return;\n }\n\n cancellation.sentTurnId = turnId;\n setCancellationState("cancelling");\n\n void session.cancel({ turnId }).catch((error: unknown) => {\n if (cancellationRef.current !== cancellation) {\n return;\n }\n\n cancellation.requested = false;\n cancellation.sentTurnId = undefined;\n setCancellationError(toErrorMessage(error));\n setCancellationState("idle");\n });\n },\n [session],\n );\n\n const handleEvent = useCallback(\n (event: HandleMessageStreamEvent) => {\n if (event.type !== "turn.started") {\n return;\n }\n\n const cancellation = cancellationRef.current;\n cancellation.turnId = event.data.turnId;\n cancelTurn(event.data.turnId);\n },\n [cancelTurn],\n );\n\n const agent = useEveAgent({ onEvent: handleEvent, session });\n const isBusy = agent.status === "submitted" || agent.status === "streaming";\n const isEmpty = agent.data.messages.length === 0;\n const errorMessage = cancellationError ?? agent.error?.message;\n const submitStatus = isBusy && cancellationState !== "idle" ? "submitted" : agent.status;\n\n const prepareTurn = () => {\n cancellationRef.current = { requested: false };\n setCancellationError(undefined);\n setCancellationState("idle");\n };\n\n const requestCancellation = () => {\n if (!isBusy || cancellationState !== "idle") {\n return;\n }\n\n const cancellation = cancellationRef.current;\n cancellation.requested = true;\n setCancellationError(undefined);\n setCancellationState("requested");\n\n if (cancellation.turnId !== undefined) {\n cancelTurn(cancellation.turnId);\n }\n };\n\n const handleSubmit = async (message: PromptInputMessage) => {\n const text = message.text.trim();\n if ((text.length === 0 && message.files.length === 0) || isBusy) return;\n\n prepareTurn();\n\n if (message.files.length === 0) {\n await agent.send({ message: text });\n return;\n }\n\n const parts: UserContent = [];\n if (text.length > 0) {\n parts.push({ text, type: "text" });\n }\n for (const file of message.files) {\n parts.push({\n data: file.url,\n filename: file.filename,\n mediaType: file.mediaType,\n type: "file",\n });\n }\n\n await agent.send({ message: parts });\n };\n\n const composer = (\n <PromptInput onSubmit={handleSubmit}>\n <PromptInputTextarea placeholder="Send a message…" />\n <PromptInputSubmit onStop={requestCancellation} status={submitStatus} />\n </PromptInput>\n );\n\n return (\n <main className="flex h-dvh flex-col overflow-hidden bg-background text-foreground">\n {isEmpty ? null : (\n <header className="flex h-14 shrink-0 items-center justify-center gap-3 pl-4 pr-2">\n <span className="flex min-w-0 items-center gap-2">\n <span className="truncate text-muted-foreground text-sm">{AGENT_NAME}</span>\n <StatusDot status={agent.status} />\n </span>\n </header>\n )}\n\n {errorMessage ? (\n <div className="mx-auto w-full max-w-3xl shrink-0 px-4 pt-2 sm:px-6">\n <div className="flex items-start gap-3 rounded-lg border border-destructive/30 bg-destructive/5 px-3 py-2.5 text-sm">\n <AlertCircleIcon className="mt-0.5 size-4 shrink-0 text-destructive" />\n <div>\n <p className="font-medium">Request failed</p>\n <p className="mt-0.5 text-muted-foreground">{errorMessage}</p>\n </div>\n </div>\n </div>\n ) : null}\n\n {isEmpty ? null : (\n <Conversation className="min-h-0 flex-1">\n <ConversationContent className="mx-auto w-full max-w-3xl gap-6 px-4 py-6 sm:px-6">\n {agent.data.messages.map((message, index) => (\n <AgentMessage\n canRespond={!isBusy}\n isStreaming={\n agent.status === "streaming" && index === agent.data.messages.length - 1\n }\n key={message.id}\n message={message}\n onInputResponses={(inputResponses) => {\n prepareTurn();\n return agent.send({ inputResponses });\n }}\n />\n ))}\n </ConversationContent>\n <ConversationScrollButton />\n </Conversation>\n )}\n\n <div\n className={cn(\n "mx-auto w-full px-4 sm:px-6",\n isEmpty\n ? "flex max-w-xl flex-1 flex-col items-center justify-center gap-8 pb-[10vh]"\n : "max-w-3xl shrink-0 pb-6",\n )}\n >\n {isEmpty ? (\n <div className="flex flex-col items-center gap-3 text-center">\n <h1 className="font-medium text-5xl tracking-tighter">{AGENT_NAME}</h1>\n </div>\n ) : null}\n <div className="w-full">{composer}</div>\n </div>\n </main>\n );\n}\n\nfunction toErrorMessage(error: unknown): string {\n return error instanceof Error ? error.message : "Unable to cancel the response.";\n}\n\nfunction StatusDot({ status }: { readonly status: AgentStatus }) {\n const isLive = status === "submitted" || status === "streaming";\n const tone =\n status === "error"\n ? "bg-destructive"\n : isLive\n ? "bg-emerald-500"\n : status === "ready"\n ? "bg-muted-foreground"\n : "bg-muted-foreground/50";\n\n return (\n <span className="relative flex size-1">\n {isLive ? (\n <span\n className={cn(\n "absolute inline-flex size-full animate-ping rounded-full opacity-75",\n tone,\n )}\n />\n ) : null}\n <span className={cn("relative inline-flex size-1 rounded-full transition-colors", tone)} />\n </span>\n );\n}\n',
+ '"use client";\n\nimport type { UserContent } from "ai";\nimport { Client, type MessageStreamEvent } from "eve/client";\nimport { useEveAgent } from "eve/react";\nimport { AlertCircleIcon } from "lucide-react";\nimport { useCallback, useRef, useState } from "react";\nimport {\n Conversation,\n ConversationContent,\n ConversationScrollButton,\n} from "@/components/ai-elements/conversation";\nimport {\n PromptInput,\n type PromptInputMessage,\n PromptInputSubmit,\n PromptInputTextarea,\n} from "@/components/ai-elements/prompt-input";\nimport { cn } from "@/lib/utils";\nimport { AgentMessage } from "./agent-message";\n\nconst AGENT_NAME = "__EVE_INIT_APP_NAME__";\n\ntype AgentStatus = ReturnType<typeof useEveAgent>["status"];\ntype CancellationState = "idle" | "requested" | "cancelling";\n\ntype Cancellation = {\n requested: boolean;\n sentTurnId?: string;\n turnId?: string;\n};\n\nexport function AgentChat() {\n const [session] = useState(() =>\n new Client({ host: "", preserveCompletedSessions: true }).session(),\n );\n const cancellationRef = useRef<Cancellation>({ requested: false });\n const [cancellationError, setCancellationError] = useState<string>();\n const [cancellationState, setCancellationState] = useState<CancellationState>("idle");\n\n const cancelTurn = useCallback(\n (turnId: string) => {\n const cancellation = cancellationRef.current;\n if (!cancellation.requested || cancellation.sentTurnId === turnId) {\n return;\n }\n\n cancellation.sentTurnId = turnId;\n setCancellationState("cancelling");\n\n void session.cancel({ turnId }).catch((error: unknown) => {\n if (cancellationRef.current !== cancellation) {\n return;\n }\n\n cancellation.requested = false;\n cancellation.sentTurnId = undefined;\n setCancellationError(toErrorMessage(error));\n setCancellationState("idle");\n });\n },\n [session],\n );\n\n const handleEvent = useCallback(\n (event: MessageStreamEvent) => {\n if (event.type !== "turn.started") {\n return;\n }\n\n const cancellation = cancellationRef.current;\n cancellation.turnId = event.data.turnId;\n cancelTurn(event.data.turnId);\n },\n [cancelTurn],\n );\n\n const agent = useEveAgent({ onEvent: handleEvent, session });\n const isBusy = agent.status === "submitted" || agent.status === "streaming";\n const isEmpty = agent.data.messages.length === 0;\n const errorMessage = cancellationError ?? agent.error?.message;\n const submitStatus = isBusy && cancellationState !== "idle" ? "submitted" : agent.status;\n\n const prepareTurn = () => {\n cancellationRef.current = { requested: false };\n setCancellationError(undefined);\n setCancellationState("idle");\n };\n\n const requestCancellation = () => {\n if (!isBusy || cancellationState !== "idle") {\n return;\n }\n\n const cancellation = cancellationRef.current;\n cancellation.requested = true;\n setCancellationError(undefined);\n setCancellationState("requested");\n\n if (cancellation.turnId !== undefined) {\n cancelTurn(cancellation.turnId);\n }\n };\n\n const handleSubmit = async (message: PromptInputMessage) => {\n const text = message.text.trim();\n if ((text.length === 0 && message.files.length === 0) || isBusy) return;\n\n prepareTurn();\n\n if (message.files.length === 0) {\n await agent.send({ message: text });\n return;\n }\n\n const parts: UserContent = [];\n if (text.length > 0) {\n parts.push({ text, type: "text" });\n }\n for (const file of message.files) {\n parts.push({\n data: file.url,\n filename: file.filename,\n mediaType: file.mediaType,\n type: "file",\n });\n }\n\n await agent.send({ message: parts });\n };\n\n const composer = (\n <PromptInput onSubmit={handleSubmit}>\n <PromptInputTextarea placeholder="Send a message…" />\n <PromptInputSubmit onStop={requestCancellation} status={submitStatus} />\n </PromptInput>\n );\n\n return (\n <main className="flex h-dvh flex-col overflow-hidden bg-background text-foreground">\n {isEmpty ? null : (\n <header className="flex h-14 shrink-0 items-center justify-center gap-3 pl-4 pr-2">\n <span className="flex min-w-0 items-center gap-2">\n <span className="truncate text-muted-foreground text-sm">{AGENT_NAME}</span>\n <StatusDot status={agent.status} />\n </span>\n </header>\n )}\n\n {errorMessage ? (\n <div className="mx-auto w-full max-w-3xl shrink-0 px-4 pt-2 sm:px-6">\n <div className="flex items-start gap-3 rounded-lg border border-destructive/30 bg-destructive/5 px-3 py-2.5 text-sm">\n <AlertCircleIcon className="mt-0.5 size-4 shrink-0 text-destructive" />\n <div>\n <p className="font-medium">Request failed</p>\n <p className="mt-0.5 text-muted-foreground">{errorMessage}</p>\n </div>\n </div>\n </div>\n ) : null}\n\n {isEmpty ? null : (\n <Conversation className="min-h-0 flex-1">\n <ConversationContent className="mx-auto w-full max-w-3xl gap-6 px-4 py-6 sm:px-6">\n {agent.data.messages.map((message, index) => (\n <AgentMessage\n canRespond={!isBusy}\n isStreaming={\n agent.status === "streaming" && index === agent.data.messages.length - 1\n }\n key={message.id}\n message={message}\n onInputResponses={(inputResponses) => {\n prepareTurn();\n return agent.send({ inputResponses });\n }}\n />\n ))}\n </ConversationContent>\n <ConversationScrollButton />\n </Conversation>\n )}\n\n <div\n className={cn(\n "mx-auto w-full px-4 sm:px-6",\n isEmpty\n ? "flex max-w-xl flex-1 flex-col items-center justify-center gap-8 pb-[10vh]"\n : "max-w-3xl shrink-0 pb-6",\n )}\n >\n {isEmpty ? (\n <div className="flex flex-col items-center gap-3 text-center">\n <h1 className="font-medium text-5xl tracking-tighter">{AGENT_NAME}</h1>\n </div>\n ) : null}\n <div className="w-full">{composer}</div>\n </div>\n </main>\n );\n}\n\nfunction toErrorMessage(error: unknown): string {\n return error instanceof Error ? error.message : "Unable to cancel the response.";\n}\n\nfunction StatusDot({ status }: { readonly status: AgentStatus }) {\n const isLive = status === "submitted" || status === "streaming";\n const tone =\n status === "error"\n ? "bg-destructive"\n : isLive\n ? "bg-emerald-500"\n : status === "ready"\n ? "bg-muted-foreground"\n : "bg-muted-foreground/50";\n\n return (\n <span className="relative flex size-1">\n {isLive ? (\n <span\n className={cn(\n "absolute inline-flex size-full animate-ping rounded-full opacity-75",\n tone,\n )}\n />\n ) : null}\n <span className={cn("relative inline-flex size-1 rounded-full transition-colors", tone)} />\n </span>\n );\n}\n',
"app/_components/agent-message.tsx":
'"use client";\n\nimport type {\n EveAuthorizationPart,\n EveDynamicToolPart,\n EveMessage,\n EveMessagePart,\n} from "eve/react";\nimport {\n CheckCircleIcon,\n ExternalLinkIcon,\n FileIcon,\n ImageIcon,\n KeyRoundIcon,\n XCircleIcon,\n} from "lucide-react";\nimport { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";\nimport { Reasoning, ReasoningContent, ReasoningTrigger } from "@/components/ai-elements/reasoning";\nimport {\n Tool,\n ToolContent,\n ToolHeader,\n ToolInput,\n ToolOutput,\n} from "@/components/ai-elements/tool";\nimport { Button } from "@/components/ui/button";\nimport { cn } from "@/lib/utils";\n\nexport type AgentInputResponse = {\n readonly optionId?: string;\n readonly requestId: string;\n readonly text?: string;\n};\n\ntype EveFilePart = Extract<EveMessagePart, { type: "file" }>;\n\nexport function AgentMessage({\n canRespond,\n isStreaming,\n message,\n onInputResponses,\n}: {\n readonly canRespond: boolean;\n readonly isStreaming: boolean;\n readonly message: EveMessage;\n readonly onInputResponses: (responses: readonly AgentInputResponse[]) => void | Promise<void>;\n}) {\n const lastTextIndex = message.parts.reduce(\n (last, part, index) => (part.type === "text" ? index : last),\n -1,\n );\n\n return (\n <Message\n data-optimistic={message.metadata?.optimistic ? "true" : undefined}\n from={message.role}\n >\n <MessageContent>\n {message.parts.map((part, index) => (\n <AgentMessagePart\n canRespond={canRespond}\n key={partKey(part, index)}\n onInputResponses={onInputResponses}\n part={part}\n showCaret={isStreaming && message.role === "assistant" && index === lastTextIndex}\n />\n ))}\n </MessageContent>\n </Message>\n );\n}\n\nfunction AgentMessagePart({\n canRespond,\n onInputResponses,\n part,\n showCaret,\n}: {\n readonly canRespond: boolean;\n readonly onInputResponses: (responses: readonly AgentInputResponse[]) => void | Promise<void>;\n readonly part: EveMessagePart;\n readonly showCaret: boolean;\n}) {\n switch (part.type) {\n case "step-start":\n return null;\n case "text":\n return (\n <MessageResponse caret="block" isAnimating={showCaret}>\n {part.text}\n </MessageResponse>\n );\n case "reasoning":\n return (\n <Reasoning defaultOpen isStreaming={part.state === "streaming"}>\n <ReasoningTrigger />\n <ReasoningContent>{part.text}</ReasoningContent>\n </Reasoning>\n );\n case "file":\n return <AttachmentPart part={part} />;\n case "authorization":\n return <AuthorizationPrompt part={part} />;\n case "dynamic-tool":\n return (\n <Tool\n defaultOpen={part.state === "approval-requested" || part.state === "approval-responded"}\n >\n <ToolHeader\n state={part.state}\n title={part.toolName}\n toolName={part.toolName}\n type="dynamic-tool"\n />\n <ToolContent>\n <ToolInput input={part.input} />\n <InputRequestActions\n canRespond={canRespond}\n part={part}\n onInputResponses={onInputResponses}\n />\n <ToolOutput errorText={part.errorText} output={part.output} />\n </ToolContent>\n </Tool>\n );\n }\n}\n\nfunction AttachmentPart({ part }: { readonly part: EveFilePart }) {\n const label = part.filename ?? "Attachment";\n const detail = [part.mediaType, formatBytes(part.size)].filter(Boolean).join(" - ");\n const isImage = part.mediaType.startsWith("image/") && part.url !== undefined;\n const Icon = isImage ? ImageIcon : FileIcon;\n const body = (\n <span className="flex max-w-sm items-center gap-3 rounded-md border bg-background/60 p-2 text-sm">\n {isImage ? (\n <img alt={label} className="size-12 shrink-0 rounded-sm object-cover" src={part.url} />\n ) : (\n <span className="flex size-10 shrink-0 items-center justify-center rounded-sm bg-muted text-muted-foreground">\n <Icon className="size-4" />\n </span>\n )}\n <span className="min-w-0 flex-1">\n <span className="block truncate font-medium">{label}</span>\n {detail ? <span className="block truncate text-muted-foreground">{detail}</span> : null}\n </span>\n {part.url ? <ExternalLinkIcon className="size-4 shrink-0 text-muted-foreground" /> : null}\n </span>\n );\n\n return part.url ? (\n <a href={part.url} rel="noreferrer" target="_blank">\n {body}\n </a>\n ) : (\n body\n );\n}\n\nfunction AuthorizationPrompt({ part }: { readonly part: EveAuthorizationPart }) {\n const isAuthorized = part.state === "completed" && part.outcome === "authorized";\n const isCompleted = part.state === "completed";\n const Icon = isAuthorized ? CheckCircleIcon : isCompleted ? XCircleIcon : KeyRoundIcon;\n const instructions = part.authorization?.instructions;\n const shouldShowInstructions = instructions !== undefined && instructions !== part.description;\n\n return (\n <div\n className={cn(\n "space-y-3 rounded-md border p-3",\n isAuthorized\n ? "border-emerald-500/30 bg-emerald-500/5"\n : isCompleted\n ? "border-destructive/30 bg-destructive/5"\n : "border-blue-500/30 bg-blue-500/5",\n )}\n >\n <div className="flex items-start gap-3">\n <span\n className={cn(\n "mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-full",\n isAuthorized\n ? "bg-emerald-500/10 text-emerald-700 dark:text-emerald-300"\n : isCompleted\n ? "bg-destructive/10 text-destructive"\n : "bg-blue-500/10 text-blue-700 dark:text-blue-300",\n )}\n >\n <Icon className="size-4" />\n </span>\n <div className="min-w-0 flex-1 space-y-2">\n <p className="font-medium text-sm">{authorizationTitle(part)}</p>\n <p className="text-muted-foreground text-sm">{authorizationDescription(part)}</p>\n {shouldShowInstructions ? (\n <p className="text-muted-foreground text-sm">{instructions}</p>\n ) : null}\n {part.state === "required" && part.authorization?.userCode ? (\n <div className="flex flex-wrap items-center gap-2 text-sm">\n <span className="text-muted-foreground">Code</span>\n <code className="rounded-md bg-background px-2 py-1 font-mono">\n {part.authorization.userCode}\n </code>\n </div>\n ) : null}\n {part.state === "required" && part.authorization?.url ? (\n <Button asChild size="sm">\n <a href={part.authorization.url} rel="noreferrer" target="_blank">\n <ExternalLinkIcon className="size-4" />\n Sign in with {part.displayName}\n </a>\n </Button>\n ) : null}\n </div>\n </div>\n </div>\n );\n}\n\nfunction authorizationTitle(part: EveAuthorizationPart): string {\n if (part.state === "required") {\n return `Connect ${part.displayName}`;\n }\n if (part.outcome === "authorized") {\n return `${part.displayName} connected`;\n }\n return `${part.displayName} authorization ${formatAuthorizationOutcome(part.outcome)}`;\n}\n\nfunction authorizationDescription(part: EveAuthorizationPart): string {\n if (part.state === "required") {\n return part.description;\n }\n if (part.outcome === "authorized") {\n return `${part.displayName} connected.`;\n }\n const tail = part.reason !== undefined ? ` (${part.reason})` : "";\n return `${part.displayName} authorization ${formatAuthorizationOutcome(part.outcome)}${tail}.`;\n}\n\nfunction formatAuthorizationOutcome(outcome: NonNullable<EveAuthorizationPart["outcome"]>): string {\n switch (outcome) {\n case "authorized":\n return "authorized";\n case "declined":\n return "declined";\n case "failed":\n return "failed";\n case "timed-out":\n return "timed out";\n }\n}\n\nfunction formatBytes(size: number | undefined): string | undefined {\n if (size === undefined) {\n return undefined;\n }\n if (size < 1024) {\n return `${size} B`;\n }\n if (size < 1024 * 1024) {\n return `${(size / 1024).toFixed(1)} KB`;\n }\n return `${(size / (1024 * 1024)).toFixed(1)} MB`;\n}\n\nfunction InputRequestActions({\n canRespond,\n onInputResponses,\n part,\n}: {\n readonly canRespond: boolean;\n readonly onInputResponses: (responses: readonly AgentInputResponse[]) => void | Promise<void>;\n readonly part: EveDynamicToolPart;\n}) {\n const inputRequest = part.toolMetadata?.eve?.inputRequest;\n if (!inputRequest) {\n return null;\n }\n\n const inputResponse = part.toolMetadata?.eve?.inputResponse;\n const selectedOption = inputRequest.options?.find(\n (option) => option.id === inputResponse?.optionId,\n );\n\n return (\n <div className="space-y-3 rounded-md border border-yellow-500/30 bg-yellow-500/5 p-3">\n <p className="text-muted-foreground text-sm">{inputRequest.prompt}</p>\n {inputResponse ? (\n <p className="font-medium text-sm">\n Responded: {selectedOption?.label ?? inputResponse.text ?? inputResponse.optionId}\n </p>\n ) : (\n <div className="flex flex-wrap gap-2">\n {inputRequest.options?.map((option) => (\n <Button\n disabled={!canRespond}\n key={option.id}\n onClick={() => {\n void onInputResponses([\n {\n optionId: option.id,\n requestId: inputRequest.requestId,\n },\n ]);\n }}\n size="sm"\n type="button"\n variant={option.style === "danger" ? "destructive" : "default"}\n >\n {option.label}\n </Button>\n ))}\n </div>\n )}\n </div>\n );\n}\n\nfunction partKey(part: EveMessagePart, index: number): string {\n switch (part.type) {\n case "authorization":\n return `authorization:${part.turnId}:${part.stepIndex}:${part.name}`;\n case "dynamic-tool":\n return part.toolCallId;\n default:\n return `${part.type}:${index}`;\n }\n}\n',
"app/globals.css":
diff --git a/packages/eve/src/shared/dynamic-tool-definition.ts b/packages/eve/src/shared/dynamic-tool-definition.ts
index ca097bf98..c66815775 100644
--- a/packages/eve/src/shared/dynamic-tool-definition.ts
+++ b/packages/eve/src/shared/dynamic-tool-definition.ts
@@ -8,7 +8,7 @@ import type {
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
@@ -16,7 +16,7 @@ import type { HandleMessageStreamEvent } from "#protocol/message.js";
* more events are validated.
*/
export type DynamicToolEventName = Extract<
- HandleMessageStreamEvent["type"],
+ UnstampedMessageStreamEvent["type"],
"session.started" | "turn.started" | "step.started"
>;
diff --git a/packages/eve/src/shared/ulid.test.ts b/packages/eve/src/shared/ulid.test.ts
new file mode 100644
index 000000000..b6dc2c91b
--- /dev/null
+++ b/packages/eve/src/shared/ulid.test.ts
@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createUlid, createUlidFactory, isUlid, ULID_LENGTH } from "#shared/ulid.js";
+
+const CROCKFORD = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const TIME_MAX = 2 ** 48 - 1;
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ vi.useRealTimers();
+});
+
+function stubRandomBytes(bytes: readonly number[]): void {
+ vi.stubGlobal("crypto", {
+ getRandomValues(target: Uint8Array<ArrayBuffer>) {
+ target.set(bytes);
+ return target;
+ },
+ });
+}
+
+describe("createUlid", () => {
+ it("produces a 26-character Crockford base32 value", () => {
+ const ulid = createUlid();
+
+ expect(ulid).toHaveLength(ULID_LENGTH);
+ expect(ulid).toMatch(CROCKFORD);
+ });
+
+ it("draws from the process-wide generator without repeating", () => {
+ const ids = Array.from({ length: 1000 }, () => createUlid());
+
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+});
+
+describe("createUlidFactory", () => {
+ it("matches the ULID spec's canonical full encoding", () => {
+ // The spec's 01ARZ3NDEKTSV4RRFFQ69G5FAV example decodes to this
+ // timestamp and 80-bit random value.
+ stubRandomBytes([0xd6, 0x76, 0x4c, 0x61, 0xef, 0xb9, 0x93, 0x02, 0xbd, 0x5b]);
+ vi.useFakeTimers();
+ vi.setSystemTime(1_469_922_850_259);
+
+ expect(createUlidFactory()()).toBe("01ARZ3NDEKTSV4RRFFQ69G5FAV");
+ });
+
+ it("encodes the timestamp exactly as the ULID spec does", () => {
+ // Golden vectors from the reference `ulid` package's `encodeTime`, so an
+ // encoder change cannot silently produce ids other tooling misreads.
+ vi.useFakeTimers();
+ const mint = createUlidFactory();
+
+ vi.setSystemTime(new Date(0));
+ expect(mint().slice(0, 10)).toBe("0000000000");
+
+ vi.setSystemTime(new Date("2026-07-27T00:00:00.000Z"));
+ expect(mint().slice(0, 10)).toBe("01KYGDY300");
+
+ vi.setSystemTime(new Date("2030-01-01T00:00:00.000Z"));
+ expect(mint().slice(0, 10)).toBe("01Q3DCBD00");
+ });
+
+ it("accepts the largest 48-bit timestamp and rejects overflow", () => {
+ stubRandomBytes(Array.from({ length: 10 }, () => 0));
+ vi.useFakeTimers();
+
+ vi.setSystemTime(TIME_MAX);
+ expect(createUlidFactory()()).toBe("7ZZZZZZZZZ0000000000000000");
+
+ vi.setSystemTime(TIME_MAX + 1);
+ expect(() => createUlidFactory()()).toThrow(/timestamp must be an integer/);
+ });
+
+ it("throws when the random component overflows at the maximum timestamp", () => {
+ stubRandomBytes(Array.from({ length: 10 }, () => 0xff));
+ vi.useFakeTimers();
+ vi.setSystemTime(TIME_MAX);
+ const mint = createUlidFactory();
+
+ expect(mint()).toBe("7ZZZZZZZZZZZZZZZZZZZZZZZZZ");
+ expect(() => mint()).toThrow(/random component overflowed/);
+ expect(() => mint()).toThrow(/random component overflowed/);
+ });
+
+ it("throws when Web Crypto is unavailable", () => {
+ vi.stubGlobal("crypto", undefined);
+
+ expect(() => createUlidFactory()()).toThrow(
+ "Cannot mint a ULID: globalThis.crypto.getRandomValues is unavailable.",
+ );
+ });
+
+ it("sorts in emission order when many ids share one millisecond", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-07-27T00:00:00.000Z"));
+ const mint = createUlidFactory();
+
+ const ids = Array.from({ length: 500 }, () => mint());
+
+ expect(ids).toEqual([...ids].sort());
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+
+ it("sorts later timestamps after earlier ones", () => {
+ vi.useFakeTimers();
+ const mint = createUlidFactory();
+
+ vi.setSystemTime(new Date("2026-07-27T00:00:00.000Z"));
+ const earlier = mint();
+ vi.setSystemTime(new Date("2026-07-27T00:00:01.000Z"));
+ const later = mint();
+
+ expect(earlier < later).toBe(true);
+ });
+
+ it("stays monotonic when the clock moves backwards", () => {
+ vi.useFakeTimers();
+ const mint = createUlidFactory();
+
+ vi.setSystemTime(new Date("2026-07-27T00:00:05.000Z"));
+ const first = mint();
+ vi.setSystemTime(new Date("2026-07-27T00:00:04.000Z"));
+ const second = mint();
+
+ expect(first < second).toBe(true);
+ });
+
+ it("isolates each generator's state from the others", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2026-07-27T00:00:05.000Z"));
+ const settled = createUlidFactory();
+ settled();
+
+ // A fresh generator has observed no clock, so it may mint an earlier
+ // timestamp than one that already ran past it.
+ vi.setSystemTime(new Date("2026-07-27T00:00:00.000Z"));
+ const fresh = createUlidFactory();
+
+ expect(fresh() < settled()).toBe(true);
+ });
+});
+
+describe("isUlid", () => {
+ it("accepts values this module mints", () => {
+ expect(isUlid(createUlid())).toBe(true);
+ });
+
+ it("rejects a wrong length or a non-Crockford character", () => {
+ const ulid = createUlid();
+
+ expect(isUlid(ulid.slice(1))).toBe(false);
+ expect(isUlid(`${ulid}0`)).toBe(false);
+ expect(isUlid(`8${"0".repeat(25)}`)).toBe(false);
+ // U is excluded from the Crockford alphabet.
+ expect(isUlid(`U${ulid.slice(1)}`)).toBe(false);
+ });
+});
diff --git a/packages/eve/src/shared/ulid.ts b/packages/eve/src/shared/ulid.ts
new file mode 100644
index 000000000..d563baf79
--- /dev/null
+++ b/packages/eve/src/shared/ulid.ts
@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+
+// Crockford base32: omits I, L, O, and U, and sorts in raw-bit order.
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_CHARS = 10;
+const TIME_MAX = 2 ** 48 - 1;
+const RANDOM_BYTES = 10;
+const RANDOM_CHARS = 16;
+
+/** Character count of a ULID: a 10-char timestamp then a 16-char random tail. */
+export const ULID_LENGTH = TIME_CHARS + RANDOM_CHARS;
+
+/** 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 function createUlidFactory(): UlidFactory {
+ let lastTimeMs = -1;
+ const lastRandom = new Uint8Array(RANDOM_BYTES);
+
+ return function createUlidFromFactory(): string {
+ const now = Date.now();
+ if (!Number.isInteger(now) || now < 0 || now > TIME_MAX) {
+ throw new Error(`Cannot mint a ULID: timestamp must be an integer from 0 to ${TIME_MAX}.`);
+ }
+
+ if (now > lastTimeMs) {
+ lastTimeMs = now;
+ randomFill(lastRandom);
+ } else if (!incrementRandom(lastRandom)) {
+ // 2^80 ids in one millisecond: advance the logical clock rather than block.
+ if (lastTimeMs === TIME_MAX) {
+ throw new Error(
+ "Cannot mint a ULID: random component overflowed at the maximum timestamp.",
+ );
+ }
+ lastTimeMs += 1;
+ randomFill(lastRandom);
+ }
+
+ return `${encodeTime(lastTimeMs)}${encodeRandom(lastRandom)}`;
+ };
+}
+
+/**
+ * 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 const createUlid: UlidFactory = createUlidFactory();
+
+/**
+ * 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 function isUlid(value: string): boolean {
+ if (value.length !== ULID_LENGTH) return false;
+ if (ENCODING.indexOf(value[0] ?? "") > 7) return false;
+ for (const character of value) {
+ if (!ENCODING.includes(character)) return false;
+ }
+ return true;
+}
+
+function randomFill(target: Uint8Array<ArrayBuffer>): void {
+ const webCrypto = globalThis.crypto;
+ if (typeof webCrypto?.getRandomValues !== "function") {
+ throw new Error("Cannot mint a ULID: globalThis.crypto.getRandomValues is unavailable.");
+ }
+ webCrypto.getRandomValues(target);
+}
+
+function encodeTime(timeMs: number): string {
+ let remaining = timeMs;
+ let encoded = "";
+ for (let index = 0; index < TIME_CHARS; index += 1) {
+ encoded = ENCODING[remaining % 32] + encoded;
+ remaining = Math.floor(remaining / 32);
+ }
+ return encoded;
+}
+
+/** Encodes 80 bits as 16 five-bit groups — an exact fit, so no padding. */
+function encodeRandom(bytes: Uint8Array): string {
+ let buffer = 0;
+ let bufferedBits = 0;
+ let encoded = "";
+
+ for (const byte of bytes) {
+ buffer = (buffer << 8) | byte;
+ bufferedBits += 8;
+ while (bufferedBits >= 5) {
+ bufferedBits -= 5;
+ encoded += ENCODING[(buffer >>> bufferedBits) & 31];
+ }
+ buffer &= (1 << bufferedBits) - 1;
+ }
+
+ return encoded;
+}
+
+/** Adds one to a big-endian counter in place. Returns false on overflow. */
+function incrementRandom(bytes: Uint8Array): boolean {
+ for (let index = bytes.length - 1; index >= 0; index -= 1) {
+ const byte = bytes[index] ?? 0;
+ if (byte < 0xff) {
+ bytes[index] = byte + 1;
+ bytes.fill(0, index + 1);
+ return true;
+ }
+ }
+ return false;
+}
diff --git a/packages/eve/src/svelte/use-eve-agent.test.ts b/packages/eve/src/svelte/use-eve-agent.test.ts
index fee4f8a00..e63e76645 100644
--- a/packages/eve/src/svelte/use-eve-agent.test.ts
+++ b/packages/eve/src/svelte/use-eve-agent.test.ts
@@ -6,8 +6,9 @@ import {
createMessageCompletedEvent,
createMessageReceivedEvent,
createSessionWaitingEvent,
- type HandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
+import { stampTestEvents } from "#internal/testing/events.js";
function createStartedMessageResponse(sessionId: string, continuationToken: string): Response {
return new Response(JSON.stringify({ continuationToken, ok: true, sessionId }), {
@@ -19,12 +20,12 @@ function createStartedMessageResponse(sessionId: string, continuationToken: stri
});
}
-function createEagerStreamResponse(events: readonly HandleMessageStreamEvent[]): Response {
+function createEagerStreamResponse(events: readonly UnstampedMessageStreamEvent[]): Response {
const encoder = new TextEncoder();
return new Response(
new ReadableStream<Uint8Array>({
start(controller) {
- for (const event of events) {
+ for (const event of stampTestEvents(events)) {
controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
}
controller.close();
@@ -41,7 +42,7 @@ afterEach(() => {
describe("useEveAgent (Svelte rune binding)", () => {
it("renders the initial projection through plain reactive properties", () => {
const agent = useEveAgent({
- initialEvents: [
+ initialEvents: stampTestEvents([
createMessageReceivedEvent({ message: "Hello", sequence: 0, turnId: "turn_1" }),
createMessageCompletedEvent({
message: "Hi there.",
@@ -49,7 +50,7 @@ describe("useEveAgent (Svelte rune binding)", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- ],
+ ]),
initialSession: {
continuationToken: "http:session_1",
sessionId: "session_1",
@@ -68,9 +69,9 @@ describe("useEveAgent (Svelte rune binding)", () => {
it("does not update the visible snapshot without browser reactivity", async () => {
const agent = useEveAgent({
- initialEvents: [
+ initialEvents: stampTestEvents([
createMessageReceivedEvent({ message: "Hello", sequence: 0, turnId: "turn_1" }),
- ],
+ ]),
});
const dataBeforeSend = agent.data;
@@ -91,7 +92,7 @@ describe("useEveAgent (Svelte rune binding)", () => {
vi.spyOn(globalThis, "fetch")
.mockResolvedValueOnce(createStartedMessageResponse("session_1", "http:session_1"))
.mockResolvedValueOnce(createEagerStreamResponse(events));
- const seenEvents: HandleMessageStreamEvent[] = [];
+ const seenEvents: UnstampedMessageStreamEvent[] = [];
const agent = useEveAgent({
onEvent(event) {
@@ -101,6 +102,6 @@ describe("useEveAgent (Svelte rune binding)", () => {
await agent.send({ message: "Hello" });
- expect(seenEvents).toEqual(events);
+ expect(seenEvents).toEqual(stampTestEvents(events));
});
});
diff --git a/packages/eve/src/svelte/use-eve-agent.ts b/packages/eve/src/svelte/use-eve-agent.ts
index 78face8e3..d0017b23b 100644
--- a/packages/eve/src/svelte/use-eve-agent.ts
+++ b/packages/eve/src/svelte/use-eve-agent.ts
@@ -12,7 +12,7 @@ import { defaultMessageReducer, type EveMessageData } from "#client/message-redu
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 };
@@ -43,7 +43,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). */
@@ -90,8 +90,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;
/**
@@ -148,7 +148,7 @@ class SvelteEveAgent<TData> implements UseEveAgentReturn<TData> {
return this.#snapshot.error;
}
- get events(): readonly HandleMessageStreamEvent[] {
+ get events(): readonly MessageStreamEvent[] {
this.#subscribe();
return this.#snapshot.events;
}
diff --git a/packages/eve/src/vue/use-eve-agent.test.ts b/packages/eve/src/vue/use-eve-agent.test.ts
index a3e4baffa..76ab41c4a 100644
--- a/packages/eve/src/vue/use-eve-agent.test.ts
+++ b/packages/eve/src/vue/use-eve-agent.test.ts
@@ -10,8 +10,9 @@ import {
createMessageReceivedEvent,
createSessionFailedEvent,
createSessionWaitingEvent,
- type HandleMessageStreamEvent,
+ type UnstampedMessageStreamEvent,
} from "#protocol/message.js";
+import { stampTestEvents } from "#internal/testing/events.js";
import { defaultMessageReducer } from "#client/message-reducer.js";
import type { SessionState } from "#client/types.js";
@@ -25,12 +26,12 @@ function createStartedMessageResponse(sessionId: string, continuationToken: stri
});
}
-function createEagerStreamResponse(events: readonly HandleMessageStreamEvent[]): Response {
+function createEagerStreamResponse(events: readonly UnstampedMessageStreamEvent[]): Response {
const encoder = new TextEncoder();
return new Response(
new ReadableStream<Uint8Array>({
start(controller) {
- for (const event of events) {
+ for (const event of stampTestEvents(events)) {
controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
}
controller.close();
@@ -150,7 +151,7 @@ describe("EveAgentStore (Vue composable backing store)", () => {
reducer: defaultMessageReducer(),
});
- const seenEvents: HandleMessageStreamEvent[] = [];
+ const seenEvents: UnstampedMessageStreamEvent[] = [];
const seenSessions: SessionState[] = [];
store.setCallbacks({
onEvent(event) {
@@ -179,7 +180,7 @@ describe("EveAgentStore (Vue composable backing store)", () => {
startResponse.resolve(createStartedMessageResponse("session_1", "http:session_1"));
await sendPromise;
- expect(seenEvents).toEqual(events);
+ expect(seenEvents).toEqual(stampTestEvents(events));
expect(store.snapshot.status).toBe("ready");
expect(store.snapshot.data).toEqual(
completedTurnData({
@@ -403,7 +404,7 @@ describe("useEveAgent (Vue composable wiring)", () => {
it("renders initial projection without subscribing during SSR", async () => {
const agent = useEveAgent({
- initialEvents: [
+ initialEvents: stampTestEvents([
createMessageReceivedEvent({ message: "Hello", sequence: 0, turnId: "turn_1" }),
createMessageCompletedEvent({
message: "Hi there.",
@@ -411,7 +412,7 @@ describe("useEveAgent (Vue composable wiring)", () => {
stepIndex: 0,
turnId: "turn_1",
}),
- ],
+ ]),
initialSession: {
continuationToken: "http:session_1",
sessionId: "session_1",
diff --git a/packages/eve/src/vue/use-eve-agent.ts b/packages/eve/src/vue/use-eve-agent.ts
index 521e7fc84..978ef8b85 100644
--- a/packages/eve/src/vue/use-eve-agent.ts
+++ b/packages/eve/src/vue/use-eve-agent.ts
@@ -11,7 +11,7 @@ import { resolveEveAgentHost } from "#client/agent-host.js";
import type { EveAgentReducer } from "#client/reducer.js";
import type { ClientSession } from "#client/session.js";
import { defaultMessageReducer, 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 };
@@ -41,7 +41,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). */
@@ -88,8 +88,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;
/**
diff --git a/packages/eve/test/client.test.ts b/packages/eve/test/client.test.ts
index fbeb383ac..29783ee74 100644
--- a/packages/eve/test/client.test.ts
+++ b/packages/eve/test/client.test.ts
@@ -1,10 +1,11 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
import {
Client,
ClientError,
type AgentInfoResult,
type HandleMessageStreamEvent,
+ type MessageStreamEvent,
} from "../src/client/index.js";
import {
EVE_SESSION_ID_HEADER,
@@ -16,6 +17,7 @@ import {
createSessionWaitingEvent,
createTurnCompletedEvent,
createTurnStartedEvent,
+ type UnstampedMessageStreamEvent,
} from "../src/protocol/message.js";
// ---------------------------------------------------------------------------
@@ -88,7 +90,7 @@ function singleTurnEvents(input: {
message: string;
sequence: number;
turnId: string;
-}): HandleMessageStreamEvent[] {
+}): UnstampedMessageStreamEvent[] {
return [
createTurnStartedEvent({ sequence: input.sequence, turnId: input.turnId }),
createMessageReceivedEvent({
@@ -111,6 +113,10 @@ afterEach(() => {
vi.restoreAllMocks();
});
+it("keeps HandleMessageStreamEvent as an alias for MessageStreamEvent", () => {
+ expectTypeOf<HandleMessageStreamEvent>().toEqualTypeOf<MessageStreamEvent>();
+});
+
// ---------------------------------------------------------------------------
// health()
// ---------------------------------------------------------------------------
@@ -386,7 +392,7 @@ describe("Session.send (result)", () => {
});
it("returns status 'failed' when the session fails without throwing", async () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
createTurnStartedEvent({ sequence: 1, turnId: "turn_001" }),
createSessionFailedEvent({
code: "internal_error",
@@ -408,7 +414,7 @@ describe("Session.send (result)", () => {
});
it("returns status 'completed' when the session completes", async () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
createTurnStartedEvent({ sequence: 1, turnId: "turn_001" }),
createMessageCompletedEvent({
message: "Done",
@@ -437,7 +443,7 @@ describe("Session.send (result)", () => {
required: ["title"],
type: "object",
} as const;
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
createTurnStartedEvent({ sequence: 1, turnId: "turn_001" }),
createMessageReceivedEvent({
message: "Summarize",
@@ -478,7 +484,7 @@ describe("Session.send (result)", () => {
});
it("resets session state after session.completed", async () => {
- const firstEvents: HandleMessageStreamEvent[] = [
+ const firstEvents: UnstampedMessageStreamEvent[] = [
createTurnStartedEvent({ sequence: 1, turnId: "turn_001" }),
createMessageCompletedEvent({
message: "Done",
@@ -538,7 +544,7 @@ describe("Session.send (stream)", () => {
const session = new Client({ host: "http://localhost:3000" }).session();
const res = await session.send("Hello");
- const collected: HandleMessageStreamEvent[] = [];
+ const collected: UnstampedMessageStreamEvent[] = [];
const iterationPromise = (async () => {
for await (const event of res) {
@@ -615,7 +621,7 @@ describe("Session.send (stream)", () => {
describe("Session.send (reconnection)", () => {
it("reconnects when the stream disconnects mid-turn", async () => {
const firstStream = createControlledStreamResponse();
- const reconnectEvents: HandleMessageStreamEvent[] = [
+ const reconnectEvents: UnstampedMessageStreamEvent[] = [
createMessageReceivedEvent({ message: "Hello", sequence: 1, turnId: "turn_001" }),
createMessageCompletedEvent({
message: "Reply",
@@ -808,7 +814,7 @@ describe("Session.stream", () => {
});
it("uses the session sessionId and streamIndex", async () => {
- const events: HandleMessageStreamEvent[] = [
+ const events: UnstampedMessageStreamEvent[] = [
createMessageCompletedEvent({
message: "Hi",
sequence: 2,
@@ -829,7 +835,7 @@ describe("Session.stream", () => {
streamIndex: 10,
});
- const collected: HandleMessageStreamEvent[] = [];
+ const collected: UnstampedMessageStreamEvent[] = [];
for await (const event of session.stream()) {
collected.push(event);
// stream() follows the durable log across transport ends; the boundary
diff --git a/packages/eve/test/dev-client-harness/live-stream.ts b/packages/eve/test/dev-client-harness/live-stream.ts
index 4ca114987..19c4b84df 100644
--- a/packages/eve/test/dev-client-harness/live-stream.ts
+++ b/packages/eve/test/dev-client-harness/live-stream.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { isCurrentTurnBoundaryEvent } from "#protocol/message.js";
function isDevelopmentMessageStreamDisconnectError(error: unknown): boolean {
@@ -43,10 +43,10 @@ export interface DevelopmentMessageStream {
* configured boundary predicate matches or the response closes.
*/
readEvents(input: {
- onEvent?(event: HandleMessageStreamEvent): void;
+ onEvent?(event: MessageStreamEvent): void;
startAfterBoundaryCount?: number;
- stopWhen?(event: HandleMessageStreamEvent): boolean;
- }): Promise<HandleMessageStreamEvent[]>;
+ stopWhen?(event: MessageStreamEvent): boolean;
+ }): Promise<MessageStreamEvent[]>;
}
class BufferedDevelopmentMessageStream implements DevelopmentMessageStream {
@@ -97,10 +97,10 @@ class BufferedDevelopmentMessageStream implements DevelopmentMessageStream {
}
async readEvents(input: {
- onEvent?(event: HandleMessageStreamEvent): void;
+ onEvent?(event: MessageStreamEvent): void;
startAfterBoundaryCount?: number;
- stopWhen?(event: HandleMessageStreamEvent): boolean;
- }): Promise<HandleMessageStreamEvent[]> {
+ stopWhen?(event: MessageStreamEvent): boolean;
+ }): Promise<MessageStreamEvent[]> {
if (this.#closed) {
return [];
}
@@ -118,12 +118,12 @@ class BufferedDevelopmentMessageStream implements DevelopmentMessageStream {
this.#isReading = true;
try {
- const events: HandleMessageStreamEvent[] = [];
+ const events: MessageStreamEvent[] = [];
const stopWhen = input.stopWhen ?? isCurrentTurnBoundaryEvent;
const startAfterBoundaryCount = input.startAfterBoundaryCount ?? 0;
let shouldCollect = startAfterBoundaryCount <= this.#boundaryCount;
- const handleEvent = (event: HandleMessageStreamEvent): boolean => {
+ const handleEvent = (event: MessageStreamEvent): boolean => {
const isBoundaryEvent = isCurrentTurnBoundaryEvent(event);
if (shouldCollect) {
@@ -160,7 +160,7 @@ class BufferedDevelopmentMessageStream implements DevelopmentMessageStream {
continue;
}
- const event = JSON.parse(line) as HandleMessageStreamEvent;
+ const event = JSON.parse(line) as MessageStreamEvent;
if (handleEvent(event)) {
return events;
@@ -209,7 +209,7 @@ class BufferedDevelopmentMessageStream implements DevelopmentMessageStream {
this.#buffer = "";
if (trailingLine.length > 0) {
- const event = JSON.parse(trailingLine) as HandleMessageStreamEvent;
+ const event = JSON.parse(trailingLine) as MessageStreamEvent;
handleEvent(event);
}
diff --git a/packages/eve/test/dev-client-harness/send-message.ts b/packages/eve/test/dev-client-harness/send-message.ts
index 0456356ef..3110a3865 100644
--- a/packages/eve/test/dev-client-harness/send-message.ts
+++ b/packages/eve/test/dev-client-harness/send-message.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { EVE_SESSION_ID_HEADER } from "#protocol/message.js";
import {
EVE_CREATE_SESSION_ROUTE_PATH,
@@ -79,17 +79,17 @@ async function openDevelopmentSessionStream(input: {
async function readDevelopmentTurnEvents(input: {
readonly headers?: DevelopmentRequestHeaders;
readonly initialStartIndex: number;
- onEvent?(event: HandleMessageStreamEvent): void;
+ onEvent?(event: MessageStreamEvent): void;
readonly sessionId: string;
readonly serverUrl: string;
readonly signal?: AbortSignal;
readonly stream: ReturnType<typeof openDevelopmentMessageStream>;
}): Promise<{
- readonly events: HandleMessageStreamEvent[];
+ readonly events: MessageStreamEvent[];
readonly stream: ReturnType<typeof openDevelopmentMessageStream>;
}> {
let currentStream = input.stream;
- const events: HandleMessageStreamEvent[] = [];
+ const events: MessageStreamEvent[] = [];
let currentStreamIndex = input.initialStartIndex;
let remainingReconnectAttempts = DEVELOPMENT_TURN_STREAM_RECONNECT_LIMIT;
@@ -135,14 +135,14 @@ async function readDevelopmentTurnEvents(input: {
export async function sendDevelopmentMessage(input: {
headers?: DevelopmentRequestHeaders;
message: string;
- onEvent?(event: HandleMessageStreamEvent): void;
+ onEvent?(event: MessageStreamEvent): void;
onResponseStart?(response: { sessionId?: string }): void;
signal?: AbortSignal;
session: DevelopmentSessionState;
serverUrl: string;
}): Promise<{
completedMessage?: string;
- events: HandleMessageStreamEvent[];
+ events: MessageStreamEvent[];
sessionId?: string;
session: DevelopmentSessionState;
}> {
diff --git a/packages/eve/test/dev-client-harness/session.ts b/packages/eve/test/dev-client-harness/session.ts
index 73151fcd5..51df8c111 100644
--- a/packages/eve/test/dev-client-harness/session.ts
+++ b/packages/eve/test/dev-client-harness/session.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageRequestBody, HandleMessageStreamEvent } from "#protocol/message.js";
+import type { HandleMessageRequestBody, MessageStreamEvent } from "#protocol/message.js";
import { countCurrentTurnBoundaryEvents, extractCurrentTurnBoundaryEvent } from "./stream.js";
/**
@@ -69,7 +69,7 @@ export function createDevelopmentMessageRequest(input: {
*/
export function updateDevelopmentSessionState(input: {
readonly continuationToken?: string;
- readonly events: readonly HandleMessageStreamEvent[];
+ readonly events: readonly MessageStreamEvent[];
readonly sessionId: string;
readonly session: DevelopmentSessionState;
}): DevelopmentSessionState {
diff --git a/packages/eve/test/dev-client-harness/stream.ts b/packages/eve/test/dev-client-harness/stream.ts
index cc52824cb..9a2d72860 100644
--- a/packages/eve/test/dev-client-harness/stream.ts
+++ b/packages/eve/test/dev-client-harness/stream.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import { isCurrentTurnBoundaryEvent } from "#protocol/message.js";
import { openDevelopmentMessageStream } from "./live-stream.js";
@@ -9,11 +9,11 @@ import { openDevelopmentMessageStream } from "./live-stream.js";
* Test-only helper.
*/
export async function readMessageStreamEvents(input: {
- onEvent?(event: HandleMessageStreamEvent): void;
+ onEvent?(event: MessageStreamEvent): void;
response: Response;
startAfterBoundaryCount?: number;
- stopWhen?(event: HandleMessageStreamEvent): boolean;
-}): Promise<HandleMessageStreamEvent[]> {
+ stopWhen?(event: MessageStreamEvent): boolean;
+}): Promise<MessageStreamEvent[]> {
const stream = openDevelopmentMessageStream({
resourceUrl: "",
response: input.response,
@@ -31,9 +31,7 @@ export async function readMessageStreamEvents(input: {
*
* Test-only helper.
*/
-export function countCurrentTurnBoundaryEvents(
- events: readonly HandleMessageStreamEvent[],
-): number {
+export function countCurrentTurnBoundaryEvents(events: readonly MessageStreamEvent[]): number {
return events.filter(isCurrentTurnBoundaryEvent).length;
}
@@ -44,7 +42,7 @@ export function countCurrentTurnBoundaryEvents(
* Test-only helper.
*/
export function extractCurrentTurnBoundaryEvent(
- events: readonly HandleMessageStreamEvent[],
-): HandleMessageStreamEvent | undefined {
+ events: readonly MessageStreamEvent[],
+): MessageStreamEvent | undefined {
return [...events].reverse().find(isCurrentTurnBoundaryEvent);
}
diff --git a/packages/eve/test/eve-run-stream-channel.test.ts b/packages/eve/test/eve-run-stream-channel.test.ts
index b591d264c..26b839aa3 100644
--- a/packages/eve/test/eve-run-stream-channel.test.ts
+++ b/packages/eve/test/eve-run-stream-channel.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it, vi } from "vitest";
-import type { HandleMessageStreamEvent } from "../src/protocol/message.js";
+import type { MessageStreamEvent } from "../src/protocol/message.js";
+import { stampTestEvents } from "../src/internal/testing/events.js";
import type { RouteHandlerArgs, GetSessionFn } from "../src/channel/routes.js";
import type { Session } from "../src/channel/session.js";
import { EVE_MESSAGE_STREAM_ROUTE_PATTERN } from "../src/protocol/routes.js";
@@ -30,18 +31,20 @@ function createGetHandler() {
describe("eveChannel GET stream", () => {
it("forwards the startIndex query parameter into getSession/getEventStream", async () => {
const getRoute = createGetHandler();
- const events = createEvents([
- {
- type: "message.completed",
- data: {
- finishReason: "stop",
- message: "second turn reply",
- sequence: 0,
- stepIndex: 0,
- turnId: "turn-1",
+ const events = createEvents(
+ stampTestEvents([
+ {
+ type: "message.completed",
+ data: {
+ finishReason: "stop",
+ message: "second turn reply",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "turn-1",
+ },
},
- },
- ]);
+ ]),
+ );
const getSession = createMockGetSession(events);
const response = await (getRoute as any).handler(
@@ -116,7 +119,7 @@ describe("eveChannel GET stream", () => {
it("re-serializes the parsed event stream as NDJSON bytes", async () => {
const getRoute = createGetHandler();
- const events: HandleMessageStreamEvent[] = [
+ const events = stampTestEvents([
{
type: "message.completed",
data: {
@@ -131,7 +134,7 @@ describe("eveChannel GET stream", () => {
type: "session.waiting",
data: { continuationToken: "eve:test", wait: "next-user-message" },
},
- ];
+ ]);
const getSession = createMockGetSession(createEvents(events));
const response = await (getRoute as any).handler(
@@ -153,10 +156,8 @@ describe("eveChannel GET stream", () => {
});
});
-function createEvents(
- events: readonly HandleMessageStreamEvent[],
-): ReadableStream<HandleMessageStreamEvent> {
- return new ReadableStream<HandleMessageStreamEvent>({
+function createEvents(events: readonly MessageStreamEvent[]): ReadableStream<MessageStreamEvent> {
+ return new ReadableStream<MessageStreamEvent>({
start(controller) {
for (const event of events) {
controller.enqueue(event);
@@ -166,7 +167,7 @@ function createEvents(
});
}
-function createMockGetSession(events: ReadableStream<HandleMessageStreamEvent>) {
+function createMockGetSession(events: ReadableStream<MessageStreamEvent>) {
return vi.fn<GetSessionFn>().mockReturnValue({
id: "session_xyz",
continuationToken: "",
diff --git a/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts b/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts
index 0996a1d3c..d005a1008 100644
--- a/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts
+++ b/packages/eve/test/scenarios/schedule-trigger.scenario.test.ts
@@ -5,7 +5,7 @@ import { describe, expect, it } from "vitest";
import type { ChannelAdapter } from "#channel/adapter.js";
import { expectScheduleRun, SCHEDULE_ADAPTER_KIND, ScheduleDispatcher } from "#channel/schedule.js";
-import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
import type { RunHandle, Runtime } from "#channel/types.js";
import { compileAgent } from "#compiler/compile-agent.js";
import { ContextContainer } from "#context/container.js";
@@ -71,7 +71,7 @@ function createCapturingRuntime(captured: CapturedRun[]): Runtime {
const handle: RunHandle = {
continuationToken: "scenario-token",
- events: new ReadableStream<HandleMessageStreamEvent>(),
+ events: new ReadableStream<MessageStreamEvent>(),
sessionId: "scenario-session",
};
return handle;
@@ -80,7 +80,7 @@ function createCapturingRuntime(captured: CapturedRun[]): Runtime {
throw new Error("deliver should not be called in this scenario");
},
async getEventStream() {
- return new ReadableStream<HandleMessageStreamEvent>();
+ return new ReadableStream<MessageStreamEvent>();
},
async getStreamTailIndex() {
return -1;
diff --git a/packages/eve/test/scenarios/turn-cancellation.scenario.test.ts b/packages/eve/test/scenarios/turn-cancellation.scenario.test.ts
index b04f694b1..2fc88dde8 100644
--- a/packages/eve/test/scenarios/turn-cancellation.scenario.test.ts
+++ b/packages/eve/test/scenarios/turn-cancellation.scenario.test.ts
@@ -1,10 +1,7 @@
import { describe, expect, it } from "vitest";
import { Client } from "../../src/client/client.js";
-import {
- type HandleMessageStreamEvent,
- isCurrentTurnBoundaryEvent,
-} from "../../src/protocol/message.js";
+import { type MessageStreamEvent, isCurrentTurnBoundaryEvent } from "../../src/protocol/message.js";
import { createEveCancelTurnRoutePath } from "../../src/protocol/routes.js";
import {
type ScenarioAppDescriptor,
@@ -225,11 +222,11 @@ describe("turn cancellation descendant cascade", () => {
);
});
-type SubagentCalledEvent = Extract<HandleMessageStreamEvent, { type: "subagent.called" }>;
+type SubagentCalledEvent = Extract<MessageStreamEvent, { type: "subagent.called" }>;
async function readSubagentCalls(input: {
readonly count: number;
- readonly iterator: AsyncIterator<HandleMessageStreamEvent>;
+ readonly iterator: AsyncIterator<MessageStreamEvent>;
readonly label: string;
}): Promise<readonly SubagentCalledEvent[]> {
return await withinEventDeadline(
@@ -246,7 +243,7 @@ async function readSubagentCalls(input: {
);
}
-function isWaitForCancelToolCall(event: HandleMessageStreamEvent): boolean {
+function isWaitForCancelToolCall(event: MessageStreamEvent): boolean {
return (
event.type === "actions.requested" &&
event.data.actions.some(
@@ -256,10 +253,10 @@ function isWaitForCancelToolCall(event: HandleMessageStreamEvent): boolean {
}
async function readUntil(input: {
- readonly iterator: AsyncIterator<HandleMessageStreamEvent>;
+ readonly iterator: AsyncIterator<MessageStreamEvent>;
readonly label: string;
- readonly matches: (event: HandleMessageStreamEvent) => boolean;
-}): Promise<{ readonly event: HandleMessageStreamEvent }> {
+ readonly matches: (event: MessageStreamEvent) => boolean;
+}): Promise<{ readonly event: MessageStreamEvent }> {
return await withinEventDeadline(
(async () => {
while (true) {
@@ -273,10 +270,10 @@ async function readUntil(input: {
}
async function readThroughBoundary(input: {
- readonly iterator: AsyncIterator<HandleMessageStreamEvent>;
+ readonly iterator: AsyncIterator<MessageStreamEvent>;
readonly label: string;
-}): Promise<readonly HandleMessageStreamEvent[]> {
- const events: HandleMessageStreamEvent[] = [];
+}): Promise<readonly MessageStreamEvent[]> {
+ const events: MessageStreamEvent[] = [];
await withinEventDeadline(
(async () => {
while (true) {
@@ -297,7 +294,7 @@ async function readThroughBoundary(input: {
return events;
}
-function expectCancellationBoundary(events: readonly HandleMessageStreamEvent[]): void {
+function expectCancellationBoundary(events: readonly MessageStreamEvent[]): void {
const types = events.map((event) => event.type);
expect(types).toContain("turn.cancelled");
expect(types.at(-1)).toBe("session.waiting");
diff --git a/packages/eve/test/tui-client/lib/stream.ts b/packages/eve/test/tui-client/lib/stream.ts
index 29960484c..9692841a5 100644
--- a/packages/eve/test/tui-client/lib/stream.ts
+++ b/packages/eve/test/tui-client/lib/stream.ts
@@ -1,4 +1,4 @@
-import type { HandleMessageStreamEvent, InputRequest } from "eve/client";
+import type { MessageStreamEvent, InputRequest } from "eve/client";
import { theme } from "./theme.ts";
@@ -22,7 +22,7 @@ const state: PrintState = {
* - Secondary scaffolding (turn/tool/session lifecycle) is dim gray.
* - Failures (`step.failed`, `turn.failed`, `session.failed`) are red.
*/
-export function printStreamEvent(event: HandleMessageStreamEvent): void {
+export function printStreamEvent(event: MessageStreamEvent): void {
switch (event.type) {
case "session.started":
process.stdout.write(
diff --git a/packages/eve/test/tui-client/tui-connection-auth-states.ts b/packages/eve/test/tui-client/tui-connection-auth-states.ts
index 635da139e..0eec769b0 100644
--- a/packages/eve/test/tui-client/tui-connection-auth-states.ts
+++ b/packages/eve/test/tui-client/tui-connection-auth-states.ts
@@ -1,6 +1,7 @@
import { setTimeout as sleep } from "node:timers/promises";
-import { ClientSession, MessageResponse, type HandleMessageStreamEvent } from "eve/client";
+import { ClientSession, MessageResponse, type MessageStreamEvent } from "eve/client";
+import type { UnstampedMessageStreamEvent } from "#protocol/message.js";
import { EveTUIRunner, MockScreen, MockUserInput } from "./lib/tui.ts";
import { theme } from "./lib/theme.ts";
@@ -30,14 +31,14 @@ import { theme } from "./lib/theme.ts";
*/
class FakeSession extends ClientSession {
- readonly #turns: ReadonlyArray<readonly HandleMessageStreamEvent[]>;
- readonly #continuations: ReadonlyArray<readonly HandleMessageStreamEvent[]>;
+ readonly #turns: ReadonlyArray<readonly UnstampedMessageStreamEvent[]>;
+ readonly #continuations: ReadonlyArray<readonly UnstampedMessageStreamEvent[]>;
#turnIndex = 0;
#continuationIndex = 0;
constructor(input: {
- turns: ReadonlyArray<readonly HandleMessageStreamEvent[]>;
- continuations: ReadonlyArray<readonly HandleMessageStreamEvent[]>;
+ turns: ReadonlyArray<readonly UnstampedMessageStreamEvent[]>;
+ continuations: ReadonlyArray<readonly UnstampedMessageStreamEvent[]>;
}) {
super(
{
@@ -61,18 +62,29 @@ class FakeSession extends ClientSession {
});
}
- override stream(): AsyncIterable<HandleMessageStreamEvent> {
+ override stream(): AsyncIterable<MessageStreamEvent> {
const events = this.#continuations[this.#continuationIndex] ?? [];
this.#continuationIndex += 1;
return pacedEvents(events);
}
}
+let nextEventIndex = 0;
+
+/** Stamps a fixture event the way an emit seam does before it hits the wire. */
+function stamp(event: UnstampedMessageStreamEvent): MessageStreamEvent {
+ nextEventIndex += 1;
+ return {
+ ...event,
+ meta: { at: new Date().toISOString(), id: `evt_smoke_${nextEventIndex}` },
+ } as MessageStreamEvent;
+}
+
async function* pacedEvents(
- events: readonly HandleMessageStreamEvent[],
-): AsyncGenerator<HandleMessageStreamEvent> {
+ events: readonly UnstampedMessageStreamEvent[],
+): AsyncGenerator<MessageStreamEvent> {
for (const event of events) {
- yield event;
+ yield stamp(event);
// Pacing gives the renderer and smoke assertions a chance to observe
// each lifecycle state between events, as the HTTP transport does live.
await sleep(200);
@@ -85,7 +97,7 @@ const stepIndex = 0;
let sequence = 0;
const next = () => ++sequence;
-const firstTurn: HandleMessageStreamEvent[] = [
+const firstTurn: UnstampedMessageStreamEvent[] = [
{ type: "session.started", data: {} },
{ type: "turn.started", data: { sequence: next(), turnId } },
{ type: "step.started", data: { sequence: next(), stepIndex, turnId } },
@@ -115,7 +127,7 @@ const firstTurn: HandleMessageStreamEvent[] = [
},
];
-const firstCallbackTurn: HandleMessageStreamEvent[] = [
+const firstCallbackTurn: UnstampedMessageStreamEvent[] = [
{
type: "authorization.completed",
data: {
@@ -137,7 +149,7 @@ const firstCallbackTurn: HandleMessageStreamEvent[] = [
];
const secondTurnId = "turn-1";
-const secondTurn: HandleMessageStreamEvent[] = [
+const secondTurn: UnstampedMessageStreamEvent[] = [
{ type: "turn.started", data: { sequence: next(), turnId: secondTurnId } },
{ type: "step.started", data: { sequence: next(), stepIndex, turnId: secondTurnId } },
{
@@ -164,7 +176,7 @@ const secondTurn: HandleMessageStreamEvent[] = [
},
];
-const secondCallbackTurn: HandleMessageStreamEvent[] = [
+const secondCallbackTurn: UnstampedMessageStreamEvent[] = [
{
type: "authorization.completed",
data: {
diff --git a/packages/eve/test/tui-client/tui-connection-auth-user.ts b/packages/eve/test/tui-client/tui-connection-auth-user.ts
index 86cf6ef91..561aa488c 100644
--- a/packages/eve/test/tui-client/tui-connection-auth-user.ts
+++ b/packages/eve/test/tui-client/tui-connection-auth-user.ts
@@ -8,7 +8,7 @@ import {
type ActionResultStreamEvent,
type AuthorizationCompletedStreamEvent,
type AuthorizationRequiredStreamEvent,
- type HandleMessageStreamEvent,
+ type MessageStreamEvent,
} from "eve/client";
import { startMcpStubServer } from "./lib/mcp-stub-server.ts";
@@ -150,7 +150,7 @@ runEnvironment("tui-connection-auth-user", async ({ cleanup, target: resolveTarg
let toolResultMatched = false;
let markerEchoedInMessage = false;
- for await (const event of stream as AsyncIterable<HandleMessageStreamEvent>) {
+ for await (const event of stream as AsyncIterable<MessageStreamEvent>) {
if (event.type === "authorization.required" && event.data.name === "stub-mcp-user") {
requiredEvent = event;
const challengeUrl = event.data.authorization?.url;
@@ -286,7 +286,7 @@ runEnvironment("tui-connection-auth-user", async ({ cleanup, target: resolveTarg
}
let followupTokenEchoed = false;
- let followupBoundary: HandleMessageStreamEvent["type"] | undefined;
+ let followupBoundary: MessageStreamEvent["type"] | undefined;
const followupAbort = new AbortController();
const followupTimer = setTimeout(() => followupAbort.abort(), 60_000);
diff --git a/packages/eve/test/vercel/vercel-sandbox-bundling.vercel.test.ts b/packages/eve/test/vercel/vercel-sandbox-bundling.vercel.test.ts
index 3bc3cbee5..28fdf50f1 100644
--- a/packages/eve/test/vercel/vercel-sandbox-bundling.vercel.test.ts
+++ b/packages/eve/test/vercel/vercel-sandbox-bundling.vercel.test.ts
@@ -1,6 +1,6 @@
import { afterAll, beforeAll, describe, it } from "vitest";
import { SANDBOX_BUNDLING_DESCRIPTOR } from "../../src/internal/testing/scenario-apps/sandbox-bundling.js";
-import type { HandleMessageStreamEvent } from "../../src/protocol/message.js";
+import type { MessageStreamEvent } from "../../src/protocol/message.js";
import { sendDevelopmentMessage } from "../dev-client-harness/send-message.js";
import { createDevelopmentSessionState } from "../dev-client-harness/session.js";
import {
@@ -68,7 +68,7 @@ describe.sequential("sandbox-bundling Vercel deployment integration", () => {
);
});
-function expectAtLeastOneAssistantTextEvent(events: readonly HandleMessageStreamEvent[]): void {
+function expectAtLeastOneAssistantTextEvent(events: readonly MessageStreamEvent[]): void {
for (const event of events) {
if (
event.type === "message.completed" &&
diff --git a/packages/eve/test/vercel/vercel-verbose-bundling.vercel.test.ts b/packages/eve/test/vercel/vercel-verbose-bundling.vercel.test.ts
index f2875564d..feeaa1f1b 100644
--- a/packages/eve/test/vercel/vercel-verbose-bundling.vercel.test.ts
+++ b/packages/eve/test/vercel/vercel-verbose-bundling.vercel.test.ts
@@ -1,6 +1,6 @@
import { afterAll, beforeAll, describe, it } from "vitest";
import { VERBOSE_BUNDLING_DESCRIPTOR } from "../../src/internal/testing/scenario-apps/verbose-bundling.js";
-import type { HandleMessageStreamEvent } from "../../src/protocol/message.js";
+import type { MessageStreamEvent } from "../../src/protocol/message.js";
import type { RuntimeToolResultActionResult } from "../../src/runtime/actions/types.js";
import { sendDevelopmentMessage } from "../dev-client-harness/send-message.js";
import { createDevelopmentSessionState } from "../dev-client-harness/session.js";
@@ -108,7 +108,7 @@ async function sendToolMessageAndCollectResult(input: {
}
function extractToolResult(
- events: readonly HandleMessageStreamEvent[],
+ events: readonly MessageStreamEvent[],
toolName: string,
): RuntimeToolResultActionResult | undefined {
for (const event of events) {