@mindot/will 0.7.0 → 0.8.0

package/src/cognition/utilities/token.tracker.ts

@@ -16,6 +16,7 @@
  * Exposes as metrics so the orchestrator and runner can log costs,
  * and the ParameterOptimizer can factor cost into optimization decisions.
  */
+import { logger } from '#core/logger'
 import type {
   Duration,
   Tick,
@@ -31,56 +32,46 @@ import { wallClock } from '#core/wall.clock'
 // transport layer (determinism contract). The tracker exposes a neutral
 // onRecord() sink; the stem bridges records onto the transport.
 
+// ── Attribution axes ──────────────────────────────────────
+//
+// Typed rather than free strings so a deviation is caught at the call site
+// instead of surfacing as a silently-unmatched routing rule or a cost bucket
+// nobody notices is empty. These live here (not in #llm) because cognition is
+// the lower layer — #llm already imports from this module, and the reverse
+// would be circular.
+
+/** Top-level cost bucket for an LLM call. */
+export type LLMCallCategory =
+  | 'executive'       // the master consciousness and its facets
+  | 'summarizer'      // rolling memory consolidation
+  | 'embedding'       // semantic-memory vectorisation
+  | 'identity-guard'  // creation-time persona review
+
+/** The actor/subsystem doing the work. */
+export type LLMCallAttribute =
+  | 'master'   // the executive itself
+  | 'facet'    // a spawned focus (conversation, planning, outreach, supervision)
+  | 'memory'   // consolidation / embedding
+  | 'guard'    // a safety reviewer
+
+/** The specific cognitive function being paid for. */
+export type LLMCallFunction =
+  | 'decision'           // the master's fused decision call
+  | 'ideation'           // the deliberate path's propose pass
+  | 'deliberation'       // action choice under contest
+  | 'conversation'       // a live reply
+  | 'outreach'           // an unprompted message
+  | 'planning'           // plan formation / revision
+  | 'supervision'        // plan-step supervision
+  | 'consolidation'      // rolling summary
+  | 'recall'             // embedding a query
+  | 'index'              // embedding a write
+  | 'identity-coherence' // persona review
+
 /** One attributed ledger record (5-axis attribution + tokens + cost). */
 export type TokenLedgerRecord = Record<string, unknown>
 export type TokenRecordListener = ( record: TokenLedgerRecord ) => void
 
-// ── Pricing table (USD per 1M tokens) ─────────────────────
-
-const MODEL_PRICING: Record<string, { input: number; output: number }> = {
-  // OpenAI
-  'openai/gpt-4o':              { input: 2.50,  output: 10.00 },
-  'openai/gpt-4o-mini':         { input: 0.15,  output: 0.60  },
-  'openai/gpt-4-turbo':         { input: 10.00, output: 30.00 },
-  'openai/gpt-3.5-turbo':       { input: 0.50,  output: 1.50  },
-  
-  // Anthropic (Claude 4.x family — prices per 1M tokens)
-  'anthropic/claude-haiku-4-5':  { input: 1.00,  output: 5.00  },
-  'anthropic/claude-sonnet-4-5': { input: 3.00,  output: 15.00 },
-  'anthropic/claude-sonnet-4-6': { input: 3.00,  output: 15.00 },
-  'anthropic/claude-opus-4-7':   { input: 5.00,  output: 25.00 },
-  // Legacy aliases kept for backward compat
-  'anthropic/claude-haiku-4':    { input: 1.00,  output: 5.00  },
-  'anthropic/claude-opus-4':     { input: 5.00,  output: 25.00 },
-  
-  // Z.ai (GLM-5 family). `glm-5.2[1m]` is the same model asking for its 1M
-  // context window — same rate, so it gets its own row rather than relying on
-  // the normalizer (a future long-context tier would price differently).
-  'glm/glm-5.2':                { input: 1.40,  output: 4.40  },
-  'glm/glm-5.2[1m]':            { input: 1.40,  output: 4.40  },
-
-  // Google
-  'google/gemini-2.0-flash':    { input: 0.10,  output: 0.40  },
-  'google/gemini-2.0-pro':      { input: 1.25,  output: 5.00  },
-  
-  // Meta (via Groq/Replicate)
-  'meta/llama-3.3-70b':         { input: 0.59,  output: 0.79  },
-  'meta/llama-4-maverick':      { input: 0.20,  output: 0.60  },
-  
-  // DeepSeek
-  'deepseek/deepseek-v3':       { input: 0.27,  output: 1.10  },
-  'deepseek/deepseek-r1':       { input: 0.55,  output: 2.19  },
-
-  // Embeddings (input-only — no completion tokens). Priced per 1M input tokens.
-  'openai/text-embedding-3-small': { input: 0.02, output: 0 },
-  'openai/text-embedding-3-large': { input: 0.13, output: 0 },
-  'google/text-embedding-004':     { input: 0,    output: 0 },  // free tier
-  'google/gemini-embedding-001':   { input: 0,    output: 0 },  // free tier
-
-  // Fallback for unknown models
-  '__default__':                { input: 3.00,  output: 15.00 },
-}
-
 // ── Prompt-cache pricing (Anthropic) ──────────────────────
 // `input_tokens` in the API usage already EXCLUDES cached tokens, so the full
 // input cost is: fresh input ×1 + cache reads ×0.1 + cache writes ×1.25.
@@ -88,40 +79,83 @@ const CACHE_READ_MULT  = 0.1
 const CACHE_WRITE_MULT = 1.25
 
 /**
- * Normalize a model id to its bare, dateless form so a raw provider model string
- * ("claude-sonnet-4-5-20250929", "anthropic/claude-haiku-4-5") resolves to the
- * right pricing row. Without this, every non-default id missed the `provider/model`
- * keys and silently fell through to __default__ ($3/$15) — pricing Haiku ~3× and
- * DeepSeek ~11× too high, and breaking the self-hosting margin telemetry entirely.
+ * Normalize a model id to its bare form so a raw provider string
+ * ("claude-sonnet-5-20260114", "anthropic/claude-haiku-4-5", "glm-5.2[1m]")
+ * matches a host price keyed plainly — and vice versa. Exact keys are tried
+ * first, so a host that prices a long-context variant differently just lists it
+ * verbatim and that wins.
  */
 function normalizeModelKey( model: string ): string {
   let m = model.toLowerCase().trim()
   const slash = m.lastIndexOf('/')
-  if( slash >= 0 ) m = m.slice( slash + 1 )   // drop "provider/" prefix
-  return m.replace( /[-@]\d{6,8}$/, '')        // drop trailing -YYYYMMDD date stamp
+  if( slash >= 0 ) m = m.slice( slash + 1 )    // drop "provider/" prefix
+  m = m.replace( /\[[^\]]*\]$/, '')             // drop a trailing qualifier, e.g. "[1m]"
+  return m.replace( /[-@]\d{6,8}$/, '')         // drop trailing -YYYYMMDD date stamp
 }
+/** USD per 1M tokens for one model. */
+export interface ModelPrice { input: number; output: number }
+
+/**
+ * Host-supplied prices, keyed by model id. Matching is exact first, then
+ * normalized (provider prefix, date stamp and context qualifier stripped), so
+ * `claude-sonnet-5` matches `claude-sonnet-5-20260114`.
+ *
+ * Prices belong to the host: they change on a vendor's schedule, differ per
+ * account, and are ~0 for a self-hosted model. The engine ships none.
+ */
+export type PriceTable = Record<string, ModelPrice>
+
+/** Models already warned about as unpriced — one line each, not one per call. */
+const _unpricedWarned = new Set<string>()
 
-// Pre-index the pricing table by normalized model name for O(1), date-insensitive
-// lookup. Built once at module load.
-const PRICING_BY_NORM: Record<string, { input: number; output: number }> = ( () => {
-  const out: Record<string, { input: number; output: number }> = {}
-  for( const [ key, price ] of Object.entries( MODEL_PRICING ) ){
-    if( key === '__default__') continue
-    out[ normalizeModelKey( key ) ] = price
+/**
+ * Resolve the price for a model id from the host's table.
+ *
+ * The engine ships no prices at all. A table baked into a release is wrong the
+ * week a vendor changes a rate, differs per account, and is meaningless for a
+ * self-hosted model — and a *partial* table is worse than none, because some
+ * models then report plausible-but-stale numbers while others honestly report
+ * nothing. Prices live with the host, next to the routing policy they inform.
+ *
+ * `null` does NOT mean free — it means *unknown*, and the caller reports zero
+ * cost with `priced: false` so the gap stays visible rather than confidently
+ * wrong. (The removed built-in default priced every unrecognised model at
+ * Sonnet's rate, overstating a budget model's output by ~54×.)
+ */
+export function resolvePricing( model: string, hostPrices?: PriceTable ): ModelPrice | null {
+  if( !hostPrices ) return null
+
+  const exact = hostPrices[ model ]
+  if( exact ) return exact
+
+  // A host table keyed by bare ids still matches a dated / provider-prefixed
+  // model id, and vice versa.
+  const norm = normalizeModelKey( model )
+  if( hostPrices[ norm ] ) return hostPrices[ norm ]
+
+  for( const [ key, price ] of Object.entries( hostPrices ) ){
+    if( normalizeModelKey( key ) === norm ) return price
   }
-  return out
-} )()
-
-/** Resolve the pricing row for any model id (exact, normalized, then default). */
-export function resolvePricing( model: string ): { input: number; output: number } {
-  return PRICING_BY_NORM[ normalizeModelKey( model ) ]
-      ?? MODEL_PRICING[ model ]
-      ?? MODEL_PRICING['__default__']!
+
+  return null
 }
 
 export interface TokenUsage {
   /** Model identifier (e.g., 'openai/gpt-4o') */
   model: string
+  /**
+   * The provider that actually served this call.
+   *
+   * Not derivable from `model`: routing is what makes the same model id
+   * reachable from several places — `deepseek-v3` direct, through a gateway, or
+   * self-hosted — at prices that differ by orders of magnitude. Without this a
+   * host billing across a multi-vendor routing table can attribute spend to a
+   * model but never to the vendor it actually paid.
+   *
+   * Optional because a caller recording usage directly (outside the LLM
+   * director) may not know it; absent means unattributed, not "the default".
+   */
+  provider?: string
   /** Input/prompt tokens consumed */
   promptTokens: number
   /** Output/completion tokens consumed */
@@ -132,16 +166,20 @@ export interface TokenUsage {
   cacheReadTokens?: number
   /** Anthropic prompt-cache write tokens (billed at 1.25× input). Optional. */
   cacheWriteTokens?: number
-  /** Estimated cost in USD */
+  /** Estimated cost in USD. Zero when `priced` is false — unknown, not free. */
   estimatedCostUsd: number
+  /**
+   * Whether a price was found for this model. False ⇒ `estimatedCostUsd` is 0
+   * because nothing priced it, NOT because the call was free. A consumer
+   * summing costs should surface unpriced calls rather than fold them in as
+   * zero.
+   */
+  priced: boolean
 
   // ── 5-axis cost attribution ──────────────────────────────
-  /** Top-level cost bucket: 'executive' | 'summarizer' | 'embedding' | 'identity-guard' | … */
-  category: string
-  /** Actor/subsystem doing the work: 'master' | 'facet' | 'memory' | 'guard' | … */
-  attribute: string
-  /** Cognitive function: 'decision' | 'ideation' | 'conversation' | 'planning' | 'deliberation' | 'outreach' | 'consolidation' | 'recall' | 'index' | 'identity-coherence' | … */
-  function: string
+  category:  LLMCallCategory
+  attribute: LLMCallAttribute
+  function:  LLMCallFunction
   /** Optional specific id or namespace: facet id, entity id, model name. */
   scope?: string
   /** Human-readable label — auto-composed from the axes when the caller omits it. */
@@ -157,15 +195,21 @@ export interface TokenUsage {
 }
 
 /** What callers pass to {@link TokenTracker.recordUsage} — cost and label are derived. */
-export type RecordUsageInput = Omit<TokenUsage, 'estimatedCostUsd' | 'label'> & { label?: string }
+export type RecordUsageInput = Omit<TokenUsage, 'estimatedCostUsd' | 'label' | 'priced'> & { label?: string }
 
 /** Compose a stable, readable label from the attribution axes. */
-function composeLabel( m: { category: string; attribute: string; function: string; scope?: string } ): string {
+function composeLabel( m: { category: LLMCallCategory; attribute: LLMCallAttribute; function: LLMCallFunction; scope?: string } ): string {
   const base = `${m.category}/${m.attribute}/${m.function}`
   return m.scope ? `${base}#${m.scope}` : base
 }
 
 export interface TokenTrackerConfig {
+  /**
+   * Host-supplied model prices (USD per 1M tokens), merged from the per-provider
+   * `prices` maps in `WillLLMConfig.providers`. These win over the built-in
+   * fallback table. Omitted ⇒ fallback only.
+   */
+  prices?: PriceTable
   /** Whether to emit cost events */
   emitCostEvents?: boolean
   /** Cost threshold for warning events */
@@ -186,6 +230,7 @@ export class TokenTracker implements SimulationEngine {
   
   private _emitCostEvents: boolean
   private _costWarningThreshold: number
+  private _prices: PriceTable | undefined
 
   // All recorded usage for the simulation run
   private _usageLog: TokenUsage[] = []
@@ -200,6 +245,11 @@ export class TokenTracker implements SimulationEngine {
   private _categoryTokens = new Map<string, { prompt: number; completion: number }>()
   private _functionCosts  = new Map<string, number>()
   private _functionTokens = new Map<string, { prompt: number; completion: number }>()
+  // Per-provider spend. The axis a host actually reconciles against invoices —
+  // "which vendor did we pay?" is not answerable from the model id once routing
+  // can reach one model through several of them.
+  private _providerCosts  = new Map<string, number>()
+  private _providerTokens = new Map<string, { prompt: number; completion: number }>()
 
   // Per-tick costs (for spike detection)
   private _tickCosts: number[] = []
@@ -219,6 +269,7 @@ export class TokenTracker implements SimulationEngine {
   constructor( config: TokenTrackerConfig = {} ){
     this._emitCostEvents        = config.emitCostEvents        ?? true
     this._costWarningThreshold  = config.costWarningThresholdUsd ?? 0.05
+    this._prices                = config.prices
     this._ledgerPath = ( config.writeLedger && config.willId )
       ? `./data/wills/${config.willId}/debug/token-report.jsonl`
       : null
@@ -231,18 +282,31 @@ export class TokenTracker implements SimulationEngine {
    * Called by LLMDirector.call after each completion (src/llm/index.ts).
    */
   recordUsage( usage: RecordUsageInput ): void {
-    const pricing    = resolvePricing( usage.model )
+    const pricing    = resolvePricing( usage.model, this._prices )
     const cacheRead  = usage.cacheReadTokens  ?? 0
     const cacheWrite = usage.cacheWriteTokens ?? 0
-    const costUsd =
-      ( usage.promptTokens     / 1_000_000 ) * pricing.input  +
-      ( usage.completionTokens / 1_000_000 ) * pricing.output +
-      ( cacheRead              / 1_000_000 ) * pricing.input * CACHE_READ_MULT  +
-      ( cacheWrite             / 1_000_000 ) * pricing.input * CACHE_WRITE_MULT
+
+    // No price ⇒ cost 0 and `priced: false`. Warn once per model id so an
+    // unconfigured provider is visible without flooding the log.
+    if( !pricing && !_unpricedWarned.has( usage.model ) ){
+      _unpricedWarned.add( usage.model )
+      logger.warn(
+        `[tokens] no price for "${usage.model}" — reporting cost 0 for it. ` +
+        `Supply one via llm.providers.<provider>.prices to get cost telemetry.`
+      )
+    }
+
+    const costUsd = pricing
+      ? ( usage.promptTokens     / 1_000_000 ) * pricing.input  +
+        ( usage.completionTokens / 1_000_000 ) * pricing.output +
+        ( cacheRead              / 1_000_000 ) * pricing.input * CACHE_READ_MULT  +
+        ( cacheWrite             / 1_000_000 ) * pricing.input * CACHE_WRITE_MULT
+      : 0
 
     const full: TokenUsage = {
       ...usage,
       label:            usage.label ?? composeLabel( usage ),
+      priced:           pricing !== null,
       estimatedCostUsd: Math.round( costUsd * 1_000_000 ) / 1_000_000, // round to micro-dollars
     }
 
@@ -256,6 +320,9 @@ export class TokenTracker implements SimulationEngine {
     // Per-axis breakdowns — the repartition surface (category × function).
     this._accumulate( this._categoryCosts, this._categoryTokens, full.category, full )
     this._accumulate( this._functionCosts, this._functionTokens, full.function, full )
+    // Unattributed rather than guessed: a caller that did not say which
+    // provider served the call must not be silently folded into the default.
+    this._accumulate( this._providerCosts, this._providerTokens, full.provider ?? 'unattributed', full )
 
     // Complete attributed ledger record (every call, all axes + cost): notify
     // record listeners (the stem forwards them onto the transport) and mirror to
@@ -280,6 +347,7 @@ export class TokenTracker implements SimulationEngine {
       tick:          full.tick,
       ts:            new Date( wallClock() ).toISOString(), // determinism-ok: ledger timestamp is telemetry, never replay state
       model:         full.model,
+      provider:      full.provider,
       category:      full.category,
       attribute:     full.attribute,
       function:      full.function,
@@ -291,6 +359,10 @@ export class TokenTracker implements SimulationEngine {
       cacheWriteTok: full.cacheWriteTokens ?? 0,
       estPromptTok:  full.estPromptTokens,
       costUsd:       full.estimatedCostUsd,
+      // Whether costUsd came from a real price. False ⇒ 0 because nothing
+      // priced this model, NOT because the call was free — a consumer summing
+      // spend must not fold unpriced calls in as zero.
+      priced:        full.priced,
       latencyMs:     full.latencyMs,
     }
 
@@ -347,31 +419,34 @@ export class TokenTracker implements SimulationEngine {
     if( this._tickCosts.length > this._maxTickCostSamples )
       this._tickCosts.shift()
 
-    // Metrics
+    // Metrics — TOKENS ONLY (W8c).
+    //
+    // Token counts are a physical, deterministic fact of a call and belong in
+    // state. Dollars are the host's accounting over that fact: prices differ per
+    // account, change on a vendor's schedule, and are ~0 self-hosted. Nothing in
+    // cognition ever read them (the sole consumer was a console runner), yet
+    // while they sat in state a host editing its price table changed state bytes
+    // and broke replay-equivalence over a number that influenced nothing.
+    //
+    // Cost still reaches the host every call on the ledger path
+    // (`onRecord` → the stem's transport bridge), which is where it was already
+    // being consumed. See `totalCostUsd` / `costBreakdown()` for in-process reads.
     commands.metrics!.push(
       [ 'llm.prompt_tokens_total',      this._totalPromptTokens ],
       [ 'llm.completion_tokens_total',  this._totalCompletionTokens ],
-      [ 'llm.cost_total_usd',           this._totalCost ],
-      [ 'llm.cost_this_tick_usd',       tickCost ],
-      [ 'llm.cost_avg_per_tick_usd',    this._averageTickCost() ],
       [ 'llm.total_calls',              this._usageLog.length ],
     )
 
-    // Per-axis cost + token breakdown — the transparency surface for
-    // "how much goes into conversation vs executive vs embedding" (by category)
-    // and "decision vs ideation vs conversation vs planning…" (by function).
-    for( const [ cat, cost ] of this._categoryCosts ){
-      commands.metrics!.push([ `llm.cost.${cat}`, cost ])
-    }
+    // Per-axis TOKEN breakdown — the transparency surface for "how much goes
+    // into conversation vs executive vs embedding". The matching cost
+    // breakdown is host-side now (W8c); `costBreakdown()` still exposes it
+    // in-process for anyone holding the tracker.
     for( const [ cat, tok ] of this._categoryTokens ){
       commands.metrics!.push(
         [ `llm.prompt_tokens.${cat}`,     tok.prompt ],
         [ `llm.completion_tokens.${cat}`, tok.completion ],
       )
     }
-    for( const [ fn, cost ] of this._functionCosts ){
-      commands.metrics!.push([ `llm.cost.fn.${fn}`, cost ])
-    }
 
     // Cost warning event
     if( tickCost > this._costWarningThreshold 
@@ -427,6 +502,24 @@ export class TokenTracker implements SimulationEngine {
     return this._functionTokens
   }
 
+  /**
+   * Cost broken down by provider ('anthropic' | 'glm' | 'moonshot' | …), plus
+   * an `unattributed` bucket for usage recorded without one.
+   *
+   * This is the axis a host reconciles against vendor invoices. Calls whose
+   * model went unpriced contribute 0 here, so compare against
+   * `getUsageLog()`'s `priced` flag before treating a small number as a small
+   * bill.
+   */
+  get providerBreakdown(): ReadonlyMap<string, number> {
+    return this._providerCosts
+  }
+
+  /** Token counts (prompt + completion) broken down by provider. */
+  get providerTokenBreakdown(): ReadonlyMap<string, { prompt: number; completion: number }> {
+    return this._providerTokens
+  }
+
   /** Cost per call average */
   get averageCostPerCall(): number {
     if( this._usageLog.length === 0 ) return 0
@@ -461,6 +554,8 @@ export class TokenTracker implements SimulationEngine {
     this._categoryTokens.clear()
     this._functionCosts.clear()
     this._functionTokens.clear()
+    this._providerCosts.clear()
+    this._providerTokens.clear()
     this._tickCosts = []
   }
 

package/src/host/boot.ts

@@ -12,9 +12,11 @@
 //   WILL_NAME        display name                    (default "Will")
 //   WILL_IDENTITY    persona prompt                  (default a minimal self)
 //   WILL_TIER        basic | standard | full         (default standard)
-//   WILL_LLM         mock | anthropic | glm          (default: auto — anthropic when
-//                                                     ANTHROPIC_API_KEY is set, glm when
-//                                                     ZAI_API_KEY is, else mock)
+//   WILL_LLM         mock | any provider name        (default: auto — whichever
+//                                                     provider's own key is set,
+//                                                     else the zero-key mock)
+//   WILL_LLM_MODEL   concrete model id               (REQUIRED for a live mind —
+//                                                     the engine has no default)
 //   WILL_TICK_MS     ms per tick                     (default 1000)
 //   WILL_SEED        deterministic seed (testing)    (default unseeded/wall-time)
 //   WILL_PMA_PATH    PMA artifact path               (default ./.will/<name>.pma.json)
@@ -25,10 +27,10 @@
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { setLogger } from '#core/logger'
-import { Will, type CreateWillOptions } from '#sdk/will'
+import { Will, detectProvider, type CreateWillOptions } from '#sdk/will'
 import type { PMASnapshot } from '#pma/index'
 import { connectMcpEffectors, type McpToolsSource } from '#root/mcp/effectors'
-import { anthropicWireHeaders, defaultBaseFor, defaultModelFor } from '#llm/index'
+import { anthropicWireHeaders, defaultBaseFor, knownWireFor, providerKeyFromEnv, PROVIDER_KEY_ENV, type LLMProvider, type LLMWire } from '#llm/index'
 
 /**
  * Route every engine log line to stderr. For `will mcp`, stdout is the MCP
@@ -47,19 +49,51 @@ function slug( s: string ): string {
 
 /** The LLM mode the hosts will boot with: an explicit WILL_LLM, else whichever
  *  provider's key is present, else the zero-key mock. */
-export function resolveLlmMode(): 'mock' | 'anthropic' | 'glm' {
-  const explicit = process.env.WILL_LLM as 'mock' | 'anthropic' | 'glm' | undefined
-  if( explicit ) return explicit
-  if( process.env.ANTHROPIC_API_KEY ) return 'anthropic'
-  if( process.env.ZAI_API_KEY ) return 'glm'
-  return 'mock'
+export function resolveLlmMode(): 'mock' | LLMProvider {
+  const explicit = process.env.WILL_LLM
+  if( explicit ) return explicit as 'mock' | LLMProvider
+  // The SDK's own detection, not a copy of it. Boot used to know only
+  // anthropic/glm, so once the provider set widened, a Will booting live on
+  // (say) Kimi had its preflight silently skipped — the one check that exists
+  // to stop a mind that boots, perceives, and never speaks.
+  return detectProvider()
 }
 
 /** The key for a live mode — the provider-agnostic override first, then the
  *  provider's own env. */
-function resolveLlmKey( mode: 'anthropic' | 'glm'): string | undefined {
-  return process.env.WILL_LLM_API_KEY
-    ?? ( mode === 'glm' ? process.env.ZAI_API_KEY : process.env.ANTHROPIC_API_KEY )
+function resolveLlmKey( mode: LLMProvider ): string | undefined {
+  return process.env.WILL_LLM_API_KEY ?? providerKeyFromEnv( mode )
+}
+
+/**
+ * The smallest real completion request, in a given wire's dialect.
+ *
+ * `null` means "this wire has no cheap ping here" — the caller raises the mind
+ * unchecked rather than inventing a request shape and reading its rejection as
+ * a broken provider.
+ */
+export function pingRequest(
+  wire: LLMWire, base: string, model: string, key: string, provider: LLMProvider,
+): { url: string; headers: Record<string, string>; body: unknown } | null {
+  const messages = [ { role: 'user', content: 'ping' } ]
+  switch( wire ){
+    case 'anthropic':
+      return {
+        url:     `${ base }/messages`,
+        headers: anthropicWireHeaders( provider, key ),
+        body:    { model, max_tokens: 1, messages },
+      }
+    case 'openai':
+      return {
+        url:     `${ base }/chat/completions`,
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${ key }` },
+        body:    { model, max_tokens: 1, messages },
+      }
+    // Gemini authenticates in the query string and nests its payload
+    // differently enough that a hand-rolled ping here would drift from the
+    // client that actually makes the calls. Better unchecked than wrong.
+    case 'google': return null
+  }
 }
 
 /**
@@ -83,7 +117,7 @@ async function preflightLLM( anatomy: string ): Promise<void> {
 
   const key = resolveLlmKey( mode )
   if( !key ){
-    const expected = mode === 'glm' ? 'ZAI_API_KEY' : 'ANTHROPIC_API_KEY'
+    const expected = PROVIDER_KEY_ENV[ mode ] ?? 'WILL_LLM_API_KEY'
     console.error(`[will] WILL_LLM=${ mode } but no ${ expected } / WILL_LLM_API_KEY is set.`)
     console.error('[will] The Will would boot, perceive, and never speak. Set a key, or run keyless with WILL_LLM=mock.')
     process.exit( 2 )
@@ -91,16 +125,38 @@ async function preflightLLM( anatomy: string ): Promise<void> {
 
   // The ping validates key + balance + reachability, which is the failure class
   // that strands an operator. It uses the pinned model when there is one, so a
-  // bad model id is caught too; otherwise the cheapest model stands in. GLM
-  // speaks the same wire at Z.ai's compat endpoint, so one ping serves both.
-  const base  = process.env.WILL_LLM_BASE_URL ?? defaultBaseFor( mode )
+  // bad model id is caught too.
+  const base = process.env.WILL_LLM_BASE_URL ?? defaultBaseFor( mode )
+  if( !base ){
+    console.error(`[will] WILL_LLM=${ mode } has no known base URL — set WILL_LLM_BASE_URL.`)
+    process.exit( 2 )
+  }
+  // The ping needs *a* model id. WILL_LLM_MODEL is the one the Will will
+  // actually use, so preferring it means a bad id is caught here rather than at
+  // the first tick. Without it there is nothing honest to send: the engine no
+  // longer carries a default model, so say so plainly instead of guessing.
   const model = process.env.WILL_LLM_MODEL
-    ?? ( mode === 'glm' ? defaultModelFor('glm') : 'claude-haiku-4-5-20251001')
+  if( !model ){
+    console.error(`[will] WILL_LLM_MODEL is not set. The engine has no default model —`)
+    console.error('[will] pick one for your provider (e.g. WILL_LLM_MODEL=claude-sonnet-4-5-20250929).')
+    process.exit( 2 )
+  }
+
+  // Ping in the provider's OWN dialect. This used to be hardcoded to the
+  // Anthropic wire, which was fine when boot knew only anthropic and glm. With
+  // the provider set widened it became a false negative: an OpenAI-wire
+  // provider answers 404 to `/messages`, preflight read that as "the LLM
+  // refused", and a perfectly working Will never got raised.
+  const ping = pingRequest( knownWireFor( mode ) ?? 'openai', base, model, key, mode )
+  if( !ping ){
+    console.error(`[will] no preflight ping for the ${ mode } wire — raising the mind unchecked.`)
+    return
+  }
   try {
-    const res = await fetch(`${ base }/messages`, {
+    const res = await fetch( ping.url, {
       method:  'POST',
-      headers: anthropicWireHeaders( mode, key ),
-      body:    JSON.stringify( { model, max_tokens: 1, messages: [ { role: 'user', content: 'ping' } ] } ),
+      headers: ping.headers,
+      body:    JSON.stringify( ping.body ),
       signal:  AbortSignal.timeout( 20_000 ),
     } )
     if( res.ok ) return

package/src/index.ts

@@ -26,6 +26,41 @@ export {
 
 export { assembleMind, type WillConfig } from '#stem/mind'
 
+// Model routing — which model serves which call.
+//
+// These were reachable only through `WillConfig.llm.router`'s structural type,
+// which meant the reference implementation this ships *for* hosts to use could
+// not be imported by one. A seam nobody can import is not a seam.
+//
+// The engine carries mechanism only: a router sees what kind of work a call is
+// and how much the moment demands, never who is paying or what anything costs.
+// The table itself is the host's.
+export {
+  NULL_ROUTER,
+  TableRouter,
+  chainRouters,
+  isNullRouter,
+  type ModelRouter,
+  type ModelRoute,
+  type RoutingRule,
+} from '#llm/routing'
+
+// Provider vocabulary — the wire each known provider speaks and where it lives.
+// A provider outside this table works identically once the host declares its
+// `wire` and `baseUrl` on the `llm.providers` entry.
+export {
+  KNOWN_PROVIDERS,
+  knownWireFor,
+  defaultBaseFor,
+  BACKGROUND_DEMAND,
+  ESCALATION_DEMAND,
+  type LLMProvider,
+  type KnownProvider,
+  type LLMWire,
+  type LLMCallMeta,
+  type ProviderCredential,
+} from '#llm/index'
+
 // External transport — the unified bidirectional envelope channel between a Will
 // and its host peer (backend). Exposes the transport interface, every envelope
 // type, and the three implementations: