gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/gsd/doctor-proactive.js

@@ -0,0 +1,239 @@
+/**
+ * GSD Doctor — Proactive Healing Layer
+ *
+ * Three mechanisms for automatic health monitoring during auto-mode:
+ *
+ * 1. Pre-dispatch health gate: lightweight check before each unit dispatch.
+ *    Returns blocking issues that should pause auto-mode rather than
+ *    dispatching into a broken state.
+ *
+ * 2. Health score tracking: tracks issue counts over time to detect
+ *    degradation trends. If health is declining, surfaces a warning.
+ *
+ * 3. Auto-heal escalation: if deterministic fix can't resolve issues
+ *    after N units, escalates to LLM-assisted heal dispatch.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { gsdRoot, resolveGsdRootFile } from "./paths.js";
+import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
+import { abortAndReset } from "./git-self-heal.js";
+import { rebuildState } from "./doctor.js";
+/** In-memory health history for the current auto-mode session. */
+let healthHistory = [];
+/** Count of consecutive units with unresolved errors. */
+let consecutiveErrorUnits = 0;
+/** Unit index counter for health tracking. */
+let healthUnitIndex = 0;
+/**
+ * Record a health snapshot after a doctor run.
+ * Called from the post-unit hook in auto.ts.
+ */
+export function recordHealthSnapshot(errors, warnings, fixesApplied) {
+    healthUnitIndex++;
+    healthHistory.push({
+        timestamp: Date.now(),
+        errors,
+        warnings,
+        fixesApplied,
+        unitIndex: healthUnitIndex,
+    });
+    // Keep only the last 50 snapshots to bound memory
+    if (healthHistory.length > 50) {
+        healthHistory = healthHistory.slice(-50);
+    }
+    if (errors > 0) {
+        consecutiveErrorUnits++;
+    }
+    else {
+        consecutiveErrorUnits = 0;
+    }
+}
+/**
+ * Get the current health trend.
+ * Returns "improving", "stable", "degrading", or "unknown" (not enough data).
+ */
+export function getHealthTrend() {
+    if (healthHistory.length < 3)
+        return "unknown";
+    const recent = healthHistory.slice(-5);
+    const older = healthHistory.slice(-10, -5);
+    if (older.length === 0)
+        return "unknown";
+    const recentAvg = recent.reduce((sum, s) => sum + s.errors + s.warnings, 0) / recent.length;
+    const olderAvg = older.reduce((sum, s) => sum + s.errors + s.warnings, 0) / older.length;
+    const delta = recentAvg - olderAvg;
+    if (delta > 1)
+        return "degrading";
+    if (delta < -1)
+        return "improving";
+    return "stable";
+}
+/**
+ * Get the number of consecutive units with unresolved errors.
+ */
+export function getConsecutiveErrorUnits() {
+    return consecutiveErrorUnits;
+}
+/**
+ * Get health history for display (e.g., dashboard overlay).
+ */
+export function getHealthHistory() {
+    return healthHistory;
+}
+/**
+ * Reset health tracking state. Called on auto-mode start/stop.
+ */
+export function resetHealthTracking() {
+    healthHistory = [];
+    consecutiveErrorUnits = 0;
+    healthUnitIndex = 0;
+}
+/**
+ * Lightweight pre-dispatch health check. Runs fast checks that should
+ * block dispatch if they fail — avoids dispatching into a broken state.
+ *
+ * This is NOT a full doctor run — it only checks critical, fast-to-evaluate
+ * conditions that would cause the next unit to fail or corrupt state.
+ *
+ * Returns { proceed: true } if dispatch should continue.
+ */
+export async function preDispatchHealthGate(basePath) {
+    const issues = [];
+    const fixesApplied = [];
+    // ── Stale crash lock blocks dispatch ──
+    // If a stale lock exists, the crash recovery path should handle it,
+    // not a new dispatch. This prevents double-dispatch after crashes.
+    try {
+        const lock = readCrashLock(basePath);
+        if (lock && !isLockProcessAlive(lock)) {
+            // Auto-clear it since we're about to dispatch anyway
+            clearLock(basePath);
+            fixesApplied.push("cleared stale auto.lock before dispatch");
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    // ── Corrupt merge/rebase state blocks dispatch ──
+    // Dispatching a unit with MERGE_HEAD present will cause git operations to fail.
+    try {
+        const gitDir = join(basePath, ".git");
+        if (existsSync(gitDir)) {
+            const blockers = ["MERGE_HEAD", "rebase-apply", "rebase-merge"].filter(f => existsSync(join(gitDir, f)));
+            if (blockers.length > 0) {
+                // Try to auto-heal
+                try {
+                    const result = abortAndReset(basePath);
+                    fixesApplied.push(`pre-dispatch: cleaned merge state (${result.cleaned.join(", ")})`);
+                }
+                catch {
+                    issues.push(`Corrupt git state: ${blockers.join(", ")}. Run /gsd doctor fix.`);
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    // ── STATE.md existence check ──
+    // If STATE.md is missing, attempt to rebuild it for the next unit's context.
+    // Non-blocking — fresh worktrees won't have it until the first unit completes (#889).
+    try {
+        const stateFile = resolveGsdRootFile(basePath, "STATE");
+        const milestonesDir = join(gsdRoot(basePath), "milestones");
+        if (existsSync(milestonesDir) && !existsSync(stateFile)) {
+            try {
+                await rebuildState(basePath);
+                fixesApplied.push("rebuilt missing STATE.md before dispatch");
+            }
+            catch {
+                // Rebuild failed — non-blocking, dispatch continues
+                fixesApplied.push("STATE.md missing — will rebuild after first unit completes");
+            }
+        }
+    }
+    catch {
+        // Non-fatal — dispatch continues without STATE.md if rebuild fails
+    }
+    // If we had critical issues that couldn't be auto-healed, block dispatch
+    if (issues.length > 0) {
+        return {
+            proceed: false,
+            reason: `Pre-dispatch health check failed:\n${issues.map(i => `  - ${i}`).join("\n")}\nRun /gsd doctor fix to resolve.`,
+            issues,
+            fixesApplied,
+        };
+    }
+    return { proceed: true, issues, fixesApplied };
+}
+// ── Auto-Heal Escalation ──────────────────────────────────────────────────
+/** Threshold: escalate to LLM heal after this many consecutive error units. */
+const ESCALATION_THRESHOLD = 5;
+/** Whether an escalation has already been triggered this session (prevent spam). */
+let escalationTriggered = false;
+/**
+ * Check whether auto-heal should escalate from deterministic fix to
+ * LLM-assisted heal. Called after each post-unit doctor run.
+ *
+ * Returns the structured issue text for LLM dispatch, or null if
+ * escalation is not needed.
+ */
+export function checkHealEscalation(errors, unresolvedIssues) {
+    if (escalationTriggered) {
+        return { shouldEscalate: false, reason: "already escalated this session", issues: [] };
+    }
+    if (consecutiveErrorUnits < ESCALATION_THRESHOLD) {
+        return {
+            shouldEscalate: false,
+            reason: `${consecutiveErrorUnits}/${ESCALATION_THRESHOLD} consecutive error units`,
+            issues: [],
+        };
+    }
+    if (errors === 0) {
+        return { shouldEscalate: false, reason: "no errors to escalate", issues: [] };
+    }
+    const trend = getHealthTrend();
+    if (trend === "improving") {
+        return { shouldEscalate: false, reason: "health is improving — deferring escalation", issues: [] };
+    }
+    escalationTriggered = true;
+    return {
+        shouldEscalate: true,
+        reason: `${consecutiveErrorUnits} consecutive units with unresolved errors (trend: ${trend})`,
+        issues: unresolvedIssues,
+    };
+}
+/**
+ * Reset escalation state. Called on auto-mode start/stop.
+ */
+export function resetEscalation() {
+    escalationTriggered = false;
+}
+/**
+ * Format a health summary for display in the auto-mode dashboard.
+ */
+export function formatHealthSummary() {
+    if (healthHistory.length === 0)
+        return "No health data yet.";
+    const latest = healthHistory[healthHistory.length - 1];
+    const trend = getHealthTrend();
+    const trendIcon = trend === "improving" ? "+" : trend === "degrading" ? "-" : "=";
+    const totalFixes = healthHistory.reduce((sum, s) => sum + s.fixesApplied, 0);
+    const parts = [
+        `Health: ${latest.errors}E/${latest.warnings}W`,
+        `trend:${trendIcon}`,
+        `fixes:${totalFixes}`,
+    ];
+    if (consecutiveErrorUnits > 0) {
+        parts.push(`streak:${consecutiveErrorUnits}/${ESCALATION_THRESHOLD}`);
+    }
+    return parts.join(" | ");
+}
+/**
+ * Reset all proactive healing state. Called on auto-mode start/stop.
+ */
+export function resetProactiveHealing() {
+    resetHealthTracking();
+    resetEscalation();
+}

package/dist/resources/extensions/gsd/doctor-providers.js

@@ -0,0 +1,292 @@
+/**
+ * GSD Doctor — Provider & Integration Health Checks
+ *
+ * Fast, deterministic checks for external service configuration.
+ * Checks key presence in auth.json and environment variables — no HTTP calls,
+ * no network I/O, always sub-10ms.
+ *
+ * Covers:
+ *   - LLM providers required by the effective model preferences (per phase)
+ *   - Remote questions channel if configured (Slack/Discord/Telegram token)
+ *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
+ */
+import { existsSync } from "node:fs";
+import { AuthStorage } from "@gsd/pi-coding-agent";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getAuthPath, PROVIDER_REGISTRY } from "./key-manager.js";
+// ── Model → Provider ID mapping ───────────────────────────────────────────────
+/**
+ * Infer the auth provider ID from a model string.
+ * Handles plain model IDs ("claude-sonnet-4-6") and prefixed ones ("openrouter/deepseek").
+ */
+function modelToProviderId(model) {
+    if (!model)
+        return null;
+    // Explicit provider prefix (e.g. "openrouter/deepseek-r1")
+    if (model.includes("/")) {
+        const prefix = model.split("/")[0].toLowerCase();
+        // Map known prefixes to registry IDs
+        const prefixMap = {
+            openrouter: "openrouter",
+            groq: "groq",
+            mistral: "mistral",
+            google: "google",
+            anthropic: "anthropic",
+            openai: "openai",
+        };
+        if (prefixMap[prefix])
+            return prefixMap[prefix];
+    }
+    const lower = model.toLowerCase();
+    if (lower.startsWith("claude"))
+        return "anthropic";
+    if (lower.startsWith("gpt-") || lower.startsWith("o1") || lower.startsWith("o3"))
+        return "openai";
+    if (lower.startsWith("gemini"))
+        return "google";
+    if (lower.startsWith("llama") || lower.startsWith("mixtral"))
+        return "groq";
+    if (lower.startsWith("grok"))
+        return "xai";
+    if (lower.startsWith("mistral") || lower.startsWith("codestral"))
+        return "mistral";
+    return null;
+}
+/** Collect all model strings from effective preferences across all phases. */
+function collectConfiguredModelProviders() {
+    const providers = new Set();
+    try {
+        const loaded = loadEffectiveGSDPreferences();
+        const models = loaded?.preferences?.models;
+        if (!models) {
+            // Default: Anthropic
+            providers.add("anthropic");
+            return providers;
+        }
+        const modelEntries = typeof models === "object" ? Object.values(models) : [];
+        for (const entry of modelEntries) {
+            const modelId = typeof entry === "string" ? entry
+                : typeof entry === "object" && entry !== null && "model" in entry
+                    ? String(entry.model)
+                    : null;
+            if (modelId) {
+                const pid = modelToProviderId(modelId);
+                if (pid)
+                    providers.add(pid);
+            }
+        }
+    }
+    catch {
+        // Preferences not readable — assume Anthropic as default
+        providers.add("anthropic");
+    }
+    if (providers.size === 0)
+        providers.add("anthropic");
+    return providers;
+}
+function resolveKey(providerId) {
+    const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+    // Check auth.json
+    const authPath = getAuthPath();
+    if (existsSync(authPath)) {
+        try {
+            const auth = AuthStorage.create(authPath);
+            const creds = auth.getCredentialsForProvider(providerId);
+            if (creds.length > 0) {
+                // Filter out empty placeholder keys (from skipped onboarding)
+                const hasRealKey = creds.some(c => c.type === "oauth" || (c.type === "api_key" && c.key));
+                if (hasRealKey) {
+                    return {
+                        found: true,
+                        source: "auth.json",
+                        backedOff: auth.areAllCredentialsBackedOff(providerId),
+                    };
+                }
+            }
+        }
+        catch {
+            // auth.json malformed — fall through to env check
+        }
+    }
+    // Check environment variable
+    if (info?.envVar && process.env[info.envVar]) {
+        return { found: true, source: "env", backedOff: false };
+    }
+    return { found: false, source: "none", backedOff: false };
+}
+// ── Individual check groups ────────────────────────────────────────────────────
+function checkLlmProviders() {
+    const required = collectConfiguredModelProviders();
+    const results = [];
+    for (const providerId of required) {
+        const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+        const label = info?.label ?? providerId;
+        const lookup = resolveKey(providerId);
+        if (!lookup.found) {
+            const envVar = info?.envVar ?? `${providerId.toUpperCase()}_API_KEY`;
+            results.push({
+                name: providerId,
+                label,
+                category: "llm",
+                status: "error",
+                message: `${label} — no API key found`,
+                detail: info?.hasOAuth
+                    ? `Run /gsd keys to authenticate`
+                    : `Set ${envVar} or run /gsd keys`,
+                required: true,
+            });
+        }
+        else if (lookup.backedOff) {
+            results.push({
+                name: providerId,
+                label,
+                category: "llm",
+                status: "warning",
+                message: `${label} — all credentials backed off (rate limited)`,
+                detail: `GSD will retry automatically`,
+                required: true,
+            });
+        }
+        else {
+            results.push({
+                name: providerId,
+                label,
+                category: "llm",
+                status: "ok",
+                message: `${label} — key present (${lookup.source})`,
+                required: true,
+            });
+        }
+    }
+    return results;
+}
+function checkRemoteQuestionsProvider() {
+    try {
+        const loaded = loadEffectiveGSDPreferences();
+        const rq = loaded?.preferences?.remote_questions;
+        if (!rq)
+            return null;
+        const channel = rq.channel;
+        if (!channel)
+            return null;
+        const providerMap = {
+            slack: "slack_bot",
+            discord: "discord_bot",
+            telegram: "telegram_bot",
+        };
+        const providerId = providerMap[channel.toLowerCase()];
+        if (!providerId)
+            return null;
+        const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+        const label = info?.label ?? channel;
+        const lookup = resolveKey(providerId);
+        if (!lookup.found) {
+            return {
+                name: providerId,
+                label,
+                category: "remote",
+                status: "warning",
+                message: `${label} — channel configured but token not found`,
+                detail: info?.envVar ? `Set ${info.envVar} or run /gsd keys` : `Run /gsd keys to configure`,
+                required: true,
+            };
+        }
+        return {
+            name: providerId,
+            label,
+            category: "remote",
+            status: "ok",
+            message: `${label} — token present (${lookup.source})`,
+            required: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function checkOptionalProviders() {
+    const optional = ["brave", "tavily", "jina", "context7"];
+    const results = [];
+    for (const providerId of optional) {
+        const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+        if (!info)
+            continue;
+        const lookup = resolveKey(providerId);
+        results.push({
+            name: providerId,
+            label: info.label,
+            category: info.category,
+            status: lookup.found ? "ok" : "unconfigured",
+            message: lookup.found
+                ? `${info.label} — key present (${lookup.source})`
+                : `${info.label} — not configured (optional)`,
+            detail: !lookup.found && info.envVar ? `Set ${info.envVar} to enable` : undefined,
+            required: false,
+        });
+    }
+    return results;
+}
+// ── Public API ─────────────────────────────────────────────────────────────────
+/**
+ * Run all provider checks: required LLM keys, remote questions channel, optional tools.
+ * Fast (sub-10ms) — reads auth.json and env vars only, no network I/O.
+ */
+export function runProviderChecks() {
+    const results = [];
+    results.push(...checkLlmProviders());
+    const remoteCheck = checkRemoteQuestionsProvider();
+    if (remoteCheck)
+        results.push(remoteCheck);
+    results.push(...checkOptionalProviders());
+    return results;
+}
+/**
+ * Format provider check results as a human-readable report string.
+ */
+export function formatProviderReport(results) {
+    if (results.length === 0)
+        return "No provider checks run.";
+    const lines = [];
+    const groups = {};
+    for (const r of results) {
+        (groups[r.category] ??= []).push(r);
+    }
+    const categoryLabels = {
+        llm: "LLM Providers",
+        remote: "Notifications",
+        search: "Search",
+        tool: "Tools",
+    };
+    for (const [cat, items] of Object.entries(groups)) {
+        lines.push(`${categoryLabels[cat] ?? cat}:`);
+        for (const item of items) {
+            const icon = item.status === "ok" ? "✓"
+                : item.status === "warning" ? "⚠"
+                    : item.status === "error" ? "✗"
+                        : "·";
+            lines.push(`  ${icon} ${item.message}`);
+            if (item.detail && item.status !== "ok") {
+                lines.push(`    ${item.detail}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Summarise check results to a compact widget-friendly string.
+ * Returns null if all required providers are ok.
+ */
+export function summariseProviderIssues(results) {
+    const errors = results.filter(r => r.required && r.status === "error");
+    const warnings = results.filter(r => r.required && r.status === "warning");
+    if (errors.length === 0 && warnings.length === 0)
+        return null;
+    const parts = [];
+    if (errors.length > 0)
+        parts.push(`✗ ${errors[0].label} key missing`);
+    if (warnings.length > 0 && errors.length === 0)
+        parts.push(`⚠ ${warnings[0].label} backed off`);
+    if (errors.length + warnings.length > 1)
+        parts.push(`(+${errors.length + warnings.length - 1} more)`);
+    return parts.join(" ");
+}

package/dist/resources/extensions/gsd/doctor-types.js

@@ -0,0 +1,12 @@
+/**
+ * Issue codes that represent expected completion-transition states.
+ * These are detected by the doctor but should NOT be auto-fixed at task level —
+ * they are resolved by the complete-slice/complete-milestone dispatch units.
+ * Consumers (e.g. auto-post-unit health tracking) should exclude these from
+ * error counts when running at task fixLevel to avoid false escalation.
+ */
+export const COMPLETION_TRANSITION_CODES = new Set([
+    "all_tasks_done_missing_slice_summary",
+    "all_tasks_done_missing_slice_uat",
+    "all_tasks_done_roadmap_not_checked",
+]);