@cyanheads/hn-mcp-server 0.5.22 → 0.6.1

package/dist/mcp-server/tools/definitions/search-content.tool.js

@@ -5,6 +5,7 @@
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { escapeHighlight, escapeInline, escapeQuoted, quoteBody, } from '../markdown-escape.js';
+import { byteLength, cutPointer, cutToBytes, fitsBudget, largestFittingLimit, measureResponse, RESPONSE_BUDGET_TEXT, } from '../response-budget.js';
 import { servedAtCap } from '../served-at-cap.js';
 import { dateBoundToEpochMs, dateRangeToEpochSeconds, decodeHtmlEntities, extractDomain, getHnService, normalizeUrl, stripHtml, stripHtmlPreservingEm, } from '../../../services/hn/hn-service.js';
 /** Most hits one call serves; a larger `count` is served at this cap. */
@@ -106,6 +107,7 @@ const searchCriteria = z
     author: z.string().optional().describe('Author filter — the username matched, trimmed.'),
     storyId: z.number().optional().describe('Discussion filter: a story or poll root id.'),
     minPoints: z.number().optional().describe('Minimum score.'),
+    minComments: z.number().optional().describe('Minimum comment count.'),
     dateRange: z
         .object({
         start: z
@@ -139,6 +141,7 @@ function renderCriteria(c) {
         c.author != null ? `author: "${escapeQuoted(c.author)}"` : null,
         c.storyId != null ? `storyId: ${c.storyId}` : null,
         c.minPoints != null ? `minPoints: ${c.minPoints}` : null,
+        c.minComments != null ? `minComments: ${c.minComments}` : null,
         bounds ? `dateRange: ${bounds.filter(Boolean).join(', ')}` : null,
         `sort: ${c.sort}`,
         `count: ${c.count}`,
@@ -157,6 +160,8 @@ function appliedFilters(input) {
         filters.push('storyId');
     if (input.minPoints != null)
         filters.push('minPoints');
+    if (input.minComments != null)
+        filters.push('minComments');
     if (input.dateRange?.start || input.dateRange?.end)
         filters.push('dateRange');
     return filters;
@@ -236,15 +241,29 @@ function causeSentences(facts) {
     }
     return sentences;
 }
+/** The sentence disclosing how the page was fitted to the response budget. */
+function budgetSentence({ highlightsTextOmitted, cutIds }) {
+    const budget = `To stay within the ${RESPONSE_BUDGET_TEXT}-byte response budget,`;
+    const omitted = 'highlights.text is omitted from every hit';
+    if (cutIds.length === 0)
+        return `${budget} ${omitted}; matchedWords still lists the matched terms.`;
+    const cut = `the text of ${cutIds.length === 1 ? 'hit' : 'hits'} ${cutIds.join(', ')} is cut short`;
+    return `${budget} ${highlightsTextOmitted ? `${omitted} and ` : ''}${cut}; hn_get_thread with a cut hit's id returns its full text, and view: "compact" or a smaller count avoids the cut.`;
+}
 /**
  * Compose the one `notice` string every search writes. `notice` is last-wins,
  * so each source goes through here: the page-state sentence first, then the
- * cause sentences in input order — query, tags, author, storyId, count. None
- * replaces another. Undefined when nothing applies — the last page of an
- * uncapped, non-empty search.
+ * cause sentences in input order — query, tags, author, storyId, count — then
+ * the budget sentence for a page fitted to the response budget. None replaces
+ * another. Undefined when nothing applies — the last page of an uncapped,
+ * non-empty search that fit.
  */
 export function composeSearchNotice(facts) {
-    const sentences = [pageStateSentence(facts), ...causeSentences(facts)].filter((sentence) => sentence != null);
+    const sentences = [
+        pageStateSentence(facts),
+        ...causeSentences(facts),
+        facts.budget && budgetSentence(facts.budget),
+    ].filter((sentence) => sentence != null);
     return sentences.length > 0 ? sentences.join(' ') : undefined;
 }
 /**
@@ -259,19 +278,21 @@ function decodeHighlightTitle(title) {
         .join('');
 }
 /**
- * Project Algolia's `_highlightResult` into a flat snippet object: the title
- * snippet, the body snippet (comment_text, else story_text — the order `text`
- * reads them in; a job's job_text is never highlighted), and the deduplicated
+ * Project Algolia's `_highlightResult` into a flat object: the title snippet,
+ * the body highlight — the whole matched body with markers, not a snippet
+ * (comment_text, else story_text — the order `text` reads them in; a job's
+ * job_text is never highlighted) — and the deduplicated
  * union of matched words across all surfaced fields. Returns undefined when
  * nothing matched.
  *
  * Titles are not HTML, though some arrive entity-encoded (`<details>`,
  * `&#34;`), so the title snippet is entity-decoded between its `<em>` markers
- * and never tag-stripped. The body snippet is stripped of its HTML with the
- * markers kept.
+ * and never tag-stripped. The body highlight, the whole matched body, is
+ * stripped of its HTML with the markers kept.
  *
- * `includeBody` is false under the compact projection, which drops the body
- * snippet — the field that duplicates a hit's full comment text.
+ * `includeBody` is false under the compact projection, and on a full page over
+ * the response budget, both of which drop the body highlight — the field that
+ * repeats a hit's full body text.
  */
 function extractHighlights(hit, includeBody) {
     const h = hit._highlightResult;
@@ -295,15 +316,188 @@ function extractHighlights(hit, includeBody) {
         matchedWords,
     };
 }
+const searchHit = z
+    .object({
+    id: z.number().describe('HN item ID — use with hn_get_thread to read the discussion.'),
+    type: z
+        .enum(HIT_TYPES)
+        .optional()
+        .describe('Item type: story (Ask HN, Show HN, and front-page stories included), comment, poll, pollopt (one option of a poll), or job. Absent when the search record names no type.'),
+    title: z.string().optional().describe('Item title (present for stories, polls, and jobs).'),
+    url: z.string().optional().describe('External link URL.'),
+    domain: z
+        .string()
+        .optional()
+        .describe('Bare hostname derived from url (e.g. "github.com", with leading "www." stripped). Absent when url is missing or unparseable.'),
+    author: z.string().describe('Author username.'),
+    points: z.number().optional().describe('Score/upvotes.'),
+    numComments: z.number().optional().describe('Comment count.'),
+    createdAt: z.string().describe('Creation time (ISO 8601).'),
+    storyTitle: z.string().optional().describe('Parent story title (present for comment results).'),
+    storyId: z
+        .number()
+        .optional()
+        .describe("Parent story ID for comment hits; equals `id` for story hits. Absent for polls, poll options, and jobs — a poll's own `id` is its discussion root."),
+    parentId: z
+        .number()
+        .optional()
+        .describe("The item a comment hit replies to: its story's id for a top-level comment, otherwise the parent comment's id — hn_get_thread with this id reads it. Present on comment hits only."),
+    storyUrl: z
+        .string()
+        .optional()
+        .describe("External link URL of a comment hit's story. Absent when that story is a text post with no link, and on every hit that is not a comment."),
+    text: z
+        .string()
+        .optional()
+        .describe(`Body text, HTML stripped: a comment's text, a text post's body, or a job's description. A job description is returned but not keyword-searched or highlighted. Cut short when the page would otherwise exceed the ${RESPONSE_BUDGET_TEXT}-byte response budget, with textTruncated set. Absent when the hit has no body, and always absent under view "compact" — call hn_get_thread with this id to read it.`),
+    textTruncated: z
+        .boolean()
+        .optional()
+        .describe(`True when text is a prefix of the body, cut short to keep the page within the ${RESPONSE_BUDGET_TEXT}-byte response budget — hn_get_thread with this id returns it whole. Absent when text is whole.`),
+    highlights: z
+        .object({
+        title: z
+            .string()
+            .optional()
+            .describe('Title snippet with matched terms wrapped in `<em>…</em>`. Titles are not HTML, though some arrive entity-encoded; entities are decoded and no tags are stripped, so a literal `<em>` in the title is indistinguishable from a marker. Absent when the title did not match.'),
+        text: z
+            .string()
+            .optional()
+            .describe('The matched body in full, not a snippet (comment_text or story_text), HTML stripped, with matched terms wrapped in `<em>…</em>` — the same text as `text` plus its markers. A literal `<em>` typed into the body is indistinguishable from a marker. Absent when the body did not match, when highlightsTextOmitted is true, and always under view "compact" — matchedWords still lists what matched.'),
+        matchedWords: z
+            .array(z.string())
+            .describe('Deduplicated union of matched terms across all searchable fields (title, url, author, comment_text, story_text, story_title).'),
+    })
+        .optional()
+        .describe('Algolia per-field highlight metadata showing which terms matched and where. Absent when no fields produced a match.'),
+})
+    .describe('A single Algolia search hit (story, comment, poll, poll option, or job).');
+/**
+ * Project an Algolia hit into a search hit. `text` carries its body; under
+ * `bodyHighlight` its highlights carry the body too — the matched body in full,
+ * with markers.
+ */
+function projectHit(hit, text, bodyHighlight) {
+    const rawText = text ? (hit.comment_text ?? hit.story_text ?? hit.job_text) : undefined;
+    const url = normalizeUrl(hit.url);
+    const domain = extractDomain(url);
+    const storyUrl = normalizeUrl(hit.story_url);
+    const highlights = extractHighlights(hit, bodyHighlight);
+    const type = hitType(hit._tags);
+    return {
+        id: Number(hit.objectID),
+        ...(type && { type }),
+        title: hit.title != null ? decodeHtmlEntities(hit.title) : undefined,
+        url,
+        domain,
+        author: hit.author,
+        points: hit.points ?? undefined,
+        numComments: hit.num_comments ?? undefined,
+        createdAt: hit.created_at,
+        storyTitle: hit.story_title != null ? decodeHtmlEntities(hit.story_title) : undefined,
+        storyId: hit.story_id ?? undefined,
+        ...(hit.parent_id != null && { parentId: hit.parent_id }),
+        ...(storyUrl && { storyUrl }),
+        text: rawText ? stripHtml(rawText) || undefined : undefined,
+        ...(highlights && { highlights }),
+    };
+}
+const searchOutput = z.object({
+    hits: z.array(searchHit).describe('Search results ranked by sort order.'),
+    query: z
+        .string()
+        .optional()
+        .describe('The query that was searched — for a URL query, without its leading scheme and www. Absent for a filter-only search.'),
+});
+const searchTrailer = {
+    criteria: { render: renderCriteria },
+};
+/**
+ * Render highlight metadata as a `> match — …` footer, surfacing each highlights
+ * field separately so structured consumers and the LLM both see what matched.
+ * The footer follows an unquoted blank line, which a quoted body never
+ * produces, so a body line reading `match — …` cannot pass for it. The
+ * matched body comes last and continues on quoted lines of its own.
+ */
+function renderHighlights(hl) {
+    const parts = [];
+    if (hl.title)
+        parts.push(`title: ${escapeHighlight(hl.title)}`);
+    if (hl.matchedWords.length)
+        parts.push(`terms: ${hl.matchedWords.join(', ')}`);
+    if (hl.text)
+        parts.push(`body: ${hl.text}`);
+    return parts.length ? `\n\n${quoteBody(`match — ${parts.join(' | ')}`)}` : '';
+}
+/** A hit's quoted body, and after a cut body the unquoted pointer to the whole text, a blank line apart. */
+function renderBody(h) {
+    const text = h.text ? `\n${quoteBody(h.text)}` : '';
+    return h.textTruncated ? `${text}\n\n${cutPointer(h.id)}` : text;
+}
+/**
+ * A hit's meta line: id, type, and the item a comment replies to, in the order
+ * `hn_get_thread` opens its meta line with, then author, score, comment count,
+ * and time. Each field renders when present, whatever the hit's type.
+ */
+function metaLine(h) {
+    return [
+        `id:${h.id}`,
+        h.type ? `type:${h.type}` : null,
+        h.parentId != null ? `parent:${h.parentId}` : null,
+        h.author,
+        h.points != null ? `${h.points} pts` : null,
+        h.numComments != null ? `${h.numComments} comments` : null,
+        h.createdAt,
+    ]
+        .filter(Boolean)
+        .join(' | ');
+}
+/** The hit's own link, then its story's, each on a line of its own under the meta line. */
+function renderLinks(h) {
+    return [h.url, h.storyUrl].map((link) => (link ? `\n${link}` : '')).join('');
+}
+function formatSearch(result) {
+    if (result.hits.length === 0) {
+        return [
+            {
+                type: 'text',
+                text: result.query != null ? `"${escapeQuoted(result.query)}" — no results.` : 'No results.',
+            },
+        ];
+    }
+    const lines = result.hits.map((h) => {
+        const meta = metaLine(h);
+        const links = renderLinks(h);
+        const hlLine = h.highlights ? renderHighlights(h.highlights) : '';
+        if (h.type === 'pollopt') {
+            // A poll option's search record carries no text and no poll; hn_get_thread has both.
+            return `### Poll option by ${h.author}\n${meta}${links}\nOption text and its poll: hn_get_thread with itemId ${h.id}${hlLine}`;
+        }
+        if (h.title) {
+            // Story result — Algolia returns storyId === id for stories, so suppress the parent ref unless it actually differs or a parent title is set.
+            const parentRef = (h.storyId != null && h.storyId !== h.id) || h.storyTitle
+                ? ` | story:"${escapeQuoted(h.storyTitle ?? '?')}"#${h.storyId ?? '?'}`
+                : '';
+            const domain = h.domain ? ` (${h.domain})` : '';
+            return `### ${escapeInline(h.title)}${domain}\n${meta}${parentRef}${links}${renderBody(h)}${hlLine}`;
+        }
+        // Comment result — parent context in heading.
+        return `### Comment on "${escapeQuoted(h.storyTitle ?? 'unknown')}" (story id:${h.storyId ?? '?'})\n${meta}${links}${renderBody(h)}${hlLine}`;
+    });
+    const header = result.query != null
+        ? `## "${escapeQuoted(result.query)}" — search results`
+        : '## Search results (filters only)';
+    return [{ type: 'text', text: `${header}\n\n${lines.join('\n\n')}` }];
+}
 export const searchHn = tool('hn_search_content', {
-    description: 'Search Hacker News stories, comments, polls, and jobs via Algolia — by keyword, by filters alone, or both. Filterable by content type, author, parent story, date range, and minimum points.',
+    description: 'Search Hacker News stories, comments, polls, and jobs via Algolia — by keyword, by filters alone, or both. Filterable by content type, author, parent story, date range, minimum points, and minimum comment count.',
     annotations: { readOnlyHint: true },
     errors: [
         {
             reason: 'missing_query_or_filter',
             code: JsonRpcErrorCode.InvalidParams,
             when: 'Neither a query nor any filter was supplied, so there is nothing to search by.',
-            recovery: 'Pass a query, or at least one filter: tags, author, storyId, minPoints, or a dateRange bound. sort, count, page, and view do not count as filters.',
+            recovery: 'Pass a query, or at least one filter: tags, author, storyId, minPoints, minComments, or a dateRange bound. sort, count, page, and view do not count as filters.',
             severity: 'notice',
         },
         {
@@ -320,6 +514,13 @@ export const searchHn = tool('hn_search_content', {
             recovery: 'Drop minPoints to search comments or jobs, or search a scored type (story, poll, ask_hn, show_hn, front_page) to filter by points.',
             severity: 'notice',
         },
+        {
+            reason: 'min_comments_unscored_type',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'minComments was combined with tags "comment" or "job", record types Algolia stores without a comment count.',
+            recovery: 'Drop minComments to search comments or jobs, or search a type with a comment count (story, poll, ask_hn, show_hn, front_page) to filter by comments.',
+            severity: 'notice',
+        },
         {
             reason: 'count_page_unaligned',
             code: JsonRpcErrorCode.InvalidParams,
@@ -373,7 +574,7 @@ export const searchHn = tool('hn_search_content', {
             .trim()
             .min(1, 'blank after trimming whitespace — pass one or more search terms, or omit query for a filter-only search.')
             .optional()
-            .describe('Search terms. Supports simple keywords — Algolia handles stemming and relevance, and a hit must contain every term. Trimmed before searching; blank or whitespace-only input is rejected. To find discussions of a page, pass its URL alone: a query with no spaces that starts with http://, https://, or www. is searched without that prefix, so submissions under either scheme, with or without www., all match. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, or a dateRange bound.'),
+            .describe('Search terms. Supports simple keywords — Algolia handles stemming and relevance, and a hit must contain every term. Matching is typo-tolerant and the last term also matches as a prefix (zig matches Zigbee); wrap a term in double quotes to match it exactly ("zig"), or put - before one to exclude it ("zig" -devlog). Trimmed before searching; blank or whitespace-only input is rejected. To find discussions of a page, pass its URL alone: a query with no spaces that starts with http://, https://, or www. is searched without that prefix, so submissions under either scheme, with or without www., all match. Omit for a filter-only search, which needs at least one of tags, author, storyId, minPoints, minComments, or a dateRange bound.'),
         tags: z
             .enum(SEARCH_TAGS)
             .optional()
@@ -407,6 +608,12 @@ export const searchHn = tool('hn_search_content', {
             .min(0)
             .optional()
             .describe('Minimum score. Applies to stories and polls, including the ask_hn, show_hn, and front_page subsets. Comments and jobs carry no points in the search index, so any minPoints excludes them — combining it with tags "comment" or "job" is rejected.'),
+        minComments: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Minimum comment count. Applies to stories and polls, including the ask_hn, show_hn, and front_page subsets. Any minComments, 0 included, excludes comments, jobs, and poll options, which carry no comment count in the search index, so an untagged search returns only stories and polls — combining it with tags "comment" or "job" is rejected.'),
         count: z
             .number()
             .int()
@@ -423,66 +630,9 @@ export const searchHn = tool('hn_search_content', {
         view: z
             .enum(['full', 'compact'])
             .default('full')
-            .describe('How much of each hit to return. "full" includes every field. "compact" omits the two body-text fields — `text` and `highlights.text` — which together can repeat a long comment twice per hit; everything else (id, title, url, domain, author, points, comment count, timestamp, parent story, title highlight, matchedWords) is unchanged. Use "compact" to scan many results, then pass a hit id to hn_get_thread to read the body you skipped.'),
-    }),
-    output: z.object({
-        hits: z
-            .array(z
-            .object({
-            id: z.number().describe('HN item ID — use with hn_get_thread to read the discussion.'),
-            type: z
-                .enum(HIT_TYPES)
-                .optional()
-                .describe('Item type: story (Ask HN, Show HN, and front-page stories included), comment, poll, pollopt (one option of a poll), or job. Absent when the search record names no type.'),
-            title: z
-                .string()
-                .optional()
-                .describe('Item title (present for stories, polls, and jobs).'),
-            url: z.string().optional().describe('External link URL.'),
-            domain: z
-                .string()
-                .optional()
-                .describe('Bare hostname derived from url (e.g. "github.com", with leading "www." stripped). Absent when url is missing or unparseable.'),
-            author: z.string().describe('Author username.'),
-            points: z.number().optional().describe('Score/upvotes.'),
-            numComments: z.number().optional().describe('Comment count.'),
-            createdAt: z.string().describe('Creation time (ISO 8601).'),
-            storyTitle: z
-                .string()
-                .optional()
-                .describe('Parent story title (present for comment results).'),
-            storyId: z
-                .number()
-                .optional()
-                .describe("Parent story ID for comment hits; equals `id` for story hits. Absent for polls, poll options, and jobs — a poll's own `id` is its discussion root."),
-            text: z
-                .string()
-                .optional()
-                .describe("Body text, HTML stripped: a comment's text, a text post's body, or a job's description. A job description is returned but not keyword-searched or highlighted. Absent when the hit has no body, and always absent under view \"compact\" — call hn_get_thread with this id to read it."),
-            highlights: z
-                .object({
-                title: z
-                    .string()
-                    .optional()
-                    .describe('Title snippet with matched terms wrapped in `<em>…</em>`. Titles are not HTML, though some arrive entity-encoded; entities are decoded and no tags are stripped, so a literal `<em>` in the title is indistinguishable from a marker. Absent when the title did not match.'),
-                text: z
-                    .string()
-                    .optional()
-                    .describe('Body snippet (comment_text or story_text), HTML stripped, with matched terms wrapped in `<em>…</em>`. A literal `<em>` typed into the body is indistinguishable from a marker. Absent when the body did not match, and always absent under view "compact" — matchedWords still lists what matched.'),
-                matchedWords: z
-                    .array(z.string())
-                    .describe('Deduplicated union of matched terms across all searchable fields (title, url, author, comment_text, story_text, story_title).'),
-            })
-                .optional()
-                .describe('Algolia per-field highlight metadata showing which terms matched and where. Absent when no fields produced a match.'),
-        })
-            .describe('A single Algolia search hit (story, comment, poll, poll option, or job).'))
-            .describe('Search results ranked by sort order.'),
-        query: z
-            .string()
-            .optional()
-            .describe('The query that was searched — for a URL query, without its leading scheme and www. Absent for a filter-only search.'),
+            .describe(`How much of each hit to return. "full" includes every field, within a ${RESPONSE_BUDGET_TEXT}-byte budget on each response surface: a page over it drops highlights.text from every hit (highlightsTextOmitted), and if still over, cuts the longest text bodies to one shared length (textTruncated) — every hit stays on the page. "compact" omits the two body-text fields — \`text\` and \`highlights.text\` — which together can repeat a long comment twice per hit; everything else (id, title, url, domain, author, points, comment count, timestamp, parent story, parentId, storyUrl, title highlight, matchedWords) is unchanged. Use "compact" to scan many results, then pass a hit id to hn_get_thread to read the body you skipped.`),
     }),
+    output: searchOutput,
     enrichment: {
         criteria: searchCriteria,
         totalHits: z
@@ -511,14 +661,16 @@ export const searchHn = tool('hn_search_content', {
             .number()
             .optional()
             .describe(`The count value served: as passed, or ${COUNT_CAP} when count was above that cap.`),
+        highlightsTextOmitted: z
+            .boolean()
+            .optional()
+            .describe(`True when highlights.text was dropped from every hit to keep this view "full" page within the ${RESPONSE_BUDGET_TEXT}-byte response budget; highlights.title and matchedWords remain. Absent otherwise.`),
         notice: z
             .string()
             .optional()
-            .describe('Agent guidance, one string. It opens with the page state: the next page to request while more pages remain, the 1,000-hit ceiling on the last page of a search that matches more, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Notes on the inputs follow it. Absent when none applies.'),
-    },
-    enrichmentTrailer: {
-        criteria: { render: renderCriteria },
+            .describe(`Agent guidance, one string. It opens with the page state: the next page to request while more pages remain, the 1,000-hit ceiling on the last page of a search that matches more, the last valid page when the requested page is past the end, or the filters to relax when a first page comes back empty. Notes on the inputs follow it, then, on a view "full" page fitted to the ${RESPONSE_BUDGET_TEXT}-byte response budget, a sentence naming what was omitted and the ids of hits whose text was cut. Absent when none applies.`),
     },
+    enrichmentTrailer: searchTrailer,
     async handler(input, ctx) {
         const { dateRange } = input;
         if (dateRange) {
@@ -533,6 +685,9 @@ export const searchHn = tool('hn_search_content', {
         if (input.minPoints != null && (input.tags === 'comment' || input.tags === 'job')) {
             throw ctx.fail('min_points_unscored_type', `minPoints cannot match tags "${input.tags}": ${input.tags} records carry no points, so any minPoints excludes every one.`);
         }
+        if (input.minComments != null && (input.tags === 'comment' || input.tags === 'job')) {
+            throw ctx.fail('min_comments_unscored_type', `minComments cannot match tags "${input.tags}": ${input.tags} records carry no comment count, so any minComments excludes every one.`);
+        }
         const filters = appliedFilters(input);
         if (input.query == null && filters.length === 0) {
             throw ctx.fail('missing_query_or_filter', 'No query and no filter were supplied, so there is nothing to search by.');
@@ -552,30 +707,7 @@ export const searchHn = tool('hn_search_content', {
         const hn = getHnService();
         const result = await hn.search(params, ctx);
         const includeBody = input.view === 'full';
-        const hits = result.hits.map((hit) => {
-            const rawText = includeBody
-                ? (hit.comment_text ?? hit.story_text ?? hit.job_text)
-                : undefined;
-            const url = normalizeUrl(hit.url);
-            const domain = extractDomain(url);
-            const highlights = extractHighlights(hit, includeBody);
-            const type = hitType(hit._tags);
-            return {
-                id: Number(hit.objectID),
-                ...(type && { type }),
-                title: hit.title != null ? decodeHtmlEntities(hit.title) : undefined,
-                url,
-                domain,
-                author: hit.author,
-                points: hit.points ?? undefined,
-                numComments: hit.num_comments ?? undefined,
-                createdAt: hit.created_at,
-                storyTitle: hit.story_title != null ? decodeHtmlEntities(hit.story_title) : undefined,
-                storyId: hit.story_id ?? undefined,
-                text: rawText ? stripHtml(rawText) || undefined : undefined,
-                ...(highlights && { highlights }),
-            };
-        });
+        const hits = result.hits.map((hit) => projectHit(hit, includeBody, includeBody));
         ctx.log.info('Search completed', {
             query: params.query,
             hits: hits.length,
@@ -589,12 +721,13 @@ export const searchHn = tool('hn_search_content', {
             ? undefined
             : (result.exhaustive?.nbHits ?? result.exhaustiveNbHits);
         const bounds = params.dateRange ? dateRangeToEpochSeconds(params.dateRange) : {};
-        ctx.enrich({
+        const pageFields = {
             criteria: {
                 ...(params.tags != null && { tags: params.tags }),
                 ...(params.author != null && { author: params.author }),
                 ...(params.storyId != null && { storyId: params.storyId }),
                 ...(params.minPoints != null && { minPoints: params.minPoints }),
+                ...(params.minComments != null && { minComments: params.minComments }),
                 ...((bounds.start != null || bounds.end != null) && {
                     dateRange: {
                         ...(bounds.start != null && { start: isoSeconds(bounds.start) }),
@@ -610,10 +743,9 @@ export const searchHn = tool('hn_search_content', {
             page,
             totalPages,
             ...(totalHits > HIT_CEILING && { reachableHits: HIT_CEILING }),
-        });
-        if (shown > 0 && page + 1 < totalPages)
-            ctx.enrich.truncated({ shown, cap: params.count });
-        const notice = composeSearchNotice({
+        };
+        const morePages = shown > 0 && page + 1 < totalPages;
+        const noticeFacts = {
             ...params,
             droppedPrefix: searched?.droppedPrefix,
             shown,
@@ -622,93 +754,62 @@ export const searchHn = tool('hn_search_content', {
             totalHitsExact,
             totalPages,
             overCap,
-        });
-        if (notice)
-            ctx.enrich.notice(notice);
-        return {
-            hits,
-            ...(params.query != null && { query: params.query }),
-        };
-    },
-    format: (result) => {
-        if (result.hits.length === 0) {
-            return [
-                {
-                    type: 'text',
-                    text: result.query != null ? `"${escapeQuoted(result.query)}" — no results.` : 'No results.',
-                },
-            ];
-        }
-        /**
-         * Render highlight metadata as a `> match — …` footer, surfacing each highlights
-         * field separately so structured consumers and the LLM both see what matched.
-         * The footer follows an unquoted blank line, which a quoted body never
-         * produces, so a body line reading `match — …` cannot pass for it. The body
-         * snippet comes last and continues on quoted lines of its own.
-         */
-        const renderHighlights = (hl) => {
-            const parts = [];
-            if (hl.title)
-                parts.push(`title: ${escapeHighlight(hl.title)}`);
-            if (hl.matchedWords.length)
-                parts.push(`terms: ${hl.matchedWords.join(', ')}`);
-            if (hl.text)
-                parts.push(`body: ${hl.text}`);
-            return parts.length ? `\n\n${quoteBody(`match — ${parts.join(' | ')}`)}` : '';
         };
-        const lines = result.hits.map((h) => {
-            const typeToken = h.type ? `type:${h.type}` : null;
-            const hlLine = h.highlights ? renderHighlights(h.highlights) : '';
-            if (h.type === 'pollopt') {
-                // A poll option's search record carries no text and no poll; hn_get_thread has both.
-                const meta = [
-                    `id:${h.id}`,
-                    typeToken,
-                    h.author,
-                    h.points != null ? `${h.points} pts` : null,
-                    h.createdAt,
-                ]
-                    .filter(Boolean)
-                    .join(' | ');
-                return `### Poll option by ${h.author}\n${meta}\nOption text and its poll: hn_get_thread with itemId ${h.id}${hlLine}`;
-            }
-            if (h.title) {
-                // Story result — Algolia returns storyId === id for stories, so suppress the parent ref unless it actually differs or a parent title is set.
-                const parentRef = (h.storyId != null && h.storyId !== h.id) || h.storyTitle
-                    ? ` | story:"${escapeQuoted(h.storyTitle ?? '?')}"#${h.storyId ?? '?'}`
-                    : '';
-                const meta = [
-                    `id:${h.id}`,
-                    typeToken,
-                    h.author,
-                    h.points != null ? `${h.points} pts` : null,
-                    h.numComments != null ? `${h.numComments} comments` : null,
-                    h.createdAt,
-                ]
-                    .filter(Boolean)
-                    .join(' | ');
-                const domain = h.domain ? ` (${h.domain})` : '';
-                const url = h.url ? `\n${h.url}` : '';
-                const text = h.text ? `\n${quoteBody(h.text)}` : '';
-                return `### ${escapeInline(h.title)}${domain}\n${meta}${parentRef}${url}${text}${hlLine}`;
+        /** The response serving `served`, with the notice and flag for how `budget` fitted it. */
+        const respond = (served, budget) => ({
+            output: { hits: served, ...(params.query != null && { query: params.query }) },
+            notice: composeSearchNotice({ ...noticeFacts, budget }),
+            highlightsTextOmitted: budget?.highlightsTextOmitted === true,
+        });
+        /** Both surfaces of a response as the caller receives it, enrichment and trailer included. */
+        const measure = (response) => measureResponse({
+            content: formatSearch(response.output),
+            result: response.output,
+            enrichment: {
+                ...pageFields,
+                ...(response.highlightsTextOmitted && { highlightsTextOmitted: true }),
+                ...(morePages && { truncated: true, shown, cap: params.count }),
+                ...(response.notice != null && { notice: response.notice }),
+            },
+            trailer: searchTrailer,
+        });
+        let response = respond(hits);
+        if (includeBody && !fitsBudget(measure(response))) {
+            /** Step 1: drop the body highlight, which repeats the matched body in full, from every hit. */
+            const highlightsTextOmitted = hits.some((hit) => hit.highlights?.text != null);
+            const lean = highlightsTextOmitted
+                ? result.hits.map((hit) => projectHit(hit, true, false))
+                : hits;
+            if (highlightsTextOmitted)
+                response = respond(lean, { highlightsTextOmitted, cutIds: [] });
+            if (!highlightsTextOmitted || !fitsBudget(measure(response))) {
+                /** Step 2: cut every body longer than the largest limit they can share. */
+                const bodies = lean.map((hit) => ({ hit, bytes: hit.text ? byteLength(hit.text) : 0 }));
+                const cutAt = (limit) => {
+                    const served = bodies.map(({ hit, bytes }) => hit.text && bytes > limit
+                        ? { ...hit, text: cutToBytes(hit.text, limit), textTruncated: true }
+                        : hit);
+                    const cutIds = served.filter((hit) => hit.textTruncated).map((hit) => hit.id);
+                    return respond(served, { highlightsTextOmitted, cutIds });
+                };
+                const limit = largestFittingLimit(bodies.map((body) => body.bytes), (limitBytes) => measure(cutAt(limitBytes)));
+                response = cutAt(limit);
+                ctx.log.info('Fitted search page to the response budget', {
+                    limitBytes: limit,
+                    cutIds: response.output.hits.filter((hit) => hit.textTruncated).map((hit) => hit.id),
+                });
             }
-            // Comment result — parent context in heading.
-            const meta = [
-                `id:${h.id}`,
-                typeToken,
-                h.author,
-                h.points != null ? `${h.points} pts` : null,
-                h.createdAt,
-            ]
-                .filter(Boolean)
-                .join(' | ');
-            const text = h.text ? `\n${quoteBody(h.text)}` : '';
-            return `### Comment on "${escapeQuoted(h.storyTitle ?? 'unknown')}" (story id:${h.storyId ?? '?'})\n${meta}${text}${hlLine}`;
+        }
+        ctx.enrich({
+            ...pageFields,
+            ...(response.highlightsTextOmitted && { highlightsTextOmitted: true }),
         });
-        const header = result.query != null
-            ? `## "${escapeQuoted(result.query)}" — search results`
-            : '## Search results (filters only)';
-        return [{ type: 'text', text: `${header}\n\n${lines.join('\n\n')}` }];
+        if (morePages)
+            ctx.enrich.truncated({ shown, cap: params.count });
+        if (response.notice)
+            ctx.enrich.notice(response.notice);
+        return response.output;
     },
+    format: formatSearch,
 });
 //# sourceMappingURL=search-content.tool.js.map