@mindot/will 0.1.1 → 0.3.0

package/src/mcp/server.ts

@@ -0,0 +1,144 @@
+// ─────────────────────────────────────────────────────────────
+// src/mcp/server.ts — a Will, exposed over the Model Context Protocol
+// ─────────────────────────────────────────────────────────────
+//
+// Lets any MCP client (Claude Desktop, Claude Code, an IDE) host a persistent
+// mind. The surface follows the same paradigm as the SDK facade: a Will is a
+// SUBJECT that emits projections, not a chatbot function —
+//
+//   • `perceive`        — deliver a stimulus into its sensory field
+//   • `next_utterance`  — await its next words (silence is a real outcome)
+//   • `state`           — read a snapshot of its inner life
+//   • `save`            — checkpoint the living mind to a PMA file
+//
+// plus read-only resources (`will://state`, `will://narrative`) for clients
+// that surface them. There is deliberately no `ask()`-shaped tool: you speak
+// TO the Will and observe what it projects; it may choose not to answer.
+//
+// One Will per server process. Boot/persistence/stdio wiring lives in cli.ts;
+// this module only maps an existing facade instance onto MCP (testable with
+// InMemoryTransport).
+// ─────────────────────────────────────────────────────────────
+
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import type { Will } from '#sdk/will'
+import { UtteranceTap } from '#root/host/utterances'
+
+export interface WillMcpOptions {
+  /** Where `save` (and the CLI's shutdown hibernate) writes the PMA artifact. */
+  pmaPath?: string
+}
+
+function serverVersion(): string {
+  // Same relative depth from src/mcp/ and dist/mcp/ — resolves in both.
+  try {
+    return JSON.parse( readFileSync( new URL( '../../package.json', import.meta.url ), 'utf8' ) ).version ?? '0.0.0'
+  }
+  catch { return '0.0.0' }
+}
+
+/**
+ * Map a running Will onto an MCP server. The caller owns the Will's lifecycle
+ * (boot, shutdown) and the transport; this only registers the surface.
+ */
+export function buildWillMcpServer( will: Will, opts: WillMcpOptions = {} ): McpServer {
+  const server = new McpServer( { name: 'mindot-will', version: serverVersion() } )
+
+  // MCP calls are separate round trips: the Will may speak BETWEEN a perceive
+  // call and the next_utterance call that follows. The tap buffers projections
+  // so a fast reply is not lost in the gap (see host/utterances.ts).
+  const tap = new UtteranceTap( will )
+
+  // ── Tools ─────────────────────────────────────────────────
+
+  server.registerTool( 'perceive', {
+    title: 'Perceive',
+    description:
+      `Deliver a stimulus (something said or observed) into ${ will.name }'s sensory field. ` +
+      `${ will.name } is a living mind, not a chatbot: this returns once the stimulus is delivered, ` +
+      `NOT when it has responded. Its response — if it chooses to give one — arrives as its next ` +
+      `utterance (use the next_utterance tool). Staying silent is a valid choice, not an error.`,
+    inputSchema: {
+      text:    z.string().describe( 'What is said or observed.' ),
+      from:    z.string().optional().describe( "Who it's from (entity id, default 'user'). Use a stable id per person." ),
+      speaker: z.string().optional().describe( 'Display name of the speaker.' ),
+    },
+  }, async ( { text, from, speaker } ) => {
+    await will.perceive( { text, ...( from ? { from } : {} ), ...( speaker ? { speaker } : {} ) } )
+    return {
+      content: [ {
+        type: 'text',
+        text: `Delivered into ${ will.name }'s sensory field at tick ${ will.state().tick }. ` +
+              `It may respond in its next utterance — or stay silent.`,
+      } ],
+    }
+  } )
+
+  server.registerTool( 'next_utterance', {
+    title: 'Next utterance',
+    description:
+      `Await ${ will.name }'s next spontaneous utterance. Returns what it says next, or reports ` +
+      `that it chose silence within the wait window — silence is a real outcome, not a failure. ` +
+      `Call after perceive to hear the response, or on its own to listen for unprompted speech.`,
+    inputSchema: {
+      within_ms: z.number().optional().describe( 'How long to wait before accepting silence (default 15000, max 120000).' ),
+      from:      z.string().optional().describe( 'Only accept an utterance addressed to this entity id.' ),
+    },
+  }, async ( { within_ms, from } ) => {
+    const within = Math.min( Math.max( within_ms ?? 15_000, 100 ), 120_000 )
+    const msg    = await tap.next( within, from )
+    if( msg )
+      return { content: [ { type: 'text', text: `${ will.name } says (to ${ msg.to }): ${ msg.content }` } ] }
+    return {
+      content: [ {
+        type: 'text',
+        text: `${ will.name } stayed silent (waited ${ within }ms). That is a choice, not an error — ` +
+              `it may be occupied with its own thoughts, or simply have nothing to say.`,
+      } ],
+    }
+  } )
+
+  server.registerTool( 'state', {
+    title: 'Inner state',
+    description:
+      `Read a snapshot of ${ will.name }'s current inner life: tick, body/affect metrics ` +
+      `(energy, stress, valence, arousal), active goals, beliefs, and self-narrative. ` +
+      `Read-only; observing does not disturb it.`,
+    inputSchema: {},
+  }, async () => (
+    { content: [ { type: 'text', text: JSON.stringify( will.state(), null, 2 ) } ] }
+  ) )
+
+  server.registerTool( 'save', {
+    title: 'Save (checkpoint)',
+    description:
+      `Checkpoint ${ will.name } into a portable PMA artifact on disk — non-destructive, it keeps ` +
+      `living. The artifact restores the same self (identity, memories, relationships, learned ` +
+      `skills) when the server next starts.`,
+    inputSchema: {},
+  }, async () => {
+    if( !opts.pmaPath )
+      return { content: [ { type: 'text', text: 'No PMA path configured — set WILL_PMA_PATH.' } ], isError: true }
+    const pma = await will.save()
+    mkdirSync( dirname( opts.pmaPath ), { recursive: true } )
+    writeFileSync( opts.pmaPath, JSON.stringify( pma ) )
+    return { content: [ { type: 'text', text: `${ will.name } checkpointed to ${ opts.pmaPath } (still living).` } ] }
+  } )
+
+  // ── Resources (read-only projections) ─────────────────────
+
+  server.registerResource( 'state', 'will://state',
+    { title: `${ will.name } — inner state`, description: 'Live snapshot of the mind: metrics, goals, beliefs, narrative.', mimeType: 'application/json' },
+    async uri => ( { contents: [ { uri: uri.href, mimeType: 'application/json', text: JSON.stringify( will.state(), null, 2 ) } ] } ),
+  )
+
+  server.registerResource( 'narrative', 'will://narrative',
+    { title: `${ will.name } — self-narrative`, description: 'The story the mind currently tells about itself.', mimeType: 'text/plain' },
+    async uri => ( { contents: [ { uri: uri.href, mimeType: 'text/plain', text: will.state().narrative || '(no narrative formed yet)' } ] } ),
+  )
+
+  return server
+}

package/src/sdk/will.ts

@@ -9,8 +9,14 @@
 //   const will = await Will.create({ name: 'Aria', identity: {...} })
 //   will.on('message', m => console.log(m.content))
 //   will.effector('search_docs', async a => await myDb.search(a.query))
-//   await will.say('What should we work on today?')
-//   const pma = await will.hibernate()          // Will.wake(pma) later
+//   await will.perceive({ from: 'ada', text: 'What should we work on?' })
+//   const reply = await will.nextUtterance({ to: 'ada' })   // WillMessage | null
+//   const pma = await will.save()               // non-destructive; keeps ticking
+//
+// A Will is a *subject*, not a function: you `perceive` stimuli to it and observe
+// its *projections* (message / effector / emotion / state) — you never `await`
+// a computed return. `nextUtterance` is a thin, honest adapter for callers that
+// want a reply-shaped await; `null` means the Will chose silence, not an error.
 //
 // Everything under here already existed; the facade hides the plumbing:
 //   • one message → outbox drain → delivery-ack, surfaced as an event;
@@ -25,9 +31,27 @@ import { WillStem } from '#stem/index'
 import type { WillConfig, WillIdentity, EngineTier, ModelTier, InitialGoal } from '#stem/mind'
 import type { PMASnapshot } from '#pma/index'
 import type { effectorInvocation } from '#types'
+import type { EffectorDeclaration, SchemaPrecondition } from '#agency/types'
 
 // ── Public surface ────────────────────────────────────────────
 
+/**
+ * A stimulus entering the Will's sensory field. A Will is a subject, not a
+ * function: you don't *call* it with input and await a return — you `perceive`
+ * something to it, and it *may* project a response later (see `nextUtterance`),
+ * coloured by its current state. Silence is a valid, meaningful outcome.
+ */
+export interface Stimulus {
+  /** What was said / observed. */
+  text: string
+  /** Who it's from (entity id). Default 'user'. */
+  from?: string
+  /** Display name of the speaker. Default 'You' for `user`, else the `from` id. */
+  speaker?: string
+  /** Conversation/thread id (default = `from`). */
+  thread?: string
+}
+
 /** A message the Will emitted to someone. */
 export interface WillMessage {
   /** Message id (stable — dedupe on it). */
@@ -38,6 +62,28 @@ export interface WillMessage {
   to: string
 }
 
+/**
+ * A motor act the Will *chose* to enact — a projection of its agency, surfaced
+ * whether or not you registered a handler for it. (When you did, the handler
+ * still runs and its outcome feeds reafference.)
+ */
+export interface WillEffectorAct {
+  /** The effector the Will selected. */
+  name: string
+  /** The arguments it bound. */
+  args: Record<string, unknown>
+  /** Its stated reason for the act. */
+  reasoning: string
+  /** Bound target entity, when the act binds one. */
+  to?: string
+}
+
+/** The Will's affect, projected when it shifts. Valence/arousal ∈ −1..1. */
+export interface WillAffect {
+  valence: number
+  arousal: number
+}
+
 /**
  * The result of an effector your handler ran. Return a bare string as shorthand
  * for `{ success: true, description }`. `metrics` optionally writes world state
@@ -52,9 +98,45 @@ export type EffectorResult = string | {
 /** Your implementation of an ability the Will can choose to use. */
 export type EffectorHandler = (
   args: Record<string, unknown>,
-  ctx: { reasoning: string; targetEntityId?: string },
+  ctx: { reasoning: string; targetEntityId?: string; description?: string },
 ) => EffectorResult | Promise<EffectorResult>
 
+/**
+ * A richer effector declaration — the ability seeded as a *learnable affordance*.
+ * `description` is its meaning (carried to perception + your handler); `cost`,
+ * `valence`, and `preconditions` are the intrinsic priors the mind starts from,
+ * refined by reafference through use. Args still bind from the situation — this
+ * is not a tool-call parameter form. Declare rich effectors in `create()`'s
+ * `effectors` map (that is where they enter the affordance repertoire).
+ */
+export interface EffectorSpec {
+  /** What the ability is for. */
+  description?: string
+  /** Intrinsic effort / energy demand 0..1 (default 0.15). */
+  cost?: number
+  /** Intrinsic reward prior −1..1 the mind expects before learning (default 0). */
+  valence?: number
+  /** Body-state gates; the ability is unavailable unless all pass. */
+  preconditions?: SchemaPrecondition[]
+  /**
+   * Whether the ability targets a specific perceived target (default 'none').
+   * 'entity' directs it at a known person, 'object' at a known thing; the bound
+   * target arrives as `ctx.targetEntityId`.
+   */
+  binds?: 'none' | 'entity' | 'object'
+  /**
+   * Routing tags (merged with 'external'/'host'). A drive-recognised tag (e.g.
+   * 'social', 'nourishment') lets a homeostatic drive lift this ability when it
+   * presses.
+   */
+  tags?: string[]
+  /** Your implementation. */
+  handler: EffectorHandler
+}
+
+/** An effectors-map value: a bare handler, or a spec carrying meaning + priors. */
+export type EffectorEntry = EffectorHandler | EffectorSpec
+
 /** A compact read of the mind's current inner state. */
 export interface WillStateSummary {
   tick: number
@@ -84,8 +166,13 @@ export interface CreateWillOptions {
    * (needs ANTHROPIC_API_KEY / WILL_LLM_* env). Omit to auto-detect.
    */
   llm?: 'mock' | 'anthropic'
-  /** Abilities the Will can choose to enact. name → your handler. */
-  effectors?: Record<string, EffectorHandler>
+  /**
+   * Abilities the Will can choose to enact. `name → handler`, or
+   * `name → { handler, description?, cost?, valence?, preconditions? }` to seed
+   * the ability with meaning + intrinsic priors (see EffectorSpec). Declared
+   * here (create time) so they enter the affordance repertoire.
+   */
+  effectors?: Record<string, EffectorEntry>
   /** Goals seeded before the first tick. Usually leave empty — the Will forms its own. */
   initialGoals?: InitialGoal[]
   /** Persist snapshots to disk across restarts (default false). */
@@ -98,7 +185,18 @@ export interface CreateWillOptions {
   id?: string
 }
 
-type WillEvent = 'message' | 'state' | 'error'
+type WillEvent = 'message' | 'state' | 'effector' | 'emotion' | 'error'
+
+/** A caller awaiting the Will's next spontaneous utterance (see nextUtterance). */
+interface UtteranceWaiter {
+  /** Only resolve on an utterance addressed to this entity, when set. */
+  to?: string
+  resolve: ( m: WillMessage | null ) => void
+  timer:   ReturnType<typeof setTimeout>
+}
+
+/** Affect must move at least this far (−1..1) before another `emotion` projection. */
+const AFFECT_EPSILON = 0.02
 
 // ── The facade ────────────────────────────────────────────────
 
@@ -110,9 +208,15 @@ export class Will {
   readonly name: string
 
   private readonly _effectors = new Map<string, EffectorHandler>()
-  private readonly _messageHandlers = new Set<( m: WillMessage ) => void>()
-  private readonly _stateHandlers = new Set<( s: WillStateSummary ) => void>()
-  private readonly _errorHandlers = new Set<( e: Error ) => void>()
+  /** Rich declarations for create-time effectors → seed the affordance repertoire. */
+  private readonly _effectorDecls = new Map<string, EffectorDeclaration>()
+  private readonly _messageHandlers  = new Set<( m: WillMessage ) => void>()
+  private readonly _stateHandlers    = new Set<( s: WillStateSummary ) => void>()
+  private readonly _effectorHandlers = new Set<( a: WillEffectorAct ) => void>()
+  private readonly _emotionHandlers  = new Set<( a: WillAffect ) => void>()
+  private readonly _errorHandlers    = new Set<( e: Error ) => void>()
+  private readonly _utteranceWaiters = new Set<UtteranceWaiter>()
+  private _lastAffect: WillAffect | null = null
   private _unsub: ( () => void ) | null = null
 
   private constructor( stem: WillStem, id: string, name: string ){
@@ -127,8 +231,8 @@ export class Will {
     const stem = new WillStem()
     const will = new Will( stem, id, opts.name )
 
-    for( const [ name, handler ] of Object.entries( opts.effectors ?? {} ) )
-      will._effectors.set( name, handler )
+    for( const [ name, entry ] of Object.entries( opts.effectors ?? {} ) )
+      will._register( name, entry )
 
     await stem.createWill( will._buildConfig( id, opts ) )
     will._attach()
@@ -148,8 +252,8 @@ export class Will {
     const stem = new WillStem()
     const will = new Will( stem, id, opts.name )
 
-    for( const [ name, handler ] of Object.entries( opts.effectors ?? {} ) )
-      will._effectors.set( name, handler )
+    for( const [ name, entry ] of Object.entries( opts.effectors ?? {} ) )
+      will._register( name, entry )
 
     await stem.createWill(
       will._buildConfig( id, { ...opts, identity: { prompt: '', ...opts.identity } } ),
@@ -161,38 +265,107 @@ export class Will {
     return will
   }
 
-  // ── Talking ────────────────────────────────────────────────
+  // ── Perceiving ─────────────────────────────────────────────
 
   /**
-   * Speak to the Will as the default user. The reply is asynchronous — it
-   * arrives on the `message` event once the Will has reasoned about it.
+   * Deliver a stimulus into the Will's sensory field. This is the one true
+   * intake — `say`/`tell` are sugar over it. It returns once the stimulus is
+   * *delivered*, NOT once the Will has responded: a response (if any) is a
+   * projection that arrives later on the `message` event, or via
+   * `nextUtterance()`. The Will may also stay silent — that is not an error.
    */
+  async perceive( stimulus: Stimulus ): Promise<void> {
+    const from = stimulus.from ?? 'user'
+    await this.stem.ingestText( this.id, {
+      kind:        'text',
+      entityId:    from,
+      threadId:    stimulus.thread ?? from,
+      content:     stimulus.text,
+      speakerName: stimulus.speaker ?? ( from === 'user' ? 'You' : from ),
+    } )
+  }
+
+  /** Perceive from the default user. Sugar over `perceive`. */
   async say( text: string ): Promise<void> {
-    return this.tell( 'user', 'You', text )
+    return this.perceive( { text, from: 'user', speaker: 'You' } )
   }
 
-  /** Speak as a specific interlocutor (multi-party conversations). */
+  /** Perceive from a specific interlocutor (multi-party). Sugar over `perceive`. */
   async tell( entityId: string, speakerName: string, text: string ): Promise<void> {
-    await this.stem.ingestText( this.id, {
-      kind: 'text', entityId, threadId: entityId, content: text, speakerName,
+    return this.perceive( { text, from: entityId, speaker: speakerName } )
+  }
+
+  /**
+   * Await the Will's *next spontaneous utterance* — a thin, honest adapter over
+   * the `message` projection stream for request/response callers. Resolves with
+   * the message, or `null` if the Will stays silent within `within` ms (default
+   * 5000). `null` is a real outcome — the Will chose not to speak — not a
+   * failure. Pass `to` to only accept an utterance addressed to that entity.
+   *
+   *   await will.perceive( { from: 'ada', text: 'Hi!' } )
+   *   const reply = await will.nextUtterance( { to: 'ada', within: 3000 } )
+   *   // reply is a WillMessage, or null if Ada got the silent treatment.
+   */
+  nextUtterance( opts: { within?: number; to?: string } = {} ): Promise<WillMessage | null> {
+    return new Promise<WillMessage | null>( resolve => {
+      const timer = setTimeout( () => {
+        this._utteranceWaiters.delete( waiter )
+        resolve( null )
+      }, opts.within ?? 5000 )
+      // Don't let a pending wait keep the host process alive.
+      ;( timer as { unref?: () => void } ).unref?.()
+      const waiter: UtteranceWaiter = { to: opts.to, resolve, timer }
+      this._utteranceWaiters.add( waiter )
     } )
   }
 
   // ── Abilities ──────────────────────────────────────────────
 
   /**
-   * Register an ability the Will can choose to enact. When the Will decides to
-   * use `name`, your handler runs with the arguments it chose; the return value
-   * is fed back as the outcome (closing the reafference loop that lets the Will
-   * learn the ability). Registering makes the effector available immediately.
+   * Register an ability the Will can choose to enact, at runtime. `entry` is a
+   * bare handler or a full spec (`{ handler, description?, cost?, valence?,
+   * preconditions?, binds?, tags? }`). When the Will decides to use `name`, your
+   * handler runs with the arguments it chose; the return value feeds back as the
+   * outcome (the reafference loop that lets the Will learn the ability).
+   *
+   * The ability's schema is added to the live repertoire so it can actually be
+   * *afforded* immediately (a grant alone only gates), then granted. Note: this
+   * is a runtime mutation — the deterministic/replayable path is declaring
+   * effectors in `create()`'s `effectors` map.
    */
-  effector( name: string, handler: EffectorHandler ): this {
-    this._effectors.set( name, handler )
-    // Communication effectors + every registered custom name.
+  effector( name: string, entry: EffectorEntry ): this {
+    this._register( name, entry )
+    // Add its schema to the live repertoire (so it can be perceived + enacted),
+    // then grant it. Comms names are no-ops in registerEffector (grant-governed).
+    this.stem.registerEffector( this.id, this._effectorDecls.get( name )! )
     this.stem.setAllowedEffectors( this.id, [ ...COMMUNICATION, ...this._effectors.keys() ] )
     return this
   }
 
+  /** Split an effectors-map entry into a handler + an EffectorDeclaration. */
+  private _register( name: string, entry: EffectorEntry ): void {
+    if( typeof entry === 'function' ){
+      this._effectors.set( name, entry )
+      this._effectorDecls.set( name, name )          // bare name — uniform prior
+      return
+    }
+    this._effectors.set( name, entry.handler )
+    const hasMeta = entry.description !== undefined || entry.cost !== undefined
+      || entry.valence !== undefined || entry.preconditions !== undefined
+      || entry.binds !== undefined || entry.tags !== undefined
+    this._effectorDecls.set( name, hasMeta
+      ? {
+          name,
+          ...( entry.description   !== undefined ? { description:   entry.description   } : {} ),
+          ...( entry.cost          !== undefined ? { cost:          entry.cost          } : {} ),
+          ...( entry.valence       !== undefined ? { valence:       entry.valence       } : {} ),
+          ...( entry.preconditions !== undefined ? { preconditions: entry.preconditions } : {} ),
+          ...( entry.binds         !== undefined ? { binds:         entry.binds         } : {} ),
+          ...( entry.tags          !== undefined ? { tags:          entry.tags          } : {} ),
+        }
+      : name )
+  }
+
   // ── Introspection ──────────────────────────────────────────
 
   /** A compact snapshot of the mind's current inner state. */
@@ -215,13 +388,19 @@ export class Will {
 
   // ── Events ─────────────────────────────────────────────────
 
-  on( event: 'message', handler: ( m: WillMessage ) => void ): this
-  on( event: 'state',   handler: ( s: WillStateSummary ) => void ): this
-  on( event: 'error',   handler: ( e: Error ) => void ): this
+  on( event: 'message',  handler: ( m: WillMessage ) => void ): this
+  on( event: 'state',    handler: ( s: WillStateSummary ) => void ): this
+  on( event: 'effector', handler: ( a: WillEffectorAct ) => void ): this
+  on( event: 'emotion',  handler: ( a: WillAffect ) => void ): this
+  on( event: 'error',    handler: ( e: Error ) => void ): this
   on( event: WillEvent, handler: ( arg: never ) => void ): this {
-    if( event === 'message' ) this._messageHandlers.add( handler as ( m: WillMessage ) => void )
-    else if( event === 'state' ) this._stateHandlers.add( handler as ( s: WillStateSummary ) => void )
-    else this._errorHandlers.add( handler as ( e: Error ) => void )
+    switch( event ){
+      case 'message':  this._messageHandlers.add(  handler as ( m: WillMessage ) => void ); break
+      case 'state':    this._stateHandlers.add(    handler as ( s: WillStateSummary ) => void ); break
+      case 'effector': this._effectorHandlers.add( handler as ( a: WillEffectorAct ) => void ); break
+      case 'emotion':  this._emotionHandlers.add(  handler as ( a: WillAffect ) => void ); break
+      default:         this._errorHandlers.add(    handler as ( e: Error ) => void )
+    }
     return this
   }
 
@@ -231,9 +410,19 @@ export class Will {
   resume(): void { this.stem.resumeWill( this.id ) }
 
   /**
-   * Distil the mind into a portable PMA artifact and archive it. The returned
-   * snapshot restores the same self via `Will.wake()` — across a restart, a
-   * fork, or a machine boundary.
+   * Checkpoint the living mind into a portable PMA artifact — NON-destructive.
+   * The Will keeps ticking; the snapshot is a point-in-time copy you can archive
+   * or wake elsewhere. Use this for periodic saves; use `hibernate()` to sleep.
+   */
+  async save(): Promise<PMASnapshot> {
+    return this.stem.distillPMA( this.id )
+  }
+
+  /**
+   * Distil the mind into a portable PMA artifact and archive it — DESTRUCTIVE:
+   * the tick loop stops (the Will sleeps). The returned snapshot restores the
+   * same self via `Will.wake()` — across a restart, a fork, or a machine
+   * boundary. For a copy that leaves the Will running, use `save()`.
    */
   async hibernate(): Promise<PMASnapshot> {
     const pma = this.stem.distillPMA( this.id )
@@ -243,6 +432,9 @@ export class Will {
 
   /** Tear the Will down (its tick loop stops; state is discarded unless persisted). */
   async stop(): Promise<void> {
+    // Resolve anyone awaiting an utterance — the Will won't speak again.
+    for( const w of this._utteranceWaiters ){ clearTimeout( w.timer ); w.resolve( null ) }
+    this._utteranceWaiters.clear()
     this._unsub?.()
     this._unsub = null
     await this.stem.archiveWill( this.id )
@@ -266,7 +458,7 @@ export class Will {
       persistentMemory: opts.persist ?? false,
       snapshotInterval: 100,
       tickIntervalMs:   opts.tickMs ?? 1000,
-      allowedGenericEffectors: [ ...COMMUNICATION, ...this._effectors.keys() ],
+      allowedGenericEffectors: [ ...COMMUNICATION, ...this._effectorDecls.values() ],
       initialGoals: opts.initialGoals ?? [],
       ...( opts.seed !== undefined ? { randomSeed: opts.seed, clock: { fixedDeltaMs: 1000, startTime: 0 } } : {} ),
     }
@@ -280,14 +472,22 @@ export class Will {
         this._emitMessage( { id: msg.id, content: msg.content, to: msg.targetEntityId } )
         try { this.stem.confirmMessageDelivery( this.id, msg.id, true ) } catch { /* best-effort */ }
       }
-      // Effector invocations → run the handler → execution-ack.
-      for( const inv of invocations )
+      // Effector invocations → project the motor act, then run the handler → ack.
+      for( const inv of invocations ){
+        this._emitEffectorAct( { name: inv.effectorName, args: inv.parameters, reasoning: inv.reasoning, to: inv.targetEntityId } )
         void this._runEffector( inv )
+      }
 
-      // State subscribers (only when someone is listening — state() is cheap but not free).
-      if( this._stateHandlers.size > 0 ){
-        const s = this.state()
-        for( const h of this._stateHandlers ) try { h( s ) } catch { /* isolate */ }
+      // Projections that read the state summary — compute it once, and only when
+      // something is actually observing (state() is cheap but not free). Isolated
+      // so a transient read error can never stall the tick loop.
+      if( this._stateHandlers.size > 0 || this._emotionHandlers.size > 0 ){
+        try {
+          const s = this.state()
+          for( const h of this._stateHandlers ) try { h( s ) } catch { /* isolate */ }
+          if( this._emotionHandlers.size > 0 ) this._maybeEmitAffect( s.metrics.valence, s.metrics.arousal )
+        }
+        catch( e ){ this._emitError( e as Error ) }
       }
     } ) ?? null
   }
@@ -304,7 +504,11 @@ export class Will {
     }
 
     try {
-      const raw = await handler( inv.parameters, { reasoning: inv.reasoning, targetEntityId: inv.targetEntityId } )
+      const raw = await handler( inv.parameters, {
+        reasoning: inv.reasoning,
+        targetEntityId: inv.targetEntityId,
+        ...( inv.description ? { description: inv.description } : {} ),
+      } )
       const result = typeof raw === 'string' ? { success: true, description: raw } : raw
       this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, result )
     }
@@ -318,6 +522,27 @@ export class Will {
 
   private _emitMessage( m: WillMessage ): void {
     for( const h of this._messageHandlers ) try { h( m ) } catch( e ){ this._emitError( e as Error ) }
+    // Wake any nextUtterance() awaiter this message satisfies.
+    if( this._utteranceWaiters.size > 0 ){
+      for( const w of [ ...this._utteranceWaiters ] ){
+        if( w.to !== undefined && w.to !== m.to ) continue
+        clearTimeout( w.timer )
+        this._utteranceWaiters.delete( w )
+        w.resolve( m )
+      }
+    }
+  }
+  private _emitEffectorAct( a: WillEffectorAct ): void {
+    for( const h of this._effectorHandlers ) try { h( a ) } catch( e ){ this._emitError( e as Error ) }
+  }
+  private _maybeEmitAffect( valence: number, arousal: number ): void {
+    const last = this._lastAffect
+    // Emit on the first read, then only when affect moves past the epsilon.
+    if( last
+      && Math.abs( last.valence - valence ) < AFFECT_EPSILON
+      && Math.abs( last.arousal - arousal ) < AFFECT_EPSILON ) return
+    this._lastAffect = { valence, arousal }
+    for( const h of this._emotionHandlers ) try { h( { valence, arousal } ) } catch( e ){ this._emitError( e as Error ) }
   }
   private _emitError( e: Error ): void {
     for( const h of this._errorHandlers ) try { h( e ) } catch { /* nowhere left to go */ }