gsd-pi 2.18.0 → 2.19.0

package/dist/resources/extensions/gsd/model-router.ts

@@ -0,0 +1,256 @@
+// GSD Extension — Dynamic Model Router
+// Maps complexity tiers to models, enforcing downgrade-only semantics.
+// The user's configured model is always the ceiling.
+
+import type { ComplexityTier, ClassificationResult } from "./complexity-classifier.js";
+import { tierOrdinal } from "./complexity-classifier.js";
+import type { ResolvedModelConfig } from "./preferences.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface DynamicRoutingConfig {
+  enabled?: boolean;
+  tier_models?: {
+    light?: string;
+    standard?: string;
+    heavy?: string;
+  };
+  escalate_on_failure?: boolean;   // default: true
+  budget_pressure?: boolean;       // default: true
+  cross_provider?: boolean;        // default: true
+  hooks?: boolean;                 // default: true
+}
+
+export interface RoutingDecision {
+  /** The model ID to use (may be downgraded from configured) */
+  modelId: string;
+  /** Fallback chain: [selected_model, ...configured_fallbacks, configured_primary] */
+  fallbacks: string[];
+  /** The complexity tier that drove this decision */
+  tier: ComplexityTier;
+  /** True if the model was downgraded from the configured primary */
+  wasDowngraded: boolean;
+  /** Human-readable reason for this decision */
+  reason: string;
+}
+
+// ─── Known Model Tiers ───────────────────────────────────────────────────────
+// Maps known model IDs to their capability tier. Used when tier_models is not
+// explicitly configured to pick the best available model for each tier.
+
+const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
+  // Light-tier models (cheapest)
+  "claude-haiku-4-5": "light",
+  "claude-3-5-haiku-latest": "light",
+  "claude-3-haiku-20240307": "light",
+  "gpt-4o-mini": "light",
+  "gemini-2.0-flash": "light",
+  "gemini-flash-2.0": "light",
+
+  // Standard-tier models
+  "claude-sonnet-4-6": "standard",
+  "claude-sonnet-4-5-20250514": "standard",
+  "claude-3-5-sonnet-latest": "standard",
+  "gpt-4o": "standard",
+  "gemini-2.5-pro": "standard",
+  "deepseek-chat": "standard",
+
+  // Heavy-tier models (most capable)
+  "claude-opus-4-6": "heavy",
+  "claude-3-opus-latest": "heavy",
+  "gpt-4-turbo": "heavy",
+  "o1": "heavy",
+  "o3": "heavy",
+};
+
+// ─── Cost Table (per 1K input tokens, approximate USD) ───────────────────────
+// Used for cross-provider cost comparison when multiple providers offer
+// the same capability tier.
+
+const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
+  "claude-haiku-4-5": 0.0008,
+  "claude-3-5-haiku-latest": 0.0008,
+  "claude-sonnet-4-6": 0.003,
+  "claude-sonnet-4-5-20250514": 0.003,
+  "claude-opus-4-6": 0.015,
+  "gpt-4o-mini": 0.00015,
+  "gpt-4o": 0.0025,
+  "gemini-2.0-flash": 0.0001,
+  "gemini-2.5-pro": 0.00125,
+  "deepseek-chat": 0.00014,
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the model to use for a given complexity tier.
+ *
+ * Downgrade-only: the returned model is always equal to or cheaper than
+ * the user's configured primary model. Never upgrades beyond configuration.
+ *
+ * @param classification  The complexity classification result
+ * @param phaseConfig     The user's configured model for this phase (ceiling)
+ * @param routingConfig   Dynamic routing configuration
+ * @param availableModelIds  List of available model IDs (from registry)
+ */
+export function resolveModelForComplexity(
+  classification: ClassificationResult,
+  phaseConfig: ResolvedModelConfig | undefined,
+  routingConfig: DynamicRoutingConfig,
+  availableModelIds: string[],
+): RoutingDecision {
+  // If no phase config or routing disabled, pass through
+  if (!phaseConfig || !routingConfig.enabled) {
+    return {
+      modelId: phaseConfig?.primary ?? "",
+      fallbacks: phaseConfig?.fallbacks ?? [],
+      tier: classification.tier,
+      wasDowngraded: false,
+      reason: "dynamic routing disabled or no phase config",
+    };
+  }
+
+  const configuredPrimary = phaseConfig.primary;
+  const configuredTier = getModelTier(configuredPrimary);
+  const requestedTier = classification.tier;
+
+  // Downgrade-only: if requested tier >= configured tier, no change
+  if (tierOrdinal(requestedTier) >= tierOrdinal(configuredTier)) {
+    return {
+      modelId: configuredPrimary,
+      fallbacks: phaseConfig.fallbacks,
+      tier: requestedTier,
+      wasDowngraded: false,
+      reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+    };
+  }
+
+  // Find the best model for the requested tier
+  const targetModelId = findModelForTier(
+    requestedTier,
+    routingConfig,
+    availableModelIds,
+    routingConfig.cross_provider !== false,
+  );
+
+  if (!targetModelId) {
+    // No suitable model found — use configured primary
+    return {
+      modelId: configuredPrimary,
+      fallbacks: phaseConfig.fallbacks,
+      tier: requestedTier,
+      wasDowngraded: false,
+      reason: `no ${requestedTier}-tier model available`,
+    };
+  }
+
+  // Build fallback chain: [downgraded_model, ...configured_fallbacks, configured_primary]
+  const fallbacks = [
+    ...phaseConfig.fallbacks.filter(f => f !== targetModelId),
+    configuredPrimary,
+  ].filter(f => f !== targetModelId);
+
+  return {
+    modelId: targetModelId,
+    fallbacks,
+    tier: requestedTier,
+    wasDowngraded: true,
+    reason: classification.reason,
+  };
+}
+
+/**
+ * Escalate to the next tier after a failure.
+ * Returns the new tier, or null if already at heavy (max).
+ */
+export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null {
+  switch (currentTier) {
+    case "light": return "standard";
+    case "standard": return "heavy";
+    case "heavy": return null;
+  }
+}
+
+/**
+ * Get the default routing config (all features enabled).
+ */
+export function defaultRoutingConfig(): DynamicRoutingConfig {
+  return {
+    enabled: false,
+    escalate_on_failure: true,
+    budget_pressure: true,
+    cross_provider: true,
+    hooks: true,
+  };
+}
+
+// ─── Internal ────────────────────────────────────────────────────────────────
+
+function getModelTier(modelId: string): ComplexityTier {
+  // Strip provider prefix if present
+  const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+
+  // Check exact match first
+  if (MODEL_CAPABILITY_TIER[bareId]) return MODEL_CAPABILITY_TIER[bareId];
+
+  // Check if any known model ID is a prefix/suffix match
+  for (const [knownId, tier] of Object.entries(MODEL_CAPABILITY_TIER)) {
+    if (bareId.includes(knownId) || knownId.includes(bareId)) return tier;
+  }
+
+  // Unknown models are assumed heavy (safest assumption)
+  return "heavy";
+}
+
+function findModelForTier(
+  tier: ComplexityTier,
+  config: DynamicRoutingConfig,
+  availableModelIds: string[],
+  crossProvider: boolean,
+): string | null {
+  // 1. Check explicit tier_models config
+  const explicitModel = config.tier_models?.[tier];
+  if (explicitModel && availableModelIds.includes(explicitModel)) {
+    return explicitModel;
+  }
+  // Also check with provider prefix stripped
+  if (explicitModel) {
+    const match = availableModelIds.find(id => {
+      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
+      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
+      return bareAvail === bareExplicit;
+    });
+    if (match) return match;
+  }
+
+  // 2. Auto-detect: find the cheapest available model in the requested tier
+  const candidates = availableModelIds
+    .filter(id => {
+      const modelTier = getModelTier(id);
+      return modelTier === tier;
+    })
+    .sort((a, b) => {
+      if (!crossProvider) return 0;
+      const costA = getModelCost(a);
+      const costB = getModelCost(b);
+      return costA - costB;
+    });
+
+  return candidates[0] ?? null;
+}
+
+function getModelCost(modelId: string): number {
+  const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+
+  if (MODEL_COST_PER_1K_INPUT[bareId] !== undefined) {
+    return MODEL_COST_PER_1K_INPUT[bareId];
+  }
+
+  // Check partial matches
+  for (const [knownId, cost] of Object.entries(MODEL_COST_PER_1K_INPUT)) {
+    if (bareId.includes(knownId) || knownId.includes(bareId)) return cost;
+  }
+
+  // Unknown cost — assume expensive to avoid routing to unknown cheap models
+  return 999;
+}

package/dist/resources/extensions/gsd/post-unit-hooks.ts

@@ -60,7 +60,8 @@ export function checkPostUnitHooks(
   }
 
   // Don't trigger hooks for other hook units (prevent hook-on-hook chains)
-  if (completedUnitType.startsWith("hook/")) return null;
+  // Don't trigger hooks for triage units (prevent hook-on-triage chains)
+  if (completedUnitType.startsWith("hook/") || completedUnitType === "triage-captures") return null;
 
   // Check if any hooks are configured for this unit type
   const hooks = resolvePostUnitHooks().filter(h =>

package/dist/resources/extensions/gsd/preferences.ts

@@ -4,6 +4,8 @@ import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
 import type { GitPreferences } from "./git-service.js";
 import type { PostUnitHookConfig, PreDispatchHookConfig, BudgetEnforcementMode, NotificationPreferences, TokenProfile, InlineLevel, PhaseSkipPreferences } from "./types.js";
+import type { DynamicRoutingConfig } from "./model-router.js";
+import { defaultRoutingConfig } from "./model-router.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
@@ -36,8 +38,10 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "git",
   "post_unit_hooks",
   "pre_dispatch_hooks",
+  "dynamic_routing",
   "token_profile",
   "phases",
+  "auto_visualize",
 ]);
 
 export interface GSDSkillRule {
@@ -128,8 +132,10 @@ export interface GSDPreferences {
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
+  dynamic_routing?: DynamicRoutingConfig;
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
+  auto_visualize?: boolean;
 }
 
 export interface LoadedGSDPreferences {
@@ -674,6 +680,20 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
   };
 }
 
+/**
+ * Resolve the dynamic routing configuration from effective preferences.
+ * Returns the merged config with defaults applied.
+ */
+export function resolveDynamicRoutingConfig(): DynamicRoutingConfig {
+  const prefs = loadEffectiveGSDPreferences();
+  const configured = prefs?.preferences.dynamic_routing;
+  if (!configured) return defaultRoutingConfig();
+  return {
+    ...defaultRoutingConfig(),
+    ...configured,
+  };
+}
+
 export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
   const prefs = loadEffectiveGSDPreferences();
   const configured = prefs?.preferences.auto_supervisor ?? {};
@@ -780,6 +800,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       : undefined,
     post_unit_hooks: mergePostUnitHooks(base.post_unit_hooks, override.post_unit_hooks),
     pre_dispatch_hooks: mergePreDispatchHooks(base.pre_dispatch_hooks, override.pre_dispatch_hooks),
+    dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
+      ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) } as DynamicRoutingConfig
+      : undefined,
     token_profile: override.token_profile ?? base.token_profile,
     phases: (base.phases || override.phases)
       ? { ...(base.phases ?? {}), ...(override.phases ?? {}) }
@@ -1100,6 +1123,56 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Dynamic Routing ─────────────────────────────────────────────────
+  if (preferences.dynamic_routing !== undefined) {
+    if (typeof preferences.dynamic_routing === "object" && preferences.dynamic_routing !== null) {
+      const dr = preferences.dynamic_routing as unknown as Record<string, unknown>;
+      const validDr: Partial<DynamicRoutingConfig> = {};
+
+      if (dr.enabled !== undefined) {
+        if (typeof dr.enabled === "boolean") validDr.enabled = dr.enabled;
+        else errors.push("dynamic_routing.enabled must be a boolean");
+      }
+      if (dr.escalate_on_failure !== undefined) {
+        if (typeof dr.escalate_on_failure === "boolean") validDr.escalate_on_failure = dr.escalate_on_failure;
+        else errors.push("dynamic_routing.escalate_on_failure must be a boolean");
+      }
+      if (dr.budget_pressure !== undefined) {
+        if (typeof dr.budget_pressure === "boolean") validDr.budget_pressure = dr.budget_pressure;
+        else errors.push("dynamic_routing.budget_pressure must be a boolean");
+      }
+      if (dr.cross_provider !== undefined) {
+        if (typeof dr.cross_provider === "boolean") validDr.cross_provider = dr.cross_provider;
+        else errors.push("dynamic_routing.cross_provider must be a boolean");
+      }
+      if (dr.hooks !== undefined) {
+        if (typeof dr.hooks === "boolean") validDr.hooks = dr.hooks;
+        else errors.push("dynamic_routing.hooks must be a boolean");
+      }
+      if (dr.tier_models !== undefined) {
+        if (typeof dr.tier_models === "object" && dr.tier_models !== null) {
+          const tm = dr.tier_models as Record<string, unknown>;
+          const validTm: Record<string, string> = {};
+          for (const tier of ["light", "standard", "heavy"]) {
+            if (tm[tier] !== undefined) {
+              if (typeof tm[tier] === "string") validTm[tier] = tm[tier] as string;
+              else errors.push(`dynamic_routing.tier_models.${tier} must be a string`);
+            }
+          }
+          if (Object.keys(validTm).length > 0) validDr.tier_models = validTm as DynamicRoutingConfig["tier_models"];
+        } else {
+          errors.push("dynamic_routing.tier_models must be an object");
+        }
+      }
+
+      if (Object.keys(validDr).length > 0) {
+        validated.dynamic_routing = validDr as unknown as DynamicRoutingConfig;
+      }
+    } else {
+      errors.push("dynamic_routing must be an object");
+    }
+  }
+
   // ─── Git Preferences ───────────────────────────────────────────────────
   if (preferences.git && typeof preferences.git === "object") {
     const git: Record<string, unknown> = {};

package/dist/resources/extensions/gsd/prompt-loader.ts

@@ -7,15 +7,17 @@
  * Templates live at prompts/ relative to this module's directory.
  * They use {{variableName}} syntax for substitution.
  *
- * Templates are cached on first read per session. This prevents a running
- * session from being invalidated when another `gsd` launch overwrites
- * ~/.gsd/agent/ with newer templates via initResources(). Without caching,
- * the in-memory extension code (which knows variable set A) can read a
- * newer template from disk (which expects variable set B), causing a
- * "template declares {{X}} but no value was provided" crash mid-session.
+ * All templates are eagerly loaded into cache at module init via warmCache().
+ * This prevents a running session from being invalidated when another `gsd`
+ * launch overwrites ~/.gsd/agent/ with newer templates via initResources().
+ * Without eager caching, the in-memory extension code (which knows variable
+ * set A) can read a newer template from disk (which expects variable set B),
+ * causing a "template declares {{X}} but no value was provided" crash
+ * mid-session — especially for late-loading templates like complete-milestone
+ * that aren't read until the end of a long auto-mode run.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -23,10 +25,44 @@ const __extensionDir = dirname(fileURLToPath(import.meta.url));
 const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
 
-// Cache templates on first read — a running session uses the template versions
-// that were on disk when it first loaded them, immune to later overwrites.
+// Cache all templates eagerly at module load — a running session uses the
+// template versions that were on disk at startup, immune to later overwrites.
 const templateCache = new Map<string, string>();
 
+/**
+ * Eagerly read all .md files from prompts/ and templates/ into cache.
+ * Called once at module init so that every template is snapshot before
+ * a concurrent initResources() can overwrite files on disk.
+ */
+function warmCache(): void {
+  try {
+    for (const file of readdirSync(promptsDir)) {
+      if (!file.endsWith(".md")) continue;
+      const name = file.slice(0, -3);
+      if (!templateCache.has(name)) {
+        templateCache.set(name, readFileSync(join(promptsDir, file), "utf-8"));
+      }
+    }
+  } catch {
+    // prompts/ may not exist in test environments — lazy loading still works
+  }
+
+  try {
+    for (const file of readdirSync(templatesDir)) {
+      if (!file.endsWith(".md")) continue;
+      const cacheKey = `tpl:${file.slice(0, -3)}`;
+      if (!templateCache.has(cacheKey)) {
+        templateCache.set(cacheKey, readFileSync(join(templatesDir, file), "utf-8"));
+      }
+    }
+  } catch {
+    // templates/ may not exist in test environments — lazy loading still works
+  }
+}
+
+// Snapshot all templates at module load time
+warmCache();
+
 /**
  * Load a prompt template and substitute variables.
  *

package/dist/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -16,6 +16,12 @@ All relevant context has been preloaded below — the current roadmap, completed
 
 {{inlinedContext}}
 
+## Deferred Captures
+
+The following user thoughts were captured during execution and deferred to future slices during triage. Consider whether any should influence the remaining roadmap:
+
+{{deferredCaptures}}
+
 If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during reassessment, without relaxing required verification or artifact rules.
 
 Then assess whether the remaining roadmap still makes sense given what was just built.

package/dist/resources/extensions/gsd/prompts/replan-slice.md

@@ -12,6 +12,14 @@ All relevant context has been preloaded below — the roadmap, current slice pla
 
 {{inlinedContext}}
 
+## Capture Context
+
+The following user-captured thoughts triggered or informed this replan:
+
+{{captureContext}}
+
+Consider these captures when rewriting the remaining tasks — they represent the user's real-time insights about what needs to change.
+
 ## Hard Constraints
 
 - **Do NOT renumber or remove completed tasks.** All `[x]` tasks and their IDs must remain exactly as they are in the plan.

package/dist/resources/extensions/gsd/prompts/triage-captures.md

@@ -0,0 +1,62 @@
+You are triaging user-captured thoughts during a GSD session.
+
+## UNIT: Triage Captures
+
+The user captured thoughts during execution using `/gsd capture`. Your job is to classify each capture, present your proposals, get user confirmation, and update CAPTURES.md with the final classifications.
+
+## Pending Captures
+
+{{pendingCaptures}}
+
+## Current Slice Plan
+
+{{currentPlan}}
+
+## Current Roadmap
+
+{{roadmapContext}}
+
+## Classification Criteria
+
+For each capture, classify it as one of:
+
+- **quick-task**: Small, self-contained, no downstream impact. Can be done in minutes without modifying the plan. Examples: fix a typo, add a missing import, tweak a config value.
+- **inject**: Belongs in the current slice but wasn't planned. Needs a new task added to the slice plan. Examples: add error handling to a module being built, add a missing test case for current work.
+- **defer**: Belongs in a future slice or milestone. Not urgent for current work. Examples: performance optimization, feature that depends on unbuilt infrastructure, nice-to-have enhancement.
+- **replan**: Changes the shape of remaining work in the current slice. Existing incomplete tasks may need rewriting. Examples: "the approach is wrong, we need to use X instead of Y", discovering a fundamental constraint.
+- **note**: Informational only. No action needed right now. Good context for future reference. Examples: "remember that the API has a rate limit", observations about code quality.
+
+## Decision Guidelines
+
+- Prefer **quick-task** when the work is clearly small and self-contained.
+- Prefer **inject** over **replan** when only a new task is needed, not rewriting existing ones.
+- Prefer **defer** over **inject** when the work doesn't belong in the current slice's scope.
+- Use **replan** only when remaining incomplete tasks need to change — not just for adding work.
+- Use **note** for observations that don't require action.
+- When unsure between quick-task and inject, consider: will this take more than 10 minutes? If yes, inject.
+
+## Instructions
+
+1. **Classify** each pending capture using the criteria above.
+
+2. **Present** your classifications to the user using `ask_user_questions`. For each capture, show:
+   - The capture text
+   - Your proposed classification
+   - Your rationale
+   - If applicable, which files would be affected
+   
+   For captures classified as **note** or **defer**, auto-confirm without asking — these are low-impact.
+   For captures classified as **quick-task**, **inject**, or **replan**, ask the user to confirm or choose a different classification.
+
+3. **Update** `.gsd/CAPTURES.md` — for each capture, update its section with the confirmed classification:
+   - Change `**Status:** pending` to `**Status:** resolved`
+   - Add `**Classification:** <type>`
+   - Add `**Resolution:** <brief description of what will happen>`
+   - Add `**Rationale:** <why this classification>`
+   - Add `**Resolved:** <current ISO timestamp>`
+
+4. **Summarize** what was triaged: how many captures, what classifications were assigned, and what actions are pending (e.g., "2 quick-tasks ready for execution, 1 deferred to S03").
+
+**Important:** Do NOT execute any resolutions. Only classify and update CAPTURES.md. Resolution execution happens separately (in auto-mode dispatch or manually by the user).
+
+When done, say: "Triage complete."