@mindot/will 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindot/will",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "author": "Fabrice <fabrice8@github.com>",
   "repository": {
     "type": "git",
@@ -21,6 +21,9 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
+    "baileys": "^7.0.0-rc13",
+    "discord.js": "^14.16.3",
+    "qrcode-terminal": "^0.12.0",
     "socket.io-client": "^4.8.1"
   },
   "exports": {
@@ -31,16 +34,27 @@
     "./mcp": {
       "import": "./dist/mcp/effectors.js",
       "types": "./dist/mcp/effectors.d.ts"
+    },
+    "./discord": {
+      "import": "./dist/channels/discord.js",
+      "types": "./dist/channels/discord.d.ts"
+    },
+    "./whatsapp": {
+      "import": "./dist/channels/whatsapp.js",
+      "types": "./dist/channels/whatsapp.d.ts"
     }
   },
   "bugs": {
     "url": "https://github.com/mindot-ai/will/issues"
   },
-  "description": "Will — an engine for persistent machine minds. A Will is a continuously-ticking synthetic mind built from 38 cognitive faculties, a learning agency pipeline, and a dual-process executive — deterministic, persistent, and portable (PMA).",
+  "description": "Will \u2014 an engine for persistent machine minds. A Will is a continuously-ticking synthetic mind built from 38 cognitive faculties, a learning agency pipeline, and a dual-process executive \u2014 deterministic, persistent, and portable (PMA).",
   "engines": {
     "bun": ">=1.0.0"
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "homepage": "https://github.com/mindot-ai/will#readme",
   "keywords": [
     "ai",

package/src/channels/discord.ts

@@ -0,0 +1,214 @@
+// ─────────────────────────────────────────────────────────────
+// src/channels/discord.ts — a Will present in a Discord server
+// ─────────────────────────────────────────────────────────────
+//
+// The bridge relays both directions of the paradigm and nothing else:
+//
+//   inbound   guild/DM message → will.perceive({ from, speaker, text, thread })
+//             — every author is `discord:<userId>` (stable across guilds), the
+//             display name is *learned* by the mind, and each Discord channel
+//             is its own conversation thread.
+//   outbound  will.on('message') → the addressee's last shared channel, else
+//             their DM, else the home channel. Proactive utterances (the mind
+//             speaking first) route the same way — that is the point.
+//
+// The Will decides when to speak. There is no command prefix and no forced
+// reply: unaddressed chatter is perceived (salience-scored by audition) and
+// silence is a valid outcome. `mentionOnly` narrows perception for busy
+// servers; it does not turn the bridge into an ask() surface.
+//
+// discord.js is imported lazily inside `createDiscordClient` — tests (and any
+// host that brings its own client) inject `client`, and the structural
+// `DiscordLikeClient` type keeps the dependency out of the type graph.
+// ─────────────────────────────────────────────────────────────
+
+import type { Will, WillMessage } from '#sdk/will'
+import { ChannelRoster } from '#channels/roster'
+import { chunkText, type ChannelBridge } from '#channels/types'
+
+const DISCORD_MESSAGE_LIMIT = 2000
+
+// ── The slice of discord.js the bridge actually uses (structural) ───────────
+
+export interface DiscordLikeChannel {
+  send( content: string ): Promise<unknown>
+  sendTyping?(): Promise<unknown>
+}
+
+export interface DiscordLikeMessage {
+  content: string
+  cleanContent?: string
+  channelId: string
+  guildId?: string | null
+  author: { id: string; bot?: boolean; username?: string; displayName?: string }
+  member?: { displayName?: string } | null
+  mentions?: { has( userId: string ): boolean }
+  channel: DiscordLikeChannel
+}
+
+export interface DiscordLikeClient {
+  user: { id: string; setPresence?( p: unknown ): void } | null
+  /** discord.js ≥14.22; polled so we needn't subscribe to the deprecated `ready`. */
+  isReady?(): boolean
+  on( event: 'messageCreate', fn: ( m: DiscordLikeMessage ) => void ): unknown
+  once( event: string, fn: () => void ): unknown
+  login( token: string ): Promise<unknown>
+  destroy(): Promise<unknown> | void
+  channels: { fetch( id: string ): Promise<unknown> }
+  users: { fetch( id: string ): Promise<{ send( content: string ): Promise<unknown> }> }
+}
+
+// ── Options ──────────────────────────────────────────────────────────────────
+
+export interface DiscordBridgeOptions {
+  /** Bot token (Discord developer portal). Unused when `client` is injected pre-logged-in. */
+  token?: string
+  /** Channel ids the Will inhabits. Unset = every channel it can see. */
+  channels?: string[]
+  /** Perceive guild messages only when the Will is @mentioned (DMs always perceived). */
+  mentionOnly?: boolean
+  /** Fallback channel for utterances with no reachable addressee. */
+  homeChannelId?: string
+  /** Roster path (default: ./.will/<willId>.discord.json). */
+  rosterPath?: string
+  /** Test / power-user seam: bring your own client; discord.js is never imported. */
+  client?: DiscordLikeClient
+  log?: ( msg: string ) => void
+}
+
+// ── The bridge ───────────────────────────────────────────────────────────────
+
+/**
+ * Connect a Will to Discord. Resolves once the bridge is live (logged in and
+ * relaying). Close it via the returned `ChannelBridge.close()` — the Will
+ * itself is not stopped; it simply loses this surface.
+ */
+export async function connectDiscord( will: Will, opts: DiscordBridgeOptions ): Promise<ChannelBridge> {
+  const log     = opts.log ?? ( ( m: string ) => console.error( `[will:discord] ${ m }` ) )
+  const roster  = new ChannelRoster( opts.rosterPath ?? `.will/${ will.id }.discord.json` )
+  const allowed = opts.channels?.length ? new Set( opts.channels ) : null
+
+  const client = opts.client ?? await createDiscordClient()
+
+  /** The most recently active allowed channel — last-resort proactive target. */
+  let lastActiveChannelId: string | null = opts.homeChannelId ?? null
+
+  // ── inbound: platform message → stimulus ──────────────────────────────────
+  client.on( 'messageCreate', message => { void onMessage( message ) } )
+
+  async function onMessage( message: DiscordLikeMessage ): Promise<void> {
+    const self = client.user
+    if( !self || message.author.id === self.id || message.author.bot ) return
+
+    const isDM = !message.guildId
+    if( !isDM && allowed && !allowed.has( message.channelId ) ) return
+
+    const addressed = isDM || ( message.mentions?.has( self.id ) ?? false )
+    if( opts.mentionOnly && !addressed ) return
+
+    const entityId = `discord:${ message.author.id }`
+    const speaker  = message.member?.displayName ?? message.author.displayName ?? message.author.username
+
+    roster.record( {
+      entityId,
+      userId: message.author.id,
+      ...( speaker ? { displayName: speaker } : {} ),
+      ...( isDM ? { dmChannelId: message.channelId } : { lastChannelId: message.channelId } ),
+    } )
+    if( !isDM ) lastActiveChannelId = message.channelId
+
+    // Being addressed is the one moment a presence cue is honest — the mind
+    // may still choose silence, and typing expires on its own.
+    if( addressed ) await message.channel.sendTyping?.().catch( () => {} )
+
+    const text = message.cleanContent || message.content
+    if( !text.trim() ) return
+
+    await will.perceive( {
+      text,
+      from:   entityId,
+      thread: `discord:${ message.channelId }`,
+      ...( speaker ? { speaker } : {} ),
+    } )
+  }
+
+  // ── outbound: projected utterance → the addressee ─────────────────────────
+  // The facade has no off(); the bridge gates its handler on `closed` instead.
+  let closed = false
+  will.on( 'message', ( m: WillMessage ) => { if( !closed ) void deliver( m ) } )
+
+  async function deliver( m: WillMessage ): Promise<void> {
+    const peer = m.to ? roster.resolve( m.to ) : undefined
+    const chunks = chunkText( m.content, DISCORD_MESSAGE_LIMIT )
+
+    // Preference order: where we last shared a room → their DM → home channel.
+    const channelIds = [ peer?.lastChannelId, peer?.dmChannelId, opts.homeChannelId ?? undefined, lastActiveChannelId ?? undefined ]
+    for( const id of channelIds ){
+      if( !id ) continue
+      try {
+        const channel = await client.channels.fetch( id ) as DiscordLikeChannel | null
+        if( !channel?.send ) continue
+        for( const chunk of chunks ) await channel.send( chunk )
+        return
+      }
+      catch { /* try the next route */ }
+    }
+    if( peer ){
+      try {
+        const user = await client.users.fetch( peer.userId )
+        for( const chunk of chunks ) await user.send( chunk )
+        return
+      }
+      catch { /* fall through */ }
+    }
+    log( `no route for utterance to '${ m.to }' — dropped (${ m.content.length } chars)` )
+  }
+
+  // ── lifecycle ──────────────────────────────────────────────────────────────
+  const bridge: ChannelBridge = {
+    kind: 'discord',
+    async start(): Promise<void> {
+      if( !client.user ){
+        // discord.js ≥14.22 renamed `ready` → `clientReady`. Subscribing to the
+        // old name is what triggers its DeprecationWarning, so we take the new
+        // name and poll `isReady()` for older builds rather than listening.
+        const ready = new Promise<void>( resolve => {
+          let poll: ReturnType<typeof setInterval> | null = null
+          const done = (): void => { if( poll ) clearInterval( poll ); resolve() }
+          client.once( 'clientReady', done )
+          poll = setInterval( () => { if( client.isReady?.() ) done() }, 100 )
+          poll.unref?.()
+        } )
+        await client.login( opts.token ?? '' )
+        await ready
+      }
+      log( `${ will.name } is present on Discord as user ${ client.user?.id }` )
+    },
+    async close(): Promise<void> {
+      if( closed ) return
+      closed = true
+      roster.flush()
+      await Promise.resolve( client.destroy() ).catch( () => {} )
+    },
+  }
+  return bridge
+}
+
+/** Build a real discord.js client (lazy import keeps it out of non-Discord hosts). */
+async function createDiscordClient(): Promise<DiscordLikeClient> {
+  let mod: typeof import( 'discord.js' )
+  try { mod = await import( 'discord.js' ) }
+  catch {
+    throw new Error( 'discord.js is not installed (it is an optionalDependency) — run `bun add discord.js` / `npm i discord.js` and retry.' )
+  }
+  const { Client, GatewayIntentBits, Partials } = mod
+  return new Client( {
+    intents: [
+      GatewayIntentBits.Guilds,
+      GatewayIntentBits.GuildMessages,
+      GatewayIntentBits.MessageContent,
+      GatewayIntentBits.DirectMessages,
+    ],
+    partials: [ Partials.Channel ],   // DMs arrive on uncached channels
+  } ) as unknown as DiscordLikeClient
+}

package/src/channels/roster.ts

@@ -0,0 +1,87 @@
+// ─────────────────────────────────────────────────────────────
+// src/channels/roster.ts — who the Will knows on a platform, and where
+// ─────────────────────────────────────────────────────────────
+//
+// The mind knows *entities*; a platform knows user ids and channels. The roster
+// is the durable seam between them: for each entity the Will has met on a
+// channel it records how to reach them again — so a *proactive* utterance
+// (`message.to` from the mind's own initiative) can find its person after a
+// restart, not just within one session.
+//
+// It persists as a small JSON file next to the PMA artifact. Writes are
+// throttled (the file is advisory routing state, not cognition — losing the
+// last few seconds costs a fallback delivery, never memory).
+// ─────────────────────────────────────────────────────────────
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** How to reach one entity on the platform. */
+export interface RosterEntry {
+  /** The mind-side entity id, e.g. 'discord:80351110224678912'. */
+  entityId: string
+  /** The platform-side user id. */
+  userId: string
+  /** Last display name seen (advisory — the *learned* name lives in the mind). */
+  displayName?: string
+  /** DM channel id, once one is known. */
+  dmChannelId?: string
+  /** Last shared (guild) channel this entity spoke in. */
+  lastChannelId?: string
+  /** Epoch ms of the last message seen from them. */
+  lastSeenAt: number
+}
+
+const FLUSH_MS = 2_000
+
+export class ChannelRoster {
+  private entries = new Map<string, RosterEntry>()
+  private dirty = false
+  private timer: ReturnType<typeof setTimeout> | null = null
+
+  constructor( private readonly path: string ) {
+    if( existsSync( path ) ){
+      try {
+        const raw = JSON.parse( readFileSync( path, 'utf8' ) ) as RosterEntry[]
+        for( const e of Array.isArray( raw ) ? raw : [] ) this.entries.set( e.entityId, e )
+      }
+      catch { /* a corrupt roster is not worth failing a boot over — start fresh */ }
+    }
+  }
+
+  /** Upsert what we just learned about an entity; schedules a throttled flush. */
+  record( update: { entityId: string; userId: string } & Partial<Omit<RosterEntry, 'entityId' | 'userId'>> ): RosterEntry {
+    const prev = this.entries.get( update.entityId )
+    const next: RosterEntry = {
+      lastSeenAt: Date.now(),
+      ...prev,
+      ...Object.fromEntries( Object.entries( update ).filter( ( [ , v ] ) => v !== undefined ) ) as typeof update,
+    }
+    this.entries.set( next.entityId, next )
+    this.dirty = true
+    if( !this.timer ){
+      this.timer = setTimeout( () => { this.timer = null; this.flush() }, FLUSH_MS )
+      this.timer.unref?.()
+    }
+    return next
+  }
+
+  resolve( entityId: string ): RosterEntry | undefined {
+    return this.entries.get( entityId )
+  }
+
+  all(): RosterEntry[] {
+    return [ ...this.entries.values() ]
+  }
+
+  /** Write to disk now (no-op when clean). Called by bridges on close. */
+  flush(): void {
+    if( !this.dirty ) return
+    try {
+      mkdirSync( dirname( this.path ), { recursive: true } )
+      writeFileSync( this.path, JSON.stringify( this.all(), null, 2 ) )
+      this.dirty = false
+    }
+    catch { /* advisory state — never take the mind down over it */ }
+  }
+}

package/src/channels/types.ts

@@ -0,0 +1,46 @@
+// ─────────────────────────────────────────────────────────────
+// src/channels/types.ts — the channel-bridge contract
+// ─────────────────────────────────────────────────────────────
+//
+// A channel bridge puts a Will *in a place where people already are* (Discord,
+// Telegram, Slack, …). It is a host surface, not a cognition surface: it turns
+// platform messages into `perceive` stimuli and delivers the Will's projected
+// utterances back — nothing more. The paradigm survives the crossing:
+//
+//   • every platform user is an entity the Will comes to know (`from`),
+//     with a *learned* name (`speaker`) — never a placeholder;
+//   • every platform channel/DM is a conversation thread (`thread`);
+//   • the Will decides when to speak. Silence is a valid outcome, so a
+//     bridge never fabricates a reply and never times a message out into
+//     an error.
+//
+// Bridges live at the same altitude as the MCP/HTTP hosts (src/mcp, src/serve):
+// they wrap the SDK facade, not the stem.
+// ─────────────────────────────────────────────────────────────
+
+/** A running connection between one Will and one platform. */
+export interface ChannelBridge {
+  /** Platform kind, e.g. 'discord'. */
+  readonly kind: string
+  /** Connect and start relaying. Resolves once the bridge is live. */
+  start(): Promise<void>
+  /** Disconnect and release resources. Idempotent. */
+  close(): Promise<void>
+}
+
+/** Split a message into platform-sized chunks on natural boundaries. */
+export function chunkText( text: string, max: number ): string[] {
+  if( text.length <= max ) return [ text ]
+  const chunks: string[] = []
+  let rest = text
+  while( rest.length > max ){
+    // Prefer a paragraph break, then a line break, then a space — else hard-cut.
+    const window = rest.slice( 0, max )
+    const cut = Math.max( window.lastIndexOf( '\n\n' ), window.lastIndexOf( '\n' ), window.lastIndexOf( ' ' ) )
+    const at = cut > max * 0.5 ? cut : max
+    chunks.push( rest.slice( 0, at ).trimEnd() )
+    rest = rest.slice( at ).trimStart()
+  }
+  if( rest ) chunks.push( rest )
+  return chunks
+}