codecartographer-pi 0.19.0 → 0.19.2

package/.codecarto/broadside/SKILL.md

@@ -90,6 +90,17 @@ Collect runs two cross-lens post-passes by default: **synthesis** (the
 executive report) and **triage** (the prioritized work order). Pass
 `include_synthesis: false` or `include_triage: false` on collect to skip one.
 
+Two caveats apply to any model you pick. The `models` action lists every id
+OpenRouter advertises a `:batch` variant for, and many of those variants do not
+exist — submitting one returns `does not have a :batch endpoint`, with nothing in
+the catalog to distinguish it beforehand. A rejected batch costs nothing, so
+probe a candidate on a single lens first. And reasoning competes with the answer for
+`max_tokens`: Broad-Side caps thinking at a quarter of each lens's output budget
+so three quarters remain for the JSON, which is the split the cost estimate
+already assumes. It caps rather than disables because some endpoints refuse to
+be switched off entirely. Override with `reasoning:` in `config.yaml` only
+alongside a raised output budget.
+
 Lenses do not all have to run on the same model. `lens_models` in `config.yaml`
 routes individual lenses to their own batch model — the usual reason being that
 a stronger model changes security and defect findings more than it changes an
@@ -125,6 +136,13 @@ from OpenRouter's runtime cost tracking: it predicts from file sizes before
 spend, it does not stop a batch mid-flight. Actual spend appears in
 `run-meta.json` after collect.
 
+Budget for the **ceiling, not the estimate**. OpenRouter charges the worst
+case when it accepts a batch — every request's full `max_tokens` — and
+refunds the unused output as each request settles. A six-lens scan of this
+repository held $0.6972 and settled at $0.3806, so the balance a run needs to
+*start* is roughly double what it ends up costing. The submit estimate sits
+between the two: above what the run should settle at, below what it can hold.
+
 ## Resilience notes
 
 - **Truncation is spoken.** A lens output whose JSON does not parse — even

package/.codecarto/broadside/config.yaml

@@ -46,9 +46,48 @@
 # and picking one for you would spend your money on our guess. Compare
 # candidates with the `models` action first.
 #
+# Two things to check before committing to a model, both learned the hard way:
+#
+#   1. The `models` action lists whatever OpenRouter advertises a `:batch`
+#      variant for, and a good number of those variants do not actually exist —
+#      submitting one comes back `Model '<id>' does not have a :batch endpoint.`
+#      Nothing in the catalog distinguishes them. Every Anthropic and OpenAI
+#      batch id tried so far is rejected this way; Google and DeepSeek work.
+#      A rejected batch costs nothing, so probe a candidate on one lens before
+#      relying on it.
+#   2. A reasoning-capable model spends its output budget thinking, and the
+#      thinking is billed at the full output rate. See `reasoning:` below.
+#
 # lens_models:
-#   security: anthropic/claude-opus-4.5:batch
-#   defect: anthropic/claude-opus-4.5:batch
+#   security: deepseek/deepseek-v4-pro-0813:batch
+#   defect: deepseek/deepseek-v4-pro-0813:batch
+
+# Reasoning control, sent on every lens request.
+#
+# By default Broad-Side caps thinking at a quarter of the lens's output budget,
+# leaving the other three quarters for the answer — which is exactly the split
+# the cost estimate already assumes.
+#
+# The cap exists because reasoning competes with the answer for `max_tokens`.
+# One measured run spent 5,758 of a 6,000-token budget thinking and left ~230
+# tokens for the JSON, which truncated mid-structure on 11 of 13 slices; those
+# tokens bill at the full output rate, so it paid for ~6,000 output tokens per
+# slice to receive ~230 usable ones. The shipped default model does the same
+# thing less consistently — reasoning from 0 to 5,757 tokens across 13 slices,
+# three of them cut off — so this is not something only exotic models do.
+#
+# It is a cap rather than an off switch on purpose. Some endpoints refuse to be
+# switched off: `google/gemini-3.8-flash:batch` rejects the entire batch with
+# "Reasoning is mandatory for this endpoint and cannot be disabled", which turns
+# a partial result into none at all. Capping works either way.
+#
+# Override only with a raised lens output budget, or the JSON truncates exactly
+# as above.
+#
+# reasoning:
+#   effort: low        # minimal | low | medium | high
+#   max_tokens: 2000   # or set the thinking budget directly
+#   enabled: false     # only where the provider allows it
 
 # Approximate run expense limit in USD (0 = no limit). Before submitting,
 # Broad-Side estimates the run cost from the collected file sizes and the
@@ -68,8 +107,8 @@
 # lookup fails (offline, private model) or you want to assert a ceiling.
 #
 # pricing:
-#   input_per_m: 0.1875
-#   output_per_m: 0.9375
+#   input_per_m: 0.375
+#   output_per_m: 1.875
 # ---------------------------------------------------------------------------
 # Run defaults. Each key below mirrors a codecarto_broadside parameter of the
 # same name and sets this repository's default for it; an explicit parameter on

package/.codecarto/workflow/scaffold-version.yaml

@@ -3,4 +3,4 @@
 # workspace's framework-owned files (GUIDE.md, templates/, workflow/ pipelines
 # and VALIDATE.md) predate the running release. Written at release time and
 # copied verbatim by init — never edit by hand.
-scaffold_version: 0.19.0
+scaffold_version: 0.19.2

package/dist/core/broadside.d.ts

@@ -6,8 +6,8 @@ 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_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";
@@ -49,7 +49,13 @@ export type CodingBenchmarks = {
 export type BroadsideCatalogResult = {
     model: string;
     source: "built-in" | "config" | "live" | "cache";
-    entry: CatalogEntry | null;
+    /**
+     * 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 = {
@@ -80,6 +86,46 @@ export type FileSlice = {
     /** Repo-relative paths of the files folded into this slice. */
     files: 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 share of a lens's output budget reasoning may spend.
+ *
+ * `estimateCost` already budgets output at 75% of `maxTokens`; capping thinking
+ * at the remaining quarter makes that assumption true by construction and
+ * guarantees the answer has room. A floor keeps the cap sane for a small lens.
+ */
+export declare const BROADSIDE_REASONING_BUDGET_FRACTION = 0.25;
+export declare const BROADSIDE_MIN_REASONING_TOKENS = 512;
+/**
+ * Cap reasoning for a lens request — deliberately a cap, not an off switch.
+ *
+ * Disabling outright is not portable: `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. Capping works whether
+ * or not a provider allows reasoning to be switched off.
+ *
+ * The failure this prevents is the budget being spent thinking rather than
+ * answering. Measured on one run: 5,758 of a 6,000-token budget went to
+ * reasoning, leaving ~230 tokens for JSON that truncated mid-structure — and
+ * those tokens bill at the full output rate. The shipped default model does the
+ * same thing less consistently (reasoning tokens from 0 to 5,757 across 13
+ * slices, three of them cut off at `finish_reason: length`), so this is not a
+ * multi-model concern.
+ */
+export declare function defaultReasoningFor(maxTokens: number): BroadsideReasoning;
 export type BatchRequest = {
     custom_id: string;
     body: {
@@ -93,6 +139,7 @@ export type BatchRequest = {
             json_schema: JsonSchemaDef;
         };
         max_tokens: number;
+        reasoning?: BroadsideReasoning;
     };
 };
 export type BatchTerminalStatus = "completed" | "failed" | "expired" | "cancelled";
@@ -115,6 +162,8 @@ 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 = {
@@ -177,6 +226,8 @@ export type BroadsideConfig = {
      * 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
@@ -220,6 +271,8 @@ export type BroadsideEstimate = {
     /** 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;
 };
@@ -227,6 +280,22 @@ export type BroadsideEstimate = {
 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;
@@ -242,6 +311,7 @@ export type BroadsideSubmitResult = {
         supportsStructuredOutputs?: boolean;
         expirationDate?: string | null;
     };
+    incremental: BroadsideIncrementalOutcome;
 };
 export type BroadsideCollectResult = {
     runId: string;
@@ -277,6 +347,7 @@ type LensDefinition = {
     sliceBy: "none" | "directory" | "auto";
     maxChars: number;
     maxTokens: number;
+    reasoning?: BroadsideReasoning;
     skipTestFiles?: boolean;
     globsFor: (info: RepoInfo) => string[];
     systemPrompt: (info: RepoInfo) => string;
@@ -286,8 +357,23 @@ 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): {
+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;
@@ -313,7 +399,40 @@ export declare function readBroadsideSkill(cwd: string): Promise<{
 }>;
 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>;
 export declare function loadBroadsideConfig(broadsideDir: string): Promise<BroadsideConfig>;
 export declare function builtInCatalogEntry(model: string): CatalogEntry | null;
 export declare function builtInPricing(model: string): ModelPricing | null;
@@ -336,6 +455,14 @@ export declare function submitBatch(batchRequests: BatchRequest[], apiKey: strin
     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[];
 export declare function pollBatchUntilTerminal(batchId: string, apiKey: string, opts?: {
     deadlineMs?: number;
     onStatus?: (status: string, counts: Record<string, unknown>) => void;
@@ -398,6 +525,18 @@ export type StoredLensResult = {
  */
 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;