@pipedog/core 0.0.0 → 0.1.0

package/dist/utils/file_resolver.js

@@ -0,0 +1,314 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/file_resolver.py
+/**
+ * Resolution of file URLs in an LLM context into bytes the provider can consume.
+ *
+ * A file reaches the context as a URL — `pipecat:<id>` from the development
+ * runner's upload endpoint, `gs://`/`s3://` from cloud storage, or plain
+ * `http(s)`. Whether that URL can be passed to the LLM provider as-is, or must
+ * first be fetched by this server and inlined as bytes, depends on the provider
+ * (each adapter declares what it can consume) and on who can reach the URL.
+ * `FileResolver` is the fetching half of that decision: it downloads the
+ * bytes when the provider can't, using the configured `FileStorage` for URLs
+ * the storage backend minted and plain HTTP for the rest, guarded by an SSRF
+ * reachability policy.
+ *
+ * The context itself is never modified: everything the resolver produces —
+ * downloaded bytes, base64 data URLs, reachability verdicts — is held in
+ * in-memory caches on the resolver, keyed by URL, where adapters read it
+ * synchronously during context conversion. The caches make resolved files
+ * provider-neutral: LLM services that share one resolver instance (e.g. services
+ * switched between mid-session) reuse each other's downloads, re-deciding only
+ * the per-provider question of whether a URL can be passed through.
+ *
+ * The resolver is configured on the LLM service (`fileResolver`), which
+ * resolves and converts in one step right before each completion — see
+ * `BaseLLMAdapter.getLlmInvocationParams`.
+ */
+import { abortable, currentSignal, rethrowIfCancelled, TimeoutError } from "@pipedog/asyncio";
+import { FileNotFoundError } from "./file_storage.js";
+import { classifyUrlReachability, defaultAllowedFileUrlNetworks, IPNetwork, UrlReachability, } from "./security/ssrf.js";
+const DEFAULT_MAX_FETCH_BYTES = 50 * 1024 * 1024;
+const DEFAULT_FETCH_TIMEOUT_SECS = 30;
+/** Raised when a file URL in the LLM context cannot be resolved to bytes. */
+export class FileResolverError extends Error {
+    name = "FileResolverError";
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function bytesToBase64(data) {
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < data.length; i += chunk) {
+        binary += String.fromCharCode(...data.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function base64ToBytes(encoded) {
+    const binary = atob(encoded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        out[i] = binary.charCodeAt(i);
+    }
+    return out;
+}
+function concatBytes(chunks, total) {
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+function isTimeout(e) {
+    return (e instanceof TimeoutError ||
+        (typeof e === "object" && e !== null && e.name === "TimeoutError"));
+}
+/**
+ * Fetches and caches the bytes behind file URLs the LLM provider can't fetch itself.
+ *
+ * Handles three kinds of URL:
+ *
+ * - `data:` URLs are decoded directly.
+ * - `http(s)` URLs are fetched by this server, but only when the resolved
+ *   address is publicly routable or falls within `allowedUrlNetworks` —
+ *   a client-supplied URL must not be able to point this server at arbitrary
+ *   private address space (SSRF). Redirects are refused rather than followed.
+ * - Any other scheme is delegated to `fileStorage`, which resolves the
+ *   URLs it minted (`pipecat:<id>` for `LocalFileStorage`; a custom backend
+ *   resolves whatever `save()` returned, e.g. `gs://` with the deployment's
+ *   own credentials).
+ *
+ * Each URL is fetched once and served from the cache afterwards: a URL is
+ * assumed to identify one immutable piece of content, the same assumption
+ * the rest of the web's caches make. Content that changes should live at a
+ * new URL (uploads through the development runner mint a fresh URL per
+ * upload; a cache-busting query string works for external URLs), or use
+ * `forget` when the application knows a URL's content changed. Note the flip
+ * side for URLs a provider consumes directly: the provider fetches those
+ * itself, on its own schedule, so their freshness is out of this resolver's
+ * hands entirely.
+ *
+ * A stored file whose backend sets `deleteAfterLoad` is deleted only after
+ * its bytes are cached, so the cache entry becomes the surviving copy — which
+ * is why LLM services that may consume the same files (e.g. services switched
+ * between mid-session) should share one resolver instance rather than each
+ * constructing their own. Scope a resolver to one session: an instance shared
+ * across sessions would hold every session's files in memory and stretch the
+ * one-fetch-per-URL assumption across all of them.
+ *
+ * Subclass and override `fetch` to support additional schemes or
+ * credentialed fetches beyond what the storage backend provides.
+ */
+export class FileResolver {
+    _fileStorage;
+    _allowedUrlNetworks;
+    _maxFetchBytes;
+    _fetchTimeoutSecs;
+    // Everything below is keyed by the URL exactly as it appears in the
+    // context, including data: URLs.
+    _bytesCache = new Map();
+    _dataUrlCache = new Map();
+    _reachabilityCache = new Map();
+    constructor(options = {}) {
+        this._fileStorage = options.fileStorage ?? null;
+        const allowedUrlNetworks = options.allowedUrlNetworks ?? defaultAllowedFileUrlNetworks();
+        this._allowedUrlNetworks = allowedUrlNetworks.map((net) => new IPNetwork(net));
+        this._maxFetchBytes = options.maxFetchBytes ?? DEFAULT_MAX_FETCH_BYTES;
+        this._fetchTimeoutSecs = options.fetchTimeoutSecs ?? DEFAULT_FETCH_TIMEOUT_SECS;
+    }
+    /** The storage backend used to resolve URLs it minted, if any. */
+    get fileStorage() {
+        return this._fileStorage;
+    }
+    /** Return the cached bytes for `url`, or null if it hasn't been fetched. */
+    cachedBytes(url) {
+        return this._bytesCache.get(url) ?? null;
+    }
+    /**
+     * Return the cached `data:` form for `url`, or null if not prepared.
+     *
+     * A `data:` URL is its own data-URL form.
+     */
+    cachedDataUrl(url) {
+        if (url.startsWith("data:")) {
+            return url;
+        }
+        return this._dataUrlCache.get(url) ?? null;
+    }
+    /** Return the cached reachability verdict for `url`, or null if unclassified. */
+    cachedReachability(url) {
+        return this._reachabilityCache.get(url) ?? null;
+    }
+    /**
+     * Drop everything cached for `url`, forcing a re-fetch on next use.
+     *
+     * For applications that know a URL's content has changed. A forgotten
+     * `deleteAfterLoad` upload can't be re-fetched — its stored copy was
+     * deleted when first cached — so forgetting one makes it unresolvable.
+     *
+     * @param url The URL whose cached content and reachability to drop.
+     */
+    forget(url) {
+        this._bytesCache.delete(url);
+        this._dataUrlCache.delete(url);
+        this._reachabilityCache.delete(url);
+    }
+    /**
+     * Classify who can reach an `http(s)` URL, honoring `allowedUrlNetworks`.
+     *
+     * Classified once per URL; later calls return the cached verdict.
+     */
+    async classify(url) {
+        let cached = this._reachabilityCache.get(url);
+        if (cached === undefined) {
+            cached = await classifyUrlReachability(url, this._allowedUrlNetworks);
+            this._reachabilityCache.set(url, cached);
+        }
+        return cached;
+    }
+    /**
+     * Return the bytes behind `url`, fetching and caching them on first use.
+     *
+     * @param url A `data:` URL, an `http(s)` URL, or a URL minted by the
+     *   configured storage backend. A storage-resolved file is deleted after a
+     *   successful load when the backend sets `deleteAfterLoad` — the bytes are
+     *   cached first, so the cache entry becomes the surviving copy.
+     * @throws FileResolverError If the URL is refused by the reachability
+     *   policy, exceeds the size limit, fails to download, or has a scheme
+     *   nothing is configured to resolve.
+     */
+    async fetch(url) {
+        const cached = this._bytesCache.get(url);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const data = await this._fetchUncached(url);
+        this._bytesCache.set(url, data);
+        return data;
+    }
+    /**
+     * Return the `data:` form of `url`'s bytes, encoding and caching it on first use.
+     *
+     * For adapters whose provider consumes base64 rather than raw bytes, so
+     * the encode happens once rather than on every context conversion.
+     *
+     * @param url A URL whose bytes are cached or fetchable — see `fetch`.
+     * @param mimeType The file's MIME type, used in the data URL.
+     * @throws FileResolverError If the bytes can't be fetched.
+     */
+    async ensureDataUrl(url, mimeType) {
+        if (url.startsWith("data:")) {
+            return url;
+        }
+        let cached = this._dataUrlCache.get(url);
+        if (cached === undefined) {
+            const data = await this.fetch(url);
+            const encoded = bytesToBase64(data);
+            cached = `data:${mimeType};base64,${encoded}`;
+            this._dataUrlCache.set(url, cached);
+        }
+        return cached;
+    }
+    async _fetchUncached(url) {
+        if (url.startsWith("data:")) {
+            return FileResolver._decodeDataUrl(url);
+        }
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            return await this._fetchHttp(url);
+        }
+        if (this._fileStorage !== null) {
+            let data;
+            try {
+                data = await this._fileStorage.load(url);
+            }
+            catch (e) {
+                if (e instanceof FileNotFoundError ||
+                    (typeof e === "object" && e !== null && e.code === "ENOENT")) {
+                    throw new FileResolverError(`File not found in storage: '${url}'`, { cause: e });
+                }
+                throw e;
+            }
+            // The bytes are about to be cached, so a backend whose URLs are
+            // all uploads it owns has no further use for the stored copy.
+            if (this._fileStorage.deleteAfterLoad) {
+                await this._fileStorage.delete(url);
+            }
+            return data;
+        }
+        throw new FileResolverError(`No way to resolve file URL '${url}': configure a FileResolver with a ` +
+            "fileStorage (or a custom fetch) that understands it.");
+    }
+    static _decodeDataUrl(url) {
+        const index = url.indexOf("base64,");
+        if (index < 0) {
+            throw new FileResolverError("Malformed data URL: not enough values to unpack");
+        }
+        try {
+            return base64ToBytes(url.slice(index + "base64,".length));
+        }
+        catch (e) {
+            throw new FileResolverError(`Malformed data URL: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+    async _fetchHttp(url) {
+        const reachability = await this.classify(url);
+        if (reachability === UrlReachability.BLOCKED) {
+            throw new FileResolverError(`Refusing to fetch unreachable URL: '${url}'`);
+        }
+        const timeoutSignal = AbortSignal.timeout(this._fetchTimeoutSecs * 1000);
+        const signal = AbortSignal.any([currentSignal(), timeoutSignal]);
+        try {
+            // Redirects are not followed: re-validating the host on every hop is
+            // more machinery than this needs, and a redirect into unreachable
+            // address space is exactly what classify() above is meant to rule out.
+            const response = await abortable(fetch(url, { redirect: "manual", signal }));
+            if (REDIRECT_STATUSES.has(response.status) || response.type === "opaqueredirect") {
+                throw new FileResolverError(`Refusing to follow redirect fetching file from URL: '${url}'`);
+            }
+            if (!response.ok) {
+                throw new FileResolverError(`Failed to fetch file from URL '${url}': ${response.status}, message='${response.statusText}'`);
+            }
+            const contentLength = response.headers.get("content-length");
+            if (contentLength !== null && Number(contentLength) > this._maxFetchBytes) {
+                throw new FileResolverError(`File at URL exceeds ${this._maxFetchBytes} byte limit`);
+            }
+            // Accumulate chunks and enforce the size cap as they arrive.
+            const chunks = [];
+            let received = 0;
+            const body = response.body;
+            if (body) {
+                const reader = body.getReader();
+                try {
+                    while (true) {
+                        const { done, value } = await abortable(reader.read());
+                        if (done)
+                            break;
+                        received += value.length;
+                        if (received > this._maxFetchBytes) {
+                            throw new FileResolverError(`File at URL exceeds ${this._maxFetchBytes} byte limit`);
+                        }
+                        chunks.push(value);
+                    }
+                }
+                finally {
+                    reader.cancel().catch(() => { });
+                }
+            }
+            return concatBytes(chunks, received);
+        }
+        catch (e) {
+            if (e instanceof FileResolverError)
+                throw e;
+            rethrowIfCancelled(e);
+            if (isTimeout(e) || timeoutSignal.aborted) {
+                throw new FileResolverError(`Timed out fetching file from URL: '${url}'`, { cause: e });
+            }
+            throw new FileResolverError(`Failed to fetch file from URL '${url}': ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+        }
+    }
+}
+//# sourceMappingURL=file_resolver.js.map

package/dist/utils/file_storage.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Pluggable storage for files uploaded by clients and referenced by URL later.
+ *
+ * `FileStorage` is the shared interface between the development runner's
+ * `POST /files` upload endpoint, which saves uploads and hands the resulting
+ * URL back to the client, and the LLM service's `FileResolver`, which loads
+ * the bytes back when the client references that URL in a send-file message.
+ * Passing the same storage instance to both means they agree on where uploads
+ * live without each needing its own copy of the configuration, and lets a
+ * deployment swap in a backend other than local disk by implementing this
+ * interface.
+ *
+ * The URL is the contract: `FileStorage.save` returns one, callers pass it
+ * back unmodified, and each implementation mints whatever form it can later
+ * resolve — `pipecat:<id>` for `LocalFileStorage`, or e.g. `gs://` / `s3://`
+ * for a custom cloud backend (which the LLM provider may then even fetch
+ * itself, without `FileStorage.load` being involved at all).
+ */
+/**
+ * Thrown by `FileStorage.load` when a URL is invalid or no longer stored
+ * (Python's built-in `FileNotFoundError`).
+ */
+export declare class FileNotFoundError extends Error {
+    name: string;
+    readonly code = "ENOENT";
+}
+/** Storage backend for files uploaded by clients and referenced by URL later. */
+export declare abstract class FileStorage {
+    /**
+     * Whether a file should be deleted once its bytes have been consumed
+     * (loaded and inlined into the LLM context by a FileResolver, which then
+     * has no further use for the stored copy). Safe only when every URL this
+     * backend resolves is an upload it owns; leave false for backends whose
+     * URLs may point at shared data (e.g. arbitrary objects in a cloud
+     * bucket), where "read into a conversation" must not mean "destroy".
+     */
+    deleteAfterLoad: boolean;
+    /**
+     * Store a file and return the URL later passed to `load` or `delete`.
+     *
+     * @param filename The original filename, for backends that want to keep it
+     *   (e.g. for content-type sniffing). Storage implementations should not use
+     *   it to derive the returned URL.
+     * @param contents The raw file contents.
+     * @returns A URL identifying the stored file, in whatever form this backend
+     *   can later resolve. Callers must pass it back unmodified to `load` or `delete`.
+     */
+    abstract save(filename: string, contents: Uint8Array): Promise<string>;
+    /**
+     * Return the stored contents for `fileUrl`.
+     *
+     * @param fileUrl A URL previously returned by `save`.
+     * @throws FileNotFoundError If `fileUrl` is invalid or no longer stored.
+     */
+    abstract load(fileUrl: string): Promise<Uint8Array>;
+    /**
+     * Remove the stored file for `fileUrl`, if present.
+     *
+     * @param fileUrl A URL previously returned by `save`.
+     */
+    abstract delete(fileUrl: string): Promise<void>;
+}
+export interface LocalFileStorageOptions {
+    /** Directory to store files in. Created on first save if missing. */
+    folder: string;
+    /**
+     * Maximum number of files to retain; oldest files (by mtime) are deleted
+     * once this is exceeded. Set to 0 to disable trimming.
+     */
+    maxFiles?: number;
+}
+/**
+ * Default storage backend: files on local disk, addressed as `pipecat:<hex>`.
+ *
+ * Suitable for local development and single-process deployments. The
+ * `pipecat:` scheme makes the URLs recognizable in logs and client payloads;
+ * the random hex suffix can't be used for path traversal and doesn't leak the
+ * original filename.
+ *
+ * STUB: disk I/O (`save`, `load`, `delete`, trimming) is not ported, since core
+ * cannot import `node:fs`. URL validation is.
+ */
+export declare class LocalFileStorage extends FileStorage {
+    deleteAfterLoad: boolean;
+    protected static readonly _URL_PREFIX = "pipecat:";
+    protected static readonly _URL_SUFFIX_PATTERN: RegExp;
+    protected _folder: string;
+    protected _maxFiles: number;
+    constructor(options: LocalFileStorageOptions);
+    /** Write `contents` to a new randomly-named file and return its `pipecat:` URL. */
+    save(_filename: string, _contents: Uint8Array): Promise<string>;
+    /** Read and return the contents stored under `fileUrl`. */
+    load(fileUrl: string): Promise<Uint8Array>;
+    /** Delete the file stored under `fileUrl`, if it exists. */
+    delete(fileUrl: string): Promise<void>;
+    /** Validate `fileUrl` and return the on-disk filename it maps to. */
+    protected _resolveSuffix(fileUrl: string): string;
+}
+//# sourceMappingURL=file_storage.d.ts.map

package/dist/utils/file_storage.js

@@ -0,0 +1,100 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/file_storage.py
+/**
+ * Pluggable storage for files uploaded by clients and referenced by URL later.
+ *
+ * `FileStorage` is the shared interface between the development runner's
+ * `POST /files` upload endpoint, which saves uploads and hands the resulting
+ * URL back to the client, and the LLM service's `FileResolver`, which loads
+ * the bytes back when the client references that URL in a send-file message.
+ * Passing the same storage instance to both means they agree on where uploads
+ * live without each needing its own copy of the configuration, and lets a
+ * deployment swap in a backend other than local disk by implementing this
+ * interface.
+ *
+ * The URL is the contract: `FileStorage.save` returns one, callers pass it
+ * back unmodified, and each implementation mints whatever form it can later
+ * resolve — `pipecat:<id>` for `LocalFileStorage`, or e.g. `gs://` / `s3://`
+ * for a custom cloud backend (which the LLM provider may then even fetch
+ * itself, without `FileStorage.load` being involved at all).
+ */
+/**
+ * Thrown by `FileStorage.load` when a URL is invalid or no longer stored
+ * (Python's built-in `FileNotFoundError`).
+ */
+export class FileNotFoundError extends Error {
+    name = "FileNotFoundError";
+    code = "ENOENT";
+}
+/** Storage backend for files uploaded by clients and referenced by URL later. */
+export class FileStorage {
+    /**
+     * Whether a file should be deleted once its bytes have been consumed
+     * (loaded and inlined into the LLM context by a FileResolver, which then
+     * has no further use for the stored copy). Safe only when every URL this
+     * backend resolves is an upload it owns; leave false for backends whose
+     * URLs may point at shared data (e.g. arbitrary objects in a cloud
+     * bucket), where "read into a conversation" must not mean "destroy".
+     */
+    deleteAfterLoad = false;
+}
+const NOT_PORTED = "not ported yet: LocalFileStorage needs filesystem access, which @pipedog/core (runtime-agnostic) does not have";
+/**
+ * Default storage backend: files on local disk, addressed as `pipecat:<hex>`.
+ *
+ * Suitable for local development and single-process deployments. The
+ * `pipecat:` scheme makes the URLs recognizable in logs and client payloads;
+ * the random hex suffix can't be used for path traversal and doesn't leak the
+ * original filename.
+ *
+ * STUB: disk I/O (`save`, `load`, `delete`, trimming) is not ported, since core
+ * cannot import `node:fs`. URL validation is.
+ */
+export class LocalFileStorage extends FileStorage {
+    // Every pipecat: URL is an upload this backend owns, so the file is
+    // removed once its bytes have been consumed into the LLM context.
+    deleteAfterLoad = true;
+    static _URL_PREFIX = "pipecat:";
+    static _URL_SUFFIX_PATTERN = /^[0-9a-f]{32}$/;
+    _folder;
+    _maxFiles;
+    constructor(options) {
+        super();
+        this._folder = options.folder;
+        this._maxFiles = options.maxFiles ?? 10;
+    }
+    /** Write `contents` to a new randomly-named file and return its `pipecat:` URL. */
+    async save(_filename, _contents) {
+        throw new Error(NOT_PORTED);
+    }
+    /** Read and return the contents stored under `fileUrl`. */
+    async load(fileUrl) {
+        this._resolveSuffix(fileUrl);
+        throw new Error(NOT_PORTED);
+    }
+    /** Delete the file stored under `fileUrl`, if it exists. */
+    async delete(fileUrl) {
+        try {
+            this._resolveSuffix(fileUrl);
+        }
+        catch (e) {
+            if (e instanceof FileNotFoundError)
+                return;
+            throw e;
+        }
+        throw new Error(NOT_PORTED);
+    }
+    /** Validate `fileUrl` and return the on-disk filename it maps to. */
+    _resolveSuffix(fileUrl) {
+        const prefix = LocalFileStorage._URL_PREFIX;
+        const suffix = fileUrl.startsWith(prefix) ? fileUrl.slice(prefix.length) : fileUrl;
+        if (!LocalFileStorage._URL_SUFFIX_PATTERN.test(suffix)) {
+            throw new FileNotFoundError(fileUrl);
+        }
+        return suffix;
+    }
+}
+//# sourceMappingURL=file_storage.js.map

package/dist/utils/frame_queue.d.ts

@@ -0,0 +1,36 @@
+/** Frame queue utilities for Pipecat pipeline processors. */
+import { Queue } from "@pipedog/asyncio";
+import type { Frame } from "../frames/frames.ts";
+export type FrameClass<T extends Frame = Frame> = abstract new (...args: any[]) => T;
+/**
+ * A Queue that knows whether any uninterruptible frame is enqueued.
+ *
+ * `reset()` removes every interruptible item and keeps the uninterruptible
+ * ones (`frame.interruptible === false`) in place.
+ *
+ * Items may be raw frames or tuples whose first element is a frame. Pass a
+ * `frameGetter` to extract the frame from each item; queues that also carry
+ * non-frame items should return null from their getter for those.
+ */
+export declare class FrameQueue<T = Frame> extends Queue<T> {
+    protected readonly _frameGetter: (item: T) => Frame | null;
+    constructor(frameGetter?: (item: T) => Frame | null);
+    /** Whether any frame of the given type is in the queue. */
+    hasFrame(frameType: FrameClass): boolean;
+    /** Whether any uninterruptible frame is currently in the queue. */
+    get hasUninterruptible(): boolean;
+    /** Remove all interruptible items, keeping uninterruptible ones. */
+    reset(): void;
+    protected _isUninterruptible(item: T): boolean;
+}
+/**
+ * A priority queue with frame-aware interruption handling. For
+ * `[priority, sequence, frame]` items pass `(item) => item[2]`.
+ */
+export declare class FramePriorityQueue<T = Frame> extends FrameQueue<T> {
+    #private;
+    constructor(frameGetter?: (item: T) => Frame | null, compare?: (a: T, b: T) => number);
+    protected _put(item: T): void;
+    protected _get(): T;
+}
+//# sourceMappingURL=frame_queue.d.ts.map

package/dist/utils/frame_queue.js

@@ -0,0 +1,66 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/frame_queue.py
+/** Frame queue utilities for Pipecat pipeline processors. */
+import { heapPop, heapPush, pythonCompare, Queue } from "@pipedog/asyncio";
+/**
+ * A Queue that knows whether any uninterruptible frame is enqueued.
+ *
+ * `reset()` removes every interruptible item and keeps the uninterruptible
+ * ones (`frame.interruptible === false`) in place.
+ *
+ * Items may be raw frames or tuples whose first element is a frame. Pass a
+ * `frameGetter` to extract the frame from each item; queues that also carry
+ * non-frame items should return null from their getter for those.
+ */
+export class FrameQueue extends Queue {
+    _frameGetter;
+    constructor(frameGetter = (item) => item) {
+        super();
+        this._frameGetter = frameGetter;
+    }
+    /** Whether any frame of the given type is in the queue. */
+    hasFrame(frameType) {
+        return this._items.some((item) => this._frameGetter(item) instanceof frameType);
+    }
+    /** Whether any uninterruptible frame is currently in the queue. */
+    get hasUninterruptible() {
+        return this._items.some((item) => this._isUninterruptible(item));
+    }
+    /** Remove all interruptible items, keeping uninterruptible ones. */
+    reset() {
+        const kept = [];
+        while (!this.empty()) {
+            const item = this.getNowait();
+            if (this._isUninterruptible(item))
+                kept.push(item);
+            this.taskDone();
+        }
+        for (const item of kept)
+            this.putNowait(item);
+    }
+    _isUninterruptible(item) {
+        const frame = this._frameGetter(item);
+        return frame !== null && !frame.interruptible;
+    }
+}
+/**
+ * A priority queue with frame-aware interruption handling. For
+ * `[priority, sequence, frame]` items pass `(item) => item[2]`.
+ */
+export class FramePriorityQueue extends FrameQueue {
+    #compare;
+    constructor(frameGetter = (item) => item, compare = pythonCompare) {
+        super(frameGetter);
+        this.#compare = compare;
+    }
+    _put(item) {
+        heapPush(this._items, item, this.#compare);
+    }
+    _get() {
+        return heapPop(this._items, this.#compare);
+    }
+}
+//# sourceMappingURL=frame_queue.js.map

package/dist/utils/http.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Type of a caller-supplied async HTTP client. The class belongs to whichever
+ * SDK the caller uses, so there is no single type to name here.
+ */
+export type AsyncHTTPClient = unknown;
+type ErrorClass = abstract new (...args: any[]) => Error;
+/**
+ * Timeout exception types to catch around SDK calls. SDKs wrap request-level
+ * timeouts in their own error type, but a timeout while iterating a response
+ * stream surfaces as the underlying transport exception.
+ *
+ * DIVERGENCE: upstream lists httpx/httpx2 `TimeoutException`. Here it is the
+ * asyncio `TimeoutError`; a `fetch` aborted by `AbortSignal.timeout()` rejects
+ * with a `DOMException` named "TimeoutError", which `isTimeoutException`
+ * also recognizes.
+ */
+export declare const TIMEOUT_EXCEPTIONS: readonly ErrorClass[];
+/** Whether `e` is one of `TIMEOUT_EXCEPTIONS` (or a fetch timeout `DOMException`). */
+export declare function isTimeoutException(e: unknown): boolean;
+/** Limits fields accepted by `connectionLimits`. */
+export interface ConnectionLimits {
+    maxConnections?: number | null;
+    maxKeepaliveConnections?: number | null;
+    keepaliveExpiry?: number | null;
+}
+/**
+ * Build a connection-limits object accepted by the HTTP client.
+ *
+ * DIVERGENCE: upstream returns an httpx `Limits` instance. `fetch` has no
+ * such object, so this returns the plain options for an SDK or agent that
+ * reads them field by field.
+ *
+ * @param options Limits fields (`maxConnections`, `maxKeepaliveConnections`,
+ *   `keepaliveExpiry`).
+ * @returns A limits object.
+ */
+export declare function connectionLimits(options?: ConnectionLimits): ConnectionLimits;
+export {};
+//# sourceMappingURL=http.d.ts.map