@inflexa-ai/harness 0.15.1 → 0.17.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/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/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;

package/dist/citations/clients/crossref.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { encodeDoiPath, firstNonEmpty, parseYear, sourceOutcome } from "./common.js";
+import { requestJson } from "../../literature/sources/http.js";
+const CrossrefItemSchema = z
+    .object({
+    DOI: z.string().optional(),
+    URL: z.string().optional(),
+    title: z.array(z.string()).optional(),
+    author: z.array(z.object({ given: z.string().optional(), family: z.string().optional(), name: z.string().optional() }).passthrough()).optional(),
+    issued: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    published: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    "container-title": z.array(z.string()).optional(),
+    volume: z.string().optional(),
+    page: z.string().optional(),
+})
+    .passthrough();
+const ExactSchema = z.object({ message: CrossrefItemSchema });
+const SearchSchema = z.object({ message: z.object({ items: z.array(CrossrefItemSchema) }).passthrough() });
+function crossrefRecord(item, index) {
+    const doi = item.DOI?.toLocaleLowerCase("en-US");
+    const sourceRecordId = firstNonEmpty([doi, item.URL, `candidate-${index}`]);
+    if (sourceRecordId === undefined)
+        return undefined;
+    const title = firstNonEmpty(item.title ?? []);
+    const venue = firstNonEmpty(item["container-title"] ?? []);
+    const authors = item.author
+        ?.map((author) => firstNonEmpty([author.name, [author.given, author.family].filter(Boolean).join(" ")]))
+        .filter((author) => author !== undefined);
+    const dateParts = item.issued?.["date-parts"]?.[0] ?? item.published?.["date-parts"]?.[0];
+    return {
+        source: "crossref",
+        sourceRecordId,
+        identifiers: { ...(doi === undefined ? {} : { doi }) },
+        ...(title === undefined ? {} : { title }),
+        ...(authors === undefined || authors.length === 0 ? {} : { authors }),
+        ...(dateParts?.[0] === undefined ? {} : { year: parseYear(dateParts[0]) }),
+        ...(venue === undefined ? {} : { venue }),
+        ...(item.volume === undefined ? {} : { volume: item.volume }),
+        ...(item.page === undefined ? {} : { firstPage: item.page.split(/[-–]/)[0] }),
+        ...(item.URL === undefined ? {} : { url: item.URL }),
+    };
+}
+export function createCrossrefClient(options = {}) {
+    const headers = {};
+    if (options.userAgent)
+        headers["User-Agent"] = options.userAgent;
+    return {
+        source: "crossref",
+        async resolve(request, signal) {
+            if (!request.plan.applicable)
+                return sourceOutcome("crossref", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+            const registration = request.registrationAgency;
+            if (request.plan.operation === "crossref_doi_if_owned") {
+                // Skipping because ownership lies elsewhere is a finding; skipping because
+                // nobody could tell us is a gap, and reporting the gap as `not_applicable`
+                // would let an unchecked DOI reach `not_found` on complete coverage.
+                if (registration.status === "undetermined") {
+                    return sourceOutcome("crossref", request.plan.operation, "unavailable", 0, [], `registration agency undetermined: ${registration.detail}`);
+                }
+                if (registration.status === "absent") {
+                    return sourceOutcome("crossref", request.plan.operation, "not_applicable", 0, [], "the DOI handle does not resolve");
+                }
+                if (registration.agency.toLocaleLowerCase("en-US") !== "crossref") {
+                    return sourceOutcome("crossref", request.plan.operation, "not_applicable", 0, [], "DOI is not registered by Crossref");
+                }
+            }
+            const doi = request.normalized.identifiers.doi;
+            const exact = request.plan.operation === "crossref_doi_if_owned";
+            const url = exact
+                ? (() => {
+                    const target = new URL(`https://api.crossref.org/works/${encodeDoiPath(doi)}`);
+                    if (options.mailto)
+                        target.searchParams.set("mailto", options.mailto);
+                    return target.toString();
+                })()
+                : (() => {
+                    const params = new URLSearchParams({
+                        "query.bibliographic": request.input.citation,
+                        rows: String(options.maxCandidates ?? 5),
+                    });
+                    if (options.mailto)
+                        params.set("mailto", options.mailto);
+                    return `https://api.crossref.org/works?${params}`;
+                })();
+            const result = exact
+                ? await requestJson(url, ExactSchema, options, signal, { headers })
+                : await requestJson(url, SearchSchema, options, signal, { headers });
+            if (result.status !== "ok")
+                return sourceOutcome("crossref", request.plan.operation, result.status, 1, [], result.detail);
+            const items = exact ? [result.value.message] : result.value.message.items;
+            const records = items.flatMap((item, index) => {
+                const record = crossrefRecord(item, index);
+                return record === undefined ? [] : [record];
+            });
+            return sourceOutcome("crossref", request.plan.operation, records.length === 0 ? "no_data" : "ok", 1, records);
+        },
+    };
+}

package/dist/citations/clients/doi-registry.d.ts

@@ -0,0 +1,3 @@
+import type { CitationSourceClient } from "../types.js";
+import { type SourceHttpOptions } from "../../literature/sources/http.js";
+export declare function createDoiRegistryClient(options?: SourceHttpOptions): CitationSourceClient;

package/dist/citations/clients/doi-registry.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { encodeDoiPath, firstNonEmpty, parseYear, sourceOutcome } from "./common.js";
+import { requestJson } from "../../literature/sources/http.js";
+const HandleResponseSchema = z.object({ responseCode: z.number() }).passthrough();
+const RegistrationAgencySchema = z.array(z.object({ DOI: z.string().optional(), RA: z.string().optional() }).passthrough());
+const CslMetadataSchema = z
+    .object({
+    DOI: z.string().optional(),
+    id: z.string().optional(),
+    title: z.union([z.string(), z.array(z.string())]).optional(),
+    author: z.array(z.object({ given: z.string().optional(), family: z.string().optional(), literal: z.string().optional() }).passthrough()).optional(),
+    issued: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    published: z.object({ "date-parts": z.array(z.array(z.number())).optional() }).optional(),
+    "container-title": z.union([z.string(), z.array(z.string())]).optional(),
+    volume: z.string().optional(),
+    page: z.string().optional(),
+    URL: z.string().optional(),
+})
+    .passthrough();
+function scalar(value) {
+    return Array.isArray(value) ? firstNonEmpty(value) : firstNonEmpty([value]);
+}
+function cslRecord(doi, registrationAgency, metadata) {
+    const authors = metadata?.author
+        ?.map((author) => firstNonEmpty([author.literal, [author.given, author.family].filter(Boolean).join(" ")]))
+        .filter((author) => author !== undefined);
+    const dateParts = metadata?.issued?.["date-parts"]?.[0] ?? metadata?.published?.["date-parts"]?.[0];
+    const title = scalar(metadata?.title);
+    const venue = scalar(metadata?.["container-title"]);
+    return {
+        source: "doi_registry",
+        sourceRecordId: doi,
+        identifiers: { doi },
+        ...(title === undefined ? {} : { title }),
+        ...(authors === undefined || authors.length === 0 ? {} : { authors }),
+        ...(dateParts?.[0] === undefined ? {} : { year: parseYear(dateParts[0]) }),
+        ...(venue === undefined ? {} : { venue }),
+        ...(metadata?.volume === undefined ? {} : { volume: metadata.volume }),
+        ...(metadata?.page === undefined ? {} : { firstPage: metadata.page.split(/[-–]/)[0] }),
+        ...(registrationAgency === undefined ? {} : { registrationAgency }),
+        ...(metadata?.URL === undefined ? {} : { url: metadata.URL }),
+    };
+}
+export function createDoiRegistryClient(options = {}) {
+    return {
+        source: "doi_registry",
+        async resolve(request, signal) {
+            const doi = request.normalized.identifiers.doi;
+            if (!request.plan.applicable || doi === undefined) {
+                return sourceOutcome("doi_registry", request.plan.operation, "not_applicable", 0, [], request.plan.reason);
+            }
+            let requestCount = 1;
+            const handle = await requestJson(`https://doi.org/api/handles/${encodeDoiPath(doi)}`, HandleResponseSchema, options, signal);
+            if (handle.status !== "ok") {
+                return handle.status === "no_data"
+                    ? {
+                        ...sourceOutcome("doi_registry", request.plan.operation, handle.status, requestCount, [], handle.detail),
+                        identifierEvidence: { type: "doi", identifier: doi, exists: false, metadataAvailable: false },
+                    }
+                    : sourceOutcome("doi_registry", request.plan.operation, handle.status, requestCount, [], handle.detail);
+            }
+            if (handle.value.responseCode !== 1) {
+                return {
+                    ...sourceOutcome("doi_registry", request.plan.operation, "no_data", requestCount),
+                    identifierEvidence: { type: "doi", identifier: doi, exists: false, metadataAvailable: false },
+                };
+            }
+            requestCount += 1;
+            const agencyResult = await requestJson(`https://doi.org/doiRA/${encodeDoiPath(doi)}`, RegistrationAgencySchema, options, signal);
+            const registrationAgency = agencyResult.status === "ok" ? agencyResult.value[0]?.RA : undefined;
+            requestCount += 1;
+            const metadataResult = await requestJson(`https://doi.org/${encodeDoiPath(doi)}`, CslMetadataSchema, options, signal, {
+                headers: { Accept: "application/vnd.citationstyles.csl+json" },
+            });
+            const metadata = metadataResult.status === "ok" ? metadataResult.value : undefined;
+            const incomplete = agencyResult.status === "unavailable" || metadataResult.status === "unavailable";
+            const detail = [
+                agencyResult.status === "unavailable" ? agencyResult.detail : undefined,
+                metadataResult.status === "unavailable" ? metadataResult.detail : undefined,
+            ]
+                .filter((value) => value !== undefined)
+                .join("; ");
+            return {
+                ...sourceOutcome("doi_registry", request.plan.operation, incomplete ? "unavailable" : "ok", requestCount, [cslRecord(doi, registrationAgency, metadata)], detail || undefined),
+                identifierEvidence: {
+                    type: "doi",
+                    identifier: doi,
+                    exists: true,
+                    ...(registrationAgency === undefined ? {} : { registrationAgency }),
+                    metadataAvailable: metadata !== undefined,
+                },
+            };
+        },
+    };
+}

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

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