codecartographer-pi 0.6.1 → 0.9.0

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

@@ -0,0 +1,403 @@
+// End-to-end auto runner for /codecarto-next --auto plus the two helpers
+// shared between the one-shot path and the auto loop.
+//
+// runSinglePhase encapsulates everything the historical inline /codecarto-next
+// did between getNextEligiblePhase and the .finally setTimeout. The one-shot
+// handler still consumes it as a fire-and-forget Promise (void runSinglePhase
+// keeps the TUI responsive while the phase runs). The auto loop awaits the
+// same Promise, validates the output, and decides whether to advance.
+//
+// autoCompletePhase mirrors /codecarto-complete's updateStatusAtomically
+// block — the gap → open_questions extraction, owner-notes append, THREAD_LOG
+// write, closeout-stub creation, dashboard regen. UI notifications stay in
+// the calling handler.
+import { runPhase } from "./agent-runner.js";
+import { clearPhase, finishPhase, getPhaseActivity, startPhase } from "./agent-state.js";
+import { buildSteeringMessage, rewritePhasePrompt } from "./agent-rewriter.js";
+import { buildPhaseSummary } from "./agent-summary.js";
+import { getAgentsWidget } from "./agent-widget.js";
+import { writeDashboard } from "./dashboard-writer.js";
+import { appendUsageRun, buildPhasePrompt, buildThreadLogEntry, buildValidationSummary, closeoutFileName, dateOnly, ensureCloseoutStub, formatMillis, formatTokenCount, getNextEligiblePhase, getWorkspaceState, loadCodecartoConfig, normalizeStatus, PACKAGE_VERSION, resolvePhase, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+/**
+ * Run one phase end to end: optional LLM-steered rewrite, spawn the sub-agent,
+ * wait for it, then emit the side effects the historical /codecarto-next chain
+ * fired (notify, phase-summary sendMessage, recordUsage, writeDashboard). The
+ * .finally linger-timeout for clearPhase fires here so both callers (one-shot
+ * + auto loop) get the same lifecycle.
+ *
+ * Pre-conditions: caller verified the phase isn't already running (via
+ * getPhaseActivity) and attached the agents widget if it wanted live progress.
+ */
+export async function runSinglePhase(ctx, pi, state, phase, options) {
+    let prompt = await buildPhasePrompt(state, phase, false, { auto: options.auto === true });
+    if (options.llmSteerEnabled) {
+        if (ctx.hasUI)
+            ctx.ui.notify(`Customizing ${phase.id} prompt via LLM rewriter…`, "info");
+        const rewrite = await rewritePhasePrompt({ ctx, state, originalPrompt: prompt, nextPhaseId: phase.id });
+        if (rewrite.used) {
+            prompt = rewrite.prompt;
+            if (ctx.hasUI)
+                ctx.ui.notify(`LLM rewriter customized ${phase.id} seed prompt.`, "info");
+            pi.sendMessage({
+                customType: "codecarto-steering",
+                content: buildSteeringMessage({
+                    nextPhaseId: phase.id,
+                    prevPhaseId: rewrite.prevPhaseId,
+                    rewrittenPrompt: rewrite.prompt,
+                }),
+                display: true,
+            });
+        }
+        else if (ctx.hasUI) {
+            ctx.ui.notify(`LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
+        }
+    }
+    const activity = startPhase(phase.id);
+    if (ctx.hasUI) {
+        ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent running)`, "info");
+        getAgentsWidget().attach(ctx.ui);
+    }
+    try {
+        const result = await runPhase(ctx, prompt, {
+            onSessionCreated: (session) => { activity.session = session; },
+            onToolStart: (id, name) => { activity.activeTools.set(id, name); activity.toolUses++; },
+            onToolEnd: (id) => { activity.activeTools.delete(id); },
+            onTextDelta: (_delta, fullText) => { activity.responseText = fullText; },
+            onTurnEnd: (turnCount) => { activity.turnCount = turnCount; },
+            onMessageEnd: (usage) => {
+                activity.lifetimeUsage.input += usage.input;
+                activity.lifetimeUsage.output += usage.output;
+                activity.lifetimeUsage.cacheWrite += usage.cacheWrite;
+            },
+        }, { sessionName: `CodeCartographer phase: ${phase.id}` }, options.signal);
+        const status = result.aborted ? "aborted" : "completed";
+        finishPhase(phase.id, { status });
+        if (ctx.hasUI) {
+            ctx.ui.notify(result.aborted
+                ? `Phase ${phase.id} aborted.`
+                : `Phase ${phase.id} sub-agent finished (${result.toolUses} tool uses, ${result.turnCount} turns).`, result.aborted ? "warning" : "info");
+        }
+        pi.sendMessage({
+            customType: "codecarto-phase-summary",
+            content: buildPhaseSummary({
+                phaseId: phase.id,
+                status: result.aborted ? "aborted" : "completed",
+                turnCount: activity.turnCount,
+                toolUses: activity.toolUses,
+                tokens: activity.lifetimeUsage,
+                durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
+                responseText: result.responseText,
+                sessionFile: result.sessionFile,
+            }),
+            display: true,
+        });
+        void recordUsage(state.workspaceDir, phase.id, status, activity, result.sessionFile);
+        void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+        return {
+            status: result.aborted ? "aborted" : "completed",
+            activity,
+            responseText: result.responseText,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        finishPhase(phase.id, { status: "error", error: message });
+        if (ctx.hasUI) {
+            ctx.ui.notify(`Phase ${phase.id} sub-agent failed: ${message}`, "error");
+        }
+        pi.sendMessage({
+            customType: "codecarto-phase-summary",
+            content: buildPhaseSummary({
+                phaseId: phase.id,
+                status: "error",
+                turnCount: activity.turnCount,
+                toolUses: activity.toolUses,
+                tokens: activity.lifetimeUsage,
+                durationMs: (activity.completedAt ?? Date.now()) - activity.startedAt,
+                responseText: "",
+                error: message,
+            }),
+            display: true,
+        });
+        void recordUsage(state.workspaceDir, phase.id, "error", activity);
+        void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+        return { status: "error", activity, error: message };
+    }
+    finally {
+        // Linger 30s so /codecarto-status can show that the phase ran.
+        setTimeout(() => clearPhase(phase.id), 30_000);
+    }
+}
+/**
+ * Re-entry guard: returns true if the phase is already running from a prior
+ * spawn (manual or auto). Callers (both /codecarto-next paths) should reject
+ * before invoking runSinglePhase.
+ */
+export function isPhaseRunning(phaseId) {
+    const existing = getPhaseActivity(phaseId);
+    return existing?.status === "running";
+}
+export async function autoCompletePhase(ctx, validation) {
+    const completionTimestamp = new Date().toISOString();
+    const updatedState = await updateStatusAtomically(ctx.cwd, (lockedState) => {
+        const phase = resolvePhase(lockedState, validation.phaseId);
+        if (!phase?.primary_output) {
+            throw new Error(`Phase ${validation.phaseId} is missing primary_output.`);
+        }
+        const nextStatus = normalizeStatus(lockedState.status, lockedState.pipeline, lockedState.status.pipeline, lockedState.cwd);
+        const existingPhase = nextStatus.phases[validation.phaseId] ?? {
+            status: "pending",
+            owner_notes: [],
+            outputs_present: [],
+            open_questions: [],
+            carry_forward: [],
+        };
+        const gapEntries = validation.rows
+            .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
+            .map((row) => ({
+            kind: "needs-maintainer-decision",
+            description: row.criterion || "Partial validation gap",
+            deferred_reason: row.evidence || "Marked PARTIAL by validation",
+        }));
+        const mergedOpenQuestions = [...existingPhase.open_questions];
+        for (const candidate of gapEntries) {
+            const dupe = mergedOpenQuestions.some((entry) => entry.description === candidate.description && entry.deferred_reason === candidate.deferred_reason);
+            if (!dupe)
+                mergedOpenQuestions.push(candidate);
+        }
+        nextStatus.phases[validation.phaseId] = {
+            status: "complete",
+            owner_notes: uniqueStrings([
+                ...existingPhase.owner_notes,
+                `Completed via /codecarto-complete on ${completionTimestamp}.`,
+                `Primary output: .codecarto/${validation.primaryOutput}`,
+                `Validation: ${validation.overall}`,
+            ]).slice(-3),
+            outputs_present: uniqueStrings([...existingPhase.outputs_present, validation.primaryOutput]),
+            open_questions: mergedOpenQuestions,
+            carry_forward: existingPhase.carry_forward ?? [],
+        };
+        nextStatus.last_updated = completionTimestamp;
+        const updatedWorkspaceState = {
+            ...lockedState,
+            status: nextStatus,
+        };
+        const nextEligible = getNextEligiblePhase(updatedWorkspaceState);
+        nextStatus.current_phase = nextEligible?.id ?? "complete";
+        nextStatus.next_actions = nextEligible
+            ? [`Begin ${nextEligible.id} phase by producing ${nextEligible.primary_output ?? `findings/${nextEligible.id}/`}`]
+            : ["All phases complete. Review findings, open questions, and downstream implementation notes."];
+        return {
+            state: { ...updatedWorkspaceState, status: nextStatus },
+            threadLogEntry: buildThreadLogEntry(validation.phaseId, validation, completionTimestamp),
+        };
+    });
+    let closeoutNotice;
+    try {
+        const created = await ensureCloseoutStub(updatedState.workspaceDir, validation.phaseId, completionTimestamp);
+        if (created) {
+            closeoutNotice = `Closeout stub: .codecarto/closeouts/${closeoutFileName(dateOnly(completionTimestamp), validation.phaseId)} (fill it in)`;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        closeoutNotice = `Closeout stub not created: ${message}`;
+    }
+    void writeDashboard(ctx.cwd, PACKAGE_VERSION);
+    return { updatedState, closeoutNotice };
+}
+export function decideAfterPhase(phaseStatus, phaseError, validation, strict) {
+    if (phaseStatus === "aborted")
+        return { action: "aborted" };
+    if (phaseStatus === "error") {
+        return { action: "stop", reason: phaseError ?? "Sub-agent errored.", error: phaseError };
+    }
+    if (!validation) {
+        return { action: "stop", reason: "Validation skipped (no result)." };
+    }
+    if (validation.overall === "FAIL" || validation.overall === "MISSING") {
+        return {
+            action: "stop",
+            reason: `Validation ${validation.overall} on ${validation.phaseId}.`,
+            validation: validation.overall,
+            validationSummary: buildValidationSummary(validation),
+        };
+    }
+    if (validation.overall === "PASS WITH GAPS" && strict) {
+        return {
+            action: "stop",
+            reason: `PASS WITH GAPS on ${validation.phaseId} (strict mode).`,
+            validation: validation.overall,
+            validationSummary: buildValidationSummary(validation),
+        };
+    }
+    return { action: "continue" };
+}
+export async function runAuto(ctx, pi, initialState, options) {
+    const startedAt = Date.now();
+    const phasesRun = [];
+    const totalTokens = { input: 0, output: 0, cacheWrite: 0 };
+    const totalPhases = initialState.pipeline.phase_order.length;
+    const config = await loadCodecartoConfig(initialState.workspaceDir);
+    const llmSteerEnabled = options.llmSteerOverride ?? config.orchestrator.llm_steer_next_phase;
+    let state = initialState;
+    while (true) {
+        if (options.signal?.aborted) {
+            return finish({
+                outcome: "aborted",
+                reason: "User aborted the auto run.",
+            });
+        }
+        const phase = getNextEligiblePhase(state);
+        if (!phase) {
+            return finish({
+                outcome: "complete",
+                reason: "Pipeline complete.",
+            });
+        }
+        if (isPhaseRunning(phase.id)) {
+            return finish({
+                outcome: "stopped",
+                reason: `Phase ${phase.id} is already running from a prior invocation.`,
+                stoppedAt: { phaseId: phase.id },
+            });
+        }
+        const phaseResult = await runSinglePhase(ctx, pi, state, phase, {
+            llmSteerEnabled,
+            signal: options.signal,
+            auto: true,
+        });
+        // Accumulate tokens whether the phase succeeded, was aborted, or errored.
+        totalTokens.input += phaseResult.activity.lifetimeUsage.input;
+        totalTokens.output += phaseResult.activity.lifetimeUsage.output;
+        totalTokens.cacheWrite += phaseResult.activity.lifetimeUsage.cacheWrite;
+        // Validate only when the phase actually completed. Aborts and errors
+        // short-circuit; decideAfterPhase handles all three outcomes.
+        let validation = null;
+        if (phaseResult.status === "completed") {
+            // State must be refreshed because the sub-agent may have written
+            // findings to disk that the validator reads.
+            const stateForValidation = (await getWorkspaceState(ctx.cwd)) ?? state;
+            validation = await validatePhaseOutput(stateForValidation, phase.id);
+        }
+        const decision = decideAfterPhase(phaseResult.status, phaseResult.error, validation, options.strict);
+        if (decision.action === "aborted") {
+            return finish({
+                outcome: "aborted",
+                reason: `Aborted during ${phase.id}.`,
+                stoppedAt: { phaseId: phase.id },
+            });
+        }
+        if (decision.action === "stop") {
+            return finish({
+                outcome: "stopped",
+                reason: decision.reason,
+                stoppedAt: { phaseId: phase.id, validation: decision.validation, error: decision.error },
+                validationSummary: decision.validationSummary,
+            });
+        }
+        // decision.action === "continue" → auto-complete and loop.
+        // validation is guaranteed non-null on the continue branch.
+        try {
+            const { updatedState } = await autoCompletePhase(ctx, validation);
+            state = updatedState;
+            phasesRun.push(phase.id);
+            options.onPhaseAdvanced?.(state);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return finish({
+                outcome: "stopped",
+                reason: `Auto-complete failed on ${phase.id}: ${message}`,
+                stoppedAt: { phaseId: phase.id, error: message },
+            });
+        }
+    }
+    function finish(partial) {
+        return {
+            ...partial,
+            phasesRun,
+            totalPhases,
+            startedAt,
+            endedAt: Date.now(),
+            totalTokens,
+        };
+    }
+}
+// ----------------------------------------------------------------------------
+// buildAutoSummary — the codecarto-auto-summary message body
+// ----------------------------------------------------------------------------
+export function buildAutoSummary(result, availableSkills = []) {
+    const totalTokens = result.totalTokens.input + result.totalTokens.output;
+    const wallTime = formatMillis(result.endedAt - result.startedAt);
+    const tokensStr = formatTokenCount(totalTokens);
+    const ranOf = `${result.phasesRun.length}/${result.totalPhases} phase${result.totalPhases === 1 ? "" : "s"}`;
+    const header = (() => {
+        switch (result.outcome) {
+            case "complete":
+                return `**Auto pipeline complete.**`;
+            case "stopped":
+                return `**Auto pipeline stopped at \`${result.stoppedAt?.phaseId ?? "?"}\`.**`;
+            case "aborted":
+                return `**Auto pipeline aborted${result.stoppedAt?.phaseId ? ` during \`${result.stoppedAt.phaseId}\`` : ""}.**`;
+        }
+    })();
+    const statsLine = `_⟳ ${ranOf} · ${tokensStr} tokens · ${wallTime}_`;
+    const lines = [header, "", statsLine];
+    if (result.outcome === "stopped" && result.validationSummary && result.validationSummary.length > 0) {
+        lines.push("", "```");
+        lines.push(...result.validationSummary);
+        lines.push("```");
+    }
+    if (result.outcome === "stopped" || result.outcome === "aborted") {
+        lines.push("", result.reason);
+        lines.push("", recoveryHint(result));
+    }
+    if (result.outcome === "complete") {
+        lines.push("", "Dashboard: `.codecarto/dashboard.html`");
+        if (availableSkills.length > 0) {
+            lines.push(`Next: try \`/codecarto-skill ${availableSkills[0]}\` (also available: ${availableSkills.slice(1).join(", ") || "none"}).`);
+        }
+    }
+    return lines.join("\n");
+}
+function recoveryHint(result) {
+    if (result.outcome === "aborted") {
+        return "Run `/codecarto-next --auto` to resume.";
+    }
+    const v = result.stoppedAt?.validation;
+    if (v === "FAIL" || v === "MISSING") {
+        return `Fix the phase output, then \`/codecarto-next --auto\` to resume.`;
+    }
+    if (v === "PASS WITH GAPS") {
+        return `Review gaps via \`/codecarto-validate\`, then \`/codecarto-complete ${result.stoppedAt?.phaseId ?? "<phase>"}\`, then \`/codecarto-next --auto\`.`;
+    }
+    if (result.stoppedAt?.error) {
+        return `Re-run \`/codecarto-next\` (single-step) on \`${result.stoppedAt.phaseId}\` to retry once the issue is resolved.`;
+    }
+    return "Run `/codecarto-next --auto` to resume.";
+}
+// ----------------------------------------------------------------------------
+// Helpers
+// ----------------------------------------------------------------------------
+async function recordUsage(workspaceDir, phaseId, status, activity, sessionFile) {
+    try {
+        await appendUsageRun(workspaceDir, {
+            timestamp: new Date().toISOString(),
+            phase: phaseId,
+            status,
+            turn_count: activity.turnCount,
+            tool_uses: activity.toolUses,
+            duration_ms: (activity.completedAt ?? Date.now()) - activity.startedAt,
+            tokens: {
+                input: activity.lifetimeUsage.input,
+                output: activity.lifetimeUsage.output,
+                cache_write: activity.lifetimeUsage.cacheWrite,
+            },
+            ...(sessionFile ? { session_file: sessionFile } : {}),
+        });
+    }
+    catch {
+        // Best-effort, matches the original recordUsage discipline.
+    }
+}

package/dist/extensions/codecarto/dashboard-flags.d.ts

@@ -0,0 +1,6 @@
+export interface DashboardFlags {
+    narrate: boolean;
+    unknown: string[];
+}
+export declare function parseDashboardFlags(args: string): DashboardFlags;
+export declare const KNOWN_DASHBOARD_FLAGS: readonly string[];

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

@@ -0,0 +1,17 @@
+// Flag parser for /codecarto-dashboard. The user invokes the slash command
+// with an optional "--narrate" flag to trigger the opt-in LLM narrator.
+// Same shape and discipline as next-flags.ts so future flags slot in
+// without refactoring.
+const KNOWN = new Set(["--narrate"]);
+export function parseDashboardFlags(args) {
+    const tokens = args.trim().split(/\s+/).filter((t) => t.length > 0);
+    const result = { narrate: false, unknown: [] };
+    for (const t of tokens) {
+        if (t === "--narrate")
+            result.narrate = true;
+        else
+            result.unknown.push(t);
+    }
+    return result;
+}
+export const KNOWN_DASHBOARD_FLAGS = [...KNOWN];

package/dist/extensions/codecarto/dashboard-narrator.d.ts

@@ -0,0 +1,8 @@
+import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type WorkspaceState } from "../../core/index.ts";
+export interface NarrateDashboardResult {
+    narration?: string;
+    used: boolean;
+    skipReason?: string;
+}
+export declare function narrateDashboard(ctx: ExtensionContext, state: WorkspaceState): Promise<NarrateDashboardResult>;

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

@@ -0,0 +1,182 @@
+// Optional LLM-narrated executive summary for the dashboard. Opt-in via
+// /codecarto-dashboard --narrate. Runs the orchestrator's model as a
+// one-shot in-memory AgentSession with no tools, reads recent closeouts +
+// status + usage totals, and produces a 200-400 word Markdown summary.
+//
+// The summary is cached to .codecarto/.dashboard-narration.local.md with a
+// YAML frontmatter recording when it was generated and the completed-phase
+// count at that time. Subsequent deterministic re-renders consult this
+// cache and surface a "<N> runs since" staleness note.
+//
+// Same one-shot pattern as agent-rewriter.ts:runRewriterOnce — different
+// system prompt, different output target. Never throws.
+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";
+// 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.
+const CLOSEOUT_BYTE_BUDGET = 4000;
+const MAX_CLOSEOUTS = 3;
+export async function narrateDashboard(ctx, state) {
+    const closeouts = await readRecentCloseouts(state.workspaceDir);
+    if (closeouts.length === 0) {
+        return { used: false, skipReason: "no closeouts to narrate from" };
+    }
+    const usage = await loadUsage(state.workspaceDir);
+    const prompt = buildNarratorPrompt({
+        projectName: state.status.project_name || "(unnamed project)",
+        pipeline: state.status.pipeline,
+        currentPhase: state.status.current_phase || "—",
+        completedCount: completedPhaseCount(state),
+        totalPhases: state.pipeline.phase_order.length,
+        usageSummary: summarizeUsage(usage),
+        closeouts,
+    });
+    let narration;
+    try {
+        narration = await runNarratorOnce(ctx, prompt);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { used: false, skipReason: `narrator session failed: ${message}` };
+    }
+    const trimmed = narration.trim();
+    if (!trimmed) {
+        return { used: false, skipReason: "narrator returned empty output" };
+    }
+    await writeNarrationCache(state.workspaceDir, trimmed, completedPhaseCount(state));
+    return { narration: trimmed, used: true };
+}
+async function readRecentCloseouts(workspaceDir) {
+    const dir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(dir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const matched = entries
+        .map((name) => {
+        const m = /^(\d{4}-\d{2}-\d{2})-(.+)\.md$/.exec(name);
+        return m ? { date: m[1], phaseOrModule: m[2], fileName: name } : null;
+    })
+        .filter((x) => x !== null)
+        .sort((a, b) => (a.date < b.date ? 1 : -1))
+        .slice(0, MAX_CLOSEOUTS);
+    const out = [];
+    for (const entry of matched) {
+        try {
+            const raw = await readFile(join(dir, entry.fileName), "utf8");
+            const truncated = raw.length > CLOSEOUT_BYTE_BUDGET
+                ? `${raw.slice(0, CLOSEOUT_BYTE_BUDGET)}\n\n[…truncated for narration budget…]`
+                : raw;
+            out.push({ ...entry, content: truncated });
+        }
+        catch {
+            // skip unreadable closeouts
+        }
+    }
+    return out;
+}
+function buildNarratorPrompt(input) {
+    const closeoutBlocks = input.closeouts.map((c) => [
+        `=== CLOSEOUT ${c.date} ${c.phaseOrModule} ===`,
+        c.content,
+        `=== END CLOSEOUT ${c.date} ${c.phaseOrModule} ===`,
+    ].join("\n")).join("\n\n");
+    return [
+        `You are writing a 200-400 word executive summary of a CodeCartographer run for a human reader (project owner, reviewer, or new team member).`,
+        "",
+        "Constraints:",
+        "- Cite specific findings from the closeouts below; quote phase IDs and artifact names verbatim.",
+        "- Do not invent findings the closeouts do not state.",
+        "- Lead with what the run discovered, not what it did mechanically. Findings > activity.",
+        "- Surface any cross-cutting risks or open questions worth pulling forward.",
+        "- Output Markdown only, no commentary, no preface, no fenced code blocks.",
+        "- 200-400 words; tight prose, no bullet-list-soup.",
+        "",
+        "=== RUN METADATA ===",
+        `Project: ${input.projectName}`,
+        `Pipeline: ${input.pipeline}`,
+        `Progress: ${input.completedCount}/${input.totalPhases} phases complete`,
+        `Current phase: ${input.currentPhase}`,
+        `Usage: ${input.usageSummary}`,
+        "=== END RUN METADATA ===",
+        "",
+        closeoutBlocks,
+    ].join("\n");
+}
+function summarizeUsage(usage) {
+    if (usage.runs.length === 0)
+        return "no runs recorded";
+    const totals = computeTotals(usage);
+    const tokensTotal = totals.tokens.input + totals.tokens.output;
+    return `${totals.runs} runs · ${formatK(tokensTotal)} tokens · ${totals.tool_uses} tool uses`;
+}
+function formatK(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(2)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return `${n}`;
+}
+function completedPhaseCount(state) {
+    return Object.values(state.status.phases).filter((p) => p.status === "complete").length;
+}
+async function writeNarrationCache(workspaceDir, content, phaseCount) {
+    const generatedAt = new Date().toISOString();
+    const frontmatter = stringifySimpleYaml({ generatedAt, phaseCountAtGeneration: phaseCount });
+    const body = `---\n${frontmatter}\n---\n${content}\n`;
+    const path = join(workspaceDir, NARRATION_CACHE_RELATIVE_PATH);
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, body, "utf8");
+    await rename(tempPath, path);
+}
+async function runNarratorOnce(ctx, prompt) {
+    const cwd = ctx.cwd;
+    const agentDir = getAgentDir();
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir,
+        sessionManager: SessionManager.inMemory(cwd),
+        settingsManager: SettingsManager.create(cwd, agentDir),
+        modelRegistry: ctx.modelRegistry,
+        model: ctx.model,
+        tools: [],
+        resourceLoader: loader,
+    });
+    await session.prompt(prompt);
+    return getLastAssistantText(session);
+}
+function getLastAssistantText(session) {
+    for (let i = session.messages.length - 1; i >= 0; i--) {
+        const msg = session.messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        const blocks = msg.content;
+        const parts = [];
+        for (const c of blocks) {
+            if (c.type === "text" && c.text)
+                parts.push(c.text);
+        }
+        const joined = parts.join("\n").trim();
+        if (joined)
+            return joined;
+    }
+    return "";
+}

package/dist/extensions/codecarto/dashboard-writer.d.ts

@@ -0,0 +1 @@
+export declare function writeDashboard(cwd: string, packageVersion: string): Promise<void>;