Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): add eve/server for in-process session stream reads (#4090)

Matan Kushner4b195e931970
diff --git a/.changeset/eve-server-sessions.md b/.changeset/eve-server-sessions.md
new file mode 100644
index 000000000..18062fb50
--- /dev/null
+++ b/.changeset/eve-server-sessions.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add `eve/server`, whose `sessions.attach(sessionId).stream({ startIndex, follow, signal })` reads a session's durable event stream in process from hooks, tools, schedules, and channel routes, with the same shape as the client and no HTTP round trip.
diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.md
index d3babc363..239b4317c 100644
--- a/docs/concepts/sessions-runs-and-streaming.md
+++ b/docs/concepts/sessions-runs-and-streaming.md
@@ -300,6 +300,24 @@ For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client`
Start with the [Client SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
+## Read a session in process
+
+Code running inside the agent's own deployment, such as a hook, tool, schedule, or channel route, can read a session's durable stream without calling its own HTTP route. `eve/server` exposes the same `attach(sessionId).stream(...)` shape as the client, so it needs no deployment URL, credentials, or stream protocol:
+
+```ts
+import { sessions } from "eve/server";
+
+const events = sessions.attach(sessionId).stream({ startIndex, follow: false });
+
+for await (const event of events) {
+ await saveEvent(sessionId, event.meta.id, event);
+}
+```
+
+`stream()` accepts `startIndex` (negative values count back from the tail), `follow`, and `signal`. Key stored events on [`meta.id`](#the-event-envelope), which stays stable across reads. With `follow: false`, the read ends at the durable tail observed when it opens; otherwise it keeps following new events until the stream closes or the signal aborts.
+
+A read reflects events that are already durable. In a hook, the current step's events may still be buffered, so a bounded read there can end before the event that triggered the hook; read again later to catch up. `sessions` reads any session ID without channel auth, so check that a caller may read a session before passing an ID from a request. It is available only in code that runs inside the eve server.
+
## Inspect the agent over HTTP
`GET /eve/v1/info` returns agent-info version 6, a JSON inspection snapshot of the effective compiled agent. It reports the selected config; active tools, instructions, memory slots, skills, channels, schedules, sandbox, connections, hooks, and instrumentation with explicit source ownership; dynamic resolvers separately from their session-specific output; local and remote agents in separate collections; prepared built-in effects; and shadowed or disabled source diagnostics. Memory tool wrappers include their selected memory-source dependency. Channel routes appear in the same effective order used by the HTTP host. Static instructions remain an ordered array whose entries expose `content` and `role`. Sandbox inspection exposes the opaque `revisionHash` that identifies its compiler-discovered environment inputs.
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 98ffb077d..3ecba4fb7 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -112,46 +112,47 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
## Imports at a glance
-| Import | Holds |
-| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `eve` | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types |
-| `eve/tools` | `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDurableSchema`, `defineDynamic`, `disableTool`, tool types |
-| `eve/tools/{bash,read_file,write_file,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions |
-| `eve/tools/approval` | Approval types and `auto`, `always`, `once`, `never` |
-| `eve/tools/ask_question` | Opt-in `askQuestion` tool factory |
-| `eve/tools/web_search` | Provider-managed `webSearch` configuration |
-| `eve/tools/workflow` | Runtime-generated `workflow` tool factory |
-| `eve/tools/sleep` | Opt-in durable `sleep` tool |
-| `eve/tools/no_reply` | Opt-in `noReply` tool factory |
-| `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic` |
-| `eve/channels` | `defineChannel`, `disableRoute`, route verbs |
-| `eve/channels/eve` | `eveChannel` |
-| `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` |
-| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories |
-| `eve/hooks` | `defineHook` |
-| `eve/schedules` | `defineSchedule` |
-| `eve/skills` | `defineSkill`, `defineDynamic` |
-| `eve/instructions` | `defineInstructions`, `defineDynamic` |
-| `eve/memory` | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types |
-| `eve/memory/scope` | `byPrincipal` and memory scope helpers |
-| `eve/memory/file` | `fileMemory`, `inMemory`, and the conditional document backend contract |
-| `eve/memory/file/vercel` | `vercelBlob` and Vercel Blob backend options |
-| `eve/context` | `defineState`, session and state types |
-| `eve/sandbox` | `defineSandbox`, provider environments, and sandbox session types |
-| `eve/instrumentation` | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types |
-| `eve/instrumentation/otel` | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types |
-| `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |
-| [`eve/models`](../guides/evaluate) | Automatic model selection with `auto` |
-| `eve/models/openai` | `openai`, `chatgpt`, deprecated `experimental_chatgpt` |
-| `eve/models/anthropic` | `anthropic` |
-| [`eve/ai`](../guides/evaluate#evaluate-inside-a-tool) | Standalone `evaluate` |
-| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
-| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |
-| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |
-| `eve/evals/loaders` | `loadJson`, `loadYaml` |
-| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |
-| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |
-| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, response errors |
+| Import | Holds |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `eve` | `defineAgent`, `defineRemoteAgent`, `defineDynamic`, agent config types |
+| `eve/tools` | `defineTool`, `defineWorkflowTool`, `defineDurableCallback`, `defineDurableSchema`, `defineDynamic`, `disableTool`, tool types |
+| `eve/tools/{bash,read_file,write_file,web_fetch,load_skill,glob,grep}` | Individual reusable tool definitions |
+| `eve/tools/approval` | Approval types and `auto`, `always`, `once`, `never` |
+| `eve/tools/ask_question` | Opt-in `askQuestion` tool factory |
+| `eve/tools/web_search` | Provider-managed `webSearch` configuration |
+| `eve/tools/workflow` | Runtime-generated `workflow` tool factory |
+| `eve/tools/sleep` | Opt-in durable `sleep` tool |
+| `eve/tools/no_reply` | Opt-in `noReply` tool factory |
+| `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection`, `defineDynamic` |
+| `eve/channels` | `defineChannel`, `disableRoute`, route verbs |
+| `eve/channels/eve` | `eveChannel` |
+| `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` |
+| `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories |
+| `eve/hooks` | `defineHook` |
+| `eve/schedules` | `defineSchedule` |
+| `eve/skills` | `defineSkill`, `defineDynamic` |
+| `eve/instructions` | `defineInstructions`, `defineDynamic` |
+| `eve/memory` | `defineMemory`, `defineMemoryProvider`, provider and lifecycle types |
+| `eve/memory/scope` | `byPrincipal` and memory scope helpers |
+| `eve/memory/file` | `fileMemory`, `inMemory`, and the conditional document backend contract |
+| `eve/memory/file/vercel` | `vercelBlob` and Vercel Blob backend options |
+| `eve/context` | `defineState`, session and state types |
+| `eve/sandbox` | `defineSandbox`, provider environments, and sandbox session types |
+| `eve/instrumentation` | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types |
+| `eve/instrumentation/otel` | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types |
+| `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |
+| [`eve/models`](../guides/evaluate) | Automatic model selection with `auto` |
+| `eve/models/openai` | `openai`, `chatgpt`, deprecated `experimental_chatgpt` |
+| `eve/models/anthropic` | `anthropic` |
+| [`eve/ai`](../guides/evaluate#evaluate-inside-a-tool) | Standalone `evaluate` |
+| `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types |
+| `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` |
+| `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` |
+| `eve/evals/loaders` | `loadJson`, `loadYaml` |
+| `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` |
+| `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins |
+| [`eve/client`](../guides/client/overview) | `Client`, `ClientSession`, health and agent-info schemas, response errors |
+| [`eve/server`](../concepts/sessions-runs-and-streaming#read-a-session-in-process) | `sessions`, for reading session streams in process |
Exported types ship from the same entrypoint as the helper they describe (for example `ToolDefinition` and `ToolContext` from `eve/tools`). The `exports` field in `packages/eve/package.json` lists every public entrypoint.
diff --git a/packages/eve/package.json b/packages/eve/package.json
index e540ec232..4f8783f68 100644
--- a/packages/eve/package.json
+++ b/packages/eve/package.json
@@ -407,6 +407,11 @@
"import": "./dist/src/public/schedules/index.js",
"default": "./dist/src/public/schedules/index.js"
},
+ "./server": {
+ "types": "./dist/src/public/server/index.d.ts",
+ "import": "./dist/src/public/server/index.js",
+ "default": "./dist/src/public/server/index.js"
+ },
"./channels": {
"types": "./dist/src/public/channels/index.d.ts",
"import": "./dist/src/public/channels/index.js",
diff --git a/packages/eve/src/execution/session-event-stream.test.ts b/packages/eve/src/execution/session-event-stream.test.ts
new file mode 100644
index 000000000..7491d4073
--- /dev/null
+++ b/packages/eve/src/execution/session-event-stream.test.ts
@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { stampTestEvent } from "#internal/testing/events.js";
+import { createSessionWaitingEvent, type MessageStreamEvent } from "#protocol/message.js";
+import { sessions } from "#public/server/index.js";
+
+const getRunMock = vi.fn();
+
+vi.mock("#compiled/@workflow/core/runtime.js", () => ({
+ getRun: (...args: unknown[]) => getRunMock(...args),
+}));
+
+const encoder = new TextEncoder();
+
+/**
+ * Mocks one session's durable stream holding `stored` events. With
+ * `open: true`, reads never reach EOF, like a live session.
+ */
+function mockSessionStream(
+ stored: readonly MessageStreamEvent[],
+ options: { open?: boolean } = {},
+) {
+ const startIndexes: Array<number | undefined> = [];
+ const cancelled: Array<number | undefined> = [];
+ getRunMock.mockImplementation(() => ({
+ getReadable(readOptions?: { startIndex?: number }) {
+ const startIndex = readOptions?.startIndex;
+ const readable = new ReadableStream<Uint8Array>({
+ start(controller) {
+ if (startIndex === undefined) return;
+ startIndexes.push(startIndex);
+ for (const event of stored.slice(startIndex)) {
+ controller.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+ }
+ if (!options.open) controller.close();
+ },
+ cancel() {
+ cancelled.push(startIndex);
+ },
+ });
+ return Object.assign(readable, { getTailIndex: async () => stored.length - 1 });
+ },
+ }));
+ return { cancelled, startIndexes };
+}
+
+const storedEvents = (count: number) =>
+ Array.from({ length: count }, (_, index) => stampTestEvent(createSessionWaitingEvent(), index));
+
+async function collect(iterable: AsyncIterable<MessageStreamEvent>) {
+ const events: MessageStreamEvent[] = [];
+ for await (const event of iterable) events.push(event);
+ return events;
+}
+
+afterEach(() => {
+ getRunMock.mockReset();
+});
+
+describe("sessions.attach().stream()", () => {
+ it("ends a bounded read at the tail observed when it opens", async () => {
+ const stored = storedEvents(3);
+ const stream = mockSessionStream(stored, { open: true });
+
+ const events = await collect(
+ sessions.attach("wrun_1").stream({ startIndex: 1, follow: false }),
+ );
+
+ expect(getRunMock).toHaveBeenCalledWith("wrun_1");
+ expect(events.map((event) => event.meta.id)).toEqual([stored[1]!.meta.id, stored[2]!.meta.id]);
+ expect(stream.startIndexes).toEqual([1]);
+ expect(stream.cancelled).toContain(1);
+ });
+
+ it("resolves a tail-relative start against the tail", async () => {
+ const stored = storedEvents(5);
+ const stream = mockSessionStream(stored);
+
+ const events = await collect(sessions.attach("wrun_1").stream({ startIndex: -2 }));
+
+ expect(events.map((event) => event.meta.id)).toEqual([stored[3]!.meta.id, stored[4]!.meta.id]);
+ expect(stream.startIndexes).toEqual([3]);
+ });
+
+ it("returns immediately when a bounded read starts past the tail", async () => {
+ const stream = mockSessionStream(storedEvents(2));
+
+ await expect(
+ collect(sessions.attach("wrun_1").stream({ startIndex: 2, follow: false })),
+ ).resolves.toEqual([]);
+ expect(stream.startIndexes).toEqual([]);
+ });
+
+ it("stops a following read when its signal aborts", async () => {
+ const stored = storedEvents(2);
+ const stream = mockSessionStream(stored, { open: true });
+ const abort = new AbortController();
+ const events: MessageStreamEvent[] = [];
+
+ for await (const event of sessions.attach("wrun_1").stream({ signal: abort.signal })) {
+ events.push(event);
+ if (events.length === 2) abort.abort();
+ }
+
+ expect(events.map((event) => event.meta.id)).toEqual(stored.map((event) => event.meta.id));
+ expect(stream.cancelled).toContain(0);
+ });
+});
diff --git a/packages/eve/src/execution/session-event-stream.ts b/packages/eve/src/execution/session-event-stream.ts
new file mode 100644
index 000000000..49ce5e22a
--- /dev/null
+++ b/packages/eve/src/execution/session-event-stream.ts
@@ -0,0 +1,99 @@
+import { parseNdjsonStream } from "#execution/ndjson-stream.js";
+import { getRun } from "#internal/workflow/runtime.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
+import {
+ normalizePersistedMessageStreamEvent,
+ type MessageStreamEventForVersion,
+ type MessageStreamVersion,
+} from "#protocol/message-version.js";
+
+/** Options for {@link streamSessionEvents}. */
+export interface SessionEventStreamOptions {
+ /**
+ * Zero-based index of the first event to read. Negative values count back
+ * from the durable tail (`-1` is the latest event). Defaults to `0`.
+ */
+ readonly startIndex?: number;
+ /**
+ * Whether to keep following events recorded after the read opens. When
+ * `false`, the read ends at the durable tail observed when it opens.
+ * Defaults to `true`.
+ */
+ readonly follow?: boolean;
+ /** Stops the read and releases the underlying stream reader. */
+ readonly signal?: AbortSignal;
+}
+
+/**
+ * Reads one session's durable event stream. Negative `startIndex` values count
+ * back from the tail.
+ */
+export function readSessionEventStream(
+ sessionId: string,
+ startIndex?: number,
+): ReadableStream<MessageStreamEvent> {
+ return parseNdjsonStream<MessageStreamEvent>(
+ () => getRun(sessionId).getReadable({ startIndex }),
+ normalizePersistedEvent,
+ );
+}
+
+/** Returns the index of the last durably recorded event, or `-1` before the first. */
+export async function readSessionStreamTailIndex(sessionId: string): Promise<number> {
+ // The readable is never consumed; cancel it so the unread source does not linger.
+ const readable = getRun(sessionId).getReadable();
+ try {
+ return await readable.getTailIndex();
+ } finally {
+ await readable.cancel().catch(() => {});
+ }
+}
+
+/**
+ * Iterates one session's durable events in process, without the HTTP stream
+ * route.
+ *
+ * A bounded read counts events up from `startIndex` to find the tail. That
+ * holds because the writer persists exactly one chunk per event (see
+ * `createOrderedStreamEmitter`).
+ */
+export async function* streamSessionEvents(
+ sessionId: string,
+ options: SessionEventStreamOptions = {},
+): AsyncGenerator<MessageStreamEvent, void, undefined> {
+ const { follow = true, signal } = options;
+ const requestedStartIndex = options.startIndex ?? 0;
+ if (signal?.aborted) return;
+
+ let tailIndex: number | undefined;
+ let startIndex = requestedStartIndex;
+ if (!follow || requestedStartIndex < 0) {
+ tailIndex = await readSessionStreamTailIndex(sessionId);
+ if (requestedStartIndex < 0) startIndex = Math.max(0, tailIndex + 1 + requestedStartIndex);
+ }
+ if (!follow && tailIndex !== undefined && startIndex > tailIndex) return;
+
+ const reader = readSessionEventStream(sessionId, startIndex).getReader();
+ const cancel = () => void reader.cancel(signal?.reason).catch(() => {});
+ signal?.addEventListener("abort", cancel, { once: true });
+ try {
+ let index = startIndex;
+ while (!signal?.aborted) {
+ const { done, value } = await reader.read();
+ if (done) return;
+ yield value;
+ if (!follow && tailIndex !== undefined && index >= tailIndex) return;
+ index += 1;
+ }
+ } finally {
+ signal?.removeEventListener("abort", cancel);
+ await reader.cancel().catch(() => {});
+ reader.releaseLock();
+ }
+}
+
+function normalizePersistedEvent(value: unknown): MessageStreamEvent {
+ return normalizePersistedMessageStreamEvent(
+ value as MessageStreamEventForVersion<MessageStreamVersion>,
+ );
+}
diff --git a/packages/eve/src/execution/session/entry.integration.test.ts b/packages/eve/src/execution/session/entry.integration.test.ts
index 8fd676cac..5f1f527fa 100644
--- a/packages/eve/src/execution/session/entry.integration.test.ts
+++ b/packages/eve/src/execution/session/entry.integration.test.ts
@@ -18,6 +18,7 @@ import {
import { createWorkflowRuntime } from "#execution/workflow-runtime.js";
import { normalizeEveAttributes } from "#runtime/attributes/normalize.js";
import { defineHook } from "#public/definitions/hook.js";
+import { sessions } from "#public/server/index.js";
import type { MessageStreamEvent } from "#protocol/message.js";
import { isEventId } from "#internal/testing/event-id.js";
import { always } from "#tools/approval/policies.js";
@@ -367,6 +368,72 @@ describe("workflowEntry integration", () => {
});
});
+ it("reads a session's durable stream in process through eve/server, including from a hook", async () => {
+ const hookReads: string[][] = [];
+ const runtime = await createTestRuntime({
+ agent: { name: "workflow-entry-server-sessions" },
+ modules: [
+ {
+ logicalPath: "hooks/read-own-stream.ts",
+ loadNamespace: async () => ({
+ default: defineHook({
+ events: {
+ async "step.completed"(_event, ctx) {
+ const ids: string[] = [];
+ for await (const event of sessions
+ .attach(ctx.session.id)
+ .stream({ follow: false })) {
+ ids.push(event.meta.id);
+ }
+ hookReads.push(ids);
+ },
+ },
+ }),
+ }),
+ },
+ ],
+ });
+
+ await runtime.run(async () => {
+ const run = await start(workflowEntry, [
+ {
+ kind: "initial",
+ ownerDeploymentId: "dpl_inline",
+ input: { message: "read your own stream" },
+ serializedContext: buildSerializedContext({
+ channelKind: "http",
+ continuationToken: "http:workflow-entry-server-sessions",
+ }),
+ },
+ ]);
+ const stream = captureTurnEvents(run);
+ let firstTurn: readonly MessageStreamEvent[];
+ try {
+ firstTurn = await stream.nextTurn();
+ } finally {
+ stream.dispose();
+ }
+
+ try {
+ const events: MessageStreamEvent[] = [];
+ for await (const event of sessions.attach(run.runId).stream({ follow: false })) {
+ events.push(event);
+ }
+ const ids = events.map((event) => event.meta.id);
+ expect(ids.slice(0, firstTurn.length)).toEqual(firstTurn.map((event) => event.meta.id));
+
+ // A hook's bounded read ends at the durable tail. The step's own writes
+ // may still be buffered, so it can see only an earlier prefix.
+ expect(hookReads.length).toBeGreaterThan(0);
+ for (const hookRead of hookReads) {
+ expect(hookRead).toEqual(ids.slice(0, hookRead.length));
+ }
+ } finally {
+ await run.cancel();
+ }
+ });
+ });
+
it("completes an expired conversation and lets its channel start a fresh session", async () => {
const runtime = await createTestRuntime({ agent: { name: "workflow-entry-timeout" } });
const continuationToken = "http:workflow-entry-timeout";
diff --git a/packages/eve/src/execution/workflow-runtime.ts b/packages/eve/src/execution/workflow-runtime.ts
index 50081e054..be530c46f 100644
--- a/packages/eve/src/execution/workflow-runtime.ts
+++ b/packages/eve/src/execution/workflow-runtime.ts
@@ -38,18 +38,16 @@ import {
type WorkflowMetadata,
} from "#internal/workflow/runtime.js";
import type { MessageStreamEvent } from "#protocol/message.js";
-import {
- normalizePersistedMessageStreamEvent,
- type MessageStreamEventForVersion,
- type MessageStreamVersion,
-} from "#protocol/message-version.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";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
import { buildRunContext } from "#execution/runtime-context.js";
import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";
-import { parseNdjsonStream } from "#execution/ndjson-stream.js";
+import {
+ readSessionEventStream,
+ readSessionStreamTailIndex,
+} from "#execution/session-event-stream.js";
import {
SESSION_HANDOFF_VERSION,
type HandoffWorkflowEntryInput,
@@ -202,10 +200,7 @@ export function createWorkflowRuntime(config: {
let events: ReadableStream<MessageStreamEvent> | undefined;
const getEvents = () => {
- events ??= parseNdjsonStream<MessageStreamEvent>(
- () => getRun(run.runId).getReadable(),
- normalizePersistedEvent,
- );
+ events ??= readSessionEventStream(run.runId);
return events;
};
@@ -233,20 +228,11 @@ export function createWorkflowRuntime(config: {
sessionId: string,
options?: GetEventStreamOptions,
): Promise<ReadableStream<MessageStreamEvent>> {
- return parseNdjsonStream<MessageStreamEvent>(
- () => getRun(sessionId).getReadable({ startIndex: options?.startIndex }),
- normalizePersistedEvent,
- );
+ return readSessionEventStream(sessionId, options?.startIndex);
},
async getStreamTailIndex(sessionId: string): Promise<number> {
- // The readable is never consumed; cancel it so the unread source does not linger.
- const readable = getRun(sessionId).getReadable();
- try {
- return await readable.getTailIndex();
- } finally {
- await readable.cancel().catch(() => {});
- }
+ return await readSessionStreamTailIndex(sessionId);
},
async resolveContinuation(
@@ -299,12 +285,6 @@ export async function startSessionOwnerStep(input: SessionOwnerStartInput): Prom
);
}
-function normalizePersistedEvent(value: unknown): MessageStreamEvent {
- return normalizePersistedMessageStreamEvent(
- value as MessageStreamEventForVersion<MessageStreamVersion>,
- );
-}
-
async function dispatchWorkflowCommand<TCommand extends SessionCommand>(
token: string | SessionInboxAddress,
command: TCommand,
diff --git a/packages/eve/src/public/server/index.ts b/packages/eve/src/public/server/index.ts
new file mode 100644
index 000000000..1be9294e5
--- /dev/null
+++ b/packages/eve/src/public/server/index.ts
@@ -0,0 +1,40 @@
+/**
+ * Server-side session access for code running inside an eve deployment,
+ * such as hooks, tools, schedules, and channel routes.
+ */
+
+import {
+ type SessionEventStreamOptions,
+ streamSessionEvents,
+} from "#execution/session-event-stream.js";
+import type { MessageStreamEvent } from "#protocol/message.js";
+
+/** Options for {@link ServerSession.stream}. */
+export type ServerSessionStreamOptions = SessionEventStreamOptions;
+
+/** A handle to one session's durable event stream, read in process. */
+export interface ServerSession {
+ readonly sessionId: string;
+ /**
+ * Reads the session's events in stream order. With `follow: false`, the read
+ * ends at the durable tail observed when it opens.
+ */
+ stream(options?: ServerSessionStreamOptions): AsyncIterable<MessageStreamEvent>;
+}
+
+/**
+ * Reads session streams in process, without calling the deployment's own
+ * HTTP stream route.
+ *
+ * Available only in code running inside the eve server, where the session
+ * store is configured. It reads any session ID without channel auth, so check
+ * that the caller may read a session before passing an ID from a request.
+ */
+export const sessions = {
+ attach(sessionId: string): ServerSession {
+ return {
+ sessionId,
+ stream: (options) => streamSessionEvents(sessionId, options),
+ };
+ },
+};