refactor: rename warmTimeout to idleTimeout across chat APIs

Author: ericallam

packages/core/src/v3/realtimeStreams/types.ts

@@ -194,13 +194,13 @@ export type RealtimeDefinedInputStream<TData> = {
    */
   wait: (options?: InputStreamWaitOptions) => ManualWaitpointPromise<TData>;
   /**
-   * Wait for data with a warm phase before suspending.
+   * Wait for data with an idle phase before suspending.
    *
-   * Keeps the task warm (active, using compute) for `warmTimeoutInSeconds`,
+   * Keeps the task active (using compute) for `idleTimeoutInSeconds`,
    * then suspends via `.wait()` if no data arrives. If data arrives during
-   * the warm phase the task responds instantly without suspending.
+   * the idle phase the task responds instantly without suspending.
    */
-  waitWithWarmup: (options: InputStreamWaitWithWarmupOptions) => Promise<{ ok: true; output: TData } | { ok: false; error?: any }>;
+  waitWithIdleTimeout: (options: InputStreamWaitWithIdleTimeoutOptions) => Promise<{ ok: true; output: TData } | { ok: false; error?: any }>;
   /**
    * Send data to this input stream on a specific run.
    * This is used from outside the task (e.g., from your backend or another task).
@@ -257,9 +257,9 @@ export type InputStreamWaitOptions = {
   spanName?: string;
 };
 
-export type InputStreamWaitWithWarmupOptions = {
-  /** Seconds to keep the task warm before suspending. */
-  warmTimeoutInSeconds: number;
+export type InputStreamWaitWithIdleTimeoutOptions = {
+  /** Seconds to keep the task idle (active, using compute) before suspending. */
+  idleTimeoutInSeconds: number;
   /** Maximum time to wait after suspending (duration string, e.g. "1h"). */
   timeout?: string;
   /** Override the default span name for the outer operation. */

packages/trigger-sdk/src/v3/ai.ts

@@ -321,8 +321,8 @@ export type ChatTaskWirePayload<TMessage extends UIMessage = UIMessage, TMetadat
   continuation?: boolean;
   /** The run ID of the previous run (only set when `continuation` is true). */
   previousRunId?: string;
-  /** Override warm timeout for this run (seconds). Set by transport.preload(). */
-  warmTimeoutInSeconds?: number;
+  /** Override idle timeout for this run (seconds). Set by transport.preload(). */
+  idleTimeoutInSeconds?: number;
 };
 
 /**
@@ -896,16 +896,16 @@ export type ChatTaskOptions<
   turnTimeout?: string;
 
   /**
-   * How long (in seconds) to keep the run warm after each turn before suspending.
-   * During this window the run stays active and can respond instantly to the
-   * next message. After this timeout, the run suspends (frees compute) and waits
-   * via `inputStream.wait()`.
+   * How long (in seconds) the run stays idle (active, using compute) after each
+   * turn, waiting for the next message. During this window responses are instant.
+   * After this timeout the run suspends (frees compute) and waits via
+   * `inputStream.wait()`.
    *
    * Set to `0` to suspend immediately after each turn.
    *
    * @default 30
    */
-  warmTimeoutInSeconds?: number;
+  idleTimeoutInSeconds?: number;
 
   /**
    * How long the `chatAccessToken` (scoped to this run) remains valid.
@@ -919,14 +919,14 @@ export type ChatTaskOptions<
   chatAccessTokenTTL?: string;
 
   /**
-   * How long (in seconds) to keep the run warm after `onPreload` fires,
+   * How long (in seconds) the run stays idle after `onPreload` fires,
    * waiting for the first message before suspending.
    *
    * Only applies to preloaded runs (triggered via `transport.preload()`).
    *
-   * @default Same as `warmTimeoutInSeconds`
+   * @default Same as `idleTimeoutInSeconds`
    */
-  preloadWarmTimeoutInSeconds?: number;
+  preloadIdleTimeoutInSeconds?: number;
 
   /**
    * How long to wait (suspended) for the first message after a preloaded run starts.
@@ -1010,9 +1010,9 @@ function chatTask<
     onTurnComplete,
     maxTurns = 100,
     turnTimeout = "1h",
-    warmTimeoutInSeconds = 30,
+    idleTimeoutInSeconds = 30,
     chatAccessTokenTTL = "1h",
-    preloadWarmTimeoutInSeconds,
+    preloadIdleTimeoutInSeconds,
     preloadTimeout,
     uiMessageStreamOptions,
     ...restOptions
@@ -1111,18 +1111,18 @@ function chatTask<
           }
 
           // Wait for the first real message — use preload-specific timeouts if configured
-          const effectivePreloadWarmTimeout =
-            payload.warmTimeoutInSeconds
-            ?? preloadWarmTimeoutInSeconds
-            ?? warmTimeoutInSeconds;
+          const effectivePreloadIdleTimeout =
+            payload.idleTimeoutInSeconds
+            ?? preloadIdleTimeoutInSeconds
+            ?? idleTimeoutInSeconds;
 
           const effectivePreloadTimeout =
             (metadata.get(TURN_TIMEOUT_METADATA_KEY) as string | undefined)
             ?? preloadTimeout
             ?? turnTimeout;
 
-          const preloadResult = await messagesInput.waitWithWarmup({
-            warmTimeoutInSeconds: effectivePreloadWarmTimeout,
+          const preloadResult = await messagesInput.waitWithIdleTimeout({
+            idleTimeoutInSeconds: effectivePreloadIdleTimeout,
             timeout: effectivePreloadTimeout,
             spanName: "waiting for first message",
           });
@@ -1493,14 +1493,14 @@ function chatTask<
                 return "continue";
               }
 
-              // Wait for the next message — stay warm briefly, then suspend
-              const effectiveWarmTimeout =
-                (metadata.get(WARM_TIMEOUT_METADATA_KEY) as number | undefined) ?? warmTimeoutInSeconds;
+              // Wait for the next message — stay idle briefly, then suspend
+              const effectiveIdleTimeout =
+                (metadata.get(IDLE_TIMEOUT_METADATA_KEY) as number | undefined) ?? idleTimeoutInSeconds;
               const effectiveTurnTimeout =
                 (metadata.get(TURN_TIMEOUT_METADATA_KEY) as string | undefined) ?? turnTimeout;
 
-              const next = await messagesInput.waitWithWarmup({
-                warmTimeoutInSeconds: effectiveWarmTimeout,
+              const next = await messagesInput.waitWithIdleTimeout({
+                idleTimeoutInSeconds: effectiveIdleTimeout,
                 timeout: effectiveTurnTimeout,
                 spanName: "waiting for next message",
               });
@@ -1554,7 +1554,7 @@ function chatTask<
 // ---------------------------------------------------------------------------
 
 const TURN_TIMEOUT_METADATA_KEY = "chat.turnTimeout";
-const WARM_TIMEOUT_METADATA_KEY = "chat.warmTimeout";
+const IDLE_TIMEOUT_METADATA_KEY = "chat.idleTimeout";
 
 /**
  * Override the turn timeout for subsequent turns in the current run.
@@ -1597,24 +1597,24 @@ function setTurnTimeoutInSeconds(seconds: number): void {
 }
 
 /**
- * Override the warm timeout for subsequent turns in the current run.
+ * Override the idle timeout for subsequent turns in the current run.
  *
- * The warm timeout controls how long the run stays active (using compute)
+ * The idle timeout controls how long the run stays active (using compute)
  * after each turn, waiting for the next message. During this window,
  * responses are instant. After it expires, the run suspends.
  *
- * @param seconds - Number of seconds to stay warm (0 to suspend immediately)
+ * @param seconds - Number of seconds to stay idle (0 to suspend immediately)
  *
  * @example
  * ```ts
  * run: async ({ messages, signal }) => {
- *   chat.setWarmTimeoutInSeconds(60);
+ *   chat.setIdleTimeoutInSeconds(60);
  *   return streamText({ model, messages, abortSignal: signal });
  * }
  * ```
  */
-function setWarmTimeoutInSeconds(seconds: number): void {
-  metadata.set(WARM_TIMEOUT_METADATA_KEY, seconds);
+function setIdleTimeoutInSeconds(seconds: number): void {
+  metadata.set(IDLE_TIMEOUT_METADATA_KEY, seconds);
 }
 
 /**
@@ -1937,8 +1937,8 @@ class ChatMessageAccumulator {
 export type ChatSessionOptions = {
   /** Run-level cancel signal (from task context). */
   signal: AbortSignal;
-  /** Seconds to stay warm between turns before suspending. @default 30 */
-  warmTimeoutInSeconds?: number;
+  /** Seconds to stay idle between turns before suspending. @default 30 */
+  idleTimeoutInSeconds?: number;
   /** Duration string for suspend timeout. @default "1h" */
   timeout?: string;
   /** Max turns before ending. @default 100 */
@@ -1988,7 +1988,7 @@ export type ChatTurn = {
  * Create a chat session that yields turns as an async iterator.
  *
  * Handles: preload wait, stop signals, message accumulation, turn-complete
- * signaling, and warm/suspend between turns. You control: initialization,
+ * signaling, and idle/suspend between turns. You control: initialization,
  * model/tool selection, persistence, and any custom per-turn logic.
  *
  * @example
@@ -2021,7 +2021,7 @@ function createChatSession(
 ): AsyncIterable<ChatTurn> {
   const {
     signal: runSignal,
-    warmTimeoutInSeconds = 30,
+    idleTimeoutInSeconds = 30,
     timeout = "1h",
     maxTurns = 100,
   } = options;
@@ -2039,8 +2039,8 @@ function createChatSession(
 
           // First turn: handle preload — wait for the first real message
           if (turn === 0 && currentPayload.trigger === "preload") {
-            const result = await messagesInput.waitWithWarmup({
-              warmTimeoutInSeconds: currentPayload.warmTimeoutInSeconds ?? warmTimeoutInSeconds,
+            const result = await messagesInput.waitWithIdleTimeout({
+              idleTimeoutInSeconds: currentPayload.idleTimeoutInSeconds ?? idleTimeoutInSeconds,
               timeout,
               spanName: "waiting for first message",
             });
@@ -2053,8 +2053,8 @@ function createChatSession(
 
           // Subsequent turns: wait for the next message
           if (turn > 0) {
-            const next = await messagesInput.waitWithWarmup({
-              warmTimeoutInSeconds,
+            const next = await messagesInput.waitWithIdleTimeout({
+              idleTimeoutInSeconds,
               timeout,
               spanName: "waiting for next message",
             });
@@ -2391,8 +2391,8 @@ export const chat = {
   setTurnTimeout,
   /** Override the turn timeout at runtime (seconds). See {@link setTurnTimeoutInSeconds}. */
   setTurnTimeoutInSeconds,
-  /** Override the warm timeout at runtime. See {@link setWarmTimeoutInSeconds}. */
-  setWarmTimeoutInSeconds,
+  /** Override the idle timeout at runtime. See {@link setIdleTimeoutInSeconds}. */
+  setIdleTimeoutInSeconds,
   /** Override toUIMessageStream() options for the current turn. See {@link setUIMessageStreamOptions}. */
   setUIMessageStreamOptions,
   /** Check if the current turn was stopped by the user. See {@link isStopped}. */

packages/trigger-sdk/src/v3/chat.ts

@@ -464,7 +464,7 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
    *
    * No-op if a session already exists for this chatId.
    */
-  async preload(chatId: string, options?: { warmTimeoutInSeconds?: number }): Promise<void> {
+  async preload(chatId: string, options?: { idleTimeoutInSeconds?: number }): Promise<void> {
     // Don't preload if session already exists
     if (this.sessions.get(chatId)?.runId) return;
 
@@ -473,8 +473,8 @@ export class TriggerChatTransport implements ChatTransport<UIMessage> {
       chatId,
       trigger: "preload" as const,
       metadata: this.defaultMetadata,
-      ...(options?.warmTimeoutInSeconds !== undefined
-        ? { warmTimeoutInSeconds: options.warmTimeoutInSeconds }
+      ...(options?.idleTimeoutInSeconds !== undefined
+        ? { idleTimeoutInSeconds: options.idleTimeoutInSeconds }
         : {}),
     };
 

packages/trigger-sdk/src/v3/streams.ts

@@ -25,7 +25,7 @@ import {
   InputStreamOncePromise,
   type InputStreamOnceResult,
   type InputStreamWaitOptions,
-  type InputStreamWaitWithWarmupOptions,
+  type InputStreamWaitWithIdleTimeoutOptions,
   type SendInputStreamOptions,
   type InferInputStreamType,
   type StreamWriteResult,
@@ -842,20 +842,20 @@ function input<TData>(opts: { id: string }): RealtimeDefinedInputStream<TData> {
         }
       });
     },
-    async waitWithWarmup(options) {
+    async waitWithIdleTimeout(options) {
       const self = this;
-      const spanName = options.spanName ?? `inputStream.waitWithWarmup()`;
+      const spanName = options.spanName ?? `inputStream.waitWithIdleTimeout()`;
 
       return tracer.startActiveSpan(
         spanName,
         async (span) => {
-          // Warm phase: keep compute alive
-          if (options.warmTimeoutInSeconds > 0) {
+          // Idle phase: keep compute alive
+          if (options.idleTimeoutInSeconds > 0) {
             const warm = await inputStreams.once(opts.id, {
-              timeoutMs: options.warmTimeoutInSeconds * 1000,
+              timeoutMs: options.idleTimeoutInSeconds * 1000,
             });
             if (warm.ok) {
-              span.setAttribute("wait.resolved", "warm");
+              span.setAttribute("wait.resolved", "idle");
               return { ok: true as const, output: warm.output as TData };
             }
           }

references/ai-chat/src/components/chat-app.tsx

@@ -56,7 +56,7 @@ export function ChatApp({
   // Model for new chats (before first message is sent)
   const [newChatModel, setNewChatModel] = useState(DEFAULT_MODEL);
   const [preloadEnabled, setPreloadEnabled] = useState(true);
-  const [warmTimeoutInSeconds, setWarmTimeoutInSeconds] = useState(60);
+  const [idleTimeoutInSeconds, setIdleTimeoutInSeconds] = useState(60);
 
   const handleSessionChange = useCallback(
     (chatId: string, session: SessionInfo | null) => {
@@ -106,7 +106,7 @@ export function ChatApp({
     setNewChatModel(DEFAULT_MODEL);
     if (preloadEnabled) {
       // Eagerly start the run — onPreload fires immediately for initialization
-      transport.preload(id, { warmTimeoutInSeconds });
+      transport.preload(id, { idleTimeoutInSeconds });
     }
   }
 
@@ -159,8 +159,8 @@ export function ChatApp({
         onDeleteChat={handleDeleteChat}
         preloadEnabled={preloadEnabled}
         onPreloadChange={setPreloadEnabled}
-        warmTimeoutInSeconds={warmTimeoutInSeconds}
-        onWarmTimeoutChange={setWarmTimeoutInSeconds}
+        idleTimeoutInSeconds={idleTimeoutInSeconds}
+        onIdleTimeoutChange={setIdleTimeoutInSeconds}
         taskMode={taskMode}
         onTaskModeChange={onTaskModeChange}
       />

references/ai-chat/src/components/chat-sidebar.tsx

@@ -26,8 +26,8 @@ type ChatSidebarProps = {
   onDeleteChat: (id: string) => void;
   preloadEnabled: boolean;
   onPreloadChange: (enabled: boolean) => void;
-  warmTimeoutInSeconds: number;
-  onWarmTimeoutChange: (seconds: number) => void;
+  idleTimeoutInSeconds: number;
+  onIdleTimeoutChange: (seconds: number) => void;
   taskMode: string;
   onTaskModeChange: (mode: string) => void;
 };
@@ -40,8 +40,8 @@ export function ChatSidebar({
   onDeleteChat,
   preloadEnabled,
   onPreloadChange,
-  warmTimeoutInSeconds,
-  onWarmTimeoutChange,
+  idleTimeoutInSeconds,
+  onIdleTimeoutChange,
   taskMode,
   onTaskModeChange,
 }: ChatSidebarProps) {
@@ -101,13 +101,13 @@ export function ChatSidebar({
           Preload new chats
         </label>
         <div className="flex items-center gap-2 text-xs text-gray-500">
-          <span className="shrink-0">Warm timeout</span>
+          <span className="shrink-0">Idle timeout</span>
           <input
             type="number"
             min={0}
             step={5}
-            value={warmTimeoutInSeconds}
-            onChange={(e) => onWarmTimeoutChange(Number(e.target.value))}
+            value={idleTimeoutInSeconds}
+            onChange={(e) => onIdleTimeoutChange(Number(e.target.value))}
             className="w-16 rounded border border-gray-300 px-1.5 py-0.5 text-xs text-gray-600 outline-none focus:border-blue-500"
           />
           <span>s</span>