gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/dist/resources/extensions/gsd/metrics.js

@@ -0,0 +1,377 @@
+/**
+ * GSD Metrics — Token & Cost Tracking
+ *
+ * Accumulates per-unit usage data across auto-mode sessions.
+ * Data is extracted from session entries before each context wipe,
+ * written to .gsd/metrics.json, and surfaced in the dashboard.
+ *
+ * Data flow:
+ *   1. Before newSession() wipes context, snapshotUnitMetrics() scans
+ *      session entries for AssistantMessage usage data
+ *   2. The unit record is appended to the in-memory ledger and flushed to disk
+ *   3. The dashboard overlay and progress widget read from the in-memory ledger
+ *   4. On crash recovery or fresh start, the ledger is loaded from disk
+ */
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { getAndClearSkills } from "./skill-telemetry.js";
+import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { parseUnitId } from "./unit-id.js";
+// Re-export from shared — canonical implementation lives in format-utils.
+export { formatTokenCount } from "../shared/mod.js";
+export function classifyUnitPhase(unitType) {
+    switch (unitType) {
+        case "research-milestone":
+        case "research-slice":
+            return "research";
+        case "plan-milestone":
+        case "plan-slice":
+            return "planning";
+        case "execute-task":
+            return "execution";
+        case "complete-slice":
+            return "completion";
+        case "reassess-roadmap":
+            return "reassessment";
+        default:
+            return "execution";
+    }
+}
+// ─── In-memory state ──────────────────────────────────────────────────────────
+let ledger = null;
+let basePath = "";
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Initialize the metrics system for a given project.
+ * Loads existing ledger from disk if present.
+ */
+export function initMetrics(base) {
+    basePath = base;
+    ledger = loadLedger(base);
+}
+/**
+ * Reset in-memory state. Called when auto-mode stops.
+ */
+export function resetMetrics() {
+    ledger = null;
+    basePath = "";
+}
+/**
+ * Snapshot usage metrics from the current session before it's wiped.
+ * Scans session entries for AssistantMessage usage data.
+ */
+export function snapshotUnitMetrics(ctx, unitType, unitId, startedAt, model, opts) {
+    if (!ledger)
+        return null;
+    const entries = ctx.sessionManager.getEntries();
+    if (!entries || entries.length === 0)
+        return null;
+    const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+    let cost = 0;
+    let toolCalls = 0;
+    let assistantMessages = 0;
+    let userMessages = 0;
+    for (const entry of entries) {
+        if (entry.type !== "message")
+            continue;
+        const msg = entry.message;
+        if (!msg)
+            continue;
+        if (msg.role === "assistant") {
+            assistantMessages++;
+            if (msg.usage) {
+                tokens.input += msg.usage.input ?? 0;
+                tokens.output += msg.usage.output ?? 0;
+                tokens.cacheRead += msg.usage.cacheRead ?? 0;
+                tokens.cacheWrite += msg.usage.cacheWrite ?? 0;
+                tokens.total += msg.usage.totalTokens ?? 0;
+                if (msg.usage.cost != null) {
+                    const c = msg.usage.cost;
+                    cost += typeof c === "number" ? c : (c.total ?? 0);
+                }
+            }
+            // Count tool calls in this message
+            if (msg.content && Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                    if (block.type === "tool_call")
+                        toolCalls++;
+                }
+            }
+        }
+        else if (msg.role === "user") {
+            userMessages++;
+        }
+    }
+    const unit = {
+        type: unitType,
+        id: unitId,
+        model,
+        startedAt,
+        finishedAt: Date.now(),
+        tokens,
+        cost,
+        toolCalls,
+        assistantMessages,
+        userMessages,
+        apiRequests: assistantMessages, // each assistant message = one API request
+        ...(opts?.tier ? { tier: opts.tier } : {}),
+        ...(opts?.modelDowngraded !== undefined ? { modelDowngraded: opts.modelDowngraded } : {}),
+        ...(opts?.contextWindowTokens !== undefined ? { contextWindowTokens: opts.contextWindowTokens } : {}),
+        ...(opts?.truncationSections !== undefined ? { truncationSections: opts.truncationSections } : {}),
+        ...(opts?.continueHereFired !== undefined ? { continueHereFired: opts.continueHereFired } : {}),
+        ...(opts?.promptCharCount != null ? { promptCharCount: opts.promptCharCount } : {}),
+        ...(opts?.baselineCharCount != null ? { baselineCharCount: opts.baselineCharCount } : {}),
+    };
+    // Auto-capture skill telemetry (#599)
+    const skills = getAndClearSkills();
+    if (skills.length > 0) {
+        unit.skills = skills;
+    }
+    // Compute cache hit rate
+    if (tokens.cacheRead > 0 || tokens.input > 0) {
+        const totalInput = tokens.cacheRead + tokens.input;
+        unit.cacheHitRate = totalInput > 0 ? Math.round((tokens.cacheRead / totalInput) * 100) : 0;
+    }
+    ledger.units.push(unit);
+    saveLedger(basePath, ledger);
+    return unit;
+}
+/**
+ * Get the current ledger (read-only).
+ */
+export function getLedger() {
+    return ledger;
+}
+function emptyTokens() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+}
+function addTokens(a, b) {
+    return {
+        input: a.input + b.input,
+        output: a.output + b.output,
+        cacheRead: a.cacheRead + b.cacheRead,
+        cacheWrite: a.cacheWrite + b.cacheWrite,
+        total: a.total + b.total,
+    };
+}
+export function aggregateByPhase(units) {
+    const map = new Map();
+    for (const u of units) {
+        const phase = classifyUnitPhase(u.type);
+        let agg = map.get(phase);
+        if (!agg) {
+            agg = { phase, units: 0, tokens: emptyTokens(), cost: 0, duration: 0 };
+            map.set(phase, agg);
+        }
+        agg.units++;
+        agg.tokens = addTokens(agg.tokens, u.tokens);
+        agg.cost += u.cost;
+        agg.duration += u.finishedAt - u.startedAt;
+    }
+    // Return in a stable order
+    const order = ["research", "planning", "execution", "completion", "reassessment"];
+    return order.map(p => map.get(p)).filter((a) => !!a);
+}
+export function aggregateBySlice(units) {
+    const map = new Map();
+    for (const u of units) {
+        const { milestone, slice } = parseUnitId(u.id);
+        const sliceId = slice ? `${milestone}/${slice}` : milestone;
+        let agg = map.get(sliceId);
+        if (!agg) {
+            agg = { sliceId, units: 0, tokens: emptyTokens(), cost: 0, duration: 0 };
+            map.set(sliceId, agg);
+        }
+        agg.units++;
+        agg.tokens = addTokens(agg.tokens, u.tokens);
+        agg.cost += u.cost;
+        agg.duration += u.finishedAt - u.startedAt;
+    }
+    return Array.from(map.values()).sort((a, b) => a.sliceId.localeCompare(b.sliceId));
+}
+export function aggregateByModel(units) {
+    const map = new Map();
+    for (const u of units) {
+        let agg = map.get(u.model);
+        if (!agg) {
+            agg = { model: u.model, units: 0, tokens: emptyTokens(), cost: 0 };
+            map.set(u.model, agg);
+        }
+        agg.units++;
+        agg.tokens = addTokens(agg.tokens, u.tokens);
+        agg.cost += u.cost;
+        if (u.contextWindowTokens !== undefined && agg.contextWindowTokens === undefined) {
+            agg.contextWindowTokens = u.contextWindowTokens;
+        }
+    }
+    return Array.from(map.values()).sort((a, b) => b.cost - a.cost);
+}
+export function getProjectTotals(units) {
+    const totals = {
+        units: units.length,
+        tokens: emptyTokens(),
+        cost: 0,
+        duration: 0,
+        toolCalls: 0,
+        assistantMessages: 0,
+        userMessages: 0,
+        apiRequests: 0,
+        totalTruncationSections: 0,
+        continueHereFiredCount: 0,
+    };
+    for (const u of units) {
+        totals.tokens = addTokens(totals.tokens, u.tokens);
+        totals.cost += u.cost;
+        totals.duration += u.finishedAt - u.startedAt;
+        totals.toolCalls += u.toolCalls;
+        totals.assistantMessages += u.assistantMessages;
+        totals.userMessages += u.userMessages;
+        totals.apiRequests += u.apiRequests ?? u.assistantMessages; // fallback for pre-existing data
+        totals.totalTruncationSections += u.truncationSections ?? 0;
+        if (u.continueHereFired)
+            totals.continueHereFiredCount++;
+    }
+    return totals;
+}
+export function aggregateByTier(units) {
+    const map = new Map();
+    for (const u of units) {
+        const tier = u.tier ?? "unknown";
+        let agg = map.get(tier);
+        if (!agg) {
+            agg = { tier, units: 0, tokens: emptyTokens(), cost: 0, downgraded: 0 };
+            map.set(tier, agg);
+        }
+        agg.units++;
+        agg.tokens = addTokens(agg.tokens, u.tokens);
+        agg.cost += u.cost;
+        if (u.modelDowngraded)
+            agg.downgraded++;
+    }
+    const order = ["light", "standard", "heavy", "unknown"];
+    return order.map(t => map.get(t)).filter((a) => !!a);
+}
+/**
+ * Format a summary of savings from dynamic routing.
+ * Returns empty string if no units were downgraded.
+ */
+export function formatTierSavings(units) {
+    const downgraded = units.filter(u => u.modelDowngraded);
+    if (downgraded.length === 0)
+        return "";
+    const downgradedCost = downgraded.reduce((sum, u) => sum + u.cost, 0);
+    const totalUnits = units.filter(u => u.tier).length;
+    const pct = totalUnits > 0 ? Math.round((downgraded.length / totalUnits) * 100) : 0;
+    return `Dynamic routing: ${downgraded.length}/${totalUnits} units downgraded (${pct}%), cost: ${formatCost(downgradedCost)}`;
+}
+/**
+ * Compute aggregate cache hit rate across all units.
+ * Returns percentage 0-100.
+ */
+export function aggregateCacheHitRate() {
+    if (!ledger || ledger.units.length === 0)
+        return 0;
+    let totalInput = 0;
+    let totalCacheRead = 0;
+    for (const unit of ledger.units) {
+        totalInput += unit.tokens.input;
+        totalCacheRead += unit.tokens.cacheRead;
+    }
+    const total = totalInput + totalCacheRead;
+    return total > 0 ? Math.round((totalCacheRead / total) * 100) : 0;
+}
+// ─── Formatting helpers ───────────────────────────────────────────────────────
+export function formatCost(cost) {
+    const n = Number(cost) || 0;
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    if (n < 1)
+        return `$${n.toFixed(3)}`;
+    return `$${n.toFixed(2)}`;
+}
+// ─── Budget Prediction ────────────────────────────────────────────────────────
+/**
+ * Calculate average cost per unit type from completed units.
+ * Returns a Map from unit type to average cost in USD.
+ */
+export function getAverageCostPerUnitType(units) {
+    const sums = new Map();
+    for (const u of units) {
+        const entry = sums.get(u.type) ?? { total: 0, count: 0 };
+        entry.total += u.cost;
+        entry.count += 1;
+        sums.set(u.type, entry);
+    }
+    const avgs = new Map();
+    for (const [type, { total, count }] of sums) {
+        avgs.set(type, total / count);
+    }
+    return avgs;
+}
+/**
+ * Estimate remaining cost given average costs and remaining unit counts.
+ * @param avgCosts - Average cost per unit type
+ * @param remainingUnits - Array of unit types still to dispatch
+ * @param fallbackAvg - Fallback average if unit type not seen before
+ * @returns Estimated remaining cost in USD
+ */
+export function predictRemainingCost(avgCosts, remainingUnits, fallbackAvg) {
+    // If no averages available, use overall average as fallback
+    const allAvgs = [...avgCosts.values()];
+    const overallAvg = fallbackAvg ?? (allAvgs.length > 0 ? allAvgs.reduce((a, b) => a + b, 0) / allAvgs.length : 0);
+    let total = 0;
+    for (const unitType of remainingUnits) {
+        total += avgCosts.get(unitType) ?? overallAvg;
+    }
+    return total;
+}
+/**
+ * Compute a projected remaining cost based on completed slice averages.
+ *
+ * Filters to slice-level entries (sliceId contains "/") to exclude bare milestone
+ * aggregates from the average. Returns [] when fewer than 2 slice-level entries
+ * exist (insufficient data for a reliable projection).
+ *
+ * If `budgetCeiling` is provided and `totalCost >= budgetCeiling`, a warning line
+ * is appended to the result.
+ */
+export function formatCostProjection(completedSlices, remainingCount, budgetCeiling) {
+    const sliceLevel = completedSlices.filter(s => s.sliceId.includes("/"));
+    if (sliceLevel.length < 2)
+        return [];
+    const totalCost = sliceLevel.reduce((sum, s) => sum + s.cost, 0);
+    const avgCost = totalCost / sliceLevel.length;
+    const projected = avgCost * remainingCount;
+    const projLine = `Projected remaining: ${formatCost(projected)} (${formatCost(avgCost)}/slice avg × ${remainingCount} remaining)`;
+    const result = [projLine];
+    if (budgetCeiling !== undefined && totalCost >= budgetCeiling) {
+        result.push(`Budget ceiling ${formatCost(budgetCeiling)} reached (spent ${formatCost(totalCost)})`);
+    }
+    return result;
+}
+// ─── Disk I/O ─────────────────────────────────────────────────────────────────
+function metricsPath(base) {
+    return join(gsdRoot(base), "metrics.json");
+}
+function isMetricsLedger(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        data.version === 1 &&
+        Array.isArray(data.units));
+}
+function defaultLedger() {
+    return { version: 1, projectStartedAt: Date.now(), units: [] };
+}
+/**
+ * Load ledger from disk without initializing in-memory state.
+ * Used by history/export commands outside of auto-mode.
+ */
+export function loadLedgerFromDisk(base) {
+    return loadJsonFileOrNull(metricsPath(base), isMetricsLedger);
+}
+function loadLedger(base) {
+    return loadJsonFile(metricsPath(base), isMetricsLedger, defaultLedger);
+}
+function saveLedger(base, data) {
+    saveJsonFile(metricsPath(base), data);
+}

package/dist/resources/extensions/gsd/migrate/command.js

@@ -0,0 +1,157 @@
+/**
+ * /gsd migrate — one-shot migration from .planning to .gsd
+ *
+ * Thin UX orchestrator: resolves paths, runs the validate → parse → transform →
+ * preview → write pipeline, and shows confirmation UI via showNextAction.
+ * All business logic lives in the pipeline modules (S01–S03).
+ *
+ * After a successful write, offers an agent-driven review that audits the
+ * output for GSD-2 standards compliance.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { gsdRoot } from "../paths.js";
+import { fileURLToPath } from "node:url";
+import { showNextAction } from "../../shared/mod.js";
+import { validatePlanningDirectory, parsePlanningDirectory, transformToGSD, generatePreview, writeGSDDirectory, } from "./index.js";
+/** Format preview stats for embedding in the review prompt. */
+function formatPreviewStats(preview) {
+    const lines = [
+        `- Milestones: ${preview.milestoneCount}`,
+        `- Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
+        `- Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
+    ];
+    if (preview.requirements.total > 0) {
+        lines.push(`- Requirements: ${preview.requirements.total} (${preview.requirements.validated} validated, ${preview.requirements.active} active, ${preview.requirements.deferred} deferred)`);
+    }
+    return lines.join("\n");
+}
+/** Load and interpolate the review-migration prompt template. */
+function buildReviewPrompt(sourcePath, gsdPath, preview) {
+    const promptsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "prompts");
+    const templatePath = join(promptsDir, "review-migration.md");
+    let content = readFileSync(templatePath, "utf-8");
+    content = content.replaceAll("{{sourcePath}}", sourcePath);
+    content = content.replaceAll("{{gsdPath}}", gsdPath);
+    content = content.replaceAll("{{previewStats}}", formatPreviewStats(preview));
+    return content.trim();
+}
+/** Dispatch the review prompt to the agent. */
+function dispatchReview(pi, sourcePath, gsdPath, preview) {
+    const prompt = buildReviewPrompt(sourcePath, gsdPath, preview);
+    pi.sendMessage({
+        customType: "gsd-migrate-review",
+        content: prompt,
+        display: false,
+    }, { triggerTurn: true });
+}
+export async function handleMigrate(args, ctx, pi) {
+    // ── Resolve source path ────────────────────────────────────────────────────
+    // Default to cwd when no args given; expand ~ to HOME
+    let rawPath = args.trim() || ".";
+    if (rawPath.startsWith("~/")) {
+        rawPath = join(process.env.HOME ?? "~", rawPath.slice(2));
+    }
+    else if (rawPath === "~") {
+        rawPath = process.env.HOME ?? "~";
+    }
+    let sourcePath = resolve(process.cwd(), rawPath);
+    if (!sourcePath.endsWith(".planning")) {
+        sourcePath = join(sourcePath, ".planning");
+    }
+    if (!existsSync(sourcePath)) {
+        ctx.ui.notify(`Directory not found: ${sourcePath}\n\n` +
+            'Migration converts a .planning/ directory (from older GSD versions) into .gsd/ format.\n' +
+            'If you are starting a new project, use /gsd:new-project instead.\n' +
+            'If migrating, ensure the path contains a .planning/ directory.', "error");
+        return;
+    }
+    // ── Validate ───────────────────────────────────────────────────────────────
+    const validation = await validatePlanningDirectory(sourcePath);
+    const warnings = validation.issues.filter((i) => i.severity === "warning");
+    const fatals = validation.issues.filter((i) => i.severity === "fatal");
+    for (const w of warnings) {
+        ctx.ui.notify(`⚠ ${w.message} (${w.file})`, "warning");
+    }
+    for (const f of fatals) {
+        ctx.ui.notify(`✖ ${f.message} (${f.file})`, "error");
+    }
+    if (!validation.valid) {
+        ctx.ui.notify("Migration blocked — fix the fatal issues above before retrying.", "error");
+        return;
+    }
+    // ── Parse → Transform → Preview ───────────────────────────────────────────
+    const parsed = await parsePlanningDirectory(sourcePath);
+    const project = transformToGSD(parsed);
+    const preview = generatePreview(project);
+    // ── Build preview text ─────────────────────────────────────────────────────
+    const lines = [
+        `Milestones: ${preview.milestoneCount}`,
+        `Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
+        `Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
+    ];
+    if (preview.requirements.total > 0) {
+        lines.push(`Requirements: ${preview.requirements.total} (${preview.requirements.validated} validated, ${preview.requirements.active} active, ${preview.requirements.deferred} deferred)`);
+    }
+    const targetGsdExists = existsSync(gsdRoot(process.cwd()));
+    if (targetGsdExists) {
+        lines.push("");
+        lines.push("⚠ A .gsd directory already exists in the current working directory — it will be overwritten.");
+    }
+    // ── Confirmation via showNextAction ────────────────────────────────────────
+    const choice = await showNextAction(ctx, {
+        title: "Migration preview",
+        summary: lines,
+        actions: [
+            {
+                id: "confirm",
+                label: "Write .gsd directory",
+                description: `Migrate ${preview.milestoneCount} milestone(s) to ${process.cwd()}/.gsd`,
+                recommended: true,
+            },
+            {
+                id: "cancel",
+                label: "Cancel",
+                description: "Exit without writing anything",
+            },
+        ],
+        notYetMessage: "Run /gsd migrate again when ready.",
+    });
+    if (choice !== "confirm") {
+        ctx.ui.notify("Migration cancelled — no files were written.", "info");
+        return;
+    }
+    // ── Write ──────────────────────────────────────────────────────────────────
+    ctx.ui.notify("Writing .gsd directory…", "info");
+    const result = await writeGSDDirectory(project, process.cwd());
+    const gsdPath = gsdRoot(process.cwd());
+    ctx.ui.notify(`✓ Migration complete — ${result.paths.length} file(s) written to .gsd/`, "info");
+    // ── Post-write review offer ────────────────────────────────────────────────
+    const reviewChoice = await showNextAction(ctx, {
+        title: "Migration written",
+        summary: [
+            `${result.paths.length} files written to .gsd/`,
+            "",
+            "The agent can now review the migrated output against GSD-2 standards —",
+            "checking structure, content quality, deriveState() round-trip, and",
+            "requirement statuses. It will fix minor issues in-place.",
+        ],
+        actions: [
+            {
+                id: "review",
+                label: "Review migration",
+                description: "Agent audits the .gsd output and reports PASS/FAIL per category",
+                recommended: true,
+            },
+            {
+                id: "skip",
+                label: "Skip review",
+                description: "Trust the migration output as-is",
+            },
+        ],
+        notYetMessage: "Run /gsd migrate again to re-migrate, or review .gsd manually.",
+    });
+    if (reviewChoice === "review") {
+        dispatchReview(pi, sourcePath, gsdPath, preview);
+    }
+}

package/dist/resources/extensions/gsd/migrate/index.js

@@ -0,0 +1,7 @@
+// Barrel export for old .planning migration module
+export { handleMigrate } from './command.js';
+export { parsePlanningDirectory } from './parser.js';
+export { validatePlanningDirectory } from './validator.js';
+export { transformToGSD } from './transformer.js';
+export { writeGSDDirectory } from './writer.js';
+export { generatePreview } from './preview.js';