The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Implement re subscribe to stream (#12)
Srajan Asthana34a1e08eedca
diff --git a/AGENTS.md b/AGENTS.mdindex a8c3bb38c..de2949441 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -13,3 +13,4 @@- Code under `packages/sdk` is autogenerated and MUST NOT be edited manually; changes belong in the generator or its source, not in the generated output.- Tests MUST live under a top-level `test` directory that mirrors the `src` layout; they MUST NOT be inlined under `src`.- Functions with more than one parameter of the same type MUST take a single options object (e.g. `f({ a, b }: { a: string; b: string })`); they MUST NOT use multiple positional parameters of that repeated type (e.g. `f(a: string, b: string)`).+- Zod unions MUST use `z.discriminatedUnion` whenever every member carries a shared literal discriminator field; `z.union` is only permitted when no such common discriminator exists.diff --git a/fern/fern.config.json b/fern/fern.config.jsonindex 14e880ebf..d52d52b9c 100644--- a/fern/fern.config.json+++ b/fern/fern.config.json@@ -1,4 +1,4 @@{"organization": "truefoundry",- "version": "5.82.0"+ "version": "5.89.4"}diff --git a/fern/generators.yml b/fern/generators.ymlindex 29357a88b..a6d8a8a9e 100644--- a/fern/generators.yml+++ b/fern/generators.yml@@ -35,7 +35,7 @@ groups:ts-sdk:generators:- name: fernapi/fern-typescript-node-sdk- version: 3.85.0+ version: 3.86.0output:location: local-file-systempath: ../packages/sdkdiff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.jsonindex d1f30c7ae..86cc391a8 100644--- a/fern/openapi/openapi.json+++ b/fern/openapi/openapi.json@@ -2097,75 +2097,92 @@"type": "string"},"ResponseFormat": {+ "discriminator": {+ "mapping": {+ "json_object": "#/components/schemas/ResponseFormatJsonObject",+ "json_schema": "#/components/schemas/ResponseFormatJsonSchema",+ "text": "#/components/schemas/ResponseFormatText"+ },+ "propertyName": "type"+ },"oneOf": [{- "properties": {- "type": {- "enum": [- "text"- ],- "type": "string"- }- },- "required": [- "type"- ],- "type": "object"+ "$ref": "#/components/schemas/ResponseFormatText"},{- "properties": {- "type": {- "enum": [- "json_object"- ],- "type": "string"- }- },- "required": [- "type"- ],- "type": "object"+ "$ref": "#/components/schemas/ResponseFormatJsonObject"},{+ "$ref": "#/components/schemas/ResponseFormatJsonSchema"+ }+ ]+ },+ "ResponseFormatJsonObject": {+ "properties": {+ "type": {+ "enum": [+ "json_object"+ ],+ "type": "string"+ }+ },+ "required": [+ "type"+ ],+ "type": "object"+ },+ "ResponseFormatJsonSchema": {+ "properties": {+ "json_schema": {"properties": {- "json_schema": {- "properties": {- "description": {- "type": "string"- },- "name": {- "type": "string"- },- "schema": {- "additionalProperties": {},- "type": "object"- },- "strict": {- "type": [- "boolean",- "null"- ]- }- },- "required": [- "name"- ],- "type": "object"+ "description": {+ "type": "string"},- "type": {- "enum": [- "json_schema"- ],+ "name": {"type": "string"+ },+ "schema": {+ "additionalProperties": {},+ "type": "object"+ },+ "strict": {+ "type": [+ "boolean",+ "null"+ ]}},"required": [- "type",- "json_schema"+ "name"],"type": "object"+ },+ "type": {+ "enum": [+ "json_schema"+ ],+ "type": "string"}- ]+ },+ "required": [+ "type",+ "json_schema"+ ],+ "type": "object"+ },+ "ResponseFormatText": {+ "properties": {+ "type": {+ "enum": [+ "text"+ ],+ "type": "string"+ }+ },+ "required": [+ "type"+ ],+ "type": "object"},"RuntimeConfig": {"properties": {@@ -3150,7 +3167,17 @@"$ref": "#/components/schemas/TurnMetrics"},"output": {- "$ref": "#/components/schemas/ModelMessageEvent"+ "anyOf": [+ {+ "$ref": "#/components/schemas/ModelMessageEvent"+ },+ {+ "type": "null"+ },+ {+ "type": "null"+ }+ ]},"required_actions": {"items": {@@ -3167,6 +3194,7 @@},"required": ["status",+ "output","required_actions","completed_at"],@@ -4541,6 +4569,99 @@"x-fern-sdk-method-name": "list_turn_events"}},+ "/api/v1/sessions/{sessionId}/turns/{turnId}/subscribe": {+ "get": {+ "description": "Subscribe to the live SSE stream for a turn. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).",+ "parameters": [+ {+ "description": "Session identifier.",+ "in": "path",+ "name": "sessionId",+ "required": true,+ "schema": {+ "description": "Session identifier.",+ "maxLength": 64,+ "minLength": 1,+ "type": "string"+ }+ },+ {+ "description": "Turn identifier.",+ "in": "path",+ "name": "turnId",+ "required": true,+ "schema": {+ "description": "Turn identifier.",+ "minLength": 1,+ "type": "string"+ }+ },+ {+ "in": "query",+ "name": "after_sequence_number",+ "required": false,+ "schema": {+ "minimum": 0,+ "type": "integer"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "text/event-stream": {+ "schema": {+ "$ref": "#/components/schemas/TurnStreamingEvent"+ }+ }+ },+ "description": "Server-Sent Events stream of turn events (deltas and lifecycle)."+ },+ "400": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "Invalid request body."+ },+ "404": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "Turn not found."+ },+ "412": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "Cannot subscribe — the live stream no longer exists."+ }+ },+ "summary": "Subscribe to a running turn",+ "tags": [+ "Sessions"+ ],+ "x-fern-sdk-group-name": [+ "sessions"+ ],+ "x-fern-sdk-method-name": "subscribe_to_turn",+ "x-fern-streaming": {+ "format": "sse",+ "resumable": true+ }+ }+ },"/api/v1/settings/mcp-servers": {"get": {"description": "All configured MCP servers with nested auth_status (settings / admin projection).",diff --git a/packages/harness/src/agent-session/TurnHandle.ts b/packages/harness/src/agent-session/TurnHandle.tsindex 60a751fc6..4b7803ac8 100644--- a/packages/harness/src/agent-session/TurnHandle.ts+++ b/packages/harness/src/agent-session/TurnHandle.ts@@ -300,8 +300,7 @@ export class TurnHandle<TTurnCustom extends object = Record<string, never>> {} else {terminalState = {status: 'done',- // TODO: revert alongside TurnStateDone.output.- ...(executeResult.output && { output: executeResult.output }),+ output: executeResult.output,required_actions: executeResult.required_actions,completed_at: createdAtIso,metrics,diff --git a/packages/harness/src/agent-session/schemas/turn.ts b/packages/harness/src/agent-session/schemas/turn.tsindex c9b1cf608..48b8c0cd5 100644--- a/packages/harness/src/agent-session/schemas/turn.ts+++ b/packages/harness/src/agent-session/schemas/turn.ts@@ -64,8 +64,7 @@ export const TurnStateErrorSchema = zexport const TurnStateDoneSchema = z.object({status: z.literal('done'),- // TODO: restore `.nullable()`; it marks the shared component nullable and breaks SDK codegen.- output: ModelMessageEventSchema.optional(),+ output: z.union([ModelMessageEventSchema, z.null()]),required_actions: z.array(ActionRequiredEventSchema),completed_at: z.string(),metrics: TurnMetricsSchema.optional(),diff --git a/packages/harness/src/core/events/schema.ts b/packages/harness/src/core/events/schema.tsindex 94fb17223..e12f59510 100644--- a/packages/harness/src/core/events/schema.ts+++ b/packages/harness/src/core/events/schema.ts@@ -338,7 +338,7 @@ export const ActionRequiredEventSchema = z.openapi('ActionRequiredEvent');/** Neutral harness output-event membership (not an HTTP/OpenAPI AgentResponse aggregate). */-export const AgentOutputEventSchema = z.union([+export const AgentOutputEventSchema = z.discriminatedUnion('type', [ModelMessageEventSchema,ToolResponseEventSchema,ThreadCreatedEventSchema,diff --git a/packages/harness/src/core/llm/responseFormat.ts b/packages/harness/src/core/llm/responseFormat.tsindex e42323617..cd6c11756 100644--- a/packages/harness/src/core/llm/responseFormat.ts+++ b/packages/harness/src/core/llm/responseFormat.ts@@ -6,23 +6,37 @@ import type { ChatCompletionCreateParamsStreaming } from 'openai/resources/chat'* share one type without agentSession → core inversion.* `passthrough()` lets unknown fields within a known `type` flow through to the LLM.*/-export const ResponseFormatSchema = z- .discriminatedUnion('type', [- z.object({ type: z.literal('text') }).passthrough(),- z.object({ type: z.literal('json_object') }).passthrough(),- z++const ResponseFormatTextSchema = z+ .object({ type: z.literal('text') })+ .passthrough()+ .openapi('ResponseFormatText');++const ResponseFormatJsonObjectSchema = z+ .object({ type: z.literal('json_object') })+ .passthrough()+ .openapi('ResponseFormatJsonObject');++const ResponseFormatJsonSchemaSchema = z+ .object({+ type: z.literal('json_schema'),+ json_schema: z.object({- type: z.literal('json_schema'),- json_schema: z- .object({- name: z.string(),- description: z.string().optional(),- schema: z.record(z.string(), z.unknown()).optional(),- strict: z.boolean().nullable().optional(),- })- .passthrough(),+ name: z.string(),+ description: z.string().optional(),+ schema: z.record(z.string(), z.unknown()).optional(),+ strict: z.boolean().nullable().optional(),}).passthrough(),+ })+ .passthrough()+ .openapi('ResponseFormatJsonSchema');++export const ResponseFormatSchema = z+ .discriminatedUnion('type', [+ ResponseFormatTextSchema,+ ResponseFormatJsonObjectSchema,+ ResponseFormatJsonSchemaSchema,]).openapi('ResponseFormat');diff --git a/packages/harness/tests/agent-session/testHelpers.ts b/packages/harness/tests/agent-session/testHelpers.tsindex 0d95ce2ab..a741bd437 100644--- a/packages/harness/tests/agent-session/testHelpers.ts+++ b/packages/harness/tests/agent-session/testHelpers.ts@@ -178,8 +178,8 @@ export function makeCreateTurnInput(input: {export function makeDoneTurnState(): TerminalTurnState {return {- // TODO: restore `output: null` alongside TurnStateDone.output.status: 'done',+ output: null,required_actions: [],completed_at: new Date().toISOString(),};diff --git a/packages/sdk/.fern/metadata.json b/packages/sdk/.fern/metadata.jsonindex c428fcbcb..0b4c85835 100644--- a/packages/sdk/.fern/metadata.json+++ b/packages/sdk/.fern/metadata.json@@ -1,7 +1,7 @@{- "cliVersion": "5.82.0",+ "cliVersion": "5.89.4","generatorName": "fernapi/fern-typescript-node-sdk",- "generatorVersion": "3.85.0",+ "generatorVersion": "3.86.0","generatorConfig": {"packageJson": {"name": "trueharness"@@ -26,7 +26,7 @@"streamType": "web","useDefaultRequestParameterValues": true},- "originGitCommit": "d6feb6f99b8379b4d4d21f4879ba997976282fbd",+ "originGitCommit": "09ef45c28d8c9e97c441e3c7f0ab3afc321a7563","originGitCommitIsDirty": true,"invokedBy": "ci","requestedVersion": "0.0.0",diff --git a/packages/sdk/reference.md b/packages/sdk/reference.mdindex 693ed22e1..8bdc99c44 100644--- a/packages/sdk/reference.md+++ b/packages/sdk/reference.md@@ -936,6 +936,88 @@ await client.sessions.listTurnEvents("sessionId", "turnId");</dl>+</dd>+</dl>+</details>++<details><summary><code>client.sessions.<a href="/src/api/resources/sessions/client/Client.ts">subscribeToTurn</a>(sessionId, turnId, { ...params }) -> core.Stream<TrueHarness.TurnStreamingEvent></code></summary>+<dl>+<dd>++#### 📝 Description++<dl>+<dd>++<dl>+<dd>++Subscribe to the live SSE stream for a turn. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).+</dd>+</dl>+</dd>+</dl>++#### 🔌 Usage++<dl>+<dd>++<dl>+<dd>++```typescript+const response = await client.sessions.subscribeToTurn("sessionId", "turnId");+for await (const item of response) {+ console.log(item);+}++```+</dd>+</dl>+</dd>+</dl>++#### ⚙️ Parameters++<dl>+<dd>++<dl>+<dd>++**sessionId:** `string` — Session identifier.++</dd>+</dl>++<dl>+<dd>++**turnId:** `string` — Turn identifier.++</dd>+</dl>++<dl>+<dd>++**request:** `TrueHarness.SubscribeToTurnSessionsRequest`++</dd>+</dl>++<dl>+<dd>++**requestOptions:** `SessionsClient.RequestOptions`++</dd>+</dl>+</dd>+</dl>++</dd></dl></details>diff --git a/packages/sdk/src/api/resources/sessions/client/Client.ts b/packages/sdk/src/api/resources/sessions/client/Client.tsindex e27cb7d50..de5c0b073 100644--- a/packages/sdk/src/api/resources/sessions/client/Client.ts+++ b/packages/sdk/src/api/resources/sessions/client/Client.ts@@ -1179,4 +1179,157 @@ export class SessionsClient {},});}++ /**+ * Subscribe to the live SSE stream for a turn. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).+ */+ public subscribeToTurn(+ sessionId: string,+ turnId: string,+ request: TrueHarness.SubscribeToTurnSessionsRequest = {},+ requestOptions?: SessionsClient.RequestOptions,+ ): core.HttpResponsePromise<core.Stream<TrueHarness.TurnStreamingEvent>> {+ return core.HttpResponsePromise.fromPromise(this.__subscribeToTurn(sessionId, turnId, request, requestOptions));+ }++ private async __subscribeToTurn(+ sessionId: string,+ turnId: string,+ request: TrueHarness.SubscribeToTurnSessionsRequest = {},+ requestOptions?: SessionsClient.RequestOptions,+ ): Promise<core.WithRawResponse<core.Stream<TrueHarness.TurnStreamingEvent>>> {+ const { afterSequenceNumber } = request;+ const _queryParams: Record<string, unknown> = {+ after_sequence_number: afterSequenceNumber,+ };+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(this._options?.headers, requestOptions?.headers);+ const _response = await (this._options.fetcher ?? core.fetcher)<ReadableStream>({+ url: core.url.join(+ (await core.Supplier.get(this._options.baseUrl)) ??+ (await core.Supplier.get(this._options.environment)),+ `api/v1/sessions/${core.url.encodePathParam(sessionId)}/turns/${core.url.encodePathParam(turnId)}/subscribe`,+ ),+ method: "GET",+ headers: _headers,+ queryString: core.url+ .queryBuilder()+ .addMany(_queryParams)+ .mergeAdditional(requestOptions?.queryParams)+ .build(),+ responseType: "sse",+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,+ abortSignal: requestOptions?.abortSignal,+ fetchFn: this._options?.fetch,+ logging: this._options.logging,+ });+ const _reconnect = async (lastEventId: string) => {+ const _reconnectResponse = await (this._options.fetcher ?? core.fetcher)<ReadableStream>({+ url: core.url.join(+ (await core.Supplier.get(this._options.baseUrl)) ??+ (await core.Supplier.get(this._options.environment)),+ `api/v1/sessions/${core.url.encodePathParam(sessionId)}/turns/${core.url.encodePathParam(turnId)}/subscribe`,+ ),+ method: "GET",+ headers: { ..._headers, "Last-Event-ID": lastEventId },+ queryString: core.url+ .queryBuilder()+ .addMany(_queryParams)+ .mergeAdditional(requestOptions?.queryParams)+ .build(),+ responseType: "sse",+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,+ abortSignal: requestOptions?.abortSignal,+ fetchFn: this._options?.fetch,+ logging: this._options.logging,+ });+ if (!_reconnectResponse.ok) {+ throw new Error("SSE stream reconnection failed");+ }+ if (_reconnectResponse.body == null) {+ throw new Error("SSE stream reconnection failed: empty response body");+ }+ return _reconnectResponse.body;+ };+ if (_response.ok) {+ return {+ data: new core.Stream({+ stream: _response.body,+ parse: async (data) => {+ return serializers.TurnStreamingEvent.parseOrThrow(data, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ });+ },+ signal: requestOptions?.abortSignal,+ eventShape: {+ type: "sse",+ resumable: true,+ },+ reconnectionEnabled:+ requestOptions?.stream?.reconnectionEnabled ?? this._options?.stream?.reconnectionEnabled,+ maxReconnectionAttempts:+ requestOptions?.stream?.maxReconnectionAttempts ??+ this._options?.stream?.maxReconnectionAttempts,+ reconnect: _reconnect,+ }),+ rawResponse: _response.rawResponse,+ };+ }++ if (_response.error.reason === "status-code") {+ switch (_response.error.statusCode) {+ case 400:+ throw new TrueHarness.BadRequestError(+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ }),+ _response.rawResponse,+ );+ case 404:+ throw new TrueHarness.NotFoundError(+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ }),+ _response.rawResponse,+ );+ case 412:+ throw new TrueHarness.PreconditionFailedError(+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ }),+ _response.rawResponse,+ );+ default:+ throw new errors.TrueHarnessError({+ statusCode: _response.error.statusCode,+ body: _response.error.body,+ rawResponse: _response.rawResponse,+ });+ }+ }++ return handleNonStatusCodeError(+ _response.error,+ _response.rawResponse,+ "GET",+ "/api/v1/sessions/{sessionId}/turns/{turnId}/subscribe",+ );+ }}diff --git a/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.tsnew file mode 100644index 000000000..9c665fdf6--- /dev/null+++ b/packages/sdk/src/api/resources/sessions/client/requests/SubscribeToTurnSessionsRequest.ts@@ -0,0 +1,9 @@+// This file was auto-generated by Fern from our API Definition.++/**+ * @example+ * {}+ */+export interface SubscribeToTurnSessionsRequest {+ afterSequenceNumber?: number;+}diff --git a/packages/sdk/src/api/resources/sessions/client/requests/index.ts b/packages/sdk/src/api/resources/sessions/client/requests/index.tsindex 8e2942151..c71849aaf 100644--- a/packages/sdk/src/api/resources/sessions/client/requests/index.ts+++ b/packages/sdk/src/api/resources/sessions/client/requests/index.ts@@ -5,4 +5,5 @@ export type { ListEventsSessionsRequest } from "./ListEventsSessionsRequest.js";export type { ListSessionsRequest } from "./ListSessionsRequest.js";export type { ListTurnEventsSessionsRequest } from "./ListTurnEventsSessionsRequest.js";export type { ListTurnsSessionsRequest } from "./ListTurnsSessionsRequest.js";+export type { SubscribeToTurnSessionsRequest } from "./SubscribeToTurnSessionsRequest.js";export type { UpdateSessionRequest } from "./UpdateSessionRequest.js";diff --git a/packages/sdk/src/api/types/ResponseFormat.ts b/packages/sdk/src/api/types/ResponseFormat.tsindex 8eb79af18..757d997ad 100644--- a/packages/sdk/src/api/types/ResponseFormat.ts+++ b/packages/sdk/src/api/types/ResponseFormat.ts@@ -3,6 +3,6 @@import type * as TrueHarness from "../index.js";export type ResponseFormat =- | TrueHarness.ResponseFormatZero- | TrueHarness.ResponseFormatOne- | TrueHarness.ResponseFormatJsonSchema;+ | TrueHarness.ResponseFormatJsonObject+ | TrueHarness.ResponseFormatJsonSchema+ | TrueHarness.ResponseFormatText;diff --git a/packages/sdk/src/api/types/ResponseFormatOne.ts b/packages/sdk/src/api/types/ResponseFormatJsonObject.tssimilarity index 67%rename from packages/sdk/src/api/types/ResponseFormatOne.tsrename to packages/sdk/src/api/types/ResponseFormatJsonObject.tsindex 30a44a555..8879c9f17 100644--- a/packages/sdk/src/api/types/ResponseFormatOne.ts+++ b/packages/sdk/src/api/types/ResponseFormatJsonObject.ts@@ -1,5 +1,5 @@// This file was auto-generated by Fern from our API Definition.-export interface ResponseFormatOne {+export interface ResponseFormatJsonObject {type: "json_object";}diff --git a/packages/sdk/src/api/types/ResponseFormatZero.ts b/packages/sdk/src/api/types/ResponseFormatText.tssimilarity index 69%rename from packages/sdk/src/api/types/ResponseFormatZero.tsrename to packages/sdk/src/api/types/ResponseFormatText.tsindex 8b90fb2d7..19a066065 100644--- a/packages/sdk/src/api/types/ResponseFormatZero.ts+++ b/packages/sdk/src/api/types/ResponseFormatText.ts@@ -1,5 +1,5 @@// This file was auto-generated by Fern from our API Definition.-export interface ResponseFormatZero {+export interface ResponseFormatText {type: "text";}diff --git a/packages/sdk/src/api/types/TurnStateDone.ts b/packages/sdk/src/api/types/TurnStateDone.tsindex dddabae41..91e6ccd63 100644--- a/packages/sdk/src/api/types/TurnStateDone.ts+++ b/packages/sdk/src/api/types/TurnStateDone.ts@@ -5,7 +5,7 @@ import type * as TrueHarness from "../index.js";export interface TurnStateDone {completedAt: string;metrics?: TrueHarness.TurnMetrics;- output?: TrueHarness.ModelMessageEvent;+ output: TrueHarness.ModelMessageEvent | null;requiredActions: TrueHarness.ActionRequiredEvent[];status: "done";}diff --git a/packages/sdk/src/api/types/index.ts b/packages/sdk/src/api/types/index.tsindex b82da2ff1..7c16f9cc2 100644--- a/packages/sdk/src/api/types/index.ts+++ b/packages/sdk/src/api/types/index.ts@@ -103,10 +103,10 @@ export * from "./RequestErrorResponse.js";export * from "./RequestErrorResponseError.js";export * from "./ResourceName.js";export * from "./ResponseFormat.js";+export * from "./ResponseFormatJsonObject.js";export * from "./ResponseFormatJsonSchema.js";export * from "./ResponseFormatJsonSchemaJsonSchema.js";-export * from "./ResponseFormatOne.js";-export * from "./ResponseFormatZero.js";+export * from "./ResponseFormatText.js";export * from "./RuntimeConfig.js";export * from "./SandboxConfig.js";export * from "./SandboxCreatedEvent.js";diff --git a/packages/sdk/src/serialization/types/ResponseFormat.ts b/packages/sdk/src/serialization/types/ResponseFormat.tsindex b5fe393cf..8a4344663 100644--- a/packages/sdk/src/serialization/types/ResponseFormat.ts+++ b/packages/sdk/src/serialization/types/ResponseFormat.ts@@ -3,13 +3,13 @@import type * as TrueHarness from "../../api/index.js";import * as core from "../../core/index.js";import type * as serializers from "../index.js";+import { ResponseFormatJsonObject } from "./ResponseFormatJsonObject.js";import { ResponseFormatJsonSchema } from "./ResponseFormatJsonSchema.js";-import { ResponseFormatOne } from "./ResponseFormatOne.js";-import { ResponseFormatZero } from "./ResponseFormatZero.js";+import { ResponseFormatText } from "./ResponseFormatText.js";export const ResponseFormat: core.serialization.Schema<serializers.ResponseFormat.Raw, TrueHarness.ResponseFormat> =- core.serialization.undiscriminatedUnion([ResponseFormatZero, ResponseFormatOne, ResponseFormatJsonSchema]);+ core.serialization.undiscriminatedUnion([ResponseFormatJsonObject, ResponseFormatJsonSchema, ResponseFormatText]);export declare namespace ResponseFormat {- export type Raw = ResponseFormatZero.Raw | ResponseFormatOne.Raw | ResponseFormatJsonSchema.Raw;+ export type Raw = ResponseFormatJsonObject.Raw | ResponseFormatJsonSchema.Raw | ResponseFormatText.Raw;}diff --git a/packages/sdk/src/serialization/types/ResponseFormatOne.ts b/packages/sdk/src/serialization/types/ResponseFormatJsonObject.tssimilarity index 64%rename from packages/sdk/src/serialization/types/ResponseFormatOne.tsrename to packages/sdk/src/serialization/types/ResponseFormatJsonObject.tsindex 13c06c3f4..e52ee9540 100644--- a/packages/sdk/src/serialization/types/ResponseFormatOne.ts+++ b/packages/sdk/src/serialization/types/ResponseFormatJsonObject.ts@@ -4,14 +4,14 @@ import type * as TrueHarness from "../../api/index.js";import * as core from "../../core/index.js";import type * as serializers from "../index.js";-export const ResponseFormatOne: core.serialization.ObjectSchema<- serializers.ResponseFormatOne.Raw,- TrueHarness.ResponseFormatOne+export const ResponseFormatJsonObject: core.serialization.ObjectSchema<+ serializers.ResponseFormatJsonObject.Raw,+ TrueHarness.ResponseFormatJsonObject> = core.serialization.object({type: core.serialization.stringLiteral("json_object"),});-export declare namespace ResponseFormatOne {+export declare namespace ResponseFormatJsonObject {export interface Raw {type: "json_object";}diff --git a/packages/sdk/src/serialization/types/ResponseFormatZero.ts b/packages/sdk/src/serialization/types/ResponseFormatText.tssimilarity index 66%rename from packages/sdk/src/serialization/types/ResponseFormatZero.tsrename to packages/sdk/src/serialization/types/ResponseFormatText.tsindex fcd44b6f4..6aa57c681 100644--- a/packages/sdk/src/serialization/types/ResponseFormatZero.ts+++ b/packages/sdk/src/serialization/types/ResponseFormatText.ts@@ -4,14 +4,14 @@ import type * as TrueHarness from "../../api/index.js";import * as core from "../../core/index.js";import type * as serializers from "../index.js";-export const ResponseFormatZero: core.serialization.ObjectSchema<- serializers.ResponseFormatZero.Raw,- TrueHarness.ResponseFormatZero+export const ResponseFormatText: core.serialization.ObjectSchema<+ serializers.ResponseFormatText.Raw,+ TrueHarness.ResponseFormatText> = core.serialization.object({type: core.serialization.stringLiteral("text"),});-export declare namespace ResponseFormatZero {+export declare namespace ResponseFormatText {export interface Raw {type: "text";}diff --git a/packages/sdk/src/serialization/types/TurnStateDone.ts b/packages/sdk/src/serialization/types/TurnStateDone.tsindex d49861751..131301cb4 100644--- a/packages/sdk/src/serialization/types/TurnStateDone.ts+++ b/packages/sdk/src/serialization/types/TurnStateDone.ts@@ -11,7 +11,7 @@ export const TurnStateDone: core.serialization.ObjectSchema<serializers.TurnStatcore.serialization.object({completedAt: core.serialization.property("completed_at", core.serialization.string()),metrics: TurnMetrics.optional(),- output: ModelMessageEvent.optional(),+ output: ModelMessageEvent.nullable(),requiredActions: core.serialization.property("required_actions", core.serialization.list(ActionRequiredEvent)),status: core.serialization.stringLiteral("done"),});diff --git a/packages/sdk/src/serialization/types/index.ts b/packages/sdk/src/serialization/types/index.tsindex b82da2ff1..7c16f9cc2 100644--- a/packages/sdk/src/serialization/types/index.ts+++ b/packages/sdk/src/serialization/types/index.ts@@ -103,10 +103,10 @@ export * from "./RequestErrorResponse.js";export * from "./RequestErrorResponseError.js";export * from "./ResourceName.js";export * from "./ResponseFormat.js";+export * from "./ResponseFormatJsonObject.js";export * from "./ResponseFormatJsonSchema.js";export * from "./ResponseFormatJsonSchemaJsonSchema.js";-export * from "./ResponseFormatOne.js";-export * from "./ResponseFormatZero.js";+export * from "./ResponseFormatText.js";export * from "./RuntimeConfig.js";export * from "./SandboxConfig.js";export * from "./SandboxCreatedEvent.js";diff --git a/packages/sdk/tests/wire/sessions.test.ts b/packages/sdk/tests/wire/sessions.test.tsindex f75e47f03..84a67f95a 100644--- a/packages/sdk/tests/wire/sessions.test.ts+++ b/packages/sdk/tests/wire/sessions.test.ts@@ -101,7 +101,7 @@ describe("SessionsClient", () => {name: "name",properties: { context_length: 1, max_output_tokens: 1 },},- response_format: { type: "text" },+ response_format: { type: "json_object" },skills: [{ description: "description", name: "name", ref: "ref", type: "git", url: "url" }],variables: { key: "value" },},@@ -157,7 +157,7 @@ describe("SessionsClient", () => {},},responseFormat: {- type: "text",+ type: "json_object",},skills: [{@@ -265,7 +265,7 @@ describe("SessionsClient", () => {name: "name",properties: { context_length: 1, max_output_tokens: 1 },},- response_format: { type: "text" },+ response_format: { type: "json_object" },skills: [{ description: "description", name: "name", ref: "ref", type: "git", url: "url" }],variables: { key: "value" },},@@ -309,7 +309,7 @@ describe("SessionsClient", () => {},},responseFormat: {- type: "text",+ type: "json_object",},skills: [{@@ -376,7 +376,7 @@ describe("SessionsClient", () => {name: "name",properties: { context_length: 1, max_output_tokens: 1 },},- response_format: { type: "text" },+ response_format: { type: "json_object" },skills: [{ description: "description", name: "name", ref: "ref", type: "git", url: "url" }],variables: { key: "value" },},@@ -421,7 +421,7 @@ describe("SessionsClient", () => {},},responseFormat: {- type: "text",+ type: "json_object",},skills: [{@@ -1014,4 +1014,98 @@ describe("SessionsClient", () => {return await client.sessions.listTurnEvents("sessionId", "turnId");}).rejects.toThrow(TrueHarnessTypes.NotFoundError);});++ test("subscribe_to_turn (1)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueHarness({ maxRetries: 0, environment: server.baseUrl });++ const rawResponseBody =+ 'event: \ndata: {"created_at":"created_at","id":"id","thread_id":"thread_id","mcp_servers":[{"auth_url":"auth_url","id":"id","name":"name"}],"type":"mcp.auth_required"}\n\n';++ server+ .mockEndpoint()+ .get("/api/v1/sessions/sessionId/turns/turnId/subscribe")+ .respondWith()+ .statusCode(200)+ .sseBody(rawResponseBody)+ .build();++ const response = await client.sessions.subscribeToTurn("sessionId", "turnId");+ const events: unknown[] = [];+ for await (const event of response) {+ events.push(event);+ }+ expect(events).toEqual([+ {+ createdAt: "created_at",+ id: "id",+ threadId: "thread_id",+ mcpServers: [+ {+ authUrl: "auth_url",+ id: "id",+ name: "name",+ },+ ],+ type: "mcp.auth_required",+ },+ ]);+ });++ test("subscribe_to_turn (2)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueHarness({ maxRetries: 0, environment: server.baseUrl });++ const rawResponseBody = { error: { message: "message" } };++ server+ .mockEndpoint()+ .get("/api/v1/sessions/sessionId/turns/turnId/subscribe")+ .respondWith()+ .statusCode(400)+ .jsonBody(rawResponseBody)+ .build();++ await expect(async () => {+ return await client.sessions.subscribeToTurn("sessionId", "turnId");+ }).rejects.toThrow(TrueHarnessTypes.BadRequestError);+ });++ test("subscribe_to_turn (3)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueHarness({ maxRetries: 0, environment: server.baseUrl });++ const rawResponseBody = { error: { message: "message" } };++ server+ .mockEndpoint()+ .get("/api/v1/sessions/sessionId/turns/turnId/subscribe")+ .respondWith()+ .statusCode(404)+ .jsonBody(rawResponseBody)+ .build();++ await expect(async () => {+ return await client.sessions.subscribeToTurn("sessionId", "turnId");+ }).rejects.toThrow(TrueHarnessTypes.NotFoundError);+ });++ test("subscribe_to_turn (4)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueHarness({ maxRetries: 0, environment: server.baseUrl });++ const rawResponseBody = { error: { message: "message" } };++ server+ .mockEndpoint()+ .get("/api/v1/sessions/sessionId/turns/turnId/subscribe")+ .respondWith()+ .statusCode(412)+ .jsonBody(rawResponseBody)+ .build();++ await expect(async () => {+ return await client.sessions.subscribeToTurn("sessionId", "turnId");+ }).rejects.toThrow(TrueHarnessTypes.PreconditionFailedError);+ });});diff --git a/packages/server/.env.example b/packages/server/.env.exampleindex 5e2243d14..75ead08aa 100644--- a/packages/server/.env.example+++ b/packages/server/.env.example@@ -44,6 +44,14 @@ SINGLE_BINARY=true# server container.REDIS_URL=redis://localhost:6379+# Resumable turn stream settings. All are optional.+# Active stream TTL defaults to SERVER_EXECUTION_TIMEOUT_SECONDS + 300.+# TURN_STREAM_TTL_SECONDS=900+# Completed streams remain available for 5 minutes by default.+# TURN_STREAM_POST_COMPLETION_TTL_SECONDS=300+# A subscribe request stays open for 10 minutes by default.+# TURN_SUBSCRIBE_TIMEOUT_MS=600000+# Required. Default API key for the OpenAI-compatible API at models.yaml's# base_url, sent as "Authorization: Bearer <key>" on every model request.# Per-model overrides use MODEL_{NAME}_API_KEY with the same {NAME} rules asdiff --git a/packages/server/jest.eventsub.config.cjs b/packages/server/jest.eventsub.config.cjsnew file mode 100644index 000000000..3bc3ecdad--- /dev/null+++ b/packages/server/jest.eventsub.config.cjs@@ -0,0 +1,25 @@+/** @type {import('jest').Config} */+module.exports = {+ testEnvironment: 'node',+ transform: {+ '^.+\\.(m?js|tsx?)$': [+ '@swc/jest',+ {+ jsc: {+ parser: { syntax: 'typescript', decorators: true, dynamicImport: true },+ target: 'es2022',+ },+ module: { type: 'commonjs' },+ },+ ],+ },+ moduleNameMapper: {+ '^(\\.{1,2}/.*)\\.js$': '$1',+ '^@truefoundry/utils/agent-session/(.*)$': '<rootDir>/../harness/src/agent-session/$1',+ '^@truefoundry/utils/core/(.*)$': '<rootDir>/../harness/src/core/$1',+ },+ testTimeout: 30_000,+ maxWorkers: '50%',+ roots: ['<rootDir>/tests/runtime/event-subscription'],+ testMatch: ['<rootDir>/tests/runtime/event-subscription/**/*.test.ts'],+};diff --git a/packages/server/package.json b/packages/server/package.jsonindex 22d64e114..a42877e5e 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -21,7 +21,8 @@"openapi:write": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' tsx --env-file=.env.test scripts/write-openapi.ts","test": "pnpm run build:gen && NODE_OPTIONS='--conditions=development' node --env-file=.env.test ./node_modules/jest/bin/jest.js --config jest.unit.config.cjs","test:store:postgres": "jest --config jest.store.postgres.config.cjs",- "test:store:sqlite": "jest --config jest.store.sqlite.config.cjs"+ "test:store:sqlite": "jest --config jest.store.sqlite.config.cjs",+ "test:eventsub": "jest --config jest.eventsub.config.cjs"},"dependencies": {"@hono/node-server": "^2.0.11",diff --git a/packages/server/registry-example/models.yaml b/packages/server/registry-example/models.yamlindex 2fd8c33ca..3f9f16b86 100644--- a/packages/server/registry-example/models.yaml+++ b/packages/server/registry-example/models.yaml@@ -38,7 +38,7 @@ models:# --- Direct Anthropic ---- name: claude-sonnet-4-6provider: anthropic- api_key: "${ANTHROPIC_API_KEY}"+ api_key: '${ANTHROPIC_API_KEY}'max_output_tokens: 32768reasoning_efforts:- low@@ -48,12 +48,12 @@ models:# --- Direct OpenAI (Responses API) ---- name: gpt-4oprovider: openai- api_key: "${OPENAI_API_KEY}"+ api_key: '${OPENAI_API_KEY}'max_output_tokens: 16384- name: o4-miniprovider: openai- api_key: "${OPENAI_API_KEY}"+ api_key: '${OPENAI_API_KEY}'max_output_tokens: 32768reasoning_efforts:- low@@ -62,7 +62,7 @@ models:- name: o3provider: openai- api_key: "${OPENAI_API_KEY}"+ api_key: '${OPENAI_API_KEY}'max_output_tokens: 32768reasoning_efforts:- low@@ -72,14 +72,14 @@ models:# --- Direct Google ---- name: gemini-2.5-flashprovider: google-gemini- api_key: "${GOOGLE_GEMINI_API_KEY}"+ api_key: '${GOOGLE_GEMINI_API_KEY}'max_output_tokens: 8192# --- Generic gateway (e.g. LiteLLM / TrueFoundry / any OpenAI-compat proxy) ---- name: claude-sonnet-4-6-gatewaymodel_id: anthropic/claude-sonnet-4-6provider: generic- api_key: "${LLM_GATEWAY_API_KEY}"+ api_key: '${LLM_GATEWAY_API_KEY}'base_url: https://your-gateway.example.com/api/llmmax_output_tokens: 32768reasoning_efforts:diff --git a/packages/server/scripts/write-openapi.ts b/packages/server/scripts/write-openapi.tsindex b67d9c574..7f53a8c95 100644--- a/packages/server/scripts/write-openapi.ts+++ b/packages/server/scripts/write-openapi.ts@@ -5,6 +5,7 @@* spec cannot drift from what the server serves. Nothing listens or dials out:* `.env.test` supplies dummy connection strings and the registry fixtures.*/+import type { TurnStreamingEvent } from '@truefoundry/utils/agent-session';import { InMemorySessionStore, Sessions } from '@truefoundry/utils/agent-session';import { RequestReplyRouter } from '@truefoundry/utils/request-reply';import { mkdirSync, writeFileSync } from 'node:fs';@@ -22,6 +23,7 @@ import { McpStore } from '../src/legacy-registry-store/McpStore';import { ModelStore } from '../src/legacy-registry-store/ModelStore';import { SkillStore } from '../src/legacy-registry-store/SkillStore';import { ActiveTurnRegistry } from '../src/runtime/activeTurns';+import { EventSubscriptionRegistry } from '../src/runtime/event-subscription';function isRecord(value: unknown): value is Record<string, unknown> {return typeof value === 'object' && value !== null;@@ -59,6 +61,7 @@ const app = createServerApp({sessions: new Sessions({ sessionStore }),activeTurns: new ActiveTurnRegistry(),requestReplyRouter: new RequestReplyRouter(),+ eventSubscriptions: new EventSubscriptionRegistry<TurnStreamingEvent>(undefined),logger: winston.createLogger({ silent: true }),});diff --git a/packages/server/src/apis/turns.ts b/packages/server/src/apis/turns.tsindex 9d1597872..25018ae71 100644--- a/packages/server/src/apis/turns.ts+++ b/packages/server/src/apis/turns.ts@@ -2,6 +2,7 @@ import { OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';import type { Sessions, Turn, TurnStreamingEvent } from '@truefoundry/utils/agent-session';import {CancellationReason,+ EventType,SessionStoreConflictError,SessionStoreNotFoundError,TurnResourceResolver,@@ -17,13 +18,22 @@ import {McpConnectionError,VercelAILLM,} from '@truefoundry/utils/core';+import type { Context } from 'hono';+import { HTTPException } from 'hono/http-exception';import { streamSSE } from 'hono/streaming';import type { Logger } from 'winston';import configuration from '../config';import type { McpStore } from '../legacy-registry-store/McpStore';import type { ModelStore } from '../legacy-registry-store/ModelStore';-import { createAndExecuteTurnRoute, getTurnRoute, listTurnEventsRoute, listTurnsRoute } from '../routes/turnRoutes';+import {+ createAndExecuteTurnRoute,+ getTurnRoute,+ listTurnEventsRoute,+ listTurnsRoute,+ subscribeTurnRoute,+} from '../routes/turnRoutes';import type { ActiveTurnRegistry } from '../runtime/activeTurns';+import { StreamGoneError, type EventSubscriptionRegistry } from '../runtime/event-subscription';import { mintPeeredTurnId } from '../runtime/peeringIds';import { TENANT_ID } from './sessions';@@ -43,6 +53,8 @@ export interface TurnsRouterDeps {activeTurns: ActiveTurnRegistry;modelStore: ModelStore;mcpStore: McpStore;+ /** Resumable live turn-event transport: create-turn writes, subscribe polls. */+ eventSubscriptions: EventSubscriptionRegistry<TurnStreamingEvent>;/** Built at boot from SANDBOX_SETTINGS; undefined = sandbox unsupported. */sandboxFactory?: TurnSandboxFactory;logger: Logger;@@ -109,11 +121,7 @@ function deriveSessionTitle(input: TurnInputItem[] | undefined): string | undefireturn trimmed.slice(0, MAX_SESSION_TITLE_LENGTH);}-/**- * SSE payload for one turn event. The `id` field carries the per-stream- * sequence number; the event body itself is not numbered (yield order is- * persist order, so the transport boundary stamps).- */+/** SSE payload: `id` carries the per-stream sequence number; the body is not numbered. */function turnEventSsePayload(event: TurnStreamingEvent, sequenceNumber: number): { id: string; data: string } {return {id: String(sequenceNumber),@@ -121,6 +129,43 @@ function turnEventSsePayload(event: TurnStreamingEvent, sequenceNumber: number):};}+/**+ * turn.created arms the active-run TTL, turn.done shortens it to the+ * post-completion drain window; mid-run events leave the TTL untouched.+ */+function streamTTLSecondsFor(event: TurnStreamingEvent): number | undefined {+ if (event.type === EventType.TURN_CREATED) {+ return configuration.TURN_STREAM_TTL_SECONDS;+ }+ if (event.type === EventType.TURN_DONE) {+ return configuration.TURN_STREAM_POST_COMPLETION_TTL_SECONDS;+ }+ return undefined;+}++/** Redis/in-memory key for one turn's resumable event stream. */+function turnStreamId(tenantId: string, sessionId: string, turnId: string): string {+ return `agent:turn:${tenantId}:${sessionId}:${turnId}:stream`;+}++/**+ * Resume cursor: `Last-Event-ID` header wins over the body value because the+ * header is updated by the SDK on every reconnect to reflect the last delivered+ * event, whereas the body is the original caller-supplied cursor and never+ * changes between reconnect attempts.+ */+function resolveAfterSequenceNumber(c: Context, bodyAfterSequenceNumber?: number): number | undefined {+ const lastEventId = c.req.header('last-event-id');+ if (lastEventId) {+ const sequenceNumber = Number(lastEventId);+ if (!Number.isInteger(sequenceNumber) || sequenceNumber < 0) {+ throw new HTTPException(400, { message: 'Invalid Last-Event-Id header' });+ }+ return sequenceNumber;+ }+ return bodyAfterSequenceNumber;+}+export function createTurnsRouter(deps: TurnsRouterDeps) {const listTurnsHandler: RouteHandler<typeof listTurnsRoute> = async c => {const { sessionId } = c.req.valid('param');@@ -244,7 +289,8 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {});let shouldWriteToSSEStream = true;- let sequenceNumber = -1;+ // Held for the whole turn; the stream's sequence counter dies with it.+ const turnEventStream = deps.eventSubscriptions.get(turnStreamId(TENANT_ID, sessionId, turn.id));return streamSSE(c, async stream => {// On client disconnect stop writing but keep draining, so the turn// completes and its events persist.@@ -256,7 +302,11 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {// persistence). Acceptable for now; reintroduce an eager buffer if clients// stall turns in practice.for await (const event of trackedStream) {- sequenceNumber += 1;+ // Dual-write before SSE so subscribers can resume even after the+ // creating client disconnects; the returned sequence is the SSE id.+ const sequenceNumber = await turnEventStream.put(event, {+ streamTTLSeconds: streamTTLSecondsFor(event),+ });if (!stream.closed && !stream.aborted && shouldWriteToSSEStream) {try {await stream.writeSSE(turnEventSsePayload(event, sequenceNumber));@@ -288,13 +338,80 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {});};+ const subscribeTurnHandler: RouteHandler<typeof subscribeTurnRoute> = async c => {+ const { sessionId, turnId } = c.req.valid('param');+ const query = c.req.valid('query');+ const afterSequenceNumber = resolveAfterSequenceNumber(c, query.after_sequence_number);++ const session = await deps.sessions.get({ tenant_id: TENANT_ID, session_id: sessionId });+ if (!session) {+ return c.json({ error: { message: `Session not found: ${sessionId}` } }, 404);+ }+ const turn = await session.getTurn(turnId);+ if (!turn) {+ return c.json({ error: { message: `Turn not found: ${turnId}` } }, 404);+ }++ const turnEventStream = deps.eventSubscriptions.get(turnStreamId(TENANT_ID, sessionId, turnId));++ // Admission check before SSE headers are sent, so it can still map to HTTP 412.+ try {+ await turnEventStream.assertSubscribable();+ } catch (error) {+ if (error instanceof StreamGoneError) {+ throw new HTTPException(412, { message: error.message, cause: error });+ }+ throw error;+ }++ // One lifecycle controller: server-side timeout, client disconnect, and+ // normal teardown all abort it, which ends poll even while it is parked+ // waiting for events.+ const subscribeAbort = new AbortController();+ const timeoutMs = configuration.TURN_SUBSCRIBE_TIMEOUT_MS;+ const timeoutHandler = setTimeout(() => {+ deps.logger.info('Subscribe turn stream server-side timeout reached, closing stream', {+ sessionId,+ turnId,+ afterSequenceNumber,+ timeoutMs,+ });+ subscribeAbort.abort(new Error('subscribe-timeout'));+ }, timeoutMs);++ return streamSSE(c, async stream => {+ stream.onAbort(() => {+ subscribeAbort.abort(new Error('client-disconnected'));+ });++ const generator = turnEventStream.poll(afterSequenceNumber, { signal: subscribeAbort.signal });+ try {+ for await (const { sequence_number: sequenceNumber, ...event } of generator) {+ await stream.writeSSE(turnEventSsePayload(event, sequenceNumber));+ if (event.type === EventType.TURN_DONE) {+ break;+ }+ }+ } catch (error) {+ if (!subscribeAbort.signal.aborted) {+ deps.logger.error('Unexpected error in turn subscribe SSE loop', extractErrorLogFields(error));+ }+ } finally {+ clearTimeout(timeoutHandler);+ // Poll loops forever by design; aborting releases a parked generator+ // immediately so the return() below settles right away.+ subscribeAbort.abort();+ await generator.return(undefined);+ await stream.close();+ }+ });+ };+const router = new OpenAPIHono();router.openapi(listTurnsRoute, listTurnsHandler);router.openapi(getTurnRoute, getTurnHandler);router.openapi(listTurnEventsRoute, listTurnEventsHandler);router.openapi(createAndExecuteTurnRoute, createAndExecuteTurnHandler);- // subscribeTurnRoute (routes/turnRoutes.ts) is defined but not registered:- // re-subscribing to a running turn needs a live-stream registry that this- // single-process server does not have yet.+ router.openapi(subscribeTurnRoute, subscribeTurnHandler);return router;}diff --git a/packages/server/src/app.ts b/packages/server/src/app.tsindex 0b3effcc8..bc9f65f29 100644--- a/packages/server/src/app.ts+++ b/packages/server/src/app.ts@@ -1,7 +1,7 @@/** The API: resource routers, the OpenAPI document and Swagger UI, all under /api/v1. */import { swaggerUI } from '@hono/swagger-ui';import { OpenAPIHono } from '@hono/zod-openapi';-import type { ISessionStore, Sessions, TurnSandboxFactory } from '@truefoundry/utils/agent-session';+import type { ISessionStore, Sessions, TurnSandboxFactory, TurnStreamingEvent } from '@truefoundry/utils/agent-session';import type { RequestReplyRouter } from '@truefoundry/utils/request-reply';import type { Context } from 'hono';import { HTTPException } from 'hono/http-exception';@@ -28,6 +28,7 @@ import type { McpStore } from './legacy-registry-store/McpStore';import type { ModelStore } from './legacy-registry-store/ModelStore';import type { SkillStore } from './legacy-registry-store/SkillStore';import type { ActiveTurnRegistry } from './runtime/activeTurns';+import type { EventSubscriptionRegistry } from './runtime/event-subscription';const openApiDocConfig = {openapi: '3.1.0',@@ -66,6 +67,8 @@ export interface ServerDeps {redis?: RedisClientType | undefined;/** Request-reply dispatch table served by this replica's executor. */requestReplyRouter: RequestReplyRouter;+ /** Hands out each turn's resumable event stream to the create and subscribe handlers. */+ eventSubscriptions: EventSubscriptionRegistry<TurnStreamingEvent>;logger: Logger;}@@ -115,6 +118,7 @@ export function createServerApp(deps: ServerDeps) {activeTurns: deps.activeTurns,modelStore: deps.modelStore,mcpStore: deps.mcpStore,+ eventSubscriptions: deps.eventSubscriptions,...(deps.sandboxFactory ? { sandboxFactory: deps.sandboxFactory } : {}),logger: deps.logger,}),diff --git a/packages/server/src/config.ts b/packages/server/src/config.tsindex 681b807c5..3ee902419 100644--- a/packages/server/src/config.ts+++ b/packages/server/src/config.ts@@ -219,6 +219,8 @@ const resolveExecutorId = (singleBinary: boolean): string => {export interface ServerConfiguration {/** HTTP port the server listens on. Env: `PORT`. */PORT: number;+ /** Peering identity embedded in the turn ids this process mints; `local` in single-binary mode. */+ EXECUTOR_ID: string;/*** Absolute path to the directory containing the YAML config files* (models.yaml, mcp.yaml, skills.yaml). Relative values are resolved@@ -333,6 +335,8 @@ export interface ServerConfiguration {* Env: `POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS`. Default 60000.*/POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS: number;+ /** Peering URL shared by all replicas; undefined in single-binary mode. Env: `REDIS_URL`. */+ REDIS_URL: string | undefined;/*** Max ms to wait for a peer executor's reply before failing with 424.* Env: `REDIS_REQUEST_REPLY_TIMEOUT_MS`. Default 60000.@@ -353,10 +357,21 @@ export interface ServerConfiguration {* Env: `REDIS_REQUEST_REPLY_POLL_INTERVAL_MS`. Default 500.*/REDIS_REQUEST_REPLY_POLL_INTERVAL_MS: number;- /** Peering URL shared by all replicas; undefined in single-binary mode. Env: `REDIS_URL`. */- REDIS_URL: string | undefined;- /** Peering identity embedded in the turn ids this process mints; `local` in single-binary mode. */- EXECUTOR_ID: string;+ /**+ * TTL for a running turn's resumable event stream.+ * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300.+ */+ TURN_STREAM_TTL_SECONDS: number;+ /**+ * TTL retained after `turn.done` so subscribers can drain remaining events.+ * Env: `TURN_STREAM_POST_COMPLETION_TTL_SECONDS`. Default 300.+ */+ TURN_STREAM_POST_COMPLETION_TTL_SECONDS: number;+ /**+ * Max ms to keep a turn subscription open.+ * Env: `TURN_SUBSCRIBE_TIMEOUT_MS`. Default 600000.+ */+ TURN_SUBSCRIBE_TIMEOUT_MS: number;}// ============================================================================@@ -372,6 +387,11 @@ const postgresPort = parsePositiveInt({raw: requireNonEmptyEnv('POSTGRES_PORT'),defaultValue: 5432,});+const serverExecutionTimeoutSeconds = parsePositiveInt({+ envKey: 'SERVER_EXECUTION_TIMEOUT_SECONDS',+ raw: getEnv('SERVER_EXECUTION_TIMEOUT_SECONDS'),+ defaultValue: 600,+});const singleBinary = parseBoolean({envKey: 'SINGLE_BINARY',@@ -381,6 +401,7 @@ const singleBinary = parseBoolean({const configuration: ServerConfiguration = {PORT: parsePort(getEnv('PORT')),+ EXECUTOR_ID: resolveExecutorId(singleBinary),REGISTRY_DIR: path.resolve(getEnv('REGISTRY_DIR', { defaultValue: 'registry' }) ?? 'registry'),MODEL_CATALOG_PATH: (() => {const override = getEnv('MODEL_CATALOG_PATH');@@ -420,11 +441,7 @@ const configuration: ServerConfiguration = {raw: getEnv('GRACEFUL_TIMEOUT_SECONDS'),defaultValue: 30,}),- SERVER_EXECUTION_TIMEOUT_SECONDS: parsePositiveInt({- envKey: 'SERVER_EXECUTION_TIMEOUT_SECONDS',- raw: getEnv('SERVER_EXECUTION_TIMEOUT_SECONDS'),- defaultValue: 600,- }),+ SERVER_EXECUTION_TIMEOUT_SECONDS: serverExecutionTimeoutSeconds,DATABASE_URL: buildPostgresConnectionString({user: postgresUser,password: postgresPassword,@@ -447,6 +464,7 @@ const configuration: ServerConfiguration = {raw: getEnv('POSTGRES_IDLE_IN_TRANSACTION_SESSION_TIMEOUT_MS'),defaultValue: 60_000,}),+ REDIS_URL: resolveRedisUrl(singleBinary),REDIS_REQUEST_REPLY_TIMEOUT_MS: parsePositiveInt({envKey: 'REDIS_REQUEST_REPLY_TIMEOUT_MS',raw: getEnv('REDIS_REQUEST_REPLY_TIMEOUT_MS'),@@ -467,8 +485,21 @@ const configuration: ServerConfiguration = {raw: getEnv('REDIS_REQUEST_REPLY_POLL_INTERVAL_MS'),defaultValue: 500,}),- REDIS_URL: resolveRedisUrl(singleBinary),- EXECUTOR_ID: resolveExecutorId(singleBinary),+ TURN_STREAM_TTL_SECONDS: parsePositiveInt({+ envKey: 'TURN_STREAM_TTL_SECONDS',+ raw: getEnv('TURN_STREAM_TTL_SECONDS'),+ defaultValue: serverExecutionTimeoutSeconds + 300,+ }),+ TURN_STREAM_POST_COMPLETION_TTL_SECONDS: parsePositiveInt({+ envKey: 'TURN_STREAM_POST_COMPLETION_TTL_SECONDS',+ raw: getEnv('TURN_STREAM_POST_COMPLETION_TTL_SECONDS'),+ defaultValue: 300,+ }),+ TURN_SUBSCRIBE_TIMEOUT_MS: parsePositiveInt({+ envKey: 'TURN_SUBSCRIBE_TIMEOUT_MS',+ raw: getEnv('TURN_SUBSCRIBE_TIMEOUT_MS'),+ defaultValue: 600_000,+ }),} as const;export default configuration;diff --git a/packages/server/src/main.ts b/packages/server/src/main.tsindex 46a485eef..61298f7c3 100644--- a/packages/server/src/main.ts+++ b/packages/server/src/main.ts@@ -5,6 +5,7 @@* SQLite migrations are packaged under dist/ but are not run at startup.*/import { serve } from '@hono/node-server';+import type { TurnStreamingEvent } from '@truefoundry/utils/agent-session';import type { RedisClientType } from 'redis';import winston from 'winston';@@ -24,6 +25,7 @@ try {{ connectRedis },{ RequestReplyExecutor, RequestReplyRouter },{ PostgresSessionStore },+ { EventSubscriptionRegistry },{ ModelCatalog },{ PostgresModelProviderStore },{ McpCatalog },@@ -45,6 +47,7 @@ try {import('./runtime/redis'),import('@truefoundry/utils/request-reply'),import('./db/postgres/session-store/PostgresSessionStore'),+ import('./runtime/event-subscription'),import('./catalog/ModelCatalog'),import('./db/postgres/model-provider-store/PostgresModelProviderStore'),import('./catalog/McpCatalog'),@@ -82,6 +85,7 @@ try {redis = await connectRedis({ url: configuration.REDIS_URL, logger });}const requestReplyRouter = new RequestReplyRouter();+ const eventSubscriptions = new EventSubscriptionRegistry<TurnStreamingEvent>(redis);const app = createServerApp({modelStore: ModelStore.load(),@@ -99,6 +103,7 @@ try {...(sandboxFactory ? { sandboxFactory } : {}),redis,requestReplyRouter,+ eventSubscriptions,logger,});diff --git a/packages/server/src/routes/turnRoutes.ts b/packages/server/src/routes/turnRoutes.tsindex 5202a728a..de86bb919 100644--- a/packages/server/src/routes/turnRoutes.ts+++ b/packages/server/src/routes/turnRoutes.ts@@ -13,7 +13,7 @@ import {ListTurnEventsResponseSchema,ListTurnsRequestQuerySchema,ListTurnsResponseSchema,- SubscribeTurnRequestSchema,+ SubscribeTurnQuerySchema,} from '../schemas/turn';import { TOKEN_PAGINATION } from './fernExtensions';import { SessionIdParamsSchema } from './sessionRoutes';@@ -114,7 +114,6 @@ export const createAndExecuteTurnRoute = createRoute({Use \`previous_turn_id\` to chain to the session's last turn (defaults to \`auto\`).`,'x-fern-sdk-group-name': ['sessions'],'x-fern-sdk-method-name': 'create_turn',- // Not resumable: subscribeTurnRoute, which would reattach, is not registered.'x-fern-streaming': { format: 'sse', resumable: false },request: {params: SessionIdParamsSchema,@@ -148,18 +147,18 @@ Use \`previous_turn_id\` to chain to the session's last turn (defaults to \`auto});export const subscribeTurnRoute = createRoute({- method: 'post',+ method: 'get',path: '/{sessionId}/turns/{turnId}/subscribe',tags: [SESSIONS_TAG],summary: 'Subscribe to a running turn',description:'Subscribe to the live SSE stream for a turn. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).',+ 'x-fern-sdk-group-name': ['sessions'],+ 'x-fern-sdk-method-name': 'subscribe_to_turn',+ 'x-fern-streaming': { format: 'sse', resumable: true },request: {params: TurnIdParamsSchema,- body: {- content: { 'application/json': { schema: SubscribeTurnRequestSchema } },- required: true,- },+ query: SubscribeTurnQuerySchema,},responses: {200: {diff --git a/packages/server/src/runtime/event-subscription/inMemory.ts b/packages/server/src/runtime/event-subscription/inMemory.tsnew file mode 100644index 000000000..c94c31dcc--- /dev/null+++ b/packages/server/src/runtime/event-subscription/inMemory.ts@@ -0,0 +1,165 @@+/**+ * Single-process backend mirroring RedisEventSubscription semantics (dense+ * sequences, whole-stream TTL, poll-forever generators, same errors).+ * Resume only works within one replica.+ */+import { EventEmitter, once } from 'node:events';+import {+ StreamGoneError,+ SUBSCRIBE_STREAM_THRESHOLD_MS,+ type EventSubscription,+ type EventSubscriptionPollOptions,+ type EventSubscriptionPutOptions,+ type SequencedEvent,+} from '.';++interface InMemoryStream<T extends object> {+ /** Dense log: the event at index i has sequence_number i. */+ events: SequencedEvent<T>[];+ /** Undefined = no TTL set yet (mirrors a Redis key without EXPIRE). */+ expiresAtMs?: number | undefined;+ expiryTimer?: NodeJS.Timeout | undefined;+}++/**+ * Owns the stream logs and their TTLs; the expiry timer is the in-process+ * equivalent of Redis key eviction.+ */+export class InMemoryEventStreamStore<T extends object> {+ private readonly streams = new Map<string, InMemoryStream<T>>();+ /** Rings per stream id on append and expiry so parked pollers wake instantly. */+ private readonly changes = new EventEmitter();++ constructor() {+ // One listener per parked poller; unlimited concurrent subscribers.+ this.changes.setMaxListeners(0);+ }++ append(streamId: string, event: T, streamTTLSeconds?: number): number {+ const stream = this.getLiveStream(streamId) ?? { events: [] };+ this.streams.set(streamId, stream);++ const sequenceNumber = stream.events.length;+ // Deep-copy so the log is isolated from caller mutations (mirrors JSON round-trip in Redis).+ stream.events.push({ ...structuredClone(event), sequence_number: sequenceNumber });++ if (streamTTLSeconds && streamTTLSeconds > 0) {+ stream.expiresAtMs = Date.now() + streamTTLSeconds * 1_000;+ this.scheduleExpiry(streamId, stream);+ }+ this.changes.emit(streamId);+ return sequenceNumber;+ }++ /** Returns the stream if it exists and has not passed its TTL; drops it lazily otherwise. */+ getLiveStream(streamId: string): InMemoryStream<T> | undefined {+ const stream = this.streams.get(streamId);+ if (!stream) {+ return undefined;+ }+ if (stream.expiresAtMs !== undefined && stream.expiresAtMs <= Date.now()) {+ this.dropStream(streamId, stream);+ return undefined;+ }+ return stream;+ }++ /**+ * Resolves on the next append/expiry of the stream; rejects when the signal+ * aborts (which also detaches the listener, so abandoned waits do not leak).+ */+ async waitForChange(streamId: string, signal?: AbortSignal): Promise<void> {+ await once(this.changes, streamId, { signal });+ }++ /**+ * Evicts a stream: clears its timer, removes it from the map, and wakes any+ * parked pollers so they observe StreamGoneError promptly. Shared by the+ * lazy-expiry path in getLiveStream and the scheduled expiry timer.+ */+ private dropStream(streamId: string, stream: InMemoryStream<T>): void {+ if (stream.expiryTimer) {+ clearTimeout(stream.expiryTimer);+ stream.expiryTimer = undefined;+ }+ if (this.streams.get(streamId) !== stream) {+ return;+ }+ this.streams.delete(streamId);+ this.changes.emit(streamId);+ }++ private scheduleExpiry(streamId: string, stream: InMemoryStream<T>): void {+ if (stream.expiryTimer) {+ clearTimeout(stream.expiryTimer);+ }+ if (stream.expiresAtMs === undefined) {+ return;+ }+ stream.expiryTimer = setTimeout(+ () => {+ this.dropStream(streamId, stream);+ },+ Math.max(0, stream.expiresAtMs - Date.now()),+ );+ stream.expiryTimer.unref();+ }+}++/** Stream-scoped view over the shared store; implements the transport contract. */+export class InMemoryEventSubscription<T extends object> implements EventSubscription<T> {+ constructor(+ private readonly store: InMemoryEventStreamStore<T>,+ private readonly streamId: string,+ ) {}++ put(event: T, options?: EventSubscriptionPutOptions): Promise<number> {+ return Promise.resolve(this.store.append(this.streamId, event, options?.streamTTLSeconds));+ }++ assertSubscribable(): Promise<void> {+ const stream = this.store.getLiveStream(this.streamId);+ if (!stream) {+ throw new StreamGoneError(this.streamId);+ }+ // Expiring within the threshold is treated as already gone, mirroring the Redis backend.+ if (stream.expiresAtMs !== undefined && stream.expiresAtMs - Date.now() < SUBSCRIBE_STREAM_THRESHOLD_MS) {+ throw new StreamGoneError(this.streamId);+ }+ return Promise.resolve();+ }++ async *poll(+ afterSequenceNumber?: number,+ options?: EventSubscriptionPollOptions,+ ): AsyncGenerator<SequencedEvent<T>, void, unknown> {+ const signal = options?.signal;+ let cursor = afterSequenceNumber === undefined ? 0 : afterSequenceNumber + 1;+ for (;;) {+ if (signal?.aborted) {+ return;+ }+ const live = this.store.getLiveStream(this.streamId);+ if (!live) {+ throw new StreamGoneError(this.streamId);+ }+ const batch = live.events.slice(cursor);+ if (batch.length === 0) {+ try {+ await this.store.waitForChange(this.streamId, signal);+ } catch (error) {+ if (signal?.aborted) {+ return;+ }+ throw error;+ }+ continue;+ }+ cursor += batch.length;+ // Deep-copy each yielded event so consumers cannot mutate the stored log.+ for (const stored of batch) {+ yield structuredClone(stored);+ }+ }+ }+}diff --git a/packages/server/src/runtime/event-subscription/index.ts b/packages/server/src/runtime/event-subscription/index.tsnew file mode 100644index 000000000..9b0a3e161--- /dev/null+++ b/packages/server/src/runtime/event-subscription/index.ts@@ -0,0 +1,69 @@+import type { RedisClientType } from 'redis';+import { InMemoryEventStreamStore, InMemoryEventSubscription } from './inMemory';+import { RedisEventSubscription } from './redis';++export interface EventSubscriptionPutOptions {+ /** Sets the lifetime of the whole stream after this append. */+ streamTTLSeconds?: number | undefined;+}++export type SequencedEvent<T extends object> = T & { sequence_number: number };++export interface EventSubscriptionPollOptions {+ /** Ends the generator promptly on abort, releasing any parked idle wait. */+ signal?: AbortSignal | undefined;+}++/**+ * One turn's resumable event stream, obtained from {@link EventSubscriptionRegistry.get}.+ * Per-stream state (e.g. the sequence counter) lives on the instance and is freed with it.+ */+export interface EventSubscription<T extends object> {+ /** Appends an event, assigns its sequence number, and returns that number. */+ put(event: T, options?: EventSubscriptionPutOptions): Promise<number>;++ /**+ * Subscription admission check, run before SSE headers are sent: rejects with+ * {@link StreamGoneError} when the stream is missing or expires within+ * {@link SUBSCRIBE_STREAM_THRESHOLD_MS}.+ */+ assertSubscribable(): Promise<void>;++ /** Yields events strictly after the supplied sequence, or from the start when omitted. */+ poll(+ afterSequenceNumber?: number,+ options?: EventSubscriptionPollOptions,+ ): AsyncGenerator<SequencedEvent<T>, void, unknown>;+}++/**+ * Hands out stream-scoped {@link EventSubscription}s: Redis-backed when a+ * client is supplied, otherwise views over one shared in-process store.+ */+export class EventSubscriptionRegistry<T extends object> {+ /** One store for the whole process so producers and subscribers share streams. */+ private readonly memoryStore = new InMemoryEventStreamStore<T>();++ constructor(private readonly redis: RedisClientType | undefined) {}++ get(streamId: string): EventSubscription<T> {+ if (this.redis) {+ return new RedisEventSubscription<T>(this.redis, streamId);+ }+ return new InMemoryEventSubscription(this.memoryStore, streamId);+ }+}++/** Reject new subscriptions when the stream expires within this window. */+export const SUBSCRIBE_STREAM_THRESHOLD_MS = 60 * 1_000;++/** The stream expired or was never created (map to HTTP 412). */+export class StreamGoneError extends Error {+ readonly code = 'STREAM_GONE' as const;++ constructor(readonly streamId: string) {+ super(`Cannot read from stream, stream does not exist anymore: ${streamId}`);+ this.name = 'StreamGoneError';+ Object.setPrototypeOf(this, new.target.prototype);+ }+}diff --git a/packages/server/src/runtime/event-subscription/redis.ts b/packages/server/src/runtime/event-subscription/redis.tsnew file mode 100644index 000000000..bd2b88bc6--- /dev/null+++ b/packages/server/src/runtime/event-subscription/redis.ts@@ -0,0 +1,114 @@+import { setTimeout as sleep } from 'node:timers/promises';+import type { RedisClientType } from 'redis';+import {+ StreamGoneError,+ SUBSCRIBE_STREAM_THRESHOLD_MS,+ type EventSubscription,+ type EventSubscriptionPollOptions,+ type EventSubscriptionPutOptions,+ type SequencedEvent,+} from '.';++const SUBSCRIBE_STREAM_POLL_ITEMS_COUNT = 100;+/** Delay between XREAD polls while a stream has no new events (a blocking XREAD would monopolize the shared connection). */+const SUBSCRIBE_STREAM_POLL_SLEEP_INTERVAL_MS = 1_000;++function sequenceNumberFromEntryId(streamId: string, entryId: string): number {+ const separator = entryId.indexOf('-');+ const raw = separator === -1 ? entryId : entryId.slice(0, separator);+ const sequenceNumber = Number(raw);+ if (!Number.isSafeInteger(sequenceNumber) || sequenceNumber < 0) {+ throw new Error(`Corrupt stream entry ${entryId} on ${streamId}: invalid sequence number`);+ }+ return sequenceNumber;+}++/**+ * One Redis Stream with locally minted sequence numbers. Assumes a single+ * producer per stream; the counter dies with the instance, the data via key TTL.+ */+export class RedisEventSubscription<T extends object> implements EventSubscription<T> {+ private nextSequenceNumber = 0;++ constructor(+ private readonly redis: RedisClientType,+ private readonly streamId: string,+ ) {}++ async put(event: T, options?: EventSubscriptionPutOptions): Promise<number> {+ const sequenceNumber = this.nextSequenceNumber;+ this.nextSequenceNumber += 1;++ const sequencedEvent: SequencedEvent<T> = { ...event, sequence_number: sequenceNumber };+ const multi = this.redis.multi().xAdd(this.streamId, `${String(sequenceNumber)}-1`, {+ data: JSON.stringify(sequencedEvent),+ });+ if (options?.streamTTLSeconds && options.streamTTLSeconds > 0) {+ multi.expire(this.streamId, options.streamTTLSeconds);+ }+ await multi.exec();+ return sequenceNumber;+ }++ async assertSubscribable(): Promise<void> {+ const expiresAtMs = await this.redis.pExpireTime(this.streamId);+ if (expiresAtMs === -2) {+ throw new StreamGoneError(this.streamId);+ }+ // Expiring within the threshold is treated as already gone: too little+ // time remains for a subscription to be useful.+ if (expiresAtMs >= 0 && expiresAtMs - Date.now() < SUBSCRIBE_STREAM_THRESHOLD_MS) {+ throw new StreamGoneError(this.streamId);+ }+ }++ async *poll(+ afterSequenceNumber?: number,+ options?: EventSubscriptionPollOptions,+ ): AsyncGenerator<SequencedEvent<T>, void, unknown> {+ const signal = options?.signal;+ let cursor = afterSequenceNumber === undefined ? '0-0' : `${String(afterSequenceNumber + 1)}-0`;+ for (;;) {+ if (signal?.aborted) {+ return;+ }+ if ((await this.redis.exists(this.streamId)) === 0) {+ throw new StreamGoneError(this.streamId);+ }+ const reply = await this.redis.xRead([{ key: this.streamId, id: cursor }], {+ COUNT: SUBSCRIBE_STREAM_POLL_ITEMS_COUNT,+ });+ const messages = reply?.[0]?.messages ?? [];+ if (messages.length === 0) {+ try {+ await sleep(SUBSCRIBE_STREAM_POLL_SLEEP_INTERVAL_MS, undefined, { signal });+ } catch (error) {+ if (signal?.aborted) {+ return;+ }+ throw error;+ }+ continue;+ }++ for (const { id, message } of messages) {+ cursor = id;+ const data = message['data'];+ if (data === undefined) {+ throw new Error(`Corrupt stream entry ${id} on ${this.streamId}: missing data field`);+ }++ let event: T;+ try {+ // Own writes read back; trusted without validation, as in the gateway.+ event = JSON.parse(data) as T;+ } catch (error) {+ throw new Error(`Corrupt stream entry ${id} on ${this.streamId}: data is not valid JSON`, {+ cause: error,+ });+ }+ yield { ...event, sequence_number: sequenceNumberFromEntryId(this.streamId, id) };+ }+ }+ }+}diff --git a/packages/server/src/schemas/turn.ts b/packages/server/src/schemas/turn.tsindex 05eaaeec8..53c8a9ca2 100644--- a/packages/server/src/schemas/turn.ts+++ b/packages/server/src/schemas/turn.ts@@ -5,11 +5,11 @@ import { SessionEventSchema, TokenPaginationSchema, TurnSchema } from '@truefounexport { CreateTurnRequestSchema, TurnSchema } from '@truefoundry/utils/agent-session';export type { Turn } from '@truefoundry/utils/agent-session';-export const SubscribeTurnRequestSchema = z+export const SubscribeTurnQuerySchema = z.object({after_sequence_number: z.number().int().nonnegative().optional(),})- .openapi('SubscribeTurnRequest');+ .openapi('SubscribeTurnQuery');export const CancelSessionRequestSchema = z.object({}).openapi('CancelSessionRequest');export const CancelSessionResponseSchema = z.object({}).openapi('CancelSessionResponse');diff --git a/packages/server/tests/runtime/event-subscription/contractSuite.ts b/packages/server/tests/runtime/event-subscription/contractSuite.tsnew file mode 100644index 000000000..9bb5e82e0--- /dev/null+++ b/packages/server/tests/runtime/event-subscription/contractSuite.ts@@ -0,0 +1,110 @@+import type { EventSubscriptionRegistry, SequencedEvent } from '../../../src/runtime/event-subscription';++/** Payload shape used by the suite; distinct per event so round-trips are provable. */+export interface TestEvent {+ type: string;+ payload: { index: number; text: string };+}++/** Long enough to outlive any test run; also self-cleans Redis keys afterwards. */+const STREAM_TTL_SECONDS = 300;++let streamCounter = 0;+function nextStreamId(): string {+ streamCounter += 1;+ return `eventsub-contract:${String(process.pid)}:${String(Date.now())}:${String(streamCounter)}`;+}++function makeEvent(index: number): TestEvent {+ return { type: 'test.event', payload: { index, text: `event-${String(index)}` } };+}++/** Drains `count` events from a fresh poll, then aborts it (poll loops forever by design). */+async function collect(+ registry: EventSubscriptionRegistry<TestEvent>,+ streamId: string,+ count: number,+ afterSequenceNumber?: number,+): Promise<SequencedEvent<TestEvent>[]> {+ const abort = new AbortController();+ const generator = registry.get(streamId).poll(afterSequenceNumber, { signal: abort.signal });+ const received: SequencedEvent<TestEvent>[] = [];+ try {+ for await (const event of generator) {+ received.push(event);+ if (received.length >= count) {+ break;+ }+ }+ } finally {+ abort.abort();+ await generator.return(undefined);+ }+ return received;+}++/** EventSubscription contract suite — factory-injected so both backends run it. */+export function runEventSubscriptionContractSuite(createRegistry: () => EventSubscriptionRegistry<TestEvent>) {+ it('put assigns dense sequence numbers starting at 0', async () => {+ const registry = createRegistry();+ const streamId = nextStreamId();+ const producer = registry.get(streamId);++ const sequenceNumbers = [];+ for (let i = 0; i < 3; i += 1) {+ sequenceNumbers.push(await producer.put(makeEvent(i), { streamTTLSeconds: STREAM_TTL_SECONDS }));+ }+ expect(sequenceNumbers).toEqual([0, 1, 2]);+ });++ it('poll from the start yields every event sent, in order, with identical payloads', async () => {+ const registry = createRegistry();+ const streamId = nextStreamId();+ const producer = registry.get(streamId);++ const sent = [makeEvent(0), makeEvent(1), makeEvent(2), makeEvent(3), makeEvent(4)];+ for (const event of sent) {+ await producer.put(event, { streamTTLSeconds: STREAM_TTL_SECONDS });+ }++ const received = await collect(registry, streamId, sent.length);+ expect(received).toEqual(sent.map((event, index) => ({ ...event, sequence_number: index })));+ });++ it('poll from a mid-stream cursor yields only events strictly after it', async () => {+ const registry = createRegistry();+ const streamId = nextStreamId();+ const producer = registry.get(streamId);++ const sent = [makeEvent(0), makeEvent(1), makeEvent(2), makeEvent(3), makeEvent(4)];+ for (const event of sent) {+ await producer.put(event, { streamTTLSeconds: STREAM_TTL_SECONDS });+ }++ const received = await collect(registry, streamId, 3, 1);+ expect(received).toEqual([+ { ...sent[2], sequence_number: 2 },+ { ...sent[3], sequence_number: 3 },+ { ...sent[4], sequence_number: 4 },+ ]);+ });++ it('poll parked at the tip receives events put after it subscribed', async () => {+ const registry = createRegistry();+ const streamId = nextStreamId();+ const producer = registry.get(streamId);++ await producer.put(makeEvent(0), { streamTTLSeconds: STREAM_TTL_SECONDS });++ // Cursor at the tip: nothing to replay, so the poller parks for live events.+ const pending = collect(registry, streamId, 2, 0);+ await producer.put(makeEvent(1));+ await producer.put(makeEvent(2));++ const received = await pending;+ expect(received).toEqual([+ { ...makeEvent(1), sequence_number: 1 },+ { ...makeEvent(2), sequence_number: 2 },+ ]);+ });+}diff --git a/packages/server/tests/runtime/event-subscription/inMemory.contract.test.ts b/packages/server/tests/runtime/event-subscription/inMemory.contract.test.tsnew file mode 100644index 000000000..df315befd--- /dev/null+++ b/packages/server/tests/runtime/event-subscription/inMemory.contract.test.ts@@ -0,0 +1,6 @@+import { EventSubscriptionRegistry } from '../../../src/runtime/event-subscription';+import { runEventSubscriptionContractSuite, type TestEvent } from './contractSuite';++describe('InMemoryEventSubscription (EventSubscription contract)', () => {+ runEventSubscriptionContractSuite(() => new EventSubscriptionRegistry<TestEvent>(undefined));+});diff --git a/packages/server/tests/runtime/event-subscription/redis.contract.test.ts b/packages/server/tests/runtime/event-subscription/redis.contract.test.tsnew file mode 100644index 000000000..43b246d63--- /dev/null+++ b/packages/server/tests/runtime/event-subscription/redis.contract.test.ts@@ -0,0 +1,26 @@+import { createClient, type RedisClientType } from 'redis';+import { EventSubscriptionRegistry } from '../../../src/runtime/event-subscription';+import { runEventSubscriptionContractSuite, type TestEvent } from './contractSuite';++const REDIS_URL_ENV = 'REDIS_EVENTSUB_TESTS_URL';++const redisUrl = process.env[REDIS_URL_ENV];+const describeRedis = redisUrl !== undefined && redisUrl !== '' ? describe : describe.skip;++describeRedis('RedisEventSubscription (EventSubscription contract)', () => {+ let client: RedisClientType;++ beforeAll(async () => {+ if (redisUrl === undefined) {+ throw new Error(`${REDIS_URL_ENV} must be set when this suite runs`);+ }+ client = createClient({ url: redisUrl });+ await client.connect();+ });++ afterAll(async () => {+ await client.close();+ });++ runEventSubscriptionContractSuite(() => new EventSubscriptionRegistry<TestEvent>(client));+});diff --git a/packages/server/tests/runtime/tsconfig.json b/packages/server/tests/runtime/tsconfig.jsonnew file mode 100644index 000000000..751b6ef89--- /dev/null+++ b/packages/server/tests/runtime/tsconfig.json@@ -0,0 +1,4 @@+{+ "extends": "../../tsconfig.json",+ "include": ["**/*"]+}diff --git a/packages/server/tests/unit/apis/deletedSessionCrud.test.ts b/packages/server/tests/unit/apis/deletedSessionCrud.test.tsindex 7894d2a35..94996a603 100644--- a/packages/server/tests/unit/apis/deletedSessionCrud.test.ts+++ b/packages/server/tests/unit/apis/deletedSessionCrud.test.ts@@ -8,6 +8,7 @@ import { createTurnsRouter } from '../../../src/apis/turns';import { McpStore } from '../../../src/legacy-registry-store/McpStore';import { ModelStore } from '../../../src/legacy-registry-store/ModelStore';import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';+import { EventSubscriptionRegistry } from '../../../src/runtime/event-subscription/index.js';import { ListSessionsResponseSchema } from '../../../src/schemas/session';describe('public CRUD after session deletion', () => {@@ -39,6 +40,7 @@ describe('public CRUD after session deletion', () => {activeTurns,modelStore,mcpStore,+ eventSubscriptions: new EventSubscriptionRegistry(undefined),logger: createLogger({ silent: true }),}),);diff --git a/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts b/packages/server/tests/unit/apis/turnStreamAfterDelete.test.tsindex a1e56c7f5..bf8ae2e0e 100644--- a/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts+++ b/packages/server/tests/unit/apis/turnStreamAfterDelete.test.ts@@ -6,6 +6,7 @@ import { createTurnsRouter } from '../../../src/apis/turns';import { McpStore } from '../../../src/legacy-registry-store/McpStore';import { ModelStore } from '../../../src/legacy-registry-store/ModelStore';import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';+import { EventSubscriptionRegistry } from '../../../src/runtime/event-subscription/index.js';describe('turn SSE after session deletion', () => {it('warns when the stream ends because the session/turn was removed', async () => {@@ -38,6 +39,7 @@ describe('turn SSE after session deletion', () => {activeTurns: new ActiveTurnRegistry(),modelStore: new ModelStore([]),mcpStore: new McpStore([]),+ eventSubscriptions: new EventSubscriptionRegistry(undefined),logger,}),);