@crewhaus/spec 0.2.0 → 0.2.2

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
@@ -241,6 +248,110 @@ const modelTiersBlock = z
 })
     .strict()
     .optional();
+/**
+ * Adaptive model routing — an opt-in `model_pool` of user-declared candidate
+ * models the runtime selects among PER TURN, with a selection `policy` that can
+ * improve the more the harness runs. The N-candidate generalisation of
+ * `model_tiers` (which is the two-candidate special case), so the two are
+ * mutually exclusive on an agent block (enforced by a refine on each shape).
+ *
+ * The user always declares the SET; the runtime only ever picks WITHIN it —
+ * `agent.model` (and the optimizer's model-path exclusion) is untouched, so
+ * learning tunes selection policy, never the candidate roster.
+ *
+ *   - `candidates` — ≥2 model-router grammar strings, each with free-form
+ *     `tags` (e.g. `cheap`, `strong`) the heuristic routes on. Declare
+ *     cheapest→strongest; tags override that order.
+ *   - `policy` — `static` (first candidate), `heuristic` (deterministic
+ *     difficulty routing, the default), or `learned` (reward-scoreboard arm
+ *     selection that improves with usage).
+ *   - `objective` — weights for the learned reward (quality / cost / latency);
+ *     defaults to quality-dominant (0.7 / 0.2 / 0.1).
+ *   - `routing` — difficulty thresholds (shared with `model_tiers`) plus the
+ *     `strongTag`/`cheapTag` the heuristic prefers.
+ *   - `learning` — read only for `policy: learned`: the per-arm exploration
+ *     floor and the cost/latency reward references.
+ *
+ * Omitted entirely → single-model behaviour, byte-identical bundles.
+ */
+const modelPoolBlock = z
+    .object({
+    candidates: z
+        .array(z
+        .object({
+        model: z.string().min(1),
+        tags: z.array(z.string().min(1)).default([]),
+    })
+        .strict())
+        .min(2),
+    policy: z.enum(["static", "heuristic", "learned"]).default("heuristic"),
+    objective: z
+        .object({
+        quality: z.number().min(0).optional(),
+        cost: z.number().min(0).optional(),
+        latency: z.number().min(0).optional(),
+    })
+        .strict()
+        .optional(),
+    routing: z
+        .object({
+        contextTokenThreshold: z.number().int().positive().optional(),
+        toolsToDefault: z.boolean().optional(),
+        firstTurnToDefault: z.boolean().optional(),
+        priorToolDensityThreshold: z.number().int().positive().optional(),
+        strongTag: z.string().min(1).optional(),
+        cheapTag: z.string().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    learning: z
+        .object({
+        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(),
+})
+    .strict()
+    .optional();
+/**
+ * Mutual-exclusion refine shared by every agent block that carries model
+ * routing: `model_pool` is the superset of both the two-tier router and the
+ * ordered failover chain, so declaring it alongside either is an error rather
+ * than an ambiguous double-route. (Per-candidate failover chains compose in a
+ * later release; this release keeps precedence unambiguous.)
+ */
+function refineModelSelection(agent, ctx) {
+    if (agent.model_pool === undefined)
+        return;
+    if (agent.model_tiers !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "agent.model_pool and agent.model_tiers are mutually exclusive — model_pool is the N-candidate generalisation of the two-tier router",
+            path: ["model_tiers"],
+        });
+    }
+    if (agent.model_fallbacks !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "agent.model_pool and agent.model_fallbacks are mutually exclusive in this release — per-candidate failover chains are a future addition",
+            path: ["model_fallbacks"],
+        });
+    }
+}
 /**
  * Section 17 — optional override for the model used by
  * `compaction-autocompact` when summarising long conversations. Defaults
@@ -630,9 +741,12 @@ const cliSchema = z
         circuit_breaker: circuitBreakerBlock,
         // Item 26 — opt-in two-tier turn-difficulty router.
         model_tiers: modelTiersBlock,
+        // Adaptive model routing — N-candidate pool with a selection policy.
+        model_pool: modelPoolBlock,
         sub_agents: subAgentsBlock,
     })
-        .strict(),
+        .strict()
+        .superRefine(refineModelSelection),
     tools: z.array(z.string().min(1)).optional(),
     tool_config: toolConfigBlock,
     mcp_servers: mcpServersBlock,
@@ -751,11 +865,14 @@ const channelAgentSchema = z
     circuit_breaker: circuitBreakerBlock,
     // Item 26 — opt-in two-tier turn-difficulty router.
     model_tiers: modelTiersBlock,
+    // Adaptive model routing — N-candidate pool with a selection policy.
+    model_pool: modelPoolBlock,
     tools: z.array(z.string().min(1)).optional(),
     tool_config: toolConfigBlock,
     sub_agents: subAgentsBlock,
 })
-    .strict();
+    .strict()
+    .superRefine(refineModelSelection);
 const channelSchema = z
     .object({
     name: safeName,
@@ -850,8 +967,11 @@ const managedAgentSchema = z
     circuit_breaker: circuitBreakerBlock,
     // Item 26 — opt-in two-tier turn-difficulty router.
     model_tiers: modelTiersBlock,
+    // Adaptive model routing — N-candidate pool with a selection policy.
+    model_pool: modelPoolBlock,
 })
-    .strict();
+    .strict()
+    .superRefine(refineModelSelection);
 const managedSchema = z
     .object({
     name: safeName,
@@ -885,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),
@@ -991,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),
@@ -1032,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),
@@ -1108,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.0",
+  "version": "0.2.2",
   "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.0",
+    "@crewhaus/errors": "0.2.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },