@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/agents/conversation-agent.d.ts

@@ -41,6 +41,7 @@ import type { RunLauncher } from "../execution/run-launcher.js";
 import { type SubmitReportDeps } from "../tools/iterate-report.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
+import type { CitationResolver } from "../citations/types.js";
 /** Canonical agent id — the single source of truth. */
 export declare const CONVERSATION_AGENT_ID: "conversation-agent";
 /**
@@ -58,6 +59,8 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * Omitted falls back to the no-op recorder.
      */
     readonly usageRecorder?: UsageRecorder;
+    /** Shared host-side bibliographic verification service. */
+    readonly citationResolver: CitationResolver;
     /** The LLM seam every loop-driving tool runs its sub-agent on. */
     readonly provider: ChatProvider;
     /** Postgres pool — plan persistence, run inspection, workspace index, working memory. */

package/dist/agents/conversation-agent.js

@@ -40,13 +40,14 @@ import { createListAvailablePackagesTool } from "../tools/sandbox/list-available
 import { createListAvailableRefsTool } from "../tools/sandbox/list-available-refs.js";
 import { createExecuteAnalysisTool } from "../tools/execute-analysis.js";
 import { planReportTool, createReportSubmitTool } from "../tools/iterate-report.js";
+import { createResolveCitationTool } from "../tools/research/resolve-citation.js";
 /** Canonical agent id — the single source of truth. */
 export const CONVERSATION_AGENT_ID = "conversation-agent";
 /** Runaway guard — heavy tool-driving turns need generous headroom. */
 const CONVERSATION_MAX_ITERATIONS = 50;
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export function createConversationAgent(deps) {
-    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, usageRecorder, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, usageRecorder, citationResolver, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
@@ -59,6 +60,8 @@ export function createConversationAgent(deps) {
         searchInteractionsTool,
         // Literature (search / details / fulltext behind one action).
         ncbi.pubmed,
+        // Verification of one caller-supplied citation (distinct from discovery).
+        createResolveCitationTool(citationResolver),
         // ChEMBL (compounds / drug / mechanism / bioactivity / targets behind one action).
         chemblTool,
         // PubChem (compound / crossrefs / assays behind one action).
@@ -132,7 +135,7 @@ export function createConversationAgent(deps) {
         createShowPlanTool(pool),
         showFileTool,
         // Batch literature/biology research (sub-agent as a loop-driving tool).
-        createLiteratureReviewerTool({ provider, model, bioKeys, usageRecorder }),
+        createLiteratureReviewerTool({ provider, model, bioKeys, citationResolver, usageRecorder }),
         // Cross-domain analogy generation (sub-agent as a loop-driving tool).
         createGenerateAnalogyReportTool({ provider, model, bioKeys, usageRecorder }),
         // Workspace semantic search + raw read/grep over the read seam.

package/dist/agents/report-builder.d.ts

@@ -19,6 +19,8 @@
 import type { AgentDefinition } from "../loop/types.js";
 import type { Tool } from "../tools/define-tool.js";
 export declare const REPORT_BUILDER_AGENT_ID = "report-builder";
+/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
+export declare const REPORT_BUILDER_SKILLS: readonly ["report-html"];
 export interface CreateReportBuilderAgentDeps {
     /** Model id — provenance / metric label; the provider owns the wire model. */
     readonly model: string;

package/dist/agents/report-builder.js

@@ -19,6 +19,8 @@
 import { reportBuilderPrompt } from "../prompts/report-builder.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 export const REPORT_BUILDER_AGENT_ID = "report-builder";
+/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
+export const REPORT_BUILDER_SKILLS = ["report-html"];
 /** Runaway guard — Jinja recovery may take several build/edit cycles. */
 const REPORT_BUILDER_MAX_ITERATIONS = 75;
 export function createReportBuilderAgent(deps) {

package/dist/agents/sandbox/shared.d.ts

@@ -27,6 +27,7 @@ import { type BlockerHolder } from "../../tools/sandbox/report-blocker.js";
 import type { AgentMeta, SandboxToolName } from "./types.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import type { Logger } from "../../lib/logger.js";
+import type { CitationResolver } from "../../citations/types.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
  * library docs, and run inspection. Spread into each agent's
@@ -74,6 +75,8 @@ export interface SandboxAgentDeps extends EnvironmentStorePaths {
     readonly step: SandboxStepCoords;
     /** API keys for the external bio/chem data sources. */
     readonly bioKeys: BioToolKeys;
+    /** Shared resolver. Required only when `meta.tools` declares `resolve_citation`. */
+    readonly citationResolver?: CitationResolver;
     /**
      * Per-run blocker cell (see the harness-sandbox-agents spec). When present, the agent gets a
      * `report_blocker` tool that records `{ kind: "blocker", reason }` into it;

package/dist/agents/sandbox/shared.js

@@ -38,6 +38,7 @@ import { createReportBlockerTool } from "../../tools/sandbox/report-blocker.js";
 import { toSandboxPath } from "../../workspace/paths.js";
 import { setActiveExecId } from "../../state/index.js";
 import { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
+import { createResolveCitationTool } from "../../tools/research/resolve-citation.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
  * library docs, and run inspection. Spread into each agent's
@@ -53,6 +54,9 @@ export const BASE_SANDBOX_TOOLS = ["listAvailablePackages", "listAvailableRefs",
 function resolveSandboxTools(deps, tools) {
     const ncbi = createNcbiTools(deps.bioKeys);
     const chemDb = createChemDbTools(deps.bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
+    if (tools.includes("resolve_citation") && deps.citationResolver === undefined) {
+        throw new Error('createSandboxAgent: SandboxToolName "resolve_citation" requires a CitationResolver dependency.');
+    }
     const registry = {
         listAvailablePackages: createListAvailablePackagesTool({ ...(deps.packagesFile ? { packagesFile: deps.packagesFile } : {}) }),
         listAvailableRefs: createListAvailableRefsTool({ ...(deps.refStorePath ? { refStorePath: deps.refStorePath } : {}) }),
@@ -60,6 +64,7 @@ function resolveSandboxTools(deps, tools) {
         queryDocs: queryDocsTool,
         inspectRun: createInspectRunTool(deps.pool),
         pubmed: ncbi.pubmed,
+        resolve_citation: deps.citationResolver === undefined ? undefined : createResolveCitationTool(deps.citationResolver),
         searchGene: searchGeneTool,
         lookupAnnotation: lookupAnnotationTool,
         searchInteractions: searchInteractionsTool,

package/dist/agents/sandbox/types.d.ts

@@ -12,7 +12,7 @@
  * in the tool's `perSource` report; the rest of the call still answers.
  */
 /** Closed allowlist of tools any sandbox agent may declare. */
-export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "pubmed" | "searchGene" | "lookupAnnotation" | "searchInteractions" | "chembl" | "pubchem" | "opentargets" | "geneDiseaseEvidence" | "drugGeneInteractions" | "genePreclinicalProfile" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "targetSafety" | "comptox";
+export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "pubmed" | "resolve_citation" | "searchGene" | "lookupAnnotation" | "searchInteractions" | "chembl" | "pubchem" | "opentargets" | "geneDiseaseEvidence" | "drugGeneInteractions" | "genePreclinicalProfile" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "targetSafety" | "comptox";
 /** Planner-facing metadata + tool allowlist for one sandbox agent. */
 export interface AgentMeta {
     /** Stable agent id — also the key in the catalog and the `AgentDefinition.id`. */

package/dist/app/chat-turn.d.ts

@@ -13,6 +13,7 @@
  * assembled `messages` and the standalone `userMessage` the caller persists.
  */
 import type { Pool } from "pg";
+import { type ThreadType } from "../memory/thread-store.js";
 import { type AssembledMessages } from "./message-assembly.js";
 import type { Logger } from "../lib/logger.js";
 export interface PrepareChatTurnDeps {
@@ -27,6 +28,7 @@ export interface PrepareChatTurnParams {
 }
 export type PrepareChatTurnResult = ({
     readonly kind: "ok";
+    readonly threadType: ThreadType;
 } & AssembledMessages) | {
     readonly kind: "not_found";
 };

package/dist/app/chat-turn.js

@@ -36,14 +36,23 @@ export async function prepareChatTurn(deps, params) {
     if (existing && existing.analysisId !== analysisId) {
         return { kind: "not_found" };
     }
+    // The type a caller resolves the turn's agent from. An existing row carries
+    // its own. An absent one defaults to `conversation` — the store's own
+    // default — so a best-effort create that fails non-fatally still leaves a
+    // usable type; a successful create overrides it from the returned row.
+    let threadType = existing ? existing.threadType : "conversation";
     // Seed the thread title from the first user message. Best-effort.
     try {
         if (!existing) {
-            unwrapOrThrow(await store.createThread({
+            // `createThread` is idempotent (ON CONFLICT reads the row back), so
+            // the returned row is authoritative for the type: a create that
+            // races another writer reflects the stored type, not an assumed one.
+            const created = unwrapOrThrow(await store.createThread({
                 threadId,
                 analysisId,
                 title: deriveThreadTitle(userInput),
             }));
+            threadType = created.threadType;
         }
         else if (!existing.title || existing.title.length === 0) {
             unwrapOrThrow(await store.updateTitle(threadId, deriveThreadTitle(userInput)));
@@ -65,5 +74,5 @@ export async function prepareChatTurn(deps, params) {
         history,
         workingMemory: createWorkingMemory(pool),
     });
-    return { kind: "ok", messages, userMessage };
+    return { kind: "ok", threadType, messages, userMessage };
 }

package/dist/app/spawn-report-session.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Report-session spawn — the host-agnostic operation that makes a `report`
+ * child thread from a conversation.
+ *
+ * The operation owns no table. It composes four reads and writes the store and
+ * the thread history already give: `getThread` for the parent, `latestSeq` for
+ * the anchor, `listThreads` for the count of report children, and
+ * `createThread` for the insert. The one storage read this capability adds,
+ * `latestSeq`, lives on the thread history, because that module owns the
+ * `messages` table.
+ *
+ * The reads and the insert take no lock and no transaction. A concurrent turn
+ * can append between the anchor read and the insert, and a retract can cut the
+ * parent's tail. A transaction cannot keep the parent still one turn later, so
+ * a lock buys no real guarantee. The anchor records the spawn point, and skew
+ * past the parent's current end is a normal state a reader expects.
+ *
+ * A conversation thread id comes from the host UI. But the spawn is a harness
+ * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
+ * the full row. A managed deployment gets the same behavior with no host code.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import type { DbError } from "../lib/db-result.js";
+import { type Thread, type ThreadInputError, type ThreadPage, type ThreadType } from "../memory/thread-store.js";
+/**
+ * A spawn the operation refuses before it writes a row. Distinct from
+ * `DbError`: nothing failed at the driver — the parent names a session the
+ * spawn refuses, and each variant carries the identifiers that say which values
+ * disagreed.
+ *
+ * The set is closed. `parent_not_found` covers an absent parent and an archived
+ * one alike, because `getThread` filters the tombstone and a spawn into hidden
+ * state is not permitted. `parent_not_a_conversation` keeps the tree flat: a
+ * report session cannot spawn another. `empty_parent_transcript` refuses a
+ * report on a parent that holds no messages, because such a report reports
+ * nothing.
+ */
+export type SpawnRefusal = {
+    readonly type: "parent_not_found";
+    readonly op: string;
+    readonly parentThreadId: string;
+} | {
+    readonly type: "parent_not_a_conversation";
+    readonly op: string;
+    readonly parentThreadId: string;
+    readonly threadType: ThreadType;
+} | {
+    readonly type: "empty_parent_transcript";
+    readonly op: string;
+    readonly parentThreadId: string;
+};
+/** The paging inputs `listReportSessions` forwards to the thread listing. */
+export interface ReportSessionPaging {
+    readonly page?: number;
+    readonly perPage?: number;
+}
+export interface ReportSessionSpawnDeps {
+    readonly pool: Pool;
+}
+export interface ReportSessionSpawn {
+    /**
+     * Make a `report` child of the parent conversation and return the full row.
+     * The child takes the analysis of the parent, the parent thread id, and the
+     * anchor — the parent's latest `messages.seq` at this moment.
+     *
+     * Refused with a `SpawnRefusal`, no row written: an absent or archived
+     * parent, a parent that is not a conversation, and a parent with no
+     * messages. A store refusal (`DbError`, `ThreadInputError`) passes through
+     * unchanged.
+     */
+    spawnReportSession(parentThreadId: string): ResultAsync<Thread, SpawnRefusal | DbError | ThreadInputError>;
+    /**
+     * The report sessions of one analysis, through the thread listing narrowed
+     * to the type `report`. It adds no predicate of its own, so its answer and
+     * the thread listing cannot disagree.
+     */
+    listReportSessions(analysisId: string, paging?: ReportSessionPaging): ResultAsync<ThreadPage, DbError>;
+}
+/**
+ * Build the report-session operations bound to a Postgres pool. The factory
+ * closure captures `pool` and constructs the store and the thread history from
+ * it, the same way the chat-turn preparation does.
+ */
+export declare function createReportSessionSpawn(deps: ReportSessionSpawnDeps): ReportSessionSpawn;

package/dist/app/spawn-report-session.js

@@ -0,0 +1,83 @@
+/**
+ * Report-session spawn — the host-agnostic operation that makes a `report`
+ * child thread from a conversation.
+ *
+ * The operation owns no table. It composes four reads and writes the store and
+ * the thread history already give: `getThread` for the parent, `latestSeq` for
+ * the anchor, `listThreads` for the count of report children, and
+ * `createThread` for the insert. The one storage read this capability adds,
+ * `latestSeq`, lives on the thread history, because that module owns the
+ * `messages` table.
+ *
+ * The reads and the insert take no lock and no transaction. A concurrent turn
+ * can append between the anchor read and the insert, and a retract can cut the
+ * parent's tail. A transaction cannot keep the parent still one turn later, so
+ * a lock buys no real guarantee. The anchor records the spawn point, and skew
+ * past the parent's current end is a normal state a reader expects.
+ *
+ * A conversation thread id comes from the host UI. But the spawn is a harness
+ * operation with no UI in front of it. Thus it mints a `randomUUID` and returns
+ * the full row. A managed deployment gets the same behavior with no host code.
+ */
+import { randomUUID } from "node:crypto";
+import { errAsync } from "neverthrow";
+import { createThreadHistory } from "../memory/thread-history.js";
+import { createThreadStore } from "../memory/thread-store.js";
+const _assertDomainError = true;
+const OP = "spawn-report-session";
+/**
+ * Compose the child title. N counts the existing report children of the parent
+ * plus one. A parent with no title yields `Report N` alone, because the seed of
+ * the parent title is best-effort and can be absent.
+ */
+function composeTitle(parentTitle, n) {
+    const suffix = `Report ${n}`;
+    return parentTitle && parentTitle.length > 0 ? `${parentTitle} — ${suffix}` : suffix;
+}
+/**
+ * Build the report-session operations bound to a Postgres pool. The factory
+ * closure captures `pool` and constructs the store and the thread history from
+ * it, the same way the chat-turn preparation does.
+ */
+export function createReportSessionSpawn(deps) {
+    const { pool } = deps;
+    const store = createThreadStore(pool);
+    const history = createThreadHistory(pool);
+    function spawnReportSession(parentThreadId) {
+        return store.getThread(parentThreadId).andThen((parent) => {
+            // An absent parent and an archived one arrive the same way — `getThread`
+            // filters the tombstone — and both refuse as `parent_not_found`.
+            if (parent === null) {
+                return errAsync({ type: "parent_not_found", op: OP, parentThreadId });
+            }
+            // The tree stays flat: only a conversation spawns a report.
+            if (parent.threadType !== "conversation") {
+                return errAsync({ type: "parent_not_a_conversation", op: OP, parentThreadId, threadType: parent.threadType });
+            }
+            return history.latestSeq(parentThreadId).andThen((anchor) => {
+                // `null` is a parent with no messages. A report on an empty transcript
+                // reports nothing, so the refusal is the correct answer.
+                if (anchor === null) {
+                    return errAsync({ type: "empty_parent_transcript", op: OP, parentThreadId });
+                }
+                // `total`, not the page length: N counts every existing report child,
+                // not the count on one page. Two concurrent spawns can compose one N.
+                // The result is two titles a user renames, and no identifier collides.
+                return store
+                    .listThreads({ analysisId: parent.analysisId, type: "report", parentThreadId })
+                    .andThen((children) => store.createThread({
+                    threadId: randomUUID(),
+                    analysisId: parent.analysisId,
+                    title: composeTitle(parent.title, children.total + 1),
+                    type: "report",
+                    parentThreadId,
+                    parentSeq: anchor,
+                }));
+            });
+        });
+    }
+    function listReportSessions(analysisId, paging = {}) {
+        return store.listThreads({ analysisId, type: "report", ...paging });
+    }
+    return { spawnReportSession, listReportSessions };
+}

package/dist/app/synthesize-run.d.ts

@@ -25,6 +25,7 @@ import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { SynthesisStatus } from "../state/index.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
+import type { CitationResolver } from "../citations/types.js";
 export interface SynthesizeRunDeps {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
@@ -38,6 +39,8 @@ export interface SynthesizeRunDeps {
     readonly synthesisModel: string;
     /** API keys for the bio/chem tools the embedded literature reviewer uses. */
     readonly bioKeys: BioToolKeys;
+    /** Shared resolver used by the embedded literature reviewer. */
+    readonly citationResolver: CitationResolver;
     /** LLM usage-accounting seam for the synthesizer loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
 }

package/dist/app/synthesize-run.js

@@ -22,7 +22,7 @@ import { loadPlan, queryRun } from "../state/index.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 export async function synthesizeRun(deps, params) {
-    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys, usageRecorder } = deps;
+    const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys, citationResolver, usageRecorder } = deps;
     const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
     await onProgress("starting", "Beginning literature-grounded synthesis");
     try {
@@ -47,6 +47,7 @@ export async function synthesizeRun(deps, params) {
             session: synthesizerSession,
             model: synthesisModel,
             bioKeys,
+            citationResolver,
             usageRecorder,
             summaries,
             planNarrative,

package/dist/citations/__fixtures__/resolver.d.ts

@@ -0,0 +1,3 @@
+import type { CitationResolver } from "../types.js";
+/** Test-only resolver for construction paths that do not execute citation tools. */
+export declare const unusedCitationResolver: CitationResolver;

package/dist/citations/__fixtures__/resolver.js

@@ -0,0 +1,9 @@
+/** Test-only resolver for construction paths that do not execute citation tools. */
+export const unusedCitationResolver = {
+    async resolveOne() {
+        throw new Error("unusedCitationResolver.resolveOne was unexpectedly called");
+    },
+    async resolveMany() {
+        throw new Error("unusedCitationResolver.resolveMany was unexpectedly called");
+    },
+};

package/dist/citations/aggregate.d.ts

@@ -0,0 +1,3 @@
+import { type CitationMatchConfig } from "./match.js";
+import type { CitationInput, CitationResolutionResult, CitationSourceOutcome, NormalizedCitation } from "./types.js";
+export declare function aggregateCitationResolution(input: CitationInput, normalized: NormalizedCitation, sourceOutcomes: readonly CitationSourceOutcome[], matchConfig?: CitationMatchConfig): CitationResolutionResult;

package/dist/citations/aggregate.js

@@ -0,0 +1,44 @@
+import { compareSuppliedMetadata, detectCitationConflicts } from "./compare.js";
+import { clusterCitationRecords, selectCitationCluster, DEFAULT_MATCH_CONFIG } from "./match.js";
+function deriveCoverage(outcomes, comparisonsIncomplete) {
+    const applicable = outcomes.filter((outcome) => outcome.status !== "not_applicable");
+    if (applicable.length === 0)
+        return "none";
+    const hasCoverage = applicable.some((outcome) => outcome.status === "ok" || outcome.status === "no_data" || outcome.records.length > 0 || outcome.identifierEvidence?.exists === true);
+    if (!hasCoverage)
+        return "none";
+    if (applicable.some((outcome) => outcome.status === "unavailable") || comparisonsIncomplete)
+        return "partial";
+    return "complete";
+}
+function deriveVerdict(normalized, selected, comparisons, coverage) {
+    if (normalized.unsupportedWorkKind !== undefined)
+        return "unverifiable";
+    if (selected !== undefined) {
+        if (comparisons.some((comparison) => comparison.status === "mismatch"))
+            return "metadata_mismatch";
+        if (comparisons.some((comparison) => comparison.status === "not_compared"))
+            return "inconclusive";
+        return "verified";
+    }
+    return coverage === "complete" ? "not_found" : "inconclusive";
+}
+export function aggregateCitationResolution(input, normalized, sourceOutcomes, matchConfig = DEFAULT_MATCH_CONFIG) {
+    const records = sourceOutcomes.flatMap((outcome) => outcome.records);
+    const candidates = clusterCitationRecords(input, normalized, records, matchConfig);
+    const selected = selectCitationCluster(candidates, matchConfig);
+    const comparisons = compareSuppliedMetadata(input, selected);
+    const coverage = deriveCoverage(sourceOutcomes, comparisons.some((comparison) => comparison.status === "not_compared"));
+    const verdict = deriveVerdict(normalized, selected, comparisons, coverage);
+    return {
+        input,
+        normalized,
+        sourceOutcomes: [...sourceOutcomes],
+        candidates,
+        ...(selected === undefined ? {} : { selectedClusterId: selected.id }),
+        comparisons,
+        conflicts: detectCitationConflicts(candidates),
+        verdict,
+        coverage,
+    };
+}

package/dist/citations/clients/arxiv.d.ts

@@ -0,0 +1,6 @@
+import type { CitationSourceClient } from "../types.js";
+import type { SourceHttpOptions } from "../../literature/sources/http.js";
+export interface ArxivCitationClientOptions extends SourceHttpOptions {
+    readonly maxCandidates?: number;
+}
+export declare function createArxivCitationClient(options?: ArxivCitationClientOptions): CitationSourceClient;

package/dist/citations/clients/arxiv.js

@@ -0,0 +1,34 @@
+import { extractArxivId } from "../normalize.js";
+import { createArxivSource } from "../../literature/sources/arxiv.js";
+import { parseYear, sourceOutcome } from "./common.js";
+function arxivRecord(paper) {
+    const year = parseYear(paper.published);
+    const identifier = extractArxivId(paper.id) ?? paper.id.toLocaleLowerCase("en-US");
+    return {
+        source: "arxiv",
+        sourceRecordId: paper.id,
+        identifiers: { arxiv: identifier },
+        title: paper.title,
+        authors: paper.authors,
+        ...(year === undefined ? {} : { year }),
+        venue: "arXiv",
+        url: paper.url,
+    };
+}
+export function createArxivCitationClient(options = {}) {
+    const source = createArxivSource(options);
+    return {
+        source: "arxiv",
+        async resolve(request, signal) {
+            if (!request.plan.applicable)
+                return sourceOutcome("arxiv", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+            const result = request.plan.operation === "arxiv_exact"
+                ? await source.lookupExact(request.normalized.identifiers.arxiv, options.maxCandidates ?? 5, signal)
+                : await source.search({ query: request.input.title ?? request.input.citation, limit: options.maxCandidates ?? 5 }, signal);
+            if (result.status !== "ok")
+                return sourceOutcome("arxiv", request.plan.operation, result.status, 1, [], result.detail);
+            const records = result.value.map(arxivRecord);
+            return sourceOutcome("arxiv", request.plan.operation, records.length === 0 ? "no_data" : "ok", 1, records);
+        },
+    };
+}

package/dist/citations/clients/common.d.ts

@@ -0,0 +1,11 @@
+import type { CitationRecord, CitationSource, CitationSourceOperation, CitationSourceOutcome, CitationSourcePlanItem } from "../types.js";
+export declare function notApplicableOutcome(plan: CitationSourcePlanItem): CitationSourceOutcome;
+export declare function sourceOutcome(source: CitationSource, operation: CitationSourceOperation, status: CitationSourceOutcome["status"], requestCount: number, records?: CitationRecord[], detail?: string): CitationSourceOutcome;
+/**
+ * Percent-encode a DOI for use as a URL path segment. A DOI suffix may legally
+ * contain `#`, `?`, and `%`, each of which silently re-parses the URL when
+ * interpolated raw; only the prefix/suffix `/` is structural and stays literal.
+ */
+export declare function encodeDoiPath(doi: string): string;
+export declare function parseYear(value: unknown): number | undefined;
+export declare function firstNonEmpty(values: readonly unknown[]): string | undefined;

package/dist/citations/clients/common.js

@@ -0,0 +1,43 @@
+export function notApplicableOutcome(plan) {
+    return {
+        source: plan.source,
+        operation: plan.operation,
+        status: "not_applicable",
+        requestCount: 0,
+        records: [],
+        detail: plan.reason,
+    };
+}
+export function sourceOutcome(source, operation, status, requestCount, records = [], detail) {
+    return {
+        source,
+        operation,
+        status,
+        requestCount,
+        records,
+        ...(detail === undefined ? {} : { detail }),
+    };
+}
+/**
+ * Percent-encode a DOI for use as a URL path segment. A DOI suffix may legally
+ * contain `#`, `?`, and `%`, each of which silently re-parses the URL when
+ * interpolated raw; only the prefix/suffix `/` is structural and stays literal.
+ */
+export function encodeDoiPath(doi) {
+    return doi.split("/").map(encodeURIComponent).join("/");
+}
+export function parseYear(value) {
+    if (typeof value === "number" && Number.isInteger(value))
+        return value;
+    if (typeof value !== "string")
+        return undefined;
+    const match = value.match(/\b(1[5-9]\d{2}|20\d{2}|21\d{2})\b/);
+    return match?.[1] === undefined ? undefined : Number(match[1]);
+}
+export function firstNonEmpty(values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}

package/dist/citations/clients/crossref.d.ts

@@ -0,0 +1,8 @@
+import type { CitationSourceClient } from "../types.js";
+import { type SourceHttpOptions } from "../../literature/sources/http.js";
+export interface CrossrefClientOptions extends SourceHttpOptions {
+    readonly mailto?: string;
+    readonly userAgent?: string;
+    readonly maxCandidates?: number;
+}
+export declare function createCrossrefClient(options?: CrossrefClientOptions): CitationSourceClient;