codecartographer-pi 0.16.0 → 0.17.1

package/dist/extensions/codecarto/index.js

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { autoCompletePhase, buildAutoSummary, isPhaseRunning, runAuto, runSinglePhase } from "./auto-runner.js";
@@ -6,12 +6,16 @@ import { disposeAgentsWidget } from "./agent-widget.js";
 import { parseDashboardFlags } from "./dashboard-flags.js";
 import { narrateDashboard } from "./dashboard-narrator.js";
 import { writeDashboard } from "./dashboard-writer.js";
+import { parseBroadsideFlags, KNOWN_BROADSIDE_TOKENS } from "./broadside-flags.js";
 import { parseNextFlags } from "./next-flags.js";
 import { phaseCompactionExtension } from "./phase-compaction.js";
-import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, computePerPhaseTotals, computeTotals, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildValidationSummary, canonicalPath, copyPackagedWorkspace, computePerPhaseTotals, computeTotals, ConfidentialityMismatchError, createEmptyStatus, DEFAULT_PIPELINE_PATH, describeScaffoldStaleness, deriveSlug, discoverLibrary, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPathResolved, BROADSIDE_LENS_IDS, BROADSIDE_SKILL_NAME, BroadsideCancelledError, broadsideDirFor, collectResultText, estimateSubmitText, getLens, listBatchModels, listSkillNames, loadBroadsideConfig, modelsText, runBroadsideCollect, runBroadsideStatus, runBroadsideSubmit, statusText, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, packagedWorkspaceDir, pathExists, PACKAGE_VERSION, readBroadsideSkill, PhasePreflightError, PIPELINE_ALIASES, publishEntry, resolvePhase, resolvePipelineChoice, runPhasePreflight, seedOrchestratorFiles, stringifySimpleYaml, switchPipeline, validatePhaseOutput, writeLibraryConfig, } from "../../core/index.js";
 import { initLibrary } from "../../core/library.js";
 import { resolveUserConfigPath } from "../../core/orchestrator-config.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
+// Broad-Side gets its own widget id: a scout run is legal on a repository with
+// no workspace, where the phase widget has nothing to render.
+const BROADSIDE_WIDGET_ID = "codecarto-broadside";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
 function derivePublishHeadline(spec, cwd) {
@@ -92,6 +96,47 @@ function setUiState(ctx, state, extraLines = []) {
     ctx.ui.setStatus(STATUS_LINE_ID, `${theme.fg("accent", "CC")} ${theme.fg("dim", currentPhase)}`);
     ctx.ui.setWidget(STATUS_WIDGET_ID, buildStatusLines(state, extraLines));
 }
+/**
+ * Resolve the OpenRouter key for a Broad-Side run. Deliberately no slash-command
+ * parameter: a key typed as a command argument lands in the session transcript.
+ */
+function resolveBroadsideKey(configuredKey) {
+    const fromEnv = process.env.OPENROUTER_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return configuredKey.trim() || null;
+}
+/** The spend decision, rendered for a human about to approve it. */
+function describeBroadsideEstimate(estimate) {
+    const lines = [
+        `Model: ${estimate.model}${estimate.mixedModels ? " (some lenses overridden — see below)" : ""} (pricing: ${estimate.pricing.source})`,
+        `Rates: $${estimate.pricing.inputPerM.toFixed(4)}/M in · $${estimate.pricing.outputPerM.toFixed(4)}/M out`,
+        "",
+        "Per lens:",
+        ...estimate.lenses.map(({ name, slices, cost, model }) => {
+            // Naming the model only when it differs keeps the common case quiet
+            // and makes a mixed-model run impossible to approve without noticing.
+            const override = estimate.mixedModels && model !== estimate.model ? ` on ${model}` : "";
+            return `  ${name}: ${slices} slice${slices === 1 ? "" : "s"} — ~$${cost.toFixed(4)}${override}`;
+        }),
+        "",
+        `Estimated total: ~$${estimate.totalCost.toFixed(4)} ` +
+            `(~${Math.round(estimate.inputTokens / 1000)}k in, ~${Math.round(estimate.outputTokens / 1000)}k out)`,
+    ];
+    if (estimate.maxCost > 0) {
+        lines.push(estimate.exceedsLimit
+            ? `This EXCEEDS the configured max_cost of $${estimate.maxCost.toFixed(2)}. Approving here overrides it for this run.`
+            : `Within the configured max_cost of $${estimate.maxCost.toFixed(2)}.`);
+    }
+    if (estimate.baseHead) {
+        lines.push(`Incremental: only modules changed since ${estimate.baseHead.slice(0, 8)} are included.`);
+    }
+    else if (estimate.sourceDirty) {
+        lines.push("Incremental was requested but the tree is dirty — this is a full scan.");
+    }
+    lines.push("", "The estimate is a pre-flight prediction from file sizes; OpenRouter bills actual usage.");
+    return lines.join("\n");
+}
 export default function codeCartographerExtension(pi) {
     phaseCompactionExtension(pi);
     let lastFeedbackLines = [];
@@ -268,7 +313,7 @@ export default function codeCartographerExtension(pi) {
             }
             if (!(await pathExists(targetWorkspaceDir))) {
                 await mkdir(ctx.cwd, { recursive: true });
-                await cp(sourceWorkspaceDir, targetWorkspaceDir, { recursive: true });
+                await copyPackagedWorkspace(targetWorkspaceDir);
             }
             const rawStatusPath = join(targetWorkspaceDir, "workflow", "status.yaml");
             const rawStatus = (await loadYamlFile(rawStatusPath)) ?? {};
@@ -573,7 +618,7 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Cannot complete ${validation.phaseId}: ${validation.overall}`, "error");
                 return;
             }
-            const { updatedState, closeoutNotice } = await autoCompletePhase(ctx, validation);
+            const { updatedState, closeoutNotice, warnings } = await autoCompletePhase(ctx, validation);
             lastFeedbackLines = [
                 `Completed phase: ${validation.phaseId}`,
                 `Validation: ${validation.overall}`,
@@ -581,10 +626,15 @@ export default function codeCartographerExtension(pi) {
             ];
             if (closeoutNotice)
                 lastFeedbackLines.push(closeoutNotice);
+            const notes = [...(validation.warnings ?? []), ...warnings];
+            for (const note of notes)
+                lastFeedbackLines.push(`NOTE: ${note} Non-gating.`);
             setUiState(ctx, updatedState, lastFeedbackLines);
-            ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" ? "warning" : "info");
+            ctx.ui.notify(`Marked ${validation.phaseId} complete`, validation.overall === "PASS WITH GAPS" || notes.length > 0 ? "warning" : "info");
             if (closeoutNotice)
                 ctx.ui.notify(closeoutNotice, "info");
+            for (const note of notes)
+                ctx.ui.notify(note, "warning");
         },
     });
     pi.registerCommand("codecarto-skill", {
@@ -597,6 +647,30 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify(`Usage: /codecarto-skill <name>${hint}`, "warning");
                 return;
             }
+            // Broad-Side is a reading guide for batch reconnaissance output, not a
+            // post-pipeline skill: it is read before or during the pipeline and works
+            // on a repository with scout state and no workspace. Same exemption the
+            // MCP surface makes in handleSkill.
+            if (skillName === BROADSIDE_SKILL_NAME) {
+                const skill = await readBroadsideSkill(ctx.cwd).catch(() => null);
+                if (!skill) {
+                    ctx.ui.notify("Broad-Side reading guide not found. Reinstall codecartographer-pi.", "error");
+                    return;
+                }
+                const message = [
+                    "Read the Broad-Side reading guide below and apply it to the batch reconnaissance results in .codecarto/broadside/.",
+                    "",
+                    skill.content,
+                ].join("\n");
+                if (ctx.isIdle()) {
+                    pi.sendUserMessage(message);
+                }
+                else {
+                    pi.sendUserMessage(message, { deliverAs: "followUp" });
+                }
+                ctx.ui.notify("Queued the Broad-Side reading guide", "info");
+                return;
+            }
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
@@ -609,7 +683,7 @@ export default function codeCartographerExtension(pi) {
             if (!(await pathExists(skillFile))) {
                 const available = await listSkillNames(state.workspaceDir);
                 const hint = available.length > 0 ? ` (available: ${available.join(", ")})` : " (no skills installed)";
-                ctx.ui.notify(`Unknown skill: ${skillName}${hint}`, "error");
+                ctx.ui.notify(`Unknown skill: ${skillName}${hint}. The Broad-Side reading guide is served as \`${BROADSIDE_SKILL_NAME}\` and is not pipeline-gated.`, "error");
                 return;
             }
             const prompt = await buildSkillPrompt(state, skillName);
@@ -624,6 +698,167 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-broadside", {
+        description: "Batch reconnaissance (Broad-Side): /codecarto-broadside [submit|collect|status|models] [lenses…] [flags]",
+        getArgumentCompletions: (prefix) => {
+            const items = KNOWN_BROADSIDE_TOKENS
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const flags = parseBroadsideFlags(args);
+            if (flags.unknown.length > 0) {
+                ctx.ui.notify(`Unknown /codecarto-broadside argument: ${flags.unknown.join(" ")}. ` +
+                    `Actions: submit, collect, status, models. Lenses: ${BROADSIDE_LENS_IDS.join(", ")}.`, "error");
+                return;
+            }
+            if (flags.error) {
+                ctx.ui.notify(flags.error, "error");
+                return;
+            }
+            // Broad-Side runs on any git repository, with or without a workspace —
+            // so this command never goes through ensureWorkspaceState.
+            const broadsideDir = broadsideDirFor(ctx.cwd);
+            const config = await loadBroadsideConfig(broadsideDir);
+            const finish = (lines, notice, level = "info") => {
+                lastFeedbackLines = lines;
+                if (codecartoModeActive) {
+                    // A workspace session already has a widget; fold the result into it.
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    void refreshWorkspaceUi(ctx, lines);
+                }
+                else if (ctx.hasUI) {
+                    // Scout-only repository: the Broad-Side widget is the only place
+                    // the result can live, so it holds it instead of being cleared.
+                    ctx.ui.setWidget(BROADSIDE_WIDGET_ID, ["Broad-Side", ...lines]);
+                }
+                ctx.ui.notify(notice, level);
+            };
+            if (flags.action === "status") {
+                const { state } = await runBroadsideStatus(ctx.cwd);
+                const runs = state.runs.length;
+                finish(statusText(state).split("\n"), runs > 0 ? `Broad-Side: ${runs} recorded run${runs === 1 ? "" : "s"}` : "Broad-Side: no runs recorded yet");
+                return;
+            }
+            const apiKey = resolveBroadsideKey(config.apiKey);
+            if (!apiKey) {
+                ctx.ui.notify("No OpenRouter API key. Set OPENROUTER_API_KEY in the environment, or add api_key to " +
+                    ".codecarto/broadside/config.yaml. (A slash command takes no key: it would land in the transcript.)", "error");
+                return;
+            }
+            if (flags.action === "models") {
+                ctx.ui.notify("Fetching the OpenRouter batch-model catalog…", "info");
+                try {
+                    const { entries, benchmarks } = await listBatchModels(broadsideDir, config, apiKey, {
+                        includeBenchmarks: flags.benchmarks,
+                    });
+                    finish(modelsText(entries, { benchmarks, defaultModel: config.model }).split("\n"), `Broad-Side: ${entries.length} batch model${entries.length === 1 ? "" : "s"} listed`);
+                }
+                catch (error) {
+                    ctx.ui.notify(`Model catalog lookup failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                }
+                return;
+            }
+            // Live per-lens progress. Poll callbacks fire often, so they render
+            // into a widget rather than a notification stream.
+            const progress = new Map();
+            const renderProgress = (heading) => {
+                if (!ctx.hasUI)
+                    return;
+                ctx.ui.setWidget(BROADSIDE_WIDGET_ID, [
+                    "Broad-Side",
+                    heading,
+                    ...[...progress.entries()].map(([lensId, line]) => `  ${lensId}: ${line}`),
+                ]);
+            };
+            const onStatus = (lensId, status, counts) => {
+                progress.set(lensId, `${status} (${counts.completed ?? 0}/${counts.total ?? "?"})`);
+                renderProgress("Polling batches…");
+            };
+            const waitSeconds = flags.waitSeconds ?? config.waitSeconds;
+            const waitMs = waitSeconds > 0 ? waitSeconds * 1000 : undefined;
+            const includeSynthesis = flags.includeSynthesis ?? config.includeSynthesis;
+            const includeTriage = flags.includeTriage ?? config.includeTriage;
+            const retryTruncated = flags.retryTruncated ?? config.retryTruncated;
+            if (flags.action === "submit") {
+                const lenses = flags.lenses.length > 0 ? flags.lenses : config.defaultLenses;
+                renderProgress("Slicing the repository and pricing the run…");
+                let submit;
+                try {
+                    submit = await runBroadsideSubmit(ctx.cwd, apiKey, {
+                        lenses,
+                        model: config.model,
+                        maxCost: flags.maxCost ?? config.maxCost,
+                        // `??`, not `||`: --no-incremental parses to false and must beat a
+                        // config-set true, exactly as MCP's `incremental: false` does (#163).
+                        incremental: flags.incremental ?? config.incremental,
+                        // Pi can ask, so it asks instead of refusing over max_cost the
+                        // way MCP has to. An approval here IS the force flag.
+                        confirm: (estimate) => ctx.ui.confirm(`Broad-Side will spend about $${estimate.totalCost.toFixed(4)}`, describeBroadsideEstimate(estimate)),
+                    });
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    if (error instanceof BroadsideCancelledError) {
+                        ctx.ui.notify("Broad-Side cancelled. Nothing was submitted.", "info");
+                        return;
+                    }
+                    ctx.ui.notify(`Broad-Side submit failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                    return;
+                }
+                const lines = estimateSubmitText(submit, lenses.map(getLens)).split("\n");
+                if (!waitMs) {
+                    lines.push("", "Batches are in flight. Run /codecarto-broadside collect when they finish.");
+                    finish(lines, `Broad-Side submitted: run ${submit.runId} (~$${submit.estimatedTotalCost.toFixed(4)})`);
+                    return;
+                }
+                ctx.ui.notify(`Broad-Side submitted run ${submit.runId}; polling for up to ${waitSeconds}s…`, "info");
+                try {
+                    const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
+                        waitMs,
+                        includeSynthesis,
+                        includeTriage,
+                        retryTruncated,
+                        onStatus,
+                    });
+                    finish([...lines, "", ...collectResultText(collect).split("\n")], `Broad-Side ${collect.status}: run ${collect.runId}`);
+                }
+                catch (error) {
+                    if (ctx.hasUI)
+                        ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                    // The batches are submitted and paid for either way — say so, so
+                    // nobody re-submits a run that is already in flight.
+                    ctx.ui.notify(`Broad-Side submitted run ${submit.runId}, but collect failed: ` +
+                        `${error instanceof Error ? error.message : String(error)}. Retry with /codecarto-broadside collect.`, "error");
+                }
+                return;
+            }
+            // action === "collect"
+            renderProgress("Polling batches…");
+            try {
+                const collect = await runBroadsideCollect(ctx.cwd, apiKey, {
+                    waitMs,
+                    includeSynthesis,
+                    includeTriage,
+                    retryTruncated,
+                    onStatus,
+                });
+                const lines = collectResultText(collect).split("\n");
+                const done = collect.status === "completed";
+                if (!done)
+                    lines.push("", "Still in flight. Run /codecarto-broadside collect again to resume.");
+                finish(lines, `Broad-Side ${collect.status}: ${collect.resultCount} result${collect.resultCount === 1 ? "" : "s"} saved`, done ? "info" : "warning");
+            }
+            catch (error) {
+                if (ctx.hasUI)
+                    ctx.ui.setWidget(BROADSIDE_WIDGET_ID, undefined);
+                ctx.ui.notify(`Broad-Side collect failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+            }
+        },
+    });
     pi.registerCommand("codecarto-publish", {
         description: "Publish the completed reimplementation spec to the configured CodeCartographer library",
         handler: async (_args, ctx) => {
@@ -667,19 +902,36 @@ export default function codeCartographerExtension(pi) {
             ].join("\n");
             if (config.library.publish_confirm && !(await ctx.ui.confirm("Publish reimplementation spec", preview)))
                 return;
+            const input = {
+                slug,
+                namespace,
+                source_repo: ctx.cwd,
+                analyzed_at: new Date().toISOString(),
+                pipeline: state.status.pipeline,
+                codecarto_version: PACKAGE_VERSION,
+                headline,
+                tags: [],
+                capabilities: [],
+                generation: piGeneration(ctx),
+            };
             try {
-                const result = await publishEntry(config.library.path, spec, {
-                    slug,
-                    namespace,
-                    source_repo: ctx.cwd,
-                    analyzed_at: new Date().toISOString(),
-                    pipeline: state.status.pipeline,
-                    codecarto_version: PACKAGE_VERSION,
-                    headline,
-                    tags: [],
-                    capabilities: [],
-                    generation: piGeneration(ctx),
-                });
+                let result;
+                try {
+                    result = await publishEntry(config.library.path, spec, input);
+                }
+                catch (error) {
+                    if (!(error instanceof ConfidentialityMismatchError))
+                        throw error;
+                    // Nothing was written. Pi declares no confidentiality, so the entry
+                    // sits at the internal default; whether it may go into a wider
+                    // library is the user's call, and a yes is the override.
+                    const publishAnyway = await ctx.ui.confirm("Confidentiality mismatch — publish anyway?", `This spec's confidentiality is "${error.entryConfidentiality}" (CodeCartographer's default; /codecarto-publish declares none), but the library "${marker.name}" has visibility "${error.libraryVisibility}". Publishing would expose it to everyone that library reaches. Publish anyway?`);
+                    if (!publishAnyway) {
+                        ctx.ui.notify("Publish cancelled. Nothing was written.", "info");
+                        return;
+                    }
+                    result = await publishEntry(config.library.path, spec, input, { allowConfidentialityMismatch: true });
+                }
                 lastFeedbackLines = [`Published ${result.namespace ? `${result.namespace}/` : ""}${result.slug} v${result.version}`, result.isNewVersion ? "New content version." : "Metadata-only update (content unchanged)."];
                 await writeDashboard(ctx.cwd, PACKAGE_VERSION);
                 await refreshWorkspaceUi(ctx, lastFeedbackLines);

package/dist/extensions/codecarto/phase-compaction.js

@@ -81,6 +81,10 @@ export function phaseCompactionExtension(pi) {
             return undefined;
         try {
             const state = await getWorkspaceState(ctx.cwd);
+            // No workspace under this cwd: nothing phase-aware to add, so the host
+            // default applies — not a failure worth a warning (#134).
+            if (!state)
+                return undefined;
             const phase = state.pipeline.phases.find((candidate) => candidate.id === phaseId);
             const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
             if (!auth.ok || !auth.apiKey)

package/dist/mcp-server/server.d.ts

@@ -230,6 +230,28 @@ export declare function handleAmend(args: {
         text: string;
     };
 }>;
+export declare function handleBroadside(args: {
+    cwd: string;
+    action: "submit" | "collect" | "status" | "models";
+    lenses?: string[];
+    api_key?: string;
+    wait_seconds?: number;
+    include_synthesis?: boolean;
+    include_triage?: boolean;
+    retry_truncated?: boolean;
+    max_cost?: number;
+    force?: boolean;
+    include_benchmarks?: boolean;
+    incremental?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        text: string;
+    };
+}>;
 export declare function handleGuide(args: {
     topic?: string;
 }): Promise<{