@maintainabilityai/research-runner 0.1.1

package/dist/schemas/ranked-source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * RankedSource — normalised search result shape after dedupe_and_rank.
+ *
+ * Each provider (Tavily / arXiv / USPTO / HackerNews) returns its own native
+ * payload; the dedupe node converts them all to this common shape with a
+ * salience score (0.0-1.0) used by synthesize to choose what to cite.
+ */
+import { z } from 'zod';
+export declare const RankedSource: z.ZodObject<{
+    /** Stable id used by the synthesis prompt as `S[N]` citation. */
+    id: z.ZodString;
+    provider: z.ZodEnum<["tavily", "arxiv", "uspto", "hackernews"]>;
+    title: z.ZodString;
+    url: z.ZodString;
+    retrieved_at: z.ZodEffects<z.ZodString, string, string>;
+    /** 0.0 - 1.0, higher = more relevant. Computed by dedupe_and_rank. */
+    salience_score: z.ZodNumber;
+    /** ≤500-char excerpt the synthesis node may quote directly. */
+    excerpt: z.ZodString;
+    /** Optional: pub date if the source has one (papers, news, patents). */
+    published_at: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /** Optional: authors (arxiv / news). */
+    authors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    provider: "tavily" | "arxiv" | "uspto" | "hackernews";
+    url: string;
+    retrieved_at: string;
+    salience_score: number;
+    excerpt: string;
+    published_at?: string | undefined;
+    authors?: string[] | undefined;
+}, {
+    id: string;
+    title: string;
+    provider: "tavily" | "arxiv" | "uspto" | "hackernews";
+    url: string;
+    retrieved_at: string;
+    salience_score: number;
+    excerpt: string;
+    published_at?: string | undefined;
+    authors?: string[] | undefined;
+}>;
+export type RankedSource = z.infer<typeof RankedSource>;
+export declare const RankedSourceList: z.ZodArray<z.ZodObject<{
+    /** Stable id used by the synthesis prompt as `S[N]` citation. */
+    id: z.ZodString;
+    provider: z.ZodEnum<["tavily", "arxiv", "uspto", "hackernews"]>;
+    title: z.ZodString;
+    url: z.ZodString;
+    retrieved_at: z.ZodEffects<z.ZodString, string, string>;
+    /** 0.0 - 1.0, higher = more relevant. Computed by dedupe_and_rank. */
+    salience_score: z.ZodNumber;
+    /** ≤500-char excerpt the synthesis node may quote directly. */
+    excerpt: z.ZodString;
+    /** Optional: pub date if the source has one (papers, news, patents). */
+    published_at: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    /** Optional: authors (arxiv / news). */
+    authors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    provider: "tavily" | "arxiv" | "uspto" | "hackernews";
+    url: string;
+    retrieved_at: string;
+    salience_score: number;
+    excerpt: string;
+    published_at?: string | undefined;
+    authors?: string[] | undefined;
+}, {
+    id: string;
+    title: string;
+    provider: "tavily" | "arxiv" | "uspto" | "hackernews";
+    url: string;
+    retrieved_at: string;
+    salience_score: number;
+    excerpt: string;
+    published_at?: string | undefined;
+    authors?: string[] | undefined;
+}>, "many">;
+export type RankedSourceList = z.infer<typeof RankedSourceList>;

package/dist/schemas/ranked-source.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RankedSourceList = exports.RankedSource = void 0;
+/**
+ * RankedSource — normalised search result shape after dedupe_and_rank.
+ *
+ * Each provider (Tavily / arXiv / USPTO / HackerNews) returns its own native
+ * payload; the dedupe node converts them all to this common shape with a
+ * salience score (0.0-1.0) used by synthesize to choose what to cite.
+ */
+const zod_1 = require("zod");
+const primitives_1 = require("./primitives");
+exports.RankedSource = zod_1.z.object({
+    /** Stable id used by the synthesis prompt as `S[N]` citation. */
+    id: zod_1.z.string().regex(/^S\d+$/),
+    provider: primitives_1.SearchProvider,
+    title: zod_1.z.string().min(1),
+    url: zod_1.z.string().url(),
+    retrieved_at: primitives_1.IsoTimestamp,
+    /** 0.0 - 1.0, higher = more relevant. Computed by dedupe_and_rank. */
+    salience_score: zod_1.z.number().min(0).max(1),
+    /** ≤500-char excerpt the synthesis node may quote directly. */
+    excerpt: zod_1.z.string().max(500),
+    /** Optional: pub date if the source has one (papers, news, patents). */
+    published_at: primitives_1.IsoTimestamp.optional(),
+    /** Optional: authors (arxiv / news). */
+    authors: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.RankedSourceList = zod_1.z.array(exports.RankedSource);

package/dist/schemas/research-brief.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ResearchBrief — validated input to the Archeologist pipeline.
+ *
+ * Produced by `validate_brief` (the pure first node) from CLI args / issue
+ * body / workflow_dispatch inputs / Looking Glass form. Every downstream
+ * node receives this object.
+ */
+import { z } from 'zod';
+export declare const ResearchBrief: z.ZodEffects<z.ZodObject<{
+    /** Plain-English research request (the topic). */
+    topic: z.ZodString;
+    scope: z.ZodObject<{
+        level: z.ZodEnum<["platform", "bar"]>;
+        /** Required: platform slug (e.g. `imdb-lite`) or BAR id (e.g. `APP-IMDB-002`). */
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        level: "platform" | "bar";
+        id: string;
+    }, {
+        level: "platform" | "bar";
+        id: string;
+    }>;
+    /** `research` = market research; `archaeology` = codebase analysis path. */
+    path: z.ZodDefault<z.ZodEnum<["research", "archaeology"]>>;
+    /** Archaeology path only: `owner/repo` of the codebase to analyze. */
+    target_repo: z.ZodOptional<z.ZodString>;
+    /** Guardrail mode applied to LLM nodes. */
+    guardrails: z.ZodDefault<z.ZodEnum<["strict", "default", "lenient"]>>;
+    /** LLM provider for the synthesis + planning nodes. */
+    llm_provider: z.ZodDefault<z.ZodEnum<["anthropic", "openai", "azure-openai", "github-models"]>>;
+    /** Token budget cap (warn before exceeding). */
+    cost_cap_tokens: z.ZodDefault<z.ZodNumber>;
+    /** Caller-supplied trigger context — flows into the audit log envelope. */
+    trigger: z.ZodObject<{
+        kind: z.ZodEnum<["workflow_dispatch", "issue_label", "issue_comment", "project_card", "local_dev"]>;
+        /** Issue number when triggered by issue / comment events. */
+        issue_number: z.ZodOptional<z.ZodNumber>;
+        /** Actor login when known (GitHub Actions sets this). */
+        actor: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "workflow_dispatch" | "issue_label" | "issue_comment" | "project_card" | "local_dev";
+        issue_number?: number | undefined;
+        actor?: string | undefined;
+    }, {
+        kind: "workflow_dispatch" | "issue_label" | "issue_comment" | "project_card" | "local_dev";
+        issue_number?: number | undefined;
+        actor?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    path: "research" | "archaeology";
+    topic: string;
+    scope: {
+        level: "platform" | "bar";
+        id: string;
+    };
+    guardrails: "strict" | "default" | "lenient";
+    llm_provider: "anthropic" | "openai" | "azure-openai" | "github-models";
+    cost_cap_tokens: number;
+    trigger: {
+        kind: "workflow_dispatch" | "issue_label" | "issue_comment" | "project_card" | "local_dev";
+        issue_number?: number | undefined;
+        actor?: string | undefined;
+    };
+    target_repo?: string | undefined;
+}, {
+    topic: string;
+    scope: {
+        level: "platform" | "bar";
+        id: string;
+    };
+    trigger: {
+        kind: "workflow_dispatch" | "issue_label" | "issue_comment" | "project_card" | "local_dev";
+        issue_number?: number | undefined;
+        actor?: string | undefined;
+    };
+    path?: "research" | "archaeology" | undefined;
+    target_repo?: string | undefined;
+    guardrails?: "strict" | "default" | "lenient" | undefined;
+    llm_provider?: "anthropic" | "openai" | "azure-openai" | "github-models" | undefined;
+    cost_cap_tokens?: number | undefined;
+}>, {
+    path: "research" | "archaeology";
+    topic: string;
+    scope: {
+        level: "platform" | "bar";
+        id: string;
+    };
+    guardrails: "strict" | "default" | "lenient";
+    llm_provider: "anthropic" | "openai" | "azure-openai" | "github-models";
+    cost_cap_tokens: number;
+    trigger: {
+        kind: "workflow_dispatch" | "issue_label" | "issue_comment" | "project_card" | "local_dev";
+        issue_number?: number | undefined;
+        actor?: string | undefined;
+    };
+    target_repo?: string | undefined;
+}, {
+    topic: string;
+    scope: {
+        level: "platform" | "bar";
+        id: string;
+    };
+    trigger: {
+        kind: "workflow_dispatch" | "issue_label" | "issue_comment" | "project_card" | "local_dev";
+        issue_number?: number | undefined;
+        actor?: string | undefined;
+    };
+    path?: "research" | "archaeology" | undefined;
+    target_repo?: string | undefined;
+    guardrails?: "strict" | "default" | "lenient" | undefined;
+    llm_provider?: "anthropic" | "openai" | "azure-openai" | "github-models" | undefined;
+    cost_cap_tokens?: number | undefined;
+}>;
+export type ResearchBrief = z.infer<typeof ResearchBrief>;

package/dist/schemas/research-brief.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResearchBrief = void 0;
+/**
+ * ResearchBrief — validated input to the Archeologist pipeline.
+ *
+ * Produced by `validate_brief` (the pure first node) from CLI args / issue
+ * body / workflow_dispatch inputs / Looking Glass form. Every downstream
+ * node receives this object.
+ */
+const zod_1 = require("zod");
+const primitives_1 = require("./primitives");
+exports.ResearchBrief = zod_1.z.object({
+    /** Plain-English research request (the topic). */
+    topic: zod_1.z.string().min(3).max(2000),
+    scope: zod_1.z.object({
+        level: primitives_1.ScopeLevel,
+        /** Required: platform slug (e.g. `imdb-lite`) or BAR id (e.g. `APP-IMDB-002`). */
+        id: zod_1.z.string().min(1),
+    }),
+    /** `research` = market research; `archaeology` = codebase analysis path. */
+    path: primitives_1.ResearchPath.default('research'),
+    /** Archaeology path only: `owner/repo` of the codebase to analyze. */
+    target_repo: zod_1.z.string().regex(/^[\w.-]+\/[\w.-]+$/).optional(),
+    /** Guardrail mode applied to LLM nodes. */
+    guardrails: primitives_1.GuardrailMode.default('default'),
+    /** LLM provider for the synthesis + planning nodes. */
+    llm_provider: primitives_1.LlmProvider.default('anthropic'),
+    /** Token budget cap (warn before exceeding). */
+    cost_cap_tokens: zod_1.z.number().int().positive().default(200_000),
+    /** Caller-supplied trigger context — flows into the audit log envelope. */
+    trigger: zod_1.z.object({
+        kind: zod_1.z.enum(['workflow_dispatch', 'issue_label', 'issue_comment', 'project_card', 'local_dev']),
+        /** Issue number when triggered by issue / comment events. */
+        issue_number: zod_1.z.number().int().optional(),
+        /** Actor login when known (GitHub Actions sets this). */
+        actor: zod_1.z.string().optional(),
+    }),
+}).superRefine((brief, ctx) => {
+    // Archaeology runs require a target repo
+    if (brief.path === 'archaeology' && !brief.target_repo) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: 'archaeology path requires target_repo (owner/repo)',
+            path: ['target_repo'],
+        });
+    }
+    // scope.id required-ness is enforced at the field level (min(1)).
+});

package/dist/schemas/research-doc.d.ts

@@ -0,0 +1,104 @@
+/**
+ * ResearchDoc — the published research artifact (research path).
+ *
+ * The synthesis LLM produces structured markdown matching the 10 canonical
+ * sections defined in `.caterpillar/prompts/research/synthesis.md`. The
+ * runner validates section presence + citation rules with a separate
+ * structural validator; this schema only enforces the surrounding metadata.
+ */
+import { z } from 'zod';
+/** A formal conclusion line as parsed from the body. Used by the structural validator. */
+export declare const FormalConclusion: z.ZodObject<{
+    id: z.ZodString;
+    statement: z.ZodString;
+    confidence: z.ZodEnum<["HIGH", "MEDIUM", "LOW"]>;
+    /** Source premise IDs (S1, S2, …) cited by this conclusion. */
+    cited_sources: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    statement: string;
+    confidence: "HIGH" | "MEDIUM" | "LOW";
+    cited_sources: string[];
+}, {
+    id: string;
+    statement: string;
+    confidence: "HIGH" | "MEDIUM" | "LOW";
+    cited_sources: string[];
+}>;
+export declare const ResearchDoc: z.ZodObject<{
+    run_id: z.ZodString;
+    topic: z.ZodString;
+    generated_at: z.ZodEffects<z.ZodString, string, string>;
+    /** Final published markdown — the body the auditor + reviewers read. */
+    body_md: z.ZodString;
+    /** Pre-extracted formal conclusions, used for downstream PRD grounding. */
+    conclusions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        confidence: z.ZodEnum<["HIGH", "MEDIUM", "LOW"]>;
+        /** Source premise IDs (S1, S2, …) cited by this conclusion. */
+        cited_sources: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        statement: string;
+        confidence: "HIGH" | "MEDIUM" | "LOW";
+        cited_sources: string[];
+    }, {
+        id: string;
+        statement: string;
+        confidence: "HIGH" | "MEDIUM" | "LOW";
+        cited_sources: string[];
+    }>, "many">>;
+    /** Citation counts the structural validator reports back. */
+    citation_stats: z.ZodObject<{
+        source_count: z.ZodNumber;
+        conclusion_count: z.ZodNumber;
+        recommendation_count: z.ZodNumber;
+        untraced_claims: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        source_count: number;
+        conclusion_count: number;
+        recommendation_count: number;
+        untraced_claims: number;
+    }, {
+        source_count: number;
+        conclusion_count: number;
+        recommendation_count: number;
+        untraced_claims: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    topic: string;
+    run_id: string;
+    generated_at: string;
+    body_md: string;
+    citation_stats: {
+        source_count: number;
+        conclusion_count: number;
+        recommendation_count: number;
+        untraced_claims: number;
+    };
+    conclusions?: {
+        id: string;
+        statement: string;
+        confidence: "HIGH" | "MEDIUM" | "LOW";
+        cited_sources: string[];
+    }[] | undefined;
+}, {
+    topic: string;
+    run_id: string;
+    generated_at: string;
+    body_md: string;
+    citation_stats: {
+        source_count: number;
+        conclusion_count: number;
+        recommendation_count: number;
+        untraced_claims: number;
+    };
+    conclusions?: {
+        id: string;
+        statement: string;
+        confidence: "HIGH" | "MEDIUM" | "LOW";
+        cited_sources: string[];
+    }[] | undefined;
+}>;
+export type ResearchDoc = z.infer<typeof ResearchDoc>;

package/dist/schemas/research-doc.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResearchDoc = exports.FormalConclusion = void 0;
+/**
+ * ResearchDoc — the published research artifact (research path).
+ *
+ * The synthesis LLM produces structured markdown matching the 10 canonical
+ * sections defined in `.caterpillar/prompts/research/synthesis.md`. The
+ * runner validates section presence + citation rules with a separate
+ * structural validator; this schema only enforces the surrounding metadata.
+ */
+const zod_1 = require("zod");
+const primitives_1 = require("./primitives");
+/** A formal conclusion line as parsed from the body. Used by the structural validator. */
+exports.FormalConclusion = zod_1.z.object({
+    id: zod_1.z.string().regex(/^C\d+$/),
+    statement: zod_1.z.string(),
+    confidence: primitives_1.Confidence,
+    /** Source premise IDs (S1, S2, …) cited by this conclusion. */
+    cited_sources: zod_1.z.array(zod_1.z.string().regex(/^S\d+$/)).min(1),
+});
+exports.ResearchDoc = zod_1.z.object({
+    run_id: primitives_1.RunId,
+    topic: zod_1.z.string(),
+    generated_at: primitives_1.IsoTimestamp,
+    /** Final published markdown — the body the auditor + reviewers read. */
+    body_md: zod_1.z.string().min(1),
+    /** Pre-extracted formal conclusions, used for downstream PRD grounding. */
+    conclusions: zod_1.z.array(exports.FormalConclusion).optional(),
+    /** Citation counts the structural validator reports back. */
+    citation_stats: zod_1.z.object({
+        source_count: zod_1.z.number().int().nonnegative(),
+        conclusion_count: zod_1.z.number().int().nonnegative(),
+        recommendation_count: zod_1.z.number().int().nonnegative(),
+        untraced_claims: zod_1.z.number().int().nonnegative(),
+    }),
+});

package/dist/search/arxiv-client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * arxiv-client — query the arXiv Atom API.
+ *
+ *   GET http://export.arxiv.org/api/query?search_query=<q>&max_results=N
+ *
+ * No auth required (arXiv rate-limits by IP — be polite, run queries
+ * sequentially or with small parallelism). Response is Atom XML.
+ *
+ * We parse with a tiny purpose-built reader instead of pulling in an XML
+ * dependency. The arXiv schema is stable and the fields we need (title,
+ * summary, id/url, published, authors) are well-known.
+ */
+export interface ArxivResult {
+    id: string;
+    title: string;
+    summary: string;
+    abstractUrl: string;
+    published: string;
+    authors: string[];
+}
+export interface ArxivSearchOpts {
+    query: string;
+    /** 1..30. arXiv accepts more but 5 is a sensible default for research. */
+    maxResults?: number;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /** Override base URL for tests. */
+    endpoint?: string;
+}
+export interface ArxivSearchResult {
+    query: string;
+    results: ArxivResult[];
+    responseBytes: number;
+    httpStatus: number;
+}
+export declare function arxivSearch(opts: ArxivSearchOpts): Promise<ArxivSearchResult>;
+/**
+ * Tiny Atom-XML reader for arXiv responses. Tolerant of CDATA + whitespace.
+ * Returns a normalised ArxivResult per `<entry>` element.
+ */
+export declare function parseArxivAtom(xml: string): ArxivResult[];

package/dist/search/arxiv-client.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * arxiv-client — query the arXiv Atom API.
+ *
+ *   GET http://export.arxiv.org/api/query?search_query=<q>&max_results=N
+ *
+ * No auth required (arXiv rate-limits by IP — be polite, run queries
+ * sequentially or with small parallelism). Response is Atom XML.
+ *
+ * We parse with a tiny purpose-built reader instead of pulling in an XML
+ * dependency. The arXiv schema is stable and the fields we need (title,
+ * summary, id/url, published, authors) are well-known.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arxivSearch = arxivSearch;
+exports.parseArxivAtom = parseArxivAtom;
+const DEFAULT_ENDPOINT = 'http://export.arxiv.org/api/query';
+async function arxivSearch(opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+    const max = Math.min(Math.max(1, opts.maxResults ?? 5), 30);
+    // arXiv wants `search_query` like `all:"agentic planning"` for phrase searches;
+    // we URL-encode the query and prefix with `all:` so the search hits any field.
+    const searchQuery = `all:${opts.query}`;
+    const url = `${endpoint}?search_query=${encodeURIComponent(searchQuery)}&max_results=${max}&sortBy=relevance`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30_000);
+    let response;
+    try {
+        response = await fetchImpl(url, { method: 'GET', signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpStatus = response.status;
+    const rawText = await response.text();
+    if (!response.ok) {
+        throw new Error(`arXiv returned ${httpStatus}: ${rawText.slice(0, 400)}`);
+    }
+    return {
+        query: opts.query,
+        results: parseArxivAtom(rawText),
+        responseBytes: Buffer.byteLength(rawText, 'utf8'),
+        httpStatus,
+    };
+}
+/**
+ * Tiny Atom-XML reader for arXiv responses. Tolerant of CDATA + whitespace.
+ * Returns a normalised ArxivResult per `<entry>` element.
+ */
+function parseArxivAtom(xml) {
+    const entries = [...xml.matchAll(/<entry\b[\s\S]*?<\/entry>/g)].map(m => m[0]);
+    const results = [];
+    for (const entry of entries) {
+        const id = extractFirst(entry, /<id>([\s\S]*?)<\/id>/);
+        const title = textOf(extractFirst(entry, /<title>([\s\S]*?)<\/title>/));
+        const summary = textOf(extractFirst(entry, /<summary>([\s\S]*?)<\/summary>/));
+        const published = extractFirst(entry, /<published>([\s\S]*?)<\/published>/);
+        const authors = [...entry.matchAll(/<author[^>]*>\s*<name>([\s\S]*?)<\/name>\s*<\/author>/g)]
+            .map(m => textOf(m[1]));
+        // arXiv ids look like "http://arxiv.org/abs/2401.12345v1" — strip version + scheme
+        const cleanId = id.replace(/^https?:\/\/arxiv\.org\/abs\//, '').replace(/v\d+$/, '');
+        const abstractUrl = `https://arxiv.org/abs/${cleanId}`;
+        if (cleanId && title) {
+            results.push({
+                id: cleanId,
+                title,
+                summary,
+                abstractUrl,
+                published: published || '',
+                authors,
+            });
+        }
+    }
+    return results;
+}
+function extractFirst(haystack, re) {
+    const m = haystack.match(re);
+    return m ? m[1].trim() : '';
+}
+/** Collapse whitespace + strip CDATA wrappers. */
+function textOf(raw) {
+    return raw
+        .replace(/^\s*<!\[CDATA\[/, '')
+        .replace(/\]\]>\s*$/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}

package/dist/search/hackernews-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * hackernews-client — query Algolia's HN Search API.
+ *
+ *   GET https://hn.algolia.com/api/v1/search?query=<q>&tags=story&hitsPerPage=N
+ *
+ * No auth, no rate-limits worth worrying about for research-scale traffic.
+ * Returns JSON with a `hits` array; we keep stories only (drop comments).
+ */
+export interface HackerNewsResult {
+    objectId: string;
+    title: string;
+    url: string;
+    hnUrl: string;
+    author: string;
+    points: number;
+    numComments: number;
+    createdAt: string;
+}
+export interface HackerNewsSearchOpts {
+    query: string;
+    /** 1..20. */
+    hitsPerPage?: number;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    endpoint?: string;
+}
+export interface HackerNewsSearchResult {
+    query: string;
+    results: HackerNewsResult[];
+    responseBytes: number;
+    httpStatus: number;
+}
+export declare function hackerNewsSearch(opts: HackerNewsSearchOpts): Promise<HackerNewsSearchResult>;

package/dist/search/hackernews-client.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * hackernews-client — query Algolia's HN Search API.
+ *
+ *   GET https://hn.algolia.com/api/v1/search?query=<q>&tags=story&hitsPerPage=N
+ *
+ * No auth, no rate-limits worth worrying about for research-scale traffic.
+ * Returns JSON with a `hits` array; we keep stories only (drop comments).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hackerNewsSearch = hackerNewsSearch;
+const DEFAULT_ENDPOINT = 'https://hn.algolia.com/api/v1/search';
+async function hackerNewsSearch(opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+    const hits = Math.min(Math.max(1, opts.hitsPerPage ?? 5), 20);
+    const url = `${endpoint}?query=${encodeURIComponent(opts.query)}&tags=story&hitsPerPage=${hits}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 30_000);
+    let response;
+    try {
+        response = await fetchImpl(url, { method: 'GET', signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpStatus = response.status;
+    const rawText = await response.text();
+    if (!response.ok) {
+        throw new Error(`Hacker News (Algolia) returned ${httpStatus}: ${rawText.slice(0, 400)}`);
+    }
+    const data = JSON.parse(rawText);
+    const results = (data.hits ?? []).map(h => ({
+        objectId: h.objectID ?? '',
+        title: h.title ?? '',
+        url: h.url ?? '',
+        hnUrl: h.objectID ? `https://news.ycombinator.com/item?id=${h.objectID}` : '',
+        author: h.author ?? '',
+        points: h.points ?? 0,
+        numComments: h.num_comments ?? 0,
+        createdAt: h.created_at ?? '',
+    })).filter(r => r.objectId && r.title);
+    return { query: opts.query, results, responseBytes: Buffer.byteLength(rawText, 'utf8'), httpStatus };
+}

package/dist/search/provider-result.d.ts

@@ -0,0 +1,25 @@
+/**
+ * provider-result — uniform shape every search provider's node emits.
+ *
+ * dedupe_and_rank consumes a flat array of these (across all providers)
+ * and produces RankedSource entries with S1..SN ids. Keeping the per-
+ * provider clients honest about a single shape avoids per-provider
+ * branches in the dedupe + ranking logic.
+ */
+import type { SearchProvider } from '../schemas';
+export interface ProviderResult {
+    provider: SearchProvider;
+    /** The query string that surfaced this result — used by the recall boost. */
+    fromQuery: string;
+    title: string;
+    /** Canonical-ish URL. dedupe_and_rank further canonicalizes. */
+    url: string;
+    /** Excerpt / abstract / snippet — capped at ≈500 chars by dedupe. */
+    content: string;
+    /** Provider-supplied relevance score, normalised to 0..1. */
+    score: number;
+    /** ISO publication date when the provider returns one (papers, news, patents). */
+    publishedDate?: string;
+    /** Optional author list (arxiv papers, patent inventors). */
+    authors?: string[];
+}

package/dist/search/provider-result.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });