@trigger.dev/core 4.4.5 → 4.5.0-rc.0

package/dist/esm/v3/apiClient/index.d.ts

@@ -1,10 +1,11 @@
 import { z } from "zod";
-import { AddTagsRequestBody, ApiDeploymentListOptions, BatchItemNDJSON, BatchTaskRunExecutionResult, BatchTriggerTaskV3RequestBody, CompleteWaitpointTokenRequestBody, CreateBatchRequestBody, CreateBatchResponse, CreateEnvironmentVariableRequestBody, CreateInputStreamWaitpointRequestBody, CreateScheduleOptions, CreateWaitpointTokenRequestBody, CreateWaitpointTokenResponseBody, ListQueueOptions, ListRunResponseItem, ListScheduleOptions, QueryExecuteResponseBody, QuerySchemaResponseBody, ListDashboardsResponseBody, RescheduleRunRequestBody, RetrieveQueueParam, ResolvePromptRequestBody, PromotePromptVersionRequestBody, CreatePromptOverrideRequestBody, UpdatePromptOverrideRequestBody, ReactivatePromptOverrideRequestBody, StreamBatchItemsResponse, TaskRunExecutionResult, TriggerTaskRequestBody, UpdateEnvironmentVariableRequestBody, UpdateMetadataRequestBody, UpdateScheduleOptions, WaitForDurationRequestBody, WaitpointTokenItem } from "../schemas/index.js";
+import { AddTagsRequestBody, ApiDeploymentListOptions, BatchItemNDJSON, BatchTaskRunExecutionResult, BatchTriggerTaskV3RequestBody, CloseSessionRequestBody, CompleteWaitpointTokenRequestBody, CreateSessionRequestBody, EndAndContinueSessionRequestBody, ListSessionsOptions, ListedSessionItem, UpdateSessionRequestBody, CreateBatchRequestBody, CreateBatchResponse, CreateEnvironmentVariableRequestBody, CreateInputStreamWaitpointRequestBody, CreateSessionStreamWaitpointRequestBody, CreateScheduleOptions, CreateWaitpointTokenRequestBody, CreateWaitpointTokenResponseBody, ListQueueOptions, ListRunResponseItem, ListScheduleOptions, QueryExecuteResponseBody, QuerySchemaResponseBody, ListDashboardsResponseBody, RescheduleRunRequestBody, RetrieveQueueParam, ResolvePromptRequestBody, PromotePromptVersionRequestBody, CreatePromptOverrideRequestBody, UpdatePromptOverrideRequestBody, ReactivatePromptOverrideRequestBody, StreamBatchItemsResponse, TaskRunExecutionResult, TriggerTaskRequestBody, UpdateEnvironmentVariableRequestBody, UpdateMetadataRequestBody, UpdateScheduleOptions, WaitForDurationRequestBody, WaitpointTokenItem } from "../schemas/index.js";
 import { AsyncIterableStream } from "../streams/asyncIterableStream.js";
 import { AnyRunTypes, TriggerJwtOptions } from "../types/tasks.js";
 import { Prettify } from "../types/utils.js";
 import { AnyZodFetchOptions, ApiPromise, ApiRequestOptions, CursorPagePromise, ZodFetchOptions, isRequestOptions } from "./core.js";
 import { AnyRealtimeRun, AnyRunShape, RealtimeRun, RunShape, RunStreamCallback, RunSubscription, SSEStreamSubscription, TaskRunShape, RealtimeRunSkipColumns, type SSEStreamPart } from "./runStream.js";
+import { type ControlEvent } from "../sessionStreams/wireProtocol.js";
 import { CreateEnvironmentVariableParams, ImportEnvironmentVariablesParams, ListProjectRunsQueryParams, ListRunsQueryParams, ListWaitpointTokensQueryParams, SubscribeToRunsQueryParams, UpdateEnvironmentVariableParams } from "./types.js";
 import { ApiClientConfiguration } from "../apiClientManager-api.js";
 export type CreateWaitpointTokenResponse = Prettify<CreateWaitpointTokenResponseBody & {
@@ -104,6 +105,16 @@ export declare class ApiClient {
         presignedUrl: string;
         storagePath?: string | undefined;
     }>;
+    /** Presigned PUT URL for a `chat.agent` session snapshot. */
+    createChatSnapshotUploadUrl(sessionId: string, requestOptions?: ZodFetchOptions): ApiPromise<{
+        presignedUrl: string;
+        storagePath?: string | undefined;
+    }>;
+    /** Presigned GET URL for a `chat.agent` session snapshot. */
+    getChatSnapshotUrl(sessionId: string, requestOptions?: ZodFetchOptions): ApiPromise<{
+        presignedUrl: string;
+        storagePath?: string | undefined;
+    }>;
     retrieveRun(runId: string, requestOptions?: ZodFetchOptions): ApiPromise<{
         status: "PENDING_VERSION" | "QUEUED" | "DEQUEUED" | "EXECUTING" | "WAITING" | "COMPLETED" | "CANCELED" | "FAILED" | "CRASHED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED" | "TIMED_OUT";
         id: string;
@@ -139,11 +150,13 @@ export declare class ApiClient {
                 startedAt?: Date | undefined;
                 idempotencyKey?: string | undefined;
                 version?: string | undefined;
+                region?: string | undefined;
                 ttl?: string | undefined;
                 batchId?: string | undefined;
                 finishedAt?: Date | undefined;
                 delayedUntil?: Date | undefined;
                 expiredAt?: Date | undefined;
+                taskKind?: string | undefined;
             } | undefined;
             parent?: {
                 status: "PENDING_VERSION" | "QUEUED" | "DEQUEUED" | "EXECUTING" | "WAITING" | "COMPLETED" | "CANCELED" | "FAILED" | "CRASHED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED" | "TIMED_OUT";
@@ -169,11 +182,13 @@ export declare class ApiClient {
                 startedAt?: Date | undefined;
                 idempotencyKey?: string | undefined;
                 version?: string | undefined;
+                region?: string | undefined;
                 ttl?: string | undefined;
                 batchId?: string | undefined;
                 finishedAt?: Date | undefined;
                 delayedUntil?: Date | undefined;
                 expiredAt?: Date | undefined;
+                taskKind?: string | undefined;
             } | undefined;
             children?: {
                 status: "PENDING_VERSION" | "QUEUED" | "DEQUEUED" | "EXECUTING" | "WAITING" | "COMPLETED" | "CANCELED" | "FAILED" | "CRASHED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED" | "TIMED_OUT";
@@ -199,11 +214,13 @@ export declare class ApiClient {
                 startedAt?: Date | undefined;
                 idempotencyKey?: string | undefined;
                 version?: string | undefined;
+                region?: string | undefined;
                 ttl?: string | undefined;
                 batchId?: string | undefined;
                 finishedAt?: Date | undefined;
                 delayedUntil?: Date | undefined;
                 expiredAt?: Date | undefined;
+                taskKind?: string | undefined;
             }[] | undefined;
         };
         depth: number;
@@ -227,6 +244,7 @@ export declare class ApiClient {
         startedAt?: Date | undefined;
         idempotencyKey?: string | undefined;
         version?: string | undefined;
+        region?: string | undefined;
         output?: any;
         ttl?: string | undefined;
         schedule?: {
@@ -245,6 +263,7 @@ export declare class ApiClient {
         finishedAt?: Date | undefined;
         delayedUntil?: Date | undefined;
         expiredAt?: Date | undefined;
+        taskKind?: string | undefined;
     }>;
     retrieveRunTrace(runId: string, requestOptions?: ZodFetchOptions): ApiPromise<{
         trace: {
@@ -360,11 +379,13 @@ export declare class ApiClient {
                 startedAt?: Date | undefined;
                 idempotencyKey?: string | undefined;
                 version?: string | undefined;
+                region?: string | undefined;
                 ttl?: string | undefined;
                 batchId?: string | undefined;
                 finishedAt?: Date | undefined;
                 delayedUntil?: Date | undefined;
                 expiredAt?: Date | undefined;
+                taskKind?: string | undefined;
             } | undefined;
             parent?: {
                 status: "PENDING_VERSION" | "QUEUED" | "DEQUEUED" | "EXECUTING" | "WAITING" | "COMPLETED" | "CANCELED" | "FAILED" | "CRASHED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED" | "TIMED_OUT";
@@ -390,11 +411,13 @@ export declare class ApiClient {
                 startedAt?: Date | undefined;
                 idempotencyKey?: string | undefined;
                 version?: string | undefined;
+                region?: string | undefined;
                 ttl?: string | undefined;
                 batchId?: string | undefined;
                 finishedAt?: Date | undefined;
                 delayedUntil?: Date | undefined;
                 expiredAt?: Date | undefined;
+                taskKind?: string | undefined;
             } | undefined;
             children?: {
                 status: "PENDING_VERSION" | "QUEUED" | "DEQUEUED" | "EXECUTING" | "WAITING" | "COMPLETED" | "CANCELED" | "FAILED" | "CRASHED" | "SYSTEM_FAILURE" | "DELAYED" | "EXPIRED" | "TIMED_OUT";
@@ -420,11 +443,13 @@ export declare class ApiClient {
                 startedAt?: Date | undefined;
                 idempotencyKey?: string | undefined;
                 version?: string | undefined;
+                region?: string | undefined;
                 ttl?: string | undefined;
                 batchId?: string | undefined;
                 finishedAt?: Date | undefined;
                 delayedUntil?: Date | undefined;
                 expiredAt?: Date | undefined;
+                taskKind?: string | undefined;
             }[] | undefined;
         };
         depth: number;
@@ -448,6 +473,7 @@ export declare class ApiClient {
         startedAt?: Date | undefined;
         idempotencyKey?: string | undefined;
         version?: string | undefined;
+        region?: string | undefined;
         output?: any;
         ttl?: string | undefined;
         schedule?: {
@@ -466,6 +492,7 @@ export declare class ApiClient {
         finishedAt?: Date | undefined;
         delayedUntil?: Date | undefined;
         expiredAt?: Date | undefined;
+        taskKind?: string | undefined;
     }>;
     listRunEvents(runId: string, requestOptions?: ZodFetchOptions): ApiPromise<any>;
     addTags(runId: string, body: AddTagsRequestBody, requestOptions?: ZodFetchOptions): ApiPromise<{
@@ -702,6 +729,165 @@ export declare class ApiClient {
     }, requestOptions?: ZodFetchOptions): ApiPromise<{
         success: boolean;
     }>;
+    createSession(body: CreateSessionRequestBody, requestOptions?: ZodFetchOptions): ApiPromise<{
+        type: string;
+        metadata: Record<string, unknown> | null;
+        id: string;
+        tags: string[];
+        createdAt: Date;
+        taskIdentifier: string;
+        externalId: string | null;
+        updatedAt: Date;
+        runId: string;
+        isCached: boolean;
+        expiresAt: Date | null;
+        closedAt: Date | null;
+        closedReason: string | null;
+        publicAccessToken: string;
+        triggerConfig?: {
+            basePayload: Record<string, unknown>;
+            tags?: string[] | undefined;
+            maxAttempts?: number | undefined;
+            maxDuration?: number | undefined;
+            region?: string | undefined;
+            queue?: string | undefined;
+            machine?: "micro" | "small-1x" | "small-2x" | "medium-1x" | "medium-2x" | "large-1x" | "large-2x" | undefined;
+            lockToVersion?: string | undefined;
+            idleTimeoutInSeconds?: number | undefined;
+        } | undefined;
+        currentRunId?: string | null | undefined;
+    }>;
+    retrieveSession(sessionIdOrExternalId: string, requestOptions?: ZodFetchOptions): ApiPromise<{
+        type: string;
+        metadata: Record<string, unknown> | null;
+        id: string;
+        tags: string[];
+        createdAt: Date;
+        taskIdentifier: string;
+        externalId: string | null;
+        updatedAt: Date;
+        expiresAt: Date | null;
+        closedAt: Date | null;
+        closedReason: string | null;
+        triggerConfig?: {
+            basePayload: Record<string, unknown>;
+            tags?: string[] | undefined;
+            maxAttempts?: number | undefined;
+            maxDuration?: number | undefined;
+            region?: string | undefined;
+            queue?: string | undefined;
+            machine?: "micro" | "small-1x" | "small-2x" | "medium-1x" | "medium-2x" | "large-1x" | "large-2x" | undefined;
+            lockToVersion?: string | undefined;
+            idleTimeoutInSeconds?: number | undefined;
+        } | undefined;
+        currentRunId?: string | null | undefined;
+    }>;
+    updateSession(sessionIdOrExternalId: string, body: UpdateSessionRequestBody, requestOptions?: ZodFetchOptions): ApiPromise<{
+        type: string;
+        metadata: Record<string, unknown> | null;
+        id: string;
+        tags: string[];
+        createdAt: Date;
+        taskIdentifier: string;
+        externalId: string | null;
+        updatedAt: Date;
+        expiresAt: Date | null;
+        closedAt: Date | null;
+        closedReason: string | null;
+        triggerConfig?: {
+            basePayload: Record<string, unknown>;
+            tags?: string[] | undefined;
+            maxAttempts?: number | undefined;
+            maxDuration?: number | undefined;
+            region?: string | undefined;
+            queue?: string | undefined;
+            machine?: "micro" | "small-1x" | "small-2x" | "medium-1x" | "medium-2x" | "large-1x" | "large-2x" | undefined;
+            lockToVersion?: string | undefined;
+            idleTimeoutInSeconds?: number | undefined;
+        } | undefined;
+        currentRunId?: string | null | undefined;
+    }>;
+    closeSession(sessionIdOrExternalId: string, body?: CloseSessionRequestBody, requestOptions?: ZodFetchOptions): ApiPromise<{
+        type: string;
+        metadata: Record<string, unknown> | null;
+        id: string;
+        tags: string[];
+        createdAt: Date;
+        taskIdentifier: string;
+        externalId: string | null;
+        updatedAt: Date;
+        expiresAt: Date | null;
+        closedAt: Date | null;
+        closedReason: string | null;
+        triggerConfig?: {
+            basePayload: Record<string, unknown>;
+            tags?: string[] | undefined;
+            maxAttempts?: number | undefined;
+            maxDuration?: number | undefined;
+            region?: string | undefined;
+            queue?: string | undefined;
+            machine?: "micro" | "small-1x" | "small-2x" | "medium-1x" | "medium-2x" | "large-1x" | "large-2x" | undefined;
+            lockToVersion?: string | undefined;
+            idleTimeoutInSeconds?: number | undefined;
+        } | undefined;
+        currentRunId?: string | null | undefined;
+    }>;
+    endAndContinueSession(sessionIdOrExternalId: string, body: EndAndContinueSessionRequestBody, requestOptions?: ZodFetchOptions): ApiPromise<{
+        runId: string;
+        swapped: boolean;
+    }>;
+    listSessions(options?: ListSessionsOptions, requestOptions?: ZodFetchOptions): CursorPagePromise<typeof ListedSessionItem>;
+    initializeSessionStream(sessionIdOrExternalId: string, io: "out" | "in", requestOptions?: ZodFetchOptions): Promise<{
+        headers: {
+            [k: string]: string;
+        };
+        version: string;
+    }>;
+    appendToSessionStream<TBody extends BodyInit>(sessionIdOrExternalId: string, io: "out" | "in", part: TBody, requestOptions?: ZodFetchOptions): Promise<{
+        ok: boolean;
+        message?: string | undefined;
+    }>;
+    /**
+     * Non-SSE drain of a Session channel's tail. Returns whatever records
+     * exist after `afterEventId` (or from the head of the stream) and closes
+     * — `wait=0` semantics, no long-poll. Used by `replaySessionOutTail` at
+     * run boot, where the SSE long-poll's ~1s tax on empty streams is the
+     * dominant cost on every fresh chat.
+     *
+     * `afterEventId` is the same cursor format as the SSE Last-Event-ID
+     * (the S2 sequence number, stringified) — pass `lastOutEventId` from a
+     * persisted snapshot to resume.
+     */
+    readSessionStreamRecords(sessionIdOrExternalId: string, io: "out" | "in", options?: {
+        afterEventId?: string;
+        baseUrl?: string;
+    }): Promise<{
+        records: {
+            id: string;
+            seqNum: number;
+            data?: unknown;
+        }[];
+    }>;
+    /**
+     * Subscribe to SSE records on a Session channel. Reuses the same
+     * {@link SSEStreamSubscription} plumbing as `readStream` for run-scoped
+     * realtime streams — auto-retry, Last-Event-ID resume, abort-on-cancel.
+     */
+    subscribeToSessionStream<T = unknown>(sessionIdOrExternalId: string, io: "out" | "in", options?: {
+        signal?: AbortSignal;
+        baseUrl?: string;
+        timeoutInSeconds?: number;
+        onComplete?: () => void;
+        onError?: (error: Error) => void;
+        lastEventId?: string;
+        onPart?: (part: SSEStreamPart<T>) => void;
+        /**
+         * Fires when a `trigger-control` record arrives on the stream (e.g.
+         * `turn-complete`, `upgrade-required`). The control record is never
+         * enqueued into the consumer stream — handle the event here.
+         */
+        onControl?: (event: ControlEvent) => void;
+    }): Promise<AsyncIterableStream<T>>;
     waitForDuration(runId: string, body: WaitForDurationRequestBody, requestOptions?: ZodFetchOptions): Promise<{
         waitUntil: Date;
         waitpoint: {
@@ -907,6 +1093,23 @@ export declare class ApiClient {
         git?: Record<string, any> | undefined;
         deployedAt?: Date | undefined;
     }>>;
+    retrieveCurrentDeployment(requestOptions?: ZodFetchOptions): ApiPromise<{
+        status: "CANCELED" | "FAILED" | "TIMED_OUT" | "PENDING" | "BUILDING" | "DEPLOYING" | "DEPLOYED";
+        id: string;
+        createdAt: Date;
+        version: string;
+        shortCode: string;
+        runtime: string | null;
+        runtimeVersion: string | null;
+        error?: {
+            message: string;
+            name: string;
+            stack?: string | undefined;
+            stderr?: string | undefined;
+        } | undefined;
+        git?: Record<string, any> | undefined;
+        deployedAt?: Date | undefined;
+    }>;
     fetchStream<T>(runId: string, streamKey: string, options?: {
         signal?: AbortSignal;
         baseUrl?: string;
@@ -934,6 +1137,10 @@ export declare class ApiClient {
         isCached: boolean;
         waitpointId: string;
     }>;
+    createSessionStreamWaitpoint(runFriendlyId: string, body: CreateSessionStreamWaitpointRequestBody, requestOptions?: ZodFetchOptions): Promise<{
+        isCached: boolean;
+        waitpointId: string;
+    }>;
     generateJWTClaims(requestOptions?: ZodFetchOptions): Promise<Record<string, any>>;
     retrieveBatch(batchId: string, requestOptions?: ZodFetchOptions): ApiPromise<{
         status: "COMPLETED" | "PENDING" | "PROCESSING" | "PARTIAL_FAILED" | "ABORTED";

package/dist/esm/v3/apiClient/index.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
 import { VERSION } from "../../version.js";
 import { generateJWT } from "../jwt.js";
-import { ApiDeploymentListResponseItem, AppendToStreamResponseBody, BatchTaskRunExecutionResult, BatchTriggerTaskV3Response, CanceledRunResponse, CompleteWaitpointTokenResponseBody, CreateBatchResponse, CreateInputStreamWaitpointResponseBody, CreateStreamResponseBody, CreateUploadPayloadUrlResponseBody, CreateWaitpointTokenResponseBody, DeletedScheduleObject, EnvironmentVariableResponseBody, EnvironmentVariableWithSecret, ListRunResponseItem, QueueItem, QueryExecuteResponseBody, QuerySchemaResponseBody, ListDashboardsResponseBody, ReplayRunResponse, ResetIdempotencyKeyResponse, RetrieveBatchV2Response, ResolvePromptResponseBody, ListPromptsResponseBody, ListPromptVersionsResponseBody, PromptOkResponseBody, PromptOverrideCreatedResponseBody, RetrieveRunResponse, RetrieveRunTraceResponseBody, RetrieveSpanDetailResponseBody, ScheduleObject, SendInputStreamResponseBody, StreamBatchItemsResponse, TaskRunExecutionResult, TriggerTaskResponse, UpdateMetadataResponseBody, WaitForDurationResponseBody, WaitForWaitpointTokenResponseBody, WaitpointRetrieveTokenResponse, WaitpointTokenItem, } from "../schemas/index.js";
+import { ApiDeploymentListResponseItem, RetrieveCurrentDeploymentResponseBody, AppendToStreamResponseBody, BatchTaskRunExecutionResult, BatchTriggerTaskV3Response, CanceledRunResponse, CompleteWaitpointTokenResponseBody, CreatedSessionResponseBody, EndAndContinueSessionResponseBody, ListedSessionItem, RetrieveSessionResponseBody, CreateBatchResponse, CreateInputStreamWaitpointResponseBody, CreateSessionStreamWaitpointResponseBody, CreateStreamResponseBody, CreateUploadPayloadUrlResponseBody, CreateWaitpointTokenResponseBody, DeletedScheduleObject, EnvironmentVariableResponseBody, EnvironmentVariableWithSecret, ListRunResponseItem, QueueItem, QueryExecuteResponseBody, QuerySchemaResponseBody, ListDashboardsResponseBody, ReplayRunResponse, ResetIdempotencyKeyResponse, RetrieveBatchV2Response, ResolvePromptResponseBody, ListPromptsResponseBody, ListPromptVersionsResponseBody, PromptOkResponseBody, PromptOverrideCreatedResponseBody, RetrieveRunResponse, RetrieveRunTraceResponseBody, RetrieveSpanDetailResponseBody, ScheduleObject, SendInputStreamResponseBody, StreamBatchItemsResponse, TaskRunExecutionResult, ReadSessionStreamRecordsResponseBody, TriggerTaskResponse, UpdateMetadataResponseBody, WaitForDurationResponseBody, WaitForWaitpointTokenResponseBody, WaitpointRetrieveTokenResponse, WaitpointTokenItem, } from "../schemas/index.js";
 import { taskContext } from "../task-context-api.js";
 import { isRequestOptions, zodfetch, zodfetchCursorPage, zodfetchOffsetLimitPage, } from "./core.js";
 import { ApiConnectionError, ApiError, BatchNotSealedError } from "./errors.js";
 import { calculateNextRetryDelay } from "../utils/retries.js";
 import { SSEStreamSubscriptionFactory, SSEStreamSubscription, runShapeStream, } from "./runStream.js";
+import { controlSubtype, } from "../sessionStreams/wireProtocol.js";
 import { API_VERSION, API_VERSION_HEADER_NAME } from "./version.js";
 import { getEnvVar } from "../utils/getEnv.js";
 const DEFAULT_ZOD_FETCH_OPTIONS = {
@@ -309,6 +310,20 @@ export class ApiClient {
             headers: this.#getHeaders(false),
         }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
     }
+    /** Presigned PUT URL for a `chat.agent` session snapshot. */
+    createChatSnapshotUploadUrl(sessionId, requestOptions) {
+        return zodfetch(CreateUploadPayloadUrlResponseBody, `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/snapshot-url`, {
+            method: "PUT",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    /** Presigned GET URL for a `chat.agent` session snapshot. */
+    getChatSnapshotUrl(sessionId, requestOptions) {
+        return zodfetch(CreateUploadPayloadUrlResponseBody, `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/snapshot-url`, {
+            method: "GET",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
     retrieveRun(runId, requestOptions) {
         return zodfetch(RetrieveRunResponse, `${this.baseUrl}/api/v3/runs/${runId}`, {
             method: "GET",
@@ -565,6 +580,152 @@ export class ApiClient {
             headers: this.#getHeaders(false),
         }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
     }
+    // ========================================================================
+    // Sessions
+    // ========================================================================
+    createSession(body, requestOptions) {
+        return zodfetch(CreatedSessionResponseBody, `${this.baseUrl}/api/v1/sessions`, {
+            method: "POST",
+            headers: this.#getHeaders(false),
+            body: JSON.stringify(body),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    retrieveSession(sessionIdOrExternalId, requestOptions) {
+        return zodfetch(RetrieveSessionResponseBody, `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}`, {
+            method: "GET",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    updateSession(sessionIdOrExternalId, body, requestOptions) {
+        return zodfetch(RetrieveSessionResponseBody, `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}`, {
+            method: "PATCH",
+            headers: this.#getHeaders(false),
+            body: JSON.stringify(body),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    closeSession(sessionIdOrExternalId, body, requestOptions) {
+        return zodfetch(RetrieveSessionResponseBody, `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}/close`, {
+            method: "POST",
+            headers: this.#getHeaders(false),
+            body: JSON.stringify(body ?? {}),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    endAndContinueSession(sessionIdOrExternalId, body, requestOptions) {
+        return zodfetch(EndAndContinueSessionResponseBody, `${this.baseUrl}/api/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}/end-and-continue`, {
+            method: "POST",
+            headers: this.#getHeaders(false),
+            body: JSON.stringify(body),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    listSessions(options, requestOptions) {
+        const searchParams = createSearchQueryForListSessions(options);
+        return zodfetchCursorPage(ListedSessionItem, `${this.baseUrl}/api/v1/sessions`, {
+            query: searchParams,
+            limit: options?.limit,
+            after: options?.after,
+            before: options?.before,
+        }, {
+            method: "GET",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    // ========================================================================
+    // Session realtime channels
+    // ========================================================================
+    async initializeSessionStream(sessionIdOrExternalId, io, requestOptions) {
+        // The server returns S2 credentials in response headers alongside a tiny
+        // JSON body with the realtime version. Follow the same shape as
+        // `createStream` so downstream clients can feed them into
+        // `StreamsWriterV2`.
+        return zodfetch(CreateStreamResponseBody, `${this.baseUrl}/realtime/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}/${io}`, {
+            method: "PUT",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions))
+            .withResponse()
+            .then(({ data, response }) => ({
+            ...data,
+            headers: Object.fromEntries(response.headers.entries()),
+        }));
+    }
+    async appendToSessionStream(sessionIdOrExternalId, io, part, requestOptions) {
+        return zodfetch(AppendToStreamResponseBody, `${this.baseUrl}/realtime/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}/${io}/append`, {
+            method: "POST",
+            headers: this.#getHeaders(false),
+            body: part,
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
+    /**
+     * Non-SSE drain of a Session channel's tail. Returns whatever records
+     * exist after `afterEventId` (or from the head of the stream) and closes
+     * — `wait=0` semantics, no long-poll. Used by `replaySessionOutTail` at
+     * run boot, where the SSE long-poll's ~1s tax on empty streams is the
+     * dominant cost on every fresh chat.
+     *
+     * `afterEventId` is the same cursor format as the SSE Last-Event-ID
+     * (the S2 sequence number, stringified) — pass `lastOutEventId` from a
+     * persisted snapshot to resume.
+     */
+    async readSessionStreamRecords(sessionIdOrExternalId, io, options) {
+        const qs = new URLSearchParams();
+        if (options?.afterEventId !== undefined) {
+            qs.set("afterEventId", options.afterEventId);
+        }
+        const url = `${options?.baseUrl ?? this.baseUrl}/realtime/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}/${io}/records${qs.toString() ? `?${qs.toString()}` : ""}`;
+        return zodfetch(ReadSessionStreamRecordsResponseBody, url, {
+            method: "GET",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, undefined));
+    }
+    /**
+     * Subscribe to SSE records on a Session channel. Reuses the same
+     * {@link SSEStreamSubscription} plumbing as `readStream` for run-scoped
+     * realtime streams — auto-retry, Last-Event-ID resume, abort-on-cancel.
+     */
+    async subscribeToSessionStream(sessionIdOrExternalId, io, options) {
+        const url = `${options?.baseUrl ?? this.baseUrl}/realtime/v1/sessions/${encodeURIComponent(sessionIdOrExternalId)}/${io}`;
+        const subscription = new SSEStreamSubscription(url, {
+            headers: this.getHeaders(),
+            signal: options?.signal,
+            onComplete: options?.onComplete,
+            onError: options?.onError,
+            timeoutInSeconds: options?.timeoutInSeconds,
+            lastEventId: options?.lastEventId,
+        });
+        const stream = await subscription.subscribe();
+        const onPart = options?.onPart;
+        const onControl = options?.onControl;
+        return stream.pipeThrough(new TransformStream({
+            transform(part, controller) {
+                // Always surface the raw part via onPart so cursor tracking
+                // (lastSeqNum, lastEventId) stays correct for both data and
+                // control records.
+                onPart?.(part);
+                // Trigger control record — route to onControl, never enqueue.
+                const subtype = controlSubtype(part.headers);
+                if (subtype) {
+                    // `part.id` is the S2 seq_num in decimal string form.
+                    // `parseInt` returns NaN if S2 ever surfaces a non-numeric
+                    // id (shouldn't happen, but `|| 0` would mask it as a real
+                    // seq 0). Drop the malformed event rather than fire
+                    // `onControl` with a misleading cursor — callers like
+                    // `findLatestSessionInCursor` and the dashboard rely on the
+                    // seqNum being meaningful for resume.
+                    const parsedSeqNum = Number.parseInt(part.id, 10);
+                    if (!Number.isFinite(parsedSeqNum)) {
+                        return;
+                    }
+                    onControl?.({
+                        subtype,
+                        headers: part.headers ?? [],
+                        seqNum: parsedSeqNum,
+                        timestamp: part.timestamp,
+                    });
+                    return;
+                }
+                controller.enqueue(part.chunk);
+            },
+        }));
+    }
     async waitForDuration(runId, body, requestOptions) {
         return zodfetch(WaitForDurationResponseBody, `${this.baseUrl}/engine/v1/runs/${runId}/wait/duration`, {
             method: "POST",
@@ -702,6 +863,12 @@ export class ApiClient {
             headers: this.#getHeaders(false),
         }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
     }
+    retrieveCurrentDeployment(requestOptions) {
+        return zodfetch(RetrieveCurrentDeploymentResponseBody, `${this.baseUrl}/api/v1/deployments/current`, {
+            method: "GET",
+            headers: this.#getHeaders(false),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
     async fetchStream(runId, streamKey, options) {
         const streamFactory = new SSEStreamSubscriptionFactory(options?.baseUrl ?? this.baseUrl, {
             headers: this.getHeaders(),
@@ -757,6 +924,13 @@ export class ApiClient {
             body: JSON.stringify(body),
         }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
     }
+    async createSessionStreamWaitpoint(runFriendlyId, body, requestOptions) {
+        return zodfetch(CreateSessionStreamWaitpointResponseBody, `${this.baseUrl}/api/v1/runs/${runFriendlyId}/session-streams/wait`, {
+            method: "POST",
+            headers: this.#getHeaders(false),
+            body: JSON.stringify(body),
+        }, mergeRequestOptions(this.defaultRequestOptions, requestOptions));
+    }
     async generateJWTClaims(requestOptions) {
         return zodfetch(z.record(z.any()), `${this.baseUrl}/api/v1/auth/jwt/claims`, {
             method: "POST",
@@ -948,6 +1122,9 @@ function createSearchQueryForListRuns(query) {
         if (query.machine) {
             searchParams.append("filter[machine]", Array.isArray(query.machine) ? query.machine.join(",") : query.machine);
         }
+        if (query.region) {
+            searchParams.append("filter[region]", Array.isArray(query.region) ? query.region.join(",") : query.region);
+        }
     }
     return searchParams;
 }
@@ -957,6 +1134,33 @@ function queueNameFromQueueTypeName(queue) {
     }
     return queue.name;
 }
+function createSearchQueryForListSessions(options) {
+    const searchParams = new URLSearchParams();
+    if (!options)
+        return searchParams;
+    const appendMany = (name, value) => {
+        if (value === undefined)
+            return;
+        searchParams.append(name, Array.isArray(value) ? value.join(",") : value);
+    };
+    appendMany("filter[type]", options.type);
+    appendMany("filter[tags]", options.tag);
+    appendMany("filter[taskIdentifier]", options.taskIdentifier);
+    if (options.externalId) {
+        searchParams.append("filter[externalId]", options.externalId);
+    }
+    appendMany("filter[status]", options.status);
+    if (options.period) {
+        searchParams.append("filter[createdAt][period]", options.period);
+    }
+    if (options.from !== undefined) {
+        searchParams.append("filter[createdAt][from]", options.from instanceof Date ? options.from.getTime().toString() : options.from.toString());
+    }
+    if (options.to !== undefined) {
+        searchParams.append("filter[createdAt][to]", options.to instanceof Date ? options.to.getTime().toString() : options.to.toString());
+    }
+    return searchParams;
+}
 function createSearchQueryForListWaitpointTokens(query) {
     const searchParams = new URLSearchParams();
     if (query) {