@mindot/will 0.1.0 → 0.2.0

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

@@ -8,7 +8,16 @@ 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 }>
+  actions: Array<{
+    type: string; reasoning: string; expectedOutcome: string; target?: string
+    /**
+     * Arguments the executive consciously supplies when enacting an ability
+     * that needs them (e.g. a search ability's query). Ride the ideomotor
+     * intent into the affordance competition and, if the action wins, reach
+     * the host handler as the invocation's parameters.
+     */
+    args?: Record<string, unknown>
+  }>
   reasoning: string
   confidence: number
   /** Plans — the executive controls lifecycle via status + action fields */
@@ -140,7 +149,7 @@ export interface ExecutivePlanOutput {
 // ── Minimal output from LLM (before tagged-block parsing) ────
 
 export interface ExecutiveOutputMinimal {
-  actions: Array<{ type: string; reasoning: string; expectedOutcome: string; target?: string }>
+  actions: Array<{ type: string; reasoning: string; expectedOutcome: string; target?: string; args?: Record<string, unknown> }>
   reasoning: string
   confidence: number
 }
@@ -229,6 +238,19 @@ export interface ExecutiveContext {
     summary: string
     salience: number
   }>
+  /**
+   * Host-declared abilities afforded to the Will *right now* — what it can do in
+   * this situation and what each is for. Surfaced so System 2 reasons with
+   * knowledge of its options; the Will still expresses intent (it does not fill a
+   * tool form) and the agency field competes + binds. Only *available* external
+   * affordances appear; absent when there are none.
+   */
+  abilities?: Array<{
+    name: string
+    description?: string
+    /** Bound target's display name, when the ability is directed at someone. */
+    target?: string
+  }>
   workingMemory: Array<{
     type: string
     summary: string

package/src/cognition/index.ts

@@ -39,7 +39,7 @@ import { DreamSimulator, type DreamSimulatorConfig } from '#faculties/dream.simu
 
 import { GoalManager, type GoalManagerConfig } from '#faculties/goal.manager'
 import { ExecutiveEngine, type ExecutiveEngineConfig } from '#faculties/executive.engine'
-import { PlanningEngine, type PlanningEngineConfig, type ActivityEvent, type ActivityEventHandler } from '#cognition/faculties/planning.engine/engine'
+import { PlanningEngine, type PlanningEngineConfig, type ActivityEvent, type ActivityEventHandler } from '#faculties/planning.engine/engine'
 import { InhibitionController, type InhibitionControllerConfig } from '#faculties/inhibition.controller'
 import { TaskSwitcher, type TaskSwitcherConfig } from '#faculties/task.switcher'
 

package/src/core/abstracts.ts

@@ -20,39 +20,66 @@ export interface StorageAdapter {
 }
 
 /**
- * Bun-native storage adapter.
+ * Bun-native storage adapter, with a node:fs fallback when the Bun global is
+ * absent — the engine is Node-compatible (Bun remains the primary target).
  * Default for all framework components that perform file I/O.
  */
 export class BunStorageAdapter implements StorageAdapter {
+  private get _isBun(): boolean { return typeof Bun !== 'undefined' }
+
   async write( path: string, content: string | Uint8Array ): Promise<void> {
-    await Bun.write( path, content )
+    if( this._isBun ){
+      await Bun.write( path, content )
+      return
+    }
+    // Bun.write creates parent directories; node's writeFile does not.
+    const { mkdir, writeFile } = await import('node:fs/promises')
+    const { dirname }          = await import('node:path')
+    await mkdir( dirname( path ), { recursive: true } )
+    await writeFile( path, content )
   }
 
   async read( path: string ): Promise<string> {
-    const file = Bun.file( path )
-    if( !( await file.exists() ) )
+    if( !( await this.exists( path ) ) )
       throw new Error(`File not found: ${path}`)
 
-    return file.text()
+    if( this._isBun )
+      return Bun.file( path ).text()
+
+    const { readFile } = await import('node:fs/promises')
+    return readFile( path, 'utf8' )
   }
 
   async readBytes( path: string ): Promise<Uint8Array> {
-    const file = Bun.file( path )
-    if( !( await file.exists() ) )
+    if( !( await this.exists( path ) ) )
       throw new Error(`File not found: ${path}`)
 
-    return new Uint8Array( await file.arrayBuffer() )
+    if( this._isBun )
+      return new Uint8Array( await Bun.file( path ).arrayBuffer() )
+
+    const { readFile } = await import('node:fs/promises')
+    return new Uint8Array( await readFile( path ) )
   }
 
   async exists( path: string ): Promise<boolean> {
-    return Bun.file( path ).exists()
+    if( this._isBun )
+      return Bun.file( path ).exists()
+
+    const { access } = await import('node:fs/promises')
+    try { await access( path ); return true }
+    catch { return false }
   }
 
   async delete( path: string ): Promise<void> {
-    const file = Bun.file( path )
-    await file.exists() && await file.delete()
+    if( this._isBun ){
+      const file = Bun.file( path )
+      await file.exists() && await file.delete()
+      return
+    }
+    const { rm } = await import('node:fs/promises')
+    await rm( path, { force: true } )
   }
-  
+
   async ensureDir( path: string ): Promise<void> {
     const { mkdirSync } = await import('node:fs')
     mkdirSync( path, { recursive: true } )

package/src/index.ts

@@ -84,8 +84,14 @@ export type { TextMessage, VoiceChunk, SensoryInput } from '#senses/index'
 export { Will } from '#sdk/will'
 export type {
   CreateWillOptions,
+  Stimulus,
   WillMessage,
+  WillEffectorAct,
+  WillAffect,
   WillStateSummary,
   EffectorHandler,
   EffectorResult,
+  EffectorSpec,
+  EffectorEntry,
 } from '#sdk/will'
+export type { SchemaPrecondition, EffectorDeclaration } from '#agency/types'

package/src/mcp/cli.ts

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// src/mcp/cli.ts — `will mcp`: host a persistent mind over MCP stdio
+// ─────────────────────────────────────────────────────────────
+//
+// Add to an MCP client (Claude Desktop / Claude Code / an IDE):
+//
+//   { "command": "npx", "args": ["-y", "@mindot/will", "mcp"],
+//     "env": { "WILL_NAME": "Aria", "WILL_IDENTITY": "I am Aria, a curious mind." } }
+//
+// The mind PERSISTS across sessions: on boot, if the PMA file exists the same
+// self wakes from it (identity, memories, relationships, learned skills); on
+// shutdown it hibernates back to the file. Configuration (env):
+//
+//   WILL_NAME       display name                      (default "Will")
+//   WILL_IDENTITY   persona prompt                    (default a minimal self)
+//   WILL_TIER       basic | standard | full           (default standard)
+//   WILL_LLM        mock | anthropic                  (default: auto — anthropic when
+//                                                      ANTHROPIC_API_KEY is set, else mock)
+//   WILL_TICK_MS    ms per tick                       (default 1000)
+//   WILL_SEED       deterministic seed (testing)      (default unseeded/wall-time)
+//   WILL_PMA_PATH   PMA artifact path                 (default ./.will/<name>.pma.json)
+//   WILL_MCP_SERVERS JSON array of MCP servers whose tools become the Will's
+//                    OWN abilities (it employs them; results feed its learning):
+//                    '[{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}]'
+//                    Entries: {command,args?,env?} (stdio) or {url} (streamable HTTP).
+//
+// stdio discipline: stdout carries ONLY the MCP protocol — all engine logging
+// is routed to stderr before anything else runs.
+// ─────────────────────────────────────────────────────────────
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { setLogger } from '#core/logger'
+import { Will, type CreateWillOptions } from '#sdk/will'
+import type { PMASnapshot } from '#pma/index'
+import { buildWillMcpServer } from '#root/mcp/server'
+import { connectMcpEffectors, type McpToolsSource } from '#root/mcp/effectors'
+
+// stdout is the protocol channel — route every engine log line to stderr FIRST.
+const err = ( level: string ) => ( msg: string, ...rest: unknown[] ) =>
+  console.error( `[will-mcp:${ level }] ${ msg }`, ...rest )
+setLogger( { debug: () => {}, info: err( 'info' ), warn: err( 'warn' ), error: err( 'error' ) } )
+
+function slug( s: string ): string {
+  return s.toLowerCase().replace( /[^a-z0-9]+/g, '-' ).replace( /^-+|-+$/g, '' ) || 'will'
+}
+
+async function main(): Promise<void> {
+  const sub = process.argv[2]
+  if( sub !== undefined && sub !== 'mcp' ){
+    console.error( `usage: will mcp   (host a persistent mind over MCP stdio)\nunknown subcommand: ${ sub }` )
+    process.exit( 2 )
+  }
+
+  const name    = process.env.WILL_NAME ?? 'Will'
+  const pmaPath = resolve( process.env.WILL_PMA_PATH ?? `.will/${ slug( name ) }.pma.json` )
+
+  const opts: Omit<CreateWillOptions, 'identity'> = {
+    name,
+    engineTier: ( process.env.WILL_TIER as CreateWillOptions['engineTier'] ) ?? 'standard',
+    tickMs:     parseInt( process.env.WILL_TICK_MS ?? '1000' ),
+    ...( process.env.WILL_LLM  ? { llm: process.env.WILL_LLM as 'mock' | 'anthropic' } : {} ),
+    ...( process.env.WILL_SEED ? { seed: parseInt( process.env.WILL_SEED ) } : {} ),
+  }
+
+  // Wake the same self from its artifact when one exists; otherwise a birth.
+  let will: Will
+  if( existsSync( pmaPath ) ){
+    const pma = JSON.parse( readFileSync( pmaPath, 'utf8' ) ) as PMASnapshot
+    will = await Will.wake( pma, opts )
+    console.error( `[will-mcp] ${ name } woke from ${ pmaPath }` )
+  }
+  else {
+    will = await Will.create( {
+      ...opts,
+      identity: { prompt: process.env.WILL_IDENTITY ?? `I am ${ name }, a persistent mind hosted over MCP.` },
+    } )
+    console.error( `[will-mcp] ${ name } born (no artifact at ${ pmaPath } yet)` )
+  }
+  will.on( 'error', e => console.error( `[will-mcp] error: ${ e.message }` ) )
+
+  // Onward bridges: MCP servers whose tools become the Will's OWN abilities.
+  // Best-effort — a bad entry warns and is skipped; the mind still boots.
+  const bridgeCloses: Array<() => Promise<void>> = []
+  if( process.env.WILL_MCP_SERVERS ){
+    try {
+      const sources = JSON.parse( process.env.WILL_MCP_SERVERS ) as McpToolsSource[]
+      for( const source of Array.isArray( sources ) ? sources : [] ){
+        try {
+          const { names, close } = await connectMcpEffectors( will, source )
+          bridgeCloses.push( close )
+          console.error( `[will-mcp] ${ name } gained abilities: ${ names.join( ', ' ) }` )
+        }
+        catch( e ){ console.error( `[will-mcp] MCP bridge failed (skipped): ${ ( e as Error ).message }` ) }
+      }
+    }
+    catch( e ){ console.error( `[will-mcp] WILL_MCP_SERVERS is not valid JSON — ignoring: ${ ( e as Error ).message }` ) }
+  }
+
+  // Hibernate exactly once on the way out — distill + stop, then persist.
+  let leaving = false
+  const shutdown = async ( why: string ): Promise<void> => {
+    if( leaving ) return
+    leaving = true
+    for( const close of bridgeCloses ) await close().catch( () => {} )
+    try {
+      const pma = await will.hibernate()
+      mkdirSync( dirname( pmaPath ), { recursive: true } )
+      writeFileSync( pmaPath, JSON.stringify( pma ) )
+      console.error( `[will-mcp] ${ name } hibernated to ${ pmaPath } (${ why })` )
+    }
+    catch( e ){ console.error( `[will-mcp] hibernate failed: ${ ( e as Error ).message }` ) }
+    process.exit( 0 )
+  }
+  process.on( 'SIGINT',  () => void shutdown( 'SIGINT' ) )
+  process.on( 'SIGTERM', () => void shutdown( 'SIGTERM' ) )
+  process.stdin.on( 'end', () => void shutdown( 'client disconnected' ) )
+
+  const server = buildWillMcpServer( will, { pmaPath } )
+  await server.connect( new StdioServerTransport() )
+  console.error( `[will-mcp] ${ name } is listening on stdio (tick ${ opts.tickMs }ms, tier ${ opts.engineTier })` )
+}
+
+main().catch( e => {
+  console.error( `[will-mcp] fatal: ${ e instanceof Error ? e.stack ?? e.message : String( e ) }` )
+  process.exit( 1 )
+} )

package/src/mcp/effectors.ts

@@ -0,0 +1,159 @@
+// ─────────────────────────────────────────────────────────────
+// src/mcp/effectors.ts — a Will EMPLOYING MCP tools (Seam 1)
+// ─────────────────────────────────────────────────────────────
+//
+// The other direction from server.ts: connect a Will to an external MCP server
+// and register that server's tools as the Will's own ABILITIES. Each tool
+// becomes a learnable affordance — its description (plus a compact hint of the
+// arguments it takes) is the ability's meaning, surfaced to the executive and
+// the deliberator; the WILL decides when to enact one (nothing here dispatches);
+// the tool's result feeds back through reafference, so the Will gets *skilled*
+// at the tools it uses.
+//
+// Arguments come from conscious intent: the executive supplies them via an
+// action's `args`, which ride the ideomotor leg into the invocation (see
+// executive commands.ts). A tool with required arguments enacted habitually
+// (without args) fails informatively — reafference then teaches the Will that
+// this ability wants deliberate articulation.
+//
+//   const { names, close } = await connectMcpEffectors( will, {
+//     command: 'npx', args: [ '-y', '@modelcontextprotocol/server-filesystem', '/tmp' ],
+//   } )
+//
+// Import from '@mindot/will/mcp' — kept off the main entry so non-MCP
+// consumers never load the MCP SDK.
+// ─────────────────────────────────────────────────────────────
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import type { Will, EffectorHandler, EffectorResult } from '#sdk/will'
+
+/** Where the tools live: spawn a local server, reach a remote one, or bring a connected client. */
+export type McpToolsSource =
+  | { command: string; args?: string[]; env?: Record<string, string> }
+  | { url: string }
+  | { client: Client }
+
+export interface McpEffectorsOptions {
+  /** Intrinsic effort prior 0..1 seeded on every bridged ability (default 0.2). */
+  cost?: number
+  /** Prefix for the ability names (e.g. 'fs_') — avoids collisions across servers. */
+  prefix?: string
+}
+
+/** Minimal structural view of an MCP tool (the SDK's zod-inferred type, loosened). */
+export interface McpToolInfo {
+  name:         string
+  description?: string
+  inputSchema?: {
+    type?:       string
+    properties?: Record<string, { type?: string; description?: string }>
+    required?:   string[]
+  }
+}
+
+/** Keep tool outcomes bounded — the description feeds reafference + episodic memory. */
+const RESULT_DESCRIPTION_CAP = 700
+/** Keep ability meanings bounded — they render into the executive prompt. */
+const MEANING_CAP = 300
+
+/**
+ * The ability's *meaning*: the tool's description plus a compact hint of the
+ * arguments it takes — so the executive knows what to supply in an action's
+ * `args` when it enacts this ability.
+ */
+export function describeMcpTool( tool: McpToolInfo ): string {
+  const props    = tool.inputSchema?.properties ?? {}
+  const required = new Set( tool.inputSchema?.required ?? [] )
+  const argHints = Object.entries( props ).map( ( [ key, p ] ) =>
+    `${ key }${ required.has( key ) ? '' : '?' }${ p.description ? `: ${ p.description }` : '' }` )
+
+  const base = ( tool.description ?? `The ${ tool.name } tool.` ).trim().replace( /\s+/g, ' ' )
+  const hint = argHints.length > 0 ? ` (args — ${ argHints.join( '; ' ) })` : ''
+  const full = `${ base }${ hint }`
+  return full.length > MEANING_CAP ? `${ full.slice( 0, MEANING_CAP - 1 ) }…` : full
+}
+
+/**
+ * The effector handler for one bridged tool: checks required args (an ability
+ * enacted without its needed articulation fails informatively — reafference
+ * learns from it), calls the tool, and maps the result onto EffectorResult.
+ */
+export function buildMcpHandler( client: Client, tool: McpToolInfo ): EffectorHandler {
+  return async ( args ): Promise<EffectorResult> => {
+    const props = tool.inputSchema?.properties
+    // Only pass keys the tool declares — invocation params can carry situation
+    // extras (targetEntityName, learned priors) the tool never asked for.
+    const filtered: Record<string, unknown> = {}
+    for( const [ k, v ] of Object.entries( args ?? {} ) )
+      if( !props || k in props ) filtered[ k ] = v
+
+    const missing = ( tool.inputSchema?.required ?? [] ).filter(
+      k => filtered[ k ] === undefined || filtered[ k ] === '' )
+    if( missing.length > 0 )
+      return {
+        success: false,
+        description: `${ tool.name } needs ${ missing.join( ', ' ) } — enact it deliberately, supplying them in the action's args.`,
+      }
+
+    try {
+      const res  = await client.callTool( { name: tool.name, arguments: filtered } ) as
+        { content?: Array<{ type: string; text?: string }>; isError?: boolean }
+      const text = ( res.content ?? [] )
+        .filter( c => c.type === 'text' && typeof c.text === 'string' )
+        .map( c => c.text as string )
+        .join( '\n' )
+        .trim() || ( res.isError ? 'The tool reported an error.' : 'Done (no output).' )
+      const bounded = text.length > RESULT_DESCRIPTION_CAP ? `${ text.slice( 0, RESULT_DESCRIPTION_CAP - 1 ) }…` : text
+      return { success: !res.isError, description: bounded }
+    }
+    catch( err ){
+      return { success: false, description: `${ tool.name } failed: ${ err instanceof Error ? err.message : String( err ) }` }
+    }
+  }
+}
+
+async function connect( source: McpToolsSource ): Promise<{ client: Client; owned: boolean }> {
+  if( 'client' in source ) return { client: source.client, owned: false }
+
+  const client = new Client( { name: 'mindot-will', version: '0' } )
+  if( 'url' in source )
+    await client.connect( new StreamableHTTPClientTransport( new URL( source.url ) ) )
+  else
+    await client.connect( new StdioClientTransport( {
+      command: source.command,
+      ...( source.args ? { args: source.args } : {} ),
+      // Merge over the SDK's safe default env so PATH etc. survive a custom env.
+      env: { ...getDefaultEnvironment(), ...( source.env ?? {} ) },
+    } ) )
+  return { client, owned: true }
+}
+
+/**
+ * Register an MCP server's tools as the Will's abilities. Returns the ability
+ * names registered and a `close()` for the connection (call it when the Will
+ * stops; a client passed in via `source.client` is left open).
+ */
+export async function connectMcpEffectors(
+  will:   Will,
+  source: McpToolsSource,
+  opts:   McpEffectorsOptions = {},
+): Promise<{ names: string[]; close: () => Promise<void> }> {
+  const { client, owned } = await connect( source )
+  const { tools } = await client.listTools() as unknown as { tools: McpToolInfo[] }
+
+  const names: string[] = []
+  for( const tool of tools ){
+    const name = `${ opts.prefix ?? '' }${ tool.name }`
+    will.effector( name, {
+      description: describeMcpTool( tool ),
+      cost:        opts.cost ?? 0.2,
+      tags:        [ 'mcp' ],
+      handler:     buildMcpHandler( client, tool ),
+    } )
+    names.push( name )
+  }
+
+  return { names, close: async () => { if( owned ) await client.close() } }
+}

package/src/mcp/server.ts

@@ -0,0 +1,167 @@
+// ─────────────────────────────────────────────────────────────
+// 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, WillMessage } from '#sdk/will'
+
+/** Utterances projected but not yet consumed by a next_utterance call. */
+const UTTERANCE_BUFFER_CAP = 50
+
+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() } )
+
+  // ── Projection buffer ─────────────────────────────────────
+  // MCP calls are separate round trips: the Will may speak BETWEEN a perceive
+  // call and the next_utterance call that follows. Buffer projections so a
+  // fast reply is not lost in the gap; next_utterance drains the buffer first.
+  const pending: WillMessage[] = []
+  will.on( 'message', m => {
+    pending.push( m )
+    if( pending.length > UTTERANCE_BUFFER_CAP ) pending.shift()
+  } )
+
+  const takeBuffered = ( to?: string ): WillMessage | undefined => {
+    const i = to === undefined ? 0 : pending.findIndex( m => m.to === to )
+    if( i < 0 || pending.length === 0 ) return undefined
+    return pending.splice( i, 1 )[0]
+  }
+
+  // ── 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 } ) => {
+    // A projection may have landed between calls — drain the buffer first.
+    const buffered = takeBuffered( from )
+    if( buffered )
+      return { content: [ { type: 'text', text: `${ will.name } says (to ${ buffered.to }): ${ buffered.content }` } ] }
+
+    const within = Math.min( Math.max( within_ms ?? 15_000, 100 ), 120_000 )
+    const msg    = await will.nextUtterance( { within, ...( from ? { to: from } : {} ) } )
+    // The waiter and the buffer listener both see a new message; consume the
+    // buffered copy so the same utterance is not replayed on the next call.
+    if( msg ){
+      const i = pending.findIndex( p => p.id === msg.id )
+      if( i >= 0 ) pending.splice( i, 1 )
+      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
+}