Skip to content

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.md
index 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.json
index 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.yml
index 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.0
output:
location: local-file-system
path: ../packages/sdk
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index 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.ts
index 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.ts
index 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 = z
export 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.md
index 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&lt;TrueHarness.TurnStreamingEvent&gt;</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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
similarity index 67%
rename from packages/sdk/src/api/types/ResponseFormatOne.ts
rename to packages/sdk/src/api/types/ResponseFormatJsonObject.ts
index 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.ts
similarity index 69%
rename from packages/sdk/src/api/types/ResponseFormatZero.ts
rename to packages/sdk/src/api/types/ResponseFormatText.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
similarity index 64%
rename from packages/sdk/src/serialization/types/ResponseFormatOne.ts
rename to packages/sdk/src/serialization/types/ResponseFormatJsonObject.ts
index 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.ts
similarity index 66%
rename from packages/sdk/src/serialization/types/ResponseFormatZero.ts
rename to packages/sdk/src/serialization/types/ResponseFormatText.ts
index 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.ts
index 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.TurnStat
core.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.ts
index 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.ts
index 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.example
index 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 as
diff --git a/packages/server/jest.eventsub.config.cjs b/packages/server/jest.eventsub.config.cjs
new file mode 100644
index 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.json
index 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.yaml
index 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-6
provider: anthropic
- api_key: "${ANTHROPIC_API_KEY}"
+ api_key: '${ANTHROPIC_API_KEY}'
max_output_tokens: 32768
reasoning_efforts:
- low
@@ -48,12 +48,12 @@ models:
# --- Direct OpenAI (Responses API) ---
- name: gpt-4o
provider: openai
- api_key: "${OPENAI_API_KEY}"
+ api_key: '${OPENAI_API_KEY}'
max_output_tokens: 16384
- name: o4-mini
provider: openai
- api_key: "${OPENAI_API_KEY}"
+ api_key: '${OPENAI_API_KEY}'
max_output_tokens: 32768
reasoning_efforts:
- low
@@ -62,7 +62,7 @@ models:
- name: o3
provider: openai
- api_key: "${OPENAI_API_KEY}"
+ api_key: '${OPENAI_API_KEY}'
max_output_tokens: 32768
reasoning_efforts:
- low
@@ -72,14 +72,14 @@ models:
# --- Direct Google ---
- name: gemini-2.5-flash
provider: 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-gateway
model_id: anthropic/claude-sonnet-4-6
provider: generic
- api_key: "${LLM_GATEWAY_API_KEY}"
+ api_key: '${LLM_GATEWAY_API_KEY}'
base_url: https://your-gateway.example.com/api/llm
max_output_tokens: 32768
reasoning_efforts:
diff --git a/packages/server/scripts/write-openapi.ts b/packages/server/scripts/write-openapi.ts
index 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.ts
index 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 | undefi
return 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 '@truefoun
export { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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,
}),
);