@crewhaus/recovery-engine 0.1.7 → 0.2.0

package/dist/index.d.ts

@@ -12,6 +12,14 @@
  *   user-aborted         → fail("user_aborted")  — orchestrator handles abort separately
  *   anything else        → fail(message)
  *
+ * Item 23 — `switch-model` is an OPT-IN `failure_taxonomy` recovery action
+ * (never a built-in `classify()` verdict, so default runs are byte-for-byte
+ * unchanged). It tells the orchestrator to route the same turn onto the
+ * next provider-failover candidate (open the active breaker so the chain
+ * reroutes) instead of exhausting backoff retries against a dead provider.
+ * Budgeted per turn like the others; a run without a failover chain treats
+ * it as a retry-shaped no-op re-issue (documented in runtime-core).
+ *
  * References: claude-code/query.ts recovery branches; agent-framework
  * _runner.py retry; AI-Harness-Systems §recovery.
  */
@@ -27,6 +35,8 @@ export type RecoveryAction = {
 } | {
     readonly kind: "tombstone";
     readonly messageId?: string;
+} | {
+    readonly kind: "switch-model";
 } | {
     readonly kind: "fail";
     readonly reason: string;
@@ -41,6 +51,8 @@ export type RecoveryState = {
     readonly continueCount: number;
     /** Number of `tombstone` actions already chosen in this turn. */
     readonly tombstoneCount: number;
+    /** Item 23 — number of `switch-model` actions already chosen this turn. */
+    readonly switchModelCount: number;
 };
 export declare const initialRecoveryState: RecoveryState;
 export declare class RecoveryEngineError extends CrewhausError {
@@ -71,7 +83,7 @@ export declare function classify(error: unknown): RecoveryErrorClass;
 export type NamedFailureClass = {
     readonly class: string;
     readonly pattern: string;
-    readonly recovery: "retry" | "compact" | "continue" | "tombstone" | "fail";
+    readonly recovery: "retry" | "compact" | "continue" | "tombstone" | "switch-model" | "fail";
     readonly hint?: string;
 };
 /**
@@ -101,6 +113,7 @@ export declare const BUDGETS: {
     readonly MAX_COMPACTS: 1;
     readonly MAX_CONTINUES: 3;
     readonly MAX_TOMBSTONES: 1;
+    readonly MAX_SWITCH_MODELS: 3;
     readonly BASE_BACKOFF_MS: 1000;
     readonly MAX_BACKOFF_MS: 30000;
     readonly MAX_JITTER_MS: 250;

package/dist/index.js

@@ -12,6 +12,14 @@
  *   user-aborted         → fail("user_aborted")  — orchestrator handles abort separately
  *   anything else        → fail(message)
  *
+ * Item 23 — `switch-model` is an OPT-IN `failure_taxonomy` recovery action
+ * (never a built-in `classify()` verdict, so default runs are byte-for-byte
+ * unchanged). It tells the orchestrator to route the same turn onto the
+ * next provider-failover candidate (open the active breaker so the chain
+ * reroutes) instead of exhausting backoff retries against a dead provider.
+ * Budgeted per turn like the others; a run without a failover chain treats
+ * it as a retry-shaped no-op re-issue (documented in runtime-core).
+ *
  * References: claude-code/query.ts recovery branches; agent-framework
  * _runner.py retry; AI-Harness-Systems §recovery.
  */
@@ -21,6 +29,7 @@ export const initialRecoveryState = {
     compactCount: 0,
     continueCount: 0,
     tombstoneCount: 0,
+    switchModelCount: 0,
 };
 export class RecoveryEngineError extends CrewhausError {
     name = "RecoveryEngineError";
@@ -32,6 +41,10 @@ const MAX_RETRIES = 5;
 const MAX_COMPACTS = 1;
 const MAX_CONTINUES = 3;
 const MAX_TOMBSTONES = 1;
+// Item 23 — cap `switch-model` hops per turn. Generous enough to walk a
+// short failover chain (primary → fallback → fallback), low enough that a
+// mutually-degraded chain fails the turn instead of looping forever.
+const MAX_SWITCH_MODELS = 3;
 const BASE_BACKOFF_MS = 1_000;
 const MAX_BACKOFF_MS = 30_000;
 const MAX_JITTER_MS = 250;
@@ -202,6 +215,11 @@ function recoverNamed(named, state) {
                 return { kind: "fail", reason: `tombstone budget exhausted: ${reason}` };
             }
             return { kind: "tombstone" };
+        case "switch-model":
+            if (state.switchModelCount >= MAX_SWITCH_MODELS) {
+                return { kind: "fail", reason: `switch-model budget exhausted: ${reason}` };
+            }
+            return { kind: "switch-model" };
         case "fail":
             return { kind: "fail", reason };
     }
@@ -220,6 +238,8 @@ export function advanceState(state, action) {
             return { ...state, continueCount: state.continueCount + 1 };
         case "tombstone":
             return { ...state, tombstoneCount: state.tombstoneCount + 1 };
+        case "switch-model":
+            return { ...state, switchModelCount: state.switchModelCount + 1 };
         case "fail":
             return state;
     }
@@ -230,6 +250,7 @@ export const BUDGETS = {
     MAX_COMPACTS,
     MAX_CONTINUES,
     MAX_TOMBSTONES,
+    MAX_SWITCH_MODELS,
     BASE_BACKOFF_MS,
     MAX_BACKOFF_MS,
     MAX_JITTER_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/recovery-engine",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pure recovery taxonomy: classify Anthropic API errors into a RecoveryAction (compact/retry/continue/tombstone/fail)",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.7"
+    "@crewhaus/errors": "0.2.0"
   },
   "license": "Apache-2.0",
   "author": {