@chrischall/mcp-utils 0.7.0 → 0.9.0

package/dist/fetchproxy/index.d.ts.map

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

package/dist/fetchproxy/index.js

@@ -9,7 +9,13 @@
  *
  *  - {@link createFetchproxyTransport} wraps a `FetchproxyServer` in the
  *    `start` / `close` / `status` lifecycle every MCP's transport interface
- *    expects, with optional debug-gated role logging.
+ *    expects, with optional debug-gated role logging, PLUS the opt-in verb
+ *    passthroughs (`fetch` / `requestJson` / `runProbe`) that redfin / homes /
+ *    compass / musescore had each hand-rolled over the server.
+ *  - {@link registerBridgeHealthcheckTool} registers a `<prefix>_healthcheck`
+ *    tool that round-trips a probe path through the bridge and surfaces the
+ *    actionable hint ladder compass + musescore had each copied (with drifted
+ *    internals + a hardcoded-port bug) into `src/tools/healthcheck.ts`.
  *  - {@link createBootstrapOpts} assembles a multi-domain / capture-header /
  *    storage-pointer declaration fragment of `FetchproxyServerOpts`, deriving
  *    the required `capabilities` from the declared bootstrap so callers can't
@@ -18,6 +24,15 @@
  * The adapter shape is identical across 12+ fetchproxy MCPs; collapsing it here
  * keeps the per-row / concurrency / deadline helpers as re-exports rather than
  * re-rolled code.
+ *
+ * Lazy-import note: this whole subpath is gated behind the OPTIONAL
+ * `@fetchproxy/server` peer dep — a consumer only resolves it by importing
+ * `@chrischall/mcp-utils/fetchproxy`, never via the core barrel. The eager
+ * top-level import below therefore never reaches a `.mcpb` bundle that
+ * externalizes `@fetchproxy/server` unless that consumer actually opted into
+ * the bridge. Everything added here routes through that same already-imported
+ * `FetchproxyServer` instance (no NEW top-level `@fetchproxy/server` import),
+ * so the bundle-load smoke posture is unchanged.
  */
 import { FetchproxyServer, FetchproxyBridgeDownError, classifyBridgeError as classifyBridgeErrorKind, } from '@fetchproxy/server';
 import { truncateErrorMessage, messageOf } from '../errors/index.js';
@@ -70,7 +85,7 @@ function envFlagEnabled(key, env = process.env) {
  * });
  */
 export function createFetchproxyTransport(opts) {
-    const { debugEnvVar, env, ...serverOpts } = opts;
+    const { debugEnvVar, env, defaultSubdomain, ...serverOpts } = opts;
     if (!serverOpts.serverName || serverOpts.serverName.trim().length === 0) {
         throw new Error('createFetchproxyTransport: `serverName` is required.');
     }
@@ -79,6 +94,15 @@ export function createFetchproxyTransport(opts) {
     }
     const server = new FetchproxyServer(serverOpts);
     const debug = debugEnvVar !== undefined && envFlagEnabled(debugEnvVar, env ?? process.env);
+    // Apply `defaultSubdomain` only when the call didn't override it AND a
+    // default exists — so an apex-served MCP (no default) sends no `subdomain`
+    // and a per-call override always wins.
+    const withSubdomain = (callOpts) => {
+        if (callOpts.subdomain !== undefined || defaultSubdomain === undefined) {
+            return callOpts;
+        }
+        return { ...callOpts, subdomain: defaultSubdomain };
+    };
     const transport = {
         server,
         get role() {
@@ -98,6 +122,30 @@ export function createFetchproxyTransport(opts) {
         status() {
             return server.bridgeHealth();
         },
+        async fetch(init) {
+            const response = await server.request(init.method, init.path, withSubdomain({
+                ...(init.headers !== undefined ? { headers: init.headers } : {}),
+                ...(init.body !== undefined ? { body: init.body } : {}),
+                ...(init.subdomain !== undefined ? { subdomain: init.subdomain } : {}),
+                ...(init.domain !== undefined ? { domain: init.domain } : {}),
+            }));
+            return { status: response.status, body: response.body, url: response.url };
+        },
+        async requestJson(method, path, init = {}) {
+            const { data, result } = await server.requestJson(method, path, withSubdomain({
+                ...(init.headers !== undefined ? { headers: init.headers } : {}),
+                ...(init.body !== undefined ? { body: init.body } : {}),
+                ...(init.subdomain !== undefined ? { subdomain: init.subdomain } : {}),
+                ...(init.domain !== undefined ? { domain: init.domain } : {}),
+            }));
+            return {
+                data,
+                result: { status: result.status, body: result.body, url: result.url },
+            };
+        },
+        runProbe(fetchFn, probePath) {
+            return server.runProbe(fetchFn, probePath);
+        },
     };
     return transport;
 }
@@ -200,4 +248,133 @@ export function bridgeErrorInfo(err) {
             return { type: 'unknown', message };
     }
 }
+/**
+ * Build the actionable next-step hint from a probe outcome. Order matters:
+ * the specific error kinds win over the generic role-based message, because a
+ * `bridge_down` can fire with `role === null` (the bridge can hand back the
+ * SW-eviction error before `listen()` resolves a role) and the specific hint
+ * must beat the "never bound a role" fallback.
+ *
+ * `port` is the ACTUAL configured bridge port (from `bridgeHealth()`), NOT a
+ * hardcoded literal — this is the audit-bug fix both copies shared.
+ */
+function healthcheckHint(args) {
+    const { hostLabel, prefix, probePath, port } = args;
+    if (args.ok) {
+        return `Bridge round-tripped ${probePath} successfully. If real tools still fail, the problem is downstream of fetchproxy (${hostLabel} redirecting on login, a bot-wall / behavioral challenge, etc.) — not the bridge.`;
+    }
+    if (args.errorKind === 'bridge_down') {
+        const base = `The fetchproxy browser extension's service worker is not responding. Chrome evicts extension service workers after ~30s idle by default — this looks like that case. Wake it by clicking the fetchproxy extension icon (or opening any ${hostLabel} tab and reloading), then retry. If it keeps happening, reload the extension from chrome://extensions.`;
+        return args.bridgeHint ? `${args.bridgeHint} ${base}` : base;
+    }
+    if (args.role === null) {
+        return `The bridge never bound a role. listen() may have failed silently on startup. Check stderr from ${prefix}-mcp for an error during start, and confirm port ${port} isn't blocked.`;
+    }
+    if (args.errorKind === 'timeout') {
+        return `Bridge is alive (role=${args.role}), but the request didn't get a response in time. Either (a) the fetchproxy browser extension isn't connected to this MCP yet — open the extension popup and check for a green dot next to "${prefix}-mcp", or (b) the signed-in ${hostLabel} tab is sleeping / closed. Open ${hostLabel} in your browser, then retry.`;
+    }
+    if (args.errorKind === 'protocol' || args.errorKind === 'http') {
+        return `The bridge returned a protocol error before any HTTP response. Most commonly: no ${hostLabel} tab is open, or the extension declined the request. Open ${hostLabel}, sign in, and retry.`;
+    }
+    return `Unexpected error — see the error.message field for details.`;
+}
+/**
+ * Register a `<prefix>_healthcheck` MCP tool that round-trips `probePath`
+ * through the bridge and reports bridge status + role + timing, plus an
+ * actionable hint ladder on failure.
+ *
+ * The probe loop / error classification / post-probe bridge projection all live
+ * in `transport.runProbe` (the `@fetchproxy/server` primitive); this factory
+ * owns only the tool registration, the result shape, and the hint ladder. The
+ * per-site bits (`prefix`, `probePath`, `hostLabel`, the probe `fetchFn`) are
+ * options.
+ *
+ * @example
+ * registerBridgeHealthcheckTool({
+ *   server, prefix: 'compass', probePath: '/robots.txt',
+ *   hostLabel: 'compass.com', transport,
+ *   probeFn: (p) => client.fetchHtml(p),
+ * });
+ */
+export function registerBridgeHealthcheckTool(args) {
+    const { server, prefix, probePath, hostLabel, transport, probeFn } = args;
+    const probeUrl = `https://${hostLabel}${probePath}`;
+    server.registerTool(`${prefix}_healthcheck`, {
+        title: 'Verify the fetchproxy bridge end-to-end',
+        description: `Round-trips a small public ${hostLabel} URL (${probePath}) through the fetchproxy bridge and returns diagnostics: the bridge's role (host/peer/null), port, version, the elapsed round-trip time, and a plain-English hint distinguishing 'bridge never came up' from 'extension not connected' from 'real ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only, no auth required.`,
+        annotations: {
+            title: 'Verify the fetchproxy bridge end-to-end',
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        inputSchema: {},
+    }, async () => {
+        let probeBody = '';
+        let thrown;
+        const probeResult = await transport.runProbe(async (path) => {
+            try {
+                probeBody = await probeFn(path);
+                return probeBody;
+            }
+            catch (e) {
+                thrown = e;
+                throw e;
+            }
+        }, probePath);
+        const ok = probeResult.ok;
+        const probe = ok
+            ? {
+                url: probeUrl,
+                elapsed_ms: probeResult.elapsed_ms,
+                status: 200,
+                body_length: probeBody.length,
+            }
+            : { url: probeUrl, elapsed_ms: probeResult.elapsed_ms };
+        let error;
+        let bridgeHint;
+        if (probeResult.error) {
+            // `runProbe` already classified the throw into `probeResult.error.kind`
+            // (fetchproxy's raw vocabulary). Trust that as the discriminator —
+            // mapping `'other'` → `'unknown'` to match the envelope — rather than
+            // re-classifying a plain `{kind,message}` object. Use the typed `thrown`
+            // (set by our probe wrapper) only to lift the server-authored
+            // `FetchproxyBridgeDownError.hint`.
+            const kind = probeResult.error.kind === 'other' ? 'unknown' : probeResult.error.kind;
+            bridgeHint =
+                thrown instanceof FetchproxyBridgeDownError ? thrown.hint : undefined;
+            error = {
+                kind,
+                message: probeResult.error.message,
+                ...(bridgeHint !== undefined ? { bridge_hint: bridgeHint } : {}),
+            };
+        }
+        // The post-probe bridge projection omits `lastExtensionMessageAt`; read it
+        // off the live status snapshot (same call, so it's current).
+        const lastExtensionMessageAt = transport.status().lastExtensionMessageAt;
+        const result = {
+            ok,
+            bridge: {
+                ...probeResult.bridge,
+                last_extension_message_at: lastExtensionMessageAt,
+            },
+            probe,
+            ...(error ? { error } : {}),
+            hint: healthcheckHint({
+                ok,
+                role: probeResult.bridge.role,
+                // FIX: the real configured port from bridgeHealth(), not a literal 37149.
+                port: probeResult.bridge.port,
+                hostLabel,
+                prefix,
+                probePath,
+                errorKind: error?.kind,
+                bridgeHint: error?.kind === 'bridge_down' ? bridgeHint : undefined,
+            }),
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
 //# sourceMappingURL=index.js.map

package/dist/fetchproxy/index.js.map

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

package/dist/http/index.d.ts

@@ -161,6 +161,22 @@ export declare class ApiError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
+/**
+ * A status-carrying HTTP error consumers can `throw new` directly — the
+ * directly-constructible parallel to {@link ApiError} (which is only thrown
+ * *inside* {@link createApiClient}). Extends {@link ApiError} so the same
+ * `err instanceof ApiError && err.status === 404` branch works for both, while
+ * its own name/`instanceof UpstreamHttpError` distinguishes the manual throws.
+ *
+ * Consolidates opentable's local `HttpError` and musescore's
+ * `MusescoreHttpError` — structural twins (status-carrying, thrown from a
+ * transport/bridge code path that doesn't go through `createApiClient`, used to
+ * branch on a 404 fallback). Repos that DO route through `createApiClient`
+ * already get {@link ApiError} for free and don't need this.
+ */
+export declare class UpstreamHttpError extends ApiError {
+    constructor(status: number, message: string);
+}
 /**
  * Build a bearer-auth fetch client with one-shot 429 retry, 401 mapping, 204 /
  * empty-body handling, and redacted error formatting.
@@ -257,6 +273,27 @@ export interface ParsedCookieJar {
  * Consolidates the IC/signupgenius cookie-jar logic.
  */
 export declare function parseCookieJar(setCookieHeaders: string[] | string | null | undefined): ParsedCookieJar;
+/**
+ * Parse a *request* `Cookie:` header (`name=value; name2=value2`) into a
+ * name→value map. This is the inbound counterpart to {@link parseCookieJar},
+ * which parses *response* `Set-Cookie` headers (with their attributes and
+ * deletion semantics) — a `Cookie` header has no attributes, just pairs.
+ *
+ * Semantics (matching creditkarma's hand-rolled `extractCookieValue` ×3):
+ *  - splits on `;`, then on the FIRST `=` only, so a value containing `=`
+ *    (e.g. base64 padding `ab==`, or `x=y=z`) is preserved verbatim,
+ *  - trims surrounding whitespace from both name and value,
+ *  - skips fragments with no `=` (bare attributes) or an empty name (`=v`),
+ *  - keeps an empty value when the name is present (`a=` → `{ a: '' }`),
+ *  - on a duplicate name, the last value wins.
+ *
+ * A missing / empty / whitespace-only header yields `{}`.
+ *
+ * Consolidates creditkarma's `extractCookieValue` (single-name lookup ×3) and
+ * the cookie-header pattern-matching in two other repos: `extractCookieValue(h,
+ * name)` is `parseCookieHeader(h)[name] ?? null`.
+ */
+export declare function parseCookieHeader(header: string): Record<string, string>;
 /**
  * Anything {@link CookieJar.absorb} can read `Set-Cookie`s from: the array from
  * `Headers.getSetCookie()`, a single (possibly comma-joined) header string, or
@@ -304,6 +341,17 @@ export declare function decodeJwtExp(token: string): number;
  * header.
  */
 export declare function decodeJwtSessionId(token: string): string | null;
+/**
+ * Generic single-claim extractor for a JWT payload. Returns the raw claim
+ * value (`unknown` — cast or narrow at the call site), or `undefined` for an
+ * undecodable token or an absent claim. Never throws.
+ *
+ * Generalizes the hand-rolled per-claim readers across the fleet (e.g.
+ * creditkarma's `extractGlidFromJwt`): `decodeJwtClaim(token, 'glid')` instead
+ * of a bespoke decode + payload-field pluck. Reuses the same base64url payload
+ * decode as {@link decodeJwtExp} / {@link decodeJwtSessionId}.
+ */
+export declare function decodeJwtClaim(token: string, claim: string): unknown;
 /** Result of {@link validateJwtExpiry}. */
 export interface JwtExpiryStatus {
     /** True when the token is past its `exp` (or undecodable / lacks `exp`). */
@@ -323,4 +371,61 @@ export interface JwtExpiryStatus {
  * reporting `expired: false`, so callers can refresh proactively.
  */
 export declare function validateJwtExpiry(token: string, nowMs?: number): JwtExpiryStatus;
+/** Options for {@link runBoundedBatch}. */
+export interface RunBoundedBatchOptions<T, R> {
+    /**
+     * Overall hard deadline for the WHOLE batch, in milliseconds. When it fires,
+     * any item that hasn't settled is filled by {@link onTimeout} and the batch
+     * returns immediately — unsettled workers are abandoned (left to settle in
+     * the background, never awaited), so a permanently-hung item can't wedge the
+     * call past this bound.
+     */
+    deadlineMs: number;
+    /**
+     * Backfill for an item the deadline cut off before it settled. Receives the
+     * original `item` and its `index` so the placeholder stays identifiable and
+     * re-runnable (the zillow `pending`-row pattern). Called only for unsettled
+     * slots.
+     */
+    onTimeout: (item: T, index: number) => R;
+    /**
+     * Backfill for an item whose `worker` REJECTED (threw). A worker error is
+     * isolated to its own slot — it never rejects the batch or cascades onto
+     * other items. Defaults to `onTimeout(item, index)` (a rejected worker is
+     * treated like a timeout) so a caller that doesn't care needn't distinguish;
+     * supply `onError` to tell a genuine failure apart from a deadline cutoff.
+     */
+    onError?: (item: T, index: number, err: unknown) => R;
+    /**
+     * Max workers in flight at once. Defaults to unbounded (all items started
+     * immediately). Use it to bound fan-out against a rate-limited upstream.
+     */
+    concurrency?: number;
+    /**
+     * Injectable timer (for tests). Defaults to `setTimeout`. Must invoke `cb`
+     * after roughly `ms`, returning a handle passed to {@link clearTimer}.
+     */
+    setTimer?: (ms: number, cb: () => void) => unknown;
+    /** Injectable clear paired with {@link setTimer}. Defaults to `clearTimeout`. */
+    clearTimer?: (handle: unknown) => void;
+}
+/**
+ * Run `worker` over `items` with an overall hard deadline and a per-item
+ * timeout-backfill, returning a full-length, input-ordered array with exactly
+ * one result per item.
+ *
+ * Each item gets an index-addressable slot. Work is raced against `deadlineMs`;
+ * when the deadline fires first, every still-unsettled slot is filled by
+ * `onTimeout(item, index)` and the batch resolves immediately — the in-flight
+ * workers are abandoned (and signalled via their `AbortSignal`) rather than
+ * awaited, so a single hung row can't keep the whole call (and the MCP request
+ * deadline behind it) pinned open. When everything settles before the deadline,
+ * the timer is cleared and every slot holds its real result.
+ *
+ * Generalises zillow's bulk-tool `runWithDeadline` (`zillow_bulk_get` /
+ * `zillow_resolve_addresses`, issues #98/#78): the slot-array + overall-deadline
+ * + `pending`-backfill shape, now with the worker + concurrency folded in and an
+ * injectable timer for deterministic tests.
+ */
+export declare function runBoundedBatch<T, R>(items: T[], worker: (item: T, signal?: AbortSignal) => Promise<R>, opts: RunBoundedBatchOptions<T, R>): Promise<R[]>;
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.d.ts.map

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

package/dist/http/index.js

@@ -66,6 +66,26 @@ export class ApiError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * A status-carrying HTTP error consumers can `throw new` directly — the
+ * directly-constructible parallel to {@link ApiError} (which is only thrown
+ * *inside* {@link createApiClient}). Extends {@link ApiError} so the same
+ * `err instanceof ApiError && err.status === 404` branch works for both, while
+ * its own name/`instanceof UpstreamHttpError` distinguishes the manual throws.
+ *
+ * Consolidates opentable's local `HttpError` and musescore's
+ * `MusescoreHttpError` — structural twins (status-carrying, thrown from a
+ * transport/bridge code path that doesn't go through `createApiClient`, used to
+ * branch on a 404 fallback). Repos that DO route through `createApiClient`
+ * already get {@link ApiError} for free and don't need this.
+ */
+export class UpstreamHttpError extends ApiError {
+    constructor(status, message) {
+        super(status, message);
+        this.name = 'UpstreamHttpError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 function hostOf(baseUrl) {
     try {
         return new URL(baseUrl).host;
@@ -336,6 +356,44 @@ export function parseCookieJar(setCookieHeaders) {
     const cookieHeader = [...jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
     return { cookies, cookieHeader };
 }
+// ---------------------------------------------------------------------------
+// parseCookieHeader
+// ---------------------------------------------------------------------------
+/**
+ * Parse a *request* `Cookie:` header (`name=value; name2=value2`) into a
+ * name→value map. This is the inbound counterpart to {@link parseCookieJar},
+ * which parses *response* `Set-Cookie` headers (with their attributes and
+ * deletion semantics) — a `Cookie` header has no attributes, just pairs.
+ *
+ * Semantics (matching creditkarma's hand-rolled `extractCookieValue` ×3):
+ *  - splits on `;`, then on the FIRST `=` only, so a value containing `=`
+ *    (e.g. base64 padding `ab==`, or `x=y=z`) is preserved verbatim,
+ *  - trims surrounding whitespace from both name and value,
+ *  - skips fragments with no `=` (bare attributes) or an empty name (`=v`),
+ *  - keeps an empty value when the name is present (`a=` → `{ a: '' }`),
+ *  - on a duplicate name, the last value wins.
+ *
+ * A missing / empty / whitespace-only header yields `{}`.
+ *
+ * Consolidates creditkarma's `extractCookieValue` (single-name lookup ×3) and
+ * the cookie-header pattern-matching in two other repos: `extractCookieValue(h,
+ * name)` is `parseCookieHeader(h)[name] ?? null`.
+ */
+export function parseCookieHeader(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(';')) {
+        const eqIdx = part.indexOf('=');
+        if (eqIdx < 0)
+            continue; // bare attribute fragment, no `=`
+        const name = part.slice(0, eqIdx).trim();
+        if (name === '')
+            continue; // missing name (leading `=`)
+        out[name] = part.slice(eqIdx + 1).trim();
+    }
+    return out;
+}
 /** Normalize a {@link SetCookieSource} to individual `Set-Cookie` strings. */
 function setCookieEntries(source) {
     if (source == null)
@@ -450,6 +508,22 @@ export function decodeJwtSessionId(token) {
     const sid = payload['session_id'] ?? payload['sid'];
     return typeof sid === 'string' ? sid : null;
 }
+/**
+ * Generic single-claim extractor for a JWT payload. Returns the raw claim
+ * value (`unknown` — cast or narrow at the call site), or `undefined` for an
+ * undecodable token or an absent claim. Never throws.
+ *
+ * Generalizes the hand-rolled per-claim readers across the fleet (e.g.
+ * creditkarma's `extractGlidFromJwt`): `decodeJwtClaim(token, 'glid')` instead
+ * of a bespoke decode + payload-field pluck. Reuses the same base64url payload
+ * decode as {@link decodeJwtExp} / {@link decodeJwtSessionId}.
+ */
+export function decodeJwtClaim(token, claim) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return undefined;
+    return payload[claim];
+}
 /** Tokens within this many seconds of `exp` are flagged as near-expiry. */
 const NEAR_EXPIRY_SKEW_SEC = 300;
 /**
@@ -481,4 +555,88 @@ export function validateJwtExpiry(token, nowMs = Date.now()) {
     }
     return { expired: false, expiresIn };
 }
+/**
+ * Run `worker` over `items` with an overall hard deadline and a per-item
+ * timeout-backfill, returning a full-length, input-ordered array with exactly
+ * one result per item.
+ *
+ * Each item gets an index-addressable slot. Work is raced against `deadlineMs`;
+ * when the deadline fires first, every still-unsettled slot is filled by
+ * `onTimeout(item, index)` and the batch resolves immediately — the in-flight
+ * workers are abandoned (and signalled via their `AbortSignal`) rather than
+ * awaited, so a single hung row can't keep the whole call (and the MCP request
+ * deadline behind it) pinned open. When everything settles before the deadline,
+ * the timer is cleared and every slot holds its real result.
+ *
+ * Generalises zillow's bulk-tool `runWithDeadline` (`zillow_bulk_get` /
+ * `zillow_resolve_addresses`, issues #98/#78): the slot-array + overall-deadline
+ * + `pending`-backfill shape, now with the worker + concurrency folded in and an
+ * injectable timer for deterministic tests.
+ */
+export function runBoundedBatch(items, worker, opts) {
+    const slots = Array.from({ length: items.length });
+    const settled = new Array(items.length).fill(false);
+    // An item whose worker threw: backfilled via onError (default onTimeout) at
+    // finish, distinct from a slot the deadline simply never reached.
+    const errored = new Array(items.length).fill(false);
+    const errorVals = new Array(items.length);
+    // Nothing to do — never arm a timer for an empty batch.
+    if (items.length === 0)
+        return Promise.resolve([]);
+    const setTimer = opts.setTimer ?? ((ms, cb) => setTimeout(cb, ms));
+    const clearTimer = opts.clearTimer ?? ((h) => clearTimeout(h));
+    const controller = new AbortController();
+    // Bounded fan-out: a pool of `limit` runners pulling the next index off a
+    // shared cursor. limit >= items.length (or unset) means "all at once".
+    const limit = opts.concurrency && opts.concurrency > 0
+        ? Math.min(opts.concurrency, items.length)
+        : items.length;
+    const runAll = async () => {
+        let cursor = 0;
+        const runner = async () => {
+            for (;;) {
+                const index = cursor;
+                cursor += 1;
+                if (index >= items.length)
+                    return;
+                // Isolate a worker rejection to its own slot: record it and continue
+                // pulling the next item, so one bad row neither rejects the batch nor
+                // strands the items this runner hasn't reached yet.
+                try {
+                    slots[index] = await worker(items[index], controller.signal);
+                    settled[index] = true;
+                }
+                catch (err) {
+                    errored[index] = true;
+                    errorVals[index] = err;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: limit }, () => runner()));
+    };
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            clearTimer(handle);
+            // Signal abandoned workers so a cooperative worker can stop early.
+            if (!controller.signal.aborted)
+                controller.abort();
+            const onError = opts.onError ?? ((item, index) => opts.onTimeout(item, index));
+            resolve(items.map((item, index) => {
+                if (settled[index])
+                    return slots[index];
+                if (errored[index])
+                    return onError(item, index, errorVals[index]);
+                return opts.onTimeout(item, index);
+            }));
+        };
+        const handle = setTimer(opts.deadlineMs, finish);
+        // Abandon (never await) the fan-out on the deadline path; on full settle,
+        // finish() clears the timer and returns the real results.
+        void runAll().then(finish, finish);
+    });
+}
 //# sourceMappingURL=index.js.map