codecartographer-pi 0.19.1 → 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

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

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.1
+scaffold_version: 0.19.2

package/dist/core/broadside.d.ts

@@ -86,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: {
@@ -99,6 +139,7 @@ export type BatchRequest = {
             json_schema: JsonSchemaDef;
         };
         max_tokens: number;
+        reasoning?: BroadsideReasoning;
     };
 };
 export type BatchTerminalStatus = "completed" | "failed" | "expired" | "cancelled";
@@ -185,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
@@ -304,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;
@@ -313,7 +357,7 @@ 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 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.
  *

package/dist/core/broadside.js

@@ -74,6 +74,34 @@ export const BROADSIDE_LENS_IDS = [
 ];
 export const BROADSIDE_POLL_INTERVAL_MS = 15_000;
 export const BROADSIDE_DEFAULT_POLL_BUDGET_MS = 25 * 60 * 1000;
+/**
+ * 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 const BROADSIDE_REASONING_BUDGET_FRACTION = 0.25;
+export 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 function defaultReasoningFor(maxTokens) {
+    return { max_tokens: Math.max(BROADSIDE_MIN_REASONING_TOKENS, Math.floor(maxTokens * BROADSIDE_REASONING_BUDGET_FRACTION)) };
+}
 /** Thrown when a confirm hook declines a run. Nothing was submitted. */
 export class BroadsideCancelledError extends Error {
     constructor(message = "Broad-Side submission cancelled. Nothing was submitted.") {
@@ -1136,7 +1164,7 @@ async function sumFileSizes(targetDir, files) {
     return total;
 }
 // ---------- request building ----------
-export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride) {
+export function buildBatchRequest(lens, info, slice, index, sliceCount, model = BROADSIDE_MODEL, maxTokensOverride, reasoningOverride) {
     const moduleTag = sanitizeId(slice.moduleName);
     const customId = sliceCount > 1 ? `${lens.id}-${moduleTag}-${index + 1}` : `${lens.id}-${moduleTag}`;
     return {
@@ -1149,6 +1177,9 @@ export function buildBatchRequest(lens, info, slice, index, sliceCount, model =
             ],
             response_format: { type: "json_schema", json_schema: SCHEMAS[lens.schemaName] },
             max_tokens: maxTokensOverride ?? lens.maxTokens,
+            // Always sent, never inherited: an absent field means the model's
+            // own default, and that default is what truncated the JSON.
+            reasoning: reasoningOverride ?? lens.reasoning ?? defaultReasoningFor(maxTokensOverride ?? lens.maxTokens),
         },
     };
 }
@@ -1297,6 +1328,24 @@ export async function persistBroadsideRun(broadsideDir, run) {
             state.runs[index] = run;
     });
 }
+/** Read a `reasoning:` block from config.yaml, ignoring anything malformed. */
+function parseReasoningConfig(raw) {
+    if (raw === false)
+        return { enabled: false };
+    if (raw === true)
+        return { enabled: true };
+    if (!raw || typeof raw !== "object")
+        return null;
+    const value = raw;
+    const out = {};
+    if (typeof value.enabled === "boolean")
+        out.enabled = value.enabled;
+    if (value.effort === "minimal" || value.effort === "low" || value.effort === "medium" || value.effort === "high")
+        out.effort = value.effort;
+    if (typeof value.max_tokens === "number" && value.max_tokens > 0)
+        out.max_tokens = value.max_tokens;
+    return Object.keys(out).length > 0 ? out : null;
+}
 export async function loadBroadsideConfig(broadsideDir) {
     const configPath = join(broadsideDir, BROADSIDE_CONFIG_FILE);
     let raw = {};
@@ -1337,6 +1386,10 @@ export async function loadBroadsideConfig(broadsideDir) {
             ? { inputPerM: inputOverride, outputPerM: outputOverride }
             : null,
         lensModels,
+        // An escape hatch, not a knob to reach for: a model whose reasoning is
+        // worth paying for needs its lens maxTokens raised to cover both the
+        // thinking and the answer, or the JSON truncates exactly as before.
+        reasoning: parseReasoningConfig(raw.reasoning),
         incremental: flag("incremental", false),
         retryTruncated: flag("retry_truncated", true),
         includeSynthesis: flag("include_synthesis", true),
@@ -1797,7 +1850,7 @@ export async function runBroadsideSubmit(cwd, apiKey, opts = {}) {
         const { lens, maxTokens, lensModel, lensOutputCap } = priced;
         const lensId = lens.id;
         const slices = slicesByLens.get(lensId) ?? [];
-        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens));
+        const requests = slices.map((sl, i) => buildBatchRequest(lens, info, sl, i, slices.length, lensModel, maxTokens, config.reasoning ?? undefined));
         for (const request of requests)
             requestsByCustomId[request.custom_id] = request;
         const entry = {

package/dist/extensions/codecarto/agent-rewriter.js

@@ -11,6 +11,7 @@ import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { closeoutFileName, pathExists } from "../../core/index.js";
+import { createChildModelRuntime } from "./child-model-runtime.js";
 /** Closeout content over this many bytes is truncated before being passed to
  *  the rewriter. Keeps the orchestrator-side cost predictable. */
 const CLOSEOUT_BYTE_BUDGET = 8000;
@@ -143,6 +144,7 @@ async function runRewriterOnce(ctx, prompt) {
     const { session } = await createAgentSession({
         cwd,
         agentDir,
+        modelRuntime: await createChildModelRuntime(ctx, agentDir),
         sessionManager: SessionManager.inMemory(cwd),
         settingsManager: SettingsManager.create(cwd, agentDir),
         model: ctx.model,

package/dist/extensions/codecarto/agent-runner.js

@@ -13,6 +13,7 @@ import { access } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { canonicalPath, isWithinPath } from "../../core/index.js";
+import { createChildModelRuntime } from "./child-model-runtime.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
 // Tools available to the phase sub-agent. Matches the codecarto interception
 // allowlist (SAFE_TOOL_NAMES in extensions/codecarto/index.ts), minus bash.
@@ -104,6 +105,7 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     const { session } = await createAgentSession({
         cwd,
         agentDir,
+        modelRuntime: await createChildModelRuntime(ctx, agentDir),
         sessionManager,
         settingsManager: SettingsManager.create(cwd, agentDir),
         model: ctx.model,

package/dist/extensions/codecarto/child-model-runtime.d.ts

@@ -0,0 +1,2 @@
+import { type ExtensionContext, ModelRuntime } from "@earendil-works/pi-coding-agent";
+export declare function createChildModelRuntime(ctx: ExtensionContext, agentDir: string): Promise<ModelRuntime>;

package/dist/extensions/codecarto/child-model-runtime.js

@@ -0,0 +1,44 @@
+// Model runtime for codecarto's child sessions (phase sub-agents, the
+// next-phase rewriter, the dashboard narrator).
+//
+// All three child sessions load with `noExtensions: true` so a globally
+// installed codecarto doesn't register its commands and tool guards twice
+// inside its own sub-agent. That isolation has a side effect: providers
+// registered by *other* global extensions via `pi.registerProvider()` — an
+// Ollama Cloud bridge, a company gateway, any custom `streamSimple` provider —
+// are registered onto the parent's ModelRuntime by the resource loader that
+// loaded them. A child that builds a fresh ModelRuntime never sees them, so
+// the parent's selected model resolves to a provider the child does not know,
+// and the session throws `No API key found for <provider>` before its first
+// turn.
+//
+// Carrying the parent's registered provider configs across keeps the child on
+// the same model the user picked without reloading (and re-registering) the
+// extensions themselves.
+import { join } from "node:path";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+export async function createChildModelRuntime(ctx, agentDir) {
+    const runtime = await ModelRuntime.create({
+        authPath: join(agentDir, "auth.json"),
+        modelsPath: join(agentDir, "models.json"),
+    });
+    for (const providerId of ctx.modelRegistry.getRegisteredProviderIds()) {
+        const config = ctx.modelRegistry.getRegisteredProviderConfig(providerId);
+        if (!config)
+            continue;
+        try {
+            runtime.registerProvider(providerId, config);
+        }
+        catch {
+            // A provider the child can't accept is not worth failing the phase
+            // over: the child either doesn't need it (the user's model comes
+            // from a different provider) or fails later with the provider-
+            // specific error, which is more useful than one thrown here.
+        }
+    }
+    // Recompose the provider table so the newly registered providers land in
+    // the availability snapshot that `hasConfiguredAuth` reads. Offline: the
+    // parent already paid for any network catalog refresh.
+    await runtime.refresh({ allowNetwork: false });
+    return runtime;
+}

package/dist/extensions/codecarto/dashboard-narrator.js

@@ -14,6 +14,7 @@ import { readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { computeTotals, NARRATION_CACHE_RELATIVE_PATH, loadUsage, pathExists, stringifySimpleYaml, } from "../../core/index.js";
+import { createChildModelRuntime } from "./child-model-runtime.js";
 // Per-closeout byte budget when stuffing the narrator's input. Three
 // closeouts × 4 KB each ≈ 12 KB of prompt context, which is well under any
 // reasonable model's input window.
@@ -153,6 +154,7 @@ async function runNarratorOnce(ctx, prompt) {
     const { session } = await createAgentSession({
         cwd,
         agentDir,
+        modelRuntime: await createChildModelRuntime(ctx, agentDir),
         sessionManager: SessionManager.inMemory(cwd),
         settingsManager: SettingsManager.create(cwd, agentDir),
         model: ctx.model,

package/dist/extensions/codecarto/index.js

@@ -785,7 +785,25 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx.cwd, validation);
+            // Completion refuses for reasons the framework words carefully — a
+            // missing phase handoff, a carry-forward without `derives_from`, a
+            // closure lacking runtime evidence. Those messages are the whole
+            // point of the refusal, and this was the one call in this file that
+            // let them escape as a rejection instead of showing them. The
+            // irony was sharp: /codecarto-next catches this same throw and tells
+            // the user to run /codecarto-complete manually, which then threw.
+            let completion;
+            try {
+                completion = await autoCompletePhase(ctx.cwd, validation);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                lastFeedbackLines = [`Completion refused: ${message}`];
+                setUiState(ctx, currentState, lastFeedbackLines);
+                ctx.ui.notify(message, "error");
+                return;
+            }
+            const { updatedState, closeoutNotice, warnings } = completion;
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "mcpName": "io.github.HuginnIndustries/codecartographer",
   "description": "Turn an unfamiliar codebase into a validated reimplementation spec, then synthesize confirmed specs and a product vision into a traceable plan.",
   "type": "module",