codecartographer-pi 0.24.1 → 0.26.0

package/dist/core/broadside.d.ts

@@ -1,890 +1,14 @@
-export declare const BROADSIDE_MODEL = "google/gemini-3.7-flash:batch";
-export declare const BROADSIDE_BATCH_URL = "https://openrouter.ai/api/beta/batches";
-export declare const BROADSIDE_DIR = "broadside";
-/** Name Broad-Side answers to on the skill surfaces. Not a post-pipeline skill — see readBroadsideSkill. */
-export declare const BROADSIDE_SKILL_NAME = "broadside";
-export declare const BROADSIDE_STATE_FILE = "state.json";
-export declare const BROADSIDE_CONFIG_FILE = "config.yaml";
-export declare const BROADSIDE_STATE_SCHEMA_VERSION = 1;
-export declare const BROADSIDE_INPUT_PRICE_PER_M = 0.375;
-export declare const BROADSIDE_OUTPUT_PRICE_PER_M = 1.875;
-export declare const BROADSIDE_MODELS_URL = "https://openrouter.ai/api/v1/models";
-export declare const BROADSIDE_BENCHMARKS_URL = "https://openrouter.ai/api/v1/benchmarks";
-export declare const BROADSIDE_CATALOG_CACHE_FILE = "model-catalog.json";
-/**
- * What this repository's own submits learned about batch endpoints: which
- * `:batch` ids OpenRouter accepted a job for and which it refused with
- * "does not have a :batch endpoint". The catalog cannot tell the two apart
- * (#141), so the `models` action annotates its rows from this file.
- */
-export declare const BROADSIDE_ENDPOINTS_FILE = "batch-endpoints.json";
-export declare const BROADSIDE_CATALOG_CACHE_TTL_MS: number;
-export declare const BROADSIDE_LENS_IDS: readonly ["architecture", "api", "security", "defect", "conventions", "porting"];
-export type BroadsideLensId = (typeof BROADSIDE_LENS_IDS)[number];
-export declare const BROADSIDE_POLL_INTERVAL_MS = 15000;
-export declare const BROADSIDE_DEFAULT_POLL_BUDGET_MS: number;
-/**
- * The run expense limit in USD a repository gets before it configures one.
- * Pi asks a human before submitting over the estimate; the MCP surface cannot,
- * and shipped with no limit at all, so a host calling submit with the stock
- * config spent whatever the estimate came to (#231). One dollar covers a
- * six-lens run of a repository this size with room to spare; a larger one
- * raises `max_cost` in config.yaml, passes `max_cost` on the call, or sets it
- * to 0 for no limit.
- */
-export declare const BROADSIDE_DEFAULT_MAX_COST = 1;
-export type ModelPricing = {
-    /** USD per million input tokens. */
-    inputPerM: number;
-    /** USD per million output tokens. */
-    outputPerM: number;
-    /** Where the numbers came from — affects what the submit text claims. */
-    source: "built-in" | "config" | "live" | "cache";
-};
-/** The subset of the OpenRouter model catalog Broad-Side actually uses. */
-export type CatalogEntry = {
-    id: string;
-    name: string;
-    inputPerM: number;
-    outputPerM: number;
-    cachedInputPerM?: number;
-    contextLength?: number;
-    maxCompletionTokens?: number;
-    /** Empty array means unknown, not "supports nothing". */
-    supportedParameters: string[];
-    expirationDate?: string | null;
-};
-export type CodingBenchmarks = {
-    /** Base model slug (batch suffix stripped) → indices. */
-    byBaseSlug: Record<string, {
-        codingIndex?: number;
-        intelligenceIndex?: number;
-    }>;
-    /** Citation/attribution metadata from the benchmarks endpoint. */
-    meta: Record<string, unknown>;
-};
-export type BroadsideCatalogResult = {
-    model: string;
-    source: "built-in" | "config" | "live" | "cache";
-    /**
-     * Always resolved. `resolveCatalogEntry` either returns an entry — from
-     * config, cache, the live catalog, or the compile-time fallback — or throws
-     * naming the model it could not price. This was declared nullable, which is
-     * the only reason the single consumer needed a non-null assertion to read it.
-     */
-    entry: CatalogEntry;
-    benchmarks?: CodingBenchmarks;
-};
-export type JsonSchemaDef = {
-    name: string;
-    strict: boolean;
-    schema: Record<string, unknown>;
-};
-/**
- * Where the file list and the file contents both came from — one source, so
- * a run's results correspond to one state of the repository (#248).
- * `working-tree`: git's view of the checkout (tracked plus untracked files,
- * ignore rules applied, files deleted on disk left out); `walk`: a bounded
- * directory walk, for a target that is not a git repository.
- */
-export type RepoSnapshotSource = "working-tree" | "walk";
-export type RepoInfo = {
-    name: string;
-    path: string;
-    language: string;
-    manifest: {
-        path: string;
-        content: string;
-    } | null;
-    mainFile: string;
-    readmeFirst: string;
-    fileTree: string;
-    fileCounts: Record<string, number>;
-    sourceGlob: string;
-    sourceExts: string[];
-    /** How many slurpable files carry one of `sourceExts`; zero means no lens has code to scan. */
-    sourceFileCount: number;
-    snapshot: RepoSnapshotSource;
-    /** Files left out of every lens because their name says they hold secrets (#252). */
-    secretFilesSkipped: string[];
-    /** Secret-like values redacted from the entry point, manifest, and README excerpt. */
-    redactedValues: number;
-};
-export type FileSlice = {
-    moduleName: string;
-    content: string;
-    fileCount: number;
-    chars: number;
-    /** Repo-relative paths of the files folded into this slice. */
-    files: string[];
-    /** Secret-like values redacted from this slice's files before upload (#252). */
-    redactedValues?: number;
-    /** The files in this slice that had at least one value redacted. */
-    redactedFiles?: string[];
-    /**
-     * Set when the lens's targeted globs matched nothing and the slice was
-     * built from its fallback globs instead (#319). The estimate, the batch
-     * entry, and the prompt all say so.
-     */
-    fallback?: string;
-};
-/**
- * OpenRouter's unified `reasoning` control, as sent on a lens request.
- *
- * Left unsent, each model applies its own default — which is how a
- * reasoning-capable model came to spend 5,758 of a 6,000-token output budget
- * thinking, leaving ~230 tokens for JSON that then truncated mid-structure. The
- * thinking is billed at the full *output* rate, so the run paid for roughly
- * 6,000 output tokens per slice to receive 230 usable ones.
- */
-export type BroadsideReasoning = {
-    enabled?: boolean;
-    effort?: "minimal" | "low" | "medium" | "high";
-    max_tokens?: number;
-};
-/**
- * The reasoning control every lens request carries: low effort.
- *
- * It used to be a token cap — `max_tokens` at a quarter of the lens's output
- * budget, so three quarters stayed for the answer. Measured live on
- * `google/gemini-3.8-flash:batch` (0.22.0 verification, defect lens, cap
- * 5,800 of a 6,000 budget): the model reasoned 5,218 tokens on the first
- * pass and **11,518 under the same cap** on the doubled-budget retry —
- * thinking scaled with `max_tokens` and the cap changed nothing, both
- * results truncated, and the retry cost twice the original for no JSON.
- * The same lens with `effort: "low"` reasoned 0 tokens, finished with
- * `stop`, returned valid JSON, and cost a twelfth as much. Gemini 3.x
- * models take a thinking *level*, not a budget, and OpenRouter forwards a
- * `max_tokens` cap to them as nothing at all; `effort` is what it can
- * translate for every provider (a level where the provider has levels, a
- * fraction of the budget where it takes a budget). So the default asks for
- * little thinking in the one vocabulary that reaches everyone.
- *
- * Deliberately not `enabled: false`: `google/gemini-3.8-flash:batch` refuses
- * the whole batch with *"Reasoning is mandatory for this endpoint and cannot
- * be disabled"*, turning a partial result into none at all. Low effort works
- * whether or not a provider allows reasoning to be switched off.
- */
-export declare const BROADSIDE_DEFAULT_REASONING: Readonly<BroadsideReasoning>;
-/** The reasoning control a lens request carries when config.yaml sets none. */
-export declare function defaultReasoningFor(): BroadsideReasoning;
-/**
- * The reasoning control a truncated slice is re-submitted with.
- *
- * A truncation on a reasoning-capable model is usually thinking that ate the
- * answer's budget, and doubling `max_tokens` doubles the thinking where the
- * provider ignores a token cap (see {@link BROADSIDE_DEFAULT_REASONING}). The
- * retry therefore asks for low effort as well, replacing a `max_tokens` cap
- * (OpenRouter refuses a request carrying both) and lowering a higher effort.
- * An explicit `enabled: false` and an effort already at or below low are left
- * as they are.
- */
-export declare function retryReasoningFor(original: BroadsideReasoning | undefined): BroadsideReasoning;
-export type BatchRequest = {
-    custom_id: string;
-    body: {
-        model: string;
-        messages: {
-            role: "system" | "user";
-            content: string;
-        }[];
-        response_format: {
-            type: "json_schema";
-            json_schema: JsonSchemaDef;
-        };
-        max_tokens: number;
-        reasoning?: BroadsideReasoning;
-    };
-};
-export type BatchTerminalStatus = "completed" | "failed" | "expired" | "cancelled";
-export type BroadsideBatchEntry = {
-    batchId: string;
-    requests: number;
-    status: string;
-    submittedAt: string;
-    completedAt?: string;
-    estimatedCost: number;
-    cost?: number;
-    resultCount?: number;
-    error?: unknown;
-    /** Why a `skipped` lens had nothing to submit: the globs that matched no file. */
-    reason?: string;
-    /**
-     * Set when the lens scanned its fallback scope because its targeted globs
-     * matched nothing (#319): "no files matched …; scanned all javascript
-     * sources instead". Absent for a targeted scan.
-     */
-    fallback?: string;
-    /** Set when this lens used a model other than the run default. */
-    model?: string;
-    /** The completion ceiling of this lens's model; bounds the truncation retry. */
-    outputCap?: number;
-};
-export type BroadsideSynthesisEntry = {
-    batchId?: string;
-    status: "pending" | "submitted" | "completed" | "failed";
-    cost?: number;
-    /** Why the pass was retired, when the batch reported one. */
-    error?: string;
-};
-/** One triage item — a scouting lead turned into a work-order entry. */
-export type TriageItem = {
-    title: string;
-    severity: string;
-    module: string;
-    impact: "high" | "medium" | "low";
-    difficulty: "high" | "medium" | "low";
-    priority: string;
-    effort_estimate: string;
-    rationale: string;
-};
-export type BroadsideTriageEntry = {
-    batchId?: string;
-    status: "pending" | "submitted" | "completed" | "failed";
-    cost?: number;
-    error?: string;
-};
-/** Recorded on the run once a verification pass has run (#143); see core/broadside-verify.ts. */
-export type BroadsideVerifyEntry = {
-    /** `completed`: every selected finding got a verdict; `partial`: the cost cap or an abort stopped it early. */
-    status: "completed" | "partial";
-    model: string;
-    top: number;
-    verified: number;
-    confirmed: number;
-    cost: number;
-    at: string;
-};
-/** The truncation retry pass of one run: one batch per model (#206). */
-export type BroadsideRetryEntry = {
-    status: "submitted" | "completed" | "failed";
-    batches: Array<{
-        model: string;
-        batchId: string;
-    }>;
-    /** When the owning collect claimed the pass (#322). */
-    claimedAt: string;
-};
-/**
- * The parts of a run that cost money to submit and that exactly one collect
- * may own: the two post-passes and the truncation retry (#322).
- */
-export type BroadsideRunSlot = "synthesis" | "triage" | "retry";
-export declare const BROADSIDE_RUN_SLOTS: readonly BroadsideRunSlot[];
-export type BroadsideRun = {
-    id: string;
-    createdAt: string;
-    model: string;
-    lenses: BroadsideLensId[];
-    status: "in-flight" | "completed" | "partial" | "failed";
-    outputDir: string;
-    batches: Partial<Record<BroadsideLensId, BroadsideBatchEntry>>;
-    synthesis: BroadsideSynthesisEntry;
-    triage: BroadsideTriageEntry;
-    /**
-     * The truncation retry pass (#133), recorded so that two collects on one
-     * run cannot both submit it (#322). Absent until a collect claims it.
-     */
-    retry?: BroadsideRetryEntry;
-    /** The verification pass over the top findings, when one has run (#143). */
-    verify?: BroadsideVerifyEntry;
-    totalCost?: number;
-    pricing?: ModelPricing;
-    maxCost?: number;
-    /** The model's completion ceiling, recorded so collect can cap retries. */
-    outputCap?: number;
-    /** Git HEAD at submit time, for incremental re-scouting (#142). */
-    sourceHead?: string | null;
-    /** Whether the working tree was dirty at submit time. */
-    sourceDirty?: boolean;
-    /** When incremental, the previous run's HEAD this run diffs against. */
-    baseHead?: string | null;
-    /** Where the scanned files and their contents were read from (#248). */
-    snapshot?: RepoSnapshotSource;
-    /** The language the lenses scanned as. */
-    language?: string;
-    /** What the secret-redaction pass did before upload (#252); absent on runs from before it. */
-    redaction?: {
-        enabled: boolean;
-        values: number;
-        files: number;
-        skippedFiles: number;
-    };
-};
-export type BroadsideStateFile = {
-    schema_version: number;
-    runs: BroadsideRun[];
-};
-export type BroadsideConfig = {
-    model: string;
-    apiKey: string;
-    defaultLenses: BroadsideLensId[];
-    /** Approximate run expense limit in USD; 0 means no limit. */
-    maxCost: number;
-    /** Manual pricing overrides (USD per million). Live lookup is preferred. */
-    pricing: {
-        inputPerM: number;
-        outputPerM: number;
-    } | null;
-    /**
-     * Per-lens model overrides. A lens absent here uses `model`. This is how a
-     * repository routes the semantic lenses (security, defect) to a stronger
-     * batch model while the cheap default carries the rest — the whole point of
-     * the cheap model is telling the expensive one where to look, and that
-     * trade-off is not the same for every lens.
-     */
-    lensModels: Partial<Record<BroadsideLensId, string>>;
-    /** Overrides every lens's reasoning setting when present. */
-    reasoning: BroadsideReasoning | null;
-    /**
-     * Repo defaults for the per-call run knobs. Each mirrors a tool parameter
-     * of the same name; an explicit parameter always wins. They live here so a
-     * repository can fix its own scouting policy once instead of restating it
-     * on every submit and collect.
-     */
-    incremental: boolean;
-    retryTruncated: boolean;
-    includeSynthesis: boolean;
-    includeTriage: boolean;
-    /** Default poll budget in seconds; 0 means "return immediately". */
-    waitSeconds: number;
-    /**
-     * Replace secret-like values with `[REDACTED:<kind>]` and skip files named
-     * like credential stores before anything is uploaded (#252). On by default;
-     * off only for a repository whose maintainers have decided its contents may
-     * leave as they are.
-     */
-    redactSecrets: boolean;
-};
-/**
- * The pre-flight facts a caller needs to decide whether a run is worth its
- * price: what each lens would cost, at what rates, against which limit. Handed
- * to {@link BroadsideSubmitOptions.confirm} before anything is submitted.
- */
-export type BroadsideEstimate = {
-    model: string;
-    pricing: ModelPricing;
-    lenses: Array<{
-        lensId: BroadsideLensId;
-        name: string;
-        slices: number;
-        maxTokens: number;
-        cost: number;
-        /** The model this lens would use — `model` unless a per-lens override applies. */
-        model: string;
-        pricing: ModelPricing;
-        /** Set when this lens is priced on its fallback scope (#319); see BroadsideBatchEntry.fallback. */
-        fallback?: string;
-    }>;
-    /** True when at least one lens uses a model other than the run default. */
-    mixedModels: boolean;
-    totalCost: number;
-    inputTokens: number;
-    outputTokens: number;
-    /** Run expense limit in USD; 0 means no limit. */
-    maxCost: number;
-    /** True when totalCost is over a non-zero maxCost. */
-    exceedsLimit: boolean;
-    /** Set when incremental scouting found a baseline to diff against. */
-    baseHead: string | null;
-    sourceDirty: boolean;
-    /** Whether a requested incremental run actually narrowed this estimate. */
-    incremental: BroadsideIncrementalOutcome;
-    /** The provider's completion ceiling, when the catalog advertises one. */
-    outputCap?: number;
-};
-/**
- * OpenRouter rejected the API key (HTTP 401/403). Thrown from the catalog
- * lookup rather than swallowed into "could not price" or a silent built-in
- * fallback: a run that cannot authenticate cannot submit either, and the
- * message that reaches the user has to say so (#251).
- */
-export declare class BroadsideAuthError extends Error {
-    readonly httpStatus: number;
-    readonly detail: string;
-    constructor(httpStatus: number, detail: string);
-}
-/**
- * `broadside/config.yaml` exists but cannot be used. A file that failed to
- * parse used to be treated exactly like an absent one — defaults, including
- * no spend cap and no lens routing, with no message — so a typo removed the
- * user's own guard (#232). Only an absent file yields defaults now.
- */
-export declare class BroadsideConfigError extends Error {
-    readonly path: string;
-    constructor(path: string, detail: string);
-}
-/**
- * `broadside/state.json` exists but cannot be read. It used to be read as
- * empty and the next checkpoint wrote that empty state over it, losing the
- * batch ids of every in-flight, already-paid run (#233). The corrupt file is
- * preserved beside itself and nothing writes over it until someone looks.
- */
-export declare class BroadsideStateError extends Error {
-    readonly path: string;
-    readonly backupPath: string;
-    constructor(path: string, backupPath: string, detail: string);
-}
-/** Thrown when a confirm hook declines a run. Nothing was submitted. */
-export declare class BroadsideCancelledError extends Error {
-    constructor(message?: string);
-}
-/**
- * Whether incremental scouting actually narrowed the run.
- *
- * A request for incremental falls back to a full scan whenever there is nothing
- * to diff against, and that fallback costs real money — the caller asked for the
- * cheap mode and gets the expensive one. It must be reported, not inferred from
- * the request counts.
- */
-export type BroadsideIncrementalOutcome = {
-    requested: boolean;
-    applied: boolean;
-    /** The commit the run diffed against, when one was found. */
-    baseHead: string | null;
-    /** Why a requested incremental run did not apply. */
-    reason?: "dirty-worktree" | "no-baseline" | "diff-failed";
-};
-export type BroadsideSubmitResult = {
-    runId: string;
-    outputDir: string;
-    batches: Partial<Record<BroadsideLensId, BroadsideBatchEntry>>;
-    estimatedTotalCost: number;
-    estimatedInputTokens: number;
-    estimatedOutputTokens: number;
-    pricing: ModelPricing;
-    maxCost?: number;
-    modelInfo: {
-        contextLength?: number;
-        maxCompletionTokens?: number;
-        supportsStructuredOutputs?: boolean;
-        expirationDate?: string | null;
-    };
-    incremental: BroadsideIncrementalOutcome;
-    /** What was scanned: the language the lenses ran as and the snapshot the files came from. */
-    repo: {
-        language: string;
-        sourceFiles: number;
-        snapshot: RepoSnapshotSource;
-        sourceHead: string | null;
-        sourceDirty: boolean;
-    };
-    /** What the secret-redaction pass did before upload (#252). */
-    redaction: {
-        enabled: boolean;
-        values: number;
-        files: number;
-        skippedFiles: string[];
-    };
-};
-export type BroadsideCollectResult = {
-    runId: string;
-    status: string;
-    totalCost: number;
-    resultCount: number;
-    /** Results whose JSON did not parse even after fence stripping —
-     * the signature of an output cut off at max_tokens. */
-    truncatedCount: number;
-    /** Truncated slices recovered by the automatic re-submit pass (#133). */
-    retriedCount: number;
-    /** Another collect on this run owns the retry pass; its result lands on a later collect (#322). */
-    retryElsewhere?: boolean;
-    lensOutcomes: Partial<Record<BroadsideLensId, {
-        status: string;
-        cost?: number;
-        resultCount?: number;
-        truncated?: number;
-        error?: string;
-    }>>;
-    synthesis: BroadsideSynthesisEntry;
-    triage: BroadsideTriageEntry;
-    topFindings: {
-        title: string;
-        severity: string;
-        sourceLens: string;
-        summary: string;
-    }[];
-    topTriageItems: TriageItem[];
-};
-type LensDefinition = {
-    id: BroadsideLensId;
-    name: string;
-    description: string;
-    schemaName: string;
-    sliceBy: "none" | "directory" | "auto";
-    maxChars: number;
-    maxTokens: number;
-    reasoning?: BroadsideReasoning;
-    skipTestFiles?: boolean;
-    globsFor: (info: RepoInfo) => string[];
-    /**
-     * Where to look when `globsFor` matches no source file (#319). The
-     * security and api lenses target server/, auth, and middleware paths
-     * because that is where the trust boundary usually lives; a service whose
-     * server is `src/server.js` matched none of them and got no security
-     * review at all. A match that is only documents is the same starvation:
-     * `SECURITY.md` satisfied the security lens on CodeCartographer itself,
-     * which then reviewed a policy and reported zero findings. The fallback
-     * is the language's whole source set, added to whatever did match —
-     * priced as such, and said so in the estimate, the run record, and the
-     * prompt.
-     */
-    fallbackGlobsFor?: (info: RepoInfo) => string[];
-    systemPrompt: (info: RepoInfo) => string;
-    userPrompt: (info: RepoInfo, source: string, moduleName: string) => string;
-};
-export declare function getLens(lensId: BroadsideLensId): LensDefinition;
-export declare function listLenses(): LensDefinition[];
-/** The languages Broad-Side can scan; anything else is refused at submit. */
-export declare const BROADSIDE_LANGUAGES: readonly ["go", "python", "rust", "typescript", "javascript"];
-/**
- * The files a run scans, and where they came from. Contents are always read
- * from the working tree, so the list is the working tree's too: tracked files
- * plus untracked ones git does not ignore, minus files deleted on disk. The
- * list used to come from `git ls-tree HEAD`, so a run mixed the committed
- * file list with uncommitted contents and never saw an untracked file (#248).
- * A target that is not a git repository gets a bounded walk.
- */
-export declare function listRepoFiles(targetDir: string): Promise<{
-    files: string[];
-    snapshot: RepoSnapshotSource;
-}>;
-export declare function collectRepoInfo(targetDir: string, opts?: {
-    redact?: boolean;
-}): Promise<RepoInfo>;
-export declare function isSlurpable(relPath: string): boolean;
-type CollectedFile = {
-    relPath: string;
-    moduleName: string;
-};
-/**
- * The files a lens will read: its targeted globs, or — when those match no
- * source file and the lens declares a fallback — the fallback globs on top
- * of whatever did match, with a sentence saying so (#319). The sentence
- * travels to the estimate, the batch entry, and the prompt, so a fallback
- * scan is never a silent one.
- *
- * "No source file" rather than "no file": a policy document or a config
- * file under a targeted path satisfies the globs and leaves the lens with
- * nothing to review, and the coverage note it writes back is the only sign.
- */
-export declare function selectLensFiles(allFiles: string[], lens: LensDefinition, info: RepoInfo): {
-    files: CollectedFile[];
-    fallback?: string;
-};
-export declare function gatherSlices(targetDir: string, lens: LensDefinition, info: RepoInfo, opts?: {
-    redact?: boolean;
-}): Promise<FileSlice[]>;
-export declare function buildBatchRequest(lens: LensDefinition, info: RepoInfo, slice: FileSlice, index: number, sliceCount: number, model?: string, maxTokensOverride?: number, reasoningOverride?: BroadsideReasoning): BatchRequest;
-/**
- * Pre-flight cost estimate for one lens.
- *
- * Every slice is its own batch request, so both halves scale with the slice
- * count. The output half used to be a single `maxTokens * 0.75` for the whole
- * lens no matter how many requests it sent — on a repository that sliced into
- * 13 modules that budgeted one request's output and shipped thirteen, and a
- * live run came in at roughly 3x its estimate. Since this number is what
- * `max_cost` binds against, under-counting it lets a run outspend the cap the
- * user set.
- *
- * @param info - Repo info, when the caller has it: lets the estimate include
- *   the system prompt and JSON schema each request carries. Omitted, the
- *   estimate covers slice content only, which is what the old signature did.
- */
-export declare function estimateCost(lens: LensDefinition, slices: FileSlice[], pricing: ModelPricing, maxTokensOverride?: number, info?: RepoInfo): {
-    inputTokens: number;
-    outputTokens: number;
-    cost: number;
-};
-export declare function broadsideDirFor(cwd: string): string;
-/**
- * Read the Broad-Side reading guide.
- *
- * It is deliberately not a post-pipeline skill under `.codecarto/skills/`: a
- * scout run is read *before* or *during* the interactive pipeline, and the
- * post-pipeline machinery gates on a completed run and wraps its prompt in
- * post-pipeline framing that would be false here. It is also readable on a
- * repository that has scout state and no workspace at all, which is why this
- * falls back to the packaged copy.
- *
- * @param cwd - Absolute path to the target repository.
- * @returns the skill text and the path it came from.
- * @throws when neither the workspace copy nor the packaged copy exists.
- */
-export declare function readBroadsideSkill(cwd: string): Promise<{
-    path: string;
-    content: string;
-}>;
-export declare function defaultBroadsideState(): BroadsideStateFile;
-export declare function loadBroadsideState(broadsideDir: string): Promise<BroadsideStateFile>;
-/**
- * Overwrite `state.json` wholesale with `state`.
- *
- * Prefer {@link persistBroadsideRun} anywhere a live operation is recording its
- * own progress — this entry point replaces the file, so any run a concurrent
- * process recorded in the meantime is erased. It remains the right call for
- * seeding a fresh workspace and for test fixtures, where "make the file exactly
- * this" is the intent.
- */
-export declare function saveBroadsideState(broadsideDir: string, state: BroadsideStateFile): Promise<void>;
-/**
- * Read-modify-write `state.json` under a lock.
- *
- * The lock is held only for the read-modify-write, never for the surrounding
- * operation: a `collect` can poll for the better part of an hour, and holding
- * the lock across that would push every concurrent caller past the 5s lock
- * timeout.
- */
-export declare function updateBroadsideStateAtomically(broadsideDir: string, mutate: (state: BroadsideStateFile) => void | Promise<void>): Promise<BroadsideStateFile>;
-/**
- * Record one run's current shape, merged into whatever is on disk *now*.
- *
- * Broad-Side operations are long-lived and hold their state in memory while
- * they poll. Writing that snapshot back wholesale silently erased any run a
- * concurrent operation had recorded since it was loaded, orphaning that run's
- * paid results on disk — present as files, invisible to `list`, and unreachable
- * by `collect`, which finds its run by position in `state.runs`. Observed live:
- * a submit at 23:35 was erased by a collect that had loaded state before it and
- * wrote back at 00:08.
- *
- * Merging by run id also self-heals: a run erased by an older writer is
- * restored the next time its own operation checkpoints.
- */
-export declare function persistBroadsideRun(broadsideDir: string, run: BroadsideRun): Promise<BroadsideStateFile>;
-/**
- * Record a collect's view of its run, keeping whatever is further along on
- * disk (#322).
- *
- * Two collects on one run each hold the run in memory and each used to write
- * the whole thing back, so the last writer replaced the other's post-pass
- * entries with its own — and both had submitted their own post-passes, since
- * each decided from the copy it loaded at entry. This writer merges slot by
- * slot: a post-pass or retry entry that is further along on disk (claimed
- * over pending, submitted over claimed, settled over submitted) wins and is
- * copied into `run`, so the caller reports what is true; a lens entry never
- * goes backwards from terminal to polling. A tie keeps this collect's copy,
- * so the collect that settled a pass records its cost. Submitting is guarded
- * separately by {@link claimRunSlot}.
- */
-export declare function persistBroadsideRunMerging(broadsideDir: string, run: BroadsideRun): Promise<BroadsideStateFile>;
-/**
- * Claim one spending slot of a run for this collect (#322).
- *
- * Read-modify-write under the state lock: if the slot on disk is still
- * unclaimed (`pending`, or absent for the retry), it is marked `submitted`
- * with no batch id *before* any network call and `true` comes back — this
- * collect owns it and may submit. Otherwise another collect got there first:
- * its entry is copied into `run` and `false` comes back. An adopted entry
- * with a batch id can be polled (polling is idempotent); one without an id
- * is a claim whose owner has not recorded the id yet, and is reported as in
- * flight elsewhere.
- */
-export declare function claimRunSlot(broadsideDir: string, run: BroadsideRun, slot: BroadsideRunSlot): Promise<boolean>;
-export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
-/** The shipped defaults: what an absent config.yaml means. */
-export declare function defaultBroadsideConfig(): BroadsideConfig;
-/** The catalog cache schema this build writes; a file from another is not read. */
-export declare const BROADSIDE_CATALOG_CACHE_SCHEMA = 3;
-/** One model's most recent submit outcome, as remembered in {@link BROADSIDE_ENDPOINTS_FILE}. */
-export type BatchEndpointRecord = {
-    status: "accepted" | "rejected";
-    /** ISO timestamp of the submit that produced this record. */
-    at: string;
-    /** The provider's refusal, for a rejected endpoint. */
-    error?: string;
-};
-export declare function readBatchEndpoints(broadsideDir: string): Promise<Record<string, BatchEndpointRecord>>;
-/**
- * Remember what a submit learned about each model it posted to. An accepted
- * job proves the endpoint exists; a "does not have a :batch endpoint"
- * refusal proves it does not. Any other rejection (quota, malformed request,
- * auth) says nothing about the endpoint and leaves the record alone.
- */
-export declare function recordBatchEndpoints(broadsideDir: string, outcomes: Array<{
-    model: string;
-    batchId: string;
-    error?: unknown;
-}>): Promise<void>;
-export declare function builtInCatalogEntry(model: string): CatalogEntry | null;
-export declare function builtInPricing(model: string): ModelPricing | null;
-export declare function resolveCatalogEntry(broadsideDir: string, config: BroadsideConfig, model: string, apiKey: string, fetcher?: FetchLike): Promise<BroadsideCatalogResult>;
-export declare function resolveModelPricing(broadsideDir: string, config: BroadsideConfig, model: string, apiKey: string, fetcher?: FetchLike): Promise<ModelPricing>;
-export declare function fetchCodingBenchmarks(apiKey: string, fetcher?: FetchLike): Promise<CodingBenchmarks | null>;
-export declare function listBatchModels(broadsideDir: string, config: BroadsideConfig, apiKey: string, opts?: {
-    includeBenchmarks?: boolean;
-    fetcher?: FetchLike;
-}): Promise<{
-    entries: CatalogEntry[];
-    source: string;
-    benchmarks: CodingBenchmarks | null;
-    defaultModel: string;
-    /** This repository's remembered submit outcomes per model, from {@link BROADSIDE_ENDPOINTS_FILE}. */
-    endpoints: Record<string, BatchEndpointRecord>;
-}>;
-export type FetchLike = (url: string, init: Record<string, unknown>) => Promise<Response>;
-export declare function submitBatch(batchRequests: BatchRequest[], apiKey: string, fetcher?: FetchLike, model?: string): Promise<{
-    batchId: string;
-    status: string;
-    error?: unknown;
-}>;
-export declare function fetchBatch(batchId: string, apiKey: string, fetcher?: FetchLike): Promise<Record<string, unknown>>;
-/**
- * Batch statuses that will never produce a result.
- *
- * Deliberately excludes the synthetic `timeout` this module returns when a poll
- * budget expires: that batch is still running server-side and has already been
- * charged, so callers must come back for it rather than retire it.
- */
-export declare const BROADSIDE_DEAD_BATCH_STATUSES: string[];
-/**
- * Batch entry statuses collect never polls again: the dead ones above, plus
- * `completed`, plus the two a submit assigns without a batch (`skipped`: no
- * matching files; `rejected`: the provider refused it). The 0.19.1 changelog
- * called the dead set "a named constant rather than two hand-maintained
- * lists"; this set was still three literal copies (self-audit sem 5.8).
- */
-export declare const BROADSIDE_TERMINAL_ENTRY_STATUSES: string[];
-export declare function pollBatchUntilTerminal(batchId: string, apiKey: string, opts?: {
-    deadlineMs?: number;
-    onStatus?: (status: string, counts: Record<string, unknown>) => void;
-    fetcher?: FetchLike;
-    pollIntervalMs?: number;
-    /**
-     * Stops polling early with the same synthetic `timeout` a spent budget
-     * returns: the batch keeps running server-side and a later collect
-     * claims it. The MCP server aborts when its client disconnects (#322).
-     */
-    signal?: AbortSignal;
-}): Promise<Record<string, unknown>>;
-/**
- * Poll several batch ids in parallel against one shared deadline. Collect
- * previously polled one lens at a time, so a slow first lens serialized the
- * wall clock for lenses that had already finished server-side (#136). The
- * onStatus callback identifies the lens so progress output stays readable
- * even while the polls interleave.
- */
-export declare function pollBatchesConcurrently(entries: Array<{
-    lensId: BroadsideLensId;
-    batchId: string;
-}>, apiKey: string, opts?: {
-    deadlineMs?: number;
-    fetcher?: FetchLike;
-    pollIntervalMs?: number;
-    signal?: AbortSignal;
-    onStatus?: (lensId: string, status: string, counts: Record<string, unknown>) => void;
-}): Promise<Map<string, Record<string, unknown>>>;
-export declare function runBroadsideSubmit(cwd: string, apiKey: string, opts?: {
-    lenses?: BroadsideLensId[];
-    fetcher?: FetchLike;
-    model?: string;
-    /**
-     * Per-lens model overrides for this run, layered over config.yaml's
-     * `lens_models`: a lens named here runs on this model, a lens named only
-     * in the file runs on the file's, and the rest run on `model` (#141).
-     */
-    lensModels?: Partial<Record<BroadsideLensId, string>>;
-    /** Approximate run expense limit in USD; 0 means no limit. */
-    maxCost?: number;
-    /** Submit even when the estimate exceeds maxCost. */
-    force?: boolean;
-    /** Diff against the previous run's HEAD and scan only changed modules (#142). */
-    incremental?: boolean;
-    /**
-     * Called with the pre-flight estimate after slicing and before any state
-     * write or submission. Returning false throws {@link BroadsideCancelledError}
-     * and nothing is submitted; returning true proceeds even past maxCost,
-     * because an interactive approval of a priced run *is* the force flag.
-     *
-     * A surface that cannot ask a human (MCP) omits this and keeps the
-     * refuse-unless-force behavior.
-     */
-    confirm?: (estimate: BroadsideEstimate) => boolean | Promise<boolean>;
-}): Promise<BroadsideSubmitResult>;
-export type StoredLensResult = {
-    lensId: BroadsideLensId;
-    customId: string;
-    moduleName: string;
-    content: string;
-    raw: Record<string, unknown>;
-    /** True when the content is not parseable JSON even after fence stripping —
-     * the telltale of an output cut off at max_tokens. */
-    truncated: boolean;
-};
-/**
- * Parse lens content as JSON, tolerating the markdown code fences some models
- * wrap structured output in (the same tolerance OpenRouter's headless-agent
- * scaffold ships for --output-schema). Returns null when the content is not
- * JSON at all — which for a strict json_schema request means the output was
- * truncated at max_tokens, not that the model chose prose.
- */
-export declare function parseLensJson(content: string): unknown | null;
-export declare function saveLensResults(runDir: string, lensId: BroadsideLensId, batch: Record<string, unknown>): Promise<StoredLensResult[]>;
-/**
- * Rebuild lens results from what a previous collect already wrote to disk.
- *
- * The post-passes are gated on having lens findings in hand, and a collect
- * only holds the ones *it* polled. When an earlier collect saved every lens
- * and then died before synthesis and triage ran — the batch window is long
- * and a poll can easily be interrupted — the next collect finds every lens
- * already terminal, skips them all, and would otherwise reach the post-pass
- * gate with nothing to hand it. Reading the saved results back is what makes
- * "a resumed collect can finish whichever is still pending" true.
- */
-export declare function loadSavedLensResults(runDir: string, lenses: BroadsideLensId[]): Promise<StoredLensResult[]>;
-export declare function runBroadsideCollect(cwd: string, apiKey: string, opts?: {
-    waitMs?: number;
-    includeSynthesis?: boolean;
-    includeTriage?: boolean;
-    /** Re-submit truncated slices once with a doubled output cap (#133). */
-    retryTruncated?: boolean;
-    onStatus?: (lensId: string, status: string, counts: Record<string, unknown>) => void;
-    fetcher?: FetchLike;
-    /**
-     * Which run to collect. Absent, the most recent — which used to be the
-     * only choice, so an older run still in flight could not be collected
-     * once a newer submit existed (#268). `status` lists the ids.
-     */
-    runId?: string;
-    /**
-     * Stops polling and submits nothing further once fired; what was
-     * already submitted keeps running server-side for a later collect to
-     * claim. The MCP server fires it when its client disconnects (#322).
-     */
-    signal?: AbortSignal;
-    /** Poll cadence override; tests drive the loop faster than 15 s. */
-    pollIntervalMs?: number;
-}): Promise<BroadsideCollectResult>;
-export declare function runBroadsideStatus(cwd: string): Promise<{
-    state: BroadsideStateFile;
-}>;
-export declare function renderFindingsMarkdown(content: string): string;
-export declare function describeIncrementalFallback(reason: BroadsideIncrementalOutcome["reason"]): string;
-export declare function estimateSubmitText(result: BroadsideSubmitResult, lenses: LensDefinition[]): string;
-export declare function modelsText(entries: CatalogEntry[], opts: {
-    benchmarks: CodingBenchmarks | null;
-    defaultModel: string;
-    endpoints?: Record<string, BatchEndpointRecord>;
-}): string;
-/**
- * A provider refusal plus what to do about it, for the two refusals a batch
- * run meets in practice and cannot fix by itself (#141):
- *
- * - `Model '<id>' does not have a :batch endpoint.` — the catalog advertises a
- *   `:batch` id that OpenRouter runs no batch endpoint for. Nothing in the
- *   catalog distinguishes these; the `models` action marks ids this
- *   repository has seen refused.
- * - `job-submission-count … in use: 16, quota: 16` — the per-account limit
- *   on concurrent batch jobs. Broad-Side submits one job per lens, so a few
- *   runs in flight on the same key fill it; the refusal costs nothing.
- */
-export declare function explainBatchError(error: unknown): string | null;
-export declare function collectResultText(result: BroadsideCollectResult): string;
-/**
- * An `onStatus` callback that appends one line to `lines` per *change* of a
- * lens's polled status. Every poll used to append a line, so a four-minute
- * wait returned twenty-six identical "in_progress (0/1)" lines per lens
- * before the result (0.22.0 live run).
- */
-export declare function statusLineWriter(lines: string[]): (lensId: string, status: string, counts: Record<string, unknown>) => void;
-export declare function statusText(state: BroadsideStateFile): string;
-export {};
+export * from "./broadside/constants.ts";
+export * from "./broadside/types.ts";
+export * from "./broadside/schemas.ts";
+export * from "./broadside/lenses.ts";
+export * from "./broadside/repo.ts";
+export * from "./broadside/requests.ts";
+export * from "./broadside/state.ts";
+export * from "./broadside/models.ts";
+export * from "./broadside/client.ts";
+export * from "./broadside/submit.ts";
+export * from "./broadside/results.ts";
+export * from "./broadside/verify.ts";
+export * from "./broadside/collect.ts";
+export * from "./broadside/render.ts";