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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.mdindex 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 awaiimport { 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 confiUse 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```typescriptconst 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 `.wThe `.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.yamlindex 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.30001807electron-to-chromium: 1.5.402node-releases: 2.0.53update-browserslist-db: 1.2.3([email protected])- [email protected]: {}+ [email protected]: {}diff --git a/packages/sdk/reference.md b/packages/sdk/reference.mdindex 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<TrueForge.TurnStreamingEvent></code></summary>+<details><summary><code>client.sessions.<a href="/src/api/resources/sessions/client/Client.ts">createTurnStream</a>(session_id, { ...params }) -> core.Stream<TrueForge.TurnStreamingEvent></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.tsindex 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.tssimilarity index 84%rename from packages/sdk/src/api/resources/sessions/client/requests/CreateTurnRequest.tsrename to packages/sdk/src/api/resources/sessions/client/requests/CreateTurnSessionsRequest.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tssimilarity index 78%rename from packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnRequest.tsrename to packages/sdk/src/serialization/resources/sessions/client/requests/CreateTurnSessionsRequest.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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: stringreturn `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.tsindex 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 \`autoresponses: {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.tsnew file mode 100644index 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?.();+ });+});