@mindot/will 0.1.1 → 0.3.0

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
+}

package/src/stem/index.ts

@@ -38,6 +38,8 @@ import { TransportController } from '#stem/tracts/transport.controller'
 import { InboundQueue } from '#stem/tracts/inbound.queue'
 import type { ExternalTransport } from '#stem/tracts/transport'
 import { effectorController } from '#stem/tracts/effector.controller'
+import { externalSchemas } from '#agency/schemas/external'
+import type { EffectorDeclaration } from '#agency/types'
 import { SensoryController } from '#stem/tracts/sensory.controller'
 import { BiographyWriter } from '#stem/tracts/biography.writer'
 import { HealthReporter } from '#stem/tracts/health.reporter'
@@ -772,6 +774,20 @@ export class WillStem {
     this._effector.setAllowed( this._get( id ), effectors )
   }
 
+  /**
+   * Register a host effector on a *running* Will (post-create `.effector()`).
+   * Builds its external schema and adds it to the live repertoire so the Will
+   * can actually perceive + enact it — a grant alone only gates; without the
+   * schema the ability could never be afforded. Comms names are no-ops here
+   * (governed by AccessGrants). This is a runtime mutation, like a grant change;
+   * the deterministic/replayable path is declaring effectors at create time.
+   */
+  registerEffector( id: string, declaration: EffectorDeclaration ): void {
+    const repertoire = this._get( id ).cognition.schemaRepertoire
+    for( const schema of externalSchemas( [ declaration ] ) )
+      repertoire.registerExternal( schema )
+  }
+
   /**
    * Called by the host/WorldInterface after executing a host-owned effector.
    * `invocationId` is the correlation handle the host echoed (the awaiting

package/src/stem/mind.ts

@@ -40,6 +40,7 @@ import { InstructionIntake }     from '#agency/engines/instruction.intake'
 import { SchemaRepertoire }      from '#agency/schemas/repertoire'
 import { INNATE_SCHEMAS }        from '#agency/schemas/innate'
 import { externalSchemas }       from '#agency/schemas/external'
+import { effectorName, type EffectorDeclaration } from '#agency/types'
 
 
 import {
@@ -260,8 +261,12 @@ export interface WillConfig {
    *
    * null or omitted = no communication effectors (minimal default).
    * Example: ['listen', 'talk', 'text'] enables inbound + text outbound.
+   *
+   * A domain effector may be a bare name or an object carrying its meaning +
+   * intrinsic priors: `{ name, description?, cost?, valence?, preconditions? }`
+   * (see EffectorDeclaration). Comms names are always bare.
    */
-  allowedGenericEffectors?: string[] | null
+  allowedGenericEffectors?: EffectorDeclaration[] | null
 
   /**
    * When true the executive engine uses a canned mock LLM response instead of
@@ -506,7 +511,7 @@ export function assembleMind( willId: string, config: WillConfig ): MindAssembly
   // creation; warnings surface; safe issues are sanitized in place.
   const idGuard = validateWillIdentity({
     identity:       config.identity,
-    effectors:      Array.isArray( config.allowedGenericEffectors ) ? config.allowedGenericEffectors : ( profile?.effectors ?? null ),
+    effectors:      ( Array.isArray( config.allowedGenericEffectors ) ? config.allowedGenericEffectors : ( profile?.effectors ?? null ) )?.map( effectorName ) ?? null,
     profileContext: profile?.context,
   })
   if( !idGuard.ok )
@@ -655,13 +660,15 @@ function _constructCognition(
   // This matters when a profile Will is created without specifying effectors:
   // the DB stores null, the service passes null, and profile effectors must win.
   // An empty array [] means "explicitly no effectors" (survives restart correctly).
-  const resolvedEffectors = Array.isArray( config.allowedGenericEffectors )
+  const resolvedEffectors: EffectorDeclaration[] | null = Array.isArray( config.allowedGenericEffectors )
     ? config.allowedGenericEffectors
     : ( profile?.effectors ?? null )
+  // Name-only view for the grant / permission surfaces (comms gating is by name).
+  const resolvedEffectorNames = resolvedEffectors?.map( effectorName ) ?? null
 
   // Agency-native permission / sense-gate authority, seeded from the resolved
   // grant list. The senses + reply path read this. (Replaced effectorRegistry.)
-  const accessGrants = new AccessGrants( resolvedEffectors )
+  const accessGrants = new AccessGrants( resolvedEffectorNames )
 
   // ── Executive Engine ────────────────────────────────────────
   // Created for all tiers so the Cognition type is always satisfied.

package/src/stem/tracts/effector.controller.ts

@@ -51,6 +51,7 @@ export class effectorController {
       parameters:       ( payload.parameters as Record<string, unknown> ) ?? {},
       targetEntityId:   payload.targetEntityId as string | undefined,
       reasoning:        ( payload.reasoning as string ) ?? '',
+      ...( typeof payload.description === 'string' ? { description: payload.description } : {} ),
       tick:             ( payload.tick as number ) ?? 0,
       timestamp:        Date.now()
     })

package/src/types.ts

@@ -29,6 +29,8 @@ export interface effectorInvocation {
   parameters:       Record<string, unknown>
   targetEntityId:   string | undefined
   reasoning:        string
+  /** The ability's declared meaning (from its EffectorDeclaration), when present. */
+  description?:     string
   tick:             number
   timestamp:        number
 }