@mindot/will 0.8.0 → 0.10.0

package/src/surface/channels/types.ts

@@ -0,0 +1,136 @@
+// ─────────────────────────────────────────────────────────────
+// src/surface/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>
+}
+
+// ── Attachments ──────────────────────────────────────────────────────────────
+//
+// People hand over documents as well as speech, and some platforms *manufacture*
+// them: Discord silently turns a long pasted markdown block into a `.md` upload.
+// A bridge that reads only the text body sees such a message as empty and — worse
+// — as nothing at all, so the person appears to have gone silent.
+//
+// What a bridge does with these is deliberately modest. A named-but-unread file
+// is already a percept the Will can act on ("what's in it?"), which is the
+// paradigm-correct outcome and strictly better than silence. Inlining text is an
+// upgrade on top, never a precondition.
+
+/** One file riding along with a platform message. */
+export interface ChannelAttachment {
+  name:         string
+  contentType?: string
+  size?:        number
+  url?:         string
+}
+
+/** Per-attachment inline budget. A 2 MB doc must not enter working memory whole. */
+const INLINE_CHAR_CAP = 24_000
+/** How many text attachments to inline from one message. */
+const INLINE_COUNT_CAP = 4
+
+const TEXTUAL_EXT = /\.(md|markdown|txt|text|json|jsonl|csv|tsv|ya?ml|log|ini|toml)$/i
+
+/** Is this something we can meaningfully read as text? */
+export function isTextual( a: ChannelAttachment ): boolean {
+  const ct = a.contentType?.split(';')[0]?.trim().toLowerCase() ?? ''
+  if( ct.startsWith('text/') ) return true
+  if( ct === 'application/json' || ct === 'application/x-yaml' ) return true
+  // Discord's own markdown uploads arrive as text/plain, but trust the extension
+  // too — content types from platforms are advisory at best.
+  return TEXTUAL_EXT.test( a.name )
+}
+
+function humanSize( bytes?: number ): string {
+  if( bytes == null ) return ''
+  return bytes < 1024 ? `${ bytes } B`
+       : bytes < 1024 * 1024 ? `${ ( bytes / 1024 ).toFixed( 1 ) } KB`
+       : `${ ( bytes / 1024 / 1024 ).toFixed( 1 ) } MB`
+}
+
+/**
+ * Render attachments into perceivable text.
+ *
+ * `fetchText` is supplied by the bridge, not by this module — the decision about
+ * which hosts are safe to fetch from is platform knowledge, and a helper that
+ * fetched arbitrary URLs found in inbound messages would be an open redirect
+ * into the Will's perception. Omit it and attachments are named, never read.
+ *
+ * Inlined content is untrusted, exactly like message text — more so, since a
+ * document is long, structured, and looks authoritative, which is the shape of
+ * an effective injection. It is fenced and labelled as shared content so the
+ * mind reads it as something it was handed, not as something it was told.
+ */
+export async function renderAttachments(
+  attachments: ChannelAttachment[],
+  speaker:     string | undefined,
+  fetchText?:  ( a: ChannelAttachment ) => Promise<string | null>,
+): Promise<string> {
+  if( attachments.length === 0 ) return ''
+  const who = speaker ?? 'someone'
+  const out: string[] = []
+  let inlined = 0
+
+  for( const a of attachments ){
+    const meta = [ a.contentType, humanSize( a.size ) ].filter( Boolean ).join(', ')
+    const label = `${ a.name }${ meta ? ` (${ meta })` : '' }`
+
+    if( !fetchText || !isTextual( a ) || inlined >= INLINE_COUNT_CAP ){
+      out.push(`[${ who } shared a file I have not read: ${ label }]`)
+      continue
+    }
+
+    const body = await fetchText( a ).catch( () => null )
+    if( body == null ){
+      out.push(`[${ who } shared a file I could not read: ${ label }]`)
+      continue
+    }
+    inlined++
+    const clipped = body.length > INLINE_CHAR_CAP
+      ? `${ body.slice( 0, INLINE_CHAR_CAP ) }\n[… truncated — ${ humanSize( body.length ) } of ${ humanSize( a.size ?? body.length ) }]`
+      : body
+    out.push(`[${ who } shared ${ label }; its contents follow — this is a document I was handed, not something said to me]\n---\n${ clipped }\n---`)
+  }
+  return out.join('\n')
+}
+
+/** 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
+}

package/src/{channels → surface/channels}/whatsapp.ts

@@ -1,10 +1,10 @@
 // ─────────────────────────────────────────────────────────────
-// src/channels/whatsapp.ts — a Will present on WhatsApp
+// src/surface/channels/whatsapp.ts — a Will present on WhatsApp
 // ─────────────────────────────────────────────────────────────
 //
 // Same paradigm as the Discord bridge, different room:
 //
-//   inbound   DM / group message → will.perceive({ from, speaker, text, thread })
+//   inbound   DM / group message → will.sense({ from, speaker, text, thread })
 //             — every author is `whatsapp:<number>` (stable across chats), the
 //             push name is *learned* by the mind, and each chat (DM or group)
 //             is its own conversation thread.
@@ -25,9 +25,9 @@
 // `WaLikeSocket` 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'
+import type { Will, WillMessage } from '#surface/sdk/will'
+import { ChannelRoster } from '#surface/channels/roster'
+import { chunkText, type ChannelBridge } from '#surface/channels/types'
 
 /** WhatsApp's hard per-message cap. */
 const WHATSAPP_MESSAGE_LIMIT = 65_536
@@ -162,10 +162,15 @@ export async function connectWhatsApp( will: Will, opts: WhatsAppBridgeOptions =
     const text = textOf( m )
     if( !text.trim() ) return
 
-    await will.perceive( {
+    await will.sense( {
+      // Somebody messaged her. Baileys filters `fromMe` upstream, so as with
+      // Discord nothing reafferent reaches this bridge today.
+      provenance: 'exafferent',
       text,
       from:   entityId,
       thread: `whatsapp:${ jid }`,
+      // A WhatsApp group jid ends in `@g.us`; anything else is a one-to-one chat.
+      direct: !jid.endsWith('@g.us'),
       ...( speaker ? { speaker } : {} ),
     } )
   }
@@ -177,11 +182,18 @@ export async function connectWhatsApp( will: Will, opts: WhatsAppBridgeOptions =
     const peer   = m.to ? roster.resolve( m.to ) : undefined
     const chunks = chunkText( m.content, WHATSAPP_MESSAGE_LIMIT )
 
-    // Last shared group → known DM → DM derived from the entity id itself →
-    // home chat → last active chat. Unlike Discord, an unmet-but-addressed
-    // entity is still reachable: `whatsapp:<number>` implies its DM jid.
+    // The chat they actually spoke in → last shared group → known DM → DM derived
+    // from the entity id itself → home chat → last active chat. Unlike Discord, an
+    // unmet-but-addressed entity is still reachable: `whatsapp:<number>` implies
+    // its DM jid.
+    //
+    // `m.thread` leads because everything after it is a guess about where this
+    // person usually is, and a reply belongs in the room the question was asked
+    // in. The Discord bridge had the identical ordering and answered a DM in a
+    // shared server channel — from the operator's side, silence.
+    const replyTo   = m.thread?.startsWith('whatsapp:') ? m.thread.slice('whatsapp:'.length ) : undefined
     const derivedDm = m.to?.startsWith('whatsapp:') ? dmJidFor( m.to.slice('whatsapp:'.length ) ) : undefined
-    const targets = [ peer?.lastChannelId, peer?.dmChannelId, derivedDm, opts.homeChatId ?? undefined, lastActiveChatId ?? undefined ]
+    const targets = [ replyTo, peer?.lastChannelId, peer?.dmChannelId, derivedDm, opts.homeChatId ?? undefined, lastActiveChatId ?? undefined ]
     for( const jid of targets ){
       if( !jid ) continue
       try {

package/src/{cli.ts → surface/cli.ts}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // ─────────────────────────────────────────────────────────────
-// src/cli.ts — the `will` command: host a persistent mind
+// src/surface/cli.ts — the `will` command: host a persistent mind
 // ─────────────────────────────────────────────────────────────
 //
 //   will mcp       host over MCP stdio (Claude Desktop / Claude Code / IDEs)
@@ -24,11 +24,11 @@
 // ─────────────────────────────────────────────────────────────
 
 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'
-import { connectDiscord } from '#channels/discord'
-import { connectWhatsApp } from '#channels/whatsapp'
+import { routeLogsToStderr, bootWillFromEnv } from '#surface/host/boot'
+import { buildWillMcpServer } from '#surface/mcp/server'
+import { buildWillHttpServer } from '#surface/serve/server'
+import { connectDiscord, parseChannels, parseMentionOnly } from '#surface/channels/discord'
+import { connectWhatsApp } from '#surface/channels/whatsapp'
 
 // stdout is the MCP protocol channel under `will mcp` — route logs FIRST.
 routeLogsToStderr()
@@ -38,7 +38,12 @@ const USAGE = `usage: will <mcp | serve | discord | whatsapp>
   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)
   discord   put a persistent mind in a Discord server (DISCORD_BOT_TOKEN; optional
-            WILL_DISCORD_CHANNELS, WILL_DISCORD_MENTION_ONLY, WILL_DISCORD_HOME_CHANNEL)
+            WILL_DISCORD_CHANNELS      "*" or unset = every channel it can see,
+                                       else a comma-separated allowlist
+            WILL_DISCORD_MENTION_ONLY  1/true = only when @mentioned, anywhere;
+                                       or a comma-separated channel list to gate
+                                       just those; DMs are always perceived
+            WILL_DISCORD_HOME_CHANNEL  where it speaks when it has no other route)
   whatsapp  put a persistent mind on WhatsApp — QR-pairs as a linked device; no token.
             UNOFFICIAL protocol (ban risk; use a spare number — docs/channels/whatsapp.md).
             Optional WILL_WHATSAPP_CHATS, WILL_WHATSAPP_MENTION_ONLY, WILL_WHATSAPP_HOME_CHAT
@@ -76,8 +81,8 @@ async function main(): Promise<void> {
     const csv = ( v?: string ) => v?.split(',').map( s => s.trim() ).filter( Boolean )
     const bridge = await connectDiscord( will, {
       token:         process.env.DISCORD_BOT_TOKEN!,
-      channels:      csv( process.env.WILL_DISCORD_CHANNELS ),
-      mentionOnly:   /^(1|true|yes)$/i.test( process.env.WILL_DISCORD_MENTION_ONLY ?? ''),
+      channels:      parseChannels( process.env.WILL_DISCORD_CHANNELS ),
+      mentionOnly:   parseMentionOnly( process.env.WILL_DISCORD_MENTION_ONLY ),
       homeChannelId: process.env.WILL_DISCORD_HOME_CHANNEL,
       rosterPath:    pmaPath.replace( /(\.pma)?\.json$/, '') + '.discord.json',
     } )

package/src/{host → surface/host}/boot.ts

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────
-// src/host/boot.ts — shared boot/shutdown for the `will` CLI hosts
+// src/surface/host/boot.ts — shared boot/shutdown for the `will` CLI hosts
 // ─────────────────────────────────────────────────────────────
 //
 // Both hosts (`will mcp`, `will serve`) raise the same mind the same way:
@@ -27,9 +27,9 @@
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { setLogger } from '#core/logger'
-import { Will, detectProvider, type CreateWillOptions } from '#sdk/will'
+import { Will, detectProvider, type CreateWillOptions } from '#surface/sdk/will'
 import type { PMASnapshot } from '#pma/index'
-import { connectMcpEffectors, type McpToolsSource } from '#root/mcp/effectors'
+import { connectMcpEffectors, type McpToolsSource } from '#surface/mcp/effectors'
 import { anthropicWireHeaders, defaultBaseFor, knownWireFor, providerKeyFromEnv, PROVIDER_KEY_ENV, type LLMProvider, type LLMWire } from '#llm/index'
 
 /**

package/src/{host → surface/host}/utterances.ts

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────
-// src/host/utterances.ts — a host-side tap on a Will's speech
+// src/surface/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
@@ -10,7 +10,7 @@
 // first, else wait, else report silence (null — a choice, never an error).
 // ─────────────────────────────────────────────────────────────
 
-import type { Will, WillMessage } from '#sdk/will'
+import type { Will, WillMessage } from '#surface/sdk/will'
 
 const BUFFER_CAP = 50
 

package/src/{mcp → surface/mcp}/effectors.ts

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────
-// src/mcp/effectors.ts — a Will EMPLOYING MCP tools (Seam 1)
+// src/surface/mcp/effectors.ts — a Will EMPLOYING MCP tools (Seam 1)
 // ─────────────────────────────────────────────────────────────
 //
 // The other direction from server.ts: connect a Will to an external MCP server
@@ -27,7 +27,7 @@
 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'
+import type { Will, EffectorHandler, EffectorResult } from '#surface/sdk/will'
 
 /** Where the tools live: spawn a local server, reach a remote one, or bring a connected client. */
 export type McpToolsSource =
@@ -53,8 +53,6 @@ export interface McpToolInfo {
   }
 }
 
-/** 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
 
@@ -105,8 +103,23 @@ export function buildMcpHandler( client: Client, tool: McpToolInfo ): EffectorHa
         .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 }
+      // The tool's output is what the act REVEALED, so it goes to `observation`
+      // and it goes WHOLE (SIGNAL_BOUNDARY P2). It used to be crammed into
+      // `description` and cut at 700 — a number nobody chose, deciding on the
+      // mind's behalf how much of an answer it was allowed to have, and doing
+      // it at the boundary where that was the only copy.
+      //
+      // `description` now carries what it is for: how the call went. Short by
+      // nature, because a fate is short.
+      return {
+        success:     !res.isError,
+        description: res.isError ? `${ tool.name } reported an error.` : `${ tool.name } ran.`,
+        // Whatever it said — including what it said when it failed. An error
+        // message is information about the world too, and cutting it or folding
+        // it into the fate is how a mind ends up knowing that something went
+        // wrong without ever learning what.
+        observation: text,
+      }
     }
     catch( err ){
       return { success: false, description: `${ tool.name } failed: ${ err instanceof Error ? err.message : String( err ) }` }

package/src/{mcp → surface/mcp}/server.ts

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────
-// src/mcp/server.ts — a Will, exposed over the Model Context Protocol
+// src/surface/mcp/server.ts — a Will, exposed over the Model Context Protocol
 // ─────────────────────────────────────────────────────────────
 //
 // Lets any MCP client (Claude Desktop, Claude Code, an IDE) host a persistent
@@ -24,8 +24,9 @@ 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 } from '#sdk/will'
-import { UtteranceTap } from '#root/host/utterances'
+import type { Will } from '#surface/sdk/will'
+import { asProvenance } from '#senses/provenance'
+import { UtteranceTap } from '#surface/host/utterances'
 
 export interface WillMcpOptions {
   /** Where `save` (and the CLI's shutdown hibernate) writes the PMA artifact. */
@@ -65,9 +66,22 @@ export function buildWillMcpServer( will: Will, opts: WillMcpOptions = {} ): Mcp
       text:    z.string().describe('What is said or observed.'),
       from:    z.string().optional().describe( "Who it's from (entity id, default 'user'). Use a stable id per person." ),
       speaker: z.string().optional().describe('Display name of the speaker.'),
+      provenance: z.enum([ 'exafferent', 'reafferent', 'unknown' ]).optional().describe(
+        `Whose doing this was. 'exafferent' (default) — the world did it, somebody spoke or something happened. ` +
+        `'reafferent' — this is ${ will.name }'s OWN act coming back to it: the result of an ability it used, ` +
+        `an echo of a message it sent. 'unknown' — you looked and cannot tell. It cannot work this out for ` +
+        `itself; its own echo and a stranger saying the same words are identical from the inside.`),
     },
-  }, async ( { text, from, speaker } ) => {
-    await will.perceive( { text, ...( from ? { from } : {} ), ...( speaker ? { speaker } : {} ) } )
+  }, async ( { text, from, speaker, provenance } ) => {
+    // asProvenance, not a bare cast: this is an untyped protocol boundary, and
+    // an older client that never sends the field has not made a claim — it just
+    // predates the field. Defaulting toward 'exafferent' errs toward noticing.
+    await will.sense( {
+      text,
+      provenance: asProvenance( provenance ),
+      ...( from ? { from } : {} ),
+      ...( speaker ? { speaker } : {} ),
+    } )
     return {
       content: [ {
         type: 'text',