@mindot/will 0.7.0 → 0.9.0

package/src/llm/index.ts

@@ -6,72 +6,176 @@ import { logger } from '#core/logger'
 import type { Tick } from '#core/types'
 import type { SessionLogger } from '#stem/tracts/session.logger'
 import { writeFileSync, mkdirSync } from 'node:fs'
-import type { TokenTracker } from '#cognition/utilities/token.tracker'
+import type {
+  TokenTracker, LLMCallCategory, LLMCallAttribute, LLMCallFunction,
+  LLMCallProcess,
+} from '#cognition/utilities/token.tracker'
+import { type ModelRouter, isNullRouter } from '#llm/routing'
 import { getCompletionRecorder, getCompletionSource } from '#core/completion.recorder'
 import type { LLMCompletionRecord } from '#core/completion.recorder'
 import { withGate } from '#llm/gate'
 import { matchConversationFocus, wrapReplyText } from '#llm/wire.contracts'
 
-export type LLMProvider = 'anthropic' | 'glm' | 'deepseek' | 'openai' | 'google'
+/**
+ * The request/response dialect an endpoint speaks. This — not the provider's
+ * name — is what the transport actually branches on.
+ */
+export type LLMWire = 'anthropic' | 'openai' | 'google'
+
+/**
+ * The provider and model a mock (test-mode) Will reports.
+ *
+ * A mock Will never reaches a network, so it needs no credentials — but it
+ * still records completions, and the tape should say plainly that nothing real
+ * served them rather than borrow some vendor's name.
+ */
+export const MOCK_PROVIDER = 'mock'
+export const MOCK_MODEL    = 'mock'
+
+/** Providers with built-in defaults. Any other string is equally valid. */
+export type KnownProvider =
+  | 'anthropic'   // Claude
+  | 'glm'         // Z.ai
+  | 'openai'      // GPT + the embedding models
+  | 'google'      // Gemini
+  | 'deepseek'
+  | 'moonshot'    // Kimi
+  | 'qwen'        // Alibaba Model Studio / DashScope
+  | 'xai'         // Grok
+  | 'minimax'
+  | 'mistral'
+  | 'ollama'      // local
+  | 'vllm'        // local / self-hosted
 
 /**
- * Providers that speak the Anthropic Messages wire.
+ * A provider name. Deliberately open: the field of providers changes monthly,
+ * and a closed union meant a host reaching Kimi or Qwen had to masquerade as
+ * `openai`, which then lied on the completion tape and in cost attribution.
  *
- * Z.ai ships a real Anthropic-compatible endpoint for GLM — it is what Claude
- * Code itself targets — so GLM rides this path rather than the OpenAI scaffold.
- * That buys it everything the path already has: token streaming, the first-byte
- * deadline, prompt-cache breakpoints, and the structured-output contract. GLM is
- * therefore a second *production* provider, not a fifth scaffold.
+ * `(string & {})` keeps editor autocomplete for the known names while accepting
+ * anything. A provider outside {@link KNOWN_PROVIDERS} simply has to declare its
+ * `wire` and `baseUrl` — see `WillLLMConfig.providers`.
  */
-const ANTHROPIC_WIRE = new Set<LLMProvider>( [ 'anthropic', 'glm' ] )
+export type LLMProvider = KnownProvider | ( string & {} )
 
-/** Does this provider accept Anthropic-shaped requests? */
-export function speaksAnthropicWire( provider: LLMProvider ): boolean {
-  return ANTHROPIC_WIRE.has( provider )
+/**
+ * Built-in wire + base URL per provider. This is *data*, not support: it saves
+ * a host from looking up an endpoint, and nothing more. Any provider absent
+ * from this table works identically once the host declares `wire` + `baseUrl`
+ * on its `llm.providers` entry.
+ *
+ * WHY THIS TABLE SURVIVES WHEN THE PRICE TABLE DID NOT. A stale price is
+ * invisible: it produces a confident wrong number nobody doubts. A stale base
+ * URL fails on the first call, loudly, with the endpoint in the message. They
+ * also move on completely different clocks — vendors reprice quarterly, and
+ * change an API host about once a decade. Convenience is worth it when being
+ * wrong is self-announcing.
+ *
+ * REGIONAL ENDPOINTS. `moonshot`, `qwen` and `minimax` all run separate
+ * mainland-China hosts (`api.moonshot.cn`, `dashscope.aliyuncs.com`,
+ * `api.minimaxi.com`). The international host is the default here; a key issued
+ * on the other one authenticates nowhere, so a host on a China account must set
+ * `baseUrl` explicitly.
+ */
+export const KNOWN_PROVIDERS: Record<string, { wire: LLMWire; baseUrl: string }> = {
+  // Never dialled — present so a test-mode Will resolves an endpoint without
+  // demanding a provider the run will never use.
+  [ MOCK_PROVIDER ]: { wire: 'anthropic', baseUrl: 'http://mock.invalid/v1' },
+
+  // ── Anthropic wire ──────────────────────────────────────────
+  anthropic: { wire: 'anthropic', baseUrl: 'https://api.anthropic.com/v1' },
+  // Z.ai documents the base as `…/api/anthropic` because the Anthropic SDK
+  // appends `/v1/messages`; this client appends `/messages`, so the version
+  // segment belongs here — verified against the live endpoint.
+  glm:       { wire: 'anthropic', baseUrl: 'https://api.z.ai/api/anthropic/v1' },
+
+  // ── OpenAI wire ─────────────────────────────────────────────
+  openai:    { wire: 'openai', baseUrl: 'https://api.openai.com/v1' },
+  deepseek:  { wire: 'openai', baseUrl: 'https://api.deepseek.com/v1' },
+  moonshot:  { wire: 'openai', baseUrl: 'https://api.moonshot.ai/v1' },
+  qwen:      { wire: 'openai', baseUrl: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1' },
+  xai:       { wire: 'openai', baseUrl: 'https://api.x.ai/v1' },
+  minimax:   { wire: 'openai', baseUrl: 'https://api.minimax.io/v1' },
+  mistral:   { wire: 'openai', baseUrl: 'https://api.mistral.ai/v1' },
+  // Local runtimes. The port is the project default; a host that moved it sets
+  // `baseUrl`. Both still want an `apiKey` — any non-empty string will do,
+  // since neither checks it.
+  ollama:    { wire: 'openai', baseUrl: 'http://localhost:11434/v1' },
+  vllm:      { wire: 'openai', baseUrl: 'http://localhost:8000/v1' },
+
+  // ── Google wire ─────────────────────────────────────────────
+  // Gemini also exposes an OpenAI-compatible surface; this client speaks the
+  // native one, which is where its caching and multimodal parts actually live.
+  google:    { wire: 'google', baseUrl: 'https://generativelanguage.googleapis.com/v1beta' },
 }
 
-/** Official API base URL (including version segment) for a provider. */
-export function defaultBaseFor( provider: LLMProvider ): string {
-  switch( provider ){
-    case 'anthropic': return 'https://api.anthropic.com/v1'
-    // Z.ai documents the base as `…/api/anthropic` because the Anthropic SDK
-    // appends `/v1/messages`; this client appends `/messages`, so the version
-    // segment belongs here — verified against the live endpoint.
-    case 'glm':       return 'https://api.z.ai/api/anthropic/v1'
-    case 'openai':    return 'https://api.openai.com/v1'
-    case 'deepseek':  return 'https://api.deepseek.com/v1'
-    case 'google':    return 'https://generativelanguage.googleapis.com/v1beta'
-  }
+/**
+ * The conventional env var holding each provider's key.
+ *
+ * This is *not* the fallback that W9 removed. That one read `ANTHROPIC_API_KEY`
+ * whatever provider was configured, so a Will pointed at another vendor sent it
+ * an Anthropic key. This lookup is keyed by the resolved provider: a `moonshot`
+ * Will reads `MOONSHOT_API_KEY` and nothing else, and an unknown provider gets
+ * nothing rather than someone else's secret.
+ *
+ * `WILL_LLM_API_KEY` still wins over all of it — it is the explicit statement.
+ */
+export const PROVIDER_KEY_ENV: Record<string, string> = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  glm:       'ZAI_API_KEY',
+  openai:    'OPENAI_API_KEY',
+  google:    'GOOGLE_API_KEY',
+  deepseek:  'DEEPSEEK_API_KEY',
+  moonshot:  'MOONSHOT_API_KEY',
+  qwen:      'DASHSCOPE_API_KEY',
+  xai:       'XAI_API_KEY',
+  minimax:   'MINIMAX_API_KEY',
+  mistral:   'MISTRAL_API_KEY',
 }
 
 /**
- * The model the executive recruits when none is pinned.
+ * The provider's own key from the environment, if it has a conventional one.
  *
- * Provider-specific because the default is *sent* — a GLM Will with no
- * `WILL_LLM_MODEL` would otherwise ask Z.ai for a Claude id and get a 404 it
- * could do nothing with. The scaffolded providers (openai/deepseek/google) keep
- * today's value: they need an explicit `WILL_LLM_MODEL` to work at all, and
- * inventing ids for them here would look like support that does not exist.
+ * An empty or blank value counts as absent. A `.env` that lists every provider
+ * and fills in one — which is what the template invites — leaves the rest as
+ * `KEY=`, and a present-but-empty key is not a key.
  */
-export function defaultModelFor( provider: LLMProvider ): string {
-  return provider === 'glm' ? 'glm-5.2' : 'claude-sonnet-4-5-20250929'
+export function providerKeyFromEnv( provider: LLMProvider ): string | undefined {
+  const name = PROVIDER_KEY_ENV[ provider ]
+  if( !name ) return undefined
+  // Gemini ships under two names in the wild; both mean the same account.
+  const value = nonBlank( process.env[ name ] )
+    ?? ( provider === 'google' ? nonBlank( process.env[ 'GEMINI_API_KEY' ] ) : undefined )
+  return value
+}
+
+const nonBlank = ( v: string | undefined ): string | undefined => v && v.trim() ? v : undefined
+
+/** Built-in wire for a known provider, or undefined — the host must declare it. */
+export function knownWireFor( provider: LLMProvider ): LLMWire | undefined {
+  return KNOWN_PROVIDERS[ provider ]?.wire
+}
+
+/** Built-in base URL for a known provider, or undefined — the host must declare it. */
+export function defaultBaseFor( provider: LLMProvider ): string | undefined {
+  return KNOWN_PROVIDERS[ provider ]?.baseUrl
 }
 
 /**
  * Auth + version headers for the Anthropic wire.
  *
- * Anthropic authenticates with `x-api-key`. Z.ai's compat endpoint accepts
- * either that or the `Authorization: Bearer` its own docs describe (both were
- * probed against the live endpoint; each is read and validated). GLM sends both
- * — same secret, same host — so the mind keeps working whichever one Z.ai
- * eventually settles on.
+ * Anthropic authenticates with `x-api-key`. Compatible endpoints (Z.ai's GLM,
+ * and every third-party clone since) generally document
+ * `Authorization: Bearer`, and accept either. So we send `x-api-key` always,
+ * and add the bearer for everyone *except* Anthropic itself — same secret, same
+ * host, and the mind keeps working whichever header the endpoint reads.
  */
 export function anthropicWireHeaders( provider: LLMProvider, apiKey: string ): Record<string, string> {
   return {
     'Content-Type':      'application/json',
     'anthropic-version': '2023-06-01',
     'x-api-key':         apiKey,
-    ...( provider === 'glm' ? { Authorization: `Bearer ${ apiKey }` } : {} ),
+    ...( provider === 'anthropic' ? {} : { Authorization: `Bearer ${ apiKey }` } ),
   }
 }
 export interface LLMDirectorConfig {
@@ -103,6 +207,49 @@ export interface LLMDirectorConfig {
    * replay runs). This replaces the former process-global getTokenTracker().
    */
   tokenTracker?: TokenTracker | null
+  /**
+   * MODEL_ROUTING W3 — per-call model selection. Absent (or NULL_ROUTER) means
+   * every call uses the default model below, exactly as before the seam existed.
+   * A router that throws, or names a provider with no usable credential, falls
+   * back to the default: a routing problem must never kill a running mind.
+   */
+  router?: ModelRouter | null
+  /**
+   * Per-provider credentials for routed calls. The top-level `apiKey`/`baseUrl`
+   * remain the default entry; a route to a provider absent from this map falls
+   * back to the default endpoint.
+   */
+  credentials?: Partial<Record<string, ProviderCredential>>
+  /**
+   * Dialect for the default provider. Required when the provider is not one of
+   * {@link KNOWN_PROVIDERS} — the engine will not guess how to talk to an
+   * endpoint it has never heard of.
+   */
+  wire?: LLMWire
+}
+
+/**
+ * Everything a single call needs to reach a model. Resolved once per call and
+ * threaded through the provider methods — never stored on the instance, because
+ * the concurrency gate lets several calls be in flight on one director at once
+ * and per-call state on `this` would race between them.
+ */
+/** What a host supplies so a routed provider can be reached. */
+export interface ProviderCredential {
+  apiKey:   string
+  baseUrl?: string
+  /** Required for providers outside {@link KNOWN_PROVIDERS}. */
+  wire?:    LLMWire
+}
+
+export interface CallEndpoint {
+  provider:        LLMProvider
+  /** The dialect to speak. Resolved once; the transport branches on this. */
+  wire:            LLMWire
+  model:           string
+  apiKey:          string
+  baseUrl:         string
+  maxOutputTokens: number
 }
 
 // ── LLM call result ──────────────────────────────────────────
@@ -124,20 +271,102 @@ export interface LLMCallResult {
  * here, letting the TokenTracker break spend down per category for transparency.
  */
 export interface LLMCallMeta {
-  /** Top-level cost bucket: 'executive' | 'summarizer' | 'embedding' | 'identity-guard' | … */
-  category: string
-  /** The actor/subsystem doing the work: 'master' | 'facet' | 'memory' | 'guard' | … */
-  attribute: string
-  /** The specific cognitive function: 'decision' | 'ideation' | 'conversation' | 'planning' | 'deliberation' | 'outreach' | 'consolidation' | 'recall' | 'index' | 'identity-coherence' | … */
-  function: string
+  /** Top-level cost bucket. */
+  category: LLMCallCategory
+  /** The actor/subsystem doing the work. */
+  attribute: LLMCallAttribute
+  /** The specific cognitive function. */
+  process: LLMCallProcess
+  /** The specific cognitive function. */
+  function: LLMCallFunction
   /** Optional specific id or namespace: facet id, entity id, model name. */
   scope?: string
   /** Free-form human-readable label. Auto-composed from the axes when omitted. */
   label?: string
+  /**
+   * How much this call demands, 0..1 — MODEL_ROUTING W0.
+   *
+   * A *cognitive* measure, never a commercial one: it says how consequential or
+   * uncertain this moment is, never who is paying for it.
+   *
+   * What actually reports it today:
+   *   · the master and every facet — including the deliberation facet — forward
+   *     `effortScore`, the a-priori effort gate (uncertainty, prior confidence,
+   *     novelty, a pending reply, stress load);
+   *   · structurally background work (summarising, the identity guard) reports a
+   *     low constant, because it is background whether the mind is calm or in
+   *     crisis.
+   *
+   * Note what is NOT here: agency's `stakes( winner, bias )` — the consequence
+   * of the specific choice under contest — is computed in
+   * `agency/selection.scoring.ts` and never reaches a call. So a deliberation
+   * facet currently reports the tick's general effort, not the stakes of the
+   * choice it is deliberating. Carrying it is MODEL_ROUTING W1, still open.
+   * This comment previously claimed deliberation passed those stakes; it does
+   * not, and a doc comment that ships to npm is a bad place to be aspirational.
+   *
+   * Absent means UNKNOWN, not zero: a consumer must fall back to its default
+   * rather than treat a missing value as "cheapest possible".
+   *
+   * This field is inert with respect to cognition. It rides along to whoever
+   * resolves the model for a call; no engine may read it back and behave
+   * differently, or the routing layer becomes a hidden input to the mind.
+   */
+  demand?: number
 }
 
+/** Structurally background work — see `LLMCallMeta.demand`. */
+export const BACKGROUND_DEMAND = 0.1
+
+/**
+ * Escalation is elevated by construction: the buffer only fires once something
+ * has already failed to resolve on its own.
+ */
+export const ESCALATION_DEMAND = 0.7
+
 /** Default attribution when a caller does not tag itself (back-compat). */
-const DEFAULT_CALL_META: LLMCallMeta = { category: 'executive', attribute: 'master', function: 'decision' }
+const DEFAULT_CALL_META: LLMCallMeta = { category: 'executive', attribute: 'master', process: 'decision', function: '-' }
+
+/**
+ * Fill in wire and base URL, or say clearly what is missing.
+ *
+ * Known providers supply both from {@link KNOWN_PROVIDERS}; anything else must
+ * declare them. The engine refuses to guess how to talk to an endpoint it has
+ * never heard of — a wrong guess is a 404 at the worst possible moment, and
+ * previously the guess was "Anthropic", which is how a GLM Will could end up
+ * asking Z.ai for a Claude model id.
+ */
+export function resolveEndpoint( spec: {
+  provider: LLMProvider
+  model: string
+  apiKey: string
+  baseUrl?: string | undefined
+  wire?: LLMWire | undefined
+  maxOutputTokens: number
+} ): CallEndpoint {
+  const wire = spec.wire ?? knownWireFor( spec.provider )
+  if( !wire )
+    throw new Error(
+      `LLM provider "${spec.provider}" has no known wire. Declare it: ` +
+      `llm.providers['${spec.provider}'].wire = 'anthropic' | 'openai' | 'google'.`
+    )
+
+  const baseUrl = spec.baseUrl ?? defaultBaseFor( spec.provider )
+  if( !baseUrl )
+    throw new Error(
+      `LLM provider "${spec.provider}" has no known base URL. Declare it: ` +
+      `llm.providers['${spec.provider}'].baseUrl.`
+    )
+
+  return {
+    provider:        spec.provider,
+    wire,
+    model:           spec.model,
+    apiKey:          spec.apiKey,
+    baseUrl,
+    maxOutputTokens: spec.maxOutputTokens,
+  }
+}
 
 export class LLMDirector {
   private _willId: string
@@ -150,6 +379,12 @@ export class LLMDirector {
   private _baseUrl: string | null
   private _timeoutMs: number
   private _tokenTracker: TokenTracker | null
+  private _router: ModelRouter | null
+  private _credentials: Partial<Record<string, ProviderCredential>>
+  /** Default endpoint — what every call used before the routing seam existed. */
+  private _defaultEndpoint: CallEndpoint
+  /** Routes already warned about (missing credential / bad provider) — log once. */
+  private _routeWarned = new Set<string>()
 
   constructor( config: LLMDirectorConfig ) {
     this._willId = config.willId
@@ -162,6 +397,75 @@ export class LLMDirector {
     this._baseUrl = config.baseUrl ?? null
     this._timeoutMs = config.timeoutMs ?? 90_000
     this._tokenTracker = config.tokenTracker ?? null
+    this._router = config.router ?? null
+    this._credentials = config.credentials ?? {}
+    this._defaultEndpoint = resolveEndpoint( {
+      provider:        this._provider,
+      model:           this._model,
+      apiKey:          this._apiKey,
+      baseUrl:         this._baseUrl ?? undefined,
+      wire:            config.wire,
+      maxOutputTokens: this._maxOutputTokens,
+    } )
+  }
+
+  /**
+   * Resolve which model serves this call. Falls back to the default endpoint
+   * whenever the router has no opinion, throws, or names a provider we hold no
+   * credential for — degrade, never crash.
+   */
+  private _resolveEndpoint( meta: LLMCallMeta ): CallEndpoint {
+    if( isNullRouter( this._router ) ) return this._defaultEndpoint
+
+    let route
+    try { route = this._router!.route( meta ) }
+    catch( err ){
+      this._warnRouteOnce(`throw:${this._router!.name}`,
+        `router "${this._router!.name}" threw — using the default model`, err )
+      return this._defaultEndpoint
+    }
+    if( !route ) return this._defaultEndpoint
+
+    // A route with no provider means "same vendor, different model" — the whole
+    // shape of the per-role model map, and the common case for a host swapping
+    // in a cheaper model for background work.
+    const provider = route.provider ?? this._defaultEndpoint.provider
+
+    // The default provider's credential is reused when the route names it;
+    // otherwise the route needs its own entry.
+    const cred = provider === this._defaultEndpoint.provider
+      ? { apiKey: this._defaultEndpoint.apiKey, baseUrl: this._defaultEndpoint.baseUrl, wire: this._defaultEndpoint.wire }
+      : this._credentials[ provider ]
+
+    if( !cred?.apiKey ){
+      this._warnRouteOnce(`cred:${provider}`,
+        `no credential for routed provider "${provider}" — using the default model` )
+      return this._defaultEndpoint
+    }
+
+    try {
+      return resolveEndpoint( {
+        provider,
+        model:           route.model,
+        apiKey:          cred.apiKey,
+        baseUrl:         route.baseUrl ?? cred.baseUrl,
+        wire:            cred.wire,
+        maxOutputTokens: route.maxOutputTokens ?? this._defaultEndpoint.maxOutputTokens,
+      } )
+    }
+    catch( err ){
+      // An undeclared wire or base URL for a routed provider is a config gap,
+      // not a reason to fail the call.
+      this._warnRouteOnce(`resolve:${provider}`,
+        `cannot reach routed provider "${provider}" — using the default model`, err )
+      return this._defaultEndpoint
+    }
+  }
+
+  private _warnRouteOnce( key: string, message: string, err?: unknown ): void {
+    if( this._routeWarned.has( key ) ) return
+    this._routeWarned.add( key )
+    logger.warn(`[llm.routing] ${message}`, err instanceof Error ? err.message : '')
   }
 
   // ── Mock response (test mode) ────────────────────────────
@@ -268,20 +572,27 @@ export class LLMDirector {
       return { text: replay.text, inputTok: replay.inputTok, outputTok: replay.outputTok }
     }
 
+    // MODEL_ROUTING W3 — resolve once, then thread it: several calls can be in
+    // flight on this director at once, so the endpoint must travel with the call
+    // rather than live on `this`. Resolved before the mock branch so a mock run
+    // records the endpoint that WOULD have served the call — the tape then says
+    // the same thing in mock and live runs.
+    const ep = this._resolveEndpoint( meta )
+
     if( this._mock ){
       const result = this._mockResponse( tick, userMessage )
       // In mock mode we don't stream raw internal text — the response will be
       // emitted from the outbox content by the SSE layer.  onChunk is intentionally
       // not called here so no internal [REPLY] / JSON format leaks to the client.
-      this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - start, true )
+      this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - start, true, ep )
       return result
     }
 
-    const result = speaksAnthropicWire( this._provider )
-      ? await this._callAnthropicStream( systemPrompt, userMessage, onChunk, temperature )
+    const result = ep.wire === 'anthropic'
+      ? await this._callAnthropicStream( ep, systemPrompt, userMessage, onChunk, temperature )
       : await ( async () => {
           // Other providers: fall back to regular call, emit whole response as one chunk
-          const r = await this._callProvider( systemPrompt, userMessage, temperature )
+          const r = await this._callProvider( ep, systemPrompt, userMessage, temperature )
           onChunk( r.text )
           return r
         } )()
@@ -289,8 +600,8 @@ export class LLMDirector {
     // Token tracking lives here too: streamed calls (conversation facets, the
     // master when broadcasting) previously bypassed the tracker entirely, so all
     // streamed spend was invisible. Record it with the caller's attribution.
-    this._track( result, meta, tick, Date.now() - start, this._estPromptTokens( systemPrompt, userMessage ) )
-    this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - start, false )
+    this._track( result, meta, tick, Date.now() - start, this._estPromptTokens( systemPrompt, userMessage ), ep )
+    this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - start, false, ep )
     return result
   }
 
@@ -300,9 +611,17 @@ export class LLMDirector {
    * mock/replay directors, so the call is simply skipped. Cache read/write tokens
    * are forwarded so the tracker prices them at 0.1× / 1.25× input.
    */
-  private _track( result: LLMCallResult, meta: LLMCallMeta, tick: Tick, latencyMs: number, estPromptTokens?: number ): void {
+  private _track( result: LLMCallResult, meta: LLMCallMeta, tick: Tick, latencyMs: number, estPromptTokens?: number, ep: CallEndpoint = this._defaultEndpoint ): void {
     this._tokenTracker?.recordUsage({
-      model:            this._model,
+      // The endpoint that actually served this call — routed or default.
+      // Pricing must follow the real model, or routed spend is attributed
+      // wrongly; the provider rides along because the same model id can be
+      // reached from several vendors at very different prices.
+      model:            ep.model,
+      provider:         ep.provider,
+      // The router's own input, kept alongside its output. Without this the
+      // ledger records WHERE a call went and never WHY.
+      demand:           meta.demand,
       promptTokens:     result.inputTok,
       completionTokens: result.outputTok,
       totalTokens:      result.inputTok + result.outputTok,
@@ -310,6 +629,7 @@ export class LLMDirector {
       cacheWriteTokens: result.cacheWriteTok,
       category:         meta.category,
       attribute:        meta.attribute,
+      process:          meta.process,
       function:         meta.function,
       scope:            meta.scope,
       label:            meta.label,
@@ -337,14 +657,17 @@ export class LLMDirector {
     result:       LLMCallResult,
     latencyMs:    number,
     mock:         boolean,
+    ep:           CallEndpoint = this._defaultEndpoint,
   ): void {
     try {
       getCompletionRecorder( this._willId )?.recordCompletion({
         tick,
         willId:          this._willId,
-        provider:        this._provider,
-        model:           this._model,
-        maxOutputTokens: this._maxOutputTokens,
+        // Record the endpoint that actually served the call: the tape is what
+        // replay re-feeds, so it must say which model produced this text.
+        provider:        ep.provider,
+        model:           ep.model,
+        maxOutputTokens: ep.maxOutputTokens,
         systemPrompt,
         userMessage,
         text:            result.text,
@@ -374,6 +697,7 @@ export class LLMDirector {
   }
 
   private async _callAnthropicStream(
+    ep:           CallEndpoint,
     systemPrompt: string,
     userMessage:  string,
     onChunk:      ( chunk: string ) => void,
@@ -387,12 +711,12 @@ export class LLMDirector {
 
     let res: Response
     try {
-      res = await fetch(`${this._resolvedBase()}/messages`, {
+      res = await fetch(`${this._resolvedBase( ep )}/messages`, {
         method: 'POST',
-        headers: anthropicWireHeaders( this._provider, this._apiKey ),
+        headers: anthropicWireHeaders( ep.provider, ep.apiKey ),
         body: JSON.stringify({
-          model:      this._model,
-          max_tokens: this._maxOutputTokens,
+          model:      ep.model,
+          max_tokens: ep.maxOutputTokens,
           ...( temperature !== undefined ? { temperature } : {} ),
           stream:     true,
           system:     this._systemField( systemPrompt ),
@@ -404,7 +728,7 @@ export class LLMDirector {
     catch( err ){
       clearTimeout( timer )
       if( controller.signal.aborted )
-        throw new Error(`LLM stream to ${this._provider} timed out after ${this._timeoutMs}ms (no response)`)
+        throw new Error(`LLM stream to ${ep.provider} timed out after ${this._timeoutMs}ms (no response)`)
       throw err
     }
 
@@ -489,9 +813,11 @@ export class LLMDirector {
     if( replay )
       return { text: replay.text, inputTok: replay.inputTok, outputTok: replay.outputTok }
 
+    const ep = this._resolveEndpoint( meta )
+
     if( this._mock ){
       const result = this._mockResponse( tick, userMessage )
-      this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - llmStart, true )
+      this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - llmStart, true, ep )
       return result
     }
 
@@ -502,44 +828,36 @@ export class LLMDirector {
     // accumulated text; live token chunks go through callStream(). Other
     // providers keep the whole-request deadline.
     const result = await withGate(
-      () => speaksAnthropicWire( this._provider )
-        ? this._callAnthropicStream( systemPrompt, userMessage, () => {}, temperature )
-        : this._callProvider( systemPrompt, userMessage, temperature ),
+      () => ep.wire === 'anthropic'
+        ? this._callAnthropicStream( ep, systemPrompt, userMessage, () => {}, temperature )
+        : this._callProvider( ep, systemPrompt, userMessage, temperature ),
       'executive/direct',
     )
 
     // Record token usage + cost into this Will's injected tracker (R4), tagged
     // with the caller's attribution. Optional — absent on mock/replay directors.
-    this._track( result, meta, tick, Date.now() - llmStart, this._estPromptTokens( systemPrompt, userMessage ) )
+    this._track( result, meta, tick, Date.now() - llmStart, this._estPromptTokens( systemPrompt, userMessage ), ep )
 
-    this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - llmStart, false )
+    this._recordCompletion( systemPrompt, userMessage, tick, result, Date.now() - llmStart, false, ep )
     return result
   }
 
   private _callProvider(
+    ep: CallEndpoint,
     systemPrompt: string,
     userMessage: string,
     temperature?: number,
   ): Promise<LLMCallResult> {
-    switch( this._provider ){
-      case 'anthropic': return this._callAnthropic( systemPrompt, userMessage, temperature )
-      case 'glm': return this._callAnthropic( systemPrompt, userMessage, temperature )
-      case 'deepseek': return this._callOpenAI( systemPrompt, userMessage, temperature )
-      case 'openai': return this._callOpenAI( systemPrompt, userMessage, temperature )
-      case 'google': return this._callGoogle( systemPrompt, userMessage, temperature )
-      default: throw new Error(`Unknown LLM provider: ${this._provider}`)
+    switch( ep.wire ){
+      case 'anthropic': return this._callAnthropic( ep, systemPrompt, userMessage, temperature )
+      case 'openai':    return this._callOpenAI( ep, systemPrompt, userMessage, temperature )
+      case 'google':    return this._callGoogle( ep, systemPrompt, userMessage, temperature )
+      default: throw new Error(`Unknown LLM wire: ${ep.wire}`)
     }
   }
 
-  /** Default API base URL (including version segment) for a provider. */
-  private _baseFor( provider: LLMProvider ): string {
-    return defaultBaseFor( provider )
-  }
-
   /** Resolved API base: explicit override wins, else the provider default. */
-  private _resolvedBase(): string {
-    return this._baseUrl ?? this._baseFor( this._provider )
-  }
+  private _resolvedBase( ep: CallEndpoint ): string { return ep.baseUrl }
 
   /**
    * fetch() with a hard per-request deadline. A hung connection is aborted
@@ -569,23 +887,23 @@ export class LLMDirector {
     return [ { type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } } ]
   }
 
-  private async _callAnthropic( systemPrompt: string, userMessage: string, temperature?: number ): Promise<LLMCallResult> {
+  private async _callAnthropic( ep: CallEndpoint, systemPrompt: string, userMessage: string, temperature?: number ): Promise<LLMCallResult> {
     const body = {
-      model: this._model,
-      max_tokens: this._maxOutputTokens,
+      model: ep.model,
+      max_tokens: ep.maxOutputTokens,
       ...( temperature !== undefined ? { temperature } : {} ),
       system: this._systemField( systemPrompt ),
       messages: [{ role: 'user', content: userMessage }]
     }
 
-    const res = await this._fetchWithTimeout(`${this._resolvedBase()}/messages`, {
+    const res = await this._fetchWithTimeout(`${this._resolvedBase( ep )}/messages`, {
       method: 'POST',
-      headers: anthropicWireHeaders( this._provider, this._apiKey ),
+      headers: anthropicWireHeaders( ep.provider, ep.apiKey ),
       body: JSON.stringify( body )
     })
 
     if( !res.ok )
-      throw new Error(`${this._provider} API ${res.status}: ${( await res.text() ).slice(0, 300)}`)
+      throw new Error(`${ep.provider} API ${res.status}: ${( await res.text() ).slice(0, 300)}`)
 
     const
     data = await res.json() as {
@@ -603,10 +921,10 @@ export class LLMDirector {
     }
   }
 
-  private async _callOpenAI( systemPrompt: string, userMessage: string, temperature?: number ): Promise<LLMCallResult> {
+  private async _callOpenAI( ep: CallEndpoint, systemPrompt: string, userMessage: string, temperature?: number ): Promise<LLMCallResult> {
     const body = {
-      model: this._model,
-      max_completion_tokens: this._maxOutputTokens,
+      model: ep.model,
+      max_completion_tokens: ep.maxOutputTokens,
       ...( temperature !== undefined ? { temperature } : {} ),
       messages: [
         { role: 'system', content: systemPrompt },
@@ -614,11 +932,11 @@ export class LLMDirector {
       ]
     }
 
-    const res = await this._fetchWithTimeout(`${this._resolvedBase()}/chat/completions`, {
+    const res = await this._fetchWithTimeout(`${this._resolvedBase( ep )}/chat/completions`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this._apiKey}`,
+        'Authorization': `Bearer ${ep.apiKey}`,
       },
       body: JSON.stringify(body),
     })
@@ -640,25 +958,25 @@ export class LLMDirector {
     }
   }
 
-  private async _callGoogle( systemPrompt: string, userMessage: string, temperature?: number ): Promise<LLMCallResult> {
+  private async _callGoogle( ep: CallEndpoint, systemPrompt: string, userMessage: string, temperature?: number ): Promise<LLMCallResult> {
     // Gemini carries the system prompt in a dedicated `systemInstruction`
     // field and the conversation in `contents`.
     const body = {
       systemInstruction: { parts: [ { text: systemPrompt } ] },
       contents:          [ { role: 'user', parts: [ { text: userMessage } ] } ],
       generationConfig:  {
-        maxOutputTokens: this._maxOutputTokens,
+        maxOutputTokens: ep.maxOutputTokens,
         ...( temperature !== undefined ? { temperature } : {} ),
       },
     }
 
     const res = await this._fetchWithTimeout(
-      `${this._resolvedBase()}/models/${this._model}:generateContent`,
+      `${this._resolvedBase( ep )}/models/${ep.model}:generateContent`,
       {
         method: 'POST',
         headers: {
           'Content-Type':   'application/json',
-          'x-goog-api-key': this._apiKey,
+          'x-goog-api-key': ep.apiKey,
         },
         body: JSON.stringify( body ),
       }