@trigger.dev/sdk 4.4.6 → 4.5.0-rc.0

package/dist/esm/v3/sessions.d.ts

@@ -0,0 +1,228 @@
+import type { ApiPromise, ApiRequestOptions, AsyncIterableStream, CloseSessionRequestBody, CreatedSessionResponseBody, CreateSessionRequestBody, InputStreamOnceOptions, InputStreamWaitOptions, InputStreamWaitWithIdleTimeoutOptions, ListSessionsOptions, ListedSessionItem, PipeStreamOptions, PipeStreamResult, RetrieveSessionResponseBody, UpdateSessionRequestBody, WriterStreamOptions } from "@trigger.dev/core/v3";
+import { CursorPagePromise, InputStreamOncePromise, ManualWaitpointPromise } from "@trigger.dev/core/v3";
+import type { ControlEvent, StreamWriteResult } from "@trigger.dev/core/v3";
+export type { CreatedSessionResponseBody, CreateSessionRequestBody, CloseSessionRequestBody, ListSessionsOptions, ListedSessionItem, RetrieveSessionResponseBody, UpdateSessionRequestBody, };
+export declare const sessions: {
+    start: typeof startSession;
+    retrieve: typeof retrieveSession;
+    update: typeof updateSession;
+    close: typeof closeSession;
+    list: typeof listSessions;
+    open: typeof open;
+};
+type SessionOpenImpl = (sessionIdOrExternalId: string) => SessionHandle;
+export declare function __setSessionOpenImplForTests(impl: SessionOpenImpl | undefined): void;
+type SessionStartImpl = (body: CreateSessionRequestBody) => Promise<CreatedSessionResponseBody> | CreatedSessionResponseBody;
+export declare function __setSessionStartImplForTests(impl: SessionStartImpl | undefined): void;
+/**
+ * Start a {@link Session} — a durable, task-bound, bidirectional I/O
+ * primitive. The server creates the row (idempotent on `externalId`)
+ * and triggers the first run from `triggerConfig` in one round-trip.
+ * Returns the new run's id and a session-scoped public access token
+ * for browser-side use against `.in/append`, `.out` SSE, and
+ * `end-and-continue`.
+ *
+ * If a session with the same `(env, externalId)` already exists,
+ * returns the existing row plus the live (or freshly re-triggered) run.
+ * Two browser tabs of the same chat converge to one session.
+ */
+declare function startSession(body: CreateSessionRequestBody, requestOptions?: ApiRequestOptions): ApiPromise<CreatedSessionResponseBody>;
+/**
+ * Retrieve a Session by `friendlyId` (`session_*`) or user-supplied
+ * `externalId`. The server disambiguates via the `session_` prefix.
+ */
+declare function retrieveSession(sessionIdOrExternalId: string, requestOptions?: ApiRequestOptions): ApiPromise<RetrieveSessionResponseBody>;
+/** Update mutable fields on a Session (tags, metadata, externalId). */
+declare function updateSession(sessionIdOrExternalId: string, body: UpdateSessionRequestBody, requestOptions?: ApiRequestOptions): ApiPromise<RetrieveSessionResponseBody>;
+/** Mark a Session as closed (terminal, idempotent). */
+declare function closeSession(sessionIdOrExternalId: string, body?: CloseSessionRequestBody, requestOptions?: ApiRequestOptions): ApiPromise<RetrieveSessionResponseBody>;
+/**
+ * List Sessions in the current environment with filters + cursor pagination.
+ * Returns a {@link CursorPagePromise} so callers can iterate pages with
+ * `for await`.
+ */
+declare function listSessions(options?: ListSessionsOptions, requestOptions?: ApiRequestOptions): CursorPagePromise<typeof ListedSessionItem>;
+/**
+ * Open a lightweight handle to a Session's realtime channels. Does not
+ * perform a network call on its own — each channel method hits the
+ * corresponding realtime endpoint.
+ */
+declare function open(sessionIdOrExternalId: string): SessionHandle;
+export declare class SessionHandle {
+    readonly id: string;
+    /**
+     * Producer-to-consumer channel: the task writes records; external
+     * clients read them. Mirrors `streams.define` — `append` / `pipe` /
+     * `writer` / `read`.
+     */
+    readonly out: SessionOutputChannel;
+    /**
+     * Consumer-to-producer channel: external clients call `.send()`; the
+     * task consumes via `.on` / `.once` / `.peek` / `.wait` /
+     * `.waitWithIdleTimeout`. Mirrors `streams.input` but keyed on the
+     * session so a conversation can survive across run boundaries.
+     */
+    readonly in: SessionInputChannel;
+    constructor(id: string, overrides?: {
+        in?: SessionInputChannel;
+        out?: SessionOutputChannel;
+    });
+}
+/**
+ * Options accepted by {@link SessionOutputChannel.pipe}. Session-scoped,
+ * so it omits the `target` field (self/parent/root/runId) that run-scoped
+ * {@link PipeStreamOptions} uses — the session is the target.
+ */
+export type SessionPipeStreamOptions = Omit<PipeStreamOptions, "target">;
+/**
+ * The `.out` side of a Session's bidirectional channel pair. Mirrors the
+ * consume-side of {@link streams.define}: `pipe` / `writer` / `append`
+ * for the task to produce records, `read` for external clients to
+ * consume via SSE. S2 credentials for direct writes are fetched
+ * internally by `pipe`/`writer` — there's no public `initialize()`.
+ */
+export declare class SessionOutputChannel {
+    #private;
+    readonly sessionId: string;
+    constructor(sessionId: string);
+    /**
+     * Append a single record. Routes through {@link writer} internally so
+     * subscribers receive the same parsed-object shape as multi-record
+     * writes — the server-side append endpoint wraps the body in a string,
+     * which would give SSE consumers a JSON-string instead of an object.
+     * Mirrors how `streams.define.append` delegates to `streams.writer`.
+     */
+    append<T>(value: T, options?: SessionPipeStreamOptions): Promise<void>;
+    /**
+     * Pipe an `AsyncIterable` / `ReadableStream` directly to S2. Fetches
+     * session S2 credentials internally and streams through
+     * {@link SessionStreamInstance}. Parallel to {@link streams.pipe} but
+     * session-scoped — no `target` option because the session is the target.
+     */
+    pipe<T>(value: AsyncIterable<T> | ReadableStream<T>, options?: SessionPipeStreamOptions): PipeStreamResult<T>;
+    /**
+     * Mirror of {@link streams.writer}: runs `execute({ write, merge })`
+     * against an in-memory queue whose records are piped to S2. Returns
+     * `{ stream, waitUntilComplete }` so callers can observe the local
+     * stream and await completion. Span is collapsible via `options.spanName`
+     * / `options.collapsed`.
+     */
+    writer<T>(options: WriterStreamOptions<T>): PipeStreamResult<T>;
+    /**
+     * Subscribe to SSE records on `.out`. Returns an async-iterable stream —
+     * auto-retry, Last-Event-ID resume, and abort propagation come from the
+     * shared {@link SSEStreamSubscription} plumbing used by run-scoped
+     * realtime streams.
+     */
+    read<T = unknown>(options?: SessionSubscribeOptions<T>): Promise<AsyncIterableStream<T>>;
+    /**
+     * Write a single Trigger control record to `.out`. The record carries a
+     * `trigger-control` header valued with `subtype` plus any sibling
+     * `extraHeaders`; the body is empty. Control records are filtered out of
+     * the consumer-facing chunk stream by the SDK transport — readers route
+     * them via the `onControl` callback instead.
+     *
+     * The returned `lastEventId` is the S2 seq_num of the written record,
+     * useful for trim chains (e.g. trim back to the previous turn-complete).
+     */
+    writeControl(subtype: string, extraHeaders?: ReadonlyArray<readonly [string, string]>): Promise<StreamWriteResult>;
+    /**
+     * Append an S2 `trim` command record to `.out`. Records with seq_num
+     * less than `earliestSeqNum` are eventually removed from the stream.
+     *
+     * Idempotent and monotonic at S2's layer (`max(existing, min(provided,
+     * current_tail))`) — backward trims are silently no-ops for deletion
+     * but still consume a seq_num. Used by `chat.agent`'s turn loop to
+     * keep `session.out` bounded to roughly one turn at steady state.
+     */
+    trimTo(earliestSeqNum: number): Promise<void>;
+}
+/**
+ * The `.in` side of a Session's bidirectional channel pair. Mirrors
+ * {@link streams.input} — consumer-side primitives for the task
+ * (`on`/`once`/`peek`/`wait`/`waitWithIdleTimeout`) plus `send` for
+ * external clients. Keyed on the session rather than the run so a
+ * conversation can survive across run boundaries.
+ */
+export declare class SessionInputChannel {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+    /**
+     * Send a single record to the channel. Called by external clients
+     * (browser, server action, another task) producing input for the run.
+     * Matches {@link streams.input.send} but session-scoped — the session
+     * is the address, no `runId` required.
+     */
+    send(value: unknown, requestOptions?: ApiRequestOptions): Promise<void>;
+    /**
+     * Register a handler that fires for every record landing on `.in`.
+     * Handlers are flushed with any buffered records on attach and cleaned
+     * up automatically when the task run completes. Returns `{ off }` to
+     * unsubscribe early.
+     */
+    on<T = unknown>(handler: (data: T) => void | Promise<void>): {
+        off: () => void;
+    };
+    /**
+     * Wait for the next record on `.in` without suspending the run.
+     * Returns `{ ok: true, output }` on arrival or `{ ok: false, error }`
+     * when the timeout fires. Chain `.unwrap()` to get the data directly.
+     */
+    once<T = unknown>(options?: InputStreamOnceOptions): InputStreamOncePromise<T>;
+    /** Non-blocking peek at the head of the `.in` buffer. */
+    peek<T = unknown>(): T | undefined;
+    /**
+     * The highest S2 sequence number of any record this channel has
+     * delivered to a `once()` / `wait()` consumer (or had shifted off its
+     * buffer into one). Distinct from "last received" — buffered-but-not-
+     * yet-consumed records don't count.
+     *
+     * Used by `chat.agent` to persist the `.in` resume cursor on each
+     * `turn-complete` control record, so the next worker boot can subscribe
+     * past already-processed user messages.
+     */
+    lastDispatchedSeqNum(): number | undefined;
+    /**
+     * Suspend the current run until the next record arrives on `.in`.
+     * Unlike {@link once}, `wait()` frees compute while blocked — the
+     * run-engine waitpoint holds the run until the session append handler
+     * fires it. Only callable from inside `task.run()`.
+     */
+    wait<T = unknown>(options?: InputStreamWaitOptions): ManualWaitpointPromise<T>;
+    /**
+     * Wait for a record with an idle-then-suspend strategy. Keeps the run
+     * active (using compute) for `idleTimeoutInSeconds`, then suspends via
+     * {@link wait} if nothing arrives. If a record arrives during the idle
+     * phase the run responds without suspending.
+     */
+    waitWithIdleTimeout<T = unknown>(options: InputStreamWaitWithIdleTimeoutOptions): Promise<{
+        ok: true;
+        output: T;
+    } | {
+        ok: false;
+        error?: Error;
+    }>;
+}
+export type SessionSubscribeOptions<T = unknown> = {
+    signal?: AbortSignal;
+    lastEventId?: string | number;
+    /** Timeout in seconds for the underlying long-poll (max 600). */
+    timeoutInSeconds?: number;
+    /** Called for each SSE event with the full event metadata (id, timestamp). */
+    onPart?: (part: {
+        id: string;
+        chunk: T;
+        timestamp: number;
+    }) => void;
+    /**
+     * Called when a `trigger-control` record arrives on the stream (e.g.
+     * `turn-complete`, `upgrade-required`). Control records are filtered
+     * out of the consumer chunk stream — handle them here. See
+     * `docs/ai-chat/client-protocol.mdx` for the wire shape.
+     */
+    onControl?: (event: ControlEvent) => void;
+    /** Called when the server signals end-of-stream. */
+    onComplete?: () => void;
+    /** Called on unrecoverable errors after the retry budget is exhausted. */
+    onError?: (error: Error) => void;
+};