@autorag/librarian 2.0.0

package/dist/mirror/index-store.d.ts

@@ -0,0 +1,16 @@
+export interface ParsedMirrorEntry {
+    readonly virtualPath: string;
+    readonly sourcePath: string;
+    readonly outputPath: string;
+    readonly parserName: string;
+    readonly sourceMtimeNs: number;
+    readonly sourceSizeBytes: number;
+    readonly updatedAt: string;
+}
+export interface ParsedMirrorIndex {
+    readonly version: 1;
+    readonly entries: Readonly<Record<string, ParsedMirrorEntry>>;
+}
+export declare function emptyMirrorIndex(): ParsedMirrorIndex;
+export declare function loadMirrorIndex(root: string): ParsedMirrorIndex;
+export declare function saveMirrorIndex(root: string, index: ParsedMirrorIndex): void;

package/dist/mirror/index.d.ts

@@ -0,0 +1,5 @@
+export type { ParsedMirrorEntry, ParsedMirrorIndex } from "./index-store.js";
+export { emptyMirrorIndex, loadMirrorIndex, saveMirrorIndex } from "./index-store.js";
+export { parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath } from "./paths.js";
+export type { ParsedMirrorDiagnostic, ParsedMirrorDiagnosticCode, ParsedMirrorSyncOptions, ParsedMirrorSyncResult, } from "./sync.js";
+export { DEFAULT_MAX_SOURCE_BYTES, detectMirrorStaleness, syncParsedMirrors } from "./sync.js";

package/dist/mirror/paths.d.ts

@@ -0,0 +1,6 @@
+export declare const PARSED_MIRROR_SUBDIR: string;
+export declare const PARSED_FILES_SUBDIR = "files";
+export declare const PARSED_INDEX_FILE = "index.json";
+export declare function parsedMirrorRoot(root: string): string;
+export declare function parsedMirrorIndexPath(root: string): string;
+export declare function parsedOutputPath(root: string, virtualPath: string): string;

package/dist/mirror/sync.d.ts

@@ -0,0 +1,38 @@
+import { type DefaultParserRegistryOptions } from "../parser/defaults.js";
+import type { ParserRegistry } from "../parser/registry.js";
+/** Refuse to fully load/parse sources larger than this. Keeps Node heap stable on home folders. */
+export declare const DEFAULT_MAX_SOURCE_BYTES: number;
+export interface ParsedMirrorSyncOptions {
+    readonly root: string;
+    readonly searchPaths: readonly string[];
+    readonly registry?: ParserRegistry;
+    readonly parserOptions?: DefaultParserRegistryOptions;
+    readonly force?: boolean;
+    /** Override max source size for parse attempts (bytes). */
+    readonly maxSourceBytes?: number;
+}
+export type ParsedMirrorDiagnosticCode = "unsupported-file" | "parser-skipped" | "parser-failed" | "deleted-mirror" | "stale-index";
+/** Path-opaque refresh diagnostic. `source` is an opaque virtual path, never a real fs path. */
+export interface ParsedMirrorDiagnostic {
+    readonly code: ParsedMirrorDiagnosticCode;
+    readonly severity: "info" | "warning";
+    readonly message: string;
+    readonly source: string;
+}
+export interface ParsedMirrorSyncResult {
+    readonly scanned: number;
+    readonly written: number;
+    readonly deleted: number;
+    readonly skipped: number;
+    readonly indexPath: string;
+    readonly diagnostics: readonly ParsedMirrorDiagnostic[];
+}
+export declare function syncParsedMirrors(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorSyncResult>;
+/**
+ * Cheap, parse-free staleness check: compares current source files (by mtime and
+ * size only — no parsing) against the recorded mirror index. Returns a
+ * `stale-index` diagnostic (opaque virtual path) for every supported source that
+ * is new or changed since the last successful refresh. Safe to call outside the
+ * query hot path (e.g. from getRefreshStatus).
+ */
+export declare function detectMirrorStaleness(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorDiagnostic[]>;

package/dist/observability/run-log.d.ts

@@ -0,0 +1,53 @@
+export type AutoRAGRunEvent = {
+    event: "search_started";
+    timestamp: string;
+    sessionId: string;
+    queryLength: number;
+    orchestratorModel: string;
+    explorerModel: string;
+} | {
+    event: "search_completed";
+    timestamp: string;
+    sessionId: string;
+    resultCount: number;
+} | {
+    event: "search_failed";
+    timestamp: string;
+    sessionId: string;
+    errorType: string;
+} | {
+    event: "cleanup_failed";
+    timestamp: string;
+    sessionId: string;
+    failureCount: number;
+    errorTypes: string[];
+} | {
+    event: "dispatch_rejected";
+    schemaVersion: 1;
+    sessionId: string;
+    toolCallId: string | null;
+    sequence: number;
+    timestamp: string;
+    dispatchKind: "launch" | "admin" | "control" | "mutation" | "schedule" | "hybrid" | "unknown";
+    code: string;
+    field: string;
+    forceCorrectable: boolean;
+} | {
+    event: "dispatch_autofilled";
+    schemaVersion: 1;
+    sessionId: string;
+    toolCallId: string | null;
+    sequence: number;
+    timestamp: string;
+    dispatchKind: "launch";
+    fields: {
+        artifacts: boolean;
+        agentScope: boolean;
+        leafModelFillCount: number;
+    };
+};
+export declare class AutoRAGRunLogger {
+    private readonly path;
+    constructor(path: string);
+    write(event: AutoRAGRunEvent): void;
+}

package/dist/parser/defaults.d.ts

@@ -0,0 +1,6 @@
+import { type OcrParserOptions } from "./ocr.js";
+import { ParserRegistry } from "./registry.js";
+export interface DefaultParserRegistryOptions {
+    readonly ocr?: OcrParserOptions;
+}
+export declare function createDefaultParserRegistry(options?: DefaultParserRegistryOptions): ParserRegistry;

package/dist/parser/eml.d.ts

@@ -0,0 +1,6 @@
+import { type ParseInput, type ParseOutput, Parser } from "./types.js";
+export declare class EmlParser extends Parser {
+    readonly name = "eml";
+    readonly extensions: readonly [".eml"];
+    parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class ParseError extends Error {
+    readonly parserName: string;
+    readonly virtualPath: string;
+    constructor(parserName: string, virtualPath: string, cause: unknown);
+}

package/dist/parser/hwp.d.ts

@@ -0,0 +1,6 @@
+import { type ParseInput, type ParseOutput, Parser } from "./types.js";
+export declare class HwpParser extends Parser {
+    readonly name = "hwp";
+    readonly extensions: readonly [".hwpx", ".hwp"];
+    parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/index.d.ts

@@ -0,0 +1,10 @@
+export { createDefaultParserRegistry, type DefaultParserRegistryOptions } from "./defaults.js";
+export { EmlParser } from "./eml.js";
+export { ParseError } from "./errors.js";
+export { HwpParser } from "./hwp.js";
+export { ImageOcrParser, type OcrEngine, type OcrEngineInput, type OcrParserOptions } from "./ocr.js";
+export { DocxParser, PptxParser, XlsxParser } from "./office.js";
+export { OpendataloaderPdfParser, type PdfConverter } from "./opendataloader-pdf.js";
+export { PlainTextParser } from "./plain-text.js";
+export { ParserRegistry } from "./registry.js";
+export { type ParseInput, type ParseOutput, Parser } from "./types.js";

package/dist/parser/ocr.d.ts

@@ -0,0 +1,25 @@
+import { type ParseInput, type ParseOutput, Parser } from "./types.js";
+export interface OcrEngineInput {
+    readonly bytes: Uint8Array;
+    readonly languages: readonly string[];
+    readonly timeoutMs: number;
+    readonly signal: AbortSignal;
+}
+export type OcrEngine = (input: OcrEngineInput) => Promise<string>;
+export interface OcrParserOptions {
+    readonly enabled: boolean;
+    readonly languages?: readonly string[];
+    readonly timeoutMs?: number;
+    readonly maxBytes?: number;
+    readonly engine?: OcrEngine;
+}
+export declare class ImageOcrParser extends Parser {
+    readonly name = "image-ocr";
+    readonly extensions: readonly [".jpg", ".jpeg", ".png", ".bmp", ".tiff"];
+    private readonly languages;
+    private readonly timeoutMs;
+    private readonly maxBytes;
+    private readonly engine;
+    constructor(options: OcrParserOptions);
+    parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/office.d.ts

@@ -0,0 +1,16 @@
+import { type ParseInput, type ParseOutput, Parser } from "./types.js";
+export declare class DocxParser extends Parser {
+    readonly name = "docx";
+    readonly extensions: readonly [".docx"];
+    parse(input: ParseInput): Promise<ParseOutput>;
+}
+export declare class PptxParser extends Parser {
+    readonly name = "pptx";
+    readonly extensions: readonly [".pptx"];
+    parse(input: ParseInput): Promise<ParseOutput>;
+}
+export declare class XlsxParser extends Parser {
+    readonly name = "xlsx";
+    readonly extensions: readonly [".xlsx", ".xls"];
+    parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/opendataloader-pdf.d.ts

@@ -0,0 +1,21 @@
+import type { ConvertOptions } from "@opendataloader/pdf";
+import { type ParseInput, type ParseOutput, Parser } from "./types.js";
+export type PdfConverter = (inputPath: string, options: ConvertOptions) => Promise<string>;
+export interface OpendataloaderPdfParserOptions {
+    readonly converter?: PdfConverter;
+    readonly ocr?: {
+        readonly enabled: boolean;
+        readonly timeoutMs?: number;
+        readonly hybrid?: string;
+        readonly hybridMode?: string;
+        readonly maxBytes?: number;
+    };
+}
+export declare class OpendataloaderPdfParser extends Parser {
+    readonly name = "opendataloader-pdf";
+    readonly extensions: readonly [".pdf"];
+    private readonly options;
+    private readonly converter;
+    constructor(options?: OpendataloaderPdfParserOptions);
+    parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/plain-text.d.ts

@@ -0,0 +1,6 @@
+import { type ParseInput, type ParseOutput, Parser } from "./types.js";
+export declare class PlainTextParser extends Parser {
+    readonly name = "plain-text";
+    readonly extensions: readonly [".txt", ".text", ".md", ".markdown"];
+    parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/registry.d.ts

@@ -0,0 +1,8 @@
+import type { Parser } from "./types.js";
+export declare class ParserRegistry {
+    private readonly parsersByExtension;
+    constructor(parsers?: readonly Parser[]);
+    register(parser: Parser): void;
+    getForVirtualPath(virtualPath: string): Parser | undefined;
+    list(): Parser[];
+}

package/dist/parser/text.d.ts

@@ -0,0 +1,2 @@
+export declare function decodeText(bytes: Uint8Array): string;
+export declare function normalizeMarkdown(markdown: string): string;

package/dist/parser/types.d.ts

@@ -0,0 +1,14 @@
+export interface ParseInput {
+    readonly virtualPath: string;
+    readonly sourcePath?: string;
+    readonly bytes: Uint8Array;
+}
+export interface ParseOutput {
+    readonly markdown: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export declare abstract class Parser {
+    abstract readonly name: string;
+    abstract readonly extensions: readonly string[];
+    abstract parse(input: ParseInput): Promise<ParseOutput>;
+}

package/dist/parser/xml-text.d.ts

@@ -0,0 +1,2 @@
+export declare function readZipXmlText(bytes: Uint8Array, pathPattern: RegExp): Promise<string[]>;
+export declare function extractTextFromXml(xml: string): string[];

package/dist/retrieval/evidence-id.d.ts

@@ -0,0 +1,16 @@
+export interface EvidenceIdInput {
+    readonly method: string;
+    readonly source: string;
+    readonly retrievalResultId?: string;
+    readonly chunkIndex?: number;
+    readonly lineNumber?: number;
+    readonly excerpt?: string;
+    readonly content?: string;
+}
+export interface NormalizedEvidenceRef extends EvidenceIdInput {
+    readonly stableEvidenceId: string;
+}
+export declare function normalizeEvidenceText(text: string): string;
+export declare function isPathOpaqueIdentifier(value: string): boolean;
+export declare function stableEvidenceId(input: EvidenceIdInput): string;
+export declare function normalizeEvidenceRef(input: EvidenceIdInput): NormalizedEvidenceRef;

package/dist/retrieval/index.d.ts

@@ -0,0 +1,7 @@
+export type { MergeOptions } from "./merger.js";
+export { ParallelRetriever, ResultMerger } from "./merger.js";
+export type { BM25Engine, BM25FallbackMode, BM25MethodOptions, BM25ReadinessState, BM25Status, BM25SyncResult, } from "./methods/bm25.js";
+export { BM25Method, BM25UnavailableError } from "./methods/bm25.js";
+export { RetrievalMethodRegistry } from "./registry.js";
+export { matchesVirtualPathScope, normalizeVirtualPath, normalizeVirtualPathScope, virtualPathScopeToRegExp, } from "./scope.js";
+export type { CuratedResult, NumberedResult, RetrievalDiagnostic, RetrievalDiagnosticCode, RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult, RetrievalWithDiagnostics, } from "./types.js";

package/dist/retrieval/merger.d.ts

@@ -0,0 +1,18 @@
+import type { RetrievalMethod, RetrievalOptions, RetrievalResult, RetrievalWithDiagnostics } from "./types.js";
+export interface MergeOptions {
+    topK: number;
+    dedup: boolean;
+}
+export declare class ResultMerger {
+    merge(results: Map<string, RetrievalResult[]>, options: MergeOptions): RetrievalResult[];
+}
+export declare class ParallelRetriever {
+    retrieve(methods: RetrievalMethod[], query: string, options: RetrievalOptions): Promise<Map<string, RetrievalResult[]>>;
+    /**
+     * Like {@link retrieve} but also returns path-opaque diagnostics for methods
+     * that failed. Partial results from healthy methods are preserved; failed
+     * methods yield an empty result set plus a diagnostic. The legacy
+     * {@link retrieve} return shape is intentionally unchanged for compatibility.
+     */
+    retrieveWithDiagnostics(methods: RetrievalMethod[], query: string, options: RetrievalOptions): Promise<RetrievalWithDiagnostics>;
+}

package/dist/retrieval/methods/bm25.d.ts

@@ -0,0 +1,52 @@
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../types.js";
+export type BM25ReadinessState = "disabled" | "dependency_unavailable" | "index_missing" | "indexing" | "ready" | "degraded_fallback" | "error";
+export type BM25Engine = "tantivy" | "typescript-fallback" | "none";
+export type BM25FallbackMode = "typescript" | "disabled";
+export interface BM25MethodOptions {
+    readonly root: string;
+    readonly indexPath?: string;
+    readonly enabled?: boolean;
+    readonly fallback?: BM25FallbackMode;
+    readonly forceEngine?: Exclude<BM25Engine, "none">;
+    readonly importBinding?: () => Promise<TantivyBinding>;
+}
+export interface BM25SyncResult {
+    readonly indexPath: string;
+    readonly indexedChunks: number;
+    readonly readiness: BM25ReadinessState;
+    readonly engine: BM25Engine;
+}
+export interface BM25Status {
+    readonly readiness: BM25ReadinessState;
+    readonly engine: BM25Engine;
+    readonly message?: string;
+}
+type TantivyBinding = typeof import("@pngwasi/node-tantivy-binding");
+export declare const BM25_SUBDIR: string;
+export declare class BM25UnavailableError extends Error {
+    readonly readiness: BM25ReadinessState;
+    constructor(readiness: BM25ReadinessState, message: string);
+}
+export declare class BM25Method implements RetrievalMethod {
+    private readonly root;
+    private readonly indexPath;
+    private readonly fallback;
+    private readonly forceEngine;
+    private readonly importBinding;
+    private status;
+    constructor(options: BM25MethodOptions);
+    describe(): RetrievalMethodDescriptor;
+    getStatus(): BM25Status;
+    sync(): Promise<BM25SyncResult>;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    private writeTantivyIndex;
+    private retrieveTantivy;
+    private writeFallbackIndex;
+    private retrieveFallback;
+    private readFallbackIndex;
+    private hasFallbackIndex;
+    private tantivyIndexPath;
+    private fallbackIndexPath;
+    private syncResult;
+}
+export {};

package/dist/retrieval/registry.d.ts

@@ -0,0 +1,8 @@
+import type { RetrievalMethod } from "./types.js";
+export declare class RetrievalMethodRegistry {
+    private readonly methods;
+    register(method: RetrievalMethod): void;
+    get(name: string): RetrievalMethod | undefined;
+    list(): RetrievalMethod[];
+    getByType(type: "posix" | "vector" | "bm25" | "hybrid" | "visual"): RetrievalMethod[];
+}

package/dist/retrieval/scope.d.ts

@@ -0,0 +1,4 @@
+export declare function normalizeVirtualPath(value: string): string;
+export declare function normalizeVirtualPathScope(scope: string | undefined): string | undefined;
+export declare function matchesVirtualPathScope(virtualPath: string, scope: string | undefined): boolean;
+export declare function virtualPathScopeToRegExp(scope: string): RegExp;

package/dist/retrieval/types.d.ts

@@ -0,0 +1,64 @@
+export interface RetrievalResult {
+    id: string;
+    content: string;
+    source: string;
+    score: number;
+    metadata: Record<string, unknown>;
+}
+export interface RetrievalMethodDescriptor {
+    name: string;
+    type: "posix" | "vector" | "bm25" | "hybrid" | "visual";
+    description: string;
+    status: "active" | "stub";
+    capabilities: string[];
+    datasourceId?: string;
+    tags?: readonly string[];
+}
+export interface RetrievalOptions {
+    topK?: number;
+    scope?: string;
+    filters?: Record<string, unknown>;
+    allowedTags?: readonly string[];
+    allowedScopes?: readonly string[];
+    signal?: AbortSignal;
+}
+export interface RetrievalMethod {
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+}
+export type RetrievalDiagnosticCode = "retrieval-method-failed" | "minsync-unavailable" | "bm25-unavailable" | "bm25-degraded-fallback";
+/** Path-opaque diagnostic emitted by the multi-method retrieval pipeline. */
+export interface RetrievalDiagnostic {
+    code: RetrievalDiagnosticCode;
+    severity: "info" | "warning" | "error";
+    message: string;
+    /** Component/method label — never a real filesystem path. */
+    source?: string;
+}
+export interface RetrievalWithDiagnostics {
+    results: Map<string, RetrievalResult[]>;
+    diagnostics: RetrievalDiagnostic[];
+}
+export interface NumberedResult {
+    index: number;
+    source: string;
+    content: string;
+    method: string;
+}
+export interface EvidenceReference {
+    method: string;
+    source: string;
+    excerpt?: string;
+    content?: string;
+    retrievalResultId?: string;
+    chunkIndex?: number;
+    lineNumber?: number;
+    stableEvidenceId: string;
+}
+export interface CuratedResult {
+    index: number;
+    content: string;
+    source: string;
+    method: string;
+    evidenceRefs?: readonly EvidenceReference[];
+}

package/dist/subagents/contracts.d.ts

@@ -0,0 +1,90 @@
+export declare const RETRIEVAL_METHODS: readonly ["posix", "bash", "posix/bash", "bm25", "minsync", "vector", "minsync/vector", "datasource"];
+export type RetrievalMethod = (typeof RETRIEVAL_METHODS)[number];
+export type SourceTemporalStatus = "asOf" | "updatedAt" | "createdAt" | "unknown";
+export type SourceTemporal = {
+    readonly status: "asOf";
+    readonly asOf: string;
+} | {
+    readonly status: "updatedAt";
+    readonly updatedAt: string;
+} | {
+    readonly status: "createdAt";
+    readonly createdAt: string;
+} | {
+    readonly status: "unknown";
+};
+export interface ExplorerAssignment {
+    readonly originalQuery: string;
+    readonly method: RetrievalMethod;
+    readonly queryVariant: string;
+    /** Optional set of variants retained when an orchestrator fans out work. */
+    readonly queryVariants?: readonly string[];
+}
+export interface EvidenceCandidate {
+    readonly source: string;
+    readonly method: RetrievalMethod;
+    readonly evidence: string;
+    readonly retrievedAt: string;
+    readonly sourceTemporal: SourceTemporal;
+    readonly locator?: string;
+}
+export interface ExplorerReport {
+    readonly assignment: ExplorerAssignment;
+    readonly evidenceCandidates: readonly EvidenceCandidate[];
+    /** Alias for consumers that use the shorter candidate field name. */
+    readonly candidates?: readonly EvidenceCandidate[];
+    readonly summary?: string;
+}
+export interface FollowUpRequest {
+    readonly reason: string;
+    readonly assignments: readonly ExplorerAssignment[];
+}
+export type JudgeDecision = {
+    readonly decision: "sufficient";
+    readonly rationale: string;
+    readonly followUp?: undefined;
+} | {
+    readonly decision: "follow_up";
+    readonly rationale: string;
+    readonly followUp: FollowUpRequest;
+};
+export interface ExhaustionErrorDetails {
+    readonly code: "EXPLORER_EXHAUSTED";
+    readonly originalQuery: string;
+    readonly iterations: number;
+    readonly maxIterations: number;
+    readonly reason: string;
+}
+export type ContractErrorCode = "INVALID_OBJECT" | "MISSING_ORIGINAL_QUERY" | "INVALID_ORIGINAL_QUERY" | "MISSING_RETRIEVAL_METHOD" | "INVALID_RETRIEVAL_METHOD" | "MISSING_QUERY_VARIANT" | "INVALID_QUERY_VARIANT" | "INVALID_QUERY_VARIANTS" | "QUERY_VARIANT_NOT_INCLUDED" | "MISSING_SOURCE" | "INVALID_SOURCE" | "MISSING_EVIDENCE_METHOD" | "INVALID_EVIDENCE_METHOD" | "MISSING_EVIDENCE" | "INVALID_EVIDENCE" | "MISSING_RETRIEVED_AT" | "INVALID_RETRIEVED_AT" | "MISSING_SOURCE_TEMPORAL" | "INVALID_SOURCE_TEMPORAL" | "MISSING_SOURCE_TEMPORAL_DATE" | "INVALID_SOURCE_TEMPORAL_DATE" | "MISSING_ASSIGNMENT" | "MISSING_EVIDENCE_CANDIDATES" | "INVALID_EVIDENCE_CANDIDATES" | "INVALID_SUMMARY" | "MISSING_FOLLOW_UP_REASON" | "INVALID_FOLLOW_UP_REASON" | "MISSING_FOLLOW_UP_ASSIGNMENTS" | "EMPTY_FOLLOW_UP_ASSIGNMENTS" | "INVALID_FOLLOW_UP_ASSIGNMENTS" | "MISSING_JUDGE_DECISION" | "INVALID_JUDGE_DECISION" | "MISSING_JUDGE_RATIONALE" | "INVALID_JUDGE_RATIONALE" | "MISSING_FOLLOW_UP" | "INVALID_FOLLOW_UP" | "INVALID_EXHAUSTION_ERROR" | "INVALID_EXHAUSTION_CODE" | "MISSING_EXHAUSTION_QUERY" | "INVALID_EXHAUSTION_QUERY" | "INVALID_EXHAUSTION_ITERATIONS" | "INVALID_EXHAUSTION_LIMIT" | "MISSING_EXHAUSTION_REASON" | "INVALID_EXHAUSTION_REASON";
+export declare class ContractValidationError extends Error {
+    readonly code: ContractErrorCode;
+    readonly path?: string;
+    constructor(code: ContractErrorCode, message: string, path?: string);
+}
+export declare class ExplorerExhaustionError extends Error {
+    readonly code: "EXPLORER_EXHAUSTED";
+    readonly originalQuery: string;
+    readonly iterations: number;
+    readonly maxIterations: number;
+    readonly reason: string;
+    constructor(details: Omit<ExhaustionErrorDetails, "code">);
+    toJSON(): ExhaustionErrorDetails;
+}
+export declare function parseExplorerAssignment(value: unknown): ExplorerAssignment;
+export declare function parseEvidenceCandidate(value: unknown): EvidenceCandidate;
+export declare function parseExplorerReport(value: unknown): ExplorerReport;
+export declare function parseFollowUpRequest(value: unknown): FollowUpRequest;
+export declare function parseJudgeDecision(value: unknown): JudgeDecision;
+export declare function parseExhaustionError(value: unknown): ExhaustionErrorDetails;
+export declare function isExplorerAssignment(value: unknown): value is ExplorerAssignment;
+export declare function isEvidenceCandidate(value: unknown): value is EvidenceCandidate;
+export declare function isExplorerReport(value: unknown): value is ExplorerReport;
+export declare function isFollowUpRequest(value: unknown): value is FollowUpRequest;
+export declare function isJudgeDecision(value: unknown): value is JudgeDecision;
+export declare function isExhaustionError(value: unknown): value is ExhaustionErrorDetails;
+export declare function safeParseExplorerAssignment(value: unknown): ExplorerAssignment | undefined;
+export declare function safeParseEvidenceCandidate(value: unknown): EvidenceCandidate | undefined;
+export declare function safeParseExplorerReport(value: unknown): ExplorerReport | undefined;
+export declare function safeParseFollowUpRequest(value: unknown): FollowUpRequest | undefined;
+export declare function safeParseJudgeDecision(value: unknown): JudgeDecision | undefined;
+export declare function safeParseExhaustionError(value: unknown): ExhaustionErrorDetails | undefined;

package/dist/subagents/dispatch-templates.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared dispatch template builders, skeleton literals, and anti-examples for
+ * AutoRAG explorer subagent dispatch.
+ *
+ * This module is the single source of truth for:
+ * - Assignment V1 sentinel/role-line constants and block builder
+ * - Single-root and multi-root success dispatch payload builders
+ * - Compact skeleton literals consumed by `formatBlockReason`
+ * - Anti-examples for rejected dispatch patterns
+ * - Stable coded patch-error reference (single source of truth for the error catalog)
+ *
+ * `buildSearchPrompt` and prompt tests reuse these builders so no divergent
+ * template text exists inside TypeScript.
+ */
+export declare const AUTORAG_ASSIGNMENT_V1_START = "<<<AUTORAG_ASSIGNMENT_V1>>>";
+export declare const AUTORAG_ASSIGNMENT_V1_END = "<<<END_AUTORAG_ASSIGNMENT_V1>>>";
+export declare const AUTORAG_ROLE_LINE_RETRIEVED_AT = "Required handoff: include retrievedAt.";
+export declare const AUTORAG_ROLE_LINE_TEMPORAL_METADATA = "Required handoff: include temporal metadata.";
+export declare const AUTORAG_CANONICAL_ROLE_LINES = "Required handoff: include retrievedAt.\nRequired handoff: include temporal metadata.";
+export declare const PLACEHOLDER_CONFIGURED_MODEL = "<configured-model>";
+export declare const PLACEHOLDER_ALLOWED_ROOT = "<allowed-root>";
+export declare const PLACEHOLDER_ASSIGNMENT_V1_BLOCK = "<Assignment V1 block>";
+export declare const PLACEHOLDER_CALLER_QUERY = "<caller query verbatim>";
+export declare const DISPATCH_ADMIN_SKELETON = "{\"action\":\"list\"}";
+export declare const DISPATCH_SINGLE_SKELETON = "{\"agentScope\":\"user\",\"artifacts\":false,\"agent\":\"autorag-explorer\",\"model\":\"<configured-model>\",\"cwd\":\"<allowed-root>\",\"task\":\"<Assignment V1 block>\"}";
+export declare const DISPATCH_FANOUT_SKELETON = "{\"agentScope\":\"user\",\"artifacts\":false,\"tasks\":[{\"agent\":\"autorag-explorer\",\"model\":\"<configured-model>\",\"cwd\":\"<allowed-root>\",\"task\":\"<Assignment V1 block>\"}]}";
+export interface AssignmentV1Options {
+    readonly originalQuery: string;
+    readonly method: string;
+    readonly queryVariants: readonly string[];
+}
+/**
+ * Build a canonical Assignment V1 block string for use as the `task` field
+ * value in a subagent dispatch payload.
+ *
+ * Output shape (LF-joined):
+ * ```
+ * <<<AUTORAG_ASSIGNMENT_V1>>>
+ * {"originalQuery":"...","method":"...","queryVariants":["..."]}
+ * <<<END_AUTORAG_ASSIGNMENT_V1>>>
+ * Required handoff: include retrievedAt.
+ * Required handoff: include temporal metadata.
+ * ```
+ */
+export declare function buildAssignmentV1Block(opts: AssignmentV1Options): string;
+export interface SingleRootDispatchOptions {
+    readonly explorerModel: string;
+    readonly allowedRoot: string;
+    readonly task: string;
+}
+/**
+ * Build a single-root success dispatch payload as pretty-printed JSON.
+ *
+ * `agentScope` and `artifacts` are set exactly once at the top level.
+ * The single leaf carries `agent`, `model`, `cwd`, and `task`.
+ * Pass `PLACEHOLDER_*` constants for prompt examples or real values for
+ * actual dispatch payloads.
+ */
+export declare function buildSingleRootDispatchPayload(opts: SingleRootDispatchOptions): string;
+export interface MultiRootDispatchTask {
+    readonly explorerModel: string;
+    readonly allowedRoot: string;
+    readonly task: string;
+}
+/**
+ * Build a multi-root success dispatch payload as pretty-printed JSON.
+ *
+ * `agentScope` and `artifacts` are set exactly once at the top level.
+ * Each task in `tasks` carries `agent`, `model`, `cwd`, and `task` and
+ * omits `agentScope`/`artifacts`. Pass one task per configured root.
+ */
+export declare function buildMultiRootDispatchPayload(tasks: readonly MultiRootDispatchTask[]): string;
+export interface DispatchAntiExample {
+    readonly label: string;
+    readonly body: string;
+    readonly reason: string;
+}
+/**
+ * Brief anti-examples showing dispatch patterns that are rejected.
+ * Each body is pretty-printed JSON using non-sensitive placeholders only.
+ */
+export declare const DISPATCH_ANTIEXAMPLES: readonly DispatchAntiExample[];
+export interface DispatchErrorInfo {
+    readonly code: string;
+    readonly exactFix: string;
+    readonly forceCorrectable: boolean;
+}
+/**
+ * Reference table of stable dispatch rejection codes, their exactFix strings,
+ * and forceCorrectable flags. This is the single source of truth for the error
+ * catalog — `dispatch-validation.ts` derives its `EXACT_FIX_MAP` and
+ * `FORCE_CORRECTABLE_MAP` from this table so no dual catalog exists.
+ *
+ * `DISPATCH_ROLE_METADATA_INVALID` is intentionally absent: valid tasks are
+ * normalized by `ensureRoleLines` and no rejection path emits that code.
+ */
+export declare const DISPATCH_ERROR_REFERENCE: readonly DispatchErrorInfo[];
+/**
+ * Build the `### Canonical dispatch templates` subsection text for the system
+ * prompt. Uses the builders and constants above so no divergent template text
+ * exists. The `explorerModelId` parameter fills the model field in the example
+ * payloads.
+ */
+export declare function buildDispatchTemplatesPromptSection(explorerModelId: string): string;