@mindot/will 0.7.0 → 0.9.0

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'
@@ -55,6 +56,8 @@ export interface Stimulus {
   speaker?: string
   /** Conversation/thread id (default = `from`). */
   thread?: string
+  /** True when `thread` is private — just this someone and the Will. See TextMessage.direct. */
+  direct?: boolean
 }
 
 /** A message the Will emitted to someone. */
@@ -65,6 +68,20 @@ export interface WillMessage {
   content: string
   /** Entity id the Will addressed (the speaker you used in say()/tell(), or a bond). */
   to: string
+  /**
+   * The conversation this belongs to — the `thread` from the `perceive()` that
+   * prompted it. Absent when the Will spoke unprompted, which genuinely has no
+   * thread.
+   *
+   * WHERE, not just to whom. The engine knew this the whole way down —
+   * `OutboxMessage.threadId` carries it — and the projection dropped it here, so
+   * a channel adapter had nothing to answer INTO and had to guess from a roster.
+   * Observed live: a DM arrived on `discord:1532693…`, she answered it correctly
+   * and in seconds, and the reply went to the shared server channel because that
+   * was the last room the roster had seen this person in. From the operator's
+   * side she had simply ignored him.
+   */
+  thread?: string
 }
 
 /**
@@ -165,20 +182,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 +252,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
@@ -261,17 +335,29 @@ export class Will {
     pma: PMASnapshot,
     opts: Omit<CreateWillOptions, 'identity'> & { identity?: Partial<WillIdentity> },
   ): Promise<Will> {
-    const id = opts.id ?? `${slug( opts.name )}-${Math.random().toString( 36 ).slice( 2, 8 )}`
+    // Waking IS being the same mind, so the id continues from the artifact unless the
+    // caller overrides it. The id is the path key for everything durable that lives
+    // OUTSIDE the artifact — `data/wills/<id>/vector_index`, snapshots, session logs.
+    // Minting a fresh `name-<random>` here gave a woken mind a brand-new, empty vector
+    // store every boot: identity/beliefs/goals returned (those are in the artifact) while
+    // episodic recall came back permanently empty, and the orphaned index was left behind
+    // on disk. Observed: four boots, four `lora-*` directories, four 4KB indexes, and a
+    // mind that concluded at 100% confidence that its own channel might not be viable
+    // because it could not recall a conversation it had just had.
+    const id = opts.id ?? pma.willId ?? `${slug( opts.name )}-${Math.random().toString( 36 ).slice( 2, 8 )}`
     const stem = new WillStem()
     const will = new Will( stem, id, opts.name )
 
     for( const [ name, entry ] of Object.entries( opts.effectors ?? {} ) )
       will._register( name, entry )
 
-    await stem.createWill(
-      will._buildConfig( id, { ...opts, identity: { prompt: '', ...opts.identity } } ),
-      true /* startPaused — load the artifact before the first tick */,
-    )
+    const config = will._buildConfig( id, { ...opts, identity: { prompt: '', ...opts.identity } } )
+    // Say out loud that this identity is a placeholder. Otherwise the creation
+    // guard warns about the empty persona we just constructed on purpose — three
+    // alarms per wake, drowning the real check that runs when the artifact loads.
+    config.identityFromArtifact = true
+
+    await stem.createWill( config, true /* startPaused — load the artifact before the first tick */ )
     stem.loadPMA( id, pma )
     stem.resumeWill( id )
     will._attach()
@@ -300,6 +386,8 @@ export class Will {
       // the Will knows the person as "someone" until a real one is learned. (The live
       // conversation focus still falls back to the entity id for its Speaker line.)
       ...( stimulus.speaker ? { speakerName: stimulus.speaker } : {} ),
+      // Omitted rather than defaulted: an unknown room is not known to be public.
+      ...( stimulus.direct !== undefined ? { direct: stimulus.direct } : {} ),
     } )
   }
 
@@ -462,13 +550,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 +575,6 @@ export class Will {
         style:  opts.identity.style ?? '',
       },
       anatomy: opts.anatomy ?? 'mind',
-      model:   opts.model,
       llm:     llmConfig,
       testMode:   useMock,
       persistentMemory: opts.persist ?? false,
@@ -495,7 +591,10 @@ export class Will {
     this._unsub = this.stem.addTickListener( this.id, ( _snapshot, _tick, outbox, invocations ) => {
       // Outbound messages → event + auto delivery-ack.
       for( const msg of outbox ){
-        this._emitMessage( { id: msg.id, content: msg.content, to: msg.targetEntityId } )
+        this._emitMessage( {
+          id: msg.id, content: msg.content, to: msg.targetEntityId,
+          ...( msg.threadId ? { thread: msg.threadId } : {} ),
+        } )
         try { this.stem.confirmMessageDelivery( this.id, msg.id, true ) } catch { /* best-effort */ }
       }
       // Effector invocations → project the motor act, then run the handler → ack.

package/src/stem/assembly.audit.ts

@@ -86,3 +86,4 @@ export function auditAssemblyWiring( engines: readonly SimulationEngine[] ): Wir
 export function wiringKeys( records: WiringRecord[], status: WiringRecord['status'] ): string[] {
   return records.filter( r => r.status === status ).map( r => `${r.engine}.${r.method}`).sort()
 }
+

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', process: 'cog', 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

@@ -23,7 +23,7 @@ import type { ExecutiveOutputFull } from '#faculties/executive.engine'
 import type { Cognition, OutboxMessage, effectorInvocation, WorldInterface } from '#types'
 import type { TextMessage, SensoryInput } from '#senses/index'
 import type { ActivityEvent, ActivityEventHandler } from '#cognition/faculties/planning.engine/engine'
-import { assembleMind, type WillConfig } from '#stem/mind'
+import { assembleMind, backfillEngineConfigs, resolveExecutiveInterval, type WillConfig } from '#stem/mind'
 import { reviewIdentityCoherence as runCoherenceReview, type CoherenceInput, type CoherenceResult } from '#stem/guards/identity.coherence'
 import { SessionLogger } from '#stem/tracts/session.logger'
 import { fileLoggingEnabled } from '#stem/tracts/transport/stream.transport'
@@ -39,10 +39,13 @@ import { InboundQueue } from '#stem/tracts/inbound.queue'
 import type { ExternalTransport } from '#stem/tracts/transport'
 import { effectorController } from '#stem/tracts/effector.controller'
 import { externalSchemas } from '#agency/schemas/external'
+import { inFlightOnRestore } from '#agency/restart'
+import { buildEngineConfigEntities } from '#cognition/config.mirror.entities'
 import type { EffectorDeclaration } from '#agency/types'
 import { SensoryController } from '#stem/tracts/sensory.controller'
 import { BiographyWriter } from '#stem/tracts/biography.writer'
 import { HealthReporter } from '#stem/tracts/health.reporter'
+import { mergeIdentity } from '#cognition/identity.entity'
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -95,7 +98,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
@@ -224,8 +227,66 @@ export class WillStem {
       try {
         const previousState = await simulation.snapshotManager.loadLatestFromStorage()
         if( previousState ){
+          // Work that was in flight when the mind slept does not resume — see
+          // agency/restart.ts. Dropped BEFORE restore so it never enters live
+          // state at all, rather than being swept on some later tick.
+          const inFlight = inFlightOnRestore( previousState.entities )
+          for( const id of inFlight ) previousState.entities.delete( id )
+
           simulation.stateManager.restore( previousState, { entities: true, metrics: false } )
-          logger.info(`[WillStem] Restored snapshot for ${config.id} — ${previousState.entities.size} entities loaded`)
+
+          // TIME MUST NOT GO BACKWARDS.
+          //
+          // Entities come back stamped with the tick they were written at, and
+          // the orchestrator overwrites the StateManager's tick from the CLOCK
+          // every tick (`_clock.tick()` → `updateClock`) — so restoring the
+          // manager's tick alone is undone immediately. The clock is the source
+          // of truth and has to resume too.
+          //
+          // Without this, every `tick - stampedTick` in the codebase computed a
+          // negative age. Measured: an awaiting intent read `-589 ticks`, so it
+          // could never time out, and the selector's staleness decay inverted
+          // into amplification (`1 - (-39 × 0.5)` = 20.6×) — a 0.47 incumbent
+          // scoring 9.74, unpreemptable, holding the channel against every other
+          // contact indefinitely and across restarts. It also means tick-stamped
+          // entity ids (`affordance-${tick}-…`, `agency-outcome-${tick}-…`) stop
+          // colliding with a previous session's.
+          simulation.clock.setTick( previousState.tick )
+
+          // The restore above replaced the entity map wholesale, including the
+          // engine-config mirror `assembleMind` had just seeded — so a Will woke
+          // with whatever config it FIRST hibernated under, and every tunable
+          // added since was unreachable to it. Restored values win; only params it
+          // has never seen are added.
+          backfillEngineConfigs( simulation, buildEngineConfigEntities( config, resolveExecutiveInterval( config ) ) )
+
+          // The same wholesale replacement takes `identity-self` — so the name
+          // `_seedIdentity` wrote moments ago is replaced by whatever the snapshot
+          // carries, which for any mind hibernated before the merging writer
+          // existed is NO NAME AT ALL.
+          //
+          // Caught only by booting: making every writer merge is necessary and was
+          // not sufficient, because restore is not a writer — it is the whole map
+          // arriving at once, and it lands between `_seedIdentity` and `loadPMA`.
+          // A live Will woke from a repaired build and still told her operator "my
+          // self-model says I'm Will".
+          //
+          // ONLY the name is re-asserted. Everything else on this entity — prompt,
+          // values, traits, traitStats, style — is the mind's own accumulated
+          // self-knowledge and must come from the snapshot, not from boot config.
+          // The name is the one field the container supplies and the tenant never
+          // learns, which is exactly why it is the one field a restore may not eat.
+          if( config.name ){
+            const restored = mergeIdentity( simulation.stateManager, { name: config.name } )
+            if( restored.length )
+              logger.info(`[WillStem] identity-self: re-asserted name '${config.name}' after restore`)
+          }
+
+          logger.info(
+            `[WillStem] Restored snapshot for ${config.id} — ${previousState.entities.size} entities loaded, ` +
+            `resuming at tick ${previousState.tick}` +
+            ( inFlight.length ? ` (dropped ${inFlight.length} in-flight)` : '')
+          )
         }
       }
       catch( err ){ logger.warn(`[WillStem] Snapshot restore failed for ${config.id} — starting fresh:`, err ) }
@@ -289,7 +350,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(),
     })
 
@@ -459,6 +520,12 @@ export class WillStem {
     instance.simulation.snapshotManager.persistNow( pauseState )
       .catch( err => logger.error(`[WillStem] snapshot persist failed on pause (${id}):`, err ))
 
+    // The vector index lives outside the snapshot and only ever persisted itself from
+    // a debounce timer nothing awaited — so it died with the process, and every
+    // restart cold-started with an EMPTY index no matter how much was consolidated.
+    instance.cognition.vectorMemory?.persist()
+      .catch( ( err: unknown ) => logger.error(`[WillStem] vector index persist failed on pause (${id}):`, err ))
+
     this._biography.writeSessionSummary( instance )
     this._biography.writeEmotionalBiographySummary( instance )
     instance.sessionLogger?.close()
@@ -574,6 +641,16 @@ export class WillStem {
       instance.simulation.stateManager.applyCommands( flushCmds )
     const archiveState = instance.simulation.stateManager.snapshot()
     await instance.simulation.snapshotManager.persistNow( archiveState )
+
+    // …and the vector index, which is NOT part of that snapshot. Awaited here (unlike
+    // the pause path) because the process usually exits straight after this: a
+    // fire-and-forget write would simply be lost, which is exactly how a mind ended a
+    // session having consolidated episodes and left a 198-byte index on disk.
+    // Indexing runs in the background (it must not stall the tick loop), so drain it
+    // first — otherwise the last episodes consolidated are still mid-embed when the
+    // index is written and are absent from the file this session leaves behind.
+    await instance.cognition.episodicConsolidator.flushIndexing()
+    await instance.cognition.vectorMemory?.persist()
   }
 
   // Session-biography writers (behavioral + emotional) extracted to
@@ -942,7 +1019,7 @@ export class WillStem {
       createdAt:  inst.createdAt,
       lastTickAt: inst.lastTickAt,
       anatomy:    inst.config.anatomy ?? 'mind',
-      model:      inst.config.model,
+      model:      inst.config.llm?.model,
     }))
   }