codecartographer-pi 0.16.0 → 0.17.0

package/dist/core/broadside.d.ts

@@ -0,0 +1,421 @@
+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.1875;
+export declare const BROADSIDE_OUTPUT_PRICE_PER_M = 0.9375;
+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";
+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;
+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";
+    entry: CatalogEntry | null;
+    benchmarks?: CodingBenchmarks;
+};
+export type JsonSchemaDef = {
+    name: string;
+    strict: boolean;
+    schema: Record<string, unknown>;
+};
+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[];
+};
+export type FileSlice = {
+    moduleName: string;
+    content: string;
+    fileCount: number;
+    chars: number;
+    /** Repo-relative paths of the files folded into this slice. */
+    files: string[];
+};
+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;
+    };
+};
+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;
+    /** 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;
+};
+/** 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;
+};
+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;
+    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;
+};
+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>>;
+    /**
+     * 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;
+};
+/**
+ * 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;
+    }>;
+    /** 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;
+    /** The provider's completion ceiling, when the catalog advertises one. */
+    outputCap?: number;
+};
+/** Thrown when a confirm hook declines a run. Nothing was submitted. */
+export declare class BroadsideCancelledError extends Error {
+    constructor(message?: string);
+}
+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;
+    };
+};
+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;
+    lensOutcomes: Partial<Record<BroadsideLensId, {
+        status: string;
+        cost?: number;
+        resultCount?: number;
+        truncated?: number;
+    }>>;
+    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;
+    skipTestFiles?: boolean;
+    globsFor: (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[];
+export declare function collectRepoInfo(targetDir: string): Promise<RepoInfo>;
+export declare function gatherSlices(targetDir: string, lens: LensDefinition, info: RepoInfo): Promise<FileSlice[]>;
+export declare function buildBatchRequest(lens: LensDefinition, info: RepoInfo, slice: FileSlice, index: number, sliceCount: number, model?: string, maxTokensOverride?: number): BatchRequest;
+export declare function estimateCost(lens: LensDefinition, slices: FileSlice[], pricing: ModelPricing, maxTokensOverride?: number): {
+    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>;
+export declare function saveBroadsideState(broadsideDir: string, state: BroadsideStateFile): Promise<void>;
+export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
+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;
+}>;
+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>>;
+export declare function pollBatchUntilTerminal(batchId: string, apiKey: string, opts?: {
+    deadlineMs?: number;
+    onStatus?: (status: string, counts: Record<string, unknown>) => void;
+    fetcher?: FetchLike;
+    pollIntervalMs?: number;
+}): 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;
+    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;
+    /** 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[]>;
+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;
+}): Promise<BroadsideCollectResult>;
+export declare function runBroadsideStatus(cwd: string): Promise<{
+    state: BroadsideStateFile;
+}>;
+export declare function renderFindingsMarkdown(content: string): string;
+export declare function estimateSubmitText(result: BroadsideSubmitResult, lenses: LensDefinition[]): string;
+export declare function modelsText(entries: CatalogEntry[], opts: {
+    benchmarks: CodingBenchmarks | null;
+    defaultModel: string;
+}): string;
+export declare function collectResultText(result: BroadsideCollectResult): string;
+export declare function statusText(state: BroadsideStateFile): string;
+export {};