@mindot/will 0.1.1 → 0.3.0

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

@@ -149,6 +149,16 @@ export class ExecutiveFacet {
   /** Stamp activity at `tick` (called at spawn and on each report). */
   markActive( tick: number ): void { this._lastActiveTick = tick }
 
+  /** _reason() calls currently in flight — a real LLM call spans many ticks. */
+  private _inflight = 0
+  /**
+   * True while the facet has work the reaper must not discard: queued reports
+   * awaiting the pump, or an in-flight _reason() whose decision hasn't landed.
+   * The idle TTL only measures *quiet* facets — reaping a busy one destroys the
+   * listeners its pending decision needs, silently dropping a conversation reply.
+   */
+  get busy(): boolean { return this._inflight > 0 || this._pendingReports.length > 0 }
+
   /**
    * Per-facet chunk handler — fires for every LLM token during _reason().
    * Set by the creating engine (e.g. AuditionEngine) for entity-scoped streaming.
@@ -236,9 +246,27 @@ export class ExecutiveFacet {
     }
 
     // Legacy (bare facets in unit tests): trigger reasoning immediately.
-    this._reason( report ).catch( err =>
-      logger.error( `[executive.facet] ${this.facetId} reasoning error:`, err )
-    )
+    this._launchReason( report )
+  }
+
+  /**
+   * Launch _reason() with in-flight accounting. `busy` must hold for the whole
+   * span (a real LLM call is 10–30s ≈ many ticks) so the supervisor's idle
+   * reaper never destroys a facet whose decision is still coming — that would
+   * clear its listeners and silently drop the reply. Completion re-stamps
+   * activity so the idle TTL measures quiet time *after* the decision, not
+   * after the report that started it.
+   */
+  private _launchReason( report: FacetReport ): void {
+    this._inflight++
+    this._reason( report )
+      .catch( err =>
+        logger.error( `[executive.facet] ${this.facetId} reasoning error:`, err )
+      )
+      .finally( () => {
+        this._inflight--
+        this.markActive( ( this._currentStateRef?.tick as number ) ?? this._lastActiveTick )
+      })
   }
 
   /**
@@ -257,9 +285,7 @@ export class ExecutiveFacet {
     this._pendingReports = []
 
     for( const report of batch )
-      this._reason( report ).catch( err =>
-        logger.error( `[executive.facet] ${this.facetId} reasoning error:`, err )
-      )
+      this._launchReason( report )
   }
 
   subscribe( listener: FacetEventListener ): () => void {

package/src/cognition/faculties/executive.engine/prompt.factory.ts

@@ -344,7 +344,7 @@ ${roleDescription}
 ${consciousnessArchitecture}
 
 ## Output Guidelines
-- **actions**: Choose from effectors you know about. If uncertain, describe what you want to achieve in natural language and your body will try to match it.
+- **actions**: Choose from effectors you know about. If uncertain, describe what you want to achieve in natural language and your body will try to match it. When enacting one of your available abilities that needs specifics (a query, a message, a value), supply them in the action's "args" object — e.g. {"type": "search_docs", "args": {"query": "tick loop design"}, ...}. Your body enacts the ability with exactly those args.
 - **plans**: Include for goals without existing plans or where plans need revision. You may keep multiple plans per goal — set **planId** to act on a specific existing plan (validate/execute/revise/cancel); omit it to draft a new one. Your current plans are listed under "## Active Plans".
 - **newBeliefs**: Extract patterns from experiences visible in your current state. Only record a belief if you can point to a specific observation that supports it — do not infer experiences you have no record of. Set 'evidence' honestly: 'single_observation' (first time noticing), 'recurring_pattern' (seen multiple times), 'strong_pattern' (deeply established).
 - **introspection**: Include when significant events occurred or you notice patterns. When you spot a cognitive bias in your own reasoning, name it in 'identifiedBiases' using its common term where one fits (e.g. overgeneralization, confirmation bias, recency bias) — this lets your self-assessment line up with the patterns your faculties detect on their own.
@@ -643,6 +643,15 @@ Dominance: ${context.affect.dominance.toFixed( 2 )}${context.affect.blends.lengt
       ? `## Percepts (What You Notice)\n${context.percepts.slice( 0, 10 ).map( p => `- [${p.category}] ${p.summary} (salience: ${p.salience.toFixed( 2 )})` ).join( '\n' ) || 'Nothing notable'}`
       : ''
 
+    // Host abilities afforded right now + what each is for. Framed as
+    // self-knowledge (things you *can* do), NOT a tool-call menu: the Will still
+    // expresses intent in natural language and the agency field enacts the fit.
+    const abilitiesBlock = ( context.abilities && context.abilities.length > 0 )
+      ? `## Abilities Available Now\nThings you can do in this situation — name one as an action's "type" (with "args" for any specifics it needs) and your body enacts it:\n${context.abilities.map( a =>
+          `- **${a.name}**${a.target ? ` (toward ${a.target})` : ''}${a.description ? ` — ${a.description}` : ''}`
+        ).join( '\n' )}`
+      : ''
+
     const ruminationsBlock = has( 'ruminations' )
       ? `## Active Ruminations (retrieved memories & thoughts)\n${context.workingMemory.map( w => `- [${w.type}] ${w.summary} (activation: ${w.activation.toFixed( 2 )})` ).join( '\n' ) || 'Nothing actively held in mind'}`
       : ''
@@ -694,6 +703,7 @@ Dominance: ${context.affect.dominance.toFixed( 2 )}${context.affect.blends.lengt
       actionDiversity.trim(),
       recentOutcomesBlock,
       perceptsBlock,
+      abilitiesBlock,
       ruminationsBlock,
       recentIntrospection.trim(),
       memoriesBlock,

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/host/boot.ts

@@ -0,0 +1,127 @@
+// ─────────────────────────────────────────────────────────────
+// src/host/boot.ts — shared boot/shutdown for the `will` CLI hosts
+// ─────────────────────────────────────────────────────────────
+//
+// Both hosts (`will mcp`, `will serve`) raise the same mind the same way:
+// env-configured, woken from its PMA artifact when one exists (else born),
+// optionally bridged onto external MCP servers whose tools become its own
+// abilities, and hibernated back to the artifact exactly once on the way out.
+// Only the protocol surface differs — that stays in each host.
+//
+// Env (shared):
+//   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: entries {command,args?,env?} or {url}.
+// ─────────────────────────────────────────────────────────────
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { setLogger } from '#core/logger'
+import { Will, type CreateWillOptions } from '#sdk/will'
+import type { PMASnapshot } from '#pma/index'
+import { connectMcpEffectors, type McpToolsSource } from '#root/mcp/effectors'
+
+/**
+ * Route every engine log line to stderr. For `will mcp`, stdout is the MCP
+ * protocol channel and must stay pure; `will serve` keeps the same discipline
+ * so both hosts log identically (and Docker captures one stream).
+ */
+export function routeLogsToStderr(): void {
+  const err = ( level: string ) => ( msg: string, ...rest: unknown[] ) =>
+    console.error( `[will:${ 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'
+}
+
+export interface BootedWill {
+  will:       Will
+  name:       string
+  pmaPath:    string
+  tickMs:     number
+  engineTier: NonNullable<CreateWillOptions['engineTier']>
+  /** Run before hibernate on shutdown (close servers/transports). LIFO. */
+  onCleanup:  ( fn: () => Promise<void> | void ) => void
+  /** Hibernate → persist → exit(0). Idempotent; SIGINT/SIGTERM already wired. */
+  shutdown:   ( why: string ) => Promise<void>
+}
+
+/** Raise the mind from env config — wake from the artifact if one exists. */
+export async function bootWillFromEnv(): Promise<BootedWill> {
+  const name       = process.env.WILL_NAME ?? 'Will'
+  const pmaPath    = resolve( process.env.WILL_PMA_PATH ?? `.will/${ slug( name ) }.pma.json` )
+  const tickMs     = parseInt( process.env.WILL_TICK_MS ?? '1000' )
+  const engineTier = ( process.env.WILL_TIER as CreateWillOptions['engineTier'] ) ?? 'standard'
+
+  const opts: Omit<CreateWillOptions, 'identity'> = {
+    name, engineTier, tickMs,
+    ...( process.env.WILL_LLM  ? { llm: process.env.WILL_LLM as 'mock' | 'anthropic' } : {} ),
+    ...( process.env.WILL_SEED ? { seed: parseInt( process.env.WILL_SEED ) } : {} ),
+  }
+
+  let will: Will
+  if( existsSync( pmaPath ) ){
+    const pma = JSON.parse( readFileSync( pmaPath, 'utf8' ) ) as PMASnapshot
+    will = await Will.wake( pma, opts )
+    console.error( `[will] ${ name } woke from ${ pmaPath }` )
+  }
+  else {
+    will = await Will.create( {
+      ...opts,
+      identity: { prompt: process.env.WILL_IDENTITY ?? `I am ${ name }, a persistent mind.` },
+    } )
+    console.error( `[will] ${ name } born (no artifact at ${ pmaPath } yet)` )
+  }
+  will.on( 'error', e => console.error( `[will] 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 cleanups: Array<() => Promise<void> | 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 )
+          cleanups.push( close )
+          console.error( `[will] ${ name } gained abilities: ${ names.join( ', ' ) }` )
+        }
+        catch( e ){ console.error( `[will] MCP bridge failed (skipped): ${ ( e as Error ).message }` ) }
+      }
+    }
+    catch( e ){ console.error( `[will] WILL_MCP_SERVERS is not valid JSON — ignoring: ${ ( e as Error ).message }` ) }
+  }
+
+  // Hibernate exactly once on the way out — cleanups (LIFO), distill + stop, persist.
+  let leaving = false
+  const shutdown = async ( why: string ): Promise<void> => {
+    if( leaving ) return
+    leaving = true
+    for( const fn of cleanups.reverse() ) await Promise.resolve( fn() ).catch( () => {} )
+    try {
+      const pma = await will.hibernate()
+      mkdirSync( dirname( pmaPath ), { recursive: true } )
+      writeFileSync( pmaPath, JSON.stringify( pma ) )
+      console.error( `[will] ${ name } hibernated to ${ pmaPath } (${ why })` )
+    }
+    catch( e ){ console.error( `[will] hibernate failed: ${ ( e as Error ).message }` ) }
+    process.exit( 0 )
+  }
+  process.on( 'SIGINT',  () => void shutdown( 'SIGINT' ) )
+  process.on( 'SIGTERM', () => void shutdown( 'SIGTERM' ) )
+
+  return {
+    will, name, pmaPath, tickMs, engineTier: engineTier ?? 'standard',
+    onCleanup: fn => cleanups.push( fn ),
+    shutdown,
+  }
+}

package/src/host/utterances.ts

@@ -0,0 +1,53 @@
+// ─────────────────────────────────────────────────────────────
+// src/host/utterances.ts — a host-side tap on a Will's speech
+// ─────────────────────────────────────────────────────────────
+//
+// Hosts that expose a Will over a request/response protocol (MCP tools, HTTP
+// long-polls) share a timing problem: the Will may speak BETWEEN two calls —
+// after a perceive round trip returns and before the caller asks for the next
+// utterance. The tap buffers projections so nothing is lost in the gap, and
+// `next()` gives the MCP/HTTP hosts one shared, honest await: drain the buffer
+// first, else wait, else report silence (null — a choice, never an error).
+// ─────────────────────────────────────────────────────────────
+
+import type { Will, WillMessage } from '#sdk/will'
+
+const BUFFER_CAP = 50
+
+export class UtteranceTap {
+  private readonly _will: Will
+  private readonly _pending: WillMessage[] = []
+
+  constructor( will: Will ){
+    this._will = will
+    will.on( 'message', m => {
+      this._pending.push( m )
+      if( this._pending.length > BUFFER_CAP ) this._pending.shift()
+    } )
+  }
+
+  /** Consume the oldest buffered utterance (optionally only one addressed to `to`). */
+  takeBuffered( to?: string ): WillMessage | undefined {
+    if( this._pending.length === 0 ) return undefined
+    const i = to === undefined ? 0 : this._pending.findIndex( m => m.to === to )
+    if( i < 0 ) return undefined
+    return this._pending.splice( i, 1 )[0]
+  }
+
+  /**
+   * The next utterance: a buffered one if a projection already landed, else
+   * await up to `within` ms. `null` = the Will chose silence. An awaited
+   * message is also consumed from the buffer so it never replays.
+   */
+  async next( within: number, to?: string ): Promise<WillMessage | null> {
+    const buffered = this.takeBuffered( to )
+    if( buffered ) return buffered
+
+    const msg = await this._will.nextUtterance( { within, ...( to ? { to } : {} ) } )
+    if( msg ){
+      const i = this._pending.findIndex( p => p.id === msg.id )
+      if( i >= 0 ) this._pending.splice( i, 1 )
+    }
+    return msg
+  }
+}

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/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() } }
+}