@trigger.dev/react-hooks 4.5.12 → 4.5.14

package/dist/commonjs/hooks/useSessionStream.js

@@ -0,0 +1,236 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSessionStream = useSessionStream;
+const react_1 = require("react");
+const throttle_js_1 = require("../utils/throttle.js");
+const trigger_swr_js_1 = require("../utils/trigger-swr.js");
+const useStableRequestCallback_js_1 = require("../utils/useStableRequestCallback.js");
+const useApiClient_js_1 = require("./useApiClient.js");
+/**
+ * Hook to read one channel of a Session's realtime stream.
+ *
+ * This hook subscribes to one of the session's channels (`out` by default, or `in`) and
+ * updates the `records` array as new records arrive. It is read-only: use `useSession` for
+ * two-way (read and write) communication. The subscription is automatically managed: it
+ * starts when the component mounts (or when `enabled` becomes `true`) and stops when the
+ * component unmounts or when `stop()` is called.
+ *
+ * Requires a Public Access Token with the `read:sessions:{id}` scope.
+ *
+ * @template TRecord - The type of each record on the channel
+ * @param sessionIdOrExternalId - The id or external id of the session to subscribe to
+ * @param options - Optional configuration for the subscription
+ * @returns An object containing:
+ *   - `records`: An array of all the records received so far (accumulates over time)
+ *   - `lastEventId`: The cursor of the last record seen, for resuming later
+ *   - `lastControl`: The last control record seen
+ *   - `error`: Any error that occurred during subscription
+ *   - `stop`: A function to manually stop the subscription
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useSessionStream } from "@trigger.dev/react-hooks";
+ *
+ * function SessionViewer({ sessionId }: { sessionId: string }) {
+ *   const { records, error } = useSessionStream<string>(sessionId, {
+ *     accessToken: publicAccessToken,
+ *   });
+ *
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return <div>{records.join("")}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Read the input channel, resuming from a persisted cursor
+ * const { records, lastEventId, stop } = useSessionStream<MyRecord>(sessionId, {
+ *   accessToken: publicAccessToken,
+ *   io: "in",
+ *   lastEventId: persistedCursor,
+ *   onControl: (event) => {
+ *     if (event.subtype === "turn-complete") {
+ *       console.log("The turn is complete");
+ *     }
+ *   },
+ * });
+ * ```
+ */
+function useSessionStream(sessionIdOrExternalId, options) {
+    const hookId = (0, react_1.useId)();
+    const idKey = options?.id ?? hookId;
+    const io = options?.io ?? "out";
+    const [initialRecordsFallback] = (0, react_1.useState)([]);
+    const { data: records, mutate: mutateRecords } = (0, trigger_swr_js_1.useSWR)([idKey, sessionIdOrExternalId, io, "records"], null, {
+        fallbackData: initialRecordsFallback,
+    });
+    const recordsRef = (0, react_1.useRef)(records ?? []);
+    (0, react_1.useEffect)(() => {
+        recordsRef.current = records || [];
+    }, [records]);
+    const { data: lastEventId = undefined, mutate: setLastEventId } = (0, trigger_swr_js_1.useSWR)([idKey, sessionIdOrExternalId, io, "lastEventId"], null);
+    const lastEventIdRef = (0, react_1.useRef)(lastEventId);
+    const channelIdentityRef = (0, react_1.useRef)(`${idKey}:${sessionIdOrExternalId}:${io}`);
+    (0, react_1.useEffect)(() => {
+        const identity = `${idKey}:${sessionIdOrExternalId}:${io}`;
+        if (channelIdentityRef.current !== identity) {
+            channelIdentityRef.current = identity;
+            lastEventIdRef.current = lastEventId;
+        }
+    }, [idKey, sessionIdOrExternalId, io, lastEventId]);
+    const { data: lastControl = undefined, mutate: setLastControl } = (0, trigger_swr_js_1.useSWR)([idKey, sessionIdOrExternalId, io, "lastControl"], null);
+    const { data: _isComplete = false, mutate: setIsComplete } = (0, trigger_swr_js_1.useSWR)([idKey, sessionIdOrExternalId, io, "complete"], null);
+    const { data: error = undefined, mutate: setError } = (0, trigger_swr_js_1.useSWR)([idKey, sessionIdOrExternalId, io, "error"], null);
+    const abortControllerRef = (0, react_1.useRef)(null);
+    const stop = (0, react_1.useCallback)(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+    }, []);
+    const onRecordsCallback = options?.onRecords;
+    const onRecords = (0, react_1.useCallback)((recordsBatch) => {
+        if (onRecordsCallback) {
+            onRecordsCallback(recordsBatch);
+        }
+    }, [onRecordsCallback]);
+    const onControlCallback = options?.onControl;
+    const onControl = (0, react_1.useCallback)((event) => {
+        if (onControlCallback) {
+            onControlCallback(event);
+        }
+    }, [onControlCallback]);
+    const apiClient = (0, useApiClient_js_1.useApiClient)(options);
+    const timeoutInSeconds = options?.timeoutInSeconds;
+    const startEventId = options?.lastEventId;
+    const throttleInMs = options?.throttleInMs;
+    const from = options?.from;
+    const maxRecords = options?.maxRecords;
+    (0, react_1.useEffect)(() => {
+        if (maxRecords != null && maxRecords >= 0) {
+            const current = recordsRef.current;
+            if (current.length > maxRecords) {
+                mutateRecords(current.slice(current.length - maxRecords));
+            }
+        }
+    }, [maxRecords, mutateRecords]);
+    const triggerRequest = (0, react_1.useCallback)(async () => {
+        try {
+            if (!sessionIdOrExternalId || !apiClient) {
+                return;
+            }
+            const abortController = new AbortController();
+            abortControllerRef.current = abortController;
+            await processSessionStream(sessionIdOrExternalId, io, apiClient, mutateRecords, recordsRef, setLastEventId, setLastControl, setError, onRecords, onControl, abortControllerRef, timeoutInSeconds, startEventId !== undefined ? String(startEventId) : lastEventIdRef.current, throttleInMs ?? 16, from, maxRecords);
+        }
+        catch (err) {
+            if (err.name === "AbortError") {
+                abortControllerRef.current = null;
+                return;
+            }
+            setError(err);
+        }
+        finally {
+            if (abortControllerRef.current) {
+                abortControllerRef.current = null;
+            }
+            setIsComplete(true);
+        }
+    }, [
+        sessionIdOrExternalId,
+        io,
+        apiClient,
+        mutateRecords,
+        setLastEventId,
+        setLastControl,
+        setError,
+        setIsComplete,
+        onRecords,
+        onControl,
+        timeoutInSeconds,
+        startEventId,
+        throttleInMs,
+        from,
+        maxRecords,
+    ]);
+    const requestSubscription = (0, useStableRequestCallback_js_1.useStableRequestCallback)(triggerRequest);
+    (0, react_1.useEffect)(() => {
+        if (typeof options?.enabled === "boolean" && !options.enabled) {
+            return;
+        }
+        if (!sessionIdOrExternalId) {
+            return;
+        }
+        requestSubscription().finally(() => { });
+        return () => {
+            stop();
+        };
+    }, [sessionIdOrExternalId, io, stop, options?.enabled, requestSubscription]);
+    return { records: records ?? initialRecordsFallback, lastEventId, lastControl, error, stop };
+}
+async function processSessionStream(sessionIdOrExternalId, io, apiClient, mutateRecordsData, existingRecordsRef, setLastEventId, setLastControl, onError, onRecords, onControl, abortControllerRef, timeoutInSeconds, lastEventId, throttleInMs, from, maxRecords) {
+    let lastSeenEventId;
+    let publishedEventId;
+    let partsBatch = [];
+    const publishLastEventId = () => {
+        if (lastSeenEventId !== publishedEventId) {
+            publishedEventId = lastSeenEventId;
+            setLastEventId(lastSeenEventId);
+        }
+    };
+    const flushParts = () => {
+        if (partsBatch.length === 0)
+            return;
+        const batch = partsBatch;
+        partsBatch = [];
+        onRecords(batch);
+    };
+    try {
+        const stream = await apiClient.subscribeToSessionStream(sessionIdOrExternalId, io, {
+            signal: abortControllerRef.current?.signal,
+            timeoutInSeconds,
+            lastEventId,
+            from,
+            onPart: (part) => {
+                lastSeenEventId = part.id;
+                partsBatch.push(part);
+            },
+            onControl: (event) => {
+                setLastControl(event);
+                onControl(event);
+            },
+        });
+        const recordsQueue = (0, throttle_js_1.createThrottledQueue)(async (newRecords) => {
+            const combined = [...existingRecordsRef.current, ...newRecords];
+            const bounded = maxRecords != null && maxRecords >= 0 && combined.length > maxRecords
+                ? combined.slice(combined.length - maxRecords)
+                : combined;
+            existingRecordsRef.current = bounded;
+            mutateRecordsData(bounded);
+            publishLastEventId();
+            flushParts();
+        }, throttleInMs);
+        for await (const record of stream) {
+            recordsQueue.add(record);
+        }
+        await recordsQueue.flush();
+        publishLastEventId();
+        flushParts();
+    }
+    catch (err) {
+        if (err.name === "AbortError") {
+            return;
+        }
+        if (err instanceof Error) {
+            onError(err);
+        }
+        else {
+            onError(new Error(String(err)));
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=useSessionStream.js.map

package/dist/commonjs/hooks/useSessionStream.js.map

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

package/dist/commonjs/index.d.ts

@@ -5,3 +5,4 @@ export * from "./hooks/useRealtime.js";
 export * from "./hooks/useTaskTrigger.js";
 export * from "./hooks/useWaitToken.js";
 export * from "./hooks/useInputStreamSend.js";
+export * from "./hooks/useSessionStream.js";

package/dist/commonjs/index.js

@@ -21,4 +21,5 @@ __exportStar(require("./hooks/useRealtime.js"), exports);
 __exportStar(require("./hooks/useTaskTrigger.js"), exports);
 __exportStar(require("./hooks/useWaitToken.js"), exports);
 __exportStar(require("./hooks/useInputStreamSend.js"), exports);
+__exportStar(require("./hooks/useSessionStream.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,0DAAwC;AACxC,oDAAkC;AAClC,yDAAuC;AACvC,4DAA0C;AAC1C,0DAAwC;AACxC,gEAA8C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,0DAAwC;AACxC,oDAAkC;AAClC,yDAAuC;AACvC,4DAA0C;AAC1C,0DAAwC;AACxC,gEAA8C;AAC9C,8DAA4C"}

package/dist/commonjs/utils/useStableRequestCallback.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Keep subscription lifecycles controlled by their effects while using the
+ * latest request inputs.
+ */
+export declare function useStableRequestCallback(callback: () => Promise<void>): () => Promise<void>;

package/dist/commonjs/utils/useStableRequestCallback.js

@@ -0,0 +1,17 @@
+"use strict";
+"use client";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useStableRequestCallback = useStableRequestCallback;
+const react_1 = require("react");
+/**
+ * Keep subscription lifecycles controlled by their effects while using the
+ * latest request inputs.
+ */
+function useStableRequestCallback(callback) {
+    const callbackRef = (0, react_1.useRef)(callback);
+    (0, react_1.useEffect)(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+    return (0, react_1.useCallback)(() => callbackRef.current(), []);
+}
+//# sourceMappingURL=useStableRequestCallback.js.map

package/dist/commonjs/utils/useStableRequestCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStableRequestCallback.js","sourceRoot":"","sources":["../../../src/utils/useStableRequestCallback.ts"],"names":[],"mappings":";AAAA,YAAY,CAAC;;;AAEb,iCAAuD;AAEvD;;;GAGG;AACH,kCAAyC,QAA6B;IACpE,MAAM,WAAW,GAAG,IAAA,cAAM,EAAC,QAAQ,CAAC,CAAC;IAErC,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IACjC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,OAAO,IAAA,mBAAW,EAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC"}

package/dist/esm/hooks/useApiClient.d.ts

@@ -12,6 +12,11 @@ export type UseApiClientOptions = {
     previewBranch?: string;
     /** Optional additional request configuration */
     requestOptions?: ApiRequestOptions;
+    /**
+     * Optional callback that mints a fresh access token. Used to reconnect a
+     * realtime stream that the server rejected because its token expired.
+     */
+    refreshAccessToken?: () => Promise<string>;
     /**
      * Enable or disable the API client instance.
      *

package/dist/esm/hooks/useApiClient.js

@@ -1,5 +1,6 @@
 "use client";
-import { ApiClient } from "@trigger.dev/core/v3";
+import { ApiClient, refreshAccessTokenOnce } from "@trigger.dev/core/v3";
+import { useCallback, useEffect, useRef } from "react";
 import { useTriggerAuthContextOptional } from "../contexts.js";
 /**
  * Hook to create an API client instance using authentication context or provided options.
@@ -26,6 +27,18 @@ export function useApiClient(options) {
     const baseUrl = options?.baseURL ?? auth?.baseURL ?? "https://api.trigger.dev";
     const accessToken = options?.accessToken ?? auth?.accessToken;
     const previewBranch = options?.previewBranch ?? auth?.previewBranch;
+    const refreshAccessToken = options?.refreshAccessToken ?? auth?.refreshAccessToken;
+    const refreshAccessTokenRef = useRef(refreshAccessToken);
+    useEffect(() => {
+        refreshAccessTokenRef.current = refreshAccessToken;
+    }, [refreshAccessToken]);
+    const stableRefreshAccessToken = useCallback(async () => {
+        const refresh = refreshAccessTokenRef.current;
+        if (!refresh) {
+            throw new Error("Missing refreshAccessToken in TriggerAuthContext or useApiClient options");
+        }
+        return refreshAccessTokenOnce(refresh);
+    }, []);
     if (!accessToken) {
         if (options?.enabled === false) {
             return undefined;
@@ -36,6 +49,6 @@ export function useApiClient(options) {
         ...auth?.requestOptions,
         ...options?.requestOptions,
     };
-    return new ApiClient(baseUrl, accessToken, previewBranch, requestOptions);
+    return new ApiClient(baseUrl, accessToken, previewBranch, requestOptions, undefined, refreshAccessToken ? stableRefreshAccessToken : undefined);
 }
 //# sourceMappingURL=useApiClient.js.map

package/dist/esm/hooks/useApiClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"useApiClient.js","sourceRoot":"","sources":["../../../src/hooks/useApiClient.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAuB/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA6B;IACxD,MAAM,IAAI,GAAG,6BAA6B,EAAE,CAAC;IAE7C,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,yBAAyB,CAAC;IAC/E,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,WAAW,CAAC;IAC9D,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,aAAa,CAAC;IACpE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,IAAI,OAAO,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,cAAc,GAAsB;QACxC,GAAG,IAAI,EAAE,cAAc;QACvB,GAAG,OAAO,EAAE,cAAc;KAC3B,CAAC;IAEF,OAAO,IAAI,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;AAC5E,CAAC"}
+{"version":3,"file":"useApiClient.js","sourceRoot":"","sources":["../../../src/hooks/useApiClient.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACvD,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AA4B/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA6B;IACxD,MAAM,IAAI,GAAG,6BAA6B,EAAE,CAAC;IAE7C,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,yBAAyB,CAAC;IAC/E,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,WAAW,CAAC;IAC9D,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,aAAa,CAAC;IACpE,MAAM,kBAAkB,GAAG,OAAO,EAAE,kBAAkB,IAAI,IAAI,EAAE,kBAAkB,CAAC;IAEnF,MAAM,qBAAqB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACzD,SAAS,CAAC,GAAG,EAAE;QACb,qBAAqB,CAAC,OAAO,GAAG,kBAAkB,CAAC;IACrD,CAAC,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACzB,MAAM,wBAAwB,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACtD,MAAM,OAAO,GAAG,qBAAqB,CAAC,OAAO,CAAC;QAE9C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;QAC9F,CAAC;QAED,OAAO,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,IAAI,OAAO,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,cAAc,GAAsB;QACxC,GAAG,IAAI,EAAE,cAAc;QACvB,GAAG,OAAO,EAAE,cAAc;KAC3B,CAAC;IAEF,OAAO,IAAI,SAAS,CAClB,OAAO,EACP,WAAW,EACX,aAAa,EACb,cAAc,EACd,SAAS,EACT,kBAAkB,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS,CAC1D,CAAC;AACJ,CAAC"}

package/dist/esm/hooks/useRealtime.d.ts

@@ -1,4 +1,4 @@
-import type { AnyTask, InferStreamType, RealtimeDefinedStream, RealtimeRun, RealtimeRunSkipColumns } from "@trigger.dev/core/v3";
+import type { AnyTask, InferStreamType, RealtimeDefinedStream, RealtimeRun, RealtimeRunSkipColumns, SSEStreamPart } from "@trigger.dev/core/v3";
 import type { UseApiClientOptions } from "./useApiClient.js";
 export type UseRealtimeRunOptions = UseApiClientOptions & {
     id?: string;
@@ -154,6 +154,12 @@ export declare function useRealtimeRunsWithTag<TTask extends AnyTask>(tag: strin
 export declare function useRealtimeBatch<TTask extends AnyTask>(batchId: string, options?: UseRealtimeRunOptions): UseRealtimeRunsInstance<TTask>;
 export type UseRealtimeStreamInstance<TPart> = {
     parts: Array<TPart>;
+    /**
+     * The event id of the last part seen. Persist this (e.g. to localStorage) and
+     * pass it back as the `lastEventId` option to resume the stream where you left
+     * off after a page reload. Updated on each throttled flush.
+     */
+    lastEventId: string | undefined;
     error: Error | undefined;
     /**
      * Abort the current request immediately, keep the generated tokens if any.
@@ -182,10 +188,46 @@ export type UseRealtimeStreamOptions<TPart> = UseApiClientOptions & {
      * @default 0
      */
     startIndex?: number;
+    /**
+     * The event id to resume from, as returned in `lastEventId`. Persist it across
+     * a page reload and pass it back to continue where the previous session left
+     * off, with no replay and no gap. Takes precedence over `startIndex` and
+     * `from`.
+     */
+    lastEventId?: string | number;
+    /**
+     * Where a fresh subscription starts reading.
+     *
+     * - `"beginning"` (default): replay the full stream history, then live-tail.
+     * - `"latest"`: start at the current tail (the latest record, then live
+     *   updates) instead of replaying history, for a last-value / live view. On
+     *   reconnect or remount the subscription resumes from the last record it
+     *   saw, so no frames are missed and none are replayed.
+     *
+     * Ignored when `startIndex` is set (which pins an absolute start position).
+     */
+    from?: "beginning" | "latest";
+    /**
+     * Cap the number of parts kept in the accumulated `parts` array. When more
+     * than `maxParts` parts have been received, only the most recent `maxParts`
+     * are retained (older parts are dropped). Use `maxParts: 1` together with
+     * `from: "latest"` for a pure last-value view with bounded memory.
+     *
+     * When unset, `parts` accumulates every record for the lifetime of the
+     * subscription (the default).
+     */
+    maxParts?: number;
     /**
      * Callback this is called when new data is received.
      */
     onData?: (data: TPart) => void;
+    /**
+     * Callback invoked once per throttled flush with the batch of parts in that
+     * flush, each carrying its event `id`, `chunk` and `timestamp`. Use it to
+     * track the resume cursor without re-rendering on every record. Fires at the
+     * `throttleInMs` cadence, not per record.
+     */
+    onParts?: (parts: Array<SSEStreamPart<TPart>>) => void;
 };
 export declare function useRealtimeStream<TDefinedStream extends RealtimeDefinedStream<any>>(stream: TDefinedStream, runId: string, options?: UseRealtimeStreamOptions<InferStreamType<TDefinedStream>>): UseRealtimeStreamInstance<InferStreamType<TDefinedStream>>;
 /**

package/dist/esm/hooks/useRealtime.js

@@ -3,14 +3,7 @@ import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { useSWR } from "../utils/trigger-swr.js";
 import { useApiClient } from "./useApiClient.js";
 import { createThrottledQueue } from "../utils/throttle.js";
-// Keep subscription lifecycles controlled by their effects while using the latest request inputs.
-function useStableRequestCallback(callback) {
-    const callbackRef = useRef(callback);
-    useEffect(() => {
-        callbackRef.current = callback;
-    }, [callback]);
-    return useCallback(() => callbackRef.current(), []);
-}
+import { useStableRequestCallback } from "../utils/useStableRequestCallback.js";
 /**
  * Hook to subscribe to realtime updates of a task run.
  *
@@ -396,6 +389,16 @@ function useRealtimeStreamImplementation(runId, streamKey, options) {
     useEffect(() => {
         partsRef.current = parts || [];
     }, [parts]);
+    const { data: persistedLastEventId, mutate: mutateLastEventId } = useSWR([idKey, runId, streamKey, "lastEventId"], null);
+    const lastEventIdRef = useRef(persistedLastEventId);
+    const streamIdentityRef = useRef(`${idKey}:${runId}:${streamKey}`);
+    useEffect(() => {
+        const identity = `${idKey}:${runId}:${streamKey}`;
+        if (streamIdentityRef.current !== identity) {
+            streamIdentityRef.current = identity;
+            lastEventIdRef.current = persistedLastEventId;
+        }
+    }, [idKey, runId, streamKey, persistedLastEventId]);
     // Add state to track when the subscription is complete
     const { data: _isComplete = false, mutate: setIsComplete } = useSWR([idKey, runId, streamKey, "complete"], null);
     const { data: error = undefined, mutate: setError } = useSWR([idKey, runId, streamKey, "error"], null);
@@ -413,10 +416,27 @@ function useRealtimeStreamImplementation(runId, streamKey, options) {
             onDataCallback(data);
         }
     }, [onDataCallback]);
+    const onPartsCallback = options?.onParts;
+    const onParts = useCallback((partsBatch) => {
+        if (onPartsCallback) {
+            onPartsCallback(partsBatch);
+        }
+    }, [onPartsCallback]);
     const apiClient = useApiClient(options);
     const timeoutInSeconds = options?.timeoutInSeconds;
     const startIndex = options?.startIndex;
+    const startEventId = options?.lastEventId;
     const throttleInMs = options?.throttleInMs;
+    const from = options?.from;
+    const maxParts = options?.maxParts;
+    useEffect(() => {
+        if (maxParts != null && maxParts >= 0) {
+            const current = partsRef.current;
+            if (current.length > maxParts) {
+                mutateParts(current.slice(current.length - maxParts));
+            }
+        }
+    }, [maxParts, mutateParts]);
     const triggerRequest = useCallback(async () => {
         try {
             if (!runId || !apiClient) {
@@ -424,7 +444,7 @@ function useRealtimeStreamImplementation(runId, streamKey, options) {
             }
             const abortController = new AbortController();
             abortControllerRef.current = abortController;
-            await processRealtimeStream(runId, streamKey, apiClient, mutateParts, partsRef, setError, onData, abortControllerRef, timeoutInSeconds, startIndex, throttleInMs ?? 16);
+            await processRealtimeStream(runId, streamKey, apiClient, mutateParts, partsRef, setError, onData, abortControllerRef, timeoutInSeconds, startIndex, throttleInMs ?? 16, from, maxParts, lastEventIdRef, (id) => mutateLastEventId(id, false), startEventId !== undefined ? String(startEventId) : undefined, onParts);
         }
         catch (err) {
             // Ignore abort errors as they are expected.
@@ -449,9 +469,14 @@ function useRealtimeStreamImplementation(runId, streamKey, options) {
         setError,
         setIsComplete,
         onData,
+        onParts,
         timeoutInSeconds,
         startIndex,
+        startEventId,
         throttleInMs,
+        from,
+        maxParts,
+        mutateLastEventId,
     ]);
     const requestSubscription = useStableRequestCallback(triggerRequest);
     useEffect(() => {
@@ -466,7 +491,7 @@ function useRealtimeStreamImplementation(runId, streamKey, options) {
             stop();
         };
     }, [runId, stop, options?.enabled, requestSubscription]);
-    return { parts: parts ?? initialPartsFallback, error, stop };
+    return { parts: parts ?? initialPartsFallback, lastEventId: persistedLastEventId, error, stop };
 }
 async function processRealtimeBatch(batchId, apiClient, mutateRunsData, existingRunsRef, onError, abortControllerRef) {
     const subscription = apiClient.subscribeToBatch(batchId, {
@@ -560,21 +585,39 @@ async function processRealtimeRun(runId, filters, apiClient, mutateRunData, onEr
         mutateRunData(part);
     }
 }
-async function processRealtimeStream(runId, streamKey, apiClient, mutatePartsData, existingPartsRef, onError, onData, abortControllerRef, timeoutInSeconds, startIndex, throttleInMs) {
+async function processRealtimeStream(runId, streamKey, apiClient, mutatePartsData, existingPartsRef, onError, onData, abortControllerRef, timeoutInSeconds, startIndex, throttleInMs, from, maxParts, lastEventIdRef, persistLastEventId, userLastEventId, onParts) {
     try {
+        const resumeFromEventId = lastEventIdRef?.current ??
+            userLastEventId ??
+            (startIndex ? (startIndex - 1).toString() : undefined);
+        const partsQueue = createThrottledQueue(async (batch) => {
+            const combined = [...existingPartsRef.current, ...batch.map((part) => part.chunk)];
+            const bounded = maxParts != null && maxParts >= 0 && combined.length > maxParts
+                ? combined.slice(combined.length - maxParts)
+                : combined;
+            existingPartsRef.current = bounded;
+            mutatePartsData(bounded);
+            if (persistLastEventId && lastEventIdRef?.current) {
+                persistLastEventId(lastEventIdRef.current);
+            }
+            onParts?.(batch);
+        }, throttleInMs);
         const stream = await apiClient.fetchStream(runId, streamKey, {
             signal: abortControllerRef.current?.signal,
             timeoutInSeconds,
-            lastEventId: startIndex ? (startIndex - 1).toString() : undefined,
+            lastEventId: resumeFromEventId,
+            from: startIndex !== undefined ? undefined : from,
+            onPart: (part) => {
+                if (part.id && lastEventIdRef) {
+                    lastEventIdRef.current = part.id;
+                }
+                partsQueue.add(part);
+            },
         });
-        // Throttle the stream
-        const streamQueue = createThrottledQueue(async (parts) => {
-            mutatePartsData([...existingPartsRef.current, ...parts]);
-        }, throttleInMs);
         for await (const part of stream) {
             onData(part);
-            streamQueue.add(part);
         }
+        await partsQueue.flush();
     }
     catch (err) {
         if (err.name === "AbortError") {