@trigger.dev/core 0.0.0-buffer-fix-20231206151546 → 0.0.0-bun-prerelease-20260909132648

package/dist/commonjs/v3/sessionStreams/router.js

@@ -0,0 +1,402 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionChannelRouter = void 0;
+/**
+ * One route's live state: its queue of records nobody has taken yet, the
+ * consumers waiting for the next one, and any attached push handlers.
+ *
+ * An `at-arrival` route never fills `queue`; a route that is not `replayable`
+ * fills it but is skipped when the floor is computed.
+ */
+class RouteState {
+    route;
+    queue = [];
+    waiters = [];
+    handlers = new Set();
+    observers = new Set();
+    constructor(route) {
+        this.route = route;
+    }
+    /**
+     * Lowest sequence a *later boot* would still have to recover. A route that
+     * is not replayable never holds anything back, however much it has queued.
+     */
+    earliestUnrecovered() {
+        if (!this.route.replayable)
+            return undefined;
+        return this.queue.length > 0 ? this.queue[0].seqNum : undefined;
+    }
+}
+/**
+ * Reads one session channel and gives every record exactly one destination.
+ *
+ * The channel carries records for several independent consumers whose delivery
+ * needs differ: a message must be delivered eventually and so can lag
+ * arbitrarily far behind the newest record, while a stop only means anything to
+ * the turn that is live when it lands. Tracking that with a single scalar
+ * cursor is not possible — the true state is always "control applied through
+ * X, message Y still owed" — so the router tracks it per route and derives the
+ * published numbers from route state:
+ *
+ * - the resume floor is held back only by records a later boot would still have
+ *   to recover, which is exactly the queued records on replayable routes;
+ * - a record whose route has declared it not replayable is never re-applied
+ *   after a resume, because the route said a later boot has no use for it;
+ * - a record with no route is terminal by classification, so it never enters a
+ *   queue and cannot park at the head of one.
+ *
+ * Those three properties are what previously needed a cursor-barrier
+ * predicate, a drop predicate with a second published header, and a
+ * discard-the-unclaimed drain respectively.
+ */
+class SessionChannelRouter {
+    table;
+    #routes = new Map();
+    #kindToRoute = new Map();
+    #highestSeq;
+    #resumeFrom;
+    #appliedThrough;
+    #onDrop;
+    constructor(table, options) {
+        this.table = table;
+        for (const route of table.routes) {
+            if (this.#routes.has(route.name)) {
+                throw new Error(`Duplicate route name "${route.name}" in session route table`);
+            }
+            if (route.delivery === "at-arrival" && route.replayable) {
+                throw new Error(`Route "${route.name}" is at-arrival and replayable, which cannot both hold: a record discarded because nobody was listening cannot also be recovered later`);
+            }
+            this.#routes.set(route.name, new RouteState(route));
+            for (const kind of route.kinds) {
+                const existing = this.#kindToRoute.get(kind);
+                if (existing) {
+                    throw new Error(`Kind "${kind}" is claimed by both "${existing}" and "${route.name}" in session route table`);
+                }
+                this.#kindToRoute.set(kind, route.name);
+            }
+        }
+        this.#onDrop = options?.onDrop;
+    }
+    /**
+     * Seed the router from a previous run's turn boundary.
+     *
+     * An absent `appliedThrough` falls back to the floor, which leaves anything
+     * above the floor treated as live. A caller resuming a boundary that predates
+     * the published replay window should resolve the window from the channel
+     * instead, so it covers everything already there at boot: a missed stop is
+     * recoverable, while a stop applied to the wrong turn kills a live answer.
+     */
+    restore(checkpoint) {
+        this.#resumeFrom = checkpoint.resumeFrom;
+        this.#appliedThrough = checkpoint.appliedThrough ?? checkpoint.resumeFrom;
+        if (this.#resumeFrom !== undefined) {
+            this.#highestSeq = this.#resumeFrom;
+        }
+    }
+    /** Where a boot should subscribe from: just past this sequence. */
+    resumeFrom() {
+        return this.#resumeFrom;
+    }
+    /**
+     * Classify one record and act on it. The record's destination is decided
+     * here, once, and never by whichever consumer happens to be waiting.
+     *
+     * Queued routes serve a waiting consumer before a push handler, so a handler
+     * can never take a record out from under a consumer that is actively awaiting
+     * one. A record handed straight to either never enters the queue, so it never
+     * holds the floor back.
+     */
+    ingest(record) {
+        if (Number.isFinite(record.seqNum)) {
+            if (this.#highestSeq === undefined || record.seqNum > this.#highestSeq) {
+                this.#highestSeq = record.seqNum;
+            }
+        }
+        const kind = this.#kindOf(record.data);
+        if (kind === undefined) {
+            return this.#drop(record, "malformed");
+        }
+        const routeName = this.#kindToRoute.get(kind);
+        const state = routeName ? this.#routes.get(routeName) : undefined;
+        if (!state || !routeName) {
+            return this.#drop(record, "unroutable");
+        }
+        if (!state.route.replayable &&
+            this.#appliedThrough !== undefined &&
+            record.seqNum <= this.#appliedThrough) {
+            return this.#drop(record, "replayed", routeName);
+        }
+        if (state.route.delivery === "at-arrival" &&
+            state.handlers.size === 0 &&
+            state.waiters.length === 0) {
+            return this.#drop(record, "no-handler", routeName);
+        }
+        for (const observer of state.observers) {
+            try {
+                observer(record);
+            }
+            catch {
+                void 0;
+            }
+        }
+        const waiter = state.waiters.shift();
+        if (waiter) {
+            if (waiter.timer)
+                clearTimeout(waiter.timer);
+            waiter.resolve(record);
+            return { action: "deliver", route: routeName };
+        }
+        if (state.handlers.size > 0) {
+            this.#invokeHandlers(state, record);
+            return { action: "deliver", route: routeName };
+        }
+        state.queue.push(record);
+        return { action: "queue", route: routeName };
+    }
+    #kindOf(data) {
+        try {
+            const kind = this.table.kindOf(data);
+            return typeof kind === "string" && kind.length > 0 ? kind : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #drop(record, reason, route) {
+        try {
+            this.#onDrop?.(record, reason, route);
+        }
+        catch {
+            void 0;
+        }
+        return { action: "drop", route, reason };
+    }
+    #invokeHandlers(state, record) {
+        for (const handler of state.handlers) {
+            try {
+                handler(record);
+            }
+            catch {
+                void 0;
+            }
+        }
+    }
+    /**
+     * The highest sequence that can be resumed past without losing anything.
+     *
+     * Held back below the earliest record still queued anywhere, because those
+     * are exactly the records a replay has to recover. Everything else the
+     * router has seen was terminally decided, so the floor is free to sit at the
+     * high water when every queue is empty.
+     */
+    resumeFloor() {
+        if (this.#highestSeq === undefined)
+            return undefined;
+        let earliestPending = Infinity;
+        for (const state of this.#routes.values()) {
+            const pending = state.earliestUnrecovered();
+            if (pending !== undefined)
+                earliestPending = Math.min(earliestPending, pending);
+        }
+        if (earliestPending === Infinity)
+            return this.#highestSeq;
+        const floor = Math.min(this.#highestSeq, earliestPending - 1);
+        return floor >= 0 ? floor : undefined;
+    }
+    /**
+     * The high water: highest sequence observed, never held back. Published as
+     * the end of the replay window so the next boot can tell a re-read
+     * `at-arrival` record from one arriving live.
+     */
+    appliedThrough() {
+        return this.#highestSeq;
+    }
+    /** Both published numbers for a turn boundary. */
+    checkpoint() {
+        return { resumeFrom: this.resumeFloor(), appliedThrough: this.appliedThrough() };
+    }
+    #stateOrThrow(name) {
+        const state = this.#routes.get(name);
+        if (!state)
+            throw new Error(`Unknown session route "${name}"`);
+        return state;
+    }
+    /**
+     * Attach a push handler. A `queued` route with a handler attached delivers
+     * straight to it instead of queueing; an `at-arrival` route discards records
+     * whenever no handler is attached.
+     *
+     * Attaching re-offers anything already queued, so a consumer that attaches
+     * after records have piled up still sees them in order.
+     */
+    on(name, handler) {
+        const state = this.#stateOrThrow(name);
+        state.handlers.add(handler);
+        if (state.queue.length > 0) {
+            const pending = state.queue.splice(0, state.queue.length);
+            for (const record of pending) {
+                try {
+                    handler(record);
+                }
+                catch {
+                    void 0;
+                }
+            }
+        }
+        return {
+            off: () => {
+                state.handlers.delete(handler);
+            },
+        };
+    }
+    /**
+     * Watch a route without consuming from it.
+     *
+     * Notification and consumption are separate concerns: an observer is told
+     * that a record arrived and the record still queues, so the resume floor
+     * stays held behind it until something actually takes it. A push handler
+     * registered with {@link on} is the opposite, and a record handed to one
+     * counts as terminally decided.
+     *
+     * Only meaningful on a replayable route. On an `at-arrival` route an observer
+     * would either have to count as a listener, which would stop an unconsumed
+     * record being discarded, or watch records it cannot affect, so it is
+     * rejected rather than given one of those two meanings.
+     *
+     * Records already queued are not re-offered: an observer reports arrivals
+     * from the moment it attaches, so re-offering would fire twice for a record
+     * that arrived before a later consumer attached.
+     */
+    observe(name, observer) {
+        const state = this.#stateOrThrow(name);
+        if (state.route.delivery === "at-arrival") {
+            throw new Error(`Route "${name}" is at-arrival, which cannot be observed: an observer must not decide whether a record is discarded, and cannot be offered one that already was`);
+        }
+        state.observers.add(observer);
+        return {
+            off: () => {
+                state.observers.delete(observer);
+            },
+        };
+    }
+    /**
+     * Remove one queued record, identified by sequence.
+     *
+     * For a consumer that decided to take a record it had only observed. Returns
+     * whether it was still queued, so a caller can tell a real take from a record
+     * something else had already consumed.
+     */
+    take(name, seqNum) {
+        const state = this.#stateOrThrow(name);
+        const index = state.queue.findIndex((record) => record.seqNum === seqNum);
+        if (index === -1)
+            return undefined;
+        return state.queue.splice(index, 1)[0];
+    }
+    /**
+     * Put a taken record back, in sequence order.
+     *
+     * For a consumer that claimed a record and then could not use it. Returning
+     * it leaves the route as though the claim never happened, so the record is
+     * delivered later and goes back to holding the resume floor. Without this a
+     * failed claim-then-use is indistinguishable from a delivery, and the record
+     * is lost.
+     */
+    untake(name, record) {
+        const state = this.#stateOrThrow(name);
+        if (state.queue.some((queued) => queued.seqNum === record.seqNum))
+            return;
+        const at = state.queue.findIndex((queued) => queued.seqNum > record.seqNum);
+        if (at === -1)
+            state.queue.push(record);
+        else
+            state.queue.splice(at, 0, record);
+    }
+    /** Whether an `at-arrival` route currently has anywhere to deliver. */
+    hasHandler(name) {
+        return this.#stateOrThrow(name).handlers.size > 0;
+    }
+    /**
+     * Take the next record on a route.
+     *
+     * `timeoutMs: 0` is a non-blocking take. Omitted means wait indefinitely.
+     * Resolves `undefined` on timeout. An `at-arrival` route delivers to a
+     * waiting caller when one is already parked here, which is what makes a pull
+     * consumer possible on such a route without weakening the discard rule.
+     */
+    next(name, options) {
+        const state = this.#stateOrThrow(name);
+        const queued = state.queue.shift();
+        if (queued)
+            return Promise.resolve(queued);
+        if (options?.timeoutMs === 0)
+            return Promise.resolve(undefined);
+        return new Promise((resolve) => {
+            const waiter = { resolve };
+            if (options?.timeoutMs !== undefined) {
+                waiter.timer = setTimeout(() => {
+                    const index = state.waiters.indexOf(waiter);
+                    if (index !== -1)
+                        state.waiters.splice(index, 1);
+                    resolve(undefined);
+                }, options.timeoutMs);
+            }
+            state.waiters.push(waiter);
+        });
+    }
+    /** Head of a route's queue without consuming it. */
+    peek(name) {
+        return this.#stateOrThrow(name).queue[0];
+    }
+    /**
+     * Whether a route has anything queued. Exact, because it reads that route's
+     * own queue rather than the head of a buffer shared with every other kind on
+     * the channel.
+     */
+    hasPending(name) {
+        return this.#stateOrThrow(name).queue.length > 0;
+    }
+    /** Number of records queued on a route. Diagnostic use. */
+    pendingCount(name) {
+        return this.#stateOrThrow(name).queue.length;
+    }
+    /**
+     * Discard whatever one route has queued and wake its waiters empty.
+     *
+     * Closes a consumer window: a route that is not replayable has nothing owed
+     * to a later boot, so once its window is over anything still queued on it is
+     * dead and must not sit at the head of the queue for the rest of the run.
+     */
+    clearRoute(name) {
+        const state = this.#stateOrThrow(name);
+        if (state.route.replayable) {
+            throw new Error(`Route "${name}" is replayable, so its queue cannot be cleared: anything queued on it is still owed to a later boot, and discarding it would lose records the resume floor is holding back`);
+        }
+        state.queue.length = 0;
+        for (const waiter of state.waiters) {
+            if (waiter.timer)
+                clearTimeout(waiter.timer);
+            waiter.resolve(undefined);
+        }
+        state.waiters.length = 0;
+    }
+    /** Drop every waiter and queue. Called between task executions. */
+    reset() {
+        for (const state of this.#routes.values()) {
+            state.queue.length = 0;
+            state.handlers.clear();
+            state.observers.clear();
+            for (const waiter of state.waiters) {
+                if (waiter.timer)
+                    clearTimeout(waiter.timer);
+                waiter.resolve(undefined);
+            }
+            state.waiters.length = 0;
+        }
+        this.#highestSeq = undefined;
+        this.#resumeFrom = undefined;
+        this.#appliedThrough = undefined;
+    }
+}
+exports.SessionChannelRouter = SessionChannelRouter;
+//# sourceMappingURL=router.js.map

package/dist/commonjs/v3/sessionStreams/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../../../src/v3/sessionStreams/router.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/v3/sessionStreams/types.d.ts

@@ -0,0 +1,111 @@
+import type { InputStreamOnceOptions } from "../realtimeStreams/types.js";
+import type { InputStreamOnceResult } from "../inputStreams/types.js";
+import { InputStreamOncePromise, InputStreamTimeoutError } from "../inputStreams/types.js";
+/**
+ * Re-export the run-scoped input stream once-promise machinery so callers
+ * depending on sessionStreams don't also need to import from inputStreams.
+ * Both APIs return the same shape.
+ */
+export { InputStreamOncePromise, InputStreamTimeoutError };
+export type { InputStreamOnceResult };
+export type SessionChannelIO = "out" | "in";
+/**
+ * One durable Session channel record.
+ *
+ * `id` is the append's stable idempotency key. `seqNum` is the record's
+ * monotonic S2 sequence within the Session channel. Both stay stable when
+ * the same record is delivered again after a reconnect.
+ */
+export type SessionStreamRecord<T = unknown> = Readonly<{
+    id: string;
+    seqNum: number;
+    data: T;
+}>;
+export type SessionStreamRecordPredicate = (record: SessionStreamRecord) => boolean;
+/**
+ * Manager for Session channel reads: a session-scoped parallel to
+ * {@link InputStreamManager} keyed on `(sessionId, io)` instead of
+ * `(runId, streamId)`. Used by {@link SessionChannel} to implement
+ * `.on` / `.once` / `.peek` / `.wait` / `.waitWithIdleTimeout`.
+ */
+export interface SessionStreamManager {
+    /**
+     * Register a handler that fires every time data arrives on the given channel.
+     *
+     * A handler that synchronously returns `true` CONSUMES the record: it is
+     * not buffered for a later `once()` and the committed-consume cursor
+     * advances past it. Any other return value (including a Promise) leaves
+     * the record available to other consumers. Kind-filtering facades return
+     * `true` for the kinds they own so the same record is never delivered
+     * twice — once to the handler and again via a buffer drain.
+     */
+    on(sessionId: string, io: SessionChannelIO, handler: (data: unknown) => void | boolean | Promise<void>, channel?: string): {
+        off: () => void;
+    };
+    /**
+     * Register a handler that receives the full record, including its sequence
+     * number. Same consume semantics as {@link on}.
+     */
+    onRecord?(sessionId: string, io: SessionChannelIO, handler: (record: SessionStreamRecord) => void | boolean | Promise<void>, channel?: string): {
+        off: () => void;
+    };
+    /** Wait for the next record on the given channel (buffered or live). */
+    once(sessionId: string, io: SessionChannelIO, options?: InputStreamOnceOptions, channel?: string): InputStreamOncePromise<unknown>;
+    /** Wait for and consume the next record, including its durable metadata. */
+    onceRecord?(sessionId: string, io: SessionChannelIO, options?: InputStreamOnceOptions, channel?: string): InputStreamOncePromise<SessionStreamRecord>;
+    /**
+     * Wait for and consume the next record accepted by `predicate`.
+     * Earlier unmatched records stay buffered and block consumption so the
+     * committed cursor never advances past them.
+     */
+    onceRecordWhere?(sessionId: string, io: SessionChannelIO, predicate: SessionStreamRecordPredicate, options?: InputStreamOnceOptions, channel?: string): InputStreamOncePromise<SessionStreamRecord>;
+    /** Non-blocking peek at the head of the channel buffer. */
+    peek(sessionId: string, io: SessionChannelIO, channel?: string): unknown | undefined;
+    /** Non-blocking peek at the head record, including its durable metadata. */
+    peekRecord?(sessionId: string, io: SessionChannelIO, channel?: string): SessionStreamRecord | undefined;
+    /** Last S2 sequence number seen on the given channel. */
+    lastSeqNum(sessionId: string, io: SessionChannelIO, channel?: string): number | undefined;
+    /** Advance the last-seen sequence number (prevents SSE replay after `.wait` resume). */
+    setLastSeqNum(sessionId: string, io: SessionChannelIO, seqNum: number, channel?: string): void;
+    /** Consume one exact record delivered through the waitpoint path. */
+    consumeRecord?(sessionId: string, io: SessionChannelIO, seqNum: number, channel?: string): void;
+    /**
+     * Highest sequence number that is safe to persist as consumed. When a later
+     * record is handled while an earlier record remains unconsumed, this stays
+     * behind the earliest unconsumed record. Distinct from {@link lastSeqNum},
+     * which advances on every received record regardless of whether anything
+     * consumed it. Used by
+     * `chat.agent` to persist the `.in` resume cursor on each
+     * `turn-complete` control record so the next worker boot can resume
+     * the channel from this point without replaying processed messages.
+     */
+    lastDispatchedSeqNum(sessionId: string, io: SessionChannelIO, channel?: string): number | undefined;
+    /**
+     * Seed the committed-consume cursor at worker boot — e.g. from the
+     * `session-in-event-id` header on the latest `turn-complete` on
+     * `.out`. Monotonic: only ever advances forward, never backwards. Existing
+     * unconsumed records still constrain {@link lastDispatchedSeqNum}.
+     */
+    setLastDispatchedSeqNum(sessionId: string, io: SessionChannelIO, seqNum: number, channel?: string): void;
+    /**
+     * Set a per-stream lower-bound SSE timestamp. Records whose timestamp
+     * is `<= minTimestamp` are dropped before dispatch. Used by chat.agent
+     * on OOM-retry boot to skip session.in records belonging to turns
+     * that already completed on the prior attempt.
+     *
+     * Pass `undefined` to clear the filter.
+     */
+    setMinTimestamp(sessionId: string, io: SessionChannelIO, minTimestamp: number | undefined, channel?: string): void;
+    /** Remove and discard the first buffered record. Returns true if one was removed. */
+    shiftBuffer(sessionId: string, io: SessionChannelIO, channel?: string): boolean;
+    /** Abort the SSE tail while preserving buffered records. Called before `.wait` suspends. */
+    disconnectStream(sessionId: string, io: SessionChannelIO, channel?: string): void;
+    /** Re-open a channel closed by {@link disconnectStream}, registering nothing. */
+    reconnectStream?(sessionId: string, io: SessionChannelIO, channel?: string): void;
+    /** Clear all `.on` handlers; abort tails without pending once-waiters. */
+    clearHandlers(): void;
+    /** Reset state between task executions. */
+    reset(): void;
+    /** Disconnect every tail. */
+    disconnect(): void;
+}

package/dist/commonjs/v3/sessionStreams/types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InputStreamTimeoutError = exports.InputStreamOncePromise = void 0;
+const types_js_1 = require("../inputStreams/types.js");
+Object.defineProperty(exports, "InputStreamOncePromise", { enumerable: true, get: function () { return types_js_1.InputStreamOncePromise; } });
+Object.defineProperty(exports, "InputStreamTimeoutError", { enumerable: true, get: function () { return types_js_1.InputStreamTimeoutError; } });
+//# sourceMappingURL=types.js.map

package/dist/commonjs/v3/sessionStreams/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/v3/sessionStreams/types.ts"],"names":[],"mappings":";;;AAEA,uDAA2F;uGAAlF,iCAAsB;wGAAE,kCAAuB"}

package/dist/commonjs/v3/sessionStreams/wireProtocol.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Wire-format constants for records on `session.out` / `session.in`.
+ *
+ * Three kinds of records can appear on a Session stream:
+ *
+ * 1. **Data records** — JSON body shaped as `{data: <UIMessageChunk>, id:
+ *    <partId>}`, no special headers. The substance of the conversation.
+ *
+ * 2. **Trigger control records** — empty body, `headers` carry `[
+ *    ["trigger-control", <subtype>], ...]` plus any subtype-specific sibling
+ *    headers (e.g. `public-access-token` on `turn-complete`). Routed to a
+ *    consumer's `onControl` callback; never surfaced as data chunks.
+ *
+ * 3. **S2 command records** — opaque body, `headers` first entry has an
+ *    empty name (only valid for S2-interpreted directives like `trim` and
+ *    `fence`). Filtered out at the SSE parser; consumers never see them.
+ *
+ * See `docs/ai-chat/client-protocol.mdx#records-on-session-out` for the
+ * customer-facing contract.
+ */
+/** Header name carrying the Trigger control subtype on control records. */
+export declare const TRIGGER_CONTROL_HEADER: "trigger-control";
+/** Header name carrying the refreshed `publicAccessToken` on `turn-complete`. */
+export declare const PUBLIC_ACCESS_TOKEN_HEADER: "public-access-token";
+/** Header name carrying the agent's last S2 event id on a handover bridge. */
+export declare const SESSION_STATE_LAST_EVENT_ID_HEADER: "last-event-id";
+/**
+ * Header on `turn-complete` records carrying the highest `session.in`
+ * seq_num the agent committed to processing during this turn. Read on
+ * the next worker boot to seed `.in`'s resume cursor — anything past
+ * this seq is new and gets delivered; anything at-or-before was already
+ * processed and is skipped. Decimal-string form of the seq_num.
+ *
+ * Omitted when no `.in` records have been consumed yet (first turn of a
+ * fresh chat triggered via the wire payload).
+ */
+export declare const SESSION_IN_EVENT_ID_HEADER: "session-in-event-id";
+/**
+ * Sibling of {@link SESSION_IN_EVENT_ID_HEADER}: the highest `.in` sequence this
+ * run had actually consumed at the turn boundary, unclamped.
+ *
+ * The resume cursor is held back behind records still waiting to be handled, so
+ * resuming from it necessarily re-delivers records that WERE handled. A message
+ * re-delivered that way is the point. A control record re-delivered that way is
+ * a bug: it applies a second time to whatever turn is live on the new run. On
+ * boot this bound tells the run which control records it has already seen.
+ */
+export declare const SESSION_IN_CONSUMED_ID_HEADER: "session-in-consumed-id";
+/**
+ * Header marking a session as closed. Carried by the `session-closed` control
+ * record, and also stamped on a `turn-complete` record when the close was
+ * decided before that turn ended — readers terminate their stream on
+ * turn-complete, so that is the last moment a live client can be told.
+ */
+export declare const SESSION_CLOSED_HEADER: "session-closed";
+/**
+ * Header on `session-closed` records carrying the reason the session was
+ * closed, as supplied to `chat.close({ reason })` / `sessions.close()`.
+ * Omitted when no reason was given.
+ */
+export declare const SESSION_CLOSED_REASON_HEADER: "session-closed-reason";
+export declare const TRIGGER_CONTROL_SUBTYPE: {
+    readonly TURN_COMPLETE: "turn-complete";
+    readonly UPGRADE_REQUIRED: "upgrade-required";
+    readonly SESSION_CLOSED: "session-closed";
+    readonly PENDING_VERSION: "pending-version";
+};
+export type TriggerControlSubtype = (typeof TRIGGER_CONTROL_SUBTYPE)[keyof typeof TRIGGER_CONTROL_SUBTYPE];
+/** Read a single header value by name. Returns the first match. */
+export declare function headerValue(headers: ReadonlyArray<readonly [string, string]> | undefined, name: string): string | undefined;
+/**
+ * Return the Trigger control subtype carried by a record's headers, if any.
+ * Returns `undefined` for data records and S2 command records.
+ */
+export declare function controlSubtype(headers: ReadonlyArray<readonly [string, string]> | undefined): string | undefined;
+/**
+ * Is this record an S2 command record? Detected via the empty-name first
+ * header, which S2 permits only for command records (trim/fence).
+ */
+export declare function isS2CommandRecord(headers: ReadonlyArray<readonly [string, string]> | undefined): boolean;
+/** Event payload delivered to a Session-stream `onControl` callback. */
+export type ControlEvent = {
+    /** Subtype value from the `trigger-control` header (e.g. `turn-complete`). */
+    subtype: string;
+    /** All headers on the underlying record. Read additional metadata here. */
+    headers: ReadonlyArray<readonly [string, string]>;
+    /** S2 sequence number of the control record. */
+    seqNum: number;
+    /** S2 arrival timestamp of the control record (ms since epoch). */
+    timestamp: number;
+};