@mindot/will 0.6.0 → 0.8.0

package/src/cognition/faculties/executive.engine/engine.ts

@@ -60,7 +60,10 @@ import {
   type GatingState
 } from '#faculties/executive.engine/gating'
 import { LLMDirector } from '#llm/index'
-import { defaultModelFor, type LLMProvider } from '#llm/index'
+import { MOCK_PROVIDER, MOCK_MODEL } from '#llm/index'
+import { getCompletionSource } from '#core/completion.recorder'
+import { providerKeyFromEnv, type LLMProvider, type LLMCallMeta, type ProviderCredential, type LLMWire } from '#llm/index'
+import type { ModelRouter } from '#llm/routing'
 import { buildFallbackOutput, parseResponse } from '#faculties/executive.engine/parser'
 import { selectProcess, ideationTemperature, DELIBERATE_THRESHOLD } from '#faculties/executive.engine/effort.gate'
 import { proposeCandidates } from '#faculties/executive.engine/deliberate.reasoning'
@@ -145,14 +148,14 @@ export class ExecutiveEngine extends AsyncEngine implements CognitiveEngine {
 
   // ── Injected dependencies ──────────────────────────────────
   private _willId: string | null = null
-  /** Per-Will, per-role model ids (config.model, resolved in mind.ts). */
-  private _models: { executive: string | null; summarizer: string | null; deliberation: string | null; conversation: string | null } =
-    { executive: null, summarizer: null, deliberation: null, conversation: null }
+  /**
+   * The Will's default model (config.model's `executive` role, resolved in
+   * mind.ts). Every other role reaches its model through the router — see
+   * `compileRoleRouter`.
+   */
+  private _modelId: string | null = null
   /** Per-Will LLM transport overrides (config.llm) — env fallbacks apply per field. */
-  private _llm: { provider?: string; apiKey?: string; baseUrl?: string; maxOutputTokens?: number; timeoutMs?: number } | null = null
-  /** One director per distinct model — same config, different model. Shared
-   *  tracker/recorder/willId, so ledger attribution and replay hold per role. */
-  private _directorCache = new Map<string, LLMDirector>()
+  private _llm: { provider?: string; apiKey?: string; baseUrl?: string; maxOutputTokens?: number; timeoutMs?: number; credentials?: Partial<Record<string, ProviderCredential>>; router?: ModelRouter | null; wire?: LLMWire } | null = null
   private _workingMemory: WorkingMemory | null = null
   private _goalManager: GoalManager | null = null
   private _episodicConsolidator: EpisodicConsolidator | null = null
@@ -267,13 +270,18 @@ export class ExecutiveEngine extends AsyncEngine implements CognitiveEngine {
 
   set willId( willId: string ){ this._willId = willId }
 
-  /** Per-Will role models (config.model, resolved). Set before the first tick. */
-  set models( m: { executive: string | null; summarizer: string | null; deliberation: string | null; conversation: string | null } ){ this._models = m }
-  get models(): { executive: string | null; summarizer: string | null; deliberation: string | null; conversation: string | null } { return this._models }
+  /**
+   * The Will's default model. Set before the first tick.
+   *
+   * This replaced a four-role map (W7): the other roles are routing rules now,
+   * compiled in mind.ts, so the engine holds one model and one router rather
+   * than a model per role plus a router.
+   */
+  set modelId( id: string | null ){ this._modelId = id }
+  get modelId(): string | null { return this._modelId }
+
   /** Per-Will LLM transport overrides (config.llm). Set before the first tick. */
-  set llm( c: { provider?: string; apiKey?: string; baseUrl?: string; maxOutputTokens?: number; timeoutMs?: number } | null ){ this._llm = c }
-  /** The executive-role model id (back-compat read). */
-  get modelId(): string | null { return this._models.executive }
+  set llm( c: { provider?: string; apiKey?: string; baseUrl?: string; maxOutputTokens?: number; timeoutMs?: number; credentials?: Partial<Record<string, ProviderCredential>>; router?: ModelRouter | null; wire?: LLMWire } | null ){ this._llm = c }
 
   // ── Public surface ─────────────────────────────────────────
 
@@ -301,48 +309,98 @@ export class ExecutiveEngine extends AsyncEngine implements CognitiveEngine {
    * and subscribe() to receive facet decisions.
    */
   /** Get-or-create the director for a model id (shared config, per-Will). */
-  private _directorFor( model: string ): LLMDirector {
-    let d = this._directorCache.get( model )
-    if( !d ){
-      // Per-Will transport overrides first (BYO keys), env per field otherwise.
-      d = new LLMDirector( {
-        willId: this._willId!,
-        model,
-        maxOutputTokens: this._llm?.maxOutputTokens ?? parseInt( process.env.WILL_MAX_OUTPUT_TOKENS ?? '8096'),
-        // Provider-agnostic key; falls back to ANTHROPIC_API_KEY for back-compat.
-        apiKey: this._llm?.apiKey ?? process.env.WILL_LLM_API_KEY ?? process.env.ANTHROPIC_API_KEY ?? '',
-        provider: ( this._llm?.provider ?? process.env.WILL_LLM_PROVIDER ?? 'anthropic') as LLMProvider,
-        // Optional base-URL override (e.g. Ollama / Azure / self-hosted). Unset →
-        // the director uses the provider's official endpoint.
-        baseUrl: this._llm?.baseUrl ?? process.env.WILL_LLM_BASE_URL ?? process.env.OPENAI_BASE_URL,
-        timeoutMs: this._llm?.timeoutMs ?? ( process.env.WILL_LLM_TIMEOUT_MS ? parseInt( process.env.WILL_LLM_TIMEOUT_MS ) : undefined ),
-        sessionLogger: this._sessionLogger,
-        mock: this._testMode,
-        // Inject the per-Will tracker (R4) so live calls record usage here, not
-        // through a process global. null is fine — the director skips recording.
-        tokenTracker: this._tokenTracker,
-      } )
-      this._directorCache.set( model, d )
-    }
-    return d
+  /**
+   * The provider, from config or environment — never guessed.
+   *
+   * This used to default to 'anthropic', which is how a Will configured for one
+   * vendor could quietly talk to another. An unset provider is a configuration
+   * error, and saying so at construction is far cheaper than a 401 mid-tick.
+   */
+  private _requireProvider(): LLMProvider {
+    const provider = this._llm?.provider ?? process.env.WILL_LLM_PROVIDER
+      ?? ( this._noLiveCalls() ? MOCK_PROVIDER : undefined )
+    if( !provider )
+      throw new Error(
+        'No LLM provider configured. Set one on the Will (llm.provider) or in ' +
+        'the environment (WILL_LLM_PROVIDER) — the engine carries no default.'
+      )
+    return provider as LLMProvider
+  }
+
+  /**
+   * True when this Will cannot make a live call, so provider/model are not
+   * required: mock mode, or a replay re-feeding recorded completions.
+   */
+  private _noLiveCalls(): boolean {
+    return this._testMode || ( !!this._willId && !!getCompletionSource( this._willId ) )
   }
 
+  /**
+   * Build this Will's one and only director.
+   *
+   * There used to be a cache of them, keyed by model, because the per-role
+   * model map had no other way to make a role use a different model. Routing
+   * gave it one — the role map now compiles to rules (see `compileRoleRouter`)
+   * and a single director resolves every call's endpoint per call. That is also
+   * strictly more faithful: a facet follows the work it is doing rather than
+   * whatever role it happened to be spawned under.
+   */
+  private _buildDirector( model: string ): LLMDirector {
+    // Resolved first: the key fallback below is keyed by it.
+    const provider = this._requireProvider()
+
+    // Per-Will transport overrides first (BYO keys), env per field otherwise.
+    return new LLMDirector( {
+      willId: this._willId!,
+      model,
+      maxOutputTokens: this._llm?.maxOutputTokens ?? parseInt( process.env.WILL_MAX_OUTPUT_TOKENS ?? '8096'),
+      // Config, then the provider-agnostic env, then THIS provider's own env.
+      // The last step is not the fallback W9 removed: that one ended at
+      // ANTHROPIC_API_KEY for every provider, so a Will pointed elsewhere sent
+      // Anthropic's key to a stranger. This one can only ever read the key
+      // belonging to the provider actually configured.
+      apiKey: this._llm?.apiKey ?? process.env.WILL_LLM_API_KEY ?? providerKeyFromEnv( provider ) ?? '',
+      provider,
+      // Optional base-URL override (e.g. Ollama / Azure / self-hosted). Unset →
+      // the director uses the provider's official endpoint.
+      baseUrl: this._llm?.baseUrl ?? process.env.WILL_LLM_BASE_URL ?? process.env.OPENAI_BASE_URL,
+      timeoutMs: this._llm?.timeoutMs ?? ( process.env.WILL_LLM_TIMEOUT_MS ? parseInt( process.env.WILL_LLM_TIMEOUT_MS ) : undefined ),
+      sessionLogger: this._sessionLogger,
+      mock: this._testMode,
+      // Inject the per-Will tracker (R4) so live calls record usage here, not
+      // through a process global. null is fine — the director skips recording.
+      tokenTracker: this._tokenTracker,
+      // Credentials for routed calls, narrowed by the stem from the host's
+      // per-provider map. Prices from that same map ride to the TokenTracker
+      // instead, so nothing carries pricing into the call path.
+      ...( this._llm?.credentials ? { credentials: this._llm.credentials } : {} ),
+      // Per-call model selection — the host's router chained with the rules
+      // compiled from the per-role model map.
+      ...( this._llm?.router ? { router: this._llm.router } : {} ),
+      // Dialect for the default provider — required for anything outside the
+      // known set, so the engine never guesses how to talk to an endpoint.
+      ...( this._llm?.wire ? { wire: this._llm.wire } : {} ),
+    } )
+  }
+
+  /**
+   * Spawn a facet.
+   *
+   * `role` declares the facet's intent at the call site. It no longer selects a
+   * model: that used to happen here, pinning a facet for life to whatever role
+   * it was spawned under, and it now happens per call from the focus function
+   * the caller sets immediately afterwards (W7). The two always agreed — every
+   * spawn site sets a focus whose `function` matches its role — so the routed
+   * answer is the same one, decided later and from the work itself.
+   */
    spawnFacet( role?: 'deliberation' | 'conversation' | 'outreach' | 'supervision'): { attention: 'available' | 'full', handle?: ExecutiveFacetHandle } {
+    void role
     // Delegate to FacetSupervisor (R5-g-3), passing the current engine
     // attachments. The supervisor owns the registry + attention budget and
     // performs the throw-checks on bus / director / state ref.
-    // A role with its own configured model gets that role's director; every
-    // other facet shares the executive's (one self, role-appropriate depth).
-    // Outreach speaks with the conversation voice; supervision thinks with the
-    // executive's depth.
-    const roleModel =
-      role === 'deliberation'                        ? this._models.deliberation :
-      role === 'conversation' || role === 'outreach' ? this._models.conversation :
-      null
-    const director  = roleModel && this._llmDirector ? this._directorFor( roleModel ) : this._llmDirector
     return this._facetSupervisor.spawn( {
       bus:         this._bus,
-      llmDirector: director,
+      llmDirector: this._llmDirector,
       stateRef:    this._lastStateRef,
       willId:      this._willId,
       inbox:       this._inbox,
@@ -433,15 +491,32 @@ export class ExecutiveEngine extends AsyncEngine implements CognitiveEngine {
     this._gatingState.executiveInterval = rtConfig.executiveInterval
     this._gatingState.cooldownTicks = rtConfig.cooldownTicks
 
-    // Initialize LLM directors if not yet done (requires willId). One director
-    // per distinct role model; roles that share a model share the instance.
+    // Initialize the LLM director if not yet done (requires willId). One per
+    // Will — every role reaches its model through the router.
     if( !this._llmDirector && this._willId ){
-      const execModel = this._models.executive ?? process.env.WILL_LLM_MODEL
-        ?? defaultModelFor( ( this._llm?.provider ?? process.env.WILL_LLM_PROVIDER ?? 'anthropic') as LLMProvider )
-      this._llmDirector = this._directorFor( execModel )
-      // The summarizer runs its role's model (falls back to executive) with the
-      // same provider, session logging and token tracking.
-      this._summarizer?.attachLLMDirector( this._directorFor( this._models.summarizer ?? execModel ) )
+      // No default model. The engine used to fall back to a Claude id for every
+      // provider but GLM, which meant a misconfigured Will asked the wrong
+      // vendor for the wrong model and failed at the first tick with a 404
+      // instead of at construction with a sentence.
+      //
+      // Two cases legitimately have no credentials and are exempt: a test-mode
+      // Will (never reaches a network — demanding a key would break the whole
+      // point of the no-key quickstart) and a replay (completions are re-fed
+      // from the tape, which carries the model that actually served them). The
+      // sentinel is what a mock run records, so the tape still says plainly
+      // that nothing real answered.
+      const defaultModel = this._modelId ?? process.env.WILL_LLM_MODEL
+        ?? ( this._noLiveCalls() ? MOCK_MODEL : undefined )
+      if( !defaultModel )
+        throw new Error(
+          'No LLM model configured. Set one on the Will (llm.model) or in the ' +
+          'environment (WILL_LLM_MODEL) — the engine carries no default.'
+        )
+      this._llmDirector = this._buildDirector( defaultModel )
+      // The summarizer shares that director. Its calls tag themselves
+      // `category: 'summarizer'`, which is what a configured summarizer role
+      // compiles to — so it still gets its own model, chosen per call.
+      this._summarizer?.attachLLMDirector( this._llmDirector )
     }
 
     // Evaluate gating
@@ -593,7 +668,7 @@ export class ExecutiveEngine extends AsyncEngine implements CognitiveEngine {
         ideationUserMessage,
         tick: state.tick,
         proposeTemperature,
-        meta: { category: 'executive', attribute: 'master', function: 'ideation' },
+        meta: { category: 'executive', attribute: 'master', function: 'ideation', demand: processSelection.effortScore },
       } )
       logger.info(
         `[executive] ◆ deliberate propose tick=${state.tick}  ` +
@@ -646,7 +721,10 @@ export class ExecutiveEngine extends AsyncEngine implements CognitiveEngine {
 
     try {
       // Use streaming call when clients are connected (F3); fall back to regular call.
-      const masterMeta = { category: 'executive', attribute: 'master', function: 'decision' }
+      // MODEL_ROUTING W0 — the effort gate already weighed this tick's demand
+      // (uncertainty, prior confidence, novelty, a pending reply, stress load);
+      // forward it rather than inventing a second measure of the same thing.
+      const masterMeta: LLMCallMeta = { category: 'executive', attribute: 'master', function: 'decision', demand: processSelection.effortScore }
       const result = this._chunkBroadcaster
         ? await this._llmDirector.callStream( systemPrompt, userMessage, state.tick, this._chunkBroadcaster, undefined, masterMeta )
         : await this._llmDirector.call( systemPrompt, userMessage, state.tick, undefined, masterMeta )

package/src/cognition/faculties/executive.engine/facet.ts

@@ -424,7 +424,7 @@ export class ExecutiveFacet {
         ideationUserMessage,
         tick: currentState.tick,
         proposeTemperature,
-        meta: { category: 'executive', attribute: 'facet', function: this._currentFocus?.function ?? 'ideation', scope: this.facetId },
+        meta: { category: 'executive', attribute: 'facet', function: this._currentFocus?.function ?? 'ideation', scope: this.facetId, demand: processSelection.effortScore },
       } )
       logger.info(
         `[executive.facet] ${this.facetId} ◆ deliberate propose tick=${currentState.tick}  ` +
@@ -465,11 +465,19 @@ export class ExecutiveFacet {
       // Use streaming call when a per-facet chunk handler is registered —
       // this enables entity-scoped token delivery (e.g. AuditionEngine SSE).
       // Falls back to regular call when no handler is present.
+      // MODEL_ROUTING W0 — same effort gate as master, so a facet's demand is
+      // measured on the identical scale (a live message awaiting reply is this
+      // focus's stakes-bearing moment, and already weighs into the score).
       const facetMeta: LLMCallMeta = {
         category:  'executive',
         attribute: 'facet',
-        function:  this._currentFocus?.function ?? 'facet',
+        // A focus that declares no function is making its decision call, the
+        // facet's analogue of master's 'decision'. This previously fell back to
+        // 'facet' — an *attribute* value, which quietly created a bogus bucket
+        // in the by-function cost breakdown. The typed axes caught it.
+        function:  this._currentFocus?.function ?? 'decision',
         scope:     this.facetId,
+        demand:    processSelection.effortScore,
       }
       const result = this._chunkHandler
         ? await this._llmDirector.callStream( systemPrompt, userMessage, currentState.tick, this._chunkHandler, undefined, facetMeta )

package/src/cognition/faculties/executive.engine/prompt.factory.ts

@@ -45,6 +45,7 @@
  */
 
 import type { ReadonlySimulationState } from '#core/types'
+import type { LLMCallFunction } from '#cognition/utilities/token.tracker'
 import type { ExecutiveSummarizer } from '#llm/summarizer'
 import type { ExecutiveContext, PendingMessage, IdeationCandidate } from '#faculties/executive.engine/types'
 import { buildExecutiveContext, type ContextDependencies } from '#faculties/executive.engine/context'
@@ -158,7 +159,7 @@ export interface FocusSection {
    * into the facet's LLM calls as `LLMCallMeta.function` so the TokenTracker can
    * break spend down per facet type. Defaults to 'facet' when unset.
    */
-  function?: string
+  function?: LLMCallFunction
   /**
    * Optional: Custom output format to append instead of the standard executive format.
    * Pass via PromptBuildOptions.outputFormat when building the user message.

package/src/cognition/index.ts

@@ -9,6 +9,8 @@ import {
   type TokenUsage,
   type TokenLedgerRecord,
   type RecordUsageInput,
+  type PriceTable,
+  type ModelPrice,
 } from '#cognition/utilities/token.tracker'
 
 import { EnergyRegulator, type EnergyRegulatorConfig } from '#faculties/energy.regulator'
@@ -84,6 +86,8 @@ export {
   type TokenUsage,
   type TokenLedgerRecord,
   type RecordUsageInput,
+  type PriceTable,
+  type ModelPrice,
 
   // ── Regulatory Engines ─────────────────────────────────────
 

package/src/cognition/memory/vector.embedder.ts

@@ -12,6 +12,10 @@
  */
 
 import type { TokenTracker } from '#cognition/utilities/token.tracker'
+import type { LLMCallFunction } from '#cognition/utilities/token.tracker'
+
+/** Embedding is only ever a read or a write. */
+export type EmbedFunction = Extract<LLMCallFunction, 'recall' | 'index'>
 
 export interface EmbeddingProvider {
   readonly modelName: string
@@ -55,7 +59,7 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
     /**
      * Per-Will token tracker. When provided, each embedding call records its
      * input-token usage under the 'embedding' category so memory-vector spend is
-     * visible alongside LLM spend instead of being a silent COGS leak.
+     * visible alongside LLM spend instead of being a silent cost leak.
      */
     tokenTracker?: TokenTracker | null
   } ){
@@ -68,7 +72,7 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
     this._tokenTracker = config.tokenTracker ?? null
   }
 
-  async embed( content: unknown, fn: string = 'recall'): Promise<number[]> {
+  async embed( content: unknown, fn: EmbedFunction = 'recall'): Promise<number[]> {
     let response: Response
     try {
       response = await fetch(`${this._apiUrl}/embeddings`, {
@@ -128,7 +132,7 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
     return embedding
   }
 
-  async embedBatch( contents: unknown[], fn: string = 'index'): Promise<number[][]> {
+  async embedBatch( contents: unknown[], fn: EmbedFunction = 'index'): Promise<number[][]> {
     // Bounded fan-out: cap concurrent requests at _maxConcurrency instead of
     // firing all of them at once (FN16), while preserving input order.
     const results: number[][] = new Array( contents.length )
@@ -170,7 +174,7 @@ export class MockEmbedder implements EmbeddingProvider {
     this._seed = seed
   }
 
-  async embed( content: unknown, _fn: string = 'recall'): Promise<number[]> {
+  async embed( content: unknown, _fn: EmbedFunction = 'recall'): Promise<number[]> {
     const str = typeof content === 'string' ? content : JSON.stringify( content )
     const hash = this._hashString( str )
     const embedding: number[] = []
@@ -184,7 +188,7 @@ export class MockEmbedder implements EmbeddingProvider {
     return embedding
   }
 
-  async embedBatch( contents: unknown[], fn: string = 'index'): Promise<number[][]> {
+  async embedBatch( contents: unknown[], fn: EmbedFunction = 'index'): Promise<number[][]> {
     return Promise.all( contents.map( c => this.embed( c, fn ) ) )
   }