@mindot/will 0.1.0

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

@@ -0,0 +1,323 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/types.ts
+// ─────────────────────────────────────────────────────────────
+
+import type { CognitiveBus } from '#cognition/bus'
+import type { PlanStep } from '#cognition/faculties/planning.engine/engine'
+
+// ── Full executive output ────────────────────────────────────
+
+export interface ExecutiveOutputFull {
+  actions: Array<{ type: string; reasoning: string; expectedOutcome: string; target?: string }>
+  reasoning: string
+  confidence: number
+  /** Plans — the executive controls lifecycle via status + action fields */
+  plans?: ExecutivePlanOutput[]
+  newBeliefs?: Array<{
+    statement: string
+    category: string
+    confidence: number
+    /**
+     * Evidence strength — replaces the hallucination-prone numeric count.
+     * The LLM picks a categorical label it can honestly assign; the runtime
+     * maps it to a numeric `supportingEpisodes` value for the belief store.
+     */
+    evidence: 'single_observation' | 'recurring_pattern' | 'strong_pattern'
+    tags: string[]
+  }>
+  introspection?: {
+    explanation: string
+    identifiedBiases: string[]
+    lessonsLearned: string[]
+    recommendations: string[]
+  }
+  narrative?: string
+  narrativeThemes?: string[]
+  currentSelfView?: string
+  identityUpdates?: {
+    traits: Array<{ key: string; value: number }>
+    values: string[]
+  }
+  /**
+   * What the Will consciously learned about the *others* it is dealing with (the analogue
+   * of identityUpdates, but about someone/something else). `keid` is the referent from the
+   * known-entity dossier / "## People You Know" context. `name` is a learned identifying
+   * name; `learned` are facts (→ keid-tagged social beliefs, so they ride the memory
+   * pipeline); `feeling` is a felt valence toward them (a bounded nudge).
+   */
+  knownEntityUpdates?: Array<{
+    keid:     string
+    name?:    string
+    learned?: string[]
+    feeling?: number
+  }>
+  newGoals?: Array<{
+    description: string
+    priority: number
+    tags: string[]
+    completionType: string
+    completionCondition?: string
+  }>
+  goalsToAbandon?: Array<{ goalId: string; reason: string }>
+  goalsToReprioritize?: Array<{ goalId: string; newPriority: number; reason: string }>
+  selfObservations?: string[]
+  /**
+   * Plain-text reply from a conversation facet — populated by parseResponse()
+   * from the [REPLY_TEXT]...[/REPLY_TEXT] block.
+   * Only present in facet mode (AuditionEngine). Undefined for master cycles.
+   * Paragraphs (double-newline separated) map to separate reply bubbles.
+   */
+  replyText?: string
+  /**
+   * @deprecated Legacy JSON reply format — no longer emitted by conversation facets.
+   * Kept for backward compatibility with any tests/tooling that inspect parsed output.
+   */
+  conversationReplies?: Array<{
+    targetEntityId: string
+    targetEntityName: string
+    messages: string[]
+  }>
+  /**
+   * System 2 only — the distinct approaches the master generated and weighed before
+   * committing, retained for explainability/auditability (and a future regret /
+   * counterfactual substrate). Populated on the deliberate (propose→evaluate) path;
+   * undefined for System 1 (the fast single-shot).
+   */
+  consideredAlternatives?: string[]
+}
+
+// ── Ideation (System 2 propose pass) ─────────────────────────
+
+/**
+ * One candidate approach from the deliberate path's ideation (propose) pass — a
+ * divergent option the master generated *before* deciding. The evaluate pass weighs
+ * these and commits; the chosen-against set is retained as `consideredAlternatives`.
+ */
+export interface IdeationCandidate {
+  /** Short handle for the option (e.g. "ask for clarification"). */
+  approach: string
+  /** One-line description of what this option concretely entails. */
+  description: string
+  /** Its main upside. */
+  upside: string
+  /** Its main risk or downside. */
+  risk: string
+}
+
+/** Output of the ideation (propose) pass — a divergent candidate set, not a decision. */
+export interface IdeationOutput {
+  candidates: IdeationCandidate[]
+}
+
+/**
+ * Plan output from the executive LLM.
+ *
+ * This is what the LLM produces in the [PLANS] tagged block.
+ * It includes lifecycle control fields (status, action, executionTier,
+ * expectedOutcome) that only the executive sets, plus the step structure
+ * that feeds into PlanningEngine's Plan type.
+ */
+export interface ExecutivePlanOutput {
+  /**
+   * Target an EXISTING plan for validate/execute/revise/cancel. Omit on a fresh
+   * `draft` to create a new plan. Enables managing multiple plans per goal (P4);
+   * when omitted, the op falls back to the goal's active plan.
+   */
+  planId?: string
+  goalId: string
+  /** Lifecycle stage the executive is setting */
+  status: 'draft' | 'validated' | 'approved' | 'revised' | 'rejected'
+  /** What PlanningEngine should do with this plan */
+  action: 'draft' | 'validate' | 'execute' | 'revise' | 'cancel'
+  /** Concrete description of what successful completion looks like */
+  expectedOutcome?: string
+  /** The steps — mirrors PlanStep structure from PlanningEngine */
+  steps: Array<Pick<PlanStep, 'action' | 'description' | 'expectedOutcome' | 'estimatedDuration' | 'prerequisites'>>
+  estimatedCost: number
+  feasibility: number
+}
+
+// ── Minimal output from LLM (before tagged-block parsing) ────
+
+export interface ExecutiveOutputMinimal {
+  actions: Array<{ type: string; reasoning: string; expectedOutcome: string; target?: string }>
+  reasoning: string
+  confidence: number
+}
+
+// ── Engine config ────────────────────────────────────────────
+
+export interface ExecutiveEngineConfig {
+  executiveInterval?: number
+  cooldownTicks?: number
+  bus?: CognitiveBus
+}
+
+// ── Context ──────────────────────────────────────────────────
+
+export type ExecutiveAttentionType = 'available' | 'full'
+export interface ExecutiveContext {
+  identity: {
+    /** Canonical persona name — from WillConfig.name (e.g. "Aria", "Guard-1"). */
+    name: string
+    prompt: string
+    values: string[]
+    traits: Record<string, number>
+    /**
+     * Per-trait self-knowledge (personal baseline + recent-shift direction) accumulated
+     * by the self-model, for graded-salience options B (relative to my own norm) and C
+     * ("rising/easing lately"). Absent until the self-model has evaluated at least once.
+     */
+    traitStats?: Record<string, { mean: number; shiftDir: number; shiftTick: number }>
+    style: string
+  }
+  worldState: {
+    energyLevel: number
+    sleepPressure: number
+    stressLoad: number
+    circadianPhase: number
+    timeOfDay: number
+    /**
+     * Tonic threat level (0–1). Always present in the standing context so a
+     * *sustained* threat stays represented even after its events habituate out of
+     * the workspace — representation (this) is kept separate from attention
+     * (event salience). See reward/threat Option-B salience.
+     */
+    threatLevel: number
+  }
+  affect: {
+    dominantEmotion: string
+    valence: number
+    arousal: number
+    dominance: number
+    blends: string[]
+  }
+  goals: Array<{
+    id: string
+    description: string
+    priority: number
+    progress: number
+    status: string
+    deadline?: number
+    lastActionAttemptTick?: number
+    lastActionType?: string
+  }>
+  /**
+   * Active/known plans, read from persisted `plan` entities — gives the executive
+   * execution awareness: which plans exist per goal, their status and step
+   * progress, so it can target a specific plan by id when managing several. (P4)
+   */
+  plans: Array<{
+    id: string
+    goalId: string
+    status: string
+    executionTier: string
+    totalSteps: number
+    completedSteps: number
+    expectedOutcome: string
+    /** Causal link to the requester whose message spawned the plan (for scoping). */
+    requestingEntityId?: string
+  }>
+  /**
+   * Plan ids surfaced by the latest episodic recall (plan descriptors carry their
+   * planId) — drives recall-scoped plan awareness (AWARENESS Stage 2). Generalizes
+   * the scope filter from `requestingEntityId` to relevance.
+   */
+  relevantPlanIds: string[]
+  percepts: Array<{
+    category: string
+    summary: string
+    salience: number
+  }>
+  workingMemory: Array<{
+    type: string
+    summary: string
+    activation: number
+  }>
+  memories: Array<{
+    content: string
+    relevance: number
+    emotionalContext: string
+    /** Simulation tick when this memory was consolidated. Used to render approximate age. */
+    tick?: number
+  }>
+  beliefs: Array<{
+    statement: string
+    category: string
+    confidence: number
+  }>
+  /** How many beliefs exist but were not included due to the relevance cap. */
+  beliefsOmitted: number
+  /**
+   * Recent action outcomes — shows the executive what it already tried and whether it
+   * landed.  Built from `decision.record` entities with an `actionStatus` set.
+   * Surfaces the Act→Confirm→Perceive feedback loop into the executive's reasoning.
+   */
+  recentActions: Array<{
+    /** Effector name that was invoked */
+    type: string
+    /** Lifecycle status set by ActionExecutor */
+    status: 'completed' | 'failed' | 'awaiting_host' | 'timed_out'
+    /** Tick the action was executed or dispatched */
+    tick: number
+    /** Short outcome description — truncated to 120 chars */
+    outcome: string
+    /** planId if this action came from a plan step */
+    planId?: string
+  }>
+  /** Behavioral disposition loaded from PMA at session start — stable per session. */
+  behavioralDisposition?: {
+    riskTolerance:   number
+    explorationRate: number
+    impulsivity:     number
+  }
+  /**
+   * How the Will has self-tuned its own faculties (the metacognition cycle's
+   * persona-prior), as first-person phrases — lets the deliberate self see its
+   * own accommodation. Omitted when no prior is active.
+   */
+  selfTuning?: string[]
+  /**
+   * What the Will knows about the others it has encountered — the known-entity dossier
+   * view, surfaced for reasoning. Joins theory-of-mind (what they seem to want/feel),
+   * reputation (trust/cooperativeness/reliability) and attachment (closeness) per `keid`,
+   * sorted by interaction recency, capped. `name` may be absent — the Will can know
+   * *someone* without yet knowing their name (provisional identity). `kind` is `sentient`
+   * for everything modelled here today; `thing` arrives with the generalised dossier.
+   * Omitted when the Will knows no one.
+   */
+  knownEntities?: Array<{
+    keid:            string
+    kind:            'sentient' | 'thing'
+    name?:           string
+    intention?:      string
+    emotion?:        string
+    trust?:          number
+    cooperativeness?: number
+    closeness?:      number
+    reliability?:    number
+    confidence?:     number
+  }>
+  /**
+   * What the Will is currently focused on (task.switcher) and how committed — surfaces
+   * task-persistence so the deliberate self weighs the cost of switching away. The
+   * `switchCost` (= effective `baseSwitchCost`, conscientiousness-developable, #28) scales
+   * how strong the pull to stay is. Omitted when nothing is in focus.
+   */
+  currentFocus?: {
+    goalId:          string
+    goalDescription?: string
+    focusTicks:      number
+    switchCost:      number
+  }
+}
+
+// ── Pending message ──────────────────────────────────────────
+
+export interface PendingMessage {
+  id: string
+  content: string
+  sender: string
+  senderId: string
+  tick: number
+}

package/src/cognition/faculties/exteroception.ts

@@ -0,0 +1,338 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/exteroception.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Exteroception — processes external world events into structured percepts.
+ *
+ * Scans the event bus and entity space for:
+ *   - New entities entering the world
+ *   - Changes to existing entities
+ *   - Explicit events (messages, notifications, environmental changes)
+ *   - Other agents' observable actions
+ *
+ * Each percept is an entity with salience tagging, enabling downstream
+ * engines (Attention, Affective, Memory) to prioritize processing.
+ *
+ * Part of Shard 0 (Perceptual Layer) — runs every tick, synchronous.
+ */
+
+import type {
+  Duration,
+  Tick,
+  Timestamp,
+  SimulationContext,
+  ReadonlySimulationState,
+  StateCommands,
+  SimulationEvent,
+  SimulationEntity,
+} from '#core/types'
+import type { SimulationEngine, EngineResult, CognitiveEngine } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+import type { CognitiveEvent, CognitiveBus } from '#cognition/bus'
+import { GenerativeModel } from '#cognition/generative.model'
+
+export interface ExteroceptionConfig {
+  /** Maximum percepts to produce per tick */
+  maxPerceptsPerTick?: number
+  /** Default salience for unmarked percepts */
+  defaultSalience?: number
+  /** Whether to emit percept events */
+  emitPerceptEvents?: boolean
+  /** Entity types to always treat as high-salience */
+  highPriorityTypes?: string[]
+  bus?: CognitiveBus
+}
+
+interface RawPercept {
+  entityId: string
+  changeType: 'appeared' | 'modified' | 'removed'
+  salience: number
+  category: string
+  summary: string
+}
+
+// Skip internal entities — they're not external percepts.
+// Percepts about percepts create a feedback loop that floods
+// working memory and episodic storage with noise.
+const internalTypes = new Set([
+  'percept', 'percept.social', 'working_memory.item',
+  'interoception', 'attention.focus', 'decision.record',
+  'task.focus', 'self_observation',
+  'goal', 'belief', 'plan', 'narrative_chapter',
+  'introspection', 'self_narrative', 'cognitive_bias',
+  'effector.created', 'empathic_state', 'attachment.bond',
+  'theory_of_mind', 'reputation', 'episodic_memory',
+  // Internal state entities written by our own engines — not external events
+  'affect.blends', 'executive.summary',
+])
+
+export class Exteroception implements SimulationEngine, CognitiveEngine {
+  readonly name     = 'exteroception'
+  
+  private _maxPerceptsPerTick: number
+  private _defaultSalience: number
+  private _emitPerceptEvents: boolean
+  private _highPriorityTypes: Set<string>
+  private _previousEntityVersions = new Map<string, number>()  // entityId → updatedAt
+
+  private _bus: CognitiveBus | null = null
+
+  private readonly _model    = new GenerativeModel()
+
+
+  constructor( config: ExteroceptionConfig = {} ){
+    this._bus = config.bus ?? null
+    this._maxPerceptsPerTick = config.maxPerceptsPerTick ?? 50
+    this._defaultSalience    = config.defaultSalience    ?? 0.3
+    this._emitPerceptEvents  = config.emitPerceptEvents  ?? true
+    this._highPriorityTypes  = new Set( config.highPriorityTypes ?? [
+      'message', 'notification', 'alert', 'threat', 'goal',
+    ])
+  }
+  attachBus( bus: CognitiveBus ): void { this._bus = bus }
+
+  // ── Engine interface ─────────────────────────────────────
+
+  subscribes(): string[] { return ['executive.prediction.formed'] }
+  publishes(): CognitiveEventSchema[] {
+    return [{ type: 'percept.category.updated', version: 1, validate: () => null }]
+  }
+
+  onCognitiveEvent( e: CognitiveEvent ): StateCommands | void {
+    this._model.observe( e.type, e.salience )
+    if( e.type === 'executive.prediction.formed' ){
+      const p = e.payload as { predictedDomains: string[]; confidence: number }
+      if( p.predictedDomains.includes('perception') )
+        this._model.setPrecision( 'percept.rate', 1.0 + p.confidence * 0.5 )
+    }
+  }
+
+  snapshot(): Record<string, unknown> { return {} }
+
+  async react(
+    _delta: Duration,
+    tick: Tick,
+    state: ReadonlySimulationState,
+    context: SimulationContext
+  ): Promise<EngineResult> {
+    const
+    events:   Array<Omit<SimulationEvent, 'id' | 'timestamp' | 'tick'>> = [],
+    commands: StateCommands = { set: [], delete: [], metrics: [] }
+
+    const rawPercepts = this._scanWorld( state )
+
+    // Cap percepts per tick
+    const capped = rawPercepts.slice( 0, this._maxPerceptsPerTick )
+
+    // Convert raw percepts to entities
+    for( let i = 0; i < capped.length; i++ ){
+      const rp = capped[i]!
+
+      const perceptEntity = {
+        id: `percept-${tick}-${i}`,
+        type: 'percept',
+        metadata: {
+          entityId: rp.entityId,
+          changeType: rp.changeType,
+          salience: rp.salience,
+          category: rp.category,
+          summary: rp.summary,
+          tick,
+        },
+      }
+
+      commands.set!.push( perceptEntity )
+
+      // Emit percept event for downstream engines
+      if( this._emitPerceptEvents )
+        events.push({
+          type: `percept.${rp.changeType}.${rp.category}`,
+          source: this.name,
+          payload: {
+            entityId: rp.entityId,
+            salience: rp.salience,
+            category: rp.category,
+            summary: rp.summary,
+          },
+        })
+    }
+
+    // Clean up old percepts from previous ticks (keep last 2 ticks of percepts)
+    commands.delete = this._collectStalePerceptIds( state, tick )
+
+    // Aggregate metrics
+    commands.metrics!.push(
+      [ 'perception.percepts_this_tick', capped.length ],
+      [ 'perception.total_entities_observed', state.entities.size ],
+    )
+
+
+    // Phase C + F: publish cognitive event — gated by prediction error
+    const _bus = this._bus
+    if( _bus && capped.length > 0 ){
+      const predErr = this._model.observe( 'percept.rate', capped.length )
+      if( !predErr.gated )
+        _bus.publish({ type: 'percept.batch.ingested', version: 1, sourceEngine: this.name, salience: Math.max( 0.2, predErr.salience ), payload: { count: capped.length } })
+    }
+
+    // percept.category.updated — one event per distinct category so subscribers
+    // (aesthetic.evaluator etc.) get a structured signal without scanning percepts
+    if( _bus && capped.length > 0 ){
+      const countByCategory = new Map<string, number>()
+      for( const rp of capped )
+        countByCategory.set( rp.category, ( countByCategory.get( rp.category ) ?? 0 ) + 1 )
+      for( const [ category, count ] of countByCategory )
+        _bus.publish({ type: 'percept.category.updated', version: 1, sourceEngine: this.name, salience: Math.min( 1, count * 0.15 + 0.2 ), payload: { category, count } })
+    }
+
+    return { events: events.length > 0 ? events : undefined, commands }
+  }
+
+  // ── Internal ─────────────────────────────────────────────
+
+  /**
+   * Scan the world for perceptible changes.
+   * Compares current entity state against previous versions.
+   */
+  // In _scanWorld(), replace the entity loop with this:
+
+private _scanWorld( state: ReadonlySimulationState ): RawPercept[] {
+    const percepts: RawPercept[] = []
+    const currentIds = new Set<string>()
+
+    for( const [ id, entity ] of state.entities ){
+      currentIds.add( id )
+
+      if( internalTypes.has( entity.type ) ){
+        // Still track the version so we don't get "appeared" events
+        // when these internal entities are first created
+        this._previousEntityVersions.set( id, entity.updatedAt )
+        continue
+      }
+
+      const previousVersion = this._previousEntityVersions.get( id )
+
+      if( previousVersion === undefined ){
+        percepts.push({
+          entityId: id,
+          changeType: 'appeared',
+          salience: this._computeSalience( entity, 'appeared', state.time ),
+          category: entity.type,
+          summary: this._summarizeEntity( entity, 'appeared'),
+        })
+      }
+      else if( entity.updatedAt > previousVersion ){
+        percepts.push({
+          entityId: id,
+          changeType: 'modified',
+          salience: this._computeSalience( entity, 'modified', state.time ),
+          category: entity.type,
+          summary: this._summarizeEntity( entity, 'modified'),
+        })
+      }
+
+      this._previousEntityVersions.set( id, entity.updatedAt )
+    }
+
+    // Detect removed entities (not internal types)
+    for( const [ id ] of this._previousEntityVersions ){
+      if( !currentIds.has( id ) ){
+        // Only report removal of meaningful entities
+        // We can't check the type here since the entity is gone,
+        // but we can infer from the ID prefix
+        if( !id.startsWith('percept-') 
+            && !id.startsWith('wm-')
+            && !id.startsWith('attention-')
+            && !id.startsWith('decision-')
+            && !id.startsWith('interoception-')
+            && !id.startsWith('task-')
+            && !id.startsWith('self-obs-') ){
+          percepts.push({
+            entityId: id,
+            changeType: 'removed',
+            salience: 0.4,
+            category: 'removed',
+            summary: `Entity removed: ${id}`,
+          })
+        }
+        this._previousEntityVersions.delete( id )
+      }
+    }
+
+    percepts.sort( ( a, b ) => b.salience - a.salience )
+    return percepts
+  }
+
+  /**
+   * Generate a meaningful summary for an entity.
+   * Instead of "New percept: percept-54-0", produce something useful.
+   */
+  private _summarizeEntity(
+    entity: Readonly<SimulationEntity>,
+    changeType: string
+  ): string {
+    const name = entity.metadata?.name as string | undefined
+    const description = entity.metadata?.description as string | undefined
+
+    if( name ){
+      return changeType === 'appeared'
+        ? `${name} appears` : `${name} changed`
+    }
+    if( description ){
+      return description.slice( 0, 100 )
+    }
+
+    return `New ${entity.type}: ${entity.id.slice(0, 30)}`
+  }
+
+  /**
+   * Compute salience of a percept based on entity characteristics.
+   */
+  private _computeSalience(
+    entity: Readonly<SimulationEntity>,
+    _changeType: string,
+    now: Timestamp
+  ): number {
+    let salience = this._defaultSalience
+
+    // High-priority types get baseline boost
+    if( this._highPriorityTypes.has( entity.type ) )
+      salience += 0.4
+
+    // Entity metadata can specify explicit salience
+    if( typeof entity.metadata?.salience === 'number')
+      salience = entity.metadata.salience
+
+    // Urgency metadata boosts salience
+    if( typeof entity.metadata?.urgency === 'number')
+      salience += entity.metadata.urgency * 0.3
+
+    // Recency boost — entities with recent updatedAt are more salient.
+    // Both sides are sim-time ms (updatedAt is stamped by StateManager from the
+    // sim clock), so recency is measured against sim-time, never wall-clock (R2).
+    const ageSeconds = ( now - entity.updatedAt ) / 1000
+    if( ageSeconds < 10 )
+      salience += 0.2
+    else if( ageSeconds < 60 )
+      salience += 0.1
+
+    return Math.min( 1, Math.max( 0, salience ) )
+  }
+
+  /**
+   * Collect IDs of stale percept entities to clean up.
+   */
+  private _collectStalePerceptIds( state: ReadonlySimulationState, currentTick: Tick ): string[] {
+    const stale: string[] = []
+
+    for( const [ id, entity ] of state.entities ){
+      if( entity.type === 'percept' && typeof entity.metadata?.tick === 'number'){
+        if( currentTick - entity.metadata.tick > 2 )
+          stale.push( id )
+      }
+    }
+
+    return stale
+  }
+}