@mindot/will 0.1.0

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

@@ -0,0 +1,222 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/gating.ts
+// ─────────────────────────────────────────────────────────────
+
+import type { PendingMessage } from '#faculties/executive.engine/types'
+import type { Tick, ReadonlySimulationState } from '#core/types'
+import type { GenerativeModel } from '#cognition/generative.model'
+import {
+  BUFFER_SALIENCE_TRIGGER,
+  BUFFER_MAX_AGE_TICKS,
+} from '#faculties/executive.engine/config'
+import type { CognitiveEvent } from '#cognition/bus'
+
+function hasPendingInstructions( state: ReadonlySimulationState, pendingMessages: PendingMessage[] ): boolean {
+  for( const entity of state.entities.values() ){
+    if( entity.type === 'percept' || entity.type === 'percept.social' ){
+      const salience = (entity.metadata?.salience as number) ?? 0
+      if( salience > 0.7 ) return true
+    }
+
+    if( entity.type === 'communication' && !entity.metadata?.processedByExecutive )
+      return true
+  }
+
+  return pendingMessages.length > 0
+}
+
+export interface GatingDependencies {
+  generativeModel: GenerativeModel
+  pendingMessages: PendingMessage[]
+  hasPendingWork: boolean
+}
+
+export interface SalienceBufferEntry {
+  event: CognitiveEvent
+  tick: number
+}
+
+export interface GatingState {
+  executiveInterval: number
+  cooldownTicks: number
+  lastExecutiveTick: number
+  salienceBuffer: SalienceBufferEntry[]
+  goallessTickCount: number
+  lowValenceTickCount: number
+}
+
+export interface GatingResult {
+  shouldActivate: boolean
+  reason: string
+  /** Cleaned buffer with stale entries removed — caller must update GatingState. */
+  cleanedBuffer: SalienceBufferEntry[]
+}
+
+/**
+ * Full gating logic — pure function.
+ * Receives all state, returns decision + reason + cleaned buffer.
+ * The caller is responsible for updating GatingState with the result.
+ */
+export function evaluateGating(
+  state: ReadonlySimulationState,
+  tick: Tick,
+  deps: GatingDependencies,
+  gs: GatingState,
+): GatingResult {
+  // ── In-flight work check ──────────────────────────────────
+  if( deps.hasPendingWork )
+    return {
+      shouldActivate: false,
+      reason: 'hasPendingWork',
+      cleanedBuffer: gs.salienceBuffer
+    }
+
+  // ── Cooldown — always enforced ────────────────────────────
+  if( tick - gs.lastExecutiveTick < gs.cooldownTicks )
+    return {
+      shouldActivate: false,
+      reason: 'cooldown',
+      cleanedBuffer: gs.salienceBuffer
+    }
+
+  // ── Read metrics ──────────────────────────────────────────
+  const energy        = state.metrics.get('energy.level')       ?? 100
+  const isResting     = state.metrics.get('state.resting')      ?? 0
+  const isSleeping    = state.metrics.get('state.sleeping')     ?? 0
+  const isForcedRest  = state.metrics.get('state.forced_rest')  ?? 0
+  const novelty       = state.metrics.get('perception.novelty') ?? 0
+  const sleepPressure = state.metrics.get('sleep.pressure')     ?? 0
+  const stressLoad    = state.metrics.get('stress.load')        ?? 0
+  const valence       = state.metrics.get('affect.valence')     ?? 0
+
+  // ── Drop stale buffer entries ─────────────────────────────
+  const cleanedBuffer = gs.salienceBuffer.filter( e => tick - e.tick < BUFFER_MAX_AGE_TICKS )
+
+  // ── Accumulated workspace salience (GWT ignition pressure) ─
+  // Computed up-front so it both overrides prediction-gating at the interval
+  // boundary and drives the pre-interval early trigger further below.
+  const totalSalience   = cleanedBuffer.reduce( ( s, e ) => s + ( e.event.salience ?? 0 ), 0 )
+  const salienceCharged = totalSalience >= BUFFER_SALIENCE_TRIGGER
+
+  // ── Forced shutdown (energy < 1) ──────────────────────────
+  if( isForcedRest > 0 )
+    return {
+      shouldActivate: false,
+      reason: 'forced_rest',
+      cleanedBuffer
+    }
+
+  // ── Voluntary rest/sleep — wake on high novelty or pending instructions ─
+  if( isResting > 0 || isSleeping > 0 ){
+    const
+    significantEvent = novelty > 0.8,
+    hasPending = hasPendingInstructions( state, deps.pendingMessages )
+
+    if( significantEvent || hasPending )
+      return {
+        shouldActivate: true,
+        reason: `awakened_from_${isSleeping > 0 ? 'sleep' : 'rest'}`,
+        cleanedBuffer
+      }
+    
+    return {
+      shouldActivate: false,
+      reason: 'resting',
+      cleanedBuffer
+    }
+  }
+
+  // ── Count active goals ────────────────────────────────────
+  let activeGoalCount = 0
+  for( const entity of state.entities.values() )
+    if( entity.type === 'goal' && entity.metadata?.status === 'active')
+      activeGoalCount++
+
+  // ── Physiological crises — bypass executiveInterval ───────
+  if( sleepPressure > 65 )
+    return { shouldActivate: true, reason: 'sleep_pressure_critical', cleanedBuffer }
+  
+  if( stressLoad > 75 )
+    return { shouldActivate: true, reason: 'stress_overload', cleanedBuffer }
+  
+  if( energy < 15 )
+    return { shouldActivate: true, reason: 'energy_critical', cleanedBuffer }
+
+  // ── Pending messages — always fire ────────────────────────
+  if( deps.pendingMessages.length > 0 )
+    return { shouldActivate: true, reason: 'pending_message', cleanedBuffer }
+
+  // ── Normal interval scheduling ────────────────────────────
+  if( tick - gs.lastExecutiveTick >= gs.executiveInterval ){
+    // Prediction-error gating — uses GenerativeModel.observe() which returns { gated }
+    const energyErr  = deps.generativeModel.observe('energy.level', energy)
+    const stressErr  = deps.generativeModel.observe('stress.load', stressLoad)
+    const noveltyErr = deps.generativeModel.observe('perception.novelty', novelty)
+    const valenceErr = deps.generativeModel.observe('affect.valence', valence)
+
+    const allGated = energyErr.gated && stressErr.gated && noveltyErr.gated && valenceErr.gated
+    const overdue  = tick - gs.lastExecutiveTick >= gs.executiveInterval * 1.5
+
+    // A salience-charged workspace ignites even when every signal is well-predicted:
+    // accumulated salient coalitions are exactly what GWT ignition is meant to catch,
+    // so prediction-gating must not suppress them at the interval boundary.
+    if( allGated && !overdue && !salienceCharged )
+      return { shouldActivate: false, reason: 'prediction_gated', cleanedBuffer }
+
+    return {
+      shouldActivate: true,
+      reason: salienceCharged ? 'salience_charged' : 'interval_elapsed',
+      cleanedBuffer
+    }
+  }
+
+  // ── Salience competition — early trigger (pre-interval) ───
+  if( salienceCharged )
+    return { shouldActivate: true, reason: 'salience_charged', cleanedBuffer }
+
+  // ── Cognitive crises — early trigger ──────────────────────
+  // Counter values are computed here (the caller will persist them via updateGatingState)
+  const goallessTicks  = activeGoalCount === 0 ? gs.goallessTickCount + 1 : 0
+  const lowValenceTicks = valence < -0.4 ? gs.lowValenceTickCount + 1 : 0
+
+  if( goallessTicks > 20 )
+    return { shouldActivate: true, reason: 'goalless_crisis', cleanedBuffer }
+  
+  if( lowValenceTicks > 30 )
+    return { shouldActivate: true, reason: 'low_valence_crisis', cleanedBuffer }
+
+  // ── High novelty — early trigger ──────────────────────────
+  if( novelty > 0.7 )
+    return { shouldActivate: true, reason: 'high_novelty', cleanedBuffer }
+
+  return { shouldActivate: false, reason: 'no_trigger', cleanedBuffer }
+}
+
+/**
+ * Update the persistent gating state after a tick.
+ * Called every tick regardless of whether the executive activated.
+ */
+export function updateGatingState(
+  gs: GatingState,
+  state: ReadonlySimulationState,
+  _tick: Tick,
+  didActivate: boolean,
+  cleanedBuffer: SalienceBufferEntry[],
+): void {
+  // Apply cleaned buffer
+  gs.salienceBuffer = cleanedBuffer
+
+  // Update crisis counters
+  let activeGoalCount = 0
+  for( const entity of state.entities.values() )
+    if( entity.type === 'goal' && entity.metadata?.status === 'active' )
+      activeGoalCount++
+  
+  const valence = state.metrics.get('affect.valence') ?? 0
+
+  gs.goallessTickCount  = activeGoalCount === 0 ? gs.goallessTickCount + 1 : 0
+  gs.lowValenceTickCount = valence < -0.4 ? gs.lowValenceTickCount + 1 : 0
+
+  if( didActivate )
+    gs.lastExecutiveTick = _tick
+}

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

@@ -0,0 +1,6 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/index.ts
+// ─────────────────────────────────────────────────────────────
+
+export { ExecutiveEngine, effortTargetForActions } from '#faculties/executive.engine/engine'
+export type { ExecutiveEngineConfig, ExecutiveOutputFull } from '#faculties/executive.engine/types'

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

@@ -0,0 +1,102 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/messages.ts
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type { Tick, ReadonlySimulationState } from '#core/types'
+import type { PendingMessage } from '#faculties/executive.engine/types'
+
+/**
+ * Message queue state — tracks incoming communication entities,
+ * pending messages during in-flight LLM calls, and reply deduplication.
+ */
+export class MessageQueue {
+  /** Messages buffered while an LLM call is in-flight. */
+  pendingMessages: PendingMessage[] = []
+
+  /** Tick when the current (or most recent) LLM call started. */
+  pendingCallStartTick: number = -1
+
+  /** Entity IDs of communication entities that have been replied to this session. */
+  private _repliedEntityIds = new Set<string>()
+
+  /**
+   * Scan the simulation state for unprocessed communication entities
+   * and queue them into pendingMessages. Call every tick.
+   */
+  scanState( state: ReadonlySimulationState, tick: Tick ): void {
+    const seenIds = new Set( this.pendingMessages.map( m => m.id ) )
+
+    for( const [ id, entity ] of state.entities ){
+      if( entity.type !== 'communication' ) continue
+      if( entity.metadata?.processedByExecutive ) continue
+      if( seenIds.has( id ) ) continue
+
+      const msgTick = ( entity.metadata?.tick as number ) ?? 0
+      this.pendingMessages.push({
+        id,
+        content: (entity.metadata?.content as string) ?? '',
+        sender: (entity.metadata?.agentName as string) ?? 'unknown',
+        senderId: (entity.metadata?.keid as string) ?? 'unknown',
+        tick: msgTick
+      })
+
+      logger.info(`[executive] queued message from ${(entity.metadata?.agentName as string) ?? 'unknown'} (tick=${msgTick})`)
+    }
+  }
+
+  /**
+   * Clear messages that were included in the most recent LLM call.
+   * Any that arrived after the call started remain for the next cycle.
+   */
+  clearProcessedMessages(): void {
+    this.pendingMessages = this.pendingMessages.filter( m => m.tick > this.pendingCallStartTick )
+  }
+
+  /**
+   * Check if we've already replied to a specific communication entity this session.
+   */
+  hasRepliedTo( entityId: string ): boolean {
+    return this._repliedEntityIds.has( entityId )
+  }
+
+  /**
+   * Mark a communication entity as replied to.
+   */
+  markReplied( entityId: string ): void {
+    this._repliedEntityIds.add( entityId )
+  }
+
+  /**
+   * Build the set of communication entity IDs visible in state within the
+   * 30-tick window, plus any pending messages. Used to mark them as processed.
+   */
+  getVisibleMessageIds( state: ReadonlySimulationState, tick: Tick ): Set<string> {
+    const ids = new Set<string>( this.pendingMessages.map( m => m.id ) )
+    for( const [ id, entity ] of state.entities ){
+      if( entity.type !== 'communication' ) continue
+
+      const msgTick = (entity.metadata?.tick as number) ?? 0
+      if( tick - msgTick > 30 ) continue
+
+      ids.add( id )
+    }
+
+    return ids
+  }
+
+  /**
+   * Get stale communication entity IDs (>50 ticks old) for cleanup.
+   */
+  getStaleMessageIds( state: ReadonlySimulationState, tick: Tick ): string[] {
+    const stale: string[] = []
+    for( const [ id, entity ] of state.entities ){
+      if( entity.type !== 'communication' ) continue
+
+      const msgTick = (entity.metadata?.tick as number) ?? 0
+      tick - msgTick > 50 && stale.push( id )
+    }
+
+    return stale
+  }
+}