@trigger.dev/sdk 0.0.0-prerelease-local-bundle-20260824142657 → 0.0.0-prerelease-20260827125919

package/dist/commonjs/v3/ai.d.ts

@@ -257,6 +257,26 @@ export type ChatTaskRunPayload<TClientData = unknown, TTools extends ToolSet = T
      */
     tools: TTools;
 };
+/**
+ * One message record delivered through {@link chat.messages}.
+ *
+ * `id` is the append's stable idempotency key and `seqNum` is its monotonic
+ * sequence on the Session `.in` channel. Both remain stable if the record is
+ * delivered again after a reconnect.
+ */
+export type ChatMessageRecord = Readonly<{
+    id: string;
+    seqNum: number;
+    payload: ChatTaskWirePayload;
+}>;
+export type ChatMessages = RealtimeDefinedInputStream<ChatTaskWirePayload> & {
+    /** Whether the local buffer head is a message that can be consumed immediately. */
+    hasPending(): Promise<boolean>;
+    /** Consume one message record, or return `undefined` when the optional timeout elapses. */
+    next(options?: {
+        timeoutInSeconds?: number;
+    }): Promise<ChatMessageRecord | undefined>;
+};
 /**
  * Signal received by a `handover-prepare` agent run waiting on
  * `session.in`. Either the customer's first-turn `streamText` finished
@@ -294,9 +314,8 @@ export type HandoverSignal = {
  * For the common case prefer `accumulator.consumeHandover()`, which also seeds
  * `payload.headStartMessages` and applies the partial for you.
  *
- * Must be called at turn 0 before any `chat.messages.waitWithIdleTimeout` —
- * that facade consumes and discards non-message chunks, which would swallow the
- * handover signal.
+ * Safe to call at any point in turn 0: the handover signal has its own route,
+ * so a message facade waiting at the same time cannot take it.
  */
 declare function waitForHandover(options: {
     /** The run's wire payload (only `trigger` / `idleTimeoutInSeconds` are read). */
@@ -2460,10 +2479,14 @@ declare function createStopSignal(): {
  * task instead of round-tripping them back from the client:
  * - `lastEventId` — the turn-complete control record's seq_num on
  *   `session.out`; where the next turn's output stream resumes.
- * - `sessionInEventId` — the committed-consume cursor on `session.in` as of
- *   this turn-complete, letting a raw loop correlate the boundary with the
- *   exact input record it acknowledged. Trigger owns input-cursor recovery,
- *   so this is for correlation / out-of-sync detection, not required.
+ * - `sessionInEventId` — the safe-to-resume-from cursor on `session.in` as of
+ *   this turn-complete. It is the highest sequence that can be resumed past
+ *   without skipping an unhandled message, so it is held back behind any
+ *   message still buffered unconsumed and is NOT necessarily the sequence of
+ *   the record this turn answered. Trigger owns input-cursor recovery, so this
+ *   is for correlation / out-of-sync detection, not required. Treat it as a
+ *   lower bound: a value below the record you just handled is expected, not a
+ *   sign of a lost turn.
  *
  * Either is `undefined` when the corresponding cursor isn't available.
  *
@@ -3010,7 +3033,7 @@ export declare const chat: {
         write(part: UIMessageChunk): void;
     };
     /** Pre-built input stream for receiving messages from the transport. */
-    messages: RealtimeDefinedInputStream<ChatTaskWirePayload>;
+    messages: ChatMessages;
     /** Create a managed stop signal wired to the stop input stream. See {@link createStopSignal}. */
     createStopSignal: typeof createStopSignal;
     /** Signal the frontend that the current turn is complete. See {@link chatWriteTurnComplete}. */