@mindot/will 0.9.0 → 0.10.0

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',

package/src/{sdk → surface/sdk}/will.ts

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────
-// src/sdk/will.ts — the ergonomic facade
+// src/surface/sdk/will.ts — the ergonomic facade
 // ─────────────────────────────────────────────────────────────
 //
 // `WillStem` is the full, powerful contract (tick listeners, the outbox drain,
@@ -9,11 +9,11 @@
 //   const will = await Will.create({ name: 'Aria', identity: {...} })
 //   will.on('message', m => console.log(m.content))
 //   will.effector('search_docs', async a => await myDb.search(a.query))
-//   await will.perceive({ from: 'ada', text: 'What should we work on?' })
+//   await will.sense({ from: 'ada', text: 'What should we work on?', provenance: 'exafferent' })
 //   const reply = await will.nextUtterance({ to: 'ada' })   // WillMessage | null
 //   const pma = await will.save()               // non-destructive; keeps ticking
 //
-// A Will is a *subject*, not a function: you `perceive` stimuli to it and observe
+// A Will is a *subject*, not a function: you `sense` stimuli to it and observe
 // its *projections* (message / effector / emotion / state) — you never `await`
 // a computed return. `nextUtterance` is a thin, honest adapter for callers that
 // want a reply-shaped await; `null` means the Will chose silence, not an error.
@@ -33,12 +33,14 @@ import { PROVIDER_KEY_ENV, providerKeyFromEnv, type LLMProvider } from '#llm/ind
 import type { PMASnapshot } from '#pma/index'
 import type { effectorInvocation } from '#types'
 import type { EffectorDeclaration, SchemaPrecondition } from '#agency/types'
+import type { PolicyArbiter } from '#stem/policy/arbiter'
+import type { SignalProvenance } from '#senses/provenance'
 
 // ── Public surface ────────────────────────────────────────────
 
 /**
  * A stimulus entering the Will's sensory field. A Will is a subject, not a
- * function: you don't *call* it with input and await a return — you `perceive`
+ * function: you don't *call* it with input and await a return — you `sense`
  * something to it, and it *may* project a response later (see `nextUtterance`),
  * coloured by its current state. Silence is a valid, meaningful outcome.
  */
@@ -54,10 +56,39 @@ export interface Stimulus {
    * name, the Will knows the person as "someone" until it learns one.
    */
   speaker?: string
+  /**
+   * Whose doing this was: `'exafferent'` (the world), `'reafferent'` (the Will's
+   * own act, coming back), or `'unknown'` (you cannot tell).
+   *
+   * REQUIRED, as of P3. Only you can answer it — nothing inside the mind can
+   * tell the echo of its own utterance from a stranger saying the same words,
+   * which is why this is asserted at the boundary and never inferred behind it.
+   * Most inbound traffic is `'exafferent'`; use `say()`/`tell()`, whose verbs
+   * already make that claim, when that is all you mean. Reach for `'reafferent'`
+   * when you are feeding back the result of something the Will did — an
+   * ability's output, a webhook fired by its own write, a platform echo of a
+   * message it sent — and pass `sourceIntentId` if you have it.
+   *
+   * It was optional for exactly one epoch, defaulting to `'exafferent'`, so that
+   * a host migrated ONCE — at P3, alongside the `perceive()` → `sense()` rename
+   * — rather than twice. That default was the last surviving instance of the
+   * four-state hole the internal types exist to forbid: an omission silently
+   * became a claim nobody made. It is gone.
+   *
+   * If you genuinely cannot tell, say `'unknown'`. That is a different statement
+   * from `'exafferent'` and the mind treats it as one: the rupture gate in
+   * `action.selector` counts only `'exafferent'` percepts, so a mislabelled echo
+   * can interrupt a mind's train of thought with its own words.
+   */
+  provenance: SignalProvenance
+  /** The intent whose enaction caused this, when `provenance` is `'reafferent'`. */
+  sourceIntentId?: string
   /** Conversation/thread id (default = `from`). */
   thread?: string
   /** True when `thread` is private — just this someone and the Will. See TextMessage.direct. */
   direct?: boolean
+  /** What the room is called, e.g. `#general`. A label, not an address. See TextMessage.threadName. */
+  threadName?: string
 }
 
 /** A message the Will emitted to someone. */
@@ -69,7 +100,7 @@ export interface WillMessage {
   /** Entity id the Will addressed (the speaker you used in say()/tell(), or a bond). */
   to: string
   /**
-   * The conversation this belongs to — the `thread` from the `perceive()` that
+   * The conversation this belongs to — the `thread` from the `sense()` that
    * prompted it. Absent when the Will spoke unprompted, which genuinely has no
    * thread.
    *
@@ -113,14 +144,75 @@ export interface WillAffect {
  */
 export type EffectorResult = string | {
   success: boolean
+  /** How the act WENT — its fate. What the Will learns competence from. */
   description: string
+  /**
+   * What the act REVEALED — new information about the world (SIGNAL_BOUNDARY P2).
+   *
+   * Return it and the Will *perceives* it: it arrives as a reafferent percept
+   * tied to the act by `sourceIntentId`, so it is remembered and recallable,
+   * not merely learned from. A lookup, a listing, a snapshot has one; a kick or
+   * a warning does not — those only have a fate.
+   *
+   *     return { success: true,
+   *              description: 'Looked up Ada.',              // how it went
+   *              observation: 'Ada joined 3 months ago, …' } // what I found
+   *
+   * Any shape — a string, a record, a list — and carried WHOLE.
+   *
+   * SEND WHAT YOU HAVE, NOT WHAT IT MEANS. You are not asked to summarise, and
+   * you should not: making meaning by connecting pieces of information is the
+   * mind's entire job, and a host that hands over a conclusion has done that
+   * work on the wrong side of the boundary. A robot's vision layer reports
+   * `{ object: 'ball', confidence: 0.9, bbox: […] }`; it has no business
+   * deciding whether that is worth reacting to.
+   *
+   * The mind labels it with the ability's own name, and sees the data itself in
+   * its percepts — state, working memory and the prompt all carry it. If you
+   * happen to have a one-line `summary` on your object it is used as the label,
+   * but that is a convenience and never a requirement.
+   *
+   * SIZE IS YOURS TO JUDGE, AND NOTHING TRUNCATES IT. What you send lands in
+   * the mind's percepts and, briefly, its prompt — so a very large payload
+   * costs tokens on the ticks it is alive. The engine will not second-guess you
+   * by cutting it: a cap here decides for a mind how much of an answer it may
+   * have, and that decision is not the engine's to make. Send the record; send
+   * the field you would want it to notice.
+   *
+   * Before this, a host with facts to hand back had to return the ack AND call
+   * `sense()` separately — two calls for one act, and the second one had to
+   * pretend somebody had spoken.
+   */
+  observation?: unknown
   metrics?: Record<string, number>
 }
 
 /** Your implementation of an ability the Will can choose to use. */
 export type EffectorHandler = (
   args: Record<string, unknown>,
-  ctx: { reasoning: string; targetEntityId?: string; description?: string },
+  ctx: {
+    reasoning: string
+    /**
+     * The `agency.intent` this handler is running under — the correlation handle
+     * the Will will match an ack to (SIGNAL_BOUNDARY P1).
+     *
+     * Pass it as `sourceIntentId` on any `sense()` you make from inside a
+     * handler, and the resulting percept is a *reafference* the mind can tie back
+     * to the act that caused it, rather than an unexplained arrival. Before this
+     * existed, `discord_inspect_channel` had to say so in English — a bracketed
+     * `[I looked into #general: …]` that only the LLM could read — because the
+     * fact had nowhere structural to live.
+     */
+    intentId: string
+    targetEntityId?: string
+    /**
+     * The addresses this host knows `targetEntityId` by — a channel id, a user id.
+     * `targetEntityId` itself is an opaque anchor (who something IS); these are
+     * where to find it. Resolved inside the Will, where the alias table lives.
+     */
+    targetAddresses?: readonly string[]
+    description?: string
+  },
 ) => EffectorResult | Promise<EffectorResult>
 
 /**
@@ -180,12 +272,6 @@ export interface CreateWillOptions {
   identity: Partial<WillIdentity> & { prompt: string }
   /** 'mind' (default: the whole architecture) | 'reflex' (no-LLM shell). */
   anatomy?: Anatomy
-  /** Concrete LLM model id, or a per-role map ({ executive, summarizer?,
-   *  deliberation?, embedding? } — unset thinking roles fall back to executive).
-   *  Unset → env / provider default.
-   *  @deprecated Pass `llmConfig: { model }` instead — model and transport are
-   *  one concern. Still honoured; an explicit `llmConfig.model` wins. */
-  model?: string | WillModelConfig
   /** Per-Will LLM config: provider, model(s), BYO apiKey, baseUrl, caps.
    *  Unset fields fall back to WILL_LLM_* envs. apiKey stays in memory only.
    *  (Named llmConfig because `llm` is the provider MODE switch.) */
@@ -372,10 +458,18 @@ export class Will {
    * *delivered*, NOT once the Will has responded: a response (if any) is a
    * projection that arrives later on the `message` event, or via
    * `nextUtterance()`. The Will may also stay silent — that is not an error.
+   *
+   * NAMED `sense`, NOT `perceive` (SIGNAL_BOUNDARY P3). What happens here is
+   * *transduction*: a signal crosses into the mind. PERCEPTION is what a sense
+   * engine does afterwards — audition runs, judges salience, and produces a
+   * `Percept`, which may not resemble what arrived and may not happen at all
+   * (a gated sense drops it). Calling the door `perceive` said the caller had
+   * already done the mind's work, and it misled every reader of this flow,
+   * including the first draft of the epoch that renamed it.
    */
-  async perceive( stimulus: Stimulus ): Promise<void> {
+  async sense( stimulus: Stimulus ): Promise<void> {
     const from = stimulus.from ?? 'user'
-    await this.stem.ingestText( this.id, {
+    await this.stem.senseText( this.id, {
       kind:        'text',
       entityId:    from,
       threadId:    stimulus.thread ?? from,
@@ -388,17 +482,32 @@ export class Will {
       ...( stimulus.speaker ? { speakerName: stimulus.speaker } : {} ),
       // Omitted rather than defaulted: an unknown room is not known to be public.
       ...( stimulus.direct !== undefined ? { direct: stimulus.direct } : {} ),
+      // Omitted when the channel does not know — a room with no name stays
+      // unnamed, the same way a person does, rather than being labelled with its id.
+      ...( stimulus.threadName ? { threadName: stimulus.threadName } : {} ),
+      // No default. `Stimulus.provenance` is required now, so there is nothing
+      // left to fall back to — the four-state hole is closed at every door into
+      // this mind, which was the point of the epoch.
+      provenance: stimulus.provenance,
+      ...( stimulus.sourceIntentId ? { sourceIntentId: stimulus.sourceIntentId } : {} ),
     } )
   }
 
-  /** Perceive from the default user. Sugar over `perceive`. */
+  /**
+   * Sense from the default user. Sugar over `sense`.
+   *
+   * Supplies `provenance: 'exafferent'` — that is not a default sneaking back
+   * in, it is what the verb MEANS. "Say" is somebody speaking to the Will; a
+   * caller who wants to feed back the Will's own act reaches for `sense` and
+   * says so. The assertion lives in the function name.
+   */
   async say( text: string ): Promise<void> {
-    return this.perceive( { text, from: 'user' } )
+    return this.sense( { text, from: 'user', provenance: 'exafferent' } )
   }
 
-  /** Perceive from a specific interlocutor (multi-party). Sugar over `perceive`. */
+  /** Sense from a specific interlocutor (multi-party). Sugar over `sense` — see `say` on provenance. */
   async tell( entityId: string, speakerName: string, text: string ): Promise<void> {
-    return this.perceive( { text, from: entityId, speaker: speakerName } )
+    return this.sense( { text, from: entityId, speaker: speakerName, provenance: 'exafferent' } )
   }
 
   /**
@@ -408,7 +517,7 @@ export class Will {
    * 5000). `null` is a real outcome — the Will chose not to speak — not a
    * failure. Pass `to` to only accept an utterance addressed to that entity.
    *
-   *   await will.perceive( { from: 'ada', text: 'Hi!' } )
+   *   await will.sense( { from: 'ada', text: 'Hi!', provenance: 'exafferent' } )
    *   const reply = await will.nextUtterance( { to: 'ada', within: 3000 } )
    *   // reply is a WillMessage, or null if Ada got the silent treatment.
    */
@@ -515,6 +624,19 @@ export class Will {
   pause():  void { this.stem.pauseWill( this.id ) }
   resume(): void { this.stem.resumeWill( this.id ) }
 
+
+  /**
+   * Install the Policy Decision Point consulted before every effector
+   * invocation this Will hands to the host (POLICY_REAFFERENCE P0). `null`
+   * restores the no-op default. See `WillStem.setArbiter` for the one scoping
+   * caveat (per-stem, not per-Will id) — irrelevant here since `Will.create()`
+   * gives this instance its own dedicated stem.
+   */
+  setArbiter( arbiter: PolicyArbiter | null ): this {
+    this.stem.setArbiter( arbiter )
+    return this
+  }
+
   /**
    * Checkpoint the living mind into a portable PMA artifact — NON-destructive.
    * The Will keeps ticking; the snapshot is a point-in-time copy you can archive
@@ -555,16 +677,14 @@ export class Will {
     const mode = opts.llm ?? detectProvider()
     const useMock = mode === 'mock'
     // `llm` selects the provider; an explicit llmConfig.provider still wins.
-    // Model rides with the transport: `llmConfig.model` is canonical, the
-    // top-level `opts.model` is the deprecated spelling of the same thing.
-    const llmConfig: WillLLMConfig | undefined = useMock && !opts.llmConfig && opts.model === undefined
+    // Model rides with the transport — `llmConfig.model`, and only that. The
+    // top-level `model` spelling is gone: two ways to say one thing is how a
+    // config grows a precedence rule nobody can remember.
+    const llmConfig: WillLLMConfig | undefined = useMock && !opts.llmConfig
       ? undefined
       : {
           ...( mode !== 'mock' ? { provider: mode } : {} ),
           ...opts.llmConfig,
-          ...( opts.llmConfig?.model !== undefined ? { model: opts.llmConfig.model }
-             : opts.model        !== undefined ? { model: opts.model }
-             : {} ),
         }
     return {
       id, name: opts.name,
@@ -622,7 +742,7 @@ export class Will {
     if( !handler ){
       // The Will chose an effector we have no handler for — report it as failed so
       // the reafference loop learns it doesn't work, rather than hanging on the await.
-      this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, {
+      this.stem.confirmEffectorExecution( this.id, inv.intentId, {
         success: false, description: `No handler registered for effector "${inv.effectorName}"`,
       } )
       return
@@ -631,15 +751,23 @@ export class Will {
     try {
       const raw = await handler( inv.parameters, {
         reasoning: inv.reasoning,
+        // The correlation handle, so a handler that feeds its own result back in
+        // can say WHICH act caused it. This line used to read
+        // `intentId: inv.decisionRecordId` — the translation that proved the
+        // wire name was already wrong.
+        intentId: inv.intentId,
         targetEntityId: inv.targetEntityId,
+        // Which of the host's own ids that referent is — without it a handler
+        // gets an opaque anchor and nothing it can look up.
+        ...( inv.targetAddresses?.length ? { targetAddresses: inv.targetAddresses } : {} ),
         ...( inv.description ? { description: inv.description } : {} ),
       } )
       const result = typeof raw === 'string' ? { success: true, description: raw } : raw
-      this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, result )
+      this.stem.confirmEffectorExecution( this.id, inv.intentId, result )
     }
     catch( err ){
       this._emitError( err instanceof Error ? err : new Error( String( err ) ) )
-      this.stem.confirmEffectorExecution( this.id, inv.decisionRecordId, {
+      this.stem.confirmEffectorExecution( this.id, inv.intentId, {
         success: false, description: `Effector "${inv.effectorName}" threw: ${( err as Error ).message}`,
       } )
     }

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

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────
-// src/serve/server.ts — a Will, exposed over plain HTTP (the sidecar)
+// src/surface/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
@@ -23,8 +23,9 @@
 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'
+import type { Will } from '#surface/sdk/will'
+import { asProvenance } from '#senses/provenance'
+import { UtteranceTap } from '#surface/host/utterances'
 
 export interface WillHttpOptions {
   /** Where POST /save writes the PMA artifact. */
@@ -98,10 +99,16 @@ export function buildWillHttpServer( will: Will, opts: WillHttpOptions = {} ): S
         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( {
+        await will.sense( {
           text,
+          // Untyped ingress — a JSON body cannot be type-checked, and a client
+          // that predates the field has not claimed anything. asProvenance()
+          // owns the direction; see its comment for why 'exafferent' and not
+          // the tidier-looking 'unknown'.
+          provenance: asProvenance( body.provenance ),
           ...( typeof body.from    === 'string' ? { from:    body.from }    : {} ),
           ...( typeof body.speaker === 'string' ? { speaker: body.speaker } : {} ),
+          ...( typeof body.sourceIntentId === 'string' ? { sourceIntentId: body.sourceIntentId } : {} ),
         } )
         // 202: delivered into the sensory field — NOT answered. A response, if
         // any, arrives on /utterances or /next-utterance; silence is valid.

package/src/types.ts

@@ -22,12 +22,33 @@ export interface effectorInvocation {
   id:               string
   /** Correlation handle — the awaiting `agency.intent` id. Echo it when POSTing to
    *  `POST /v1/wills/:id/effectors/invoked/ack`; the Will reconciles the result onto
-   *  that intent. (Field name kept for wire-contract stability; no longer a
-   *  `decision.record` id since the agency cutover.) */
-  decisionRecordId: string
+   *  that intent.
+   *
+   *  Called `decisionRecordId` until the aliases came out. It stopped being a
+   *  `decision.record` id at the agency cutover and was kept anyway "for
+   *  wire-contract stability" — so the wire was stable and wrong, naming a
+   *  record type that no longer exists, while the SDK translated it to
+   *  `intentId` one hop later for the handler. Stability that preserves a false
+   *  name is preserving the wrong thing. */
+  intentId:         string
   effectorName:      string
   parameters:       Record<string, unknown>
   targetEntityId:   string | undefined
+  /**
+   * The addresses the world knows `targetEntityId` by.
+   *
+   * `targetEntityId` is an ANCHOR (`ke:1sqlkux`) — since 0.9.0 identity is opaque
+   * and deliberately not an address, because who someone is and where to find them
+   * are different facts. A host holds channel ids and knows nothing of anchors, so
+   * an invocation naming only the referent is one no surface can act on. Resolved
+   * inside, where the alias table lives, exactly as the outbox resolves a message
+   * addressed to a referent.
+   *
+   * Outbound only: this is the mind saying which of its own handles it means.
+   * Nothing here lets a surface name someone TO the mind — that is what perception
+   * is for.
+   */
+  targetAddresses?: readonly string[]
   reasoning:        string
   /** The ability's declared meaning (from its EffectorDeclaration), when present. */
   description?:     string

package/dist/channels/discord.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/channels/roster.ts","../../src/channels/types.ts","../../src/channels/discord.ts"],"names":[],"mappings":"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","file":"discord.js","sourcesContent":["// ─────────────────────────────────────────────────────────────\n// src/channels/roster.ts — who the Will knows on a platform, and where\n// ─────────────────────────────────────────────────────────────\n//\n// The mind knows *entities*; a platform knows user ids and channels. The roster\n// is the durable seam between them: for each entity the Will has met on a\n// channel it records how to reach them again — so a *proactive* utterance\n// (`message.to` from the mind's own initiative) can find its person after a\n// restart, not just within one session.\n//\n// It persists as a small JSON file next to the PMA artifact. Writes are\n// throttled (the file is advisory routing state, not cognition — losing the\n// last few seconds costs a fallback delivery, never memory).\n// ─────────────────────────────────────────────────────────────\n\nimport { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs'\nimport { dirname } from 'node:path'\n\n/** How to reach one entity on the platform. */\nexport interface RosterEntry {\n  /** The mind-side entity id, e.g. 'discord:80351110224678912'. */\n  entityId: string\n  /** The platform-side user id. */\n  userId: string\n  /** Last display name seen (advisory — the *learned* name lives in the mind). */\n  displayName?: string\n  /** DM channel id, once one is known. */\n  dmChannelId?: string\n  /** Last shared (guild) channel this entity spoke in. */\n  lastChannelId?: string\n  /** Epoch ms of the last message seen from them. */\n  lastSeenAt: number\n}\n\nconst FLUSH_MS = 2_000\n\nexport class ChannelRoster {\n  private entries = new Map<string, RosterEntry>()\n  private dirty = false\n  private timer: ReturnType<typeof setTimeout> | null = null\n\n  constructor( private readonly path: string ) {\n    if( existsSync( path ) ){\n      try {\n        const raw = JSON.parse( readFileSync( path, 'utf8') ) as RosterEntry[]\n        for( const e of Array.isArray( raw ) ? raw : [] ) this.entries.set( e.entityId, e )\n      }\n      catch { /* a corrupt roster is not worth failing a boot over — start fresh */ }\n    }\n  }\n\n  /** Upsert what we just learned about an entity; schedules a throttled flush. */\n  record( update: { entityId: string; userId: string } & Partial<Omit<RosterEntry, 'entityId' | 'userId'>> ): RosterEntry {\n    const prev = this.entries.get( update.entityId )\n    const next: RosterEntry = {\n      lastSeenAt: Date.now(),\n      ...prev,\n      ...Object.fromEntries( Object.entries( update ).filter( ( [ , v ] ) => v !== undefined ) ) as typeof update,\n    }\n    this.entries.set( next.entityId, next )\n    this.dirty = true\n    if( !this.timer ){\n      this.timer = setTimeout( () => { this.timer = null; this.flush() }, FLUSH_MS )\n      this.timer.unref?.()\n    }\n    return next\n  }\n\n  resolve( entityId: string ): RosterEntry | undefined {\n    return this.entries.get( entityId )\n  }\n\n  all(): RosterEntry[] {\n    return [ ...this.entries.values() ]\n  }\n\n  /** Write to disk now (no-op when clean). Called by bridges on close. */\n  flush(): void {\n    if( !this.dirty ) return\n    try {\n      mkdirSync( dirname( this.path ), { recursive: true } )\n      writeFileSync( this.path, JSON.stringify( this.all(), null, 2 ) )\n      this.dirty = false\n    }\n    catch { /* advisory state — never take the mind down over it */ }\n  }\n}\n","// ─────────────────────────────────────────────────────────────\n// src/channels/types.ts — the channel-bridge contract\n// ─────────────────────────────────────────────────────────────\n//\n// A channel bridge puts a Will *in a place where people already are* (Discord,\n// Telegram, Slack, …). It is a host surface, not a cognition surface: it turns\n// platform messages into `perceive` stimuli and delivers the Will's projected\n// utterances back — nothing more. The paradigm survives the crossing:\n//\n//   • every platform user is an entity the Will comes to know (`from`),\n//     with a *learned* name (`speaker`) — never a placeholder;\n//   • every platform channel/DM is a conversation thread (`thread`);\n//   • the Will decides when to speak. Silence is a valid outcome, so a\n//     bridge never fabricates a reply and never times a message out into\n//     an error.\n//\n// Bridges live at the same altitude as the MCP/HTTP hosts (src/mcp, src/serve):\n// they wrap the SDK facade, not the stem.\n// ─────────────────────────────────────────────────────────────\n\n/** A running connection between one Will and one platform. */\nexport interface ChannelBridge {\n  /** Platform kind, e.g. 'discord'. */\n  readonly kind: string\n  /** Connect and start relaying. Resolves once the bridge is live. */\n  start(): Promise<void>\n  /** Disconnect and release resources. Idempotent. */\n  close(): Promise<void>\n}\n\n// ── Attachments ──────────────────────────────────────────────────────────────\n//\n// People hand over documents as well as speech, and some platforms *manufacture*\n// them: Discord silently turns a long pasted markdown block into a `.md` upload.\n// A bridge that reads only the text body sees such a message as empty and — worse\n// — as nothing at all, so the person appears to have gone silent.\n//\n// What a bridge does with these is deliberately modest. A named-but-unread file\n// is already a percept the Will can act on (\"what's in it?\"), which is the\n// paradigm-correct outcome and strictly better than silence. Inlining text is an\n// upgrade on top, never a precondition.\n\n/** One file riding along with a platform message. */\nexport interface ChannelAttachment {\n  name:         string\n  contentType?: string\n  size?:        number\n  url?:         string\n}\n\n/** Per-attachment inline budget. A 2 MB doc must not enter working memory whole. */\nconst INLINE_CHAR_CAP = 24_000\n/** How many text attachments to inline from one message. */\nconst INLINE_COUNT_CAP = 4\n\nconst TEXTUAL_EXT = /\\.(md|markdown|txt|text|json|jsonl|csv|tsv|ya?ml|log|ini|toml)$/i\n\n/** Is this something we can meaningfully read as text? */\nexport function isTextual( a: ChannelAttachment ): boolean {\n  const ct = a.contentType?.split(';')[0]?.trim().toLowerCase() ?? ''\n  if( ct.startsWith('text/') ) return true\n  if( ct === 'application/json' || ct === 'application/x-yaml' ) return true\n  // Discord's own markdown uploads arrive as text/plain, but trust the extension\n  // too — content types from platforms are advisory at best.\n  return TEXTUAL_EXT.test( a.name )\n}\n\nfunction humanSize( bytes?: number ): string {\n  if( bytes == null ) return ''\n  return bytes < 1024 ? `${ bytes } B`\n       : bytes < 1024 * 1024 ? `${ ( bytes / 1024 ).toFixed( 1 ) } KB`\n       : `${ ( bytes / 1024 / 1024 ).toFixed( 1 ) } MB`\n}\n\n/**\n * Render attachments into perceivable text.\n *\n * `fetchText` is supplied by the bridge, not by this module — the decision about\n * which hosts are safe to fetch from is platform knowledge, and a helper that\n * fetched arbitrary URLs found in inbound messages would be an open redirect\n * into the Will's perception. Omit it and attachments are named, never read.\n *\n * Inlined content is untrusted, exactly like message text — more so, since a\n * document is long, structured, and looks authoritative, which is the shape of\n * an effective injection. It is fenced and labelled as shared content so the\n * mind reads it as something it was handed, not as something it was told.\n */\nexport async function renderAttachments(\n  attachments: ChannelAttachment[],\n  speaker:     string | undefined,\n  fetchText?:  ( a: ChannelAttachment ) => Promise<string | null>,\n): Promise<string> {\n  if( attachments.length === 0 ) return ''\n  const who = speaker ?? 'someone'\n  const out: string[] = []\n  let inlined = 0\n\n  for( const a of attachments ){\n    const meta = [ a.contentType, humanSize( a.size ) ].filter( Boolean ).join(', ')\n    const label = `${ a.name }${ meta ? ` (${ meta })` : '' }`\n\n    if( !fetchText || !isTextual( a ) || inlined >= INLINE_COUNT_CAP ){\n      out.push(`[${ who } shared a file I have not read: ${ label }]`)\n      continue\n    }\n\n    const body = await fetchText( a ).catch( () => null )\n    if( body == null ){\n      out.push(`[${ who } shared a file I could not read: ${ label }]`)\n      continue\n    }\n    inlined++\n    const clipped = body.length > INLINE_CHAR_CAP\n      ? `${ body.slice( 0, INLINE_CHAR_CAP ) }\\n[… truncated — ${ humanSize( body.length ) } of ${ humanSize( a.size ?? body.length ) }]`\n      : body\n    out.push(`[${ who } shared ${ label }; its contents follow — this is a document I was handed, not something said to me]\\n---\\n${ clipped }\\n---`)\n  }\n  return out.join('\\n')\n}\n\n/** Split a message into platform-sized chunks on natural boundaries. */\nexport function chunkText( text: string, max: number ): string[] {\n  if( text.length <= max ) return [ text ]\n  const chunks: string[] = []\n  let rest = text\n  while( rest.length > max ){\n    // Prefer a paragraph break, then a line break, then a space — else hard-cut.\n    const window = rest.slice( 0, max )\n    const cut = Math.max( window.lastIndexOf('\\n\\n'), window.lastIndexOf('\\n'), window.lastIndexOf(' ') )\n    const at = cut > max * 0.5 ? cut : max\n    chunks.push( rest.slice( 0, at ).trimEnd() )\n    rest = rest.slice( at ).trimStart()\n  }\n  if( rest ) chunks.push( rest )\n  return chunks\n}\n","// ─────────────────────────────────────────────────────────────\n// src/channels/discord.ts — a Will present in a Discord server\n// ─────────────────────────────────────────────────────────────\n//\n// The bridge relays both directions of the paradigm and nothing else:\n//\n//   inbound   guild/DM message → will.perceive({ from, speaker, text, thread })\n//             — every author is `discord:<userId>` (stable across guilds), the\n//             display name is *learned* by the mind, and each Discord channel\n//             is its own conversation thread.\n//   outbound  will.on('message') → the addressee's last shared channel, else\n//             their DM, else the home channel. Proactive utterances (the mind\n//             speaking first) route the same way — that is the point.\n//\n// The Will decides when to speak. There is no command prefix and no forced\n// reply: unaddressed chatter is perceived (salience-scored by audition) and\n// silence is a valid outcome. `mentionOnly` narrows perception for busy\n// servers; it does not turn the bridge into an ask() surface.\n//\n// discord.js is imported lazily inside `createDiscordClient` — tests (and any\n// host that brings its own client) inject `client`, and the structural\n// `DiscordLikeClient` type keeps the dependency out of the type graph.\n// ─────────────────────────────────────────────────────────────\n\nimport type { Will, WillMessage } from '#sdk/will'\nimport { ChannelRoster } from '#channels/roster'\nimport { chunkText, renderAttachments, isTextual, type ChannelBridge, type ChannelAttachment } from '#channels/types'\n\nconst DISCORD_MESSAGE_LIMIT = 2000\n\n/**\n * The only hosts the bridge will fetch attachment bodies from.\n *\n * Deliberately an allowlist of Discord's own CDN. An inbound message is\n * untrusted input; following URLs it names would turn perception into an open\n * redirect, and a `url` field is no more trustworthy than the message text.\n */\nconst DISCORD_CDN_HOSTS = new Set( [ 'cdn.discordapp.com', 'media.discordapp.net' ] )\n\n/** Refuse to pull a large file into a percept — the cap in renderAttachments\n *  bounds what is *kept*, this bounds what is fetched at all. */\nconst MAX_FETCH_BYTES = 256 * 1024\n\n// ── The slice of discord.js the bridge actually uses (structural) ───────────\n\nexport interface DiscordLikeChannel {\n  send( content: string ): Promise<unknown>\n  sendTyping?(): Promise<unknown>\n}\n\nexport interface DiscordLikeAttachment {\n  name?:        string | null\n  contentType?: string | null\n  size?:        number\n  url?:         string\n}\n\nexport interface DiscordLikeMessage {\n  content: string\n  cleanContent?: string\n  channelId: string\n  guildId?: string | null\n  author: { id: string; bot?: boolean; username?: string; displayName?: string }\n  member?: { displayName?: string } | null\n  mentions?: { has( userId: string ): boolean }\n  channel: DiscordLikeChannel\n  /**\n   * Files riding with the message.\n   *\n   * discord.js hands us a `Collection`, which extends `Map` — so iterating it\n   * directly yields `[id, attachment]` PAIRS, not attachments. Typing this as a\n   * bare `Iterable` was wrong and silently produced `name: undefined` against\n   * the real client while passing every test, because the test fake injects an\n   * array. Both shapes are accepted now and normalised in `collectAttachments`.\n   */\n  attachments?: ReadonlyMap<string, DiscordLikeAttachment> | Iterable<DiscordLikeAttachment>\n}\n\nexport interface DiscordLikeClient {\n  user: { id: string; setPresence?( p: unknown ): void } | null\n  /** discord.js ≥14.22; polled so we needn't subscribe to the deprecated `ready`. */\n  isReady?(): boolean\n  on( event: 'messageCreate', fn: ( m: DiscordLikeMessage ) => void ): unknown\n  once( event: string, fn: () => void ): unknown\n  login( token: string ): Promise<unknown>\n  destroy(): Promise<unknown> | void\n  channels: { fetch( id: string ): Promise<unknown> }\n  users: { fetch( id: string ): Promise<{ send( content: string ): Promise<unknown> }> }\n}\n\n// ── Options ──────────────────────────────────────────────────────────────────\n\nexport interface DiscordBridgeOptions {\n  /** Bot token (Discord developer portal). Unused when `client` is injected pre-logged-in. */\n  token?: string\n  /**\n   * Channel ids the Will inhabits. Unset — or the single wildcard `'*'` — means\n   * every channel it can see, so adding it to a new channel in Discord is enough.\n   * A list restrains it to exactly those, and a message anywhere else is dropped\n   * at the bridge: the Will never perceives it and its silence there is not a choice.\n   */\n  channels?: readonly string[]\n  /**\n   * Where the Will only perceives guild messages that @mention it. DMs are always\n   * perceived either way.\n   *\n   *   `true`            — everywhere\n   *   `[ 'id', … ]`     — only in those channels; it listens openly elsewhere\n   *   omitted / `false` — nowhere\n   *\n   * The list form is what makes a wide-open roster usable: present in every channel,\n   * but a quiet participant in the busy ones.\n   */\n  mentionOnly?: boolean | readonly string[]\n  /** Fallback channel for utterances with no reachable addressee. */\n  homeChannelId?: string\n  /** Roster path (default: ./.will/<willId>.discord.json). */\n  rosterPath?: string\n  /**\n   * Read the contents of text-like attachments (.md, .txt, .json, …) into the\n   * percept, rather than only naming them. Default true.\n   *\n   * Only Discord's own CDN is ever fetched, and only up to a size cap. Set false\n   * for a bridge that should never pull remote bytes — the Will still perceives\n   * that a file arrived and can ask about it.\n   */\n  readAttachments?: boolean\n  /** Test / power-user seam: bring your own client; discord.js is never imported. */\n  client?: DiscordLikeClient\n  log?: ( msg: string ) => void\n}\n\n// ── The bridge ───────────────────────────────────────────────────────────────\n\n/**\n * Connect a Will to Discord. Resolves once the bridge is live (logged in and\n * relaying). Close it via the returned `ChannelBridge.close()` — the Will\n * itself is not stopped; it simply loses this surface.\n */\nexport async function connectDiscord( will: Will, opts: DiscordBridgeOptions ): Promise<ChannelBridge> {\n  const log     = opts.log ?? ( ( m: string ) => console.error(`[will:discord] ${ m }`) )\n  const roster  = new ChannelRoster( opts.rosterPath ?? `.will/${ will.id }.discord.json`)\n  // `null` = everywhere. An explicit '*' reads the same as omitting the list, so a\n  // host can say \"all channels\" out loud instead of by leaving a variable blank.\n  const allowed = opts.channels?.length && !opts.channels.includes('*')\n    ? new Set( opts.channels )\n    : null\n\n  // Mention-gating is either global (true) or scoped to named channels.\n  const mentionEverywhere = opts.mentionOnly === true\n  const mentionIn         = Array.isArray( opts.mentionOnly ) && opts.mentionOnly.length\n    ? new Set( opts.mentionOnly )\n    : null\n\n  const client = opts.client ?? await createDiscordClient()\n\n  /** The most recently active allowed channel — last-resort proactive target. */\n  let lastActiveChannelId: string | null = opts.homeChannelId ?? null\n\n  // ── inbound: platform message → stimulus ──────────────────────────────────\n  client.on('messageCreate', message => { void onMessage( message ) } )\n\n  async function onMessage( message: DiscordLikeMessage ): Promise<void> {\n    const self = client.user\n    if( !self || message.author.id === self.id || message.author.bot ) return\n\n    const isDM = !message.guildId\n    if( !isDM && allowed && !allowed.has( message.channelId ) ) return\n\n    const addressed = isDM || ( message.mentions?.has( self.id ) ?? false )\n    // DMs are addressed by definition, so this never gates them.\n    if( !addressed && ( mentionEverywhere || mentionIn?.has( message.channelId ) ) ) return\n\n    const entityId = `discord:${ message.author.id }`\n    const speaker  = message.member?.displayName ?? message.author.displayName ?? message.author.username\n\n    roster.record( {\n      entityId,\n      userId: message.author.id,\n      ...( speaker ? { displayName: speaker } : {} ),\n      ...( isDM ? { dmChannelId: message.channelId } : { lastChannelId: message.channelId } ),\n    } )\n    if( !isDM ) lastActiveChannelId = message.channelId\n\n    // Being addressed is the one moment a presence cue is honest — the mind\n    // may still choose silence, and typing expires on its own.\n    if( addressed ) await message.channel.sendTyping?.().catch( () => {} )\n\n    const said  = ( message.cleanContent || message.content ).trim()\n    const files = collectAttachments( message )\n\n    // An attachment-only message used to die here on the empty body: no percept,\n    // no log line, nothing. From the mind's side the person had simply gone\n    // quiet — and Discord *makes* these, turning a long pasted markdown block\n    // into a .md upload. Only a message with neither words nor files is nothing.\n    if( !said && files.length === 0 ) return\n\n    const shared = await renderAttachments(\n      files, speaker,\n      opts.readAttachments === false ? undefined : fetchAttachmentText,\n    )\n    const text = [ said, shared ].filter( Boolean ).join('\\n')\n\n    await will.perceive( {\n      text,\n      from:   entityId,\n      thread: `discord:${ message.channelId }`,\n      // `isDM` has been computed on every inbound since this bridge shipped and\n      // used only to pick a roster field. It is the one fact that makes a room\n      // the right or wrong place to say something, and the mind never saw it —\n      // which is how a follow-up promised in a DM went out to #general.\n      direct: isDM,\n      ...( speaker ? { speaker } : {} ),\n    } )\n  }\n\n  /**\n   * Normalise whatever the client gave us into attachments.\n   *\n   * `.values()` first: a discord.js Collection is a Map, so `for..of` over it\n   * yields `[id, attachment]` pairs and every field reads `undefined`. Arrays\n   * expose `.values()` too and yield their elements, so one branch covers the\n   * real client, a plain array, and a Map alike.\n   */\n  function collectAttachments( message: DiscordLikeMessage ): ChannelAttachment[] {\n    if( !message.attachments ) return []\n    const source = message.attachments as { values?: () => Iterable<DiscordLikeAttachment> }\n    const items: Iterable<DiscordLikeAttachment> = typeof source.values === 'function'\n      ? source.values()\n      : message.attachments as Iterable<DiscordLikeAttachment>\n\n    const out: ChannelAttachment[] = []\n    for( const a of items )\n      out.push( {\n        name: a.name ?? 'unnamed',\n        ...( a.contentType ? { contentType: a.contentType } : {} ),\n        ...( a.size != null ? { size: a.size } : {} ),\n        ...( a.url ? { url: a.url } : {} ),\n      } )\n    return out\n  }\n\n  /** Fetch one text attachment — Discord CDN only, size-capped. */\n  async function fetchAttachmentText( a: ChannelAttachment ): Promise<string | null> {\n    if( !a.url || !isTextual( a ) ) return null\n    let host: string\n    try { host = new URL( a.url ).hostname }\n    catch { return null }\n    if( !DISCORD_CDN_HOSTS.has( host ) ){\n      log(`refusing to fetch attachment '${ a.name }' from non-CDN host ${ host }`)\n      return null\n    }\n    if( a.size != null && a.size > MAX_FETCH_BYTES ){\n      log(`attachment '${ a.name }' is ${ a.size } bytes — naming it without reading`)\n      return null\n    }\n    const res = await fetch( a.url, { signal: AbortSignal.timeout( 10_000 ) } )\n    if( !res.ok ){\n      log(`attachment '${ a.name }' fetch failed: ${ res.status }`)\n      return null\n    }\n    return ( await res.text() ).slice( 0, MAX_FETCH_BYTES )\n  }\n\n  // ── outbound: projected utterance → the addressee ─────────────────────────\n  // The facade has no off(); the bridge gates its handler on `closed` instead.\n  let closed = false\n  will.on('message', ( m: WillMessage ) => { if( !closed ) void deliver( m ) } )\n\n  async function deliver( m: WillMessage ): Promise<void> {\n    const peer = m.to ? roster.resolve( m.to ) : undefined\n    const chunks = chunkText( m.content, DISCORD_MESSAGE_LIMIT )\n\n    // A reply goes back to the room it was said in. `m.thread` is the thread from\n    // the `perceive()` that prompted this — `discord:<channelId>` — so it is not a\n    // guess about where this person usually is, it is where they just spoke.\n    //\n    // Everything below it IS a guess, and the guesses were wrong in the way that\n    // matters most: a DM arrived, she answered it in seconds, and the answer went\n    // to the shared server channel because `lastChannelId` still held the last\n    // room they had been in together. She looked like she was ignoring him.\n    //\n    // Unprompted utterances carry no thread — nothing was said to them — so those\n    // still fall through to the roster, which is the right behaviour there.\n    const replyTo = m.thread?.startsWith('discord:') ? m.thread.slice('discord:'.length ) : undefined\n\n    // Preference order: the room they spoke in → where we last shared a room →\n    // their DM → home channel.\n    const channelIds = [ replyTo, peer?.lastChannelId, peer?.dmChannelId, opts.homeChannelId ?? undefined, lastActiveChannelId ?? undefined ]\n    for( const id of channelIds ){\n      if( !id ) continue\n      try {\n        const channel = await client.channels.fetch( id ) as DiscordLikeChannel | null\n        if( !channel?.send ) continue\n        for( const chunk of chunks ) await channel.send( chunk )\n        return\n      }\n      catch { /* try the next route */ }\n    }\n    if( peer ){\n      try {\n        const user = await client.users.fetch( peer.userId )\n        for( const chunk of chunks ) await user.send( chunk )\n        return\n      }\n      catch { /* fall through */ }\n    }\n    log(`no route for utterance to '${ m.to }' — dropped (${ m.content.length } chars)`)\n  }\n\n  // ── lifecycle ──────────────────────────────────────────────────────────────\n  const bridge: ChannelBridge = {\n    kind: 'discord',\n    async start(): Promise<void> {\n      if( !client.user ){\n        // discord.js ≥14.22 renamed `ready` → `clientReady`. Subscribing to the\n        // old name is what triggers its DeprecationWarning, so we take the new\n        // name and poll `isReady()` for older builds rather than listening.\n        const ready = new Promise<void>( resolve => {\n          let poll: ReturnType<typeof setInterval> | null = null\n          const done = (): void => { if( poll ) clearInterval( poll ); resolve() }\n          client.once('clientReady', done )\n          poll = setInterval( () => { if( client.isReady?.() ) done() }, 100 )\n          poll.unref?.()\n        } )\n        await client.login( opts.token ?? '')\n        await ready\n      }\n      log(`${ will.name } is present on Discord as user ${ client.user?.id }`)\n    },\n    async close(): Promise<void> {\n      if( closed ) return\n      closed = true\n      roster.flush()\n      await Promise.resolve( client.destroy() ).catch( () => {} )\n    },\n  }\n  return bridge\n}\n\n/** Build a real discord.js client (lazy import keeps it out of non-Discord hosts). */\nasync function createDiscordClient(): Promise<DiscordLikeClient> {\n  let mod: typeof import('discord.js')\n  try { mod = await import('discord.js') }\n  catch {\n    throw new Error('discord.js is not installed (it is an optionalDependency) — run `bun add discord.js` / `npm i discord.js` and retry.')\n  }\n  const { Client, GatewayIntentBits, Partials } = mod\n  return new Client( {\n    intents: [\n      GatewayIntentBits.Guilds,\n      GatewayIntentBits.GuildMessages,\n      GatewayIntentBits.MessageContent,\n      GatewayIntentBits.DirectMessages,\n    ],\n    partials: [ Partials.Channel ],   // DMs arrive on uncached channels\n  } ) as unknown as DiscordLikeClient\n}\n\n/**\n * Parse `WILL_DISCORD_MENTION_ONLY` into the `mentionOnly` option.\n *\n * Accepts a boolean OR a channel list, because \"only speak when spoken to\" is\n * rarely a whole-server property — it is how you stay present in a busy channel\n * without narrating in it.\n *\n *   `1` / `true` / `yes`   → true (everywhere)\n *   `0` / `false` / unset  → false (nowhere)\n *   `123,456`              → only those channels\n *\n * Exported so every host parses it identically; the CLI and any SDK host share\n * this rather than each re-deriving the syntax.\n */\nexport function parseMentionOnly( raw?: string ): boolean | string[] {\n  const v = raw?.trim()\n  if( !v ) return false\n  if( /^(1|true|yes)$/i.test( v ) ) return true\n  if( /^(0|false|no)$/i.test( v ) ) return false\n\n  const ids = v.split(',').map( s => s.trim() ).filter( Boolean )\n  return ids.length ? ids : false\n}\n\n/**\n * Parse `WILL_DISCORD_CHANNELS`. `*` (or unset/empty) means every channel the Will\n * can see — being added to a channel in Discord is then all it takes. Anything else\n * restrains it to exactly the ids listed.\n */\nexport function parseChannels( raw?: string ): string[] | undefined {\n  const ids = raw?.split(',').map( s => s.trim() ).filter( Boolean )\n  return ids?.length ? ids : undefined\n}\n"]}