The open-source agent harness - the runtime layer that turns an LLM into a working agent.
// This file was auto-generated by Fern from our API Definition.
import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
import { type NormalizedClientOptionsWithAuth, normalizeClientOptionsWithAuth } from "../../../../BaseClient.js";
import { mergeHeaders } from "../../../../core/headers.js";
import * as core from "../../../../core/index.js";
import { mergeAdditionalBodyParameters } from "../../../../core/requestBody.js";
import { handleNonStatusCodeError } from "../../../../errors/handleNonStatusCodeError.js";
import * as errors from "../../../../errors/index.js";
import * as serializers from "../../../../serialization/index.js";
import * as TrueForge from "../../../index.js";
export declare namespace SessionsClient {
export type Options = BaseClientOptions;
export interface RequestOptions extends BaseRequestOptions {}
}
export class SessionsClient {
protected readonly _options: NormalizedClientOptionsWithAuth<SessionsClient.Options>;
constructor(options: SessionsClient.Options) {
this._options = normalizeClientOptionsWithAuth(options);
}
/**
* List the sessions (newest first by default).
*
* @param {TrueForge.ListSessionsRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.list()
*/
public async list(
request: TrueForge.ListSessionsRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.Page<TrueForge.Session, TrueForge.ListSessionsResponse>> {
const list = core.HttpResponsePromise.interceptFunction(
async (
request: TrueForge.ListSessionsRequest,
): Promise<core.WithRawResponse<TrueForge.ListSessionsResponse>> => {
const {
limit = 25,
order,
pageToken,
startTimestamp,
endTimestamp,
agentId,
createdByMe,
metadata,
sourceType,
sourceId,
} = request;
const _queryParams: Record<string, unknown> = {
limit,
order:
order != null
? serializers.ListSessionsOrder.jsonOrThrow(order, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
})
: undefined,
page_token: pageToken,
start_timestamp: startTimestamp != null ? startTimestamp?.toISOString() : undefined,
end_timestamp: endTimestamp != null ? endTimestamp?.toISOString() : undefined,
agent_id: agentId,
created_by_me: createdByMe,
metadata,
source_type:
sourceType != null
? serializers.SessionSourceType.jsonOrThrow(sourceType, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
})
: undefined,
source_id: sourceId,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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",
),
method: "GET",
headers: _headers,
queryString: core.url
.queryBuilder()
.addMany(_queryParams)
.mergeAdditional(requestOptions?.queryParams)
.build(),
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.ListSessionsResponse.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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/sessions");
},
);
const dataWithRawResponse = await list(request).withRawResponse();
return new core.Page<TrueForge.Session, TrueForge.ListSessionsResponse>({
response: dataWithRawResponse.data,
rawResponse: dataWithRawResponse.rawResponse,
hasNextPage: (response) =>
response?.pagination.nextPageToken != null &&
!(typeof response?.pagination.nextPageToken === "string" && response?.pagination.nextPageToken === ""),
getItems: (response) => response?.data ?? [],
loadPage: (response) => {
return list(core.setObjectProperty(request, "pageToken", response?.pagination.nextPageToken));
},
});
}
/**
* Create a session with `agent` as either `{ name }` (named registry binding) or `{ spec: AgentSpec }` (inline). Named sessions snapshot the agent name at create and resolve the live agent on each turn. Responses use `{ type: "reference", name, id }` or `{ type: "inline", spec }`.
*
* @param {TrueForge.CreateSessionRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link TrueForge.UnprocessableEntityError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.create({
* agent: {
* name: "name"
* }
* })
*/
public create(
request: TrueForge.CreateSessionRequest,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.GetSessionResponse> {
return core.HttpResponsePromise.fromPromise(this.__create(request, requestOptions));
}
private async __create(
request: TrueForge.CreateSessionRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.GetSessionResponse>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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",
),
method: "POST",
headers: _headers,
contentType: "application/json",
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: mergeAdditionalBodyParameters(
serializers.CreateSessionRequest.jsonOrThrow(request, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
}),
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.GetSessionResponse.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 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");
}
/**
* Fetch a session by ID. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.
*
* @param {string} session_id - Session identifier.
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.get("session_id")
*/
public get(
session_id: string,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.GetSessionResponse> {
return core.HttpResponsePromise.fromPromise(this.__get(session_id, requestOptions));
}
private async __get(
session_id: string,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.GetSessionResponse>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}`,
),
method: "GET",
headers: _headers,
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
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.GetSessionResponse.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 403:
throw new TrueForge.ForbiddenError(
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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/sessions/{session_id}");
}
/**
* Delete a session and all related turns, events, and internal state. Only the session creator may delete it. Idempotent if already gone.
*
* @param {string} session_id - Session identifier.
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.delete("session_id")
*/
public delete(session_id: string, requestOptions?: SessionsClient.RequestOptions): core.HttpResponsePromise<void> {
return core.HttpResponsePromise.fromPromise(this.__delete(session_id, requestOptions));
}
private async __delete(
session_id: string,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<void>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}`,
),
method: "DELETE",
headers: _headers,
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
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: undefined, rawResponse: _response.rawResponse };
}
if (_response.error.reason === "status-code") {
switch (_response.error.statusCode) {
case 403:
throw new TrueForge.ForbiddenError(
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,
"DELETE",
"/api/v1/sessions/{session_id}",
);
}
/**
* Update a session: optional `title`, `metadata`, `shared`, and (inline sessions only) `agent` as `{ spec: AgentSpec }`. Named sessions reject agent updates. An empty body is a valid no-op that refreshes `updated_at`. Only the session creator may update it.
*
* @param {string} session_id - Session identifier.
* @param {TrueForge.UpdateSessionRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link TrueForge.UnprocessableEntityError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.update("session_id")
*/
public update(
session_id: string,
request: TrueForge.UpdateSessionRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.GetSessionResponse> {
return core.HttpResponsePromise.fromPromise(this.__update(session_id, request, requestOptions));
}
private async __update(
session_id: string,
request: TrueForge.UpdateSessionRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.GetSessionResponse>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}`,
),
method: "PATCH",
headers: _headers,
contentType: "application/json",
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: mergeAdditionalBodyParameters(
serializers.UpdateSessionRequest.jsonOrThrow(request, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
}),
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.GetSessionResponse.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 403:
throw new TrueForge.ForbiddenError(
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 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,
"PATCH",
"/api/v1/sessions/{session_id}",
);
}
/**
* Cancel the running last turn for a session. Only the session creator may cancel.
*
* @param {string} session_id - Session identifier.
* @param {TrueForge.CancelSessionRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link TrueForge.PreconditionFailedError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.cancel("session_id")
*/
public cancel(
session_id: string,
request: TrueForge.CancelSessionRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.CancelSessionResponse> {
return core.HttpResponsePromise.fromPromise(this.__cancel(session_id, request, requestOptions));
}
private async __cancel(
session_id: string,
request: TrueForge.CancelSessionRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.CancelSessionResponse>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/cancel`,
),
method: "POST",
headers: _headers,
contentType: "application/json",
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: mergeAdditionalBodyParameters(
serializers.CancelSessionRequest.jsonOrThrow(request, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
}),
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.CancelSessionResponse.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 403:
throw new TrueForge.ForbiddenError(
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,
);
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}/cancel",
);
}
/**
* List session events as `{ turn_id, event }` across the active turn branch (newest first), including persisted events from a running tip. Each turn contributes turn.created, content events (model.message, tool.call, …), and turn.done when terminal; streaming deltas are not included. Use `page_token` to paginate backward toward older events while retaining the original branch anchor. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.
*
* @param {string} session_id - Session identifier.
* @param {TrueForge.ListEventsSessionsRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.listEvents("session_id")
*/
public async listEvents(
session_id: string,
request: TrueForge.ListEventsSessionsRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.Page<TrueForge.SessionEventItem, TrueForge.ListSessionEventsResponse>> {
const list = core.HttpResponsePromise.interceptFunction(
async (
request: TrueForge.ListEventsSessionsRequest,
): Promise<core.WithRawResponse<TrueForge.ListSessionEventsResponse>> => {
const { pageToken, lastTurnId, limit = 100 } = request;
const _queryParams: Record<string, unknown> = {
page_token: pageToken,
last_turn_id: lastTurnId,
limit,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/events`,
),
method: "GET",
headers: _headers,
queryString: core.url
.queryBuilder()
.addMany(_queryParams)
.mergeAdditional(requestOptions?.queryParams)
.build(),
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.ListSessionEventsResponse.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 403:
throw new TrueForge.ForbiddenError(
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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(
_response.error,
_response.rawResponse,
"GET",
"/api/v1/sessions/{session_id}/events",
);
},
);
const dataWithRawResponse = await list(request).withRawResponse();
return new core.Page<TrueForge.SessionEventItem, TrueForge.ListSessionEventsResponse>({
response: dataWithRawResponse.data,
rawResponse: dataWithRawResponse.rawResponse,
hasNextPage: (response) =>
response?.pagination.nextPageToken != null &&
!(typeof response?.pagination.nextPageToken === "string" && response?.pagination.nextPageToken === ""),
getItems: (response) => response?.data ?? [],
loadPage: (response) => {
return list(core.setObjectProperty(request, "pageToken", response?.pagination.nextPageToken));
},
});
}
/**
* List turns for a session (newest first by default), token-paginated. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.
*
* @param {string} session_id - Session identifier.
* @param {TrueForge.ListTurnsSessionsRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.listTurns("session_id")
*/
public async listTurns(
session_id: string,
request: TrueForge.ListTurnsSessionsRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.Page<TrueForge.Turn, TrueForge.ListTurnsResponse>> {
const list = core.HttpResponsePromise.interceptFunction(
async (
request: TrueForge.ListTurnsSessionsRequest,
): Promise<core.WithRawResponse<TrueForge.ListTurnsResponse>> => {
const { limit = 25, pageToken } = request;
const _queryParams: Record<string, unknown> = {
limit,
page_token: pageToken,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/turns`,
),
method: "GET",
headers: _headers,
queryString: core.url
.queryBuilder()
.addMany(_queryParams)
.mergeAdditional(requestOptions?.queryParams)
.build(),
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.ListTurnsResponse.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 403:
throw new TrueForge.ForbiddenError(
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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(
_response.error,
_response.rawResponse,
"GET",
"/api/v1/sessions/{session_id}/turns",
);
},
);
const dataWithRawResponse = await list(request).withRawResponse();
return new core.Page<TrueForge.Turn, TrueForge.ListTurnsResponse>({
response: dataWithRawResponse.data,
rawResponse: dataWithRawResponse.rawResponse,
hasNextPage: (response) =>
response?.pagination.nextPageToken != null &&
!(typeof response?.pagination.nextPageToken === "string" && response?.pagination.nextPageToken === ""),
getItems: (response) => response?.data ?? [],
loadPage: (response) => {
return list(core.setObjectProperty(request, "pageToken", response?.pagination.nextPageToken));
},
});
}
/**
* Create a turn within a session and execute it.
* Only the session creator may create turns.
* 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`); use `none` for a new root.
*/
public createTurnStream(
session_id: string,
request: TrueForge.CreateTurnSessionsStreamRequest,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<core.Stream<TrueForge.TurnStreamingEvent>> {
return core.HttpResponsePromise.fromPromise(this.__createTurnStream(session_id, request, requestOptions));
}
private async __createTurnStream(
session_id: string,
request: TrueForge.CreateTurnSessionsStreamRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<core.Stream<TrueForge.TurnStreamingEvent>>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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(session_id, errors.TrueForgeError)}/turns`,
),
method: "POST",
headers: _headers,
contentType: "application/json",
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: mergeAdditionalBodyParameters(
{
...serializers.CreateTurnSessionsStreamRequest.jsonOrThrow(request, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
}),
stream: true,
},
requestOptions?.additionalBodyParameters,
),
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 (_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",
},
}),
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 401:
throw new TrueForge.UnauthorizedError(
serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
skipValidation: true,
breadcrumbsPrefix: ["response"],
}),
_response.rawResponse,
);
case 403:
throw new TrueForge.ForbiddenError(
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 413:
throw new TrueForge.ContentTooLargeError(
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",
);
}
/**
* Create a turn within a session and execute it.
* Only the session creator may create turns.
* 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`); use `none` for a new root.
*
* @param {string} session_id - Session identifier.
* @param {TrueForge.CreateTurnSessionsRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.UnauthorizedError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link TrueForge.PreconditionFailedError}
* @throws {@link TrueForge.ContentTooLargeError}
* @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 _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/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 401:
throw new TrueForge.UnauthorizedError(
serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
skipValidation: true,
breadcrumbsPrefix: ["response"],
}),
_response.rawResponse,
);
case 403:
throw new TrueForge.ForbiddenError(
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 413:
throw new TrueForge.ContentTooLargeError(
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. Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.
*
* @param {string} session_id - Session identifier.
* @param {string} turn_id - Turn identifier.
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.getTurn("session_id", "turn_id")
*/
public getTurn(
session_id: string,
turn_id: string,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.GetTurnResponse> {
return core.HttpResponsePromise.fromPromise(this.__getTurn(session_id, turn_id, requestOptions));
}
private async __getTurn(
session_id: string,
turn_id: string,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.GetTurnResponse>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/turns/${core.url.encodePathParam(turn_id, errors.TrueForgeError)}`,
),
method: "GET",
headers: _headers,
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
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 403:
throw new TrueForge.ForbiddenError(
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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(
_response.error,
_response.rawResponse,
"GET",
"/api/v1/sessions/{session_id}/turns/{turn_id}",
);
}
/**
* Download a file from the sandbox this turn ran in. Paths come from the assistant's `sandbox_artifacts` block. Only the session creator may download.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link TrueForge.GoneError}
* @throws {@link TrueForge.PreconditionFailedError}
* @throws {@link TrueForge.ContentTooLargeError}
* @throws {@link TrueForge.FailedDependencyError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*/
public downloadSandboxFile(
session_id: string,
turn_id: string,
request: TrueForge.DownloadSandboxFileSessionsRequest,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<core.BinaryResponse> {
return core.HttpResponsePromise.fromPromise(
this.__downloadSandboxFile(session_id, turn_id, request, requestOptions),
);
}
private async __downloadSandboxFile(
session_id: string,
turn_id: string,
request: TrueForge.DownloadSandboxFileSessionsRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<core.BinaryResponse>> {
const { path } = request;
const _queryParams: Record<string, unknown> = {
path,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
this._options?.headers,
requestOptions?.headers,
);
const _response = await (this._options.fetcher ?? core.fetcher)<core.BinaryResponse>({
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, errors.TrueForgeError)}/turns/${core.url.encodePathParam(turn_id, errors.TrueForgeError)}/download-sandbox-file`,
),
method: "GET",
headers: _headers,
queryString: core.url
.queryBuilder()
.addMany(_queryParams)
.mergeAdditional(requestOptions?.queryParams)
.build(),
responseType: "binary-response",
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: _response.body, 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 403:
throw new TrueForge.ForbiddenError(
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 410:
throw new TrueForge.GoneError(
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 413:
throw new TrueForge.ContentTooLargeError(
serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
skipValidation: true,
breadcrumbsPrefix: ["response"],
}),
_response.rawResponse,
);
case 424:
throw new TrueForge.FailedDependencyError(
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,
"GET",
"/api/v1/sessions/{session_id}/turns/{turn_id}/download-sandbox-file",
);
}
/**
* Paginated persisted events for a turn (insertion order by default). Allowed for the creator, a manager of the bound named agent, or any tenant member when the session is shared.
*
* @param {string} session_id - Session identifier.
* @param {string} turn_id - Turn identifier.
* @param {TrueForge.ListTurnEventsSessionsRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.listTurnEvents("session_id", "turn_id")
*/
public async listTurnEvents(
session_id: string,
turn_id: string,
request: TrueForge.ListTurnEventsSessionsRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.Page<TrueForge.SessionEvent, TrueForge.ListTurnEventsResponse>> {
const list = core.HttpResponsePromise.interceptFunction(
async (
request: TrueForge.ListTurnEventsSessionsRequest,
): Promise<core.WithRawResponse<TrueForge.ListTurnEventsResponse>> => {
const { limit = 100, pageToken, order } = request;
const _queryParams: Record<string, unknown> = {
limit,
page_token: pageToken,
order:
order != null
? serializers.ListTurnEventsOrder.jsonOrThrow(order, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
})
: undefined,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/turns/${core.url.encodePathParam(turn_id, errors.TrueForgeError)}/events`,
),
method: "GET",
headers: _headers,
queryString: core.url
.queryBuilder()
.addMany(_queryParams)
.mergeAdditional(requestOptions?.queryParams)
.build(),
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.ListTurnEventsResponse.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 403:
throw new TrueForge.ForbiddenError(
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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(
_response.error,
_response.rawResponse,
"GET",
"/api/v1/sessions/{session_id}/turns/{turn_id}/events",
);
},
);
const dataWithRawResponse = await list(request).withRawResponse();
return new core.Page<TrueForge.SessionEvent, TrueForge.ListTurnEventsResponse>({
response: dataWithRawResponse.data,
rawResponse: dataWithRawResponse.rawResponse,
hasNextPage: (response) =>
response?.pagination.nextPageToken != null &&
!(typeof response?.pagination.nextPageToken === "string" && response?.pagination.nextPageToken === ""),
getItems: (response) => response?.data ?? [],
loadPage: (response) => {
return list(core.setObjectProperty(request, "pageToken", response?.pagination.nextPageToken));
},
});
}
/**
* Create events for a turn. Only the session creator may create them.
*
* @param {string} session_id - Session identifier.
* @param {string} turn_id - Turn identifier.
* @param {TrueForge.CreateTurnEventRequest} request
* @param {SessionsClient.RequestOptions} requestOptions - Request-specific configuration.
*
* @throws {@link TrueForge.BadRequestError}
* @throws {@link TrueForge.ForbiddenError}
* @throws {@link TrueForge.NotFoundError}
* @throws {@link TrueForge.ConflictError}
* @throws {@link errors.TrueForgeError}
* @throws {@link errors.TrueForgeTimeoutError}
*
* @example
* await client.sessions.createTurnEvent("session_id", "turn_id", {
* events: [{
* type: "user.mcp_auth_continue"
* }]
* })
*/
public createTurnEvent(
session_id: string,
turn_id: string,
request: TrueForge.CreateTurnEventRequest,
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<TrueForge.CreateTurnEventResponse> {
return core.HttpResponsePromise.fromPromise(
this.__createTurnEvent(session_id, turn_id, request, requestOptions),
);
}
private async __createTurnEvent(
session_id: string,
turn_id: string,
request: TrueForge.CreateTurnEventRequest,
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<TrueForge.CreateTurnEventResponse>> {
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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, errors.TrueForgeError)}/turns/${core.url.encodePathParam(turn_id, errors.TrueForgeError)}/events`,
),
method: "POST",
headers: _headers,
contentType: "application/json",
queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
requestType: "json",
body: mergeAdditionalBodyParameters(
serializers.CreateTurnEventRequest.jsonOrThrow(request, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
omitUndefined: true,
}),
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.CreateTurnEventResponse.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 403:
throw new TrueForge.ForbiddenError(
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 409:
throw new TrueForge.ConflictError(
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/{turn_id}/events",
);
}
/**
* Subscribe to the live SSE stream for a turn. Only the session creator may subscribe. Pass `after_sequence_number` to resume after a disconnect (exclusive — events after this sequence number are replayed).
*/
public subscribeToTurn(
session_id: string,
turn_id: string,
request: TrueForge.SubscribeToTurnSessionsRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): core.HttpResponsePromise<core.Stream<TrueForge.TurnStreamingEvent>> {
return core.HttpResponsePromise.fromPromise(
this.__subscribeToTurn(session_id, turn_id, request, requestOptions),
);
}
private async __subscribeToTurn(
session_id: string,
turn_id: string,
request: TrueForge.SubscribeToTurnSessionsRequest = {},
requestOptions?: SessionsClient.RequestOptions,
): Promise<core.WithRawResponse<core.Stream<TrueForge.TurnStreamingEvent>>> {
const { afterSequenceNumber } = request;
const _queryParams: Record<string, unknown> = {
after_sequence_number: afterSequenceNumber,
};
const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();
const _headers: core.Fetcher.Args["headers"] = mergeHeaders(
_authRequest.headers,
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(session_id, errors.TrueForgeError)}/turns/${core.url.encodePathParam(turn_id, errors.TrueForgeError)}/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(session_id, errors.TrueForgeError)}/turns/${core.url.encodePathParam(turn_id, errors.TrueForgeError)}/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 TrueForge.BadRequestError(
serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {
unrecognizedObjectKeys: "passthrough",
allowUnrecognizedUnionMembers: true,
allowUnrecognizedEnumValues: true,
skipValidation: true,
breadcrumbsPrefix: ["response"],
}),
_response.rawResponse,
);
case 403:
throw new TrueForge.ForbiddenError(
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,
);
default:
throw new errors.TrueForgeError({
statusCode: _response.error.statusCode,
body: _response.error.body,
rawResponse: _response.rawResponse,
});
}
}
return handleNonStatusCodeError(
_response.error,
_response.rawResponse,
"GET",
"/api/v1/sessions/{session_id}/turns/{turn_id}/subscribe",
);
}
}