codecartographer-pi 0.1.4 → 0.6.0

package/dist/extensions/codecarto/index.js

@@ -1,9 +1,52 @@
 import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadOrchestratorState, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, writeOrchestratorState, } from "../../core/index.js";
+import { runPhase } from "./agent-runner.js";
+import { rewritePhasePrompt } from "./agent-rewriter.js";
+import { clearPhase, finishPhase, getPhaseActivity, startPhase } from "./agent-state.js";
+import { buildPhaseSummary } from "./agent-summary.js";
+import { disposeAgentsWidget, getAgentsWidget } from "./agent-widget.js";
+import { parseNextFlags } from "./next-flags.js";
+import { appendUsageRun, buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, computePerPhaseTotals, computeTotals, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadCodecartoConfig, loadUsage, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
+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 {
+        // Local usage logging is best-effort. A full disk or permission
+        // failure shouldn't surface as a phase error to the user.
+    }
+}
+function formatUsageTokens(count) {
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(2)}M`;
+    if (count >= 1_000)
+        return `${(count / 1_000).toFixed(1)}k`;
+    return `${count}`;
+}
+function formatUsageDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const minutes = Math.floor(ms / 60_000);
+    const seconds = Math.floor((ms % 60_000) / 1000);
+    return `${minutes}m${seconds.toString().padStart(2, "0")}s`;
+}
 function buildStatusLines(state, extraLines = []) {
     const nextPhase = getNextEligiblePhase(state);
     const currentPhase = nextPhase?.id ?? state.status.current_phase ?? "complete";
@@ -79,6 +122,11 @@ export default function codeCartographerExtension(pi) {
             return;
         pi.setActiveTools(SAFE_TOOL_NAMES);
     });
+    pi.on("session_shutdown", async () => {
+        // Tear down the persistent agents widget so we don't leak the timer
+        // or render against a torn-down UI context after a session swap.
+        disposeAgentsWidget();
+    });
     pi.on("agent_end", async (_event, ctx) => {
         await refreshWorkspaceUi(ctx);
     });
@@ -153,21 +201,6 @@ export default function codeCartographerExtension(pi) {
             normalizedStatus.last_updated = new Date().toISOString();
             await writeFile(rawStatusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
             lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
-            // Claim the current Pi session as the orchestrator for this workspace.
-            // /codecarto-next will then spawn each phase as a child session, keeping
-            // the orchestrator's context window clean. The pointer is gitignored
-            // (workflow/.orchestrator.local.yaml) so it's machine-local. If we have
-            // no session file (rare; Pi running headless), skip silently — handlers
-            // fall back to in-place phase prompts.
-            const orchestratorSessionFile = ctx.sessionManager.getSessionFile();
-            const orchestratorSessionId = ctx.sessionManager.getSessionId();
-            if (orchestratorSessionFile && orchestratorSessionId) {
-                await writeOrchestratorState(ctx.cwd, {
-                    sessionFile: orchestratorSessionFile,
-                    sessionId: orchestratorSessionId,
-                });
-                lastFeedbackLines.push(`Claimed this session as the orchestrator (${orchestratorSessionId.slice(0, 8)}…).`);
-            }
             ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
             await ctx.reload();
             return;
@@ -186,8 +219,19 @@ export default function codeCartographerExtension(pi) {
         },
     });
     pi.registerCommand("codecarto-next", {
-        description: "Queue the next eligible CodeCartographer phase prompt",
-        handler: async (_args, ctx) => {
+        description: "Run the next eligible CodeCartographer phase as a sub-agent. Flags: --llm-steer / --no-llm-steer",
+        getArgumentCompletions: (prefix) => {
+            const items = ["--llm-steer", "--no-llm-steer"]
+                .filter((value) => value.startsWith(prefix))
+                .map((value) => ({ value, label: value }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            const flags = parseNextFlags(args);
+            if (flags.unknown.length > 0) {
+                ctx.ui.notify(`Unknown /codecarto-next flag: ${flags.unknown.join(" ")}`, "error");
+                return;
+            }
             const state = await ensureWorkspaceState(ctx);
             if (!state)
                 return;
@@ -198,71 +242,110 @@ export default function codeCartographerExtension(pi) {
                 ctx.ui.notify("All CodeCartographer phases are complete.", "info");
                 return;
             }
-            const prompt = await buildPhasePrompt(state, phase, false);
-            const orchestrator = await loadOrchestratorState(ctx.cwd);
-            const currentSessionFile = ctx.sessionManager.getSessionFile();
-            // Legacy path: workspace has no orchestrator pointer (created by 0.1.2
-            // or earlier, or Pi has no session file). Queue the prompt in-place
-            // exactly as we did before sub-agent mode existed.
-            if (!orchestrator || !currentSessionFile) {
-                if (ctx.isIdle())
-                    pi.sendUserMessage(prompt);
-                else
-                    pi.sendUserMessage(prompt, { deliverAs: "followUp" });
-                lastFeedbackLines = [`Queued phase prompt for ${phase.id} (in-place; run /codecarto-init to enable sub-agent mode)`];
-                setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+            // Reject re-entry: don't spawn a duplicate runner for a phase that's
+            // already in flight from a previous /codecarto-next invocation.
+            const existing = getPhaseActivity(phase.id);
+            if (existing && existing.status === "running") {
+                ctx.ui.notify(`Phase ${phase.id} is already running.`, "warning");
                 return;
             }
-            // Orchestrator path: we're the parent. Spawn a child session for the
-            // phase so its tool calls and reasoning land in an isolated context.
-            //
-            // SDK contract: after `ctx.newSession()` resolves, `ctx` is invalidated
-            // — touching `ctx.ui` or `ctx.sessionManager` from the outer scope
-            // raises "extension ctx is stale after session replacement". So all
-            // outer-session work (status line, widget) has to happen BEFORE the
-            // call, and any work that needs a fresh ctx happens INSIDE the
-            // `withSession` callback against the new session's ctx.
-            if (currentSessionFile === orchestrator.sessionFile) {
-                lastFeedbackLines = [`Spawned ${phase.id} phase in a sub-agent`];
-                setUiState(ctx, state, lastFeedbackLines);
-                ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent)`, "info");
-                await ctx.newSession({
-                    parentSession: orchestrator.sessionFile,
-                    withSession: async (childCtx) => {
-                        childCtx.sendUserMessage(prompt);
-                    },
-                });
-                return;
+            const config = await loadCodecartoConfig(state.workspaceDir);
+            const llmSteerEnabled = flags.llmSteerOverride ?? config.orchestrator.llm_steer_next_phase;
+            let prompt = await buildPhasePrompt(state, phase, false);
+            if (llmSteerEnabled) {
+                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;
+                    ctx.ui.notify(`LLM rewriter customized ${phase.id} seed prompt.`, "info");
+                }
+                else {
+                    ctx.ui.notify(`LLM rewriter skipped (${rewrite.skipReason}); using stock prompt.`, "warning");
+                }
             }
-            // Phase-child path: switch the TUI back to the orchestrator and chain
-            // the next phase atomically. Same staleness rule: pre-switch work uses
-            // `ctx`; post-switch work uses the fresh `orchestratorCtx` passed to
-            // `withSession`. Inside that callback the inner `newSession()` again
-            // invalidates `orchestratorCtx`, so the inner spawn must be the last
-            // thing the callback does.
-            lastFeedbackLines = ["Returning to orchestrator and queuing next phase as a sub-agent"];
+            const activity = startPhase(phase.id);
+            lastFeedbackLines = [`Running ${phase.id} phase as sub-agent`];
             setUiState(ctx, state, lastFeedbackLines);
-            await ctx.switchSession(orchestrator.sessionFile, {
-                withSession: async (orchestratorCtx) => {
-                    const freshState = await getWorkspaceState(orchestratorCtx.cwd);
-                    if (!freshState) {
-                        orchestratorCtx.ui.notify("Workspace state not found after switch.", "error");
-                        return;
-                    }
-                    const nextPhase = getNextEligiblePhase(freshState);
-                    if (!nextPhase) {
-                        orchestratorCtx.ui.notify("All CodeCartographer phases are complete.", "info");
-                        return;
-                    }
-                    const nextPrompt = await buildPhasePrompt(freshState, nextPhase, false);
-                    await orchestratorCtx.newSession({
-                        parentSession: orchestrator.sessionFile,
-                        withSession: async (nextChildCtx) => {
-                            nextChildCtx.sendUserMessage(nextPrompt);
-                        },
-                    });
+            ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent running)`, "info");
+            // Attach the persistent "Agents" widget so the user can watch the
+            // phase's tool/turn/token counts live above the editor while the
+            // orchestrator's TUI stays responsive.
+            getAgentsWidget().attach(ctx.ui);
+            // Fire-and-forget: spawn the phase runner asynchronously so the
+            // orchestrator's TUI stays responsive. The runner mutates the shared
+            // agent-state map from event callbacks; M2 will read that map from a
+            // persistent widget. For M1 we just notify on completion.
+            void 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}` })
+                .then((result) => {
+                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");
+                }
+                // Inject a CustomMessageEntry into the orchestrator's session so
+                // the user sees a closeout summary in the TUI scrollback and the
+                // orchestrator's LLM picks up the phase result as context on the
+                // next turn. display:true renders in the TUI; no triggerTurn so
+                // the LLM doesn't auto-respond — the user remains in control.
+                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);
+            })
+                .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);
+            })
+                .finally(() => {
+                // Sub-agent may have written findings, owner_notes, or carry-forward
+                // items into status.yaml. Refresh the main status widget so the
+                // "Open questions / Carry-forward / Next" lines reflect the new
+                // state without waiting for the user to run /codecarto-status.
+                void refreshWorkspaceUi(ctx);
+                // Linger 30s in M1 so /codecarto-status can show that the phase ran;
+                // M2's widget owns the proper "linger N turns" lifecycle.
+                setTimeout(() => clearPhase(phase.id), 30_000);
             });
         },
     });
@@ -440,4 +523,34 @@ export default function codeCartographerExtension(pi) {
             ctx.ui.notify(`Queued CodeCartographer skill: ${skillName}`, "info");
         },
     });
+    pi.registerCommand("codecarto-usage", {
+        description: "Show cumulative + per-phase token usage from local phase runs",
+        handler: async (_args, ctx) => {
+            const state = await ensureWorkspaceState(ctx);
+            if (!state)
+                return;
+            const usage = await loadUsage(state.workspaceDir);
+            if (usage.runs.length === 0) {
+                lastFeedbackLines = ["No phase runs recorded yet."];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify("No phase runs recorded yet.", "info");
+                return;
+            }
+            const totals = computeTotals(usage);
+            const perPhase = computePerPhaseTotals(usage);
+            const lines = [];
+            lines.push(`Total runs: ${totals.runs}`);
+            lines.push(`Total tokens: ${formatUsageTokens(totals.tokens.input)} in · ${formatUsageTokens(totals.tokens.output)} out · ${formatUsageTokens(totals.tokens.cache_write)} cache-write`);
+            lines.push(`Total duration: ${formatUsageDuration(totals.duration_ms)} · ${totals.tool_uses} tool uses`);
+            lines.push("");
+            lines.push("Per-phase totals:");
+            for (const [phaseId, t] of perPhase) {
+                const tokensTotal = t.tokens.input + t.tokens.output;
+                lines.push(`  ${phaseId}: ${t.runs} run${t.runs === 1 ? "" : "s"} · ${formatUsageTokens(tokensTotal)} tokens · ${t.tool_uses} tool uses · ${formatUsageDuration(t.duration_ms)}`);
+            }
+            lastFeedbackLines = lines;
+            setUiState(ctx, state, lastFeedbackLines);
+            ctx.ui.notify(`CodeCartographer usage: ${totals.runs} run${totals.runs === 1 ? "" : "s"}, ${formatUsageTokens(totals.tokens.input + totals.tokens.output)} tokens total`, "info");
+        },
+    });
 }

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

@@ -0,0 +1,6 @@
+export interface NextFlags {
+    llmSteerOverride?: boolean;
+    unknown: string[];
+}
+export declare function parseNextFlags(args: string): NextFlags;
+export declare const KNOWN_NEXT_FLAGS: readonly string[];

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

@@ -0,0 +1,19 @@
+// Flag parser for /codecarto-next. The user invokes the slash command with
+// an optional "--llm-steer" or "--no-llm-steer" override. We parse and
+// validate; index.ts decides how to merge the override with workspace
+// config to compute the effective "should we run the LLM rewriter?" bit.
+const KNOWN = new Set(["--llm-steer", "--no-llm-steer"]);
+export function parseNextFlags(args) {
+    const tokens = args.trim().split(/\s+/).filter((t) => t.length > 0);
+    const result = { unknown: [] };
+    for (const t of tokens) {
+        if (t === "--llm-steer")
+            result.llmSteerOverride = true;
+        else if (t === "--no-llm-steer")
+            result.llmSteerOverride = false;
+        else
+            result.unknown.push(t);
+    }
+    return result;
+}
+export const KNOWN_NEXT_FLAGS = [...KNOWN];

package/dist/mcp-server/server.js

@@ -367,7 +367,7 @@ const HANDLERS = {
 };
 // ---------- server bootstrap ----------
 export function buildServer() {
-    const server = new Server({ name: "codecartographer", version: "0.1.4" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "codecartographer", version: "0.2.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = HANDLERS[request.params.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.1.4",
+  "version": "0.6.0",
   "description": "CodeCartographer packaged for Pi as an extension-driven workflow wrapper.",
   "type": "module",
   "keywords": [
@@ -42,7 +42,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0",
+    "@earendil-works/pi-coding-agent": "~0.74.0",
     "@sinclair/typebox": "*"
   },
   "pi": {

package/dist/core/orchestrator.d.ts

@@ -1,6 +0,0 @@
-export interface OrchestratorState {
-    sessionFile: string;
-    sessionId: string;
-}
-export declare function loadOrchestratorState(cwd: string): Promise<OrchestratorState | null>;
-export declare function writeOrchestratorState(cwd: string, state: OrchestratorState): Promise<void>;

package/dist/core/orchestrator.js

@@ -1,36 +0,0 @@
-// Per-machine pointer to the Pi session that runs as the CodeCartographer
-// orchestrator. Stored in `.codecarto/workflow/.orchestrator.local.yaml`
-// (gitignored) so committed `status.yaml` doesn't leak machine-specific
-// session file paths to collaborators.
-//
-// Only the Pi extension writes/reads this — the MCP path has no session
-// concept. When the file is missing or malformed, `/codecarto-next` falls
-// back to in-place phase prompts (legacy 0.1.0–0.1.2 behavior).
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { pathExists } from "./utils.js";
-import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
-const ORCHESTRATOR_STATE_RELATIVE = "workflow/.orchestrator.local.yaml";
-function orchestratorStatePath(cwd) {
-    return join(cwd, ".codecarto", ORCHESTRATOR_STATE_RELATIVE);
-}
-export async function loadOrchestratorState(cwd) {
-    const path = orchestratorStatePath(cwd);
-    if (!(await pathExists(path)))
-        return null;
-    let data;
-    try {
-        data = await loadYamlFile(path);
-    }
-    catch {
-        return null;
-    }
-    if (!data?.sessionFile || !data?.sessionId)
-        return null;
-    return { sessionFile: data.sessionFile, sessionId: data.sessionId };
-}
-export async function writeOrchestratorState(cwd, state) {
-    const path = orchestratorStatePath(cwd);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${stringifySimpleYaml(state)}\n`, "utf8");
-}