@cyanheads/hn-mcp-server 0.5.21 → 0.6.0

package/dist/mcp-server/tools/definitions/get-thread.tool.js

@@ -4,19 +4,32 @@
  * @module mcp-server/tools/definitions/get-thread.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { invalidParams, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
-import { decodeCursor, encodeCursor } from '@cyanheads/mcp-ts-core/utils';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { escapeMarkdownInline, markdown } from '@cyanheads/mcp-ts-core/utils';
 import { escapeInline, quoteBody } from '../markdown-escape.js';
-import { decodeHtmlEntities, getHnService, isRateLimited, normalizeUrl, stripHtml, } from '../../../services/hn/hn-service.js';
-/** Largest `maxComments` accepts, mirrored in the input schema. */
-const MAX_COMMENTS = 200;
-/** Largest `depth` accepts, mirrored in the input schema. */
-const MAX_DEPTH = 10;
+import { byteLength, enrichmentBytes, fitsBudget, longestFittingPrefix, RESPONSE_BUDGET_TEXT, } from '../response-budget.js';
+import { servedAtCap } from '../served-at-cap.js';
+import { decodeThreadCursor, encodeThreadCursor, } from '../thread-cursor.js';
+import { CALL_BUDGET_MS, decodeHtmlEntities, getHnService, isDeadlineCut, isRateLimited, normalizeUrl, REQUEST_TIMEOUT_MS, stripHtml, } from '../../../services/hn/hn-service.js';
+/** Most comments one call returns; a larger `maxComments` is served at this cap. */
+const MAX_COMMENTS_CAP = 200;
+/** Largest `maxComments` accepted; anything above it is rejected. */
+const MAX_COMMENTS_CEILING = 1000;
 /**
- * Byte budget for the rendered `format()` text. Checked between comments, so a
- * page never ends mid-comment, and the first comment on a page is always kept.
+ * Most reply levels one call resolves; a larger `depth` is served at this cap.
+ * Every issued cursor carries a depth at or below it, so it also bounds the
+ * depth a cursor may claim.
  */
-const RESPONSE_BUDGET_BYTES = 64_000;
+const DEPTH_CAP = 10;
+/** Largest `depth` accepted; anything above it is rejected. */
+const DEPTH_CEILING = 100;
+/**
+ * Most dead or deleted comments a notice names when the depth limit cut their
+ * replies and a larger depth still reaches the rest. At the depth cap an ID is
+ * the only way into those replies, so every one is named — at most the items
+ * one call examines.
+ */
+const OMITTED_IDS_NAMED = 10;
 /** Most comments one batch fetches — bounds the fetches a size cut leaves unused. */
 const FETCH_CHUNK = 25;
 /**
@@ -25,6 +38,18 @@ const FETCH_CHUNK = 25;
  * them would run unbounded.
  */
 const MAX_ITEMS_EXAMINED = 1_000;
+/**
+ * Most `parent` links one call follows to find a comment root's story. The
+ * deepest comment in 22 of HN's largest threads is 32 links below its story.
+ */
+const MAX_STORY_HOPS = 64;
+/**
+ * The story lookup ends this long after the call starts, its retries and
+ * backoff included, so a slow root fetch leaves it less time rather than
+ * stretching the call. It is the lookup's slice of the call's
+ * {@link CALL_BUDGET_MS}, leaving the traversal at least the rest.
+ */
+const STORY_LOOKUP_DEADLINE_MS = 20_000;
 // ---------------------------------------------------------------------------
 // Schemas
 // ---------------------------------------------------------------------------
@@ -53,11 +78,18 @@ const ItemSchema = z
     url: z.string().optional().describe('External link URL.'),
     text: z.string().optional().describe('Body text (HTML stripped).'),
     score: z.number().optional().describe('Upvote count.'),
-    descendants: z.number().optional().describe('Total comment count.'),
+    descendants: z
+        .number()
+        .optional()
+        .describe("HN's count of live comments in the thread; dead and deleted comments are not counted."),
     parent: z
         .number()
         .optional()
         .describe('For a comment root, the ID of the story or comment it replies to — pass it as itemId for the context above.'),
+    storyId: z
+        .number()
+        .optional()
+        .describe('For a comment root, the ID of the story or poll its discussion belongs to — pass it as itemId for the whole thread, or as storyId to hn_search_content. Absent for other roots, and when the story could not be found (notice says why).'),
     poll: z.number().optional().describe('For a poll-option root, the ID of its poll.'),
     parts: z.array(z.number()).optional().describe('For a poll root, its option IDs in HN order.'),
     deleted: z
@@ -81,19 +113,21 @@ const CommentSchema = z
     time: z.number().optional().describe('Unix timestamp.'),
     text: z.string().optional().describe('Comment text (HTML stripped).'),
     depth: z.number().describe('Nesting level (0 = direct reply to root).'),
-    parentId: z.number().describe('Parent item ID.'),
+    parentId: z
+        .number()
+        .describe('Parent item ID: the root or another comment. It can name a dead or deleted comment, which this list omits while still returning its replies; pass that ID as itemId to see it marked.'),
     childCount: z
         .number()
         .describe('Number of direct child comments (may exceed what was resolved).'),
     isOp: z
         .literal(true)
         .optional()
-        .describe('Present and `true` when the comment author matches the root item author (OP replying within their own thread). Omitted otherwise — including when either author is missing. Most threads carry no OP replies, so absence is the common case; treat missing as "not OP" rather than unknown.'),
+        .describe('Present and `true` when the comment author submitted the story or poll the thread belongs to (OP replying within their own thread) — for a comment root, the story at item.storyId. Omitted otherwise, including when either author is missing. Most threads carry no OP replies, so absence usually means "not OP"; it means unknown when the thread\'s root has no author (a deleted story, for example) or when notice says replies are not marked.'),
 })
     .describe('A single comment in the thread with its tree position.');
 // ---------------------------------------------------------------------------
-// Rendering — format() and the size budget share these, so the budget measures
-// exactly the text format() produces.
+// Rendering — format() and the response budget share these, so the budget
+// measures exactly the text format() produces.
 // ---------------------------------------------------------------------------
 const TYPE_LABELS = {
     story: 'Story',
@@ -104,8 +138,6 @@ const TYPE_LABELS = {
 };
 /** Separator format() places between the root block and the first comment. */
 const COMMENTS_DIVIDER = '\n---\n';
-const utf8 = new TextEncoder();
-const byteLength = (text) => utf8.encode(text).byteLength;
 /** Heading that names the root's type, state, and — for a poll option — its poll. */
 function rootHeading(item) {
     const state = item.deleted ? '[deleted] ' : item.dead ? '[dead] ' : '';
@@ -135,6 +167,7 @@ function renderRoot(item) {
         `id:${item.id}`,
         `type:${item.type}`,
         item.parent != null ? `parent:${item.parent}` : null,
+        item.storyId != null ? `story:${item.storyId}` : null,
         item.poll != null ? `poll:${item.poll}` : null,
         item.parts?.length ? `parts:${item.parts.join(',')}` : null,
         item.score != null ? `${item.score} pts` : null,
@@ -175,75 +208,67 @@ function renderThread(item, comments) {
     }
     return parts.join('\n');
 }
-const CursorStateSchema = z
-    .object({
-    offset: z.number().int().min(0),
-    limit: z.number().int().min(1),
-    itemId: z.number().int(),
-    depth: z.number().int().min(1).max(MAX_DEPTH),
-    /** Each group is `[level, parentId, ...ids]`. */
-    frontier: z.array(z.array(z.number().int().min(0)).min(3)).min(1),
-    depthCut: z.literal(true).optional(),
-})
-    .refine((state) => state.frontier.every(([level = state.depth]) => level < state.depth));
-function encodeThreadCursor(state) {
-    const groups = [];
-    let group;
-    for (const { id, level, parentId } of state.frontier) {
-        if (group?.[0] === level && group[1] === parentId) {
-            group.push(id);
-        }
-        else {
-            group = [level, parentId, id];
-            groups.push(group);
-        }
-    }
-    return encodeCursor({
-        offset: state.offset,
-        limit: state.limit,
-        itemId: state.itemId,
-        depth: state.depth,
-        frontier: groups,
-        ...(state.depthCut && { depthCut: true }),
-    });
-}
-function malformedCursor(cause) {
-    return invalidParams('cursor is not one hn_get_thread issued, or it was altered.', {
-        recovery: {
-            hint: 'Pass nextCursor exactly as a previous hn_get_thread call returned it, or omit cursor to start the thread from the top.',
-        },
-    }, { cause });
-}
-/** Decode and validate a cursor; anything this tool did not issue is an input error. */
-function readCursor(cursor, ctx) {
-    let decoded;
-    try {
-        decoded = decodeCursor(cursor, ctx);
-    }
-    catch (error) {
-        throw malformedCursor(error);
-    }
-    const parsed = CursorStateSchema.safeParse(decoded);
-    if (!parsed.success)
-        throw malformedCursor(parsed.error);
-    const { offset, itemId, depth, frontier, depthCut } = parsed.data;
+/** Bytes format() adds before the first comment, and between two comments. */
+const DIVIDER_BYTES = byteLength(`\n${COMMENTS_DIVIDER}\n`);
+const SEPARATOR_BYTES = byteLength(COMMENT_SEPARATOR);
+/** The content[] trailer's string fields render here, so the response budget sizes them as sent. */
+const codeSpan = (value) => markdown()
+    .inlineCode(value ?? '')
+    .build();
+const threadTrailer = {
+    failedIds: { render: (ids) => `**Failed to load:** ${(ids ?? []).join(', ')}` },
+    truncationReason: { render: (reason) => `**truncationReason:** ${codeSpan(reason)}` },
+    nextCursor: { render: (cursor) => `**nextCursor:** ${codeSpan(cursor)}` },
+};
+/**
+ * The page `walk` serves at `index`: `marks[index]`, or its end at
+ * `marks.length`. The end stops as the walk did. A page cut back to an earlier
+ * mark leaves everything after it unvisited, so it stops on `size` — or on
+ * `rate_limited` when a rate limit had already failed a fetch by then.
+ */
+function pageAt(walk, index) {
+    const mark = walk.marks[index] ?? walk.end;
+    const rest = walk.levels.flatMap((queue, level) => level < mark.level
+        ? []
+        : queue.slice(level === mark.level ? mark.head : 0, mark.lengths[level]));
+    const stop = mark === walk.end
+        ? walk.stop
+        : mark.rateLimit
+            ? 'rate_limited'
+            : rest.length > 0
+                ? 'size'
+                : mark.timeCut
+                    ? 'time'
+                    : undefined;
     return {
-        offset,
-        itemId,
-        depth,
-        depthCut: depthCut === true,
-        frontier: frontier.flatMap(([level = 0, parentId = 0, ...ids]) => ids.map((id) => ({ id, level, parentId }))),
+        comments: walk.comments.slice(0, mark.comments),
+        failed: walk.failed.slice(0, mark.failed),
+        liveDepthCut: mark.liveDepthCut,
+        omittedDead: mark.omittedDead,
+        omittedDeleted: mark.omittedDeleted,
+        omittedDepthCut: walk.omittedDepthCut.slice(0, mark.omittedDepthCut),
+        pageBytes: mark.pageBytes,
+        rateLimit: mark.rateLimit,
+        rest,
+        stop,
     };
 }
 /**
  * Ranked BFS over the frontier: every comment at one depth before any at the
  * next, and HN's kids order within each parent. Fetches in chunks no larger
  * than the comments still wanted, so filtered and failed items never push a
- * later sibling out of the page — anything unvisited stays in `rest`.
+ * later sibling out of the page — anything unvisited stays queued.
  *
- * Stops on `maxComments`, the item ceiling, the byte budget, or a rate limit.
- * After a rate limit nothing more is fetched: every level below would pay its
- * own retry ladder against a throttled upstream.
+ * Stops on `maxComments`, the item ceiling, the response budget, a rate limit,
+ * or the call's time budget. The budget check here sizes the page alone, on
+ * both surfaces, and keeps the first comment whatever its size; the enrichment
+ * is known only once the walk stops, so the handler fits it by serving the page
+ * at an earlier mark. After a rate limit nothing more is fetched: every level
+ * below would pay its own retry ladder against a throttled upstream. No batch
+ * is sent with less than one request timeout left before `deadline`, so a fetch
+ * the deadline cuts has always had a full attempt to answer; an entry held back
+ * stays queued. A batch the deadline cut, the last one included, stops the walk
+ * on `time`, so its failed entries ride a cursor.
  */
 async function walkThread(hn, ctx, args) {
     const levels = Array.from({ length: args.depth }, () => []);
@@ -251,25 +276,61 @@ async function walkThread(hn, ctx, args) {
         levels[entry.level]?.push(entry);
     const comments = [];
     const failed = [];
-    let { rateLimit, usedBytes } = args;
+    let { page, rateLimit } = args;
     let omittedDeleted = 0;
     let omittedDead = 0;
-    let depthCut = false;
+    let liveDepthCut = false;
+    const omittedDepthCut = [];
     let examined = 0;
+    let timeCut = false;
     let stop;
+    /** The level being read, and its next entry; every level above is read. */
+    let atLevel = 0;
+    let atHead = 0;
+    const marks = [];
+    const mark = () => ({
+        comments: comments.length,
+        failed: failed.length,
+        head: atHead,
+        lengths: levels.map((queue) => queue.length),
+        level: atLevel,
+        liveDepthCut,
+        omittedDead,
+        omittedDeleted,
+        omittedDepthCut: omittedDepthCut.length,
+        pageBytes: page,
+        rateLimit,
+        timeCut,
+    });
+    /** Queue a visited comment's replies one level down; true when the depth limit cut them instead. */
+    const enqueueKids = (c, level) => {
+        if (!c.kids?.length)
+            return false;
+        const next = levels[level + 1];
+        if (!next)
+            return true;
+        next.push(...c.kids.map((id) => ({ id, level: level + 1, parentId: c.id })));
+        return false;
+    };
     walk: for (const [level, queue] of levels.entries()) {
-        while (queue.length > 0) {
+        atLevel = level;
+        atHead = 0;
+        while (atHead < queue.length) {
             if (rateLimit)
                 stop = 'rate_limited';
             else if (comments.length >= args.maxComments)
                 stop = 'count';
             else if (examined >= MAX_ITEMS_EXAMINED)
                 stop = 'examined';
+            else if (args.deadline - Date.now() < REQUEST_TIMEOUT_MS)
+                stop = 'time';
             if (stop)
                 break walk;
-            const batch = queue.slice(0, Math.min(args.maxComments - comments.length, FETCH_CHUNK, MAX_ITEMS_EXAMINED - examined));
+            const head = atHead;
+            const batch = queue.slice(head, head +
+                Math.min(args.maxComments - comments.length, FETCH_CHUNK, MAX_ITEMS_EXAMINED - examined));
             examined += batch.length;
-            const slots = await hn.fetchItems(batch.map((entry) => entry.id), ctx);
+            const slots = await hn.fetchItems(batch.map((entry) => entry.id), ctx, args.deadline);
             let visited = 0;
             for (const [i, entry] of batch.entries()) {
                 const slot = slots[i];
@@ -285,57 +346,97 @@ async function walkThread(hn, ctx, args) {
                         depth: level,
                         parentId: entry.parentId,
                         childCount: c.kids?.length ?? 0,
-                        ...(c.by != null && c.by === args.rootBy && { isOp: true }),
+                        ...(c.by != null && c.by === args.opAuthor && { isOp: true }),
+                    };
+                    /** The comment's rendered block and its JSON array element, each with its separator. */
+                    const first = comments.length === 0;
+                    const grown = {
+                        contentBytes: page.contentBytes +
+                            byteLength(renderComment(comment)) +
+                            (first ? DIVIDER_BYTES : SEPARATOR_BYTES),
+                        structuredBytes: page.structuredBytes + byteLength(JSON.stringify(comment)) + (first ? 0 : 1),
                     };
-                    const bytes = byteLength(renderComment(comment)) +
-                        (comments.length === 0
-                            ? byteLength(`\n${COMMENTS_DIVIDER}\n`)
-                            : byteLength(COMMENT_SEPARATOR));
-                    if (comments.length > 0 && usedBytes + bytes > RESPONSE_BUDGET_BYTES) {
+                    if (!first && !fitsBudget(grown)) {
                         stop = 'size';
                         break;
                     }
                     comments.push(comment);
-                    usedBytes += bytes;
-                    if (c.kids?.length) {
-                        const next = levels[level + 1];
-                        if (next)
-                            next.push(...c.kids.map((id) => ({ id, level: level + 1, parentId: c.id })));
-                        else
-                            depthCut = true;
-                    }
+                    page = grown;
+                    if (enqueueKids(c, level))
+                        liveDepthCut = true;
+                    atHead = head + i + 1;
+                    marks.push(mark());
                 }
                 else if (slot.kind === 'failed') {
                     failed.push(entry);
                     if (isRateLimited(slot.error))
                         rateLimit ??= slot.error;
+                    else if (isDeadlineCut(slot.error))
+                        timeCut = true;
                 }
                 else if (slot.kind === 'item') {
+                    /** Omitted, but its live replies are still owed at their true depth. */
                     if (slot.item.deleted)
                         omittedDeleted++;
                     else
                         omittedDead++;
+                    if (enqueueKids(slot.item, level))
+                        omittedDepthCut.push(slot.item.id);
                 }
                 visited++;
             }
-            queue.splice(0, visited);
+            atHead = head + visited;
             if (stop)
                 break walk;
         }
     }
-    /** A rate limit on the last batch still leaves its failed entries to resume. */
+    /** A rate limit or a time cut on the last batch still leaves its failed entries to resume. */
     if (!stop && rateLimit && failed.length > 0)
         stop = 'rate_limited';
-    return {
-        comments,
-        depthCut,
-        failed,
-        omittedDead,
-        omittedDeleted,
-        rateLimit,
-        rest: levels.flat(),
-        stop,
-    };
+    else if (!stop && timeCut)
+        stop = 'time';
+    return { comments, end: mark(), failed, levels, marks, omittedDepthCut, stop };
+}
+/**
+ * Find the story or poll a comment root belongs to by following `parent` links
+ * up from it, one request per link, all bounded by one `deadline`. A failed,
+ * missing, or parentless ancestor, the hop ceiling, or the deadline ends the
+ * lookup with a `gap` instead of failing the call; a cancellation propagates.
+ */
+async function findStory(hn, ctx, root, deadline) {
+    const outOfTime = 'the lookup ran out of time';
+    let next = root.parent;
+    let below = 'it';
+    let hops = 0;
+    while (next != null) {
+        if (hops === MAX_STORY_HOPS) {
+            return { hops, gap: `it sits more than ${MAX_STORY_HOPS} levels below its story` };
+        }
+        if (Date.now() >= deadline)
+            return { hops, gap: outOfTime, transient: true };
+        hops++;
+        const [slot] = await hn.fetchItems([next], ctx, deadline);
+        if (slot?.kind === 'failed') {
+            if (isRateLimited(slot.error)) {
+                return {
+                    hops,
+                    gap: 'the HN API is rate-limiting this server',
+                    rateLimit: slot.error,
+                    transient: true,
+                };
+            }
+            const gap = Date.now() >= deadline ? outOfTime : `ancestor ${next} failed to load`;
+            return { hops, gap, transient: true };
+        }
+        if (slot?.kind !== 'item')
+            return { hops, gap: `ancestor ${next} does not exist` };
+        if (slot.item.type !== 'comment') {
+            return { hops, story: { id: slot.item.id, by: slot.item.by } };
+        }
+        below = `ancestor ${slot.item.id}`;
+        next = slot.item.parent;
+    }
+    return { hops, gap: `HN lists no parent for ${below}` };
 }
 function projectOption(option) {
     return {
@@ -346,12 +447,17 @@ function projectOption(option) {
         ...(option.dead && { dead: true }),
     };
 }
-/** A 429's `Retry-After`, worded for a notice. */
+/**
+ * A 429's `Retry-After`, worded for a notice. A notice is authored Markdown and
+ * the header is upstream text, so an HTTP-date (or anything else) is escaped.
+ */
 function waitFor(rateLimit) {
     const retryAfter = rateLimit?.data?.retryAfter;
     if (typeof retryAfter !== 'string')
         return 'several seconds';
-    return /^\d+$/.test(retryAfter) ? `${retryAfter} seconds` : `until ${retryAfter}`;
+    return /^\d+$/.test(retryAfter)
+        ? `${retryAfter} seconds`
+        : `until ${escapeMarkdownInline(retryAfter)}`;
 }
 const plural = (n, one, many = `${one}s`) => (n === 1 ? one : many);
 // ---------------------------------------------------------------------------
@@ -371,8 +477,8 @@ export const getThread = tool('hn_get_thread', {
         {
             reason: 'invalid_cursor',
             code: JsonRpcErrorCode.InvalidParams,
-            when: 'The cursor was issued for a different itemId than the one passed with it.',
-            recovery: 'Pass the cursor with the same itemId it was returned for, or omit cursor to start this item from the top.',
+            when: 'The cursor is not one this tool issued, was altered, or was issued for a different itemId than the one passed with it.',
+            recovery: 'Pass nextCursor unchanged, with the same itemId it was returned for, or omit cursor to start this item from the top.',
             severity: 'notice',
         },
         {
@@ -424,16 +530,16 @@ export const getThread = tool('hn_get_thread', {
             .number()
             .int()
             .min(0)
-            .max(MAX_DEPTH)
+            .max(DEPTH_CEILING)
             .default(3)
-            .describe(`How many levels of replies to resolve. 0 = just the item, no comments. 1 = direct replies only. Replies below this depth are never fetched — to read them, raise depth or call again with a specific comment's itemId to drill into its subtree. Ignored when cursor is set: the depth the cursor was issued with applies.`),
+            .describe(`How many levels of replies to resolve, at most ${DEPTH_CAP} per call. 0 = just the item, no comments. 1 = direct replies only. A larger value is served at ${DEPTH_CAP}. Replies below the depth served are never fetched — to read them, raise depth up to ${DEPTH_CAP}, or call again with a comment from the deepest level returned, or one notice names, as itemId to drill into its subtree. Ignored when cursor is set: the depth the cursor was issued with applies.`),
         maxComments: z
             .number()
             .int()
             .min(1)
-            .max(MAX_COMMENTS)
+            .max(MAX_COMMENTS_CEILING)
             .default(50)
-            .describe(`Maximum comments in one response, across all depth levels. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops at a fixed 64,000-byte text budget. When either limit stops the traversal, nextCursor continues it.`),
+            .describe(`Maximum comments in one response, across all depth levels, at most ${MAX_COMMENTS_CAP} per call. A larger value is served at ${MAX_COMMENTS_CAP}, and nextCursor continues from there. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. A response also stops between comments to stay within a fixed ${RESPONSE_BUDGET_TEXT}-byte budget on each surface — all content[] text, nextCursor and the rest of the trailer included, and the structuredContent JSON — though its first comment is always returned whole. When either limit stops the traversal, nextCursor continues it.`),
         cursor: z
             .string()
             .optional()
@@ -452,47 +558,64 @@ export const getThread = tool('hn_get_thread', {
         totalAvailable: z
             .number()
             .optional()
-            .describe("HN's total comment count for the root (descendants), which also counts dead and deleted comments. Absent for comment and job roots."),
+            .describe("HN's count of live comments in the thread (descendants); dead and deleted comments are not counted. Absent for comment and job roots."),
         truncated: z
             .boolean()
             .optional()
-            .describe('True when comments remain unread: reachable through nextCursor (truncationReason count, size, or rate_limited), or below the depth limit (depth). Absent on a terminal page — including a thread that loads in full at exactly maxComments.'),
+            .describe('True when comments remain unread: reachable through nextCursor (truncationReason count, size, rate_limited, or time), or below the depth limit (depth). Absent on a terminal page — including a thread that loads in full at exactly maxComments.'),
         truncationReason: z
-            .enum(['count', 'size', 'depth', 'rate_limited'])
+            .enum(['count', 'size', 'depth', 'rate_limited', 'time'])
             .optional()
-            .describe('Why the traversal stopped short: count = maxComments (or the 1,000-item ceiling per call) was reached; size = the 64,000-byte response budget was reached; rate_limited = the HN API throttled the fetches; depth = replies lie below the depth limit, which nextCursor does not reach — raise depth or pass a comment id as itemId. When a cursor reason and a depth cut both apply, the cursor reason is reported.'),
+            .describe(`Why the traversal stopped short: count = maxComments (or the 1,000-item ceiling per call) was reached; size = the page stopped between comments to keep content[] and structuredContent each within the ${RESPONSE_BUDGET_TEXT}-byte response budget; rate_limited = the HN API throttled the fetches; time = the call's ${CALL_BUDGET_MS / 1000}-second time budget ran short because the HN API answered slowly or not at all; depth = replies lie below the depth limit, which nextCursor does not reach — raise depth or pass a comment id as itemId. When a cursor reason and a depth cut both apply, the cursor reason is reported.`),
         nextCursor: z
             .string()
             .optional()
-            .describe('Pass as cursor, with the same itemId, to continue from the next unseen comment. Present when truncationReason is count, size, or rate_limited; absent on the last page.'),
+            .describe('Pass as cursor, with the same itemId, to continue from the next unseen comment. Present when truncationReason is count, size, rate_limited, or time; absent on the last page.'),
         shown: z.number().optional().describe('Number of comments returned.'),
-        cap: z.number().optional().describe('The maxComments cap that was applied.'),
+        cap: z
+            .number()
+            .optional()
+            .describe(`The maxComments value served: as passed, or ${MAX_COMMENTS_CAP} when maxComments was above that cap.`),
         failedIds: z
             .array(z.number())
             .optional()
-            .describe('Comment and poll-option IDs whose fetch failed after retries, so neither they nor their replies are in this response. They are not deleted or missing and may load on a later call. Failed comments ride in nextCursor and are retried when you continue; without one, call again, or pass an ID as itemId to fetch that comment and its replies. Absent when everything the traversal reached loaded.'),
+            .describe(`Comment and poll-option IDs whose fetch failed after retries or ran past the call's ${CALL_BUDGET_MS / 1000}-second time budget, so neither they nor their replies are in this response. They are not deleted or missing and may load on a later call. Failed comments ride in nextCursor and are retried when you continue; without one, call again, or pass an ID as itemId to fetch that comment and its replies. Absent when everything the traversal reached loaded.`),
         notice: z
             .string()
             .optional()
-            .describe('Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, or rate-limit stop, or a larger depth or a comment id as itemId for a depth cut. Absent when nothing was dropped, failed, or left unread.'),
-    },
-    enrichmentTrailer: {
-        failedIds: { render: (ids) => `**Failed to load:** ${(ids ?? []).join(', ')}` },
+            .describe('Traversal context: counts of deleted/dead comments dropped, the IDs that failed to load and how to retry them, then what stopped the traversal and how to continue — nextCursor for a count, size, rate-limit, or time-budget stop, or a larger depth or a comment id as itemId for a depth cut — noting when the maxComments or depth that stopped it was served at its per-call cap. Dead or deleted comments whose replies the depth limit cut are named by id, to pass as itemId, on the page that reaches them, since comments omits them. Absent when nothing was dropped, failed, or left unread.'),
     },
+    enrichmentTrailer: threadTrailer,
     async handler(input, ctx) {
-        const resume = input.cursor ? readCursor(input.cursor, ctx) : undefined;
+        const startedAt = Date.now();
+        /** Bounds every request below — root, story lookup, poll options, every batch. */
+        const deadline = startedAt + CALL_BUDGET_MS;
+        const resume = input.cursor ? decodeThreadCursor(input.cursor, DEPTH_CAP) : undefined;
+        if (input.cursor && !resume) {
+            throw ctx.fail('invalid_cursor', 'cursor is not one hn_get_thread issued, or it was altered.', { itemId: input.itemId });
+        }
         if (resume && resume.itemId !== input.itemId) {
             throw ctx.fail('invalid_cursor', `This cursor continues item ${resume.itemId}, not item ${input.itemId}.`, { itemId: input.itemId });
         }
         const hn = getHnService();
-        const root = await hn.fetchItem(input.itemId, ctx);
+        const root = await hn.fetchItem(input.itemId, ctx, deadline);
         if (!root) {
             throw ctx.fail('item_not_found', `Item ${input.itemId} not found`, { itemId: input.itemId });
         }
+        /**
+         * OP on a comment root means the author of the story above it. A cursor
+         * carries the story an earlier page found; one issued before it was found
+         * looks again.
+         */
+        const lookup = root.type !== 'comment'
+            ? undefined
+            : resume?.story
+                ? { hops: 0, story: resume.story }
+                : await findStory(hn, ctx, root, startedAt + STORY_LOOKUP_DEADLINE_MS);
         const options = [];
         const failedOptionIds = [];
         let optionRateLimit;
-        for (const slot of root.parts?.length ? await hn.fetchItems(root.parts, ctx) : []) {
+        for (const slot of root.parts?.length ? await hn.fetchItems(root.parts, ctx, deadline) : []) {
             if (slot.kind === 'item') {
                 options.push(projectOption(slot.item));
             }
@@ -518,110 +641,194 @@ export const getThread = tool('hn_get_thread', {
             score: root.score,
             descendants: root.descendants,
             ...(root.parent != null && { parent: root.parent }),
+            ...(lookup?.story && { storyId: lookup.story.id }),
             ...(root.poll != null && { poll: root.poll }),
             ...(root.parts && root.parts.length > 0 && { parts: root.parts }),
             ...(root.deleted && { deleted: true }),
             ...(root.dead && { dead: true }),
             ...(options.length > 0 && { options }),
         };
-        const depth = resume?.depth ?? input.depth;
+        const depth = resume?.depth ?? Math.min(input.depth, DEPTH_CAP);
+        const maxComments = Math.min(input.maxComments, MAX_COMMENTS_CAP);
         const seed = resume?.frontier ??
             (depth > 0 ? (root.kids ?? []).map((id) => ({ id, level: 0, parentId: root.id })) : []);
-        const walk = await walkThread(hn, ctx, {
+        const traversal = await walkThread(hn, ctx, {
+            deadline,
             depth,
-            maxComments: input.maxComments,
-            rateLimit: optionRateLimit,
-            rootBy: root.by,
+            maxComments,
+            opAuthor: lookup ? lookup.story?.by : root.by,
+            page: {
+                contentBytes: byteLength(renderRoot(item)),
+                structuredBytes: byteLength(JSON.stringify({ item, comments: [] })),
+            },
+            rateLimit: optionRateLimit ?? lookup?.rateLimit,
             seed,
-            usedBytes: byteLength(renderRoot(item)),
         });
-        const { comments, stop } = walk;
+        const totalAvailable = root.descendants;
+        /** The enrichment serving `walk`, every field in the order it is written. */
+        const enrichmentFor = (walk) => {
+            const { comments, stop } = walk;
+            const totalLoaded = comments.length;
+            /** Comments returned across every page so far, this one included. */
+            const loadedSoFar = (resume?.offset ?? 0) + totalLoaded;
+            const failedCommentIds = walk.failed.map((entry) => entry.id);
+            const failedIds = [...failedCommentIds, ...failedOptionIds];
+            const omittedCut = walk.omittedDepthCut;
+            const depthCut = walk.liveDepthCut || omittedCut.length > 0 || resume?.depthCut === true;
+            /** Failed comments lead the cursor, so continuing retries them rather than skipping them. */
+            const nextCursor = stop &&
+                encodeThreadCursor({
+                    offset: loadedSoFar,
+                    itemId: input.itemId,
+                    depth,
+                    frontier: [...walk.failed, ...walk.rest],
+                    depthCut,
+                    ...(lookup?.story && { story: lookup.story }),
+                });
+            const noticeParts = [];
+            if (lookup?.gap) {
+                const retry = !lookup.transient
+                    ? ''
+                    : nextCursor
+                        ? ' Continuing with nextCursor retries the lookup.'
+                        : lookup.rateLimit
+                            ? ` Wait ${waitFor(lookup.rateLimit)}, then call again.`
+                            : ' Call again to retry.';
+                noticeParts.push(`Could not find the story this comment belongs to: ${lookup.gap}. storyId is absent and replies by the story's author are not marked isOp.${retry}`);
+            }
+            else if (lookup?.story && !lookup.story.by) {
+                noticeParts.push(`The story this comment belongs to (id ${lookup.story.id}) has no author on record, so no reply is marked isOp.`);
+            }
+            if (walk.omittedDeleted > 0 || walk.omittedDead > 0) {
+                noticeParts.push(`${walk.omittedDeleted} deleted, ${walk.omittedDead} dead — omitted from this view.`);
+            }
+            if (failedCommentIds.length > 0) {
+                const n = failedCommentIds.length;
+                const retry = nextCursor
+                    ? `nextCursor carries ${plural(n, 'it', 'them')}, so continuing retries ${plural(n, 'it', 'them')}; or pass an id as itemId to fetch that comment and its replies.`
+                    : 'Call again to retry, or pass an id as itemId to fetch that comment and its replies.';
+                noticeParts.push(`Could not fetch ${n} ${plural(n, 'comment')} (${plural(n, 'id')} ${failedCommentIds.join(', ')}); ${plural(n, 'its', 'their')} replies were not reached either. ${retry}`);
+            }
+            if (failedOptionIds.length > 0) {
+                const n = failedOptionIds.length;
+                noticeParts.push(`Could not fetch ${n} poll ${plural(n, 'option')} (${plural(n, 'id')} ${failedOptionIds.join(', ')}). Call again to retry.`);
+            }
+            const loaded = totalAvailable != null ? ` with ${loadedSoFar}/${totalAvailable} comments loaded` : '';
+            const resumeHint = 'Pass nextCursor as cursor, with the same itemId, to continue.';
+            /** Below the depth cap a larger depth reaches every omitted subtree, so a few names do. */
+            const named = depth < DEPTH_CAP ? omittedCut.slice(0, OMITTED_IDS_NAMED) : omittedCut;
+            const unnamed = omittedCut.length - named.length;
+            const omittedIds = `${plural(omittedCut.length, 'id')} ${named.join(', ')}${unnamed > 0 ? `, and ${unnamed} more` : ''}`;
+            switch (stop) {
+                case 'count':
+                    noticeParts.push(`Stopped at maxComments ${maxComments}${loaded}.`, ...(input.maxComments > MAX_COMMENTS_CAP
+                        ? [servedAtCap('maxComments', input.maxComments, MAX_COMMENTS_CAP)]
+                        : []), resumeHint);
+                    break;
+                case 'examined':
+                    noticeParts.push(`Stopped after examining ${MAX_ITEMS_EXAMINED.toLocaleString('en-US')} items in one call${loaded}. ${resumeHint}`);
+                    break;
+                case 'size':
+                    noticeParts.push(`Stopped at the ${RESPONSE_BUDGET_TEXT}-byte response budget after ${totalLoaded} ${plural(totalLoaded, 'comment')}${loaded}. ${resumeHint}`);
+                    break;
+                case 'rate_limited':
+                    noticeParts.push(`Stopped early: the HN API is rate-limiting this server${loaded}. Wait ${waitFor(walk.rateLimit)}, then pass nextCursor as cursor, with the same itemId, to resume; comments that failed to load are retried first.`);
+                    break;
+                case 'time':
+                    noticeParts.push(`Stopped early to stay within this call's ${CALL_BUDGET_MS / 1000}-second time budget${loaded}. ${resumeHint}`);
+                    break;
+                case undefined:
+                    if (depthCut) {
+                        const raise = depth < DEPTH_CAP ? `Raise depth (max ${DEPTH_CAP}), or pass` : 'Pass';
+                        /** With a cursor its depth applies; the cap is named only when it is what was served. */
+                        const overCap = input.depth > DEPTH_CAP && depth === DEPTH_CAP;
+                        /**
+                         * Name only drill-in targets this page can vouch for. A cut carried from
+                         * an earlier page may have fallen below a comment shown there or one
+                         * named there as omitted, and this page cannot tell which.
+                         */
+                        const targets = [
+                            walk.liveDepthCut
+                                ? `a depth-${depth - 1} comment that shows replies`
+                                : resume?.depthCut
+                                    ? `a depth-${depth - 1} comment with replies on an earlier page (shown there, or named as omitted)`
+                                    : undefined,
+                            omittedCut.length === 1
+                                ? `omitted comment ${omittedCut[0]}`
+                                : omittedCut.length > 1
+                                    ? `an omitted comment with replies (${omittedIds})`
+                                    : undefined,
+                        ].filter((target) => target != null);
+                        noticeParts.push(`The depth limit (${depth}) left replies unread${loaded}.`, ...(overCap ? [servedAtCap('depth', input.depth, DEPTH_CAP)] : []), `${raise} the id of ${targets.join(', or of ')}${targets.length > 1 ? ',' : ''} as itemId to read its subtree.`);
+                    }
+                    else if (resume && totalLoaded === 0 && noticeParts.length === 0) {
+                        noticeParts.push('No comments remain past this cursor; the thread has been read to the end.');
+                    }
+                    break;
+            }
+            /** A page nextCursor continues reports the depth cut later, by flag alone, so it names them now. */
+            if (stop && omittedCut.length > 0) {
+                const n = omittedCut.length;
+                const raiseAll = unnamed > 0 ? `, or raise depth (max ${DEPTH_CAP}) to read them all` : '';
+                noticeParts.push(`${n} omitted ${plural(n, 'comment')} (${omittedIds}) ${plural(n, 'has', 'have')} replies below the depth limit, which nextCursor does not reach; pass ${plural(n, 'its id', 'an id')} as itemId to read ${plural(n, 'its', "that comment's")} subtree${raiseAll}.`);
+            }
+            const notice = noticeParts.join(' ');
+            const capped = stop === 'count' || stop === 'examined' || stop === 'size';
+            return {
+                totalLoaded,
+                ...(totalAvailable != null && { totalAvailable }),
+                ...(failedIds.length > 0 && { failedIds }),
+                ...((capped || stop === 'rate_limited' || stop === 'time' || depthCut) && {
+                    truncated: true,
+                }),
+                ...(capped && { shown: totalLoaded, cap: maxComments }),
+                ...(notice.length > 0 && { notice }),
+                ...((stop || depthCut) && {
+                    truncationReason: stop === 'examined' ? 'count' : (stop ?? 'depth'),
+                    ...(nextCursor && { nextCursor }),
+                }),
+            };
+        };
+        /**
+         * Serve the longest page that fits the response budget on both surfaces,
+         * enrichment included: the walk's own, or one cut back to an earlier
+         * comment. The first comment stays whatever its size.
+         */
+        const served = new Map();
+        const serve = (index) => {
+            let at = served.get(index);
+            if (!at) {
+                const page = pageAt(traversal, index);
+                at = { page, enrichment: enrichmentFor(page) };
+                served.set(index, at);
+            }
+            return at;
+        };
+        const { page, enrichment } = serve(longestFittingPrefix(traversal.marks.length + 1, (index) => {
+            const { page, enrichment } = serve(index);
+            const added = enrichmentBytes(enrichment, threadTrailer);
+            return {
+                contentBytes: page.pageBytes.contentBytes + added.contentBytes,
+                structuredBytes: page.pageBytes.structuredBytes + added.structuredBytes,
+            };
+        }));
         ctx.log.info('Resolved thread', {
             itemId: input.itemId,
-            comments: comments.length,
-            failed: walk.failed.length + failedOptionIds.length,
-            stop,
-        });
-        const totalLoaded = comments.length;
-        /** Comments returned across every page so far, this one included. */
-        const loadedSoFar = (resume?.offset ?? 0) + totalLoaded;
-        const totalAvailable = root.descendants;
-        const failedCommentIds = walk.failed.map((entry) => entry.id);
-        const failedIds = [...failedCommentIds, ...failedOptionIds];
-        ctx.enrich({
-            totalLoaded,
-            ...(totalAvailable != null && { totalAvailable }),
-            ...(failedIds.length > 0 && { failedIds }),
+            comments: page.comments.length,
+            failed: page.failed.length + failedOptionIds.length,
+            stop: page.stop,
+            ...(page.comments.length < traversal.comments.length && {
+                fittedFrom: traversal.comments.length,
+            }),
+            ...(lookup && { storyId: lookup.story?.id, storyHops: lookup.hops }),
         });
-        const depthCut = walk.depthCut || resume?.depthCut === true;
-        /** Failed comments lead the cursor, so continuing retries them rather than skipping them. */
-        const nextCursor = stop &&
-            encodeThreadCursor({
-                offset: loadedSoFar,
-                limit: input.maxComments,
-                itemId: input.itemId,
-                depth,
-                frontier: [...walk.failed, ...walk.rest],
-                depthCut,
-            });
-        const noticeParts = [];
-        if (walk.omittedDeleted > 0 || walk.omittedDead > 0) {
-            noticeParts.push(`${walk.omittedDeleted} deleted, ${walk.omittedDead} dead — omitted from this view.`);
-        }
-        if (failedCommentIds.length > 0) {
-            const n = failedCommentIds.length;
-            const retry = nextCursor
-                ? `nextCursor carries ${plural(n, 'it', 'them')}, so continuing retries ${plural(n, 'it', 'them')}; or pass an id as itemId to fetch that comment and its replies.`
-                : 'Call again to retry, or pass an id as itemId to fetch that comment and its replies.';
-            noticeParts.push(`Could not fetch ${n} ${plural(n, 'comment')} (${plural(n, 'id')} ${failedCommentIds.join(', ')}); ${plural(n, 'its', 'their')} replies were not reached either. ${retry}`);
-        }
-        if (failedOptionIds.length > 0) {
-            const n = failedOptionIds.length;
-            noticeParts.push(`Could not fetch ${n} poll ${plural(n, 'option')} (${plural(n, 'id')} ${failedOptionIds.join(', ')}). Call again to retry.`);
-        }
-        const loaded = totalAvailable != null ? ` with ${loadedSoFar}/${totalAvailable} comments loaded` : '';
-        const resumeHint = 'Pass nextCursor as cursor, with the same itemId, to continue.';
-        switch (stop) {
-            case 'count':
-                noticeParts.push(`Stopped at maxComments ${input.maxComments}${loaded}. ${resumeHint}`);
-                break;
-            case 'examined':
-                noticeParts.push(`Stopped after examining ${MAX_ITEMS_EXAMINED.toLocaleString('en-US')} items in one call${loaded}. ${resumeHint}`);
-                break;
-            case 'size':
-                noticeParts.push(`Stopped at the ${RESPONSE_BUDGET_BYTES.toLocaleString('en-US')}-byte response budget after ${totalLoaded} ${plural(totalLoaded, 'comment')}${loaded}. ${resumeHint}`);
-                break;
-            case 'rate_limited':
-                noticeParts.push(`Stopped early: the HN API is rate-limiting this server${loaded}. Wait ${waitFor(walk.rateLimit)}, then pass nextCursor as cursor, with the same itemId, to resume; comments that failed to load are retried first.`);
-                break;
-            case undefined:
-                if (depthCut) {
-                    const raise = depth < MAX_DEPTH ? `Raise depth (max ${MAX_DEPTH}), or pass` : 'Pass';
-                    noticeParts.push(`The depth limit (${depth}) left replies unread${loaded}. ${raise} the id of a depth-${depth - 1} comment that shows replies as itemId to read its subtree.`);
-                }
-                else if (resume && totalLoaded === 0 && noticeParts.length === 0) {
-                    noticeParts.push('No comments remain past this cursor; the thread has been read to the end.');
-                }
-                break;
-        }
-        const notice = noticeParts.join(' ');
-        if (stop === 'count' || stop === 'examined' || stop === 'size') {
-            ctx.enrich.truncated({ shown: totalLoaded, cap: input.maxComments, guidance: notice });
-        }
-        else if (stop === 'rate_limited' || depthCut) {
-            ctx.enrich({ truncated: true });
-            ctx.enrich.notice(notice);
-        }
-        else if (notice) {
+        const { notice, truncationReason, nextCursor, ...fields } = enrichment;
+        ctx.enrich(fields);
+        if (notice)
             ctx.enrich.notice(notice);
-        }
-        if (stop || depthCut) {
-            ctx.enrich({
-                truncationReason: stop === 'examined' ? 'count' : (stop ?? 'depth'),
-                ...(nextCursor && { nextCursor }),
-            });
-        }
-        return { item, comments };
+        if (truncationReason)
+            ctx.enrich({ truncationReason, ...(nextCursor && { nextCursor }) });
+        return { item, comments: page.comments };
     },
     format: (result) => [{ type: 'text', text: renderThread(result.item, result.comments) }],
 });