@crewhaus/spec 0.1.8 → 0.2.1

package/dist/index.js

@@ -26,6 +26,24 @@ const safeName = z
  * Will grow into the full catalog spec (eval, deploy) — see
  * docs/MODULE-CATALOG.md PART A Layer F1.
  */
+/**
+ * Section 28 (#43) — OPTIONAL spec-schema version stamp. Every target schema is
+ * `.strict()`, so before this field a migration that stamped `version: 1` on a
+ * spec's YAML produced a document `parseSpec` REJECTED ("Unrecognized key(s)").
+ * This additive optional field gives migrations somewhere to stamp:
+ *
+ *   - ABSENT  → the spec is current/unversioned (the pre-#43 world). Fully
+ *     back-compat: every existing spec keeps parsing unchanged.
+ *   - PRESENT → a non-negative integer the migration-engine reads as the spec's
+ *     schema version (`spec.version ?? 0` in migration-engine/migration-runner).
+ *
+ * It is a spec-schema knob, NOT the IR `version` (which stays `0` — the IR's
+ * own contract version). `lower()` does not thread this field into the IR; it
+ * exists purely so the versioned-migration chain has a home. Added to EVERY
+ * member of the discriminated union because the union is `.strict()` — a field
+ * absent from a member would still be rejected on that target.
+ */
+const versionField = z.number().int().nonnegative().optional();
 // Permissions block (Section 7). SECURITY: `mode: "bypass"` is intentionally
 // absent from the enum — bypass can only enter the system via the CLI flag.
 // Defense in depth: parse-time and runtime checks both reject it.
@@ -163,6 +181,158 @@ const toolConfigBlock = z
     }
 })
     .optional();
+/**
+ * Item 22 — spec-declared provider failover chain, on the agent blocks of
+ * the shapes whose emitted runtime calls `runChatLoop` with a single
+ * primary model (cli, channel, managed today).
+ *
+ * `model_fallbacks` is an ordered list of model strings tried when the
+ * primary's circuit breaker is open — each entry follows the SAME
+ * model-string grammar as `agent.model` (`claude-*`, `openai/*`,
+ * `bedrock/*`, `groq/*`, …; validated like `agent.model` at parse time,
+ * with the full grammar enforced by the model-router when resolved).
+ * Cross-provider fallbacks resolve their own credentials lazily via the
+ * normal model-router path — a fallback with a missing key warns at boot
+ * and is skipped when tried, never hard-failing the run.
+ *
+ * `circuit_breaker` tunes the per-candidate breakers. Field names mirror
+ * `CircuitBreakerOptions` in `@crewhaus/circuit-breaker` exactly
+ * (failureThreshold / windowMs / cooldownMs); package defaults (5 failures
+ * / 60s window / 30s cooldown) apply per field when omitted. Declaring
+ * `circuit_breaker` WITHOUT `model_fallbacks` is valid: the primary
+ * adapter alone gets breaker-wrapped (fail-fast on a degraded provider
+ * instead of hammering it).
+ */
+const modelFallbacksBlock = z.array(z.string().min(1)).min(1).optional();
+const circuitBreakerBlock = z
+    .object({
+    /** Consecutive failures inside windowMs that trip the breaker. */
+    failureThreshold: z.number().int().positive().optional(),
+    /** Window for counting consecutive failures (ms). */
+    windowMs: z.number().int().positive().optional(),
+    /** How long the breaker stays open before allowing a probe (ms). */
+    cooldownMs: z.number().int().positive().optional(),
+})
+    .strict()
+    .optional();
+/**
+ * Item 26 — opt-in two-tier turn-difficulty router. When present, the runtime
+ * picks a model tier PER TURN from deterministic signals (estimated context
+ * tokens, whether tools are in play, turn index, prior-turn tool_use density):
+ * the cheap `fast` model for easy turns, the `default` model for hard ones. A
+ * fast-tier turn that FAILS re-runs on `default` (misroute recovery). Both are
+ * full model-router grammar strings. `routing` tunes the escalation thresholds
+ * (all optional — sensible defaults apply). Omitted entirely → single-model
+ * behaviour, byte-identical bundles.
+ */
+const modelTiersBlock = z
+    .object({
+    fast: z.string().min(1),
+    default: z.string().min(1),
+    routing: z
+        .object({
+        contextTokenThreshold: z.number().int().positive().optional(),
+        toolsToDefault: z.boolean().optional(),
+        firstTurnToDefault: z.boolean().optional(),
+        priorToolDensityThreshold: z.number().int().positive().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .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(),
+    })
+        .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
@@ -265,19 +435,51 @@ const failureTaxonomyEntrySchema = z
     .object({
     class: z.string().min(1),
     pattern: z.string().min(1),
-    recovery: z.enum(["retry", "compact", "continue", "tombstone", "fail"]),
+    // Item 23 — `switch-model` routes the same turn onto the next provider
+    // failover candidate (pairs with `agent.model_fallbacks`; a no-op
+    // re-issue when no chain is declared). See recovery-engine +
+    // AUTOMATION-OPPORTUNITIES.md item 23.
+    recovery: z.enum(["retry", "compact", "continue", "tombstone", "switch-model", "fail"]),
     hint: z.string().min(1).optional(),
 })
     .strict();
 const failureTaxonomyBlock = z.array(failureTaxonomyEntrySchema).optional();
+/**
+ * Item 27 — run-level spend cap with a degradation ladder. Generalizes the
+ * optimizer's `--budget-usd` to normal runs. `usd` is the dollar ceiling;
+ * when the run's accrued spend reaches it, `on_exceed` decides:
+ *   - `{ action: "stop" }`      — end the run cleanly before the next turn.
+ *   - `{ action: "degrade", model }` — re-resolve the primary model to the
+ *     cheaper `model` (one rung) and continue; a later breach on the
+ *     degraded model stops the run.
+ * The check is PRE-TURN (beside compaction), so an in-flight turn always
+ * completes. Carried on the same interactive shapes as the failover chain
+ * (cli, channel, managed). `on_exceed.model` follows the agent.model
+ * grammar. Defaults to `{ action: "stop" }` when `on_exceed` is omitted.
+ */
+const budgetBlock = z
+    .object({
+    usd: z.number().positive(),
+    on_exceed: z
+        .discriminatedUnion("action", [
+        z.object({ action: z.literal("stop") }).strict(),
+        z.object({ action: z.literal("degrade"), model: z.string().min(1) }).strict(),
+    ])
+        .default({ action: "stop" }),
+})
+    .strict()
+    .optional();
 /**
  * Response-feedback block — declares that a harness collects human ratings on
  * agent responses (thumbs/stars/scale/comment) which `crewhaus distill` turns
  * into eval datasets + graders. Cross-cutting like security: carried on the
  * interactive shapes that consume it (cli, channel). `channelReactions` gates
  * codegen of Slack 👍/👎 → feedback in the channel target; `modality`/`storage`
- * configure the capture surfaces; `autoDistill` is a forward-looking flag for a
- * continuous flywheel. `.strict()` so a typo'd sub-key fails the build.
+ * configure the capture surfaces; `autoDistill` turns accumulated ratings into
+ * versioned `<name>-ratings` registry datasets at CLI run teardown (item 1);
+ * `exitPrompt` gates the one-keystroke REPL exit rating prompt (default on
+ * when the block is present; set `false` to keep capture surfaces without the
+ * prompt). `.strict()` so a typo'd sub-key fails the build.
  */
 const feedbackBlock = z
     .object({
@@ -286,10 +488,93 @@ const feedbackBlock = z
     scale: z.object({ min: z.number().int(), max: z.number().int() }).strict().optional(),
     storage: z.object({ location: safeName }).strict().optional(),
     autoDistill: z.boolean().optional(),
+    exitPrompt: z.boolean().optional(),
     channelReactions: z.boolean().optional(),
 })
     .strict()
     .optional();
+/**
+ * Feature #53 — cross-session memory block. Its mere presence wires the
+ * Remember/Recall tools into the harness (no hand-editing). The auto-*
+ * switches layer on top: `autoCapture` summarizes the session's durable
+ * outcomes into `.crewhaus/memories/<name>.jsonl` at run teardown;
+ * `autoRecall` injects the top-`recallK` relevant memories into the system
+ * prompt at session start (mirrors project-memory auto-load). Carried on the
+ * interactive shapes that run a chat loop (cli, channel, managed, research).
+ * `.strict()` so a typo'd sub-key fails the build.
+ */
+const memoryBlock = z
+    .object({
+    enabled: z.boolean().optional(),
+    autoCapture: z.boolean().optional(),
+    autoCaptureThreshold: z.number().int().positive().optional(),
+    autoRecall: z.boolean().optional(),
+    recallK: z.number().int().positive().max(50).optional(),
+})
+    .strict()
+    .optional();
+/**
+ * Ops item 37 — cross-cutting `observability` block. Today it carries one
+ * sub-block, `slo`, that declares production Service-Level Objectives + the
+ * mitigation ladder the runtime SLO monitor walks on a SUSTAINED breach.
+ *
+ * The monitor (runtime-core, env/spec-gated) folds bus events into rolling
+ * windows (reusing the alert-watchdog's accumulator + the metrics-collector's
+ * TTFT histogram) and, when a target is breached for `windowSeconds`, executes
+ * the ladder rungs in the declared order: `alert` (webhook/hook), `pause-intake`
+ * (gateway/managed 429 `budget_exceeded` path), `rollback` (auto-rollback the
+ * env pin via deployment-controller). Every rung is audit-logged.
+ *
+ * Targets are all OPTIONAL — declare only the SLOs you care about; an omitted
+ * target is never evaluated. `mitigation` defaults to `["alert"]` (observe-only
+ * is safe) so a spec that lists thresholds without a ladder still warns. Higher
+ * rungs are opt-in because they touch traffic/deploys — a spec must ask for them
+ * explicitly. `.strict()` so a typo'd sub-key fails the build.
+ *
+ * NOTE `egress_block_rate` derives from the `permission_decision` egress
+ * outcomes (no dedicated egress TraceEvent exists); `ttft_ms`/`p95_latency_ms`
+ * derive from the same per-turn/TTFT samples the alert-watchdog accumulates.
+ */
+const sloBlock = z
+    .object({
+    /** Fractional error rate ceiling (unrecovered errors / model calls), e.g. 0.05. */
+    error_rate: z.number().min(0).max(1).optional(),
+    /** p95 per-turn latency ceiling, milliseconds. */
+    p95_latency_ms: z.number().positive().optional(),
+    /** p95 time-to-first-token ceiling, milliseconds. */
+    ttft_ms: z.number().positive().optional(),
+    /** Cost burn ceiling, USD per hour of wall-clock. */
+    cost_per_hour_usd: z.number().positive().optional(),
+    /** Fractional egress-block rate ceiling (egress-blocked / external calls), e.g. 0.1. */
+    egress_block_rate: z.number().min(0).max(1).optional(),
+    /**
+     * Rolling window (seconds) a breach must persist before the ladder fires.
+     * A single blip never mitigates — the monitor only acts on a SUSTAINED
+     * breach across this window. Default 300s (5 min).
+     */
+    window_seconds: z.number().int().positive().optional(),
+    /**
+     * Mitigation ladder, walked in declared order on a sustained breach. Each
+     * rung is executed at most once per session. `alert` is always safe;
+     * `pause-intake` / `rollback` touch traffic + deploys so they are opt-in.
+     */
+    mitigation: z
+        .array(z.enum(["alert", "pause-intake", "rollback"]))
+        .nonempty()
+        .optional(),
+})
+    .strict()
+    .refine((s) => s.error_rate !== undefined ||
+    s.p95_latency_ms !== undefined ||
+    s.ttft_ms !== undefined ||
+    s.cost_per_hour_usd !== undefined ||
+    s.egress_block_rate !== undefined, { message: "observability.slo must declare at least one target threshold" });
+const observabilityBlock = z
+    .object({
+    slo: sloBlock.optional(),
+})
+    .strict()
+    .optional();
 /**
  * Section 47 — blockchain subsystem blocks (cross-cutting). Any shape may
  * declare any subset of `chains` / `wallets` / `contracts` /
@@ -422,6 +707,7 @@ const channelGatewayBlock = z
 const cliSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("cli"),
     agent: z
         .object({
@@ -431,9 +717,17 @@ const cliSchema = z
         // runtime default applies. Raise it for turns that emit large
         // multi-file edits so the model isn't cut off mid-`tool_use`.
         max_tokens: z.number().int().positive().optional(),
+        // Item 22 — provider failover chain (see modelFallbacksBlock docs).
+        model_fallbacks: modelFallbacksBlock,
+        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,
@@ -441,7 +735,10 @@ const cliSchema = z
     compaction: compactionBlock,
     security: securityBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    budget: budgetBlock,
     feedback: feedbackBlock,
+    memory: memoryBlock,
+    observability: observabilityBlock,
     cli: cliOptionsBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
@@ -461,6 +758,7 @@ const workflowStepSchema = z
 const workflowSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("workflow"),
     model: z.string().min(1),
     steps: z.array(workflowStepSchema).min(1),
@@ -543,14 +841,23 @@ const channelAgentSchema = z
     .object({
     model: z.string().min(1),
     instructions: z.string().min(1),
+    // Item 22 — provider failover chain (see modelFallbacksBlock docs).
+    model_fallbacks: modelFallbacksBlock,
+    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,
+    version: versionField,
     target: z.literal("channel"),
     agent: channelAgentSchema,
     channels: channelsBlock,
@@ -559,7 +866,10 @@ const channelSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    budget: budgetBlock,
     feedback: feedbackBlock,
+    memory: memoryBlock,
+    observability: observabilityBlock,
     heartbeat: heartbeatBlock,
     gateway: channelGatewayBlock,
     chains: chainsBlock,
@@ -599,6 +909,7 @@ const graphEdgeSchema = z
 const graphSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("graph"),
     model: z.string().min(1),
     entry: z.string().min(1),
@@ -632,17 +943,29 @@ const managedAgentSchema = z
     .object({
     model: z.string().min(1),
     instructions: z.string().min(1),
+    // Item 22 — provider failover chain (see modelFallbacksBlock docs).
+    model_fallbacks: modelFallbacksBlock,
+    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,
+    version: versionField,
     target: z.literal("managed"),
     agent: managedAgentSchema,
     tenants: z.array(managedTenantSchema).min(1),
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    budget: budgetBlock,
+    memory: memoryBlock,
+    observability: observabilityBlock,
 })
     .strict();
 // Vector-store backend ids accepted in specs. Mirrors `VectorBackendId`
@@ -666,6 +989,7 @@ const pipelineDocumentSchema = z
 const pipelineSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("pipeline"),
     agent: z
         .object({
@@ -731,6 +1055,7 @@ const crewRoutingSchema = z
 const crewSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("crew"),
     /** Crew-wide model fallback used by any role that omits `role.model`. */
     model: z.string().min(1),
@@ -765,6 +1090,7 @@ const researchRetrieveSchema = z
 const researchSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("research"),
     agent: z
         .object({
@@ -782,6 +1108,7 @@ const researchSchema = z
     permissions: permissionsBlock,
     compaction: compactionBlock,
     failure_taxonomy: failureTaxonomyBlock,
+    memory: memoryBlock,
     chains: chainsBlock,
     wallets: walletsBlock,
     contracts: contractsBlock,
@@ -804,6 +1131,7 @@ const batchQueueSchema = z
 const batchSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("batch"),
     agent: z
         .object({
@@ -844,6 +1172,7 @@ const voiceTelephonySchema = z
 const voiceSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("voice"),
     agent: z
         .object({
@@ -878,6 +1207,7 @@ const browserDriverSchema = z
 const browserSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("browser"),
     agent: z
         .object({
@@ -907,6 +1237,7 @@ const browserSchema = z
 const evalSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("eval"),
     agent: z
         .object({
@@ -971,6 +1302,7 @@ const onchainTriggerSchema = z.discriminatedUnion("kind", [
 const onchainSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("onchain"),
     agent: z
         .object({
@@ -1005,6 +1337,7 @@ const onchainSchema = z
 const onchainGameSchema = z
     .object({
     name: safeName,
+    version: versionField,
     target: z.literal("onchain-game"),
     agent: z
         .object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "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.1.8",
+    "@crewhaus/errors": "0.2.1",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },