@cyanheads/hn-mcp-server 0.5.21 → 0.6.0

package/dist/mcp-server/tools/thread-cursor.js

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview The hn_get_thread cursor: the unvisited frontier packed as
+ * base64url over a varint payload, and a decoder that also reads the JSON
+ * format earlier releases issued, accepting every string they accepted.
+ * Anything else decodes to `undefined`.
+ * @module mcp-server/tools/thread-cursor
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+/**
+ * Longest cursor accepted, in characters: over four times the longest a real
+ * thread issues in either format. A longer one is rejected unread.
+ */
+export const MAX_CURSOR_LENGTH = 150_000;
+/** First payload byte of a packed cursor. Any other payload is read as the JSON format. */
+const PACKED_FORMAT = 0x01;
+/** Seven value bits per varint byte, so eight bytes cover every safe integer. */
+const MAX_VARINT_BYTES = 8;
+const utf8 = new TextEncoder();
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true });
+/** Shared by both formats. Each frontier group is `[level, parentId, ...ids]`. */
+const CursorStateSchema = z.object({
+    offset: z.number().int().min(0),
+    itemId: z.number().int(),
+    depth: z.number().int().min(1),
+    frontier: z.array(z.array(z.number().int().min(0)).min(3)).min(1),
+    depthCut: z.literal(true).optional(),
+    story: z.object({ id: z.number().int().min(1), by: z.string().min(1).optional() }).optional(),
+});
+/** The JSON format also carries `limit`, which nothing reads, and never a story. */
+const JsonCursorSchema = CursorStateSchema.omit({ story: true }).extend({
+    limit: z.number().int().min(1),
+});
+const zigzag = (n) => (n < 0 ? -2 * n - 1 : 2 * n);
+const unzigzag = (n) => (n % 2 === 0 ? n / 2 : -(n + 1) / 2);
+/**
+ * Pack a cursor:
+ *
+ * ```text
+ * 0x01                                      format version
+ * varint itemId, depth, offset, depthCut (0|1), groupCount
+ * per (level, parentId) group:
+ *   varint level, zigzag(parentId - itemId), idCount
+ *   zigzag varint per ID: delta from the previous ID, the first from parentId
+ * varint storyId (0 = none or unresolved)
+ *   if non-zero: varint author byte length, then the author as UTF-8
+ * ```
+ *
+ * A run of frontier entries sharing a level and parent forms one group, so
+ * siblings share a header; entries keep their traversal order.
+ */
+export function encodeThreadCursor(state) {
+    const out = [PACKED_FORMAT];
+    const varint = (n) => {
+        let rest = n;
+        while (rest >= 0x80) {
+            out.push((rest % 0x80) + 0x80);
+            rest = Math.floor(rest / 0x80);
+        }
+        out.push(rest);
+    };
+    const groups = [];
+    for (const { id, level, parentId } of state.frontier) {
+        const last = groups.at(-1);
+        if (last?.level === level && last.parentId === parentId)
+            last.ids.push(id);
+        else
+            groups.push({ ids: [id], level, parentId });
+    }
+    varint(state.itemId);
+    varint(state.depth);
+    varint(state.offset);
+    varint(state.depthCut ? 1 : 0);
+    varint(groups.length);
+    for (const { ids, level, parentId } of groups) {
+        varint(level);
+        varint(zigzag(parentId - state.itemId));
+        varint(ids.length);
+        let previous = parentId;
+        for (const id of ids) {
+            varint(zigzag(id - previous));
+            previous = id;
+        }
+    }
+    varint(state.story?.id ?? 0);
+    if (state.story) {
+        const author = utf8.encode(state.story.by ?? '');
+        varint(author.length);
+        for (const byte of author)
+            out.push(byte);
+    }
+    return Buffer.from(out).toString('base64url');
+}
+/**
+ * Read a packed payload into the shape {@link CursorStateSchema} validates,
+ * throwing on one the layout cannot hold. Every loop step consumes at least one
+ * byte or throws, so a count the payload claims never drives more work — or a
+ * larger allocation — than the payload's own length.
+ */
+function unpack(bytes) {
+    let at = 1;
+    const varint = () => {
+        let value = 0;
+        let scale = 1;
+        for (let i = 0; i < MAX_VARINT_BYTES; i++) {
+            const byte = bytes[at++];
+            if (byte === undefined)
+                throw new Error('truncated');
+            value += (byte & 0x7f) * scale;
+            if (byte < 0x80) {
+                if (value > Number.MAX_SAFE_INTEGER)
+                    throw new Error('unsafe integer');
+                return value;
+            }
+            scale *= 0x80;
+        }
+        throw new Error('varint too long');
+    };
+    const itemId = varint();
+    const depth = varint();
+    const offset = varint();
+    const depthCut = varint();
+    if (depthCut > 1)
+        throw new Error('depth-cut flag');
+    const frontier = [];
+    const groupCount = varint();
+    for (let g = 0; g < groupCount; g++) {
+        const level = varint();
+        const parentId = itemId + unzigzag(varint());
+        const group = [level, parentId];
+        const idCount = varint();
+        let previous = parentId;
+        for (let k = 0; k < idCount; k++) {
+            previous += unzigzag(varint());
+            group.push(previous);
+        }
+        frontier.push(group);
+    }
+    const storyId = varint();
+    let story;
+    if (storyId > 0) {
+        const length = varint();
+        if (length > bytes.length - at)
+            throw new Error('author past the payload');
+        const by = strictUtf8.decode(bytes.subarray(at, at + length));
+        at += length;
+        story = { id: storyId, ...(by.length > 0 && { by }) };
+    }
+    if (at !== bytes.length)
+        throw new Error('trailing bytes');
+    return {
+        offset,
+        itemId,
+        depth,
+        frontier,
+        ...(depthCut === 1 && { depthCut: true }),
+        ...(story && { story }),
+    };
+}
+/**
+ * Decode a cursor in either format; `undefined` for anything that is not a
+ * state hn_get_thread can resume — a cursor longer than
+ * {@link MAX_CURSOR_LENGTH}, a payload in neither format, a truncated or
+ * overlong one, or a state that fails validation (a depth past `maxDepth`, a
+ * frontier level at or past its depth). Linear in the cursor's length.
+ *
+ * Both formats are read as earlier releases read the JSON one, so every string
+ * they accepted still decodes to the same state: either base64 alphabet,
+ * padding or none, characters outside the alphabet (whitespace among them)
+ * skipped, and nothing read past the first `=`. A JSON payload is decoded as
+ * UTF-8 with invalid bytes replaced, then parsed, so whitespace around its
+ * tokens and keys it does not use are ignored.
+ */
+export function decodeThreadCursor(cursor, maxDepth) {
+    if (cursor.length > MAX_CURSOR_LENGTH)
+        return;
+    const bytes = Buffer.from(cursor.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+    const packed = bytes[0] === PACKED_FORMAT;
+    let decoded;
+    try {
+        decoded = packed ? unpack(bytes) : JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        return;
+    }
+    const parsed = (packed ? CursorStateSchema : JsonCursorSchema).safeParse(decoded);
+    if (!parsed.success)
+        return;
+    const { offset, itemId, depth, frontier, depthCut, story } = parsed.data;
+    if (depth > maxDepth || frontier.some(([level = depth]) => level >= depth))
+        return;
+    return {
+        offset,
+        itemId,
+        depth,
+        depthCut: depthCut === true,
+        frontier: frontier.flatMap(([level = 0, parentId = 0, ...ids]) => ids.map((id) => ({ id, level, parentId }))),
+        ...(story && { story }),
+    };
+}
+//# sourceMappingURL=thread-cursor.js.map

package/dist/mcp-server/tools/thread-cursor.js.map

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

package/dist/services/hn/hn-service.d.ts

@@ -5,6 +5,17 @@
 import type { Context } from '@cyanheads/mcp-ts-core';
 import { McpError } from '@cyanheads/mcp-ts-core/errors';
 import type { AlgoliaResponse, HnFeedType, HnItem, HnUser } from './types.js';
+/** One attempt's timeout, the body read included. */
+export declare const REQUEST_TIMEOUT_MS = 10000;
+/**
+ * The time budget of one tool call that chains batch fetches, counted from the
+ * call's start and shared by every request in it, retries and backoff included.
+ * One hung fetch's whole retry ladder (four attempts and three backoffs, at most
+ * 48.75 s with jitter) fits, so a single slow item settles as it would unbounded;
+ * the margin under the MCP SDK client's 60-second default request timeout covers
+ * transport and serialization.
+ */
+export declare const CALL_BUDGET_MS = 50000;
 /** Decode numeric and named HTML entities. An undeclared name stays as typed. */
 export declare function decodeHtmlEntities(text: string): string;
 /**
@@ -17,7 +28,7 @@ export declare function decodeHtmlEntities(text: string): string;
  */
 export declare function stripHtml(html: string): string;
 /**
- * {@link stripHtml} for an Algolia highlight snippet, which is the field's HTML
+ * {@link stripHtml} for an Algolia highlight value, which is the field's HTML
  * with `<em>` inserted around matched terms: the `<em>…</em>` markers survive,
  * including inside a link collapsed to its href.
  */
@@ -45,14 +56,28 @@ export declare function dateBoundToEpochMs(bound: string): number;
  * `10:00:00.5` must still admit an item created at `10:00:00`.
  */
 export declare function dateBoundToEpochSeconds(bound: string, rounding?: 'floor' | 'ceil'): number;
+/**
+ * The exclusive `created_at_i` bounds a search sends to Algolia, in Unix
+ * seconds: the start rounded down and the end rounded up, as
+ * {@link dateBoundToEpochSeconds} describes. A bound left unset is absent. The
+ * request and the tool's echo of its criteria both read this one conversion.
+ */
+export declare function dateRangeToEpochSeconds(range: {
+    start?: string | undefined;
+    end?: string | undefined;
+}): {
+    start?: number;
+    end?: number;
+};
 /**
  * One slot of a {@link HnService.fetchItems} batch, in input order.
  *
  * - `item` — HN returned the item. It may be dead or deleted; callers filter.
  * - `absent` — HN answered `null`: no item exists under this ID.
- * - `failed` — the fetch failed after retries, or never started because an
- *   earlier slot was rate-limited. `error` is the classified failure. A later
- *   call may succeed, so a caller reports the ID rather than dropping it.
+ * - `failed` — the fetch failed after retries, the batch's deadline cut it, or
+ *   it never started because an earlier slot was rate-limited or the deadline
+ *   had passed. `error` is the classified failure. A later call may succeed, so
+ *   a caller reports the ID rather than dropping it.
  */
 export type ItemSlot = {
     kind: 'item';
@@ -78,6 +103,18 @@ export declare function settlePage(slots: readonly ItemSlot[]): {
 };
 /** True for the classified 429 `getJson` throws once retries are spent or the wait outlasts them. */
 export declare function isRateLimited(err: unknown): err is McpError;
+/**
+ * True for a failure a deadline caused: a retry ladder it cut short
+ * (`retry_deadline_exceeded`) or a {@link HnService.fetchItems} slot it left
+ * unstarted (`deadline_exceeded`). A hung fetch whose whole ladder ran out
+ * before the deadline is an ordinary `Timeout`, not a cut.
+ */
+export declare function isDeadlineCut(err: unknown): err is McpError;
+/**
+ * The sentence, leading space included, a paged tool's failure notice adds when
+ * the call's time budget cut some of the failed `slots`; empty when it cut none.
+ */
+export declare function timeBudgetCutSentence(slots: readonly ItemSlot[]): string;
 export declare class HnService {
     private readonly concurrencyLimit;
     constructor(concurrencyLimit: number);
@@ -85,19 +122,35 @@ export declare class HnService {
      * GET a JSON document from an upstream, with retries around the full
      * fetch-and-parse pipeline and both failure shapes — non-2xx status and
      * HTML-instead-of-JSON — classified onto a contract reason.
+     *
+     * `deadline`, a `Date.now()` instant, bounds every attempt and backoff
+     * together; past it the call fails with a `Timeout` whose `data.reason` is
+     * `retry_deadline_exceeded`, unless the last attempt failed on an HTTP
+     * status, which keeps its contract reason. A caller abort still wins over it.
+     *
+     * An attempt keeps its full request timeout even with less of the deadline
+     * left: the deadline's own signal then ends it, so a cut always reads as the
+     * deadline's rather than racing an attempt timer set to the same instant.
      */
     private getJson;
-    /** Fetch a single item by ID. Returns null when HN reports the item is missing. */
-    fetchItem(id: number, ctx: Context): Promise<HnItem | null>;
+    /**
+     * Fetch a single item by ID. Returns null when HN reports the item is missing.
+     * `deadline` bounds its retries as in {@link HnService.getJson}.
+     */
+    fetchItem(id: number, ctx: Context, deadline?: number): Promise<HnItem | null>;
     /**
      * Fetch a user profile by username. Returns null when the user does not exist.
      * The username is percent-encoded as a single path segment — an unencoded
      * value containing `/` or dot-segments would otherwise escape the `/user/`
-     * route and resolve to a different Firebase resource.
+     * route and resolve to a different Firebase resource. `deadline` bounds its
+     * retries as in {@link HnService.getJson}.
+     */
+    fetchUser(username: string, ctx: Context, deadline?: number): Promise<HnUser | null>;
+    /**
+     * Fetch a feed's ID array. Throws on upstream failure after retries.
+     * `deadline` bounds its retries as in {@link HnService.getJson}.
      */
-    fetchUser(username: string, ctx: Context): Promise<HnUser | null>;
-    /** Fetch a feed's ID array. Throws on upstream failure after retries. */
-    fetchFeed(type: HnFeedType, ctx: Context): Promise<number[]>;
+    fetchFeed(type: HnFeedType, ctx: Context, deadline?: number): Promise<number[]>;
     /**
      * Batch-fetch items with concurrency limiting: one {@link ItemSlot} per ID,
      * in input order. A per-item failure after exhausted retries fills a
@@ -105,13 +158,21 @@ export declare class HnService {
      * not per-item:
      *
      * - A caller abort rethrows, ending the batch instead of spending the rest of
-     *   the ID list on fetches nobody is waiting for.
+     *   the ID list on fetches nobody is waiting for — including one that lands
+     *   during a retry's backoff, which surfaces as the raw abort reason.
      * - An `upstream_rate_limited` failure stops the batch. Fetches already in
      *   flight settle, and every slot not yet started is reported `failed` with
      *   that error, rather than each running its own retry ladder against a
      *   throttled upstream.
+     *
+     * With a `deadline` (a `Date.now()` instant), a fetch still retrying when it
+     * passes fails its slot with a `Timeout` instead of finishing its ladder, and
+     * no fetch starts past it: every slot not yet started is reported `failed`
+     * with one `Timeout` (`data.reason: 'deadline_exceeded'`), or with the rate
+     * limit when one also stopped the batch. {@link isDeadlineCut} tells both
+     * kinds of cut slot from an ordinary failure.
      */
-    fetchItems(ids: readonly number[], ctx: Context): Promise<ItemSlot[]>;
+    fetchItems(ids: readonly number[], ctx: Context, deadline?: number): Promise<ItemSlot[]>;
     /**
      * Search HN via Algolia. Throws on upstream failure after retries. An omitted
      * `query` sends no `query` param, making a filter-only search; the tags are

package/dist/services/hn/hn-service.d.ts.map

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

package/dist/services/hn/hn-service.js

@@ -2,12 +2,22 @@
  * @fileoverview HN API service — Firebase and Algolia HTTP clients with HTML stripping utilities.
  * @module services/hn/hn-service
  */
-import { invalidParams, JsonRpcErrorCode, McpError, rateLimited, serviceUnavailable, } from '@cyanheads/mcp-ts-core/errors';
+import { invalidParams, JsonRpcErrorCode, McpError, rateLimited, serviceUnavailable, timeout, } from '@cyanheads/mcp-ts-core/errors';
 import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
 import { getServerConfig } from '../../config/server-config.js';
 const HN_API = 'https://hacker-news.firebaseio.com/v0';
 const ALGOLIA_API = 'https://hn.algolia.com/api/v1';
-const REQUEST_TIMEOUT_MS = 10_000;
+/** One attempt's timeout, the body read included. */
+export const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * The time budget of one tool call that chains batch fetches, counted from the
+ * call's start and shared by every request in it, retries and backoff included.
+ * One hung fetch's whole retry ladder (four attempts and three backoffs, at most
+ * 48.75 s with jitter) fits, so a single slow item settles as it would unbounded;
+ * the margin under the MCP SDK client's 60-second default request timeout covers
+ * transport and serialization.
+ */
+export const CALL_BUDGET_MS = 50_000;
 // ---------------------------------------------------------------------------
 // HTML utilities
 // ---------------------------------------------------------------------------
@@ -65,8 +75,7 @@ const PARTIAL_ENTITY = /&#?[0-9A-Za-z]*$/;
  * Replace each `open … close` span, leftmost opener first and the nearest closer
  * after it, with `render(opener, inner)`. An opener with no closer after it ends
  * the scan — no later opener can find one either — so every search runs forward
- * once and a pass stays linear, where a lazy `open([\s\S]*?)close` regex rescans
- * to the end for each unclosed opener.
+ * once and a pass stays linear.
  */
 function replaceSpans(text, open, close, render) {
     let out = '';
@@ -85,8 +94,7 @@ function replaceSpans(text, open, close, render) {
 }
 /**
  * Apply `rewrite` to the text up to its last `>`. No tag can close past that
- * point, and leaving it out keeps a regex from rescanning to the end of the
- * string for every unmatched `<` there.
+ * point, so the rewrite never reads beyond it.
  */
 function throughLastTag(text, rewrite) {
     const end = text.lastIndexOf('>') + 1;
@@ -169,7 +177,7 @@ export function stripHtml(html) {
     return toPlainText(html, false);
 }
 /**
- * {@link stripHtml} for an Algolia highlight snippet, which is the field's HTML
+ * {@link stripHtml} for an Algolia highlight value, which is the field's HTML
  * with `<em>` inserted around matched terms: the `<em>…</em>` markers survive,
  * including inside a link collapsed to its href.
  */
@@ -215,6 +223,18 @@ export function dateBoundToEpochMs(bound) {
 export function dateBoundToEpochSeconds(bound, rounding = 'floor') {
     return Math[rounding](dateBoundToEpochMs(bound) / 1000);
 }
+/**
+ * The exclusive `created_at_i` bounds a search sends to Algolia, in Unix
+ * seconds: the start rounded down and the end rounded up, as
+ * {@link dateBoundToEpochSeconds} describes. A bound left unset is absent. The
+ * request and the tool's echo of its criteria both read this one conversion.
+ */
+export function dateRangeToEpochSeconds(range) {
+    return {
+        ...(range.start ? { start: dateBoundToEpochSeconds(range.start) } : {}),
+        ...(range.end ? { end: dateBoundToEpochSeconds(range.end, 'ceil') } : {}),
+    };
+}
 /**
  * Settle one page of a batch for the paged tools: the live items in input
  * order, and the IDs whose fetch failed. Dead, deleted, and absent slots drop
@@ -242,6 +262,29 @@ export function settlePage(slots) {
 export function isRateLimited(err) {
     return err instanceof McpError && err.data?.reason === 'upstream_rate_limited';
 }
+/**
+ * True for a failure a deadline caused: a retry ladder it cut short
+ * (`retry_deadline_exceeded`) or a {@link HnService.fetchItems} slot it left
+ * unstarted (`deadline_exceeded`). A hung fetch whose whole ladder ran out
+ * before the deadline is an ordinary `Timeout`, not a cut.
+ */
+export function isDeadlineCut(err) {
+    return (err instanceof McpError &&
+        err.code === JsonRpcErrorCode.Timeout &&
+        (err.data?.reason === 'retry_deadline_exceeded' || err.data?.reason === 'deadline_exceeded'));
+}
+/**
+ * The sentence, leading space included, a paged tool's failure notice adds when
+ * the call's time budget cut some of the failed `slots`; empty when it cut none.
+ */
+export function timeBudgetCutSentence(slots) {
+    const failed = slots.filter((slot) => slot.kind === 'failed');
+    const cut = failed.filter((slot) => isDeadlineCut(slot.error)).length;
+    if (cut === 0)
+        return '';
+    const which = cut < failed.length ? `${cut} of them` : failed.length === 1 ? 'it' : 'they';
+    return ` This call's ${CALL_BUDGET_MS / 1000}-second time budget ran out before ${which} loaded.`;
+}
 /** Detect HTML error bodies returned by upstream APIs under rate limiting or maintenance. */
 function isHtmlErrorBody(text) {
     return /^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text);
@@ -340,18 +383,24 @@ function upstreamFailureFor(upstream, status, cause) {
  * (`errorSource: 'FetchHttpError'`) are rewritten. The message drops the
  * upstream URL and the verbatim response body, which stay on the `cause` chain
  * for server-side logs.
+ *
+ * A retry deadline that cuts the ladder short ends it with its own `Timeout`,
+ * the last attempt's failure as its cause. When that attempt failed on an HTTP
+ * status, the status is classified as an exhausted ladder's would be: a 429
+ * still reads as `upstream_rate_limited`, so a batch stops on it.
  */
 async function withUpstreamHttpErrors(upstream, fn) {
     try {
         return await fn();
     }
     catch (err) {
-        if (!(err instanceof McpError) || err.data?.errorSource !== 'FetchHttpError')
+        const failure = err instanceof McpError && err.data?.reason === 'retry_deadline_exceeded' ? err.cause : err;
+        if (!(failure instanceof McpError) || failure.data?.errorSource !== 'FetchHttpError')
             throw err;
-        const status = err.data.status;
+        const status = failure.data.status;
         if (typeof status !== 'number')
             throw err;
-        throw upstreamFailureFor(upstream, status, err);
+        throw upstreamFailureFor(upstream, status, failure);
     }
 }
 // ---------------------------------------------------------------------------
@@ -366,32 +415,51 @@ export class HnService {
      * GET a JSON document from an upstream, with retries around the full
      * fetch-and-parse pipeline and both failure shapes — non-2xx status and
      * HTML-instead-of-JSON — classified onto a contract reason.
+     *
+     * `deadline`, a `Date.now()` instant, bounds every attempt and backoff
+     * together; past it the call fails with a `Timeout` whose `data.reason` is
+     * `retry_deadline_exceeded`, unless the last attempt failed on an HTTP
+     * status, which keeps its contract reason. A caller abort still wins over it.
+     *
+     * An attempt keeps its full request timeout even with less of the deadline
+     * left: the deadline's own signal then ends it, so a cut always reads as the
+     * deadline's rather than racing an attempt timer set to the same instant.
      */
-    getJson(upstream, operation, url, ctx) {
-        return withUpstreamHttpErrors(upstream, () => withRetry(async () => {
-            const res = await fetchWithTimeout(url, REQUEST_TIMEOUT_MS, ctx, {
-                signal: ctx.signal,
-            });
+    getJson(upstream, operation, url, ctx, deadline) {
+        return withUpstreamHttpErrors(upstream, () => withRetry(async ({ signal }) => {
+            const res = await fetchWithTimeout(url, REQUEST_TIMEOUT_MS, ctx, { signal });
             return parseJsonBody(await res.text(), upstream);
-        }, { operation, context: ctx, signal: ctx.signal }));
+        }, {
+            operation,
+            context: ctx,
+            signal: ctx.signal,
+            ...(deadline !== undefined && { deadlineMs: Math.max(0, deadline - Date.now()) }),
+        }));
     }
-    /** Fetch a single item by ID. Returns null when HN reports the item is missing. */
-    fetchItem(id, ctx) {
-        return this.getJson('HN API', 'hn.fetchItem', `${HN_API}/item/${id}.json`, ctx);
+    /**
+     * Fetch a single item by ID. Returns null when HN reports the item is missing.
+     * `deadline` bounds its retries as in {@link HnService.getJson}.
+     */
+    fetchItem(id, ctx, deadline) {
+        return this.getJson('HN API', 'hn.fetchItem', `${HN_API}/item/${id}.json`, ctx, deadline);
     }
     /**
      * Fetch a user profile by username. Returns null when the user does not exist.
      * The username is percent-encoded as a single path segment — an unencoded
      * value containing `/` or dot-segments would otherwise escape the `/user/`
-     * route and resolve to a different Firebase resource.
+     * route and resolve to a different Firebase resource. `deadline` bounds its
+     * retries as in {@link HnService.getJson}.
      */
-    fetchUser(username, ctx) {
-        return this.getJson('HN API', 'hn.fetchUser', `${HN_API}/user/${encodeURIComponent(username)}.json`, ctx);
+    fetchUser(username, ctx, deadline) {
+        return this.getJson('HN API', 'hn.fetchUser', `${HN_API}/user/${encodeURIComponent(username)}.json`, ctx, deadline);
     }
-    /** Fetch a feed's ID array. Throws on upstream failure after retries. */
-    fetchFeed(type, ctx) {
+    /**
+     * Fetch a feed's ID array. Throws on upstream failure after retries.
+     * `deadline` bounds its retries as in {@link HnService.getJson}.
+     */
+    fetchFeed(type, ctx, deadline) {
         const endpoint = type === 'jobs' ? 'jobstories' : `${type}stories`;
-        return this.getJson('HN API', 'hn.fetchFeed', `${HN_API}/${endpoint}.json`, ctx);
+        return this.getJson('HN API', 'hn.fetchFeed', `${HN_API}/${endpoint}.json`, ctx, deadline);
     }
     /**
      * Batch-fetch items with concurrency limiting: one {@link ItemSlot} per ID,
@@ -400,28 +468,38 @@ export class HnService {
      * not per-item:
      *
      * - A caller abort rethrows, ending the batch instead of spending the rest of
-     *   the ID list on fetches nobody is waiting for.
+     *   the ID list on fetches nobody is waiting for — including one that lands
+     *   during a retry's backoff, which surfaces as the raw abort reason.
      * - An `upstream_rate_limited` failure stops the batch. Fetches already in
      *   flight settle, and every slot not yet started is reported `failed` with
      *   that error, rather than each running its own retry ladder against a
      *   throttled upstream.
+     *
+     * With a `deadline` (a `Date.now()` instant), a fetch still retrying when it
+     * passes fails its slot with a `Timeout` instead of finishing its ladder, and
+     * no fetch starts past it: every slot not yet started is reported `failed`
+     * with one `Timeout` (`data.reason: 'deadline_exceeded'`), or with the rate
+     * limit when one also stopped the batch. {@link isDeadlineCut} tells both
+     * kinds of cut slot from an ordinary failure.
      */
-    async fetchItems(ids, ctx) {
+    async fetchItems(ids, ctx, deadline) {
         const slots = new Array(ids.length);
         let rateLimit;
         let next = 0;
+        const pastDeadline = () => deadline !== undefined && Date.now() >= deadline;
         const worker = async () => {
-            while (!rateLimit && next < ids.length) {
+            while (!rateLimit && !pastDeadline() && next < ids.length) {
                 const i = next++;
                 const id = ids[i];
                 if (id == null)
                     continue;
                 try {
-                    const item = await this.fetchItem(id, ctx);
+                    const item = await this.fetchItem(id, ctx, deadline);
                     slots[i] = item ? { kind: 'item', id, item } : { kind: 'absent', id };
                 }
                 catch (error) {
-                    if (error instanceof McpError && error.code === JsonRpcErrorCode.RequestCancelled) {
+                    if (ctx.signal.aborted ||
+                        (error instanceof McpError && error.code === JsonRpcErrorCode.RequestCancelled)) {
                         throw error;
                     }
                     slots[i] = { kind: 'failed', id, error };
@@ -437,12 +515,24 @@ export class HnService {
         const workerCount = Math.min(this.concurrencyLimit, ids.length);
         await Promise.all(Array.from({ length: workerCount }, worker));
         const skipped = ids.length - next;
-        if (rateLimit && skipped > 0) {
+        let unstarted = rateLimit;
+        if (skipped > 0 && rateLimit) {
             ctx.log.warning('Batch stopped: upstream rate-limited, remaining items not fetched', {
                 skipped,
             });
         }
-        return ids.map((id, i) => slots[i] ?? { kind: 'failed', id, error: rateLimit });
+        else if (skipped > 0) {
+            unstarted = timeout('The time budget ran out before this item was fetched.', {
+                reason: 'deadline_exceeded',
+                recovery: {
+                    hint: "The HN API was too slow to answer within this call's time budget. Retry the same call after a short delay.",
+                },
+            });
+            ctx.log.warning('Batch stopped: time budget spent, remaining items not fetched', {
+                skipped,
+            });
+        }
+        return ids.map((id, i) => slots[i] ?? { kind: 'failed', id, error: unstarted });
     }
     /**
      * Search HN via Algolia. Throws on upstream failure after retries. An omitted
@@ -468,12 +558,11 @@ export class HnService {
         const numericFilters = [];
         if (params.minPoints != null)
             numericFilters.push(`points>=${params.minPoints}`);
-        if (params.dateRange?.start) {
-            numericFilters.push(`created_at_i>${dateBoundToEpochSeconds(params.dateRange.start)}`);
-        }
-        if (params.dateRange?.end) {
-            numericFilters.push(`created_at_i<${dateBoundToEpochSeconds(params.dateRange.end, 'ceil')}`);
-        }
+        const bounds = params.dateRange ? dateRangeToEpochSeconds(params.dateRange) : {};
+        if (bounds.start != null)
+            numericFilters.push(`created_at_i>${bounds.start}`);
+        if (bounds.end != null)
+            numericFilters.push(`created_at_i<${bounds.end}`);
         if (numericFilters.length)
             url.searchParams.set('numericFilters', numericFilters.join(','));
         return this.getJson('Algolia', 'hn.search', url, ctx);