@mindot/will 0.2.0 → 0.3.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@mindot/will",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Fabrice <fabrice8@github.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mindot-ai/will.git"
   },
   "bin": {
-    "will": "dist/mcp/cli.js"
+    "will": "dist/cli.js"
   },
   "main": "./dist/index.js",
   "devDependencies": {

package/src/cli.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────
+// src/cli.ts — the `will` command: host a persistent mind
+// ─────────────────────────────────────────────────────────────
+//
+//   will mcp     host over MCP stdio (Claude Desktop / Claude Code / IDEs)
+//   will serve   host over HTTP (any language; the sidecar) — WILL_PORT/WILL_HOST
+//
+// Both hosts raise the same mind the same way (see host/boot.ts): env-configured,
+// woken from its PMA artifact when one exists, hibernated back on the way out —
+// the mind PERSISTS across sessions. Shared env: WILL_NAME, WILL_IDENTITY,
+// WILL_TIER, WILL_LLM, WILL_TICK_MS, WILL_SEED, WILL_PMA_PATH, WILL_MCP_SERVERS.
+//
+// MCP client config:
+//   { "command": "npx", "args": ["-y", "@mindot/will", "mcp"],
+//     "env": { "WILL_NAME": "Aria", "WILL_IDENTITY": "I am Aria." } }
+//
+// Sidecar:
+//   WILL_NAME=Aria will serve            # http://127.0.0.1:7777
+//   curl -X POST localhost:7777/perceive -d '{"text":"Hello"}'
+// ─────────────────────────────────────────────────────────────
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { routeLogsToStderr, bootWillFromEnv } from '#root/host/boot'
+import { buildWillMcpServer } from '#root/mcp/server'
+import { buildWillHttpServer } from '#root/serve/server'
+
+// stdout is the MCP protocol channel under `will mcp` — route logs FIRST.
+routeLogsToStderr()
+
+const USAGE = `usage: will <mcp | serve>
+
+  mcp     host a persistent mind over MCP stdio (Claude Desktop / Claude Code)
+  serve   host a persistent mind over HTTP (any language; WILL_PORT, default 7777)
+
+Shared env: WILL_NAME, WILL_IDENTITY, WILL_TIER, WILL_LLM, WILL_TICK_MS,
+WILL_SEED, WILL_PMA_PATH, WILL_MCP_SERVERS. The mind persists across runs via
+its PMA artifact.`
+
+async function main(): Promise<void> {
+  const sub = process.argv[2]
+
+  if( sub !== 'mcp' && sub !== 'serve' ){
+    console.error( sub ? `unknown subcommand: ${ sub }\n\n${ USAGE }` : USAGE )
+    process.exit( sub ? 2 : 0 )
+  }
+
+  const { will, name, pmaPath, tickMs, engineTier, onCleanup, shutdown } = await bootWillFromEnv()
+
+  if( sub === 'mcp' ){
+    // The MCP client owns our stdin — its disconnect is the shutdown signal.
+    process.stdin.on( 'end', () => void shutdown( 'client disconnected' ) )
+    const server = buildWillMcpServer( will, { pmaPath } )
+    await server.connect( new StdioServerTransport() )
+    console.error( `[will] ${ name } is listening on MCP stdio (tick ${ tickMs }ms, tier ${ engineTier })` )
+    return
+  }
+
+  // serve — the HTTP sidecar.
+  const port = parseInt( process.env.WILL_PORT ?? '7777' )
+  const host = process.env.WILL_HOST ?? '127.0.0.1'
+  const server = buildWillHttpServer( will, { pmaPath } )
+  onCleanup( () => new Promise<void>( r => server.close( () => r() ) ) )
+  await new Promise<void>( ( resolve, reject ) => {
+    server.once( 'error', reject )
+    server.listen( port, host, () => resolve() )
+  } )
+  console.error( `[will] ${ name } is listening on http://${ host }:${ port } (tick ${ tickMs }ms, tier ${ engineTier })` )
+  console.error( `[will] try: curl -X POST http://${ host }:${ port }/perceive -H 'content-type: application/json' -d '{"text":"Hello"}'` )
+}
+
+main().catch( e => {
+  console.error( `[will] fatal: ${ e instanceof Error ? e.stack ?? e.message : String( e ) }` )
+  process.exit( 1 )
+} )

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/mcp/server.ts

@@ -24,10 +24,8 @@ 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
+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. */
@@ -49,21 +47,10 @@ function serverVersion(): string {
 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]
-  }
+  // 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 ─────────────────────────────────────────────────
 
@@ -101,20 +88,10 @@ export function buildWillMcpServer( will: Will, opts: WillMcpOptions = {} ): Mcp
       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 )
+    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',

package/src/serve/server.ts

@@ -0,0 +1,154 @@
+// ─────────────────────────────────────────────────────────────
+// src/serve/server.ts — a Will, exposed over plain HTTP (the sidecar)
+// ─────────────────────────────────────────────────────────────
+//
+// `will serve` for hosts that aren't Node and aren't MCP clients — a Python
+// app, a game server, a cron job, anything that can speak HTTP. Same paradigm
+// as the SDK facade and the MCP surface: a Will is a SUBJECT you speak to and
+// observe, never a request/response function —
+//
+//   POST /perceive        deliver a stimulus  → 202 (delivered, not answered)
+//   GET  /next-utterance  long-poll its next words; 200 {silence:true} is a
+//                         real outcome, never an error
+//   GET  /utterances      SSE stream of projections (utterance/emotion/action)
+//   GET  /state           snapshot of its inner life
+//   POST /save            checkpoint the living mind (non-destructive)
+//   GET  /health          liveness: name, tick, uptime
+//
+// There is deliberately no ask()-shaped route. Zero dependencies (node:http).
+// Boot/persistence/shutdown wiring lives in the CLI; this module only maps a
+// facade instance onto a server (testable on an ephemeral port).
+// ─────────────────────────────────────────────────────────────
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Will } from '#sdk/will'
+import { UtteranceTap } from '#root/host/utterances'
+
+export interface WillHttpOptions {
+  /** Where POST /save writes the PMA artifact. */
+  pmaPath?: string
+}
+
+const SSE_HEARTBEAT_MS = 15_000
+
+function json( res: ServerResponse, status: number, body: unknown ): void {
+  const text = JSON.stringify( body )
+  res.writeHead( status, { 'content-type': 'application/json', 'access-control-allow-origin': '*' } )
+  res.end( text )
+}
+
+async function readJsonBody( req: IncomingMessage ): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = []
+  for await ( const c of req ) chunks.push( c as Buffer )
+  const raw = Buffer.concat( chunks ).toString( 'utf8' ).trim()
+  if( !raw ) return {}
+  return JSON.parse( raw ) as Record<string, unknown>
+}
+
+/**
+ * Map a running Will onto an HTTP server. The caller owns the Will's lifecycle
+ * and calls `listen()`; everything here is the protocol surface.
+ */
+export function buildWillHttpServer( will: Will, opts: WillHttpOptions = {} ): Server {
+  const tap   = new UtteranceTap( will )
+  const born  = Date.now()
+
+  // SSE subscribers — every projection fans out to all open streams.
+  const streams = new Set<ServerResponse>()
+  const fanout  = ( event: string, data: unknown ): void => {
+    const frame = `event: ${ event }\ndata: ${ JSON.stringify( data ) }\n\n`
+    for( const res of streams ) res.write( frame )
+  }
+  will.on( 'message',  m => fanout( 'utterance', m ) )
+  will.on( 'emotion',  a => fanout( 'emotion', a ) )
+  will.on( 'effector', a => fanout( 'action', a ) )
+
+  const server = createServer( ( req, res ) => {
+    void handle( req, res ).catch( err => {
+      if( !res.headersSent )
+        json( res, 500, { error: err instanceof Error ? err.message : String( err ) } )
+      else res.end()
+    } )
+  } )
+
+  async function handle( req: IncomingMessage, res: ServerResponse ): Promise<void> {
+    const url = new URL( req.url ?? '/', 'http://sidecar' )
+    const route = `${ req.method } ${ url.pathname }`
+
+    if( req.method === 'OPTIONS' ){
+      res.writeHead( 204, {
+        'access-control-allow-origin':  '*',
+        'access-control-allow-methods': 'GET, POST, OPTIONS',
+        'access-control-allow-headers': 'content-type',
+      } )
+      res.end()
+      return
+    }
+
+    switch( route ){
+      case 'GET /health':
+        return json( res, 200, { ok: true, name: will.name, tick: will.state().tick, uptimeMs: Date.now() - born } )
+
+      case 'GET /state':
+        return json( res, 200, will.state() )
+
+      case 'POST /perceive': {
+        const body = await readJsonBody( req )
+        const text = typeof body.text === 'string' ? body.text : ''
+        if( !text ) return json( res, 400, { error: 'text is required' } )
+        await will.perceive( {
+          text,
+          ...( typeof body.from    === 'string' ? { from:    body.from }    : {} ),
+          ...( typeof body.speaker === 'string' ? { speaker: body.speaker } : {} ),
+        } )
+        // 202: delivered into the sensory field — NOT answered. A response, if
+        // any, arrives on /utterances or /next-utterance; silence is valid.
+        return json( res, 202, { delivered: true, tick: will.state().tick } )
+      }
+
+      case 'GET /next-utterance': {
+        const within = Math.min( Math.max( parseInt( url.searchParams.get( 'within_ms' ) ?? '15000' ) || 15_000, 100 ), 120_000 )
+        const from   = url.searchParams.get( 'from' ) ?? undefined
+        const msg    = await tap.next( within, from )
+        return msg
+          ? json( res, 200, { utterance: msg } )
+          : json( res, 200, { silence: true, waitedMs: within } )   // a choice, not an error
+      }
+
+      case 'GET /utterances': {
+        res.writeHead( 200, {
+          'content-type':                'text/event-stream',
+          'cache-control':               'no-cache',
+          'connection':                  'keep-alive',
+          'access-control-allow-origin': '*',
+        } )
+        res.write( `event: hello\ndata: ${ JSON.stringify( { name: will.name, tick: will.state().tick } ) }\n\n` )
+        streams.add( res )
+        const heartbeat = setInterval( () => res.write( `: tick ${ will.state().tick }\n\n` ), SSE_HEARTBEAT_MS )
+        req.on( 'close', () => { clearInterval( heartbeat ); streams.delete( res ) } )
+        return
+      }
+
+      case 'POST /save': {
+        if( !opts.pmaPath ) return json( res, 409, { error: 'no PMA path configured — set WILL_PMA_PATH' } )
+        const pma = await will.save()
+        mkdirSync( dirname( opts.pmaPath ), { recursive: true } )
+        writeFileSync( opts.pmaPath, JSON.stringify( pma ) )
+        return json( res, 200, { saved: true, path: opts.pmaPath } )
+      }
+
+      default:
+        return json( res, 404, {
+          error: `no such route: ${ route }`,
+          routes: [ 'GET /health', 'GET /state', 'POST /perceive', 'GET /next-utterance', 'GET /utterances (SSE)', 'POST /save' ],
+        } )
+    }
+  }
+
+  // Close open SSE streams when the server closes (so close() can complete).
+  server.on( 'close', () => { for( const res of streams ) res.end(); streams.clear() } )
+
+  return server
+}