/** * Investigation orchestrator (investigate-pipeline lane, Ticket T4; * docs/plans/investigate-pipeline DESIGN.md D3, PRD AC-3/AC-4/AC-9/ * AC-10; ADR-0013). * * Thin, data-returning composition of the seams `search` and `read` * already export — no bespoke merge fork, no local fan-out copy, no * transport of its own: * * 1. planSubQueries (T2, injected loadContextText — no filesystem). * 2. resolveFanoutPlan over the resolved provider pin (AC-1 tiers, * the same inputs handleSearch passes). * 3. Grid execution through the exported seams: fan-out mode runs * executeFanoutPlan; single mode runs the exported search() with * {merge: N > 1} over the escaped-pipe join of the sub-queries * (the exact context-mode join precedent, index.ts handleSearch). * 4. Top --sources distinct sources = the first K rows of the merged * FormattedResult[] (mergeResults already collapsed near-dup * clusters to representatives — a near-dup pair IS one row). * 5. Reads: bounded-concurrency pool (default 4) over the reader * capability seam via executeReaderOperation, one client per * read (descriptor.create per read), closed in `finally`. * 6. extractPassages (T3) per read result. * 7. EvidencePack assembly per the T1 types. * * `--synthesize` (T7, PRD AC-7, DESIGN D6, ADR-0013 §2) is the explicit * Z.AI-only escape hatch and is ADDITIVE-ONLY BY CONSTRUCTION: the pack * is fully assembled (searches, reads, extraction, coverage) BEFORE the * synthesis dep is ever called, so the brief can only ever be ADDED as * the LAST key — a failed synthesis is the invocation's terminal error * and never degrades, shrinks, or reorders the pack. The command holds * no transport: construction is handler-seam wiring, exactly like every * other capability, and the dep is injected. * * Reader supplier selection mirrors handleRead: the FIRST descriptor * in registry order whose injected `readerCapabilityFor` resolves a * ReaderCapability serves every read (the same first-configured-capable * order read uses; cross-provider fallback per failed read is the * index.ts handler seam's business, T6). A supplier that rejects a * source terminally classifies as `reader-failed:`; a supplier * that cannot serve the capability at all classifies as * `no-reader-supplier`. Unread rows carry reason codes only * (redacted, house rule); the pool continues past them; * `sourcesRead` counts successes only. * * Consumption linearity: every billable arm and read attempt records * exactly one event (N×M + K) because the shared executors emit per * invoke and the orchestrator never double-reads a URL. * * `--isolated` is ACCEPTED, never rejected: the pid-segment cache * behavior is the main() handler seam's job (T6) — the command has no * cache-directory logic of its own; the injected cache IS the * (possibly isolated) production cache. Journal entry/marker WRITING * lives at the index.ts descriptor seam (journalingDescriptors / * captureServingDescriptors): this command consumes the injected * descriptor list verbatim, so capture-wrapped descriptors keep * stamping servedFrom/cacheKey cells the journal hook consumes — the * T4-level guarantee (asserted by the seam-passthrough test); journal * wiring itself is deferred to T6 (journal.ts / index.ts untouched). */ import type { CommandContext, CommandResult } from "../command-invocation.js"; import type { ReaderCapability } from "../capabilities/reader.js"; import type { FusionMode } from "../lib/config-store.js"; import { type ResponseCache } from "../lib/cache.js"; import type { RetryPolicy } from "../lib/execution.js"; import type { ConsumptionSink } from "../lib/consumption.js"; import type { ProviderDescriptor, ProviderId } from "../providers/types.js"; import { type LadderRule } from "../lib/output-budget.js"; /** * `--synthesize` escape hatch (T7). The deterministic brief prompt: the * bare question, the planned sub-query grid, and the extracted passage * quotes (bounded). No clock, no randomness — identical fixtures produce * a byte-identical prompt. */ export interface SynthesisPrompt { readonly question: string; readonly subQueries: readonly string[]; /** Extracted passage quotes, in pack order, capped at * {@link SYNTHESIS_QUOTE_CAP}. */ readonly quotes: readonly string[]; } /** * Passage-quote cap for the brief prompt. Bounded so the prompt cannot * grow with the read pool: 20 quotes ≈ the first few sources' passages, * well inside the Z.AI chat context even at the passage cap (5 per * source). Deterministic (first N in pack order), never sampled. */ export declare const SYNTHESIS_QUOTE_CAP = 20; /** * The synthesis dep shape. `synthesize?` is threaded from the handler * seam (index.ts), which owns the transport — the command never * constructs one. Production passes a Z.AI chat-completions caller; * tests pass a fixture. */ export type SynthesizeBrief = (prompt: SynthesisPrompt) => Promise; /** * `investigate --help` (T6/T7). The command's rejected-flag contract is * part of the surface: --depth/--arms/--budget-tokens DO NOT EXIST (PRD * AC-1 — the rejection is the feature), and --context-stdin is * deliberately not investigate's (search-only spelling; pipes and * --context cover the sub-query sources). */ export declare const INVESTIGATE_HELP: string; export interface InvestigateOptions { /** * Raw `--provider` value (comma-list / "all" / single id), threaded * to resolveFanoutPlan verbatim — the same tier grammar search uses. */ readonly provider?: string; /** `--context` file path; selects the planner's context tier. */ readonly contextFile?: string; /** * `--sources`: how many distinct post-cluster sources to read. * Positive integer; default 5. 0/negative/non-integers are * VALIDATION_ERROR (validation at the trust boundary). */ readonly sources?: number; /** * ACCEPTED, never rejected (PRD AC-9: no ISOLATED_REJECTED path). * The pid-segment cache behavior belongs to the main() handler seam * (T6) — this command has no cache-directory logic of its own; the * injected cache IS the (possibly isolated) production cache. */ readonly isolated?: boolean; /** `--no-cache`: threaded to every underlying search + read. */ readonly noCache?: boolean; /** * `--no-journal`: threaded through ONLY as far as the command seam * allows (the underlying ops take no such option — journaling is * wired at the index.ts descriptor/hook seam). T6 owns the real * suppression; recorded here so the option never fails the parse. */ readonly noJournal?: boolean; /** * `--max-chars` (T5, D7): whole-envelope Output Budget over the * EvidencePack via INVESTIGATE_LADDER. Strict positive integer * (parseBriefMaxChars class); 0/negative/fractional values are * VALIDATION_ERROR at the trust boundary. */ readonly maxChars?: number; /** * `--synthesize` (T7, PRD AC-7): attach an additive `brief` to the * pack via the injected {@link InvestigateExecutionDependencies. * synthesize} dep. Z.AI-only (the notice lives at the handler seam, * where the raw provider pin is visible). Set without a dep is a * wiring bug — the command throws rather than silently skipping. */ readonly synthesize?: boolean; /** * investigate-verify lane (DESIGN D3, PRD AC-1): claim-corroboration * mode. The positional becomes the statement; `splitClaims` owns the * grid (one verbatim sub-query per sentence-claim, ≤ 8 — the R1 * fail-loud cap); the planner module is NOT invoked. `--context` + * `--verify` is pair-rejected at the index.ts parse seam; `|` is * literal text (claims split on sentences, never pipes). */ readonly verify?: boolean; } /** * INVESTIGATE_LADDER (D7 budget order; verify lane D6 extension): * passages trim FIRST (quote truncate, charRange adjusts — the * round-trip pin survives), then LATE sources drop whole, then — * verify packs only — evidence pointers drop per claim (whole). * question/subQueries/coverage and verify claim text/verdicts/cue * counts are never cut — expressed by omission (no rule touches * them). */ export declare const INVESTIGATE_LADDER: readonly [LadderRule, LadderRule, LadderRule]; export interface InvestigateExecutionDependencies { /** * Live provider registry — the same `HandlerDependencies. * providerDescriptors` list handleSearch consumes (possibly the * capture-wrapped journalingDescriptors list; this command never * unwraps it, so journal servedFrom/cacheKey stamping survives). */ readonly descriptors: readonly ProviderDescriptor[]; /** The resolved env (env + file-configured keys). Input only. */ readonly env: NodeJS.ProcessEnv; /** Whether `fanout` is enabled in the active config. */ readonly configFanout: boolean; /** Resolved per-capability routing table. */ readonly routing?: Readonly>; /** Shared response cache for search arms AND reads. */ readonly cache: ResponseCache; readonly sleep: (ms: number) => Promise; readonly random: () => number; readonly retryPolicy?: RetryPolicy; /** Usage-ledger sink — N×M + K linearity pins on it. */ readonly consume?: ConsumptionSink; /** Clock for consumption events. */ readonly now?: () => number; /** * Fusion ranking mode — resolved ONCE at the handler seam (env > * config > "rrf"), exactly how handleSearch threads it. Omitted * (direct tests) → "rrf". */ readonly fusionMode?: FusionMode; /** * Wall clock for `fetchedAt` (ISO-8601 UTC-Z, D5). Injected for * byte-identical determinism pins; defaults to `() => new Date()`. */ nowWall?: () => Date; /** * Read-pool concurrency bound (default 4). Overridable in deps so * tests can pin the pool shape without timers. */ readConcurrency?: number; /** Injected context reader (production: readContextSource-shaped). */ loadContextText(filePath: string): Promise; /** * Reader supplier seam: resolve the ReaderCapability a provider * descriptor serves, or `undefined` when it has none. Production * mirrors handleRead's shape — `descriptor.create({ env }).reader` — * so selection follows the same first-configured-capable order read * uses (the registry order the descriptor list already carries). */ readerCapabilityFor(descriptor: ProviderDescriptor): ReaderCapability | undefined; /** * T5: resolved secrets for the compaction artifact's redaction (the * save seam's contract — the caller redacts before persisting). * Omitted (direct tests, no secrets) → no-op redaction. */ readonly secrets?: string[]; /** * T7: the synthesis transport (handler-seam wiring — this command * never constructs one). Consulted ONLY when `--synthesize` is set, * and only AFTER the pack is fully assembled. */ synthesize?: SynthesizeBrief; } export declare function investigate(question: string, options: InvestigateOptions | undefined, deps: InvestigateExecutionDependencies, context?: CommandContext): Promise; //# sourceMappingURL=investigate.d.ts.map