Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Add non-streaming create-turn that returns a running turn.

debajyoti-truefoundrybf81d3d493c1
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index 6a29758fc..519b463cb 100644
--- a/fern/openapi/openapi.json
+++ b/fern/openapi/openapi.json
@@ -729,6 +729,11 @@
},
"previous_turn_id": {
"$ref": "#/components/schemas/PreviousTurnIdInput"
+ },
+ "stream": {
+ "default": true,
+ "description": "When true (default), stream turn events as SSE. When false, return the running turn immediately.",
+ "type": "boolean"
}
},
"type": "object"
@@ -4687,7 +4692,7 @@
"x-fern-sdk-method-name": "list_turns"
},
"post": {
- "description": "Create a turn within a session and stream its execution as Server-Sent Events.\nUse `previous_turn_id` to chain to the session's last turn (defaults to `auto`).",
+ "description": "Create a turn within a session and execute it.\nWhen `stream` is true (default), respond with a Server-Sent Events stream of turn events.\nWhen `stream` is false, return the turn immediately with `state.status: \"running\"` while execution continues in the background; use get turn or subscribe to observe completion.\nUse `previous_turn_id` to chain to the session's last turn (defaults to `auto`).",
"parameters": [
{
"description": "Session identifier.",
@@ -4715,13 +4720,18 @@
"responses": {
"200": {
"content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/GetTurnResponse"
+ }
+ },
"text/event-stream": {
"schema": {
"$ref": "#/components/schemas/TurnStreamingEvent"
}
}
},
- "description": "Server-Sent Events stream of turn events."
+ "description": "When stream is false: the running turn. When stream is true: Server-Sent Events stream of turn events."
},
"400": {
"content": {
@@ -4774,7 +4784,14 @@
"x-fern-sdk-method-name": "create_turn",
"x-fern-streaming": {
"format": "sse",
- "resumable": false
+ "response": {
+ "$ref": "#/components/schemas/GetTurnResponse"
+ },
+ "response-stream": {
+ "$ref": "#/components/schemas/TurnStreamingEvent"
+ },
+ "resumable": false,
+ "stream-condition": "$request.stream"
}
}
},
diff --git a/packages/frontend/src/harnessServer.ts b/packages/frontend/src/harnessServer.ts
index 0dbde8cc4..58d88fc2a 100644
--- a/packages/frontend/src/harnessServer.ts
+++ b/packages/frontend/src/harnessServer.ts
@@ -221,7 +221,7 @@ export function createHarnessChatServer(options: CreateHarnessServerOptions = {}
input?: TurnInputItem[];
previousTurnId?: string;
}) {
- const stream = await client.sessions.createTurn(sessionId, {
+ const stream = await client.sessions.createTurnStream(sessionId, {
...(input === undefined ? {} : { input: toHarnessInput(input) }),
...(previousTurnId === undefined ? {} : { previousTurnId: toHarnessPreviousTurnId(previousTurnId) }),
});
diff --git a/packages/frontend/tests/harnessServer.test.ts b/packages/frontend/tests/harnessServer.test.ts
index 68fe444c4..98af58d0c 100644
--- a/packages/frontend/tests/harnessServer.test.ts
+++ b/packages/frontend/tests/harnessServer.test.ts
@@ -116,8 +116,9 @@ describe('createHarnessChatServer', () => {
}
const sent = turnRequests.at(-1);
- assert.ok(sent !== null && typeof sent === 'object' && 'previous_turn_id' in sent);
+ assert.ok(sent !== null && typeof sent === 'object' && 'previous_turn_id' in sent && 'stream' in sent);
assert.equal(sent.previous_turn_id, null);
+ assert.equal(sent.stream, true);
assert.deepEqual(events, [
{
diff --git a/packages/harness/src/agent-session/schemas/turn.ts b/packages/harness/src/agent-session/schemas/turn.ts
index 269a5a1e7..6e8d81c20 100644
--- a/packages/harness/src/agent-session/schemas/turn.ts
+++ b/packages/harness/src/agent-session/schemas/turn.ts
@@ -112,6 +112,11 @@ export const CreateTurnRequestSchema = z
.default('auto')
.describe(`Defaults to 'auto' (chain to session last turn). Use 'null' for the session's first turn.`)
.openapi('PreviousTurnIdInput'),
+ stream: z
+ .boolean()
+ .optional()
+ .default(true)
+ .describe('When true (default), stream turn events as SSE. When false, return the running turn immediately.'),
})
.superRefine((data, ctx) => {
if (!data.input) return;
diff --git a/packages/sdk/.fern/metadata.json b/packages/sdk/.fern/metadata.json
index 1d15a783d..d59b0c8b3 100644
--- a/packages/sdk/.fern/metadata.json
+++ b/packages/sdk/.fern/metadata.json
@@ -29,8 +29,7 @@
},
"originGitCommit": "7c5244e21d9e9590677f0862bc3d1cc0dd7a1bbc",
"originGitCommitIsDirty": true,
- "invokedBy": "ci",
+ "invokedBy": "manual",
"requestedVersion": "0.0.0",
- "ciProvider": "github",
"sdkVersion": "0.0.0"
}
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 510d218fe..33bd092b9 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -48,7 +48,7 @@ Instantiate and use the client with the following:
import { TrueForge } from "trueforge";
const client = new TrueForge({ baseUrl: "YOUR_BASE_URL" });
-const response = await client.sessions.createTurn("session_id");
+const response = await client.sessions.createTurnStream("session_id", {});
for await (const item of response) {
console.log(item);
}
@@ -76,7 +76,7 @@ will be thrown.
import { TrueForgeError } from "trueforge";
try {
- await client.sessions.createTurn(...);
+ await client.sessions.createTurnStream(...);
} catch (err) {
if (err instanceof TrueForgeError) {
console.log(err.statusCode);
@@ -96,7 +96,7 @@ The SDK uses async iterators, so you can consume the responses using a `for awai
import { TrueForge } from "trueforge";
const client = new TrueForge({ baseUrl: "YOUR_BASE_URL" });
-const response = await client.sessions.createTurn("session_id");
+const response = await client.sessions.createTurnStream("session_id", {});
for await (const item of response) {
console.log(item);
}
@@ -128,7 +128,7 @@ const client = new TrueForge({
}
});
-const response = await client.sessions.createTurn(..., {
+const response = await client.sessions.createTurnStream(..., {
headers: {
'X-Custom-Header': 'custom value'
}
@@ -140,7 +140,7 @@ const response = await client.sessions.createTurn(..., {
If you would like to send additional query string parameters as part of the request, use the `queryParams` request option.
```typescript
-const response = await client.sessions.createTurn(..., {
+const response = await client.sessions.createTurnStream(..., {
queryParams: {
'customQueryParamKey': 'custom query param value'
}
@@ -170,7 +170,7 @@ Which status codes are retried depends on the `retryStatusCodes` generator confi
Use the `maxRetries` request option to configure this behavior.
```typescript
-const response = await client.sessions.createTurn(..., {
+const response = await client.sessions.createTurnStream(..., {
maxRetries: 0 // override maxRetries at the request level
});
```
@@ -180,7 +180,7 @@ const response = await client.sessions.createTurn(..., {
The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
```typescript
-const response = await client.sessions.createTurn(..., {
+const response = await client.sessions.createTurnStream(..., {
timeoutInSeconds: 30 // override timeout to 30s
});
```
@@ -191,7 +191,7 @@ The SDK allows users to abort requests at any point by passing in an abort signa
```typescript
const controller = new AbortController();
-const response = await client.sessions.createTurn(..., {
+const response = await client.sessions.createTurnStream(..., {
abortSignal: controller.signal
});
controller.abort(); // aborts the request
@@ -203,7 +203,7 @@ The SDK provides access to raw response data, including headers, through the `.w
The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.
```typescript
-const { data, rawResponse } = await client.sessions.createTurn(...).withRawResponse();
+const { data, rawResponse } = await client.sessions.createTurnStream(...).withRawResponse();
console.log(data);
console.log(rawResponse.headers['X-My-Header']);
diff --git a/packages/sdk/pnpm-lock.yaml b/packages/sdk/pnpm-lock.yaml
index 2fb00e120..e76571160 100644
--- a/packages/sdk/pnpm-lock.yaml
+++ b/packages/sdk/pnpm-lock.yaml
@@ -405,8 +405,8 @@ packages:
resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
- resolution: {integrity: sha512-72Cuvd95zbSYPKq6Fhg8eDJRlzgWDf7/mtoZv6Qe/DYNCEBdNxoA3+rZAU2ZhGCpZlns3EssFavaZomckT5Uuw==}
+ resolution: {integrity: sha512-daRXJ9EB/rdRgu7kV+TTl1YUKtlsMWblPl2sLnpg9DZae16QCegol6A1SmCE31Lm9mXC1sRWGt/krouH+/dl7Q==}
resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
@@ -1318,14 +1318,14 @@ snapshots:
dependencies:
baseline-browser-mapping: 2.11.12
- caniuse-lite: 1.0.30001806
+ caniuse-lite: 1.0.30001807
electron-to-chromium: 1.5.402
node-releases: 2.0.53
update-browserslist-db: 1.2.3([email protected])
diff --git a/packages/sdk/reference.md b/packages/sdk/reference.md
index c8dcc3fa0..5ea5950ec 100644
--- a/packages/sdk/reference.md
+++ b/packages/sdk/reference.md
@@ -1216,7 +1216,7 @@ await client.sessions.listTurns("session_id");
</dl>
</details>
-<details><summary><code>client.sessions.<a href="/src/api/resources/sessions/client/Client.ts">createTurn</a>(session_id, { ...params }) -> core.Stream&lt;TrueForge.TurnStreamingEvent&gt;</code></summary>
+<details><summary><code>client.sessions.<a href="/src/api/resources/sessions/client/Client.ts">createTurnStream</a>(session_id, { ...params }) -> core.Stream&lt;TrueForge.TurnStreamingEvent&gt;</code></summary>
<dl>
<dd>
@@ -1228,7 +1228,9 @@ await client.sessions.listTurns("session_id");
<dl>
<dd>
-Create a turn within a session and stream its execution as Server-Sent Events.
+Create a turn within a session and execute it.
+When `stream` is true (default), respond with a Server-Sent Events stream of turn events.
+When `stream` is false, return the turn immediately with `state.status: "running"` while execution continues in the background; use get turn or subscribe to observe completion.
Use `previous_turn_id` to chain to the session's last turn (defaults to `auto`).
</dd>
</dl>
@@ -1244,7 +1246,7 @@ Use `previous_turn_id` to chain to the session's last turn (defaults to `auto`).
<dd>
```typescript
-const response = await client.sessions.createTurn("session_id");
+const response = await client.sessions.createTurnStream("session_id", {});
for await (const item of response) {
console.log(item);
}
@@ -1271,7 +1273,81 @@ for await (const item of response) {
<dl>
<dd>
-**request:** `TrueForge.CreateTurnRequest`
+**request:** `TrueForge.CreateTurnSessionsStreamRequest`
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**requestOptions:** `SessionsClient.RequestOptions`
+
+</dd>
+</dl>
+</dd>
+</dl>
+
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.sessions.<a href="/src/api/resources/sessions/client/Client.ts">createTurn</a>(session_id, { ...params }) -> TrueForge.GetTurnResponse</code></summary>
+<dl>
+<dd>
+
+#### πŸ“ Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Create a turn within a session and execute it.
+When `stream` is true (default), respond with a Server-Sent Events stream of turn events.
+When `stream` is false, return the turn immediately with `state.status: "running"` while execution continues in the background; use get turn or subscribe to observe completion.
+Use `previous_turn_id` to chain to the session's last turn (defaults to `auto`).
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### πŸ”Œ Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```typescript
+await client.sessions.createTurn("session_id", {});
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### βš™οΈ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**session_id:** `string` β€” Session identifier.
+
+</dd>
+</dl>
+
+<dl>
+<dd>
+
+**request:** `TrueForge.CreateTurnSessionsRequest`
</dd>
</dl>
diff --git a/packages/sdk/src/api/resources/sessions/client/Client.ts b/packages/sdk/src/api/resources/sessions/client/Client.ts
index ef54289a5..2302b7b57 100644
--- a/packages/sdk/src/api/resources/sessions/client/Client.ts
+++ b/packages/sdk/src/api/resources/sessions/client/Client.ts
@@ -854,20 +854,22 @@ export class SessionsClient {
}
/**
- * Create a turn within a session and stream its execution as Server-Sent Events.
+ * Create a turn within a session and execute it.
+ * When `stream` is true (default), respond with a Server-Sent Events stream of turn events.
+ * When `stream` is false, return the turn immediately with `state.status: "running"` while execution continues in the background; use get turn or subscribe to observe completion.
* Use `previous_turn_id` to chain to the session's last turn (defaults to `auto`).
*/
- public createTurn(
+ public createTurnStream(
session_id: string,
- request: TrueForge.CreateTurnRequest = {},
+ request: TrueForge.CreateTurnSessionsStreamRequest,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<core.Stream<TrueForge.TurnStreamingEvent>> {
- return core.HttpResponsePromise.fromPromise(this.__createTurn(session_id, request, requestOptions));
+ return core.HttpResponsePromise.fromPromise(this.__createTurnStream(session_id, request, requestOptions));
}
- private async __createTurn(
+ private async __createTurnStream(
session_id: string,
- request: TrueForge.CreateTurnRequest = {},
+ request: TrueForge.CreateTurnSessionsStreamRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<core.Stream<TrueForge.TurnStreamingEvent>>> {
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(this._options?.headers, requestOptions?.headers);
@@ -883,12 +885,15 @@ export class SessionsClient {
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: mergeAdditionalBodyParameters(
- serializers.CreateTurnRequest.jsonOrThrow(request, {
- unrecognizedObjectKeys: "passthrough",
- allowUnrecognizedUnionMembers: true,
- allowUnrecognizedEnumValues: true,
- omitUndefined: true,
- }),
+ {
+ ...serializers.CreateTurnSessionsStreamRequest.jsonOrThrow(request, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ omitUndefined: true,
+ }),
+ stream: true,
+ },
requestOptions?.additionalBodyParameters,
),
responseType: "sse",
@@ -983,6 +988,145 @@ export class SessionsClient {
);
}
+ /**
+ * Create a turn within a session and execute it.
+ * When `stream` is true (default), respond with a Server-Sent Events stream of turn events.
+ * When `stream` is false, return the turn immediately with `state.status: "running"` while execution continues in the background; use get turn or subscribe to observe completion.
+ * Use `previous_turn_id` to chain to the session's last turn (defaults to `auto`).
+ *
+ * @param {string} session_id - Session identifier.
+ * @param {TrueForge.CreateTurnSessionsRequest} request
+ * @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
+ *
+ * @throws {@link TrueForge.BadRequestError}
+ * @throws {@link TrueForge.NotFoundError}
+ * @throws {@link TrueForge.PreconditionFailedError}
+ * @throws {@link TrueForge.UnprocessableEntityError}
+ * @throws {@link errors.TrueForgeError}
+ * @throws {@link errors.TrueForgeTimeoutError}
+ *
+ * @example
+ * await client.sessions.createTurn("session_id", {})
+ */
+ public createTurn(
+ session_id: string,
+ request: TrueForge.CreateTurnSessionsRequest,
+ requestOptions?: SessionsClient.RequestOptions,
+ ): core.HttpResponsePromise<TrueForge.GetTurnResponse> {
+ return core.HttpResponsePromise.fromPromise(this.__createTurn(session_id, request, requestOptions));
+ }
+
+ private async __createTurn(
+ session_id: string,
+ request: TrueForge.CreateTurnSessionsRequest,
+ requestOptions?: SessionsClient.RequestOptions,
+ ): Promise<core.WithRawResponse<TrueForge.GetTurnResponse>> {
+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(this._options?.headers, requestOptions?.headers);
+ const _response = await (this._options.fetcher ?? core.fetcher)({
+ url: core.url.join(
+ (await core.Supplier.get(this._options.baseUrl)) ??
+ (await core.Supplier.get(this._options.environment)),
+ `api/v1/sessions/${core.url.encodePathParam(session_id)}/turns`,
+ ),
+ method: "POST",
+ headers: _headers,
+ contentType: "application/json",
+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+ requestType: "json",
+ body: mergeAdditionalBodyParameters(
+ {
+ ...serializers.CreateTurnSessionsRequest.jsonOrThrow(request, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ omitUndefined: true,
+ }),
+ stream: false,
+ },
+ requestOptions?.additionalBodyParameters,
+ ),
+ 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 (_response.ok) {
+ return {
+ data: serializers.GetTurnResponse.parseOrThrow(_response.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ rawResponse: _response.rawResponse,
+ };
+ }
+
+ if (_response.error.reason === "status-code") {
+ switch (_response.error.statusCode) {
+ case 400:
+ throw new TrueForge.BadRequestError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 404:
+ throw new TrueForge.NotFoundError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 412:
+ throw new TrueForge.PreconditionFailedError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ case 422:
+ throw new TrueForge.UnprocessableEntityError(
+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
+ unrecognizedObjectKeys: "passthrough",
+ allowUnrecognizedUnionMembers: true,
+ allowUnrecognizedEnumValues: true,
+ skipValidation: true,
+ breadcrumbsPrefix: ["response"],
+ }),
+ _response.rawResponse,
+ );
+ default:
+ throw new errors.TrueForgeError({
+ statusCode: _response.error.statusCode,
+ body: _response.error.body,
+ rawResponse: _response.rawResponse,
+ });
+ }
+ }
+
+ return handleNonStatusCodeError(
+ _response.error,
+ _response.rawResponse,
+ "POST",
+ "/api/v1/sessions/{session_id}/turns",
+ );
+ }
+
/**
* Fetch a single turn by ID.
*
diff --git a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
similarity index 84%
rename from packages/sdk/src/api/resources/sessions/client/requests/CreateTurnRequest.ts
rename to packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
index b770f10a7..80ab4093f 100644
--- a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnRequest.ts
+++ b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
@@ -6,7 +6,7 @@ import type * as TrueForge from "../../../../index.js";
* @example
* {}
*/
-export interface CreateTurnRequest {
+export interface CreateTurnSessionsRequest {
input?: TrueForge.TurnInputItem[];
previousTurnId?: TrueForge.PreviousTurnIdInput | null;
}
diff --git a/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
new file mode 100644
index 000000000..5d44f5fa6
--- /dev/null
+++ b/packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
@@ -0,0 +1,12 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../index.js";
+
+/**
+ * @example
+ * {}
+ */
+export interface CreateTurnSessionsStreamRequest {
+ input?: TrueForge.TurnInputItem[];
+ previousTurnId?: TrueForge.PreviousTurnIdInput | null;
+}
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 c71849aaf..3c7edcb44 100644
--- a/packages/sdk/src/api/resources/sessions/client/requests/index.ts
+++ b/packages/sdk/src/api/resources/sessions/client/requests/index.ts
@@ -1,6 +1,7 @@
export type { CancelSessionRequest } from "./CancelSessionRequest.js";
export type { CreateSessionRequest } from "./CreateSessionRequest.js";
-export type { CreateTurnRequest } from "./CreateTurnRequest.js";
+export type { CreateTurnSessionsRequest } from "./CreateTurnSessionsRequest.js";
+export type { CreateTurnSessionsStreamRequest } from "./CreateTurnSessionsStreamRequest.js";
export type { ListEventsSessionsRequest } from "./ListEventsSessionsRequest.js";
export type { ListSessionsRequest } from "./ListSessionsRequest.js";
export type { ListTurnEventsSessionsRequest } from "./ListTurnEventsSessionsRequest.js";
diff --git a/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnRequest.ts b/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
similarity index 78%
rename from packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnRequest.ts
rename to packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
index 163b3b69c..ab2ea5bf3 100644
--- a/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnRequest.ts
+++ b/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsRequest.ts
@@ -6,15 +6,15 @@ import type * as serializers from "../../../../index.js";
import { PreviousTurnIdInput } from "../../../../types/PreviousTurnIdInput.js";
import { TurnInputItem } from "../../../../types/TurnInputItem.js";
-export const CreateTurnRequest: core.serialization.Schema<
- serializers.CreateTurnRequest.Raw,
- TrueForge.CreateTurnRequest
+export const CreateTurnSessionsRequest: core.serialization.Schema<
+ serializers.CreateTurnSessionsRequest.Raw,
+ TrueForge.CreateTurnSessionsRequest
> = core.serialization.object({
input: core.serialization.list(TurnInputItem).optional(),
previousTurnId: core.serialization.property("previous_turn_id", PreviousTurnIdInput.optionalNullable()),
});
-export declare namespace CreateTurnRequest {
+export declare namespace CreateTurnSessionsRequest {
export interface Raw {
input?: TurnInputItem.Raw[] | null;
previous_turn_id?: (PreviousTurnIdInput.Raw | null | undefined) | null;
diff --git a/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts b/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
new file mode 100644
index 000000000..fef0431c3
--- /dev/null
+++ b/packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsStreamRequest.ts
@@ -0,0 +1,22 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../../../../api/index.js";
+import * as core from "../../../../../core/index.js";
+import type * as serializers from "../../../../index.js";
+import { PreviousTurnIdInput } from "../../../../types/PreviousTurnIdInput.js";
+import { TurnInputItem } from "../../../../types/TurnInputItem.js";
+
+export const CreateTurnSessionsStreamRequest: core.serialization.Schema<
+ serializers.CreateTurnSessionsStreamRequest.Raw,
+ TrueForge.CreateTurnSessionsStreamRequest
+> = core.serialization.object({
+ input: core.serialization.list(TurnInputItem).optional(),
+ previousTurnId: core.serialization.property("previous_turn_id", PreviousTurnIdInput.optionalNullable()),
+});
+
+export declare namespace CreateTurnSessionsStreamRequest {
+ export interface Raw {
+ input?: TurnInputItem.Raw[] | null;
+ previous_turn_id?: (PreviousTurnIdInput.Raw | null | undefined) | null;
+ }
+}
diff --git a/packages/sdk/src/serialization/resources/sessions/client/requests/index.ts b/packages/sdk/src/serialization/resources/sessions/client/requests/index.ts
index 7a69e2918..834355641 100644
--- a/packages/sdk/src/serialization/resources/sessions/client/requests/index.ts
+++ b/packages/sdk/src/serialization/resources/sessions/client/requests/index.ts
@@ -1,4 +1,5 @@
export { CancelSessionRequest } from "./CancelSessionRequest.js";
export { CreateSessionRequest } from "./CreateSessionRequest.js";
-export { CreateTurnRequest } from "./CreateTurnRequest.js";
+export { CreateTurnSessionsRequest } from "./CreateTurnSessionsRequest.js";
+export { CreateTurnSessionsStreamRequest } from "./CreateTurnSessionsStreamRequest.js";
export { UpdateSessionRequest } from "./UpdateSessionRequest.js";
diff --git a/packages/sdk/tests/wire/sessions.test.ts b/packages/sdk/tests/wire/sessions.test.ts
index 002902329..c5df6bee5 100644
--- a/packages/sdk/tests/wire/sessions.test.ts
+++ b/packages/sdk/tests/wire/sessions.test.ts
@@ -608,10 +608,10 @@ describe("SessionsClient", () => {
}).rejects.toThrow(TrueForgeTypes.NotFoundError);
});
- test("create_turn (1)", async () => {
+ test("create_turn_stream (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawRequestBody = {};
+ const rawRequestBody = { stream: true };
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';
@@ -624,7 +624,7 @@ describe("SessionsClient", () => {
.sseBody(rawResponseBody)
.build();
- const response = await client.sessions.createTurn("session_id");
+ const response = await client.sessions.createTurnStream("session_id", {});
const events: unknown[] = [];
for await (const event of response) {
events.push(event);
@@ -646,10 +646,136 @@ describe("SessionsClient", () => {
]);
});
+ test("create_turn_stream (2)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+ const rawRequestBody = { stream: true };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/sessions/session_id/turns")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(400)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sessions.createTurnStream("session_id", {});
+ }).rejects.toThrow(TrueForgeTypes.BadRequestError);
+ });
+
+ test("create_turn_stream (3)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+ const rawRequestBody = { stream: true };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/sessions/session_id/turns")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(404)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sessions.createTurnStream("session_id", {});
+ }).rejects.toThrow(TrueForgeTypes.NotFoundError);
+ });
+
+ test("create_turn_stream (4)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+ const rawRequestBody = { stream: true };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/sessions/session_id/turns")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(412)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sessions.createTurnStream("session_id", {});
+ }).rejects.toThrow(TrueForgeTypes.PreconditionFailedError);
+ });
+
+ test("create_turn_stream (5)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+ const rawRequestBody = { stream: true };
+ const rawResponseBody = { error: { message: "message" } };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/sessions/session_id/turns")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(422)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ await expect(async () => {
+ return await client.sessions.createTurnStream("session_id", {});
+ }).rejects.toThrow(TrueForgeTypes.UnprocessableEntityError);
+ });
+
+ test("create_turn (1)", async () => {
+ const server = mockServerPool.createServer();
+ const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
+ const rawRequestBody = { stream: false };
+ const rawResponseBody = {
+ data: {
+ created_at: "created_at",
+ id: "id",
+ input: [{ content: "content", type: "user.message" }],
+ previous_turn_id: "previous_turn_id",
+ session_id: "session_id",
+ state: { completed_at: "completed_at", reason: "server-execution-timeout", status: "cancelled" },
+ },
+ };
+
+ server
+ .mockEndpoint()
+ .post("/api/v1/sessions/session_id/turns")
+ .jsonBody(rawRequestBody)
+ .respondWith()
+ .statusCode(200)
+ .jsonBody(rawResponseBody)
+ .build();
+
+ const response = await client.sessions.createTurn("session_id", {});
+ expect(response).toEqual({
+ data: {
+ createdAt: "created_at",
+ id: "id",
+ input: [
+ {
+ content: "content",
+ type: "user.message",
+ },
+ ],
+ previousTurnId: "previous_turn_id",
+ sessionId: "session_id",
+ state: {
+ completedAt: "completed_at",
+ reason: "server-execution-timeout",
+ status: "cancelled",
+ },
+ },
+ });
+ });
+
test("create_turn (2)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawRequestBody = {};
+ const rawRequestBody = { stream: false };
const rawResponseBody = { error: { message: "message" } };
server
@@ -662,14 +788,14 @@ describe("SessionsClient", () => {
.build();
await expect(async () => {
- return await client.sessions.createTurn("session_id");
+ return await client.sessions.createTurn("session_id", {});
}).rejects.toThrow(TrueForgeTypes.BadRequestError);
});
test("create_turn (3)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawRequestBody = {};
+ const rawRequestBody = { stream: false };
const rawResponseBody = { error: { message: "message" } };
server
@@ -682,14 +808,14 @@ describe("SessionsClient", () => {
.build();
await expect(async () => {
- return await client.sessions.createTurn("session_id");
+ return await client.sessions.createTurn("session_id", {});
}).rejects.toThrow(TrueForgeTypes.NotFoundError);
});
test("create_turn (4)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawRequestBody = {};
+ const rawRequestBody = { stream: false };
const rawResponseBody = { error: { message: "message" } };
server
@@ -702,14 +828,14 @@ describe("SessionsClient", () => {
.build();
await expect(async () => {
- return await client.sessions.createTurn("session_id");
+ return await client.sessions.createTurn("session_id", {});
}).rejects.toThrow(TrueForgeTypes.PreconditionFailedError);
});
test("create_turn (5)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, baseUrl: server.baseUrl });
- const rawRequestBody = {};
+ const rawRequestBody = { stream: false };
const rawResponseBody = { error: { message: "message" } };
server
@@ -722,7 +848,7 @@ describe("SessionsClient", () => {
.build();
await expect(async () => {
- return await client.sessions.createTurn("session_id");
+ return await client.sessions.createTurn("session_id", {});
}).rejects.toThrow(TrueForgeTypes.UnprocessableEntityError);
});
diff --git a/packages/server/src/apis/turns.ts b/packages/server/src/apis/turns.ts
index a8efb3e09..b8a3562c4 100644
--- a/packages/server/src/apis/turns.ts
+++ b/packages/server/src/apis/turns.ts
@@ -40,7 +40,7 @@ import {
subscribeTurnRoute,
} from '../routes/turnRoutes';
import type { ActiveTurnRegistry } from '../runtime/activeTurns';
-import { StreamGoneError, type EventSubscriptionRegistry } from '../runtime/event-subscription';
+import { StreamGoneError, type EventSubscription, type EventSubscriptionRegistry } from '../runtime/event-subscription';
import { mintPeeredTurnId } from '../runtime/peeringIds';
import {
buildTurnSandbox,
@@ -227,6 +227,48 @@ export function turnStreamId(tenantId: string, sessionId: string, turnId: string
return `agent:turn:${tenantId}:${sessionId}:${turnId}:stream`;
}
+/**
+ * Dual-write turn events to the resumable subscription registry, then optionally
+ * forward each sequenced event (SSE path). Shared by streaming and non-streaming
+ * create-turn; the HTTP response lifecycle does not own execution.
+ */
+export async function drainTurnEvents(input: {
+ trackedStream: AsyncIterable<TurnStreamingEvent>;
+ turnEventStream: EventSubscription<TurnStreamingEvent>;
+ sessionId: string;
+ turnId: string;
+ maxExecutionTimer: NodeJS.Timeout;
+ logger: Logger;
+ onEvent?: (event: TurnStreamingEvent, sequenceNumber: number) => Promise<void>;
+}): Promise<void> {
+ const { trackedStream, turnEventStream, sessionId, turnId, maxExecutionTimer, logger, onEvent } = input;
+ try {
+ for await (const event of trackedStream) {
+ // Dual-write before any client sink so subscribers can resume after disconnect.
+ const sequenceNumber = await turnEventStream.put(event, {
+ streamTTLSeconds: streamTTLSecondsFor(event),
+ });
+ await onEvent?.(event, sequenceNumber);
+ }
+ } catch (error) {
+ if (error instanceof SessionStoreNotFoundError) {
+ logger.warn('Turn stream ended after session/turn was removed', {
+ sessionId,
+ turnId,
+ ...extractErrorLogFields(error),
+ });
+ } else {
+ logger.error('Unexpected error in turn event drain', {
+ sessionId,
+ turnId,
+ ...extractErrorLogFields(error),
+ });
+ }
+ } finally {
+ clearTimeout(maxExecutionTimer);
+ }
+}
+
/**
* 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
@@ -366,20 +408,43 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
stream: turn.stream(),
});
- let shouldWriteToSSEStream = true;
// Held for the whole turn; the stream's sequence counter dies with it.
const turnEventStream = deps.eventSubscriptions.get(turnStreamId(TENANT_ID, sessionId, turn.id));
+ const drainInput = {
+ trackedStream,
+ turnEventStream,
+ sessionId,
+ turnId: turn.id,
+ maxExecutionTimer,
+ logger: deps.logger,
+ };
+
+ // Non-stream: same unawaited drain scheduling as Hono streamSSE's run(cb).
+ // Wait until the first dual-write (turn.created) so immediate subscribeToTurn
+ // cannot 412 before the resumable stream exists.
+ if (!body.stream) {
+ const { promise: firstEventDualWritten, resolve: markFirstEventDualWritten } = Promise.withResolvers<undefined>();
+ void drainTurnEvents({
+ ...drainInput,
+ onEvent: () => {
+ markFirstEventDualWritten(undefined);
+ return Promise.resolve();
+ },
+ }).finally(() => {
+ markFirstEventDualWritten(undefined);
+ });
+ await firstEventDualWritten;
+ return c.json({ data: toWireTurn(turn.record) }, 200);
+ }
+
+ let shouldWriteToSSEStream = true;
return streamSSE(c, async stream => {
stream.onAbort(() => {
shouldWriteToSSEStream = false;
});
- try {
- for await (const event of trackedStream) {
- // 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),
- });
+ await drainTurnEvents({
+ ...drainInput,
+ onEvent: async (event, sequenceNumber) => {
if (!stream.closed && !stream.aborted && shouldWriteToSSEStream) {
try {
await stream.writeSSE(turnEventSsePayload(event, sequenceNumber));
@@ -388,25 +453,9 @@ export function createTurnsRouter(deps: TurnsRouterDeps) {
shouldWriteToSSEStream = false;
}
}
- }
- } catch (error) {
- if (error instanceof SessionStoreNotFoundError) {
- deps.logger.warn('Turn stream ended after session/turn was removed', {
- sessionId,
- turnId: turn.id,
- ...extractErrorLogFields(error),
- });
- } else {
- deps.logger.error('Unexpected error in turn SSE stream loop', {
- sessionId,
- turnId: turn.id,
- ...extractErrorLogFields(error),
- });
- }
- } finally {
- clearTimeout(maxExecutionTimer);
- await stream.close();
- }
+ },
+ });
+ await stream.close();
});
};
diff --git a/packages/server/src/routes/turnRoutes.ts b/packages/server/src/routes/turnRoutes.ts
index 574e908a2..fa1370d37 100644
--- a/packages/server/src/routes/turnRoutes.ts
+++ b/packages/server/src/routes/turnRoutes.ts
@@ -110,11 +110,19 @@ export const createAndExecuteTurnRoute = createRoute({
path: '/{session_id}/turns',
tags: [SESSIONS_TAG],
summary: 'Create and execute a turn in a session',
- description: `Create a turn within a session and stream its execution as Server-Sent Events.
+ description: `Create a turn within a session and execute it.
+When \`stream\` is true (default), respond with a Server-Sent Events stream of turn events.
+When \`stream\` is false, return the turn immediately with \`state.status: "running"\` while execution continues in the background; use get turn or subscribe to observe completion.
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',
- 'x-fern-streaming': { format: 'sse', resumable: false },
+ 'x-fern-streaming': {
+ format: 'sse',
+ resumable: false,
+ 'stream-condition': '$request.stream',
+ response: { $ref: '#/components/schemas/GetTurnResponse' },
+ 'response-stream': { $ref: '#/components/schemas/TurnStreamingEvent' },
+ },
request: {
params: SessionIdParamsSchema,
body: {
@@ -125,11 +133,15 @@ Use \`previous_turn_id\` to chain to the session's last turn (defaults to \`auto
responses: {
200: {
content: {
+ 'application/json': {
+ schema: GetTurnResponseSchema,
+ },
'text/event-stream': {
schema: TurnStreamingEventSchema,
},
},
- description: 'Server-Sent Events stream of turn events.',
+ description:
+ 'When stream is false: the running turn. When stream is true: Server-Sent Events stream of turn events.',
},
400: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
diff --git a/packages/server/tests/unit/apis/createTurnNonStreaming.test.ts b/packages/server/tests/unit/apis/createTurnNonStreaming.test.ts
new file mode 100644
index 000000000..58fe4300f
--- /dev/null
+++ b/packages/server/tests/unit/apis/createTurnNonStreaming.test.ts
@@ -0,0 +1,122 @@
+import { OpenAPIHono } from '@hono/zod-openapi';
+import type { Sessions, TurnStreamingEvent } from '@truefoundry/utils-core/agent-session';
+import { AgentSpecSchema } from '@truefoundry/utils-core/agent-session';
+import { createLogger } from 'winston';
+import { TENANT_ID } from '../../../src/apis/sessions';
+import { createTurnsRouter, turnStreamId } from '../../../src/apis/turns';
+import { migrateSqliteToLatest } from '../../../src/db/migrateSqlite';
+import { createSqliteDb } from '../../../src/db/sqlite/client';
+import { SqliteMcpServerStore } from '../../../src/db/sqlite/mcp-server-store/SqliteMcpServerStore';
+import { SqliteModelProviderStore } from '../../../src/db/sqlite/model-provider-store/SqliteModelProviderStore';
+import { SqliteSandboxProviderStore } from '../../../src/db/sqlite/sandbox-provider-store/SqliteSandboxProviderStore';
+import { SqliteSessionStore } from '../../../src/db/sqlite/session-store/SqliteSessionStore';
+import { SqliteSkillStore } from '../../../src/db/sqlite/skill-store/SqliteSkillStore';
+import { SqliteOAuthTokenStore } from '../../../src/db/sqlite/token-store/SqliteOAuthTokenStore';
+import { ActiveTurnRegistry } from '../../../src/runtime/activeTurns';
+import { EventSubscriptionRegistry } from '../../../src/runtime/event-subscription/index.js';
+
+describe('create turn non-streaming', () => {
+ it('returns the running turn JSON after dual-writing turn.created so subscribe can attach', async () => {
+ const logger = createLogger({ silent: true });
+ const db = createSqliteDb(':memory:');
+ await migrateSqliteToLatest(db);
+ const modelProviderStore = new SqliteModelProviderStore(db);
+ await modelProviderStore.upsertProvider({
+ tenant_id: 'default',
+ name: 'test-provider',
+ manifest: {
+ type: 'openai',
+ auth: { api_key: 'sk-test' },
+ models: [
+ {
+ model_id: 'test-model',
+ name: 'test-model',
+ properties: { context_length: 128000, max_output_tokens: 4096 },
+ },
+ ],
+ },
+ });
+
+ let releaseRest: (() => void) | undefined;
+ const restParked = new Promise<void>(resolve => {
+ releaseRest = resolve;
+ });
+
+ const sessions = {
+ get: () =>
+ Promise.resolve({
+ agent_spec: AgentSpecSchema.parse({ model: { name: 'test-provider/test-model' } }),
+ record: { last_turn_id: null },
+ createTurn: () =>
+ Promise.resolve({
+ id: 'turn-non-stream',
+ record: {
+ turn_id: 'turn-non-stream',
+ session_id: 's1',
+ previous_turn_id: null,
+ input: [],
+ state: { status: 'running' },
+ created_at: new Date('2026-01-01T00:00:00.000Z'),
+ },
+ stream: async function* stream() {
+ yield {
+ type: 'turn.created',
+ id: 'evt_created',
+ turn_id: 'turn-non-stream',
+ previous_turn_id: null,
+ state: { status: 'running' },
+ created_at: '2026-01-01T00:00:00.000Z',
+ thread_id: null,
+ };
+ await restParked;
+ },
+ }),
+ }),
+ } as unknown as Sessions;
+
+ const eventSubscriptions = new EventSubscriptionRegistry<TurnStreamingEvent>(undefined);
+ const app = new OpenAPIHono();
+ app.route(
+ '/',
+ createTurnsRouter({
+ sessions,
+ sessionStore: new SqliteSessionStore(db),
+ activeTurns: new ActiveTurnRegistry(),
+ modelProviderStore,
+ mcpServerStore: new SqliteMcpServerStore(db),
+ tokenStore: new SqliteOAuthTokenStore(db),
+ skillStore: new SqliteSkillStore(db),
+ eventSubscriptions,
+ sandboxProviderStore: new SqliteSandboxProviderStore(db),
+ logger,
+ }),
+ );
+
+ const response = await app.request('/s1/turns', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ stream: false }),
+ });
+
+ expect(response.status).toBe(200);
+ expect(response.headers.get('content-type') ?? '').toContain('application/json');
+ const body: unknown = await response.json();
+ expect(body).toEqual({
+ data: {
+ id: 'turn-non-stream',
+ session_id: 's1',
+ previous_turn_id: null,
+ input: [],
+ state: { status: 'running' },
+ created_at: '2026-01-01T00:00:00.000Z',
+ },
+ });
+
+ // Resumable stream must exist before the JSON response returns.
+ await expect(
+ eventSubscriptions.get(turnStreamId(TENANT_ID, 's1', 'turn-non-stream')).assertSubscribable(),
+ ).resolves.toBeUndefined();
+
+ releaseRest?.();
+ });
+});