@mindot/will 0.7.0 → 0.8.0

package/src/llm/routing.ts

@@ -0,0 +1,198 @@
+// ─────────────────────────────────────────────────────────────
+// src/llm/routing.ts
+// ─────────────────────────────────────────────────────────────
+//
+// MODEL_ROUTING W2 — per-call model selection.
+//
+// A Will runs one LLMDirector, and every call site shares it: the master's
+// decision, each facet, the propose pass, the rolling summariser, the identity
+// guard. They are not the same cognitive act, and they need not be the same
+// inference. This module lets a host decide which model serves which call,
+// without the engine learning anything it should not know.
+//
+// WHAT THIS IS NOT. This is a mechanism, never a policy. The engine may know
+// that a call is routine or consequential — that is a cognitive fact it already
+// computes (`LLMCallMeta.demand`). It must never know who is paying, what plan
+// they are on, or what anything costs us. A router that needs commercial
+// information is the host's to write; the seam below carries none of it.
+//
+// DETERMINISM CONTRACT. A router is an external oracle, exactly like the LLM
+// itself and the policy arbiter. Its choice is already captured: the completion
+// tape records `provider` and `model` on every call, and replay re-feeds the
+// recorded completion rather than re-deciding. So replay never consults a
+// router, and a run replays byte-for-byte whether the router is absent,
+// present, or since reconfigured.
+//
+// SCOPE. A router may read the call meta and its own configuration, and nothing
+// else. It must not reach into simulation state — that is what keeps this
+// module below cognition (src/llm imports no cognition behaviour) and keeps
+// routing from becoming a hidden input to the mind.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type { LLMProvider, LLMCallMeta } from '#llm/index'
+
+/**
+ * Where a single call should go. Every field except `model` falls back to the
+ * Will's default when omitted.
+ */
+export interface ModelRoute {
+  /**
+   * Omit to keep the Will's default provider and change only the model — the
+   * common "same vendor, different model for this kind of work" route, and what
+   * the per-role model map compiles to (a role has never had a provider of its
+   * own). Name a provider to cross vendors; it must appear in `llm.providers`
+   * or the route falls back to the default.
+   */
+  provider?: LLMProvider
+  model: string
+  /** Override the provider's API base (self-hosted / OpenAI-compatible servers). */
+  baseUrl?: string
+  /** Override the output-token ceiling for this call. */
+  maxOutputTokens?: number
+}
+
+/**
+ * Chooses a model for a call.
+ *
+ * Returning `null` means "no opinion" — the Will's default model is used. A
+ * router should return `null` rather than guess when it does not recognise a
+ * call: falling back is always safe, and a wrong route is not.
+ */
+export interface ModelRouter {
+  /** Stable identifier, recorded alongside routing telemetry. */
+  readonly name: string
+  route( meta: LLMCallMeta ): ModelRoute | null
+}
+
+/**
+ * The default. Has no opinion about anything, allocates nothing.
+ *
+ * A Will running this must be byte-identical to one built before the routing
+ * seam existed — that property is asserted by test, and it is what lets this
+ * ship dark.
+ */
+export const NULL_ROUTER: ModelRouter = {
+  name: 'null',
+  route(): ModelRoute | null { return null },
+}
+
+/** True when the router is the no-op default (used to skip the seam entirely). */
+export function isNullRouter( router: ModelRouter | null | undefined ): boolean {
+  return !router || router === NULL_ROUTER
+}
+
+// ── Reference implementation ──────────────────────────────────
+
+/**
+ * One entry in a {@link TableRouter}'s table. All present conditions must match
+ * (logical AND); an absent condition matches anything.
+ */
+export interface RoutingRule {
+  /**
+   * Match `LLMCallMeta.category` exactly (e.g. 'executive', 'summarizer').
+   *
+   * The axes are typed rather than free strings so a rule that names a bucket
+   * the engine never emits fails to compile instead of silently never matching
+   * — a routing table's worst failure is the rule that looks right and is dead.
+   */
+  category?: LLMCallMeta['category']
+  /** Match `LLMCallMeta.attribute` exactly (e.g. 'master', 'facet', 'guard'). */
+  attribute?: LLMCallMeta['attribute']
+  /** Match `LLMCallMeta.function` exactly (e.g. 'decision', 'consolidation'). */
+  function?: LLMCallMeta['function']
+  /**
+   * Inclusive lower bound on `LLMCallMeta.demand`. A call with no demand
+   * reported never matches a rule that sets this — absent means unknown, and
+   * unknown must not be treated as zero.
+   */
+  minDemand?: number
+  /** Exclusive upper bound on `LLMCallMeta.demand`. Same absence rule. */
+  maxDemand?: number
+  /** Where a matching call goes. */
+  route: ModelRoute
+}
+
+/**
+ * A worked example of the seam: first matching rule wins, otherwise no opinion.
+ *
+ * This ships so that the interface has a reference implementation and so that
+ * hosts have something to copy — it is deliberately dumb. It is not a routing
+ * strategy, and the engine ships no table of its own: what belongs where is the
+ * host's decision, expressed as configuration.
+ *
+ * Rules are evaluated in order, so put specific rules before general ones.
+ */
+export class TableRouter implements ModelRouter {
+  readonly name: string
+  private readonly _rules: readonly RoutingRule[]
+
+  constructor( rules: readonly RoutingRule[], name = 'table' ){
+    this._rules = [ ...rules ]
+    this.name   = name
+  }
+
+  route( meta: LLMCallMeta ): ModelRoute | null {
+    for( const rule of this._rules ){
+      if( matches( rule, meta ) ) return rule.route
+    }
+    return null
+  }
+}
+
+/**
+ * Ask each router in turn; the first with an opinion wins.
+ *
+ * This exists because a Will can have two sources of routing at once: the
+ * host's own router, and the one compiled from its per-role model map. Order
+ * expresses precedence — an explicit router is consulted before the role map,
+ * which is the precedence those two mechanisms already had when roles were
+ * served by separate directors.
+ *
+ * A throwing link is skipped, not propagated. The links are independent
+ * decisions, and one broken router must not take a working one down with it —
+ * that would silently demote every role-mapped call to the default model.
+ */
+export function chainRouters( ...routers: ( ModelRouter | null | undefined )[] ): ModelRouter {
+  const chain = routers.filter( ( r ): r is ModelRouter => !isNullRouter( r ) )
+  if( chain.length === 0 ) return NULL_ROUTER
+  if( chain.length === 1 ) return chain[ 0 ]!
+
+  const warned = new Set<string>()
+  return {
+    name: chain.map( r => r.name ).join('>'),
+    route( meta: LLMCallMeta ): ModelRoute | null {
+      for( const router of chain ){
+        try {
+          const hit = router.route( meta )
+          if( hit ) return hit
+        }
+        catch( err ){
+          if( !warned.has( router.name ) ){
+            warned.add( router.name )
+            logger.warn(`[llm.routing] router "${router.name}" threw — skipping it: ${( err as Error ).message}`)
+          }
+        }
+      }
+      return null
+    },
+  }
+}
+
+function matches( rule: RoutingRule, meta: LLMCallMeta ): boolean {
+  if( rule.category  !== undefined && rule.category  !== meta.category  ) return false
+  if( rule.attribute !== undefined && rule.attribute !== meta.attribute ) return false
+  if( rule.function  !== undefined && rule.function  !== meta.function  ) return false
+
+  // Absent demand is UNKNOWN, not zero: a demand-bounded rule cannot claim a
+  // call whose demand was never measured.
+  const bounded = rule.minDemand !== undefined || rule.maxDemand !== undefined
+  if( bounded ){
+    const d = meta.demand
+    if( typeof d !== 'number' || Number.isNaN( d ) ) return false
+    if( rule.minDemand !== undefined && d <  rule.minDemand ) return false
+    if( rule.maxDemand !== undefined && d >= rule.maxDemand ) return false
+  }
+
+  return true
+}

package/src/llm/summarizer.ts

@@ -17,6 +17,7 @@
 
 import { logger } from '#core/logger'
 import type { LLMDirector } from '#llm/index'
+import { BACKGROUND_DEMAND } from '#llm/index'
 
 export interface SummarizerConfig {
   /** How many executive calls between summarization runs. Default: 10 */
@@ -148,7 +149,10 @@ export class ExecutiveSummarizer {
         userMessage,
         this._callCount as any,
         undefined,
-        { category: 'summarizer', attribute: 'memory', function: 'consolidation' }
+        // MODEL_ROUTING W0 — compression is background work at a constant low
+        // demand: distilling excerpts is the same job whether the mind is calm
+        // or in crisis, so there is no honest per-tick measure to forward here.
+        { category: 'summarizer', attribute: 'memory', function: 'consolidation', demand: BACKGROUND_DEMAND }
       )
 
       if( result.text ){

package/src/runners/thin-shim.runner.ts

@@ -16,6 +16,14 @@
 
 import type { WillConfig } from '#stem/mind'
 import type { StateSnapshot } from '#stem/index'
+import type { TokenTracker } from '#cognition/utilities/token.tracker'
+
+/**
+ * The Will's token tracker, for cost display. Held here rather than passed in
+ * because printStatus is registered as a TickListener, whose third parameter is
+ * the outbox. Cost is no longer a state metric (W8c) — it lives on the tracker.
+ */
+let _tracker: TokenTracker | undefined
 import { WillStem } from '#stem/index'
 
 // ── Env config ────────────────────────────────────────────────
@@ -88,14 +96,15 @@ function printStatus( snapshot: StateSnapshot, tick: number ): void {
     `  entities=${entities}`
   )
 
-  // LLM stats every LOG_INTERVAL
-  const costTotal    = ( snapshot.metrics.get('llm.cost_total_usd') ?? 0 ).toFixed( 4 )
-  const costThisTick = ( snapshot.metrics.get('llm.cost_this_tick_usd') ?? 0 ).toFixed( 5 )
-  const totalCalls   = snapshot.metrics.get('llm.total_calls') ?? 0
+  // LLM stats every LOG_INTERVAL. Tokens come from state; cost comes from the
+  // tracker — dollars are host accounting and no longer live in state (W8c).
+  const totalCalls = snapshot.metrics.get('llm.total_calls') ?? 0
+  const cost = _tracker
+    ? `  total_cost=$${_tracker.totalCostUsd.toFixed( 4 )}`
+    : ''
 
   console.log(
-    `  [llm] total_cost=$${costTotal}` +
-    `  tick_cost=$${costThisTick}` +
+    `  [llm]${cost}` +
     `  calls=${totalCalls}` +
     `  prompt=${snapshot.metrics.get('llm.prompt_tokens_total') ?? 0}` +
     `  completion=${snapshot.metrics.get('llm.completion_tokens_total') ?? 0}`
@@ -141,6 +150,9 @@ async function main(): Promise<void> {
   console.log('[init] Assembling mind...')
   await manager.createWill( willConfig )
 
+  // Cost is no longer a state metric (W8c) — read it off the Will's tracker.
+  _tracker = manager.getWillCognition( WILL_ID ).tokenTracker
+
   manager.addTickListener( WILL_ID, printStatus )
 
   // Graceful shutdown

package/src/sdk/will.ts

@@ -29,6 +29,7 @@
 
 import { WillStem } from '#stem/index'
 import type { WillConfig, WillIdentity, Anatomy, InitialGoal, WillModelConfig, WillLLMConfig } from '#stem/mind'
+import { PROVIDER_KEY_ENV, providerKeyFromEnv, type LLMProvider } from '#llm/index'
 import type { PMASnapshot } from '#pma/index'
 import type { effectorInvocation } from '#types'
 import type { EffectorDeclaration, SchemaPrecondition } from '#agency/types'
@@ -165,20 +166,42 @@ export interface CreateWillOptions {
   anatomy?: Anatomy
   /** Concrete LLM model id, or a per-role map ({ executive, summarizer?,
    *  deliberation?, embedding? } — unset thinking roles fall back to executive).
-   *  Unset → env / provider default. */
+   *  Unset → env / provider default.
+   *  @deprecated Pass `llmConfig: { model }` instead — model and transport are
+   *  one concern. Still honoured; an explicit `llmConfig.model` wins. */
   model?: string | WillModelConfig
-  /** Per-Will LLM transport overrides (provider, BYO apiKey, baseUrl, caps).
+  /** Per-Will LLM config: provider, model(s), BYO apiKey, baseUrl, caps.
    *  Unset fields fall back to WILL_LLM_* envs. apiKey stays in memory only.
-   *  (Named llmConfig because `llm` is the mock/anthropic MODE switch.) */
+   *  (Named llmConfig because `llm` is the provider MODE switch.) */
   llmConfig?: WillLLMConfig
    /**
-   * LLM mode. 'mock' (default when no key is present) runs a deterministic
-   * canned executive — zero keys, zero cost. 'anthropic' calls Claude (needs
-   * ANTHROPIC_API_KEY / WILL_LLM_* env); 'glm' calls Z.ai's GLM over its
-   * Anthropic-compatible endpoint (needs ZAI_API_KEY / WILL_LLM_*). Omit to
-   * auto-detect from whichever key is set.
+   * LLM mode — which provider the executive speaks to.
+   *
+   * 'mock' (the default when no key is present) runs a deterministic canned
+   * executive: zero keys, zero cost. Every other value names a provider and
+   * needs its key, either the provider's own env below or the
+   * provider-agnostic WILL_LLM_API_KEY:
+   *
+   *   anthropic  ANTHROPIC_API_KEY   Claude, native Messages wire
+   *   glm        ZAI_API_KEY         Z.ai GLM, Anthropic-compatible wire
+   *   openai     OPENAI_API_KEY      OpenAI wire
+   *   google     GOOGLE_API_KEY | GEMINI_API_KEY   native Gemini wire
+   *   deepseek   DEEPSEEK_API_KEY    OpenAI wire
+   *   moonshot   MOONSHOT_API_KEY    Kimi — OpenAI wire
+   *   qwen       DASHSCOPE_API_KEY   Alibaba Model Studio — OpenAI wire
+   *   xai        XAI_API_KEY         Grok — OpenAI wire
+   *   minimax    MINIMAX_API_KEY     OpenAI wire
+   *   mistral    MISTRAL_API_KEY     OpenAI wire
+   *   ollama · vllm                  local; no key, set `llm` explicitly
+   *
+   * Any other string works too — it just has to declare its `wire` and
+   * `baseUrl` on `llmConfig.providers`. Naming the vendor rather than
+   * borrowing `openai` because it speaks that wire is what keeps the
+   * completion tape and the cost breakdown honest.
+   *
+   * Omit to auto-detect from whichever key is set.
    */
-  llm?: 'mock' | 'anthropic' | 'glm'
+  llm?: 'mock' | LLMProvider
   /**
    * Abilities the Will can choose to enact. `name → handler`, or
    * `name → { handler, description?, cost?, valence?, preconditions? }` to seed
@@ -213,6 +236,41 @@ const AFFECT_EPSILON = 0.02
 
 // ── The facade ────────────────────────────────────────────────
 
+
+/**
+ * Which provider to talk to when the caller did not say.
+ *
+ * Checks the provider-agnostic key first (it means "I configured this
+ * deliberately"), then each provider's conventional env. The order among
+ * providers is detection precedence when several keys happen to be present —
+ * it is not a ranking, and no provider here is more supported than another.
+ */
+export function detectProvider(): 'mock' | LLMProvider {
+  // A provider-agnostic key says nothing about who to send it to. Guessing
+  // here is how a key meant for one vendor ends up at another; the guess used
+  // to be 'anthropic' unconditionally.
+  if( process.env.WILL_LLM_API_KEY ){
+    const provider = process.env.WILL_LLM_PROVIDER
+    if( !provider )
+      throw new Error(
+        'WILL_LLM_API_KEY is set but WILL_LLM_PROVIDER is not — there is no way ' +
+        'to tell which provider that key belongs to. Set WILL_LLM_PROVIDER, or ' +
+        'use a provider-specific key (ANTHROPIC_API_KEY, ZAI_API_KEY, …).'
+      )
+    return provider as LLMProvider
+  }
+  // A provider-specific key IS the explicit statement — no guess involved.
+  // Order is precedence when several are present, and is append-only: moving an
+  // entry silently changes which vendor an existing environment talks to.
+  //
+  // Read through providerKeyFromEnv rather than raw truthiness, so "is a key
+  // set?" and "what is the key?" cannot disagree — a blank `XAI_API_KEY=` would
+  // otherwise select xai here and then supply nothing to call it with.
+  for( const provider of Object.keys( PROVIDER_KEY_ENV ) )
+    if( providerKeyFromEnv( provider ) ) return provider
+  return 'mock'
+}
+
 export class Will {
   /** The underlying WillStem — drop here for the full contract. */
   readonly stem: WillStem
@@ -462,13 +520,22 @@ export class Will {
 
   private _buildConfig( id: string, opts: CreateWillOptions ): WillConfig {
     // Auto-detect from whichever provider key is present; explicit `llm` wins.
-    const mode = opts.llm
-      ?? ( process.env.ANTHROPIC_API_KEY ? 'anthropic' : process.env.ZAI_API_KEY ? 'glm' : 'mock')
+    // Order is detection precedence when several keys are set, not a
+    // recommendation — every provider here is a first-class target.
+    const mode = opts.llm ?? detectProvider()
     const useMock = mode === 'mock'
-    // `llm: 'glm'` selects the provider; an explicit llmConfig still overrides it.
-    const llmConfig = mode === 'glm'
-      ? { provider: 'glm' as const, ...opts.llmConfig }
-      : opts.llmConfig
+    // `llm` selects the provider; an explicit llmConfig.provider still wins.
+    // Model rides with the transport: `llmConfig.model` is canonical, the
+    // top-level `opts.model` is the deprecated spelling of the same thing.
+    const llmConfig: WillLLMConfig | undefined = useMock && !opts.llmConfig && opts.model === undefined
+      ? undefined
+      : {
+          ...( mode !== 'mock' ? { provider: mode } : {} ),
+          ...opts.llmConfig,
+          ...( opts.llmConfig?.model !== undefined ? { model: opts.llmConfig.model }
+             : opts.model        !== undefined ? { model: opts.model }
+             : {} ),
+        }
     return {
       id, name: opts.name,
       identity: {
@@ -478,7 +545,6 @@ export class Will {
         style:  opts.identity.style ?? '',
       },
       anatomy: opts.anatomy ?? 'mind',
-      model:   opts.model,
       llm:     llmConfig,
       testMode:   useMock,
       persistentMemory: opts.persist ?? false,

package/src/stem/guards/identity.coherence.ts

@@ -18,7 +18,7 @@
 // ─────────────────────────────────────────────────────────────
 
 import type { WillIdentity } from '#stem/mind'
-import { LLMDirector, defaultModelFor, type LLMProvider, type LLMCallMeta } from '#llm/index'
+import { LLMDirector, BACKGROUND_DEMAND, type LLMProvider, type LLMCallMeta } from '#llm/index'
 import type { TokenTracker } from '#cognition/utilities/token.tracker'
 
 export interface CoherenceIssue {
@@ -48,7 +48,10 @@ export interface IdentityReviewer {
 }
 
 /** Attribution tag for the one creation-time coherence-review call. */
-const COHERENCE_META: LLMCallMeta = { category: 'identity-guard', attribute: 'guard', function: 'identity-coherence' }
+// MODEL_ROUTING W0 — a one-shot classification at creation time; constant low
+// demand (structurally background, and it runs before there is a mind whose
+// state could modulate it).
+const COHERENCE_META: LLMCallMeta = { category: 'identity-guard', attribute: 'guard', function: 'identity-coherence', demand: BACKGROUND_DEMAND }
 
 const VALID_KINDS = new Set<CoherenceIssue['kind']>( [ 'contradiction', 'false-capability', 'injection', 'incoherence', 'other' ] )
 
@@ -112,13 +115,21 @@ export async function reviewIdentityCoherence(
   input: CoherenceInput,
   opts:  { willId?: string; tokenTracker?: TokenTracker | null } = {},
 ): Promise<CoherenceResult> {
-  const provider = ( process.env.WILL_LLM_PROVIDER ?? 'anthropic') as LLMProvider
+  // No defaults: an unconfigured environment cannot review a persona, and
+  // silently reviewing it with somebody else's model is worse than not running.
+  const provider = process.env.WILL_LLM_PROVIDER
+  const model    = process.env.WILL_LLM_MODEL
+  if( !provider || !model )
+    return { ok: true, ran: false, issues: [], raw: 'review skipped: WILL_LLM_PROVIDER / WILL_LLM_MODEL not set' }
+
   const director = new LLMDirector({
     willId:          opts.willId ?? 'identity-coherence',
-    model:           process.env.WILL_LLM_MODEL ?? defaultModelFor( provider ),
+    model,
     maxOutputTokens: 512,
-    apiKey:          process.env.WILL_LLM_API_KEY ?? process.env.ANTHROPIC_API_KEY ?? '',
-    provider,
+    // Provider-agnostic key only — the old chain ended at ANTHROPIC_API_KEY,
+    // so a Will pointed at another vendor would have sent it an Anthropic key.
+    apiKey:          process.env.WILL_LLM_API_KEY ?? '',
+    provider: provider as LLMProvider,
     sessionLogger:   null,
     baseUrl:         process.env.WILL_LLM_BASE_URL ?? process.env.OPENAI_BASE_URL,
     // When a per-Will tracker is supplied, the creation-time review records under

package/src/stem/index.ts

@@ -95,7 +95,7 @@ export interface WillSummary {
   createdAt:  Date
   lastTickAt: Date | null
   anatomy:    WillConfig['anatomy']
-  model:      WillConfig['model']
+  model:      NonNullable<WillConfig['llm']>['model']
 }
 
 // Re-export WillConfig so the API layer only imports from manager
@@ -289,7 +289,7 @@ export class WillStem {
       willId:     config.id,
       willName:   config.name,
       anatomy:    config.anatomy ?? 'mind',
-      model:      config.model ?? null,
+      model:      config.llm?.model ?? null,
       startedAt:  new Date().toISOString(),
     })
 
@@ -942,7 +942,7 @@ export class WillStem {
       createdAt:  inst.createdAt,
       lastTickAt: inst.lastTickAt,
       anatomy:    inst.config.anatomy ?? 'mind',
-      model:      inst.config.model,
+      model:      inst.config.llm?.model,
     }))
   }