@crewhaus/spec 0.2.1 → 0.2.3

package/dist/index.js

@@ -195,6 +195,13 @@ const toolConfigBlock = z
  * normal model-router path — a fallback with a missing key warns at boot
  * and is skipped when tried, never hard-failing the run.
  *
+ * The declared ORDER is honoured verbatim — it is a TRUST ordering ("what do
+ * I run when my primary is down"), and the runtime never reorders it (a
+ * 2026-07 design review deliberately retired the cost-ranking idea; see the
+ * `rankFallbacks` docstring in model-router's failover.ts). Want cheaper
+ * models preferred? Order the list yourself — or use `agent.model_pool`,
+ * which is the cost/quality routing surface.
+ *
  * `circuit_breaker` tunes the per-candidate breakers. Field names mirror
  * `CircuitBreakerOptions` in `@crewhaus/circuit-breaker` exactly
  * (failureThreshold / windowMs / cooldownMs); package defaults (5 failures
@@ -302,6 +309,18 @@ const modelPoolBlock = z
         minSamplesPerArm: z.number().int().positive().optional(),
         costRefUsd: z.number().positive().optional(),
         latencyRefMs: z.number().int().positive().optional(),
+        // ε for ε-greedy online exploration once every arm clears the sample
+        // floor (fraction of exploit-phase turns that try a non-best model).
+        // Default 0 → deterministic explore-then-exploit, no RNG.
+        explorationRate: z.number().min(0).max(1).optional(),
+        // Fixed exploration seed for reproducible-across-runs behaviour (e.g.
+        // tests). Omitted → the runtime seeds from the sessionId, so each run
+        // explores differently while still replaying from its own transcript.
+        seed: z.string().min(1).optional(),
+        // Exploit-phase exploration strategy. "epsilon-greedy" (default) uses
+        // explorationRate; "thompson" draws each arm from its reward posterior
+        // and self-balances (explorationRate is then ignored).
+        bandit: z.enum(["epsilon-greedy", "thompson"]).optional(),
     })
         .strict()
         .optional(),
@@ -986,17 +1005,33 @@ const pipelineDocumentSchema = z
     metadata: z.record(z.string(), z.unknown()).optional(),
 })
     .strict();
+/**
+ * Adaptive model routing — the minimal single-agent block shared by the
+ * pipeline/research/batch/browser shapes, now carrying the opt-in
+ * `model_pool`. Their emitted runtimes each call `runChatLoop` with a single
+ * primary (exactly the cli shape's execution model), so the pool routes there
+ * with zero runtime changes. The superRefine is trivially satisfied today
+ * (these shapes carry no `model_tiers`/`model_fallbacks`) but keeps the
+ * mutual-exclusion rule uniform if they ever gain them. NOT used by
+ * onchain/onchain-game: their emitted bundles are callable modules whose
+ * agent-loop wiring is still deferred (see target-onchain slice-2 notes), so
+ * a `model_pool` there would be an inert spec field.
+ */
+const pooledSingleAgentSchema = z
+    .object({
+    model: z.string().min(1),
+    instructions: z.string().min(1),
+    // Adaptive model routing — N-candidate pool with a selection policy.
+    model_pool: modelPoolBlock,
+})
+    .strict()
+    .superRefine(refineModelSelection);
 const pipelineSchema = z
     .object({
     name: safeName,
     version: versionField,
     target: z.literal("pipeline"),
-    agent: z
-        .object({
-        model: z.string().min(1),
-        instructions: z.string().min(1),
-    })
-        .strict(),
+    agent: pooledSingleAgentSchema,
     retrieve: z
         .object({
         embedderModel: z.string().min(1),
@@ -1092,12 +1127,7 @@ const researchSchema = z
     name: safeName,
     version: versionField,
     target: z.literal("research"),
-    agent: z
-        .object({
-        model: z.string().min(1),
-        instructions: z.string().min(1),
-    })
-        .strict(),
+    agent: pooledSingleAgentSchema,
     goal: z.string().min(1),
     branchingFactor: z.number().int().min(1).max(8).default(3),
     maxDurationMs: z.number().int().positive().default(300_000),
@@ -1133,12 +1163,7 @@ const batchSchema = z
     name: safeName,
     version: versionField,
     target: z.literal("batch"),
-    agent: z
-        .object({
-        model: z.string().min(1),
-        instructions: z.string().min(1),
-    })
-        .strict(),
+    agent: pooledSingleAgentSchema,
     queue: batchQueueSchema,
     concurrency: z.number().int().min(1).max(64).default(4),
     idempotencyWindowMs: z.number().int().positive().default(60_000),
@@ -1209,12 +1234,7 @@ const browserSchema = z
     name: safeName,
     version: versionField,
     target: z.literal("browser"),
-    agent: z
-        .object({
-        model: z.string().min(1),
-        instructions: z.string().min(1),
-    })
-        .strict(),
+    agent: pooledSingleAgentSchema,
     driver: browserDriverSchema.default({}),
     /** Vision-grounding model. Defaults to the agent's primary model. */
     groundingModel: z.string().min(1).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "User-facing spec schema (Zod) + YAML parser",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.2.1",
+    "@crewhaus/errors": "0.2.3",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },