@cyanheads/hn-mcp-server 0.5.22 → 0.6.0

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

@@ -5,10 +5,12 @@
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 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 { 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 { decodeHtmlEntities, getHnService, isRateLimited, normalizeUrl, stripHtml, } from '../../../services/hn/hn-service.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. */
@@ -28,11 +30,6 @@ const DEPTH_CEILING = 100;
  * one call examines.
  */
 const OMITTED_IDS_NAMED = 10;
-/**
- * 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.
- */
-const RESPONSE_BUDGET_BYTES = 64_000;
 /** Most comments one batch fetches — bounds the fetches a size cut leaves unused. */
 const FETCH_CHUNK = 25;
 /**
@@ -49,7 +46,8 @@ 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.
+ * 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;
 // ---------------------------------------------------------------------------
@@ -128,8 +126,8 @@ const CommentSchema = z
 })
     .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',
@@ -140,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] ' : '';
@@ -212,15 +208,67 @@ function renderThread(item, comments) {
     }
     return parts.join('\n');
 }
+/** 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 {
+        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 }, () => []);
@@ -228,13 +276,32 @@ 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 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)
@@ -246,18 +313,24 @@ async function walkThread(hn, ctx, args) {
         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];
@@ -275,23 +348,31 @@ async function walkThread(hn, ctx, args) {
                         childCount: c.kids?.length ?? 0,
                         ...(c.by != null && c.by === args.opAuthor && { isOp: true }),
                     };
-                    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) {
+                    /** 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),
+                    };
+                    if (!first && !fitsBudget(grown)) {
                         stop = 'size';
                         break;
                     }
                     comments.push(comment);
-                    usedBytes += bytes;
+                    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. */
@@ -304,25 +385,17 @@ async function walkThread(hn, ctx, args) {
                 }
                 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,
-        failed,
-        liveDepthCut,
-        omittedDead,
-        omittedDepthCut,
-        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
@@ -374,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);
 // ---------------------------------------------------------------------------
@@ -461,7 +539,7 @@ export const getThread = tool('hn_get_thread', {
             .min(1)
             .max(MAX_COMMENTS_CEILING)
             .default(50)
-            .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 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()
@@ -484,15 +562,15 @@ export const getThread = tool('hn_get_thread', {
         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()
@@ -501,17 +579,17 @@ export const getThread = tool('hn_get_thread', {
         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 — 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: {
-        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 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 });
@@ -520,7 +598,7 @@ export const getThread = tool('hn_get_thread', {
             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 });
         }
@@ -537,7 +615,7 @@ export const getThread = tool('hn_get_thread', {
         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));
             }
@@ -574,147 +652,183 @@ export const getThread = tool('hn_get_thread', {
         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,
             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,
+            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 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 }),
-        });
-        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_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 < 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(' ');
-        if (stop === 'count' || stop === 'examined' || stop === 'size') {
-            ctx.enrich.truncated({ shown: totalLoaded, cap: maxComments, guidance: notice });
-        }
-        else if (stop === 'rate_limited' || depthCut) {
-            ctx.enrich({ truncated: true });
+        const { notice, truncationReason, nextCursor, ...fields } = enrichment;
+        ctx.enrich(fields);
+        if (notice)
             ctx.enrich.notice(notice);
-        }
-        else 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) }],
 });