@mindot/will 0.1.0

package/src/cognition/agency/proactive.communicator.ts

@@ -0,0 +1,274 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/proactive.communication.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * ProactiveCommunicator — the agency pipeline's communicate-enaction handler.
+ *
+ * Owned privately by the MotorSchemaExecutor (its only caller): when a `communicate`
+ * motor schema wins the action competition, this turns the decided intent into
+ * delivery + memory. It validates the request, emits the memory/state side-effects
+ * (`conversation.sent` + the shared `conversation.exchange`), and hands the actual
+ * outbox row(s) to the shared OutboxWriter. It does NOT own the row shape (the
+ * writer does) and does NOT gate (AccessGrants does, upstream in the executor).
+ *
+ * Effectors handled: listen, talk, text, gesture, broadcast
+ *
+ * Outbound flow:
+ *   agency MotorSchemaExecutor → ProactiveCommunicator → OutboxWriter.enqueue
+ *   → OutboxController drains per tick → TransportController emits (or SSE)
+ */
+
+import { logger } from '#core/logger'
+import { wallClock } from '#core/wall.clock'
+import type { ActionRequest, ActionResult } from '#types'
+import type { ReadonlySimulationState, StateCommands } from '#core/types'
+import type { OutboxWriter } from '#stem/tracts/outbox.writer'
+import type { SessionLogger } from '#stem/tracts/session.logger'
+import { buildConversationExchange } from '#cognition/conversation.memory'
+
+export interface ProactiveCommunicatorOptions {
+  /** Shared outbox producer — owns the row shape; the executor delegates pushes. */
+  writer:  OutboxWriter
+  willId?: string
+}
+
+export class ProactiveCommunicator {
+  private _writer:        OutboxWriter
+  private _willId:        string
+  private _sessionLogger: SessionLogger | null = null
+
+  constructor( options: ProactiveCommunicatorOptions ){
+    this._writer = options.writer
+    this._willId = options.willId ?? 'will'
+  }
+
+  attachSessionLogger( logger: SessionLogger | null ): void {
+    this._sessionLogger = logger
+  }
+
+  async executeAction(
+    request: ActionRequest,
+    _state:  ReadonlySimulationState,
+  ): Promise<ActionResult> {
+    const commands: StateCommands = { metrics: [] }
+
+    switch( request.effector ){
+      case 'listen':    return this._handleListen( request, commands )
+      case 'talk':      return this._handleOutboundMessage('talk',      request, commands )
+      case 'text':      return this._handleOutboundMessage('text',      request, commands )
+      case 'gesture':   return this._handleGesture(         request, commands )
+      case 'broadcast': return this._handleBroadcast(       request, commands )
+      default:
+        return {
+          success: false,
+          description: `ProactiveCommunicator does not handle: ${request.effector}`,
+          commands,
+          feedback: { outcomeQuality: 0, surprise: 0, lessons: [] },
+        }
+    }
+  }
+
+  // ── Handlers ─────────────────────────────────────────────────
+
+  private async _handleListen(
+    _request: ActionRequest,
+    commands: StateCommands,
+  ): Promise<ActionResult> {
+    return {
+      success: true,
+      description: `You open yourself to incoming communication. Others may now reach you through available channels.`,
+      commands,
+      feedback: {
+        outcomeQuality: 1.0,
+        surprise: 0.05,
+        lessons: [ 'Being reachable allows others to connect with you.' ],
+      },
+    }
+  }
+
+  private async _handleGesture(
+    request:  ActionRequest,
+    commands: StateCommands,
+  ): Promise<ActionResult> {
+    const targetEntityId = request.targetEntityId
+                        ?? ( request.parameters?.targetEntityId as string )
+                        ?? 'unknown'
+    const gestureType    = ( request.parameters?.gestureType as string ) ?? 'gesture'
+
+    this._writer.enqueue({
+      targetEntityId,
+      content:     gestureType,
+      effectorName: 'gesture',
+      gestureType,
+    })
+
+    return {
+      success: true,
+      description: `You ${gestureType} toward ${targetEntityId}. The gesture is directed and sincere.`,
+      commands,
+      feedback: {
+        outcomeQuality: 0.8,
+        surprise: 0.1,
+        lessons: [ 'Non-verbal communication carries its own weight.' ],
+      },
+    }
+  }
+
+  private async _handleBroadcast(
+    request:  ActionRequest,
+    commands: StateCommands,
+  ): Promise<ActionResult> {
+    const rawMessages     = request.parameters?.messages
+    const contentParam    = ( request.parameters?.content as string ) ?? ''
+    const targetEntityIds = ( request.parameters?.targetEntityIds as string[] ) ?? []
+
+    const bubbles: string[] = Array.isArray( rawMessages )
+      ? ( rawMessages as string[] ).filter( Boolean )
+      : [ contentParam || ( request.parameters?.message as string ) || '' ].filter( Boolean )
+
+    const finalContent = bubbles.join(' ')
+    const target = targetEntityIds.length > 0 ? targetEntityIds.join(',') : '*'
+    this._writer.enqueue({
+      targetEntityId: target,
+      content:        finalContent,
+      effectorName:    'broadcast',
+    })
+
+    return {
+      success: true,
+      description: `You broadcast: "${finalContent.slice( 0, 80 )}${finalContent.length > 80 ? '…' : ''}"`,
+      commands,
+      feedback: {
+        outcomeQuality: 0.75,
+        surprise: 0.2,
+        lessons: [ 'Broadcasts reach multiple entities simultaneously.' ],
+      },
+    }
+  }
+
+  private async _handleOutboundMessage(
+    effectorName: 'talk' | 'text',
+    request:     ActionRequest,
+    commands:    StateCommands,
+  ): Promise<ActionResult> {
+    const targetEntityId   = request.targetEntityId
+                          ?? ( request.parameters?.targetEntityId as string )
+    const targetEntityName = ( request.parameters?.targetEntityName as string ) ?? targetEntityId ?? 'them'
+
+    // The executive always writes the actual words — no composition step.
+    // Accept `messages` (array), or legacy `message`/`content` (single string).
+    const rawMessages = request.parameters?.messages
+    const bubbles: string[] = Array.isArray( rawMessages )
+      ? ( rawMessages as string[] ).filter( Boolean )
+      : [ ( request.parameters?.message as string )
+          || ( request.parameters?.content as string )
+          || '' ].filter( Boolean )
+
+    if( !targetEntityId ){
+      return {
+        success: false,
+        description: `You want to ${effectorName} but there is no one specific to reach out to.`,
+        commands,
+        feedback: {
+          outcomeQuality: 0,
+          surprise: 0.2,
+          lessons: [ 'Specify a targetEntityId to send a message.' ],
+        },
+      }
+    }
+
+    if( bubbles.length === 0 ){
+      return {
+        success: false,
+        description: `You wanted to ${effectorName} ${targetEntityName} but didn't write anything.`,
+        commands,
+        feedback: { outcomeQuality: 0, surprise: 0.1, lessons: [ 'Provide a messages array with the actual words.' ] },
+      }
+    }
+
+    // Generate outbox message IDs first so we can embed them in conversation.sent
+    // and correlate deliveries back to this intent (TODO 11.3).
+    const originalMessage  = ( request.parameters?.originalMessage as string ) ?? ''
+    const deliveryTick     = ( request.parameters?.tick as number ) ?? 0
+    const replyToMessageId = ( request.parameters?.replyToMessageId as string ) ?? undefined
+    const isAck            = ( request.parameters?.isAck as boolean ) ?? false
+
+    const outboxMessageIds: string[] = []
+    bubbles.forEach( ( bubble, i ) => {
+      logger.info(`[communication] pushing to outbox: ${effectorName} → ${targetEntityId} "${bubble.slice( 0, 80 )}"`)
+      outboxMessageIds.push( this._writer.enqueue({
+        targetEntityId,
+        targetEntityName,
+        content:     bubble,
+        effectorName,
+        replyToMessageId,
+      }, `-${ i }` ) )
+    })
+
+    // Write the intent record at push time so context-builder can see what we said.
+    // NOTE (11.3): this entity tracks intent, not confirmation.  confirmMessageDelivery()
+    // will update it with delivered:true once the client ACKs.
+    const sentEntityId = `conv-sent-${targetEntityId}-${deliveryTick}`
+
+    commands.set ??= []
+    commands.set.push({
+      id:        sentEntityId,
+      type:      'conversation.sent',
+      createdAt: wallClock(),
+      metadata: {
+        targetEntityId,
+        targetEntityName,
+        messageCount:    bubbles.length,
+        preview:         bubbles[0]?.slice( 0, 100 ) ?? '',
+        effectorName,
+        tick:            deliveryTick,
+        delivered:       false,
+        isAck,
+        outboxMessageIds,  // enables confirmMessageDelivery to update this entity
+      },
+    })
+
+    // Log the outbound message for session auditing (D4)
+    this._sessionLogger?.write({
+      type:             'conversation.out',
+      tick:             deliveryTick,
+      targetEntityId,
+      targetEntityName,
+      messageCount:     bubbles.length,
+      messages:         bubbles.map( b => b.slice( 0, 300 ) ),
+      preview:          bubbles[0]?.slice( 0, 100 ) ?? '',
+      isAck,
+    })
+
+    const fullReply = bubbles.join(' ')
+
+    // Persist every outbound as a conversation.exchange WM item so it consolidates
+    // into episodic + vector memory — the same shape the AuditionEngine uses for
+    // facet replies (built by the shared buildConversationExchange). UNCONDITIONAL
+    // (option a): master-initiated outreach (no inbound `originalMessage`) must also
+    // be remembered, so a facet later spawned to continue recalls what was said.
+    commands.set ??= []
+    commands.set.push( buildConversationExchange({
+      entityId:    targetEntityId,
+      entityName:  targetEntityName,
+      userMessage: originalMessage,
+      willReply:   fullReply,
+      tick:        ( request.parameters?.tick as number ) ?? 0,
+      idSeed:      wallClock(),
+      createdAt:   wallClock(),
+    }) )
+
+    return {
+      success: true,
+      description: `You reach out to ${targetEntityName}: "${fullReply.slice( 0, 80 )}${fullReply.length > 80 ? '…' : ''}"`,
+      commands,
+      feedback: {
+        outcomeQuality: 0.85,
+        surprise: 0.15,
+        lessons: [ `Your message is queued for delivery to ${targetEntityName}.` ],
+      },
+    }
+  }
+
+}

package/src/cognition/agency/reconcile.learning.ts

@@ -0,0 +1,82 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/reconcile.learning.ts  —  host-ack reconciliation
+// ─────────────────────────────────────────────────────────────
+//
+// Closes the async loop for `external` / `communicate` enactions. When the
+// MotorSchemaExecutor dispatches a host-owned effector it leaves the intent
+// 'awaiting' and emits `agency.invocation`. The host later executes it and calls
+// back; `reconcileInvocation` turns that callback into the `agency.outcome` the
+// ReafferenceEngine already consumes — which both teaches the skill the real
+// result AND frees the serial Will (reafference deletes the awaiting intent via
+// the outcome's `intentId`).
+//
+// This is the agency-native equivalent of the legacy effectorController.
+// confirmExecution — same efference-copy / reafference contract, new vocabulary.
+// The stem wires its host ack endpoint to call this and write the returned entity.
+// ─────────────────────────────────────────────────────────────
+
+import type { EntityInput, Tick } from '#core/types'
+
+export interface HostAckResult {
+  success:        boolean
+  /** 0..1 — how good the world's reply was. Defaults from `success` when omitted. */
+  outcomeQuality?: number
+  /** −1..1 felt valence of the outcome. */
+  valence?:       number
+  description?:   string
+}
+
+/**
+ * Build the `agency.outcome` entity that confirms an awaiting invocation. The
+ * caller (stem host-ack endpoint) writes it via `stateManager.setEntity`; the
+ * ReafferenceEngine consumes it next tick — learning from it and deleting the
+ * awaiting intent identified by `intentId`.
+ *
+ * `schema` is the awaiting intent's schema (the host has it from the
+ * `agency.invocation` payload); `predictedReward`/`predictedValence` are the
+ * efference copy the executor persisted on the intent, so surprise is honest.
+ *
+ * `provenance` carries the awaiting intent's plan link (planId/stepId) when it was
+ * committed from a plan's frontier prior. It rides on the agency.outcome so the
+ * ReafferenceEngine — the engine that consumes async-acked outcomes — can emit the
+ * `action.outcome{planId,stepId}` the PlanningEngine advances on. (The executor
+ * emits that itself for sync/timeout outcomes; the host-ack path has no executor in
+ * the loop, so reafference is the single emitter for it — see ReafferenceEngine.)
+ */
+export function reconcileInvocation(
+  intentId: string,
+  schema:   string,
+  result:   HostAckResult,
+  tick:     Tick,
+  predicted: { reward: number; valence: number } = { reward: 0.5, valence: 0 },
+  provenance: { planId?: string; stepId?: string } = {},
+): EntityInput {
+  const outcomeQuality = result.outcomeQuality ?? ( result.success ? 0.8 : 0.1 )
+  const valence        = result.valence ?? ( result.success ? 0.2 : -0.2 )
+  const surprise       = clamp01( Math.abs( predicted.reward - outcomeQuality ) )
+
+  return {
+    id:   `agency-outcome-${ tick }-${ intentId }`,
+    type: 'agency.outcome',
+    metadata: {
+      schema,
+      intentId,
+      success:          result.success,
+      outcomeQuality,
+      valence,
+      predictedReward:  predicted.reward,
+      predictedValence: predicted.valence,
+      surprise,
+      description:      result.description ?? ( result.success ? 'The world confirmed the action.' : 'The world rejected the action.' ),
+      mode:             'external',
+      tick,
+      reconciled:       true,
+      ...( provenance.planId ? { planId: provenance.planId } : {} ),
+      ...( provenance.stepId ? { stepId: provenance.stepId } : {} ),
+    },
+  }
+}
+
+function clamp01( n: number ): number {
+  return n < 0 ? 0 : n > 1 ? 1 : n
+}

package/src/cognition/agency/schemas/external.ts

@@ -0,0 +1,59 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/schemas/external.ts  —  host-owned domain effectors
+// ─────────────────────────────────────────────────────────────
+//
+// A host (game engine, app, robot) declares the domain effectors its world
+// supports — `move`, `attack`, `trade`, `give`, `use`, … — via a profile's
+// `effectors` list or the Will's `allowedGenericEffectors`. This turns those
+// declarations into enactable MotorSchemas so they enter the agency loop like
+// anything else: the AffordanceSynthesizer surfaces them in the field, the
+// ActionSelector competes them, and the MotorSchemaExecutor routes the chosen
+// one to the host via the `external` enaction mode (emitted now, acked later,
+// the result returning as reafference the Will learns from).
+//
+// Excluded: the communication surface (listen/talk/text/gesture/broadcast),
+// which is governed by AccessGrants + the ProactiveCommunicator; and any name
+// that shadows an innate stance (the innate floor already provides it).
+//
+// Scope (Phase 1): objectless schemas — the Will chooses the act and the host
+// resolves the target. Entity-bound external effectors (e.g. attack a specific
+// perceived entity) are a follow-up; the synthesizer currently binds a single
+// entity schema. See CUSTOM_EFFECTOR_WIRING_TODO.md.
+// ─────────────────────────────────────────────────────────────
+
+import type { MotorSchema } from '#agency/types'
+import { EXPLICIT_EFFECTORS } from '#agency/access.grants'
+import { INNATE_SCHEMA_BY_ID } from '#agency/schemas/innate'
+
+/** Default effort/energy demand for a host action when none is specified. */
+const DEFAULT_EXTERNAL_COST = 0.15
+
+/**
+ * Build enactable MotorSchemas for a host's declared domain effectors. Comms
+ * names and innate-shadowing names are filtered out; the rest become objectless,
+ * `external`-tagged primitives that route to the host on enaction.
+ */
+export function externalSchemas( effectors?: string[] | null ): MotorSchema[] {
+  const seen = new Set<string>()
+  const out:  MotorSchema[] = []
+
+  for( const name of effectors ?? [] ){
+    if( typeof name !== 'string' || name.length === 0 ) continue
+    if( EXPLICIT_EFFECTORS.has( name ) )  continue   // communication — handled by AccessGrants
+    if( INNATE_SCHEMA_BY_ID.has( name ) ) continue   // shadows an innate stance
+    if( seen.has( name ) )                continue
+    seen.add( name )
+
+    out.push({
+      id:          name,
+      kind:        'primitive',
+      source:      'external',
+      cost:        DEFAULT_EXTERNAL_COST,
+      binds:       'none',
+      baseValence: 0,
+      tags:        [ 'external', 'host' ],
+    })
+  }
+
+  return out
+}

package/src/cognition/agency/schemas/innate.ts

@@ -0,0 +1,111 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/schemas/innate.ts  —  the always-on floor of the field
+// ─────────────────────────────────────────────────────────────
+//
+// Innate schemas are the reflexive floor of agency — the possibilities a mind
+// always has available simply by being an embodied perceiver, before it has
+// learned anything. Most need no object (orient, rest, reflect); two bind to
+// what perception surfaces (`inspect` a percept, `reach-out` to a known mind).
+//
+// This is NOT a catalog the executive picks from. It is the seed set the
+// AffordanceSynthesizer draws on so the field is never empty; learned composite
+// schemas (Phase 3) are layered on top via the repertoire.
+// ─────────────────────────────────────────────────────────────
+
+import type { MotorSchema } from '#agency/types'
+
+export const INNATE_SCHEMAS: MotorSchema[] = [
+  // ── objectless stances ───────────────────────────────────────
+  {
+    id:         'orient',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.05,
+    baseValence: 0.0,
+    tags:       [ 'perception', 'reflexive' ],
+  },
+  {
+    id:         'attend',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.08,
+    preconditions: [ { metric: 'energy.level', op: 'gt', value: 10 } ],
+    baseValence: 0.0,
+    tags:       [ 'attention', 'meta-cognition' ],
+  },
+  {
+    id:         'rest',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.0,
+    preconditions: [ { metric: 'energy.level', op: 'lt', value: 95 } ],
+    baseValence: 0.15,
+    tags:       [ 'self-care', 'regulatory' ],
+  },
+  {
+    id:         'withdraw',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.03,
+    baseValence: 0.05,
+    tags:       [ 'self-protection', 'regulatory' ],
+  },
+  {
+    id:         'reflect',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.06,
+    preconditions: [ { metric: 'energy.level', op: 'gt', value: 10 } ],
+    baseValence: 0.05,
+    tags:       [ 'cognitive', 'meta-cognition', 'internal' ],
+  },
+  {
+    id:         'wait',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.01,
+    baseValence: 0.0,
+    tags:       [ 'neutral' ],
+  },
+  {
+    id:         'express',
+    kind:       'primitive',
+    source:     'innate',
+    binds:      'none',
+    cost:       0.02,
+    baseValence: 0.1,
+    tags:       [ 'affective', 'expression' ],
+  },
+
+  // ── perception-bound possibilities ───────────────────────────
+  {
+    id:         'inspect',
+    kind:       'primitive',
+    source:     'perceptual',
+    binds:      'percept',
+    cost:       0.06,
+    preconditions: [ { metric: 'energy.level', op: 'gt', value: 8 } ],
+    baseValence: 0.05,
+    tags:       [ 'perception', 'information' ],
+  },
+  {
+    id:         'reach-out',
+    kind:       'primitive',
+    source:     'social',
+    binds:      'entity',
+    cost:       0.1,
+    preconditions: [ { metric: 'energy.level', op: 'gt', value: 5 } ],
+    baseValence: 0.2,
+    tags:       [ 'social', 'communication' ],
+  },
+]
+
+/** Fast id → schema lookup over the innate floor. */
+export const INNATE_SCHEMA_BY_ID: ReadonlyMap<string, MotorSchema> =
+  new Map( INNATE_SCHEMAS.map( s => [ s.id, s ] ) )