@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/data/safety-panel-schema.d.ts

@@ -1,8 +1,4 @@
 import { z } from "zod";
-export declare const ORGAN_SYSTEMS: readonly ["cardiac", "hepatic", "renal", "cns", "hematologic", "gi", "respiratory", "metabolic", "immune"];
-export declare const SEVERITIES: readonly ["high", "medium", "low"];
-export type OrganSystem = (typeof ORGAN_SYSTEMS)[number];
-export type Severity = (typeof SEVERITIES)[number];
 export declare const CHEMBL_RE: RegExp;
 export declare const UNIPROT_RE: RegExp;
 export declare const SafetyTargetSchema: z.ZodObject<{
@@ -16,11 +12,20 @@ export declare const SafetyTargetSchema: z.ZodObject<{
         metabolic: "metabolic";
         immune: "immune";
         hepatic: "hepatic";
+        musculoskeletal: "musculoskeletal";
         cns: "cns";
         renal: "renal";
+        reproductive: "reproductive";
         respiratory: "respiratory";
         cardiac: "cardiac";
+        vascular: "vascular";
+        pns: "pns";
         gi: "gi";
+        pancreas: "pancreas";
+        endocrine_thyroid: "endocrine_thyroid";
+        dermatologic: "dermatologic";
+        ocular: "ocular";
+        oncology: "oncology";
     }>;
     clinical_consequence: z.ZodString;
     severity: z.ZodEnum<{
@@ -46,11 +51,20 @@ export declare const SafetyPanelFileSchema: z.ZodObject<{
             metabolic: "metabolic";
             immune: "immune";
             hepatic: "hepatic";
+            musculoskeletal: "musculoskeletal";
             cns: "cns";
             renal: "renal";
+            reproductive: "reproductive";
             respiratory: "respiratory";
             cardiac: "cardiac";
+            vascular: "vascular";
+            pns: "pns";
             gi: "gi";
+            pancreas: "pancreas";
+            endocrine_thyroid: "endocrine_thyroid";
+            dermatologic: "dermatologic";
+            ocular: "ocular";
+            oncology: "oncology";
         }>;
         clinical_consequence: z.ZodString;
         severity: z.ZodEnum<{
@@ -61,4 +75,3 @@ export declare const SafetyPanelFileSchema: z.ZodObject<{
         references: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export type SafetyPanelFile = z.infer<typeof SafetyPanelFileSchema>;

package/dist/data/safety-panel-schema.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-export const ORGAN_SYSTEMS = ["cardiac", "hepatic", "renal", "cns", "hematologic", "gi", "respiratory", "metabolic", "immune"];
-export const SEVERITIES = ["high", "medium", "low"];
+import { OrganSystemSchema } from "../contracts/organ-system.js";
+import { SeveritySchema } from "../contracts/severity.js";
 export const CHEMBL_RE = /^CHEMBL\d+$/;
 // UniProt 6-char accession: letter (any A-Z, covering A-N, O, P, Q, R-Z sub-families),
 // followed by a digit, three alphanumerics, and a final digit.
@@ -21,9 +21,9 @@ export const SafetyTargetSchema = z.object({
     uniprot: UniprotSchema,
     ensembl_gene_id: EnsemblGeneSchema.optional(),
     name: z.string().min(1).max(120),
-    organ_system: z.enum(ORGAN_SYSTEMS),
+    organ_system: OrganSystemSchema,
     clinical_consequence: z.string().min(1).max(200),
-    severity: z.enum(SEVERITIES),
+    severity: SeveritySchema,
     references: z.array(ReferenceSchema).min(1),
 });
 export const SafetyPanelFileSchema = z.object({

package/dist/execution/artifact-metadata.js

@@ -95,6 +95,7 @@ function buildSubmitTool(holder, knownPaths) {
             "remaining}: accepted=true means every file now has metadata — STOP. " +
             "Otherwise drop the unknownPaths and describe the remaining files.",
         inputSchema: SubmitFileMetadataInputSchema,
+        describeCall: "none",
         execute: async (input) => {
             const unknownPaths = [];
             for (const entry of input.files) {

package/dist/execution/report-runner.js

@@ -39,11 +39,9 @@ import { passthroughStep } from "../loop/run-step.js";
 import { previewVersionDir, previewDir, latestPreviewVersion } from "../workspace/paths.js";
 import { withPreviewLock } from "../tools/lib/preview-lock.js";
 import { createBuildReportTool, createSubmitReportTool, createMintPreviewUrlTool, createPreviewSnapshotTool, createVersionFsTools, } from "../tools/report/index.js";
-import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID } from "../agents/report-builder.js";
+import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID, REPORT_BUILDER_SKILLS } from "../agents/report-builder.js";
 import { createSkillTools } from "../tools/sandbox/skills.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-/** Skill pack the report-builder prompt directs the model to read (design-system reference). */
-const REPORT_BUILDER_SKILLS = ["report-html"];
 const REPORT_AGENT_MAX_STEPS = 75;
 export async function runReportIteration(deps, opts) {
     const logger = (deps.logger ?? createNoopLogger()).named("report-runner").with({ previewId: opts.previewId });

package/dist/execution/run-synthesis.d.ts

@@ -31,6 +31,7 @@ import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { CitationResolver } from "../citations/types.js";
 /**
  * The synthesizer's agent identity — the `source.agentId` on its loop events
  * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
@@ -67,6 +68,8 @@ export interface GenerateRunSynthesisInput {
     readonly model: 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 + reviewer loops; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
     /** Step summaries from the completed run. Non-empty. */

package/dist/execution/run-synthesis.js

@@ -270,6 +270,7 @@ function buildValidateTool(ctx) {
         inputSchema: z.object({
             synthesis: z.unknown().describe("The candidate synthesis, in any shape. Field-by-field schema: see submit_synthesis."),
         }),
+        describeCall: "none",
         execute: async (input) => {
             const result = fullyValidate(input.synthesis, ctx);
             return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
@@ -289,6 +290,7 @@ function buildSubmitTool(holder, ctx) {
             "already-accepted synthesis untouched; a later accepted submission " +
             "supersedes an earlier one.",
         inputSchema: z.object({ synthesis: RunSynthesisSchema }),
+        describeCall: "none",
         execute: async (input) => {
             const result = fullyValidate(input.synthesis, ctx);
             if (!result.valid) {
@@ -349,6 +351,7 @@ export async function generateRunSynthesis(input) {
         provider: input.provider,
         model: input.model,
         bioKeys: input.bioKeys,
+        citationResolver: input.citationResolver,
         usageRecorder: input.usageRecorder,
     });
     const validateTool = buildValidateTool(innerCtx);

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  */
 export { assembleCoreRuntime } from "./runtime/assemble.js";
 export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable } from "./runtime/assemble.js";
+export type { ThreadAgentResolver, UnregisteredThreadType } from "./runtime/assemble.js";
 export { bootHarness } from "./runtime/boot.js";
 export type { BootHarnessDeps, BootedHarness } from "./runtime/boot.js";
 export { createConversationAgent } from "./agents/conversation-agent.js";
@@ -31,6 +32,11 @@ export type { DbosWorkflowPurgerDeps } from "./execution/dbos-workflow-purger.js
 export type { WorkflowPurger } from "./execution/workflow-purger.js";
 export { defineTool, isToolError } from "./tools/define-tool.js";
 export type { Tool, ToolDefinition, ToolContext, ToolError } from "./tools/define-tool.js";
+export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
+export { createCitationResolver } from "./citations/resolve.js";
+export type { CitationResolverConfig, CitationResolverDependencies, CitationResolverSourceConfig } from "./citations/resolve.js";
+export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
+export type { CitationKind, CitationInput, CitationSource, CitationSourceStatus, CitationResolver, CitationResolveOptions, CitationResolutionResult, CitationVerdict, CitationCoverage, ComparisonStatus, CitationField, UnsupportedWorkKind, CitationIdentifiers, NormalizedCitationMetadata, NormalizedCitation, CitationSourceOutcome, CitationRecord, IdentifierEvidence, CitationFieldComparison, CitationConflict, CitationCandidateCluster, CitationSourceClient, CitationSourceRequest, CitationSourceOperation, CitationSourcePlanItem, RegistrationAgencyEvidence, } from "./citations/types.js";
 export { createAskGateway } from "./tools/approval/gateway.js";
 export type { AskGateway, AskGatewayDeps, AskContext, AnswerOutcome, PendingAsk } from "./tools/approval/gateway.js";
 export { UnavailableAsk, AskRejectedError } from "./tools/approval/contract.js";
@@ -56,7 +62,7 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 export { prepareChatTurn } from "./app/chat-turn.js";
 export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
-export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
+export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome, ConversationTurn } from "./memory/thread-history.js";
 export { syntheticUserMessage, syntheticRecordMessage, isSyntheticUserMessage, isSyntheticRecordMessage } from "./memory/ai-sdk-message-storage.js";
@@ -72,6 +78,9 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./cont
 export type { CortexChatPartType, PartDescriptor, PartEmitter, PartConsumer } from "./contracts/part-registry.js";
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
 export type { DbosConfig } from "./runtime/dbos.js";
+export { dbosState } from "./runtime/dbos.js";
+export type { DbosState } from "./runtime/dbos.js";
+export { isDraining } from "./runtime/lifecycle.js";
 export { StatusString } from "@dbos-inc/dbos-sdk";
 export type { WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 export { createPool } from "./lib/storage.js";
@@ -113,6 +122,8 @@ export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export type { ExecuteAnalysisDeps, ExecuteAnalysisInput, ExecuteAnalysisResult, RunObservation, RunProvenanceEvent, RunStepObservation, StepRuntimeStatus, } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
 export type { SandboxStepDeps, SandboxStepInput, SandboxStepResult, SandboxAgentBuildContext } from "./workflows/sandbox-step.js";
+export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";
+export type { ClaimInvestigationConfig } from "./workflows/target-assessment/investigation/index.js";
 export { createRunEventStream } from "./execution/run-event-stream.js";
 export type { RunEventStream, RunEventStreamDeps, RunEventSubscribeOptions, RunEventPartHandler } from "./execution/run-event-stream.js";
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";

package/dist/index.js

@@ -33,6 +33,18 @@ export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
 // Tool primitive.
 export { defineTool, isToolError } from "./tools/define-tool.js";
+// Tool-call-detail authoring aids for an embedder that contributes a host tool.
+// A `describeCall` hook that pre-empts truncation — a count in place of a
+// mid-value cut that would name a file that does not exist — must gate on the
+// SAME bound the harness enforces at the emit site. Thus `DETAIL_MAX_LENGTH`
+// rides the curated surface, so a host reads the one number rather than copying
+// it and drifting when the harness retunes the cap. `normalizeDetail` is that
+// emit-site transform, exported so a host can assert a hook's output against
+// exactly what the harness will render.
+export { normalizeDetail, DETAIL_MAX_LENGTH } from "./loop/tool-detail.js";
+// Host-agnostic citation verification service and its public contracts.
+export { createCitationResolver } from "./citations/resolve.js";
+export { CitationKindSchema, CitationInputSchema, CitationSourceSchema, CitationSourceStatusSchema, CitationResolutionResultSchema, CitationVerdictSchema, CitationCoverageSchema, ComparisonStatusSchema, CitationFieldSchema, UnsupportedWorkKindSchema, CitationIdentifiersSchema, NormalizedCitationMetadataSchema, NormalizedCitationSchema, CitationRecordSchema, IdentifierEvidenceSchema, CitationSourceOutcomeSchema, CitationFieldComparisonSchema, CitationConflictSchema, CitationCandidateClusterSchema, CitationClusterRelationSchema, CitationSourceOperationSchema, CitationSourcePlanItemSchema, } from "./citations/types.js";
 // Seam: tool approval (`ctx.ask`). `createAskGateway` realizes the `Ask` seam
 // over the injected `Pool` and carries the outward `answer`/`pending` API plus
 // the boot-time `sweepExpired`; `UnavailableAsk` is the shipped deny-by-default
@@ -117,6 +129,12 @@ export { PART_REGISTRY, isTransient, isReconciling, isSidebarPart } from "./cont
 // older releases could leave PENDING `ephemeral:*` rows that recovery would
 // otherwise re-dispatch. No current workflow creates that prefix.
 export { launchDbos, shutdownDbos, sweepEphemeralWorkflows } from "./runtime/dbos.js";
+// The readiness pair. Both flags are mutated by harness-owned code an embedder
+// does not call itself — `launchDbos` flips the DBOS state, and the `shutdown`
+// handle `bootHarness` returns marks draining — so the reads have to come from
+// here for a host's own probe to reflect them at all.
+export { dbosState } from "./runtime/dbos.js";
+export { isDraining } from "./runtime/lifecycle.js";
 // DBOS workflow-status vocabulary. An embedder that reads its own
 // `dbos.workflow_status` rows must classify them against the SDK's status set,
 // but must never depend on `@dbos-inc/dbos-sdk` directly — the SDK is
@@ -176,6 +194,10 @@ export { ExecEventMessageSchema } from "./sandbox/types.js";
 // these, but an embedder running only the run engine registers them directly.
 export { registerExecuteAnalysis } from "./workflows/execute-analysis.js";
 export { registerSandboxStep } from "./workflows/sandbox-step.js";
+// Target assessment — the bounds its claim-investigation phase runs under. An
+// embedder wiring `executeTargetAssessment` sets these at its composition root;
+// the dossier reports whichever values were in force.
+export { DEFAULT_CLAIM_INVESTIGATION_CONFIG } from "./workflows/target-assessment/investigation/index.js";
 // Run-event read seam — the fine-grained durable channel beside `observeRun`.
 // The two are a deliberate pair, not a duplication: `observeRun` is the coarse,
 // in-process run/step snapshot a workflow hands its host synchronously, and it

package/dist/lib/async-utils.d.ts

@@ -1,10 +1,22 @@
 /**
- * Shared async utilities — sleep and bounded-concurrency map.
+ * Shared async utilities — sleep and a bounded-concurrency `Promise.all`.
  */
 /** Promise-based delay. */
 export declare function sleep(ms: number): Promise<void>;
 /**
- * Map over items with bounded concurrency.
- * At most `concurrency` items are processed simultaneously.
+ * Run each task with a cap on how many run at the same time, and give back the results in the order of
+ * the input.
+ *
+ * The signature mirrors `Promise.all`. The mapped return type is element-wise, thus a tuple of thunks
+ * with different return types keeps each one, and a plain array of thunks gives a plain array. The input
+ * is an array of thunks and not an array of promises, because a promise is already running when it is
+ * made, and a cap over a set of started promises caps nothing.
+ *
+ * `concurrency` must be a number at or above 1. p-queue throws a `TypeError` for any other value.
+ *
+ * The failure behavior is that of `Promise.all`. The first rejection rejects the whole call, and each
+ * task that the queue already started still runs to completion.
  */
-export declare function mapConcurrent<T, R>(items: T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function allWithConcurrency<T extends readonly (() => unknown)[] | []>(tasks: T, concurrency: number): Promise<{
+    -readonly [P in keyof T]: Awaited<T[P] extends () => infer R ? R : never>;
+}>;

package/dist/lib/async-utils.js

@@ -1,24 +1,29 @@
 /**
- * Shared async utilities — sleep and bounded-concurrency map.
+ * Shared async utilities — sleep and a bounded-concurrency `Promise.all`.
  */
+import PQueue from "p-queue";
 /** Promise-based delay. */
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Map over items with bounded concurrency.
- * At most `concurrency` items are processed simultaneously.
+ * Run each task with a cap on how many run at the same time, and give back the results in the order of
+ * the input.
+ *
+ * The signature mirrors `Promise.all`. The mapped return type is element-wise, thus a tuple of thunks
+ * with different return types keeps each one, and a plain array of thunks gives a plain array. The input
+ * is an array of thunks and not an array of promises, because a promise is already running when it is
+ * made, and a cap over a set of started promises caps nothing.
+ *
+ * `concurrency` must be a number at or above 1. p-queue throws a `TypeError` for any other value.
+ *
+ * The failure behavior is that of `Promise.all`. The first rejection rejects the whole call, and each
+ * task that the queue already started still runs to completion.
  */
-export async function mapConcurrent(items, concurrency, fn) {
-    const results = new Array(items.length);
-    let nextIndex = 0;
-    async function worker() {
-        while (nextIndex < items.length) {
-            const i = nextIndex++;
-            results[i] = await fn(items[i], i);
-        }
-    }
-    const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
-    await Promise.all(workers);
-    return results;
+export function allWithConcurrency(tasks, concurrency) {
+    const queue = new PQueue({ concurrency });
+    // `addAll` collapses every task onto one result type, thus it cannot express the element-wise type
+    // above. The cast is sound because `addAll` maps the input array through `Promise.all`, which keeps
+    // the position of each task, and each element is the awaited return of the task at that position.
+    return queue.addAll(tasks);
 }

package/dist/lib/cache.d.ts

@@ -0,0 +1,8 @@
+export declare class BoundedTtlCache<Value> {
+    private readonly maximum;
+    private readonly now;
+    private readonly entries;
+    constructor(maximum: number, now?: () => number);
+    get(key: string): Value | undefined;
+    set(key: string, value: Value, ttlMs: number): void;
+}

package/dist/lib/cache.js

@@ -0,0 +1,35 @@
+export class BoundedTtlCache {
+    maximum;
+    now;
+    entries = new Map();
+    constructor(maximum, now = Date.now) {
+        this.maximum = maximum;
+        this.now = now;
+        if (!Number.isInteger(maximum) || maximum < 0)
+            throw new Error("cache maximum must be a non-negative integer");
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        if (this.maximum === 0 || ttlMs <= 0)
+            return;
+        this.entries.delete(key);
+        this.entries.set(key, { value, expiresAt: this.now() + ttlMs });
+        while (this.entries.size > this.maximum) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+}

package/dist/lib/host-concurrency.js

@@ -27,6 +27,7 @@ const DEFAULT_LIMITS = {
     hgnc: 6,
     uniprot: 6,
     iuphar: 4,
+    monarch: 3,
     ema: 2,
     pubchem: 4,
     "annotation-llm": 4,

package/dist/lib/rate-limit.d.ts

@@ -0,0 +1,35 @@
+export interface RateLimitConfig {
+    readonly maxConcurrency: number;
+    readonly requestsPerSecond: number;
+    /**
+     * Retry policy for the source's HTTP layer. Retries re-enter the limiter as
+     * fresh attempts, so they are paced like any other request; the limiter
+     * itself does not read these two fields.
+     */
+    readonly maxRetries: number;
+    readonly maxRetryDelayMs: number;
+}
+export interface RateLimitRuntime {
+    readonly now?: () => number;
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare function sleepWithSignal(milliseconds: number, signal?: AbortSignal): Promise<void>;
+export declare class BoundedRateLimiter {
+    private readonly config;
+    private readonly semaphore;
+    private readonly now;
+    private readonly sleep;
+    private reservationTail;
+    private nextStartAt;
+    constructor(config: RateLimitConfig, runtime?: RateLimitRuntime);
+    private reserveStart;
+    run<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}
+/**
+ * Admission gate for a source's HTTP layer (`SourceHttpOptions.schedule`).
+ *
+ * It gates the network call alone: the caller arms its request timeout inside
+ * the admitted operation, so a request held behind pacing or a concurrency
+ * ceiling cannot be reported as a timeout before it ever reaches the network.
+ */
+export declare function createRateLimitSchedule(config: RateLimitConfig, runtime?: RateLimitRuntime): <T>(operation: () => Promise<T>, signal?: AbortSignal) => Promise<T>;

package/dist/lib/rate-limit.js

@@ -0,0 +1,121 @@
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
+export function sleepWithSignal(milliseconds, signal) {
+    if (milliseconds <= 0)
+        return Promise.resolve();
+    if (signal?.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            reject(abortReason(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+class Semaphore {
+    maximum;
+    active = 0;
+    waiters = [];
+    constructor(maximum) {
+        this.maximum = maximum;
+    }
+    async acquire(signal) {
+        if (signal?.aborted)
+            throw abortReason(signal);
+        if (this.active < this.maximum) {
+            this.active += 1;
+            return;
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, ...(signal === undefined ? {} : { signal }) };
+            if (signal !== undefined) {
+                waiter.onAbort = () => {
+                    const index = this.waiters.indexOf(waiter);
+                    if (index >= 0)
+                        this.waiters.splice(index, 1);
+                    reject(abortReason(signal));
+                };
+                signal.addEventListener("abort", waiter.onAbort, { once: true });
+            }
+            this.waiters.push(waiter);
+        });
+    }
+    release() {
+        const waiter = this.waiters.shift();
+        if (waiter === undefined) {
+            this.active -= 1;
+            return;
+        }
+        if (waiter.signal !== undefined && waiter.onAbort !== undefined)
+            waiter.signal.removeEventListener("abort", waiter.onAbort);
+        waiter.resolve();
+    }
+}
+export class BoundedRateLimiter {
+    config;
+    semaphore;
+    now;
+    sleep;
+    reservationTail = Promise.resolve();
+    nextStartAt = 0;
+    constructor(config, runtime = {}) {
+        this.config = config;
+        if (!Number.isInteger(config.maxConcurrency) || config.maxConcurrency < 1)
+            throw new Error("maxConcurrency must be a positive integer");
+        if (!(config.requestsPerSecond > 0))
+            throw new Error("requestsPerSecond must be positive");
+        this.semaphore = new Semaphore(config.maxConcurrency);
+        this.now = runtime.now ?? Date.now;
+        this.sleep = runtime.sleep ?? sleepWithSignal;
+    }
+    async reserveStart(signal) {
+        let release;
+        const predecessor = this.reservationTail;
+        this.reservationTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        if (signal?.aborted) {
+            release();
+            throw abortReason(signal);
+        }
+        await predecessor;
+        try {
+            if (signal?.aborted)
+                throw abortReason(signal);
+            const startAt = Math.max(this.now(), this.nextStartAt);
+            this.nextStartAt = startAt + 1000 / this.config.requestsPerSecond;
+            return startAt;
+        }
+        finally {
+            release();
+        }
+    }
+    async run(operation, signal) {
+        const startAt = await this.reserveStart(signal);
+        await this.sleep(Math.max(0, startAt - this.now()), signal);
+        await this.semaphore.acquire(signal);
+        try {
+            return await operation();
+        }
+        finally {
+            this.semaphore.release();
+        }
+    }
+}
+/**
+ * Admission gate for a source's HTTP layer (`SourceHttpOptions.schedule`).
+ *
+ * It gates the network call alone: the caller arms its request timeout inside
+ * the admitted operation, so a request held behind pacing or a concurrency
+ * ceiling cannot be reported as a timeout before it ever reaches the network.
+ */
+export function createRateLimitSchedule(config, runtime = {}) {
+    const limiter = new BoundedRateLimiter(config, runtime);
+    return (operation, signal) => limiter.run(operation, signal);
+}

package/dist/literature/sources/arxiv.d.ts

@@ -0,0 +1,22 @@
+import { type SourceHttpOptions, type SourceHttpResult } from "./http.js";
+export interface ArxivPaper {
+    id: string;
+    title: string;
+    abstract: string;
+    authors: string[];
+    published: string;
+    categories: string[];
+    url: string;
+    pdfUrl?: string;
+}
+export interface ArxivSearchInput {
+    readonly query: string;
+    readonly categories?: readonly string[];
+    readonly limit: number;
+}
+export interface ArxivSource {
+    search(input: ArxivSearchInput, signal?: AbortSignal): Promise<SourceHttpResult<ArxivPaper[]>>;
+    lookupExact(id: string, limit: number, signal?: AbortSignal): Promise<SourceHttpResult<ArxivPaper[]>>;
+}
+export declare function parseArxivAtom(xml: string): ArxivPaper[];
+export declare function createArxivSource(options?: SourceHttpOptions): ArxivSource;

package/dist/literature/sources/arxiv.js

@@ -0,0 +1,103 @@
+import { requestText } from "./http.js";
+const BASE_URL = "https://export.arxiv.org/api/query";
+const stripCdata = (value) => value.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1");
+const decodeXmlEntities = (value) => value
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hexadecimal) => String.fromCodePoint(parseInt(hexadecimal, 16)))
+    .replace(/&#(\d+);/g, (_, decimal) => String.fromCodePoint(parseInt(decimal, 10)))
+    .replace(/&amp;/g, "&");
+const collapseWhitespace = (value) => decodeXmlEntities(stripCdata(value)).replace(/\s+/g, " ").trim();
+function extractEntries(xml) {
+    const expression = /<entry\b[^>]*>([\s\S]*?)<\/entry>/g;
+    const entries = [];
+    let match;
+    while ((match = expression.exec(xml)) !== null)
+        entries.push(match[1]);
+    return entries;
+}
+function firstMatch(entry, tag) {
+    return entry.match(new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`))?.[1];
+}
+function allMatches(entry, tag) {
+    const expression = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`, "g");
+    const values = [];
+    let match;
+    while ((match = expression.exec(entry)) !== null)
+        values.push(match[1]);
+    return values;
+}
+function linkAttribute(entry, predicate) {
+    const expression = /<link\b([^>]*)\/>/g;
+    let match;
+    while ((match = expression.exec(entry)) !== null) {
+        const attributes = match[1];
+        if (predicate(attributes))
+            return attributes.match(/href="([^"]+)"/)?.[1];
+    }
+    return undefined;
+}
+function categoryTerms(entry) {
+    const expression = /<category\b([^>]*)\/>/g;
+    const terms = [];
+    let match;
+    while ((match = expression.exec(entry)) !== null) {
+        const term = match[1].match(/term="([^"]+)"/)?.[1];
+        if (term !== undefined)
+            terms.push(term);
+    }
+    return terms;
+}
+export function parseArxivAtom(xml) {
+    return extractEntries(xml).flatMap((entry) => {
+        const rawId = firstMatch(entry, "id");
+        const title = firstMatch(entry, "title");
+        if (rawId === undefined || title === undefined)
+            return [];
+        const idMatch = rawId.match(/abs\/(.+)$/);
+        const authors = allMatches(entry, "author")
+            .map((author) => firstMatch(author, "name"))
+            .filter((name) => name !== undefined)
+            .map(collapseWhitespace);
+        const htmlUrl = linkAttribute(entry, (attributes) => /rel="alternate"/.test(attributes) && /type="text\/html"/.test(attributes));
+        const pdfUrl = linkAttribute(entry, (attributes) => /title="pdf"/.test(attributes));
+        return [
+            {
+                id: idMatch?.[1] ?? collapseWhitespace(rawId),
+                title: collapseWhitespace(title),
+                abstract: collapseWhitespace(firstMatch(entry, "summary") ?? ""),
+                authors,
+                published: collapseWhitespace(firstMatch(entry, "published") ?? ""),
+                categories: categoryTerms(entry),
+                url: htmlUrl ?? collapseWhitespace(rawId),
+                ...(pdfUrl === undefined ? {} : { pdfUrl }),
+            },
+        ];
+    });
+}
+export function createArxivSource(options = {}) {
+    async function fetchPapers(params, signal) {
+        const result = await requestText(`${BASE_URL}?${params}`, options, signal);
+        if (result.status !== "ok")
+            return result;
+        if (!/<feed\b/.test(result.value))
+            return { status: "unavailable", detail: "response schema mismatch: missing Atom feed" };
+        return { status: "ok", value: parseArxivAtom(result.value) };
+    }
+    return {
+        search: (input, signal) => {
+            const categoryQuery = input.categories !== undefined && input.categories.length > 0
+                ? ` AND (${input.categories.map((category) => `cat:${category}`).join(" OR ")})`
+                : "";
+            return fetchPapers(new URLSearchParams({
+                search_query: `all:${input.query}${categoryQuery}`,
+                max_results: String(input.limit),
+                sortBy: "relevance",
+                sortOrder: "descending",
+            }), signal);
+        },
+        lookupExact: (id, limit, signal) => fetchPapers(new URLSearchParams({ id_list: id, max_results: String(limit) }), signal),
+    };
+}