codecartographer-pi 0.6.0 → 0.8.0

package/dist/extensions/codecarto/agent-rewriter.d.ts

@@ -10,6 +10,8 @@ export interface RewritePhasePromptResult {
     prompt: string;
     used: boolean;
     skipReason?: string;
+    /** ID of the previous phase whose closeout the rewriter read, when used. */
+    prevPhaseId?: string;
 }
 /**
  * Run the rewriter and return the customized seed prompt. On any failure
@@ -18,3 +20,14 @@ export interface RewritePhasePromptResult {
  * throws. The caller decides what to surface to the user.
  */
 export declare function rewritePhasePrompt(input: RewritePhasePromptInput): Promise<RewritePhasePromptResult>;
+/**
+ * Build the markdown block injected into the orchestrator's session
+ * (via pi.sendMessage with customType "codecarto-steering") whenever the
+ * rewriter produces a customized seed. Lets the user audit what the
+ * rewriter chose to emphasize before the phase sub-agent starts.
+ */
+export declare function buildSteeringMessage(input: {
+    nextPhaseId: string;
+    prevPhaseId?: string;
+    rewrittenPrompt: string;
+}): string;

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

@@ -48,7 +48,27 @@ export async function rewritePhasePrompt(input) {
     if (!trimmed) {
         return { prompt: originalPrompt, used: false, skipReason: "rewriter returned empty output" };
     }
-    return { prompt: trimmed, used: true };
+    return { prompt: trimmed, used: true, prevPhaseId };
+}
+/**
+ * Build the markdown block injected into the orchestrator's session
+ * (via pi.sendMessage with customType "codecarto-steering") whenever the
+ * rewriter produces a customized seed. Lets the user audit what the
+ * rewriter chose to emphasize before the phase sub-agent starts.
+ */
+export function buildSteeringMessage(input) {
+    const provenance = input.prevPhaseId
+        ? `customized by the orchestrator's LLM from \`${input.prevPhaseId}\`'s closeout`
+        : "customized by the orchestrator's LLM";
+    return [
+        `**Steering: \`${input.nextPhaseId}\` seed prompt**`,
+        "",
+        `_${provenance}. The phase sub-agent will receive the prompt below as its first user message._`,
+        "",
+        "---",
+        "",
+        input.rewrittenPrompt,
+    ].join("\n");
 }
 function findPreviousPhaseId(state, nextPhaseId) {
     const order = state.pipeline.phase_order;

package/dist/extensions/codecarto/auto-runner.d.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type PhaseActivity } from "./agent-state.ts";
+import { type PipelinePhase, type ValidationOverall, type ValidationResult, type WorkspaceState } from "../../core/index.ts";
+export interface RunSinglePhaseOptions {
+    llmSteerEnabled: boolean;
+    signal?: AbortSignal;
+}
+export interface SinglePhaseResult {
+    status: "completed" | "aborted" | "error";
+    activity: PhaseActivity;
+    error?: string;
+    responseText?: string;
+}
+/**
+ * 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 declare function runSinglePhase(ctx: ExtensionContext, pi: ExtensionAPI, state: WorkspaceState, phase: PipelinePhase, options: RunSinglePhaseOptions): Promise<SinglePhaseResult>;
+/**
+ * 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 declare function isPhaseRunning(phaseId: string): boolean;
+export interface AutoCompleteResult {
+    updatedState: WorkspaceState;
+    closeoutNotice?: string;
+}
+export declare function autoCompletePhase(ctx: ExtensionContext, validation: ValidationResult): Promise<AutoCompleteResult>;
+export type AutoOutcome = "complete" | "stopped" | "aborted";
+export interface AutoRunOptions {
+    strict: boolean;
+    llmSteerOverride?: boolean;
+    signal?: AbortSignal;
+}
+export interface AutoRunResult {
+    outcome: AutoOutcome;
+    reason: string;
+    phasesRun: string[];
+    totalPhases: number;
+    startedAt: number;
+    endedAt: number;
+    totalTokens: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    };
+    stoppedAt?: {
+        phaseId: string;
+        validation?: ValidationOverall;
+        error?: string;
+    };
+    validationSummary?: string[];
+}
+/**
+ * Per-iteration decision: given the outcome of a sub-agent run and (if it
+ * completed) its validation result, what should the auto loop do next?
+ * Pure function — no I/O, no module state — so the decision matrix is
+ * unit-testable without mocking the SDK.
+ */
+export type AutoDecision = {
+    action: "continue";
+} | {
+    action: "stop";
+    reason: string;
+    validation?: ValidationOverall;
+    error?: string;
+    validationSummary?: string[];
+} | {
+    action: "aborted";
+};
+export declare function decideAfterPhase(phaseStatus: SinglePhaseResult["status"], phaseError: string | undefined, validation: ValidationResult | null, strict: boolean): AutoDecision;
+export declare function runAuto(ctx: ExtensionContext, pi: ExtensionAPI, initialState: WorkspaceState, options: AutoRunOptions): Promise<AutoRunResult>;
+export declare function buildAutoSummary(result: AutoRunResult, availableSkills?: string[]): string;

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

@@ -0,0 +1,399 @@
+// 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);
+    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,
+            }),
+            display: true,
+        });
+        void recordUsage(state.workspaceDir, phase.id, status, activity);
+        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,
+        });
+        // 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);
+        }
+        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) {
+    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,
+            },
+        });
+    }
+    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>;