codecartographer-pi 0.1.4 → 0.6.0

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

@@ -0,0 +1,35 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+export type PhaseStatus = "running" | "completed" | "error" | "aborted";
+export interface PhaseActivity {
+    phaseId: string;
+    status: PhaseStatus;
+    startedAt: number;
+    completedAt?: number;
+    turnCount: number;
+    toolUses: number;
+    /** Currently-executing tool calls keyed by toolCallId, value is the tool name. */
+    activeTools: Map<string, string>;
+    /** Latest streaming response text from the assistant (for "thinking…" UI). */
+    responseText: string;
+    /** Cumulative token usage across all assistant turns; survives in-session compaction. */
+    lifetimeUsage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    };
+    session?: AgentSession;
+    error?: string;
+}
+export declare function getPhaseActivity(phaseId: string): PhaseActivity | undefined;
+export declare function listPhaseActivity(): PhaseActivity[];
+export declare function startPhase(phaseId: string): PhaseActivity;
+export declare function finishPhase(phaseId: string, outcome: {
+    status: Exclude<PhaseStatus, "running">;
+    error?: string;
+}): void;
+/**
+ * Clear a phase from the activity map. The widget (M2) will linger finished
+ * phases for a turn or two before calling this; for now (M1) we clear after
+ * a fixed timeout so the orchestrator notification stays meaningful.
+ */
+export declare function clearPhase(phaseId: string): void;

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

@@ -0,0 +1,46 @@
+// Shared, per-extension-instance phase activity state. The runner mutates
+// 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.
+const phaseActivity = new Map();
+export function getPhaseActivity(phaseId) {
+    return phaseActivity.get(phaseId);
+}
+export function listPhaseActivity() {
+    return [...phaseActivity.values()];
+}
+export function startPhase(phaseId) {
+    const existing = phaseActivity.get(phaseId);
+    if (existing && existing.status === "running")
+        return existing;
+    const activity = {
+        phaseId,
+        status: "running",
+        startedAt: Date.now(),
+        turnCount: 0,
+        toolUses: 0,
+        activeTools: new Map(),
+        responseText: "",
+        lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+    };
+    phaseActivity.set(phaseId, activity);
+    return activity;
+}
+export function finishPhase(phaseId, outcome) {
+    const activity = phaseActivity.get(phaseId);
+    if (!activity)
+        return;
+    activity.status = outcome.status;
+    activity.completedAt = Date.now();
+    if (outcome.error)
+        activity.error = outcome.error;
+    activity.activeTools.clear();
+}
+/**
+ * Clear a phase from the activity map. The widget (M2) will linger finished
+ * phases for a turn or two before calling this; for now (M1) we clear after
+ * a fixed timeout so the orchestrator notification stays meaningful.
+ */
+export function clearPhase(phaseId) {
+    phaseActivity.delete(phaseId);
+}

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

@@ -0,0 +1,17 @@
+import type { PhaseActivity } from "./agent-state.ts";
+export interface PhaseSummaryInput {
+    phaseId: string;
+    status: PhaseActivity["status"];
+    turnCount: number;
+    toolUses: number;
+    tokens: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    };
+    durationMs: number;
+    responseText: string;
+    sessionFile?: string;
+    error?: string;
+}
+export declare function buildPhaseSummary(input: PhaseSummaryInput): string;

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

@@ -0,0 +1,79 @@
+// Build the markdown summary that's injected into the orchestrator's session
+// when a phase sub-agent finishes. The summary is a CustomMessageEntry
+// (display: true, no triggerTurn) so the user sees it in the TUI and the
+// orchestrator's LLM picks it up as context on the user's next turn.
+const RESPONSE_TEXT_CHAR_BUDGET = 2000;
+export function buildPhaseSummary(input) {
+    const stats = formatStats(input);
+    const headerLine = formatHeader(input.phaseId, input.status);
+    if (input.status === "error") {
+        const errorLine = input.error ? `\n\n\`${input.error}\`` : "";
+        return `${headerLine}\n\n${stats}${errorLine}`;
+    }
+    const trailer = formatTrailer(input);
+    const excerpt = formatExcerpt(input.responseText);
+    const sections = [headerLine, stats];
+    if (excerpt)
+        sections.push(excerpt);
+    sections.push(trailer);
+    return sections.join("\n\n");
+}
+function formatHeader(phaseId, status) {
+    switch (status) {
+        case "completed":
+            return `**Phase \`${phaseId}\` finished.**`;
+        case "aborted":
+            return `**Phase \`${phaseId}\` aborted.**`;
+        case "error":
+            return `**Phase \`${phaseId}\` failed.**`;
+        default:
+            return `**Phase \`${phaseId}\`.**`;
+    }
+}
+function formatStats(input) {
+    const parts = [];
+    if (input.turnCount > 0)
+        parts.push(`⟳ ${input.turnCount}`);
+    if (input.toolUses > 0)
+        parts.push(`${input.toolUses} tool use${input.toolUses === 1 ? "" : "s"}`);
+    const totalTokens = input.tokens.input + input.tokens.output;
+    if (totalTokens > 0)
+        parts.push(formatTokens(totalTokens));
+    if (input.durationMs > 0)
+        parts.push(formatDuration(input.durationMs));
+    return parts.length > 0 ? `_${parts.join(" · ")}_` : "_(no activity recorded)_";
+}
+function formatExcerpt(responseText) {
+    const trimmed = responseText.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.length <= RESPONSE_TEXT_CHAR_BUDGET)
+        return trimmed;
+    return `${trimmed.slice(0, RESPONSE_TEXT_CHAR_BUDGET).trimEnd()}…\n\n_(transcript truncated; resume the phase session for the full output)_`;
+}
+function formatTrailer(input) {
+    const lines = [];
+    if (input.sessionFile) {
+        lines.push(`Phase transcript: \`${input.sessionFile}\` (open via \`/resume\`).`);
+    }
+    if (input.status === "completed") {
+        lines.push("Run `/codecarto-validate` to check the output, then `/codecarto-complete` to advance.");
+    }
+    return lines.join("\n");
+}
+function formatTokens(count) {
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(1)}M tokens`;
+    if (count >= 1_000)
+        return `${(count / 1_000).toFixed(1)}k tokens`;
+    return `${count} tokens`;
+}
+function formatDuration(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`;
+}

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

@@ -0,0 +1,26 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+declare class CodecartoAgentsWidget {
+    private uiCtx;
+    private timer;
+    private spinnerFrame;
+    private widgetRegistered;
+    private tui;
+    private lastStatus;
+    /** Tick counts for finished phases — used to age them out. */
+    private finishedAge;
+    /**
+     * Wire this widget to a UI context. Called from /codecarto-next when a
+     * phase starts. Idempotent — if already running on the same context the
+     * call is a no-op.
+     */
+    attach(uiCtx: ExtensionUIContext): void;
+    /** Tear down — called from extension dispose. */
+    dispose(): void;
+    private ensureTimer;
+    private update;
+    private unregister;
+    private renderLines;
+}
+export declare function getAgentsWidget(): CodecartoAgentsWidget;
+export declare function disposeAgentsWidget(): void;
+export {};

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

@@ -0,0 +1,260 @@
+// Persistent "Agents" widget rendered above the editor while CodeCartographer
+// phase sub-agents are running. Reads the shared agent-state map every ~80ms
+// to update the spinner and per-phase stats; unregisters itself when no phase
+// is active and any finished phases have lingered out.
+//
+// Pattern adapted from @tintinweb/pi-subagents (src/ui/agent-widget.ts).
+// Slimmed down: codecarto runs at most a small number of phases sequentially
+// per workflow, so the overflow/queue logic in tintinweb's version is dropped.
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { listPhaseActivity } from "./agent-state.js";
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const WIDGET_KEY = "codecarto-agents";
+const STATUS_KEY = "codecarto-agents-status";
+const TICK_MS = 80;
+/** How many ticks a finished phase lingers in the widget before removal. */
+const FINISHED_LINGER_TICKS = 80; // ~6.4s at 80ms
+const TOOL_DISPLAY = {
+    read: "reading",
+    edit: "editing",
+    write: "writing",
+    grep: "searching",
+    find: "finding files",
+    ls: "listing",
+};
+class CodecartoAgentsWidget {
+    uiCtx;
+    timer;
+    spinnerFrame = 0;
+    widgetRegistered = false;
+    tui;
+    lastStatus;
+    /** Tick counts for finished phases — used to age them out. */
+    finishedAge = new Map();
+    /**
+     * Wire this widget to a UI context. Called from /codecarto-next when a
+     * phase starts. Idempotent — if already running on the same context the
+     * call is a no-op.
+     */
+    attach(uiCtx) {
+        if (this.uiCtx === uiCtx && this.timer !== undefined)
+            return;
+        this.uiCtx = uiCtx;
+        this.widgetRegistered = false;
+        this.tui = undefined;
+        this.lastStatus = undefined;
+        this.ensureTimer();
+        this.update();
+    }
+    /** Tear down — called from extension dispose. */
+    dispose() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.uiCtx) {
+            this.uiCtx.setWidget(WIDGET_KEY, undefined);
+            this.uiCtx.setStatus(STATUS_KEY, undefined);
+        }
+        this.widgetRegistered = false;
+        this.tui = undefined;
+        this.lastStatus = undefined;
+        this.finishedAge.clear();
+    }
+    ensureTimer() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.update(), TICK_MS);
+    }
+    update() {
+        if (!this.uiCtx)
+            return;
+        const all = listPhaseActivity();
+        const running = all.filter((a) => a.status === "running");
+        const finished = all.filter((a) => a.status !== "running");
+        // Age finished phases. Drop those past the linger threshold.
+        for (const a of finished) {
+            const age = (this.finishedAge.get(a.phaseId) ?? 0) + 1;
+            this.finishedAge.set(a.phaseId, age);
+        }
+        // Forget aged-out phases (visual only — agent-state owns the actual map).
+        const visibleFinished = finished.filter((a) => (this.finishedAge.get(a.phaseId) ?? 0) <= FINISHED_LINGER_TICKS);
+        // Drop entries for phases that are no longer in the activity map.
+        for (const id of [...this.finishedAge.keys()]) {
+            if (!all.some((a) => a.phaseId === id))
+                this.finishedAge.delete(id);
+        }
+        const hasActive = running.length > 0;
+        const hasContent = hasActive || visibleFinished.length > 0;
+        if (!hasContent) {
+            this.unregister();
+            return;
+        }
+        const newStatus = hasActive
+            ? `${running.length} CodeCartographer phase${running.length === 1 ? "" : "s"} running`
+            : undefined;
+        if (newStatus !== this.lastStatus) {
+            this.uiCtx.setStatus(STATUS_KEY, newStatus);
+            this.lastStatus = newStatus;
+        }
+        this.spinnerFrame++;
+        if (!this.widgetRegistered) {
+            this.uiCtx.setWidget(WIDGET_KEY, (tui, theme) => {
+                this.tui = tui;
+                return {
+                    render: () => this.renderLines(tui, theme),
+                    invalidate: () => {
+                        this.widgetRegistered = false;
+                        this.tui = undefined;
+                    },
+                };
+            }, { placement: "aboveEditor" });
+            this.widgetRegistered = true;
+        }
+        else {
+            this.tui?.requestRender();
+        }
+    }
+    unregister() {
+        if (!this.uiCtx)
+            return;
+        if (this.widgetRegistered) {
+            this.uiCtx.setWidget(WIDGET_KEY, undefined);
+            this.widgetRegistered = false;
+            this.tui = undefined;
+        }
+        if (this.lastStatus !== undefined) {
+            this.uiCtx.setStatus(STATUS_KEY, undefined);
+            this.lastStatus = undefined;
+        }
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        this.finishedAge.clear();
+    }
+    renderLines(tui, theme) {
+        const all = listPhaseActivity();
+        if (all.length === 0)
+            return [];
+        const cols = tui.terminal?.columns ?? 80;
+        const truncate = (line) => truncateToWidth(line, cols);
+        const running = all.filter((a) => a.status === "running");
+        const finished = all
+            .filter((a) => a.status !== "running")
+            .filter((a) => (this.finishedAge.get(a.phaseId) ?? 0) <= FINISHED_LINGER_TICKS);
+        const headingColor = running.length > 0 ? "accent" : "dim";
+        const headingIcon = running.length > 0 ? "●" : "○";
+        const heading = `${theme.fg(headingColor, headingIcon)} ${theme.fg(headingColor, "CodeCartographer")}`;
+        const lines = [truncate(heading)];
+        const allEntries = [];
+        for (const a of running)
+            allEntries.push({ activity: a, isLast: false });
+        for (const a of finished)
+            allEntries.push({ activity: a, isLast: false });
+        for (let i = 0; i < allEntries.length; i++) {
+            allEntries[i].isLast = i === allEntries.length - 1;
+        }
+        for (const { activity, isLast } of allEntries) {
+            const connector = isLast ? "└─" : "├─";
+            const continuation = isLast ? "   " : "│  ";
+            if (activity.status === "running") {
+                const frame = SPINNER[this.spinnerFrame % SPINNER.length];
+                const stats = formatRunningStats(activity);
+                const header = `${theme.fg("dim", connector)} ${theme.fg("accent", frame)} ${theme.bold(activity.phaseId)} phase  ${theme.fg("dim", stats)}`;
+                const activityText = describeActivity(activity);
+                lines.push(truncate(header));
+                lines.push(truncate(`${theme.fg("dim", continuation)}${theme.fg("dim", `   ⎿ ${activityText}`)}`));
+            }
+            else {
+                const stats = formatFinishedStats(activity);
+                const icon = formatStatusIcon(activity.status, theme);
+                const dim = activity.status === "completed" ? "dim" : "warning";
+                const errSuffix = activity.error ? ` ${theme.fg("error", `– ${activity.error.slice(0, 60)}`)}` : "";
+                lines.push(truncate(`${theme.fg("dim", connector)} ${icon} ${theme.fg(dim, `${activity.phaseId} phase`)}  ${theme.fg("dim", stats)}${errSuffix}`));
+            }
+        }
+        return lines;
+    }
+}
+function formatRunningStats(a) {
+    const parts = [];
+    if (a.turnCount > 0)
+        parts.push(`⟳ ${a.turnCount}`);
+    if (a.toolUses > 0)
+        parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
+    const tokens = a.lifetimeUsage.input + a.lifetimeUsage.output;
+    if (tokens > 0)
+        parts.push(formatTokens(tokens));
+    parts.push(formatDuration(Date.now() - a.startedAt));
+    return parts.join(" · ");
+}
+function formatFinishedStats(a) {
+    const parts = [];
+    if (a.turnCount > 0)
+        parts.push(`⟳ ${a.turnCount}`);
+    if (a.toolUses > 0)
+        parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
+    const tokens = a.lifetimeUsage.input + a.lifetimeUsage.output;
+    if (tokens > 0)
+        parts.push(formatTokens(tokens));
+    const dur = a.completedAt ? a.completedAt - a.startedAt : 0;
+    if (dur > 0)
+        parts.push(formatDuration(dur));
+    return parts.join(" · ");
+}
+function formatTokens(count) {
+    if (count >= 1_000_000)
+        return `${(count / 1_000_000).toFixed(1)}M tokens`;
+    if (count >= 1_000)
+        return `${(count / 1_000).toFixed(1)}k tokens`;
+    return `${count} tokens`;
+}
+function formatDuration(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 formatStatusIcon(status, theme) {
+    switch (status) {
+        case "completed": return theme.fg("success", "✓");
+        case "aborted": return theme.fg("warning", "■");
+        case "error": return theme.fg("error", "✗");
+        default: return theme.fg("dim", "·");
+    }
+}
+function describeActivity(a) {
+    if (a.activeTools.size > 0) {
+        const counts = new Map();
+        for (const name of a.activeTools.values()) {
+            const action = TOOL_DISPLAY[name] ?? name;
+            counts.set(action, (counts.get(action) ?? 0) + 1);
+        }
+        const parts = [];
+        for (const [action, count] of counts) {
+            parts.push(count > 1 ? `${action} ×${count}` : action);
+        }
+        return `${parts.join(", ")}…`;
+    }
+    const text = a.responseText.split("\n").find((l) => l.trim()) ?? "";
+    if (text.trim().length > 0) {
+        return text.length > 60 ? `${text.slice(0, 60)}…` : text;
+    }
+    return "thinking…";
+}
+let widgetSingleton;
+export function getAgentsWidget() {
+    if (!widgetSingleton)
+        widgetSingleton = new CodecartoAgentsWidget();
+    return widgetSingleton;
+}
+export function disposeAgentsWidget() {
+    if (widgetSingleton) {
+        widgetSingleton.dispose();
+        widgetSingleton = undefined;
+    }
+}