@snipcodeit/mgw 0.4.0 → 0.6.0

package/dist/lib/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index$1 = require('../index-B-_JvYpz.cjs');
+var index$1 = require('../index-CHrVAIMY.cjs');
 var require$$0 = require('child_process');
 var require$$1 = require('path');
 var require$$3 = require('os');
@@ -145,6 +145,500 @@ function requirePipeline () {
 	return pipeline;
 }
 
+var agentErrors;
+var hasRequiredAgentErrors;
+
+function requireAgentErrors () {
+	if (hasRequiredAgentErrors) return agentErrors;
+	hasRequiredAgentErrors = 1;
+	const { MgwError } = index$1.requireErrors();
+	const SEVERITY_LEVELS = Object.freeze({
+	  critical: { name: "critical", weight: 4, description: "Agent produced dangerous or misleading results" },
+	  high: { name: "high", weight: 3, description: "Agent failed to produce usable output" },
+	  medium: { name: "medium", weight: 2, description: "Agent partially succeeded but gaps remain" },
+	  low: { name: "low", weight: 1, description: "Minor issue, likely recoverable automatically" }
+	});
+	const AGENT_FAILURE_TYPES = Object.freeze({
+	  timeout: Object.freeze({
+	    code: "AGENT_ERR_TIMEOUT",
+	    name: "timeout",
+	    severity: "high",
+	    description: "Agent exceeded turn limit or wall-clock timeout without completing its task",
+	    recovery: "Retry with reduced scope \u2014 split the task into smaller sub-tasks or increase the turn budget",
+	    retryable: true
+	  }),
+	  "malformed-output": Object.freeze({
+	    code: "AGENT_ERR_MALFORMED_OUTPUT",
+	    name: "malformed-output",
+	    severity: "high",
+	    description: "Agent returned output that cannot be parsed or does not match the expected format",
+	    recovery: "Retry with explicit format instructions \u2014 add structured output examples to the prompt",
+	    retryable: true
+	  }),
+	  "partial-completion": Object.freeze({
+	    code: "AGENT_ERR_PARTIAL_COMPLETION",
+	    name: "partial-completion",
+	    severity: "medium",
+	    description: "Agent completed some but not all assigned tasks \u2014 partial artifacts exist",
+	    recovery: "Spawn a continuation agent for the remaining tasks using the partial output as context",
+	    retryable: true
+	  }),
+	  hallucination: Object.freeze({
+	    code: "AGENT_ERR_HALLUCINATION",
+	    name: "hallucination",
+	    severity: "critical",
+	    description: "Agent claimed success but required artifacts are missing or do not match expectations",
+	    recovery: "Reject all results and retry with a verification-first approach \u2014 require artifact proof before completion",
+	    retryable: false
+	  }),
+	  "permission-denied": Object.freeze({
+	    code: "AGENT_ERR_PERMISSION_DENIED",
+	    name: "permission-denied",
+	    severity: "high",
+	    description: "Agent was blocked by a pre-commit hook, sandbox restriction, or file permission",
+	    recovery: "Escalate to human operator \u2014 review sandbox configuration and hook settings",
+	    retryable: false
+	  })
+	});
+	const _codeToType = /* @__PURE__ */ new Map();
+	for (const [key, def] of Object.entries(AGENT_FAILURE_TYPES)) {
+	  _codeToType.set(def.code, { key, ...def });
+	}
+	class AgentFailureError extends MgwError {
+	  /**
+	   * @param {string} message - Human-readable error description
+	   * @param {object} [opts]
+	   * @param {string} [opts.agentType]   - GSD agent type (gsd-planner, gsd-executor, etc.)
+	   * @param {string} [opts.failureType] - Failure type key from AGENT_FAILURE_TYPES
+	   * @param {string[]} [opts.artifacts] - List of expected artifacts that are missing/malformed
+	   * @param {string} [opts.stage]       - Pipeline stage where failure occurred
+	   * @param {number} [opts.issueNumber] - Related GitHub issue number
+	   * @param {Error}  [opts.cause]       - Original error
+	   */
+	  constructor(message, opts) {
+	    const o = opts || {};
+	    const failureDef = o.failureType ? AGENT_FAILURE_TYPES[o.failureType] : null;
+	    const code = failureDef ? failureDef.code : "AGENT_ERR_UNKNOWN";
+	    super(message, { code, stage: o.stage, issueNumber: o.issueNumber, cause: o.cause });
+	    this.name = "AgentFailureError";
+	    this.agentType = o.agentType || null;
+	    this.failureType = o.failureType || null;
+	    this.artifacts = Array.isArray(o.artifacts) ? o.artifacts : [];
+	  }
+	  /**
+	   * Get the full failure type definition for this error.
+	   * @returns {object|null}
+	   */
+	  getFailureDefinition() {
+	    if (!this.failureType) return null;
+	    return AGENT_FAILURE_TYPES[this.failureType] || null;
+	  }
+	  /**
+	   * Get the severity level for this error.
+	   * @returns {string|null}
+	   */
+	  getSeverity() {
+	    const def = this.getFailureDefinition();
+	    return def ? def.severity : null;
+	  }
+	  /**
+	   * Check whether this failure type is safe to auto-retry.
+	   * @returns {boolean}
+	   */
+	  isRetryable() {
+	    const def = this.getFailureDefinition();
+	    return def ? def.retryable : false;
+	  }
+	}
+	const CLASSIFICATION_PATTERNS = [
+	  // Timeout patterns
+	  { pattern: "turn limit", type: "timeout" },
+	  { pattern: "max turns", type: "timeout" },
+	  { pattern: "context window exhausted", type: "timeout" },
+	  { pattern: "exceeded.*timeout", type: "timeout" },
+	  { pattern: "agent timed out", type: "timeout" },
+	  { pattern: "wall.?clock.*exceeded", type: "timeout" },
+	  // Malformed output patterns
+	  { pattern: "unparseable", type: "malformed-output" },
+	  { pattern: "invalid json", type: "malformed-output" },
+	  { pattern: "parse error", type: "malformed-output" },
+	  { pattern: "unexpected token", type: "malformed-output" },
+	  { pattern: "malformed output", type: "malformed-output" },
+	  { pattern: "missing required field", type: "malformed-output" },
+	  { pattern: "output format", type: "malformed-output" },
+	  { pattern: "expected.*format", type: "malformed-output" },
+	  // Partial completion patterns
+	  { pattern: "partial completion", type: "partial-completion" },
+	  { pattern: "incomplete.*tasks", type: "partial-completion" },
+	  { pattern: "completed.*of.*tasks", type: "partial-completion" },
+	  { pattern: "remaining tasks", type: "partial-completion" },
+	  { pattern: "some tasks failed", type: "partial-completion" },
+	  // Hallucination patterns (check before generic patterns)
+	  { pattern: "artifacts? missing", type: "hallucination" },
+	  { pattern: "claimed success.*missing", type: "hallucination" },
+	  { pattern: "file.*not found.*after", type: "hallucination" },
+	  { pattern: "verification failed.*not exist", type: "hallucination" },
+	  { pattern: "hallucination", type: "hallucination" },
+	  { pattern: "phantom", type: "hallucination" },
+	  // Permission denied patterns
+	  { pattern: "permission denied", type: "permission-denied" },
+	  { pattern: "access denied", type: "permission-denied" },
+	  { pattern: "hook.*failed", type: "permission-denied" },
+	  { pattern: "pre.?commit.*rejected", type: "permission-denied" },
+	  { pattern: "sandbox.*blocked", type: "permission-denied" },
+	  { pattern: "sandbox.*violation", type: "permission-denied" },
+	  { pattern: "eacces", type: "permission-denied" }
+	];
+	function classifyAgentFailure(error, context) {
+	  if (!error || typeof error !== "object") return null;
+	  const message = (error.message || "").toLowerCase();
+	  const code = (error.code || "").toLowerCase();
+	  const ctx = context || {};
+	  if (ctx.expectedArtifacts && ctx.actualArtifacts) {
+	    const expected = new Set(ctx.expectedArtifacts);
+	    const actual = new Set(ctx.actualArtifacts);
+	    const missing = [...expected].filter((a) => !actual.has(a));
+	    if (missing.length > 0 && ctx.tasksCompleted > 0) {
+	      const def = AGENT_FAILURE_TYPES.hallucination;
+	      return { type: "hallucination", code: def.code, severity: def.severity, confidence: "high" };
+	    }
+	  }
+	  if (typeof ctx.tasksTotal === "number" && typeof ctx.tasksCompleted === "number") {
+	    if (ctx.tasksCompleted > 0 && ctx.tasksCompleted < ctx.tasksTotal) {
+	      const def = AGENT_FAILURE_TYPES["partial-completion"];
+	      return { type: "partial-completion", code: def.code, severity: def.severity, confidence: "high" };
+	    }
+	  }
+	  if (code === "eacces" || code === "eperm") {
+	    const def = AGENT_FAILURE_TYPES["permission-denied"];
+	    return { type: "permission-denied", code: def.code, severity: def.severity, confidence: "high" };
+	  }
+	  for (const { pattern, type } of CLASSIFICATION_PATTERNS) {
+	    const regex = new RegExp(pattern, "i");
+	    if (regex.test(message)) {
+	      const def = AGENT_FAILURE_TYPES[type];
+	      return { type, code: def.code, severity: def.severity, confidence: "medium" };
+	    }
+	  }
+	  return null;
+	}
+	function getRecoveryAction(failureType) {
+	  const def = AGENT_FAILURE_TYPES[failureType];
+	  if (!def) return null;
+	  return {
+	    action: def.recovery,
+	    retryable: def.retryable,
+	    severity: def.severity
+	  };
+	}
+	function isRetryable(failureType) {
+	  const def = AGENT_FAILURE_TYPES[failureType];
+	  return def ? def.retryable : false;
+	}
+	function compareSeverity(a, b) {
+	  const weightA = (SEVERITY_LEVELS[a] || { weight: 0 }).weight;
+	  const weightB = (SEVERITY_LEVELS[b] || { weight: 0 }).weight;
+	  return weightA - weightB;
+	}
+	function getFailureByCode(errorCode) {
+	  return _codeToType.get(errorCode) || null;
+	}
+	agentErrors = {
+	  // Constants
+	  AGENT_FAILURE_TYPES,
+	  SEVERITY_LEVELS,
+	  // Error class
+	  AgentFailureError,
+	  // Classification
+	  classifyAgentFailure,
+	  // Recovery
+	  getRecoveryAction,
+	  isRetryable,
+	  // Utilities
+	  compareSeverity,
+	  getFailureByCode
+	};
+	return agentErrors;
+}
+
+var modelFallback;
+var hasRequiredModelFallback;
+
+function requireModelFallback () {
+	if (hasRequiredModelFallback) return modelFallback;
+	hasRequiredModelFallback = 1;
+	const fs = require$$2;
+	const path = require$$1;
+	const { MgwError } = index$1.requireErrors();
+	let classifyAgentFailure = null;
+	let _AGENT_FAILURE_TYPES = null;
+	try {
+	  const agentErrors = requireAgentErrors();
+	  classifyAgentFailure = agentErrors.classifyAgentFailure;
+	  _AGENT_FAILURE_TYPES = agentErrors.AGENT_FAILURE_TYPES;
+	} catch (_) {
+	}
+	let classifyFailure = null;
+	try {
+	  const retry = index$1.requireRetry();
+	  classifyFailure = retry.classifyFailure;
+	} catch (_) {
+	}
+	const DEFAULT_FALLBACK_CHAINS = Object.freeze({
+	  "gsd-planner": Object.freeze(["inherit", "sonnet", "haiku"]),
+	  "gsd-executor": Object.freeze(["sonnet", "haiku"]),
+	  "gsd-verifier": Object.freeze(["sonnet", "haiku"]),
+	  "gsd-plan-checker": Object.freeze(["sonnet", "haiku"]),
+	  "general-purpose": Object.freeze(["sonnet", "haiku"])
+	});
+	const NON_FALLBACK_FAILURE_TYPES = /* @__PURE__ */ new Set([
+	  "hallucination",
+	  // Unsafe — different model might hallucinate differently
+	  "permission-denied"
+	  // Environment issue — model change won't help
+	]);
+	class ModelFallbackError extends MgwError {
+	  /**
+	   * @param {string} message
+	   * @param {object} [opts]
+	   * @param {string} [opts.failureType]      - Last classified failure type
+	   * @param {string} [opts.agentType]        - GSD agent type
+	   * @param {string[]} [opts.modelsAttempted] - Models that were tried
+	   * @param {number} [opts.fallback_attempts] - Number of fallback attempts made
+	   * @param {Error}  [opts.cause]            - Last error from final model attempt
+	   * @param {string} [opts.stage]            - Pipeline stage
+	   * @param {number} [opts.issueNumber]      - Related GitHub issue number
+	   */
+	  constructor(message, opts) {
+	    const o = opts || {};
+	    super(message, {
+	      code: "MODEL_FALLBACK_EXHAUSTED",
+	      stage: o.stage,
+	      issueNumber: o.issueNumber,
+	      cause: o.cause
+	    });
+	    this.name = "ModelFallbackError";
+	    this.failureType = o.failureType || null;
+	    this.agentType = o.agentType || null;
+	    this.modelsAttempted = Array.isArray(o.modelsAttempted) ? o.modelsAttempted : [];
+	    this.fallback_attempts = typeof o.fallback_attempts === "number" ? o.fallback_attempts : 0;
+	  }
+	}
+	class ModelFallbackEngine {
+	  /**
+	   * @param {object} [opts]
+	   * @param {boolean} [opts.enabled]        - Master enable/disable switch (overrides config)
+	   * @param {object} [opts.chains]          - Per-agent-type chain overrides
+	   *   Format: { 'gsd-planner': ['inherit', 'sonnet'] }
+	   * @param {string} [opts.configPath]      - Path to .mgw/config.json (default: auto-detect)
+	   */
+	  constructor(opts) {
+	    const o = opts || {};
+	    const fileConfig = ModelFallbackEngine.loadConfig(o.configPath || null);
+	    if (typeof o.enabled === "boolean") {
+	      this._enabled = o.enabled;
+	    } else if (typeof fileConfig.enabled === "boolean") {
+	      this._enabled = fileConfig.enabled;
+	    } else {
+	      this._enabled = false;
+	    }
+	    this._chains = Object.assign(
+	      {},
+	      DEFAULT_FALLBACK_CHAINS,
+	      fileConfig.chains || {},
+	      o.chains || {}
+	    );
+	  }
+	  // -------------------------------------------------------------------------
+	  // Public API
+	  // -------------------------------------------------------------------------
+	  /**
+	   * Check whether model fallback is enabled.
+	   * @returns {boolean}
+	   */
+	  get enabled() {
+	    return this._enabled;
+	  }
+	  /**
+	   * Resolve the ordered fallback chain for an agent type.
+	   *
+	   * If model_fallback is disabled, returns an array with only the primary
+	   * model (no fallback — preserves backward-compatible behavior).
+	   *
+	   * @param {string} agentType - GSD agent type (e.g. 'gsd-planner')
+	   * @returns {string[]} Ordered model chain (first = primary, rest = fallbacks)
+	   */
+	  resolveFallbackChain(agentType) {
+	    const chain = this._chains[agentType] || this._chains["general-purpose"] || ["sonnet"];
+	    if (!this._enabled) {
+	      return [chain[0]];
+	    }
+	    return [...chain];
+	  }
+	  /**
+	   * Execute an async function with model-tier fallback.
+	   *
+	   * Takes a function that receives a model name and attempts execution
+	   * with each model in the fallback chain until one succeeds or the
+	   * chain is exhausted.
+	   *
+	   * @param {(modelName: string) => Promise<*>} fn - Async function that accepts model name
+	   * @param {object} [opts]
+	   * @param {string} [opts.agentType]    - GSD agent type for chain lookup
+	   * @param {function} [opts.onFallback] - Callback on fallback: (fromModel, toModel, attempt, error) => void
+	   * @param {AbortSignal} [opts.signal]  - AbortSignal to cancel fallback attempts
+	   * @returns {Promise<{ result: *, model: string, fallback_attempts: number, total_models_tried: number }>}
+	   * @throws {ModelFallbackError} If all models in chain are exhausted
+	   * @throws {Error} Original error if failure type is non-fallback-eligible
+	   */
+	  async executeWithFallback(fn, opts) {
+	    const o = opts || {};
+	    const agentType = o.agentType || "general-purpose";
+	    const onFallback = typeof o.onFallback === "function" ? o.onFallback : null;
+	    const signal = o.signal || null;
+	    const chain = this.resolveFallbackChain(agentType);
+	    const modelsAttempted = [];
+	    let lastError = null;
+	    let fallbackAttempts = 0;
+	    for (let i = 0; i < chain.length; i++) {
+	      const model = chain[i];
+	      if (signal && signal.aborted) {
+	        throw lastError || new MgwError("Fallback aborted by signal", { code: "FALLBACK_ABORTED" });
+	      }
+	      modelsAttempted.push(model);
+	      try {
+	        const result = await fn(model);
+	        return {
+	          result,
+	          model,
+	          fallback_attempts: fallbackAttempts,
+	          total_models_tried: modelsAttempted.length
+	        };
+	      } catch (err) {
+	        lastError = err;
+	        const failureType = this._classifyForFallback(err, agentType);
+	        if (NON_FALLBACK_FAILURE_TYPES.has(failureType)) {
+	          throw err;
+	        }
+	        if (i < chain.length - 1) {
+	          fallbackAttempts++;
+	          if (onFallback) {
+	            try {
+	              onFallback(model, chain[i + 1], fallbackAttempts, err);
+	            } catch (_) {
+	            }
+	          }
+	        }
+	      }
+	    }
+	    throw new ModelFallbackError(
+	      `Model fallback exhausted for ${agentType}: tried ${modelsAttempted.join(", ")}`,
+	      {
+	        failureType: this._classifyForFallback(lastError, agentType),
+	        agentType,
+	        modelsAttempted,
+	        fallback_attempts: fallbackAttempts,
+	        cause: lastError
+	      }
+	    );
+	  }
+	  // -------------------------------------------------------------------------
+	  // Internal: error classification for fallback decisions
+	  // -------------------------------------------------------------------------
+	  /**
+	   * Classify an error to determine if model fallback should be attempted.
+	   *
+	   * Uses agent-errors.cjs classification first (if available), then falls
+	   * back to generic retry.cjs classification.
+	   *
+	   * @param {Error} err       - The error to classify
+	   * @param {string} [agentType] - GSD agent type for context
+	   * @returns {string} Failure type key (e.g. 'timeout', 'permanent', 'transient')
+	   * @private
+	   */
+	  _classifyForFallback(err, agentType) {
+	    if (classifyAgentFailure) {
+	      const agentResult = classifyAgentFailure(err, { agentType });
+	      if (agentResult && agentResult.type) {
+	        return agentResult.type;
+	      }
+	    }
+	    if (classifyFailure) {
+	      const genericResult = classifyFailure(err);
+	      if (genericResult && genericResult.class) {
+	        if (genericResult.class === "transient") return "timeout";
+	        if (genericResult.class === "needs-info") return "needs-info";
+	        return "permanent";
+	      }
+	    }
+	    return "permanent";
+	  }
+	  // -------------------------------------------------------------------------
+	  // Static: config loading
+	  // -------------------------------------------------------------------------
+	  /**
+	   * Load model fallback configuration from .mgw/config.json.
+	   *
+	   * Looks for a `retry` section with `model_fallback` and `fallback_chains`:
+	   * ```json
+	   * {
+	   *   "retry": {
+	   *     "model_fallback": true,
+	   *     "fallback_chains": {
+	   *       "gsd-planner": ["inherit", "sonnet"],
+	   *       "gsd-executor": ["sonnet", "haiku"]
+	   *     }
+	   *   }
+	   * }
+	   * ```
+	   *
+	   * @param {string} [configPath] - Explicit path to config.json. If null,
+	   *   searches for .mgw/config.json relative to cwd.
+	   * @returns {{ enabled?: boolean, chains?: object }}
+	   */
+	  static loadConfig(configPath) {
+	    const empty = {};
+	    try {
+	      const cfgPath = configPath || path.join(process.cwd(), ".mgw", "config.json");
+	      if (!fs.existsSync(cfgPath)) return empty;
+	      const raw = fs.readFileSync(cfgPath, "utf-8");
+	      const config = JSON.parse(raw);
+	      if (!config || typeof config !== "object") return empty;
+	      const retry = config.retry;
+	      if (!retry || typeof retry !== "object") return empty;
+	      const result = {};
+	      if (typeof retry.model_fallback === "boolean") {
+	        result.enabled = retry.model_fallback;
+	      }
+	      if (retry.fallback_chains && typeof retry.fallback_chains === "object") {
+	        const chains = {};
+	        for (const [agentType, chain] of Object.entries(retry.fallback_chains)) {
+	          if (Array.isArray(chain) && chain.every((m) => typeof m === "string")) {
+	            chains[agentType] = chain;
+	          }
+	        }
+	        if (Object.keys(chains).length > 0) {
+	          result.chains = chains;
+	        }
+	      }
+	      return result;
+	    } catch (_) {
+	      return empty;
+	    }
+	  }
+	}
+	modelFallback = {
+	  // Constants
+	  DEFAULT_FALLBACK_CHAINS,
+	  NON_FALLBACK_FAILURE_TYPES,
+	  // Error class
+	  ModelFallbackError,
+	  // Engine
+	  ModelFallbackEngine
+	};
+	return modelFallback;
+}
+
 var gsdAdapter;
 var hasRequiredGsdAdapter;
 
@@ -316,6 +810,32 @@ Set GSD_TOOLS_PATH or add gsd_path to .mgw/config.json`
 	  }
 	  return { activeMilestone, currentPhase, planCount };
 	}
+	let ModelFallbackEngine = null;
+	try {
+	  const modelFallback = requireModelFallback();
+	  ModelFallbackEngine = modelFallback.ModelFallbackEngine;
+	} catch (_) {
+	}
+	let _fallbackEngineSingleton = null;
+	function getModelFallbackEngine() {
+	  if (!ModelFallbackEngine) return null;
+	  if (!_fallbackEngineSingleton) {
+	    _fallbackEngineSingleton = new ModelFallbackEngine();
+	  }
+	  return _fallbackEngineSingleton;
+	}
+	function resolveFallbackChain(agentType) {
+	  const engine = getModelFallbackEngine();
+	  if (engine && engine.enabled) {
+	    return engine.resolveFallbackChain(agentType);
+	  }
+	  try {
+	    const primary = resolveModel(agentType);
+	    return [primary];
+	  } catch (_) {
+	    return ["sonnet"];
+	  }
+	}
 	gsdAdapter = {
 	  resolveGsdRoot,
 	  getGsdToolsPath,
@@ -326,7 +846,9 @@ Set GSD_TOOLS_PATH or add gsd_path to .mgw/config.json`
 	  historyDigest,
 	  roadmapAnalyze,
 	  selectGsdRoute,
-	  getGsdState
+	  getGsdState,
+	  getModelFallbackEngine,
+	  resolveFallbackChain
 	};
 	return gsdAdapter;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snipcodeit/mgw",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "GitHub-native issue-to-PR automation for Claude Code, powered by Get Shit Done",
   "bin": {
     "mgw": "./dist/bin/mgw.cjs"
@@ -16,7 +16,10 @@
   "scripts": {
     "build": "pkgroll --clean-dist --src .",
     "dev": "pkgroll --watch --src .",
-    "test": "node --test test/*.test.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:node": "node --test test/*.test.cjs",
+    "test:coverage": "vitest run --coverage",
     "lint": "eslint lib/ bin/ test/",
     "prepublishOnly": "npm run build",
     "completions": "node bin/generate-completions.cjs",
@@ -30,8 +33,10 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.2",
-    "pkgroll": "^2.26.3"
+    "pkgroll": "^2.26.3",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -56,4 +61,4 @@
   "bugs": {
     "url": "https://github.com/snipcodeit/mgw/issues"
   }
-}
+}