codecartographer-pi 0.10.0 → 0.12.0

package/dist/core/usage.js

@@ -13,6 +13,9 @@ import { pathExists } from "./utils.js";
 import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
 export const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
 const SCHEMA_VERSION = 1;
+export function emptyCompactionTelemetry() {
+    return { successful: 0, failed: 0, aborted: 0, reasons: { threshold: 0, overflow: 0, manual: 0 } };
+}
 export async function loadUsage(workspaceDir) {
     const path = join(workspaceDir, USAGE_RELATIVE_PATH);
     if (!(await pathExists(path)))
@@ -23,8 +26,6 @@ export async function loadUsage(workspaceDir) {
         return normalize(parsed);
     }
     catch {
-        // Malformed file: treat as empty rather than blocking the user. They
-        // can fix or delete the file; corrupt local state shouldn't stop work.
         return emptyUsage();
     }
 }
@@ -33,45 +34,56 @@ export async function appendUsageRun(workspaceDir, run) {
     current.runs.push(run);
     const path = join(workspaceDir, USAGE_RELATIVE_PATH);
     const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-    const serialized = `${stringifySimpleYaml(current)}\n`;
-    await writeFile(tempPath, serialized, "utf8");
+    await writeFile(tempPath, `${stringifySimpleYaml(current)}\n`, "utf8");
     await rename(tempPath, path);
 }
 export function computeTotals(file) {
-    const totals = {
-        runs: file.runs.length,
-        tokens: { input: 0, output: 0, cache_write: 0 },
-        tool_uses: 0,
-        duration_ms: 0,
-    };
-    for (const r of file.runs) {
-        totals.tokens.input += r.tokens?.input ?? 0;
-        totals.tokens.output += r.tokens?.output ?? 0;
-        totals.tokens.cache_write += r.tokens?.cache_write ?? 0;
-        totals.tool_uses += r.tool_uses ?? 0;
-        totals.duration_ms += r.duration_ms ?? 0;
-    }
+    const totals = emptyTotals();
+    totals.runs = file.runs.length;
+    for (const run of file.runs)
+        addRun(totals, run);
     return totals;
 }
 export function computePerPhaseTotals(file) {
     const byPhase = new Map();
-    for (const r of file.runs) {
-        const t = byPhase.get(r.phase) ?? {
-            runs: 0,
-            tokens: { input: 0, output: 0, cache_write: 0 },
-            tool_uses: 0,
-            duration_ms: 0,
-        };
-        t.runs += 1;
-        t.tokens.input += r.tokens?.input ?? 0;
-        t.tokens.output += r.tokens?.output ?? 0;
-        t.tokens.cache_write += r.tokens?.cache_write ?? 0;
-        t.tool_uses += r.tool_uses ?? 0;
-        t.duration_ms += r.duration_ms ?? 0;
-        byPhase.set(r.phase, t);
+    for (const run of file.runs) {
+        const totals = byPhase.get(run.phase) ?? emptyTotals();
+        totals.runs += 1;
+        addRun(totals, run);
+        byPhase.set(run.phase, totals);
     }
     return byPhase;
 }
+function emptyTotals() {
+    return {
+        runs: 0,
+        compaction_runs: 0,
+        tokens: { input: 0, output: 0, cache_write: 0 },
+        tool_uses: 0,
+        duration_ms: 0,
+        compactions: emptyCompactionTelemetry(),
+    };
+}
+function addRun(totals, run) {
+    totals.tokens.input += run.tokens?.input ?? 0;
+    totals.tokens.output += run.tokens?.output ?? 0;
+    totals.tokens.cache_write += run.tokens?.cache_write ?? 0;
+    totals.tool_uses += run.tool_uses ?? 0;
+    totals.duration_ms += run.duration_ms ?? 0;
+    if (run.compactions)
+        totals.compaction_runs += 1;
+    addCompactions(totals.compactions, run.compactions);
+}
+function addCompactions(target, source) {
+    if (!source)
+        return;
+    target.successful += source.successful;
+    target.failed += source.failed;
+    target.aborted += source.aborted;
+    target.reasons.threshold += source.reasons.threshold;
+    target.reasons.overflow += source.reasons.overflow;
+    target.reasons.manual += source.reasons.manual;
+}
 function emptyUsage() {
     return { version: SCHEMA_VERSION, runs: [] };
 }
@@ -79,29 +91,35 @@ function normalize(raw) {
     if (!raw || typeof raw !== "object")
         return emptyUsage();
     const runs = Array.isArray(raw.runs) ? raw.runs.filter(isUsageRun) : [];
-    return {
-        version: typeof raw.version === "number" ? raw.version : SCHEMA_VERSION,
-        runs,
-    };
+    return { version: typeof raw.version === "number" ? raw.version : SCHEMA_VERSION, runs };
 }
 function isUsageRun(x) {
     if (!x || typeof x !== "object")
         return false;
-    const r = x;
-    return (typeof r.timestamp === "string" &&
-        typeof r.phase === "string" &&
-        (r.status === "completed" || r.status === "aborted" || r.status === "error") &&
-        isFiniteNumber(r.turn_count) &&
-        isFiniteNumber(r.tool_uses) &&
-        isFiniteNumber(r.duration_ms) &&
-        isUsageTokens(r.tokens) &&
-        (r.session_file === undefined || typeof r.session_file === "string"));
+    const run = x;
+    return (typeof run.timestamp === "string" &&
+        typeof run.phase === "string" &&
+        (run.status === "completed" || run.status === "aborted" || run.status === "error") &&
+        isFiniteNumber(run.turn_count) &&
+        isFiniteNumber(run.tool_uses) &&
+        isFiniteNumber(run.duration_ms) &&
+        isUsageTokens(run.tokens) &&
+        (run.session_file === undefined || typeof run.session_file === "string") &&
+        (run.compactions === undefined || isCompactionTelemetry(run.compactions)));
 }
 function isUsageTokens(x) {
     if (!x || typeof x !== "object")
         return false;
-    const t = x;
-    return isFiniteNumber(t.input) && isFiniteNumber(t.output) && isFiniteNumber(t.cache_write);
+    const tokens = x;
+    return isFiniteNumber(tokens.input) && isFiniteNumber(tokens.output) && isFiniteNumber(tokens.cache_write);
+}
+function isCompactionTelemetry(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const telemetry = x;
+    const reasons = telemetry.reasons;
+    return isFiniteNumber(telemetry.successful) && isFiniteNumber(telemetry.failed) && isFiniteNumber(telemetry.aborted) &&
+        Boolean(reasons) && isFiniteNumber(reasons?.threshold) && isFiniteNumber(reasons?.overflow) && isFiniteNumber(reasons?.manual);
 }
 function isFiniteNumber(x) {
     return typeof x === "number" && Number.isFinite(x);

package/dist/core/workspace.d.ts

@@ -1,11 +1,13 @@
-import type { WorkspaceState } from "./types.ts";
+import type { PhaseHandoff, WorkspaceState } from "./types.ts";
 export declare const packagedWorkspaceDir: string;
 export declare const PACKAGE_VERSION: string;
 export declare function getWorkspaceState(cwd: string): Promise<WorkspaceState | null>;
 export declare function updateStatusAtomically(cwd: string, updater: (state: WorkspaceState) => Promise<{
     state: WorkspaceState;
+    handoff?: PhaseHandoff;
     threadLogEntry?: string;
 }> | {
     state: WorkspaceState;
+    handoff?: PhaseHandoff;
     threadLogEntry?: string;
 }): Promise<WorkspaceState>;

package/dist/core/workspace.js

@@ -3,10 +3,10 @@
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
 import { existsSync, readFileSync } from "node:fs";
-import { appendFile, rename, writeFile } from "node:fs/promises";
+import { appendFile, readFile, rename, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { acquireLock, normalizeStatus } from "./status.js";
+import { acquireLock, applyHandoff, normalizeStatus, parseHandoff } from "./status.js";
 import { pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
 // Walk up from the current file to find the package root. Needed because the
@@ -42,6 +42,24 @@ export const PACKAGE_VERSION = (() => {
         return "0.0.0";
     }
 })();
+function assertCanonicalStatus(status) {
+    if (status.schema_version !== 1) {
+        throw new Error(`Cannot write unsupported status schema_version ${String(status.schema_version)}.`);
+    }
+    if (!Array.isArray(status.post_pipeline)) {
+        throw new Error("Cannot write status: post_pipeline must be an array.");
+    }
+    if (!status.phases || typeof status.phases !== "object" || Array.isArray(status.phases)) {
+        throw new Error("Cannot write status: phases must be a mapping.");
+    }
+    for (const [phaseId, phase] of Object.entries(status.phases)) {
+        for (const field of ["owner_notes", "outputs_present", "open_questions", "carry_forward"]) {
+            if (!Array.isArray(phase?.[field])) {
+                throw new Error(`Cannot write status: phases.${phaseId}.${field} must be an array.`);
+            }
+        }
+    }
+}
 export async function getWorkspaceState(cwd) {
     const workspaceDir = join(cwd, ".codecarto");
     const statusPath = join(workspaceDir, "workflow", "status.yaml");
@@ -79,13 +97,31 @@ export async function updateStatusAtomically(cwd, updater) {
         }
         const result = await updater(currentState);
         const nextState = result.state;
+        // Apply handoff if provided
+        if (result.handoff) {
+            const handoff = parseHandoff(result.handoff);
+            applyHandoff(nextState.status, handoff);
+        }
+        assertCanonicalStatus(nextState.status);
         const serialized = `${stringifySimpleYaml(nextState.status)}\n`;
         const tempPath = `${statusPath}.${process.pid}.${Date.now()}.tmp`;
         await writeFile(tempPath, serialized, "utf8");
         await rename(tempPath, statusPath);
         if (result.threadLogEntry) {
             const threadLogPath = join(workspaceDir, "THREAD_LOG.md");
-            await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+            let currentLog = "";
+            try {
+                currentLog = await readFile(threadLogPath, "utf8");
+            }
+            catch {
+                // File may not exist yet
+            }
+            const logEntries = currentLog.split(/\r?\n/).filter((line) => line.trim().startsWith("- "));
+            const normalizedEntry = result.threadLogEntry.trim();
+            const isDuplicate = logEntries.some((line) => line.trim() === normalizedEntry);
+            if (!isDuplicate) {
+                await appendFile(threadLogPath, result.threadLogEntry, "utf8");
+            }
         }
         return nextState;
     }

package/dist/core/yaml.js

@@ -132,6 +132,30 @@ export function parseSimpleYaml(raw) {
             const key = trimmed.slice(0, separator).trim();
             const rawValue = trimmed.slice(separator + 1).trim();
             index++;
+            if (key in result) {
+                throw new Error(`Duplicate YAML key: ${key} near line: ${line.trim()}`);
+            }
+            if (rawValue === "|" || rawValue === "|-") {
+                const blockLines = [];
+                let contentIndent = null;
+                while (index < lines.length) {
+                    const blockLine = lines[index] ?? "";
+                    if (blockLine.trim() === "") {
+                        blockLines.push("");
+                        index++;
+                        continue;
+                    }
+                    const blockIndent = countIndent(blockLine);
+                    if (blockIndent <= indent)
+                        break;
+                    contentIndent ??= blockIndent;
+                    blockLines.push(blockLine.slice(Math.min(contentIndent, blockIndent)));
+                    index++;
+                }
+                const content = blockLines.join("\n").replace(/\n+$/, "");
+                result[key] = rawValue === "|" ? `${content}\n` : content;
+                continue;
+            }
             if (rawValue !== "") {
                 result[key] = parseYamlScalar(rawValue);
                 continue;

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

@@ -145,7 +145,6 @@ async function runRewriterOnce(ctx, prompt) {
         agentDir,
         sessionManager: SessionManager.inMemory(cwd),
         settingsManager: SettingsManager.create(cwd, agentDir),
-        modelRegistry: ctx.modelRegistry,
         model: ctx.model,
         tools: [],
         resourceLoader: loader,

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

@@ -1,4 +1,15 @@
 import { type AgentSession, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare function needsPhaseContinuation(messages: ReadonlyArray<{
+    role: string;
+    stopReason?: string;
+}>): boolean;
+export declare function shouldContinuePhase(messages: ReadonlyArray<{
+    role: string;
+    stopReason?: string;
+}>, primaryOutputPresent: boolean): boolean;
+export declare function primaryOutputExists(cwd: string, primaryOutput: string): Promise<boolean>;
+export declare function buildPhaseContinuationPrompt(compacted: boolean): string;
+export declare function waitForCompaction(compactionCompleted: Promise<boolean>, timeoutMs?: number): Promise<boolean>;
 export interface PhaseRunCallbacks {
     onSessionCreated?: (session: AgentSession) => void;
     onToolStart?: (toolCallId: string, toolName: string) => void;
@@ -10,12 +21,20 @@ export interface PhaseRunCallbacks {
         output: number;
         cacheWrite: number;
     }) => void;
+    onCompactionEnd?: (event: {
+        reason: "manual" | "threshold" | "overflow";
+        successful: boolean;
+        aborted: boolean;
+    }) => void;
 }
 export interface PhaseRunOptions {
     /** Display name written via appendSessionInfo so the session shows up in
      *  /resume's picker as e.g. "CodeCartographer phase: blueprint". Pi reads
      *  it via SessionManager.getSessionName(). */
     sessionName?: string;
+    /** Primary output relative to `.codecarto/`; used to detect provider runs
+     * that stop normally before writing their required artifact. */
+    primaryOutput?: string;
 }
 export interface PhaseRunResult {
     session: AgentSession;

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

@@ -9,11 +9,51 @@
 // system prompt, no parent-context inheritance, no turn-limit grace logic.
 // Codecarto phases are bounded by their phase prompt and validation gate;
 // they don't need the full subagent-framework machinery.
+import { access } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { canonicalPath, isWithinPath } from "../../core/index.js";
+import { phaseCompactionExtension } from "./phase-compaction.js";
 // Tools available to the phase sub-agent. Matches the codecarto interception
 // allowlist (SAFE_TOOL_NAMES in extensions/codecarto/index.ts), minus bash.
 // Phases analyze source code and write findings; they don't need a shell.
 const PHASE_TOOL_NAMES = ["read", "edit", "write", "grep", "find", "ls"];
+const COMPACTION_SETTLE_TIMEOUT_MS = 30_000;
+export function needsPhaseContinuation(messages) {
+    const last = messages.at(-1);
+    if (!last)
+        return false;
+    return last.role === "toolResult" || (last.role === "assistant" && last.stopReason === "toolUse");
+}
+export function shouldContinuePhase(messages, primaryOutputPresent) {
+    return !primaryOutputPresent || needsPhaseContinuation(messages);
+}
+export async function primaryOutputExists(cwd, primaryOutput) {
+    const workspaceRoot = await canonicalPath(join(cwd, ".codecarto"));
+    const candidate = await canonicalPath(resolve(workspaceRoot, primaryOutput));
+    if (!isWithinPath(candidate, workspaceRoot))
+        return false;
+    return access(candidate).then(() => true, () => false);
+}
+export function buildPhaseContinuationPrompt(compacted) {
+    const recovery = compacted
+        ? "Continue the current CodeCartographer phase from the compacted context and durable checkpoint."
+        : "The previous phase run stopped before finalizing its required output. Continue from the current session context.";
+    return `${recovery} Finish the declared primary output, validation block, status updates, and closeout before ending.`;
+}
+export async function waitForCompaction(compactionCompleted, timeoutMs = COMPACTION_SETTLE_TIMEOUT_MS) {
+    let timer;
+    try {
+        return await Promise.race([
+            compactionCompleted,
+            new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Run one CodeCartographer phase as an isolated AgentSession. Awaiting this
  * function blocks until the phase completes (or aborts via signal). The
@@ -30,17 +70,19 @@ const PHASE_TOOL_NAMES = ["read", "edit", "write", "grep", "find", "ls"];
 export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal) {
     const cwd = ctx.cwd;
     const agentDir = getAgentDir();
-    // Resource loader: load Pi extensions and skills (so codecarto's own tool
-    // interception applies to the child) but skip prompt templates, themes,
-    // and project context files — they'd just bloat the system prompt.
+    // Resource loader: isolate the child from global extensions/skills and load
+    // only CodeCartographer's inline phase guards and compaction hooks. This
+    // avoids duplicate registration when CodeCartographer is globally installed
+    // while preserving the same safety when it was loaded explicitly with -e.
     const loader = new DefaultResourceLoader({
         cwd,
         agentDir,
-        noExtensions: false,
-        noSkills: false,
+        noExtensions: true,
+        noSkills: true,
         noPromptTemplates: true,
         noThemes: true,
         noContextFiles: true,
+        extensionFactories: [phaseCompactionExtension],
     });
     await loader.reload();
     // File-backed session in the same directory the orchestrator's TUI uses.
@@ -64,7 +106,6 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
         agentDir,
         sessionManager,
         settingsManager: SettingsManager.create(cwd, agentDir),
-        modelRegistry: ctx.modelRegistry,
         model: ctx.model,
         tools: PHASE_TOOL_NAMES,
         resourceLoader: loader,
@@ -75,6 +116,8 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     let turnCount = 0;
     let currentMessageText = "";
     let aborted = false;
+    let resolveCompaction;
+    const compactionCompleted = new Promise((resolve) => { resolveCompaction = resolve; });
     const unsubscribe = session.subscribe((event) => {
         switch (event.type) {
             case "tool_execution_start": {
@@ -117,6 +160,16 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
                 }
                 break;
             }
+            case "compaction_end": {
+                const compactEvent = event;
+                callbacks.onCompactionEnd?.({
+                    reason: compactEvent.reason,
+                    successful: compactEvent.result !== undefined && compactEvent.result !== null && !compactEvent.aborted && !compactEvent.errorMessage,
+                    aborted: compactEvent.aborted,
+                });
+                resolveCompaction?.(true);
+                break;
+            }
         }
     });
     let abortCleanup = () => { };
@@ -130,6 +183,15 @@ export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal
     }
     try {
         await session.prompt(prompt);
+        let primaryOutputPresent = true;
+        if (options.primaryOutput) {
+            primaryOutputPresent = await primaryOutputExists(cwd, options.primaryOutput);
+        }
+        if (!aborted && shouldContinuePhase(session.messages, primaryOutputPresent)) {
+            const compacted = await waitForCompaction(compactionCompleted);
+            if (!aborted)
+                await session.prompt(buildPhaseContinuationPrompt(compacted));
+        }
     }
     finally {
         unsubscribe();

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

@@ -1,4 +1,5 @@
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { type CompactionTelemetry } from "../../core/usage.ts";
 export type PhaseStatus = "running" | "completed" | "error" | "aborted";
 export interface PhaseActivity {
     phaseId: string;
@@ -17,6 +18,8 @@ export interface PhaseActivity {
         output: number;
         cacheWrite: number;
     };
+    /** Compaction outcomes observed during this phase session. */
+    compactions: CompactionTelemetry;
     session?: AgentSession;
     error?: string;
 }

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

@@ -2,6 +2,7 @@
 // it from session-event callbacks; the agents widget (M2) reads it on each
 // render. Module-scoped Map so different command handlers can hand work to
 // the runner and the widget sees the same state without explicit plumbing.
+import { emptyCompactionTelemetry } from "../../core/usage.js";
 const phaseActivity = new Map();
 export function getPhaseActivity(phaseId) {
     return phaseActivity.get(phaseId);
@@ -22,6 +23,7 @@ export function startPhase(phaseId) {
         activeTools: new Map(),
         responseText: "",
         lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+        compactions: emptyCompactionTelemetry(),
     };
     phaseActivity.set(phaseId, activity);
     return activity;

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

@@ -9,6 +9,11 @@ export interface PhaseSummaryInput {
         output: number;
         cacheWrite: number;
     };
+    compactions?: {
+        successful: number;
+        failed: number;
+        aborted: number;
+    };
     durationMs: number;
     responseText: string;
     sessionFile?: string;

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

@@ -39,6 +39,15 @@ function formatStats(input) {
     const totalTokens = input.tokens.input + input.tokens.output;
     if (totalTokens > 0)
         parts.push(formatTokens(totalTokens));
+    const compact = input.compactions;
+    if (compact && compact.successful + compact.failed + compact.aborted > 0) {
+        const details = [`${compact.successful} compaction${compact.successful === 1 ? "" : "s"}`];
+        if (compact.failed > 0)
+            details.push(`${compact.failed} failed`);
+        if (compact.aborted > 0)
+            details.push(`${compact.aborted} aborted`);
+        parts.push(details.join(", "));
+    }
     if (input.durationMs > 0)
         parts.push(formatDuration(input.durationMs));
     return parts.length > 0 ? `_${parts.join(" · ")}_` : "_(no activity recorded)_";

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

@@ -186,6 +186,9 @@ function formatRunningStats(a) {
     const tokens = a.lifetimeUsage.input + a.lifetimeUsage.output;
     if (tokens > 0)
         parts.push(formatTokens(tokens));
+    const compactions = a.compactions.successful + a.compactions.failed + a.compactions.aborted;
+    if (compactions > 0)
+        parts.push(`${compactions} compact`);
     parts.push(formatDuration(Date.now() - a.startedAt));
     return parts.join(" · ");
 }
@@ -198,6 +201,9 @@ function formatFinishedStats(a) {
     const tokens = a.lifetimeUsage.input + a.lifetimeUsage.output;
     if (tokens > 0)
         parts.push(formatTokens(tokens));
+    const compactions = a.compactions.successful + a.compactions.failed + a.compactions.aborted;
+    if (compactions > 0)
+        parts.push(`${compactions} compact`);
     const dur = a.completedAt ? a.completedAt - a.startedAt : 0;
     if (dur > 0)
         parts.push(formatDuration(dur));

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

@@ -1,9 +1,11 @@
 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";
+import { type PhasePreflightResult, type PipelinePhase, type ValidationOverall, type ValidationResult, type WorkspaceState } from "../../core/index.ts";
 export interface RunSinglePhaseOptions {
     llmSteerEnabled: boolean;
     signal?: AbortSignal;
+    /** Preflight validated by the caller so prompt construction does not repeat it. */
+    preflight?: PhasePreflightResult;
     /**
      * True when this phase is being driven by `/codecarto-next --auto`. The flag
      * propagates into `buildPhasePrompt` so interactive hooks (notably the