@mindot/will 0.8.0 → 0.10.0

package/dist/surface/channels/discord.d.ts

@@ -0,0 +1,177 @@
+import { W as Will } from '../../will-evj9_vrd.js';
+import { C as ChannelBridge } from '../../types-E9-HV-SW.js';
+
+interface DiscordLikeChannel {
+    send(content: string): Promise<unknown>;
+    sendTyping?(): Promise<unknown>;
+    /** `general` for a text channel; absent on a DM, which has no name and is a person. */
+    name?: string | null;
+    /** The thread's parent channel, so a thread reads as "#general › release-cut". */
+    parent?: {
+        name?: string | null;
+    } | null;
+    /** What the room is FOR, in the server's own words. Only read when asked. */
+    topic?: string | null;
+    /** How many are in it — a count, never a roster. */
+    memberCount?: number;
+}
+interface DiscordLikeAttachment {
+    name?: string | null;
+    contentType?: string | null;
+    size?: number;
+    url?: string;
+}
+interface DiscordLikeMessage {
+    content: string;
+    cleanContent?: string;
+    channelId: string;
+    guildId?: string | null;
+    /** The server this was said in. Its NAME is what a person calls the place. */
+    guild?: {
+        name?: string | null;
+    } | null;
+    author: {
+        id: string;
+        bot?: boolean;
+        username?: string;
+        displayName?: string;
+    };
+    member?: {
+        displayName?: string;
+    } | null;
+    mentions?: {
+        has(userId: string): boolean;
+    };
+    channel: DiscordLikeChannel;
+    /**
+     * Files riding with the message.
+     *
+     * discord.js hands us a `Collection`, which extends `Map` — so iterating it
+     * directly yields `[id, attachment]` PAIRS, not attachments. Typing this as a
+     * bare `Iterable` was wrong and silently produced `name: undefined` against
+     * the real client while passing every test, because the test fake injects an
+     * array. Both shapes are accepted now and normalised in `collectAttachments`.
+     */
+    attachments?: ReadonlyMap<string, DiscordLikeAttachment> | Iterable<DiscordLikeAttachment>;
+}
+/**
+ * A reaction, and the message it lands on.
+ *
+ * Both halves may be PARTIAL: Discord delivers a reaction on an uncached message
+ * with almost every field empty, which is the normal case for a message the bot
+ * sent before its current process started. `fetch()` fills it in, and the handler
+ * must call it rather than reading through the hole.
+ */
+interface DiscordLikeReaction {
+    emoji: {
+        name?: string | null;
+        id?: string | null;
+    };
+    message: DiscordLikeMessage & {
+        partial?: boolean;
+        author?: {
+            id: string;
+            bot?: boolean;
+            username?: string;
+            displayName?: string;
+        };
+        fetch?(): Promise<DiscordLikeReaction['message']>;
+    };
+    partial?: boolean;
+    fetch?(): Promise<DiscordLikeReaction>;
+}
+interface DiscordLikeReactor {
+    id: string;
+    bot?: boolean;
+    username?: string;
+    displayName?: string;
+}
+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;
+    on(event: 'messageReactionAdd', fn: (r: DiscordLikeReaction, u: DiscordLikeReactor) => 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>;
+        }>;
+    };
+}
+interface DiscordBridgeOptions {
+    /** Bot token (Discord developer portal). Unused when `client` is injected pre-logged-in. */
+    token?: string;
+    /**
+     * Channel ids the Will inhabits. Unset — or the single wildcard `'*'` — means
+     * every channel it can see, so adding it to a new channel in Discord is enough.
+     * A list restrains it to exactly those, and a message anywhere else is dropped
+     * at the bridge: the Will never perceives it and its silence there is not a choice.
+     */
+    channels?: readonly string[];
+    /**
+     * Where the Will only perceives guild messages that @mention it. DMs are always
+     * perceived either way.
+     *
+     *   `true`            — everywhere
+     *   `[ 'id', … ]`     — only in those channels; it listens openly elsewhere
+     *   omitted / `false` — nowhere
+     *
+     * The list form is what makes a wide-open roster usable: present in every channel,
+     * but a quiet participant in the busy ones.
+     */
+    mentionOnly?: boolean | readonly string[];
+    /** Fallback channel for utterances with no reachable addressee. */
+    homeChannelId?: string;
+    /** Roster path (default: ./.will/<willId>.discord.json). */
+    rosterPath?: string;
+    /**
+     * Read the contents of text-like attachments (.md, .txt, .json, …) into the
+     * percept, rather than only naming them. Default true.
+     *
+     * Only Discord's own CDN is ever fetched, and only up to a size cap. Set false
+     * for a bridge that should never pull remote bytes — the Will still perceives
+     * that a file arrived and can ask about it.
+     */
+    readAttachments?: boolean;
+    /** Test / power-user seam: bring your own client; discord.js is never imported. */
+    client?: DiscordLikeClient;
+    log?: (msg: string) => void;
+}
+/**
+ * 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.
+ */
+declare function connectDiscord(will: Will, opts: DiscordBridgeOptions): Promise<ChannelBridge>;
+/**
+ * Parse `WILL_DISCORD_MENTION_ONLY` into the `mentionOnly` option.
+ *
+ * Accepts a boolean OR a channel list, because "only speak when spoken to" is
+ * rarely a whole-server property — it is how you stay present in a busy channel
+ * without narrating in it.
+ *
+ *   `1` / `true` / `yes`   → true (everywhere)
+ *   `0` / `false` / unset  → false (nowhere)
+ *   `123,456`              → only those channels
+ *
+ * Exported so every host parses it identically; the CLI and any SDK host share
+ * this rather than each re-deriving the syntax.
+ */
+declare function parseMentionOnly(raw?: string): boolean | string[];
+/**
+ * Parse `WILL_DISCORD_CHANNELS`. `*` (or unset/empty) means every channel the Will
+ * can see — being added to a channel in Discord is then all it takes. Anything else
+ * restrains it to exactly the ids listed.
+ */
+declare function parseChannels(raw?: string): string[] | undefined;
+
+export { type DiscordBridgeOptions, type DiscordLikeAttachment, type DiscordLikeChannel, type DiscordLikeClient, type DiscordLikeMessage, type DiscordLikeReaction, type DiscordLikeReactor, connectDiscord, parseChannels, parseMentionOnly };

package/dist/surface/channels/discord.js

@@ -0,0 +1,394 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+
+// src/surface/channels/roster.ts
+var FLUSH_MS = 2e3;
+var ChannelRoster = class {
+  constructor(path) {
+    this.path = path;
+    if (existsSync(path)) {
+      try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        for (const e of Array.isArray(raw) ? raw : []) this.entries.set(e.entityId, e);
+      } catch {
+      }
+    }
+  }
+  path;
+  entries = /* @__PURE__ */ new Map();
+  dirty = false;
+  timer = null;
+  /** Upsert what we just learned about an entity; schedules a throttled flush. */
+  record(update) {
+    const prev = this.entries.get(update.entityId);
+    const next = {
+      lastSeenAt: Date.now(),
+      ...prev,
+      ...Object.fromEntries(Object.entries(update).filter(([, v]) => v !== void 0))
+    };
+    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) {
+    return this.entries.get(entityId);
+  }
+  all() {
+    return [...this.entries.values()];
+  }
+  /** Write to disk now (no-op when clean). Called by bridges on close. */
+  flush() {
+    if (!this.dirty) return;
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      writeFileSync(this.path, JSON.stringify(this.all(), null, 2));
+      this.dirty = false;
+    } catch {
+    }
+  }
+};
+
+// src/surface/channels/types.ts
+var INLINE_CHAR_CAP = 24e3;
+var INLINE_COUNT_CAP = 4;
+var TEXTUAL_EXT = /\.(md|markdown|txt|text|json|jsonl|csv|tsv|ya?ml|log|ini|toml)$/i;
+function isTextual(a) {
+  const ct = a.contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+  if (ct.startsWith("text/")) return true;
+  if (ct === "application/json" || ct === "application/x-yaml") return true;
+  return TEXTUAL_EXT.test(a.name);
+}
+function humanSize(bytes) {
+  if (bytes == null) return "";
+  return bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+async function renderAttachments(attachments, speaker, fetchText) {
+  if (attachments.length === 0) return "";
+  const who = speaker ?? "someone";
+  const out = [];
+  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)}
+[\u2026 truncated \u2014 ${humanSize(body.length)} of ${humanSize(a.size ?? body.length)}]` : body;
+    out.push(`[${who} shared ${label}; its contents follow \u2014 this is a document I was handed, not something said to me]
+---
+${clipped}
+---`);
+  }
+  return out.join("\n");
+}
+function chunkText(text, max) {
+  if (text.length <= max) return [text];
+  const chunks = [];
+  let rest = text;
+  while (rest.length > max) {
+    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;
+}
+
+// src/surface/channels/discord.ts
+var DISCORD_MESSAGE_LIMIT = 2e3;
+var DISCORD_CDN_HOSTS = /* @__PURE__ */ new Set(["cdn.discordapp.com", "media.discordapp.net"]);
+var MAX_FETCH_BYTES = 256 * 1024;
+var REACTION_QUOTE_CHARS = 140;
+function roomLabel(message) {
+  if (!message.guildId) return void 0;
+  const own = message.channel?.name;
+  if (!own) return void 0;
+  const parent = message.channel?.parent?.name;
+  const room = parent ? `#${parent} \u203A ${own}` : `#${own}`;
+  const guild = message.guild?.name;
+  return guild ? `${room} in ${guild}` : room;
+}
+async function connectDiscord(will, opts) {
+  const log = opts.log ?? ((m) => console.error(`[will:discord] ${m}`));
+  const roster = new ChannelRoster(opts.rosterPath ?? `.will/${will.id}.discord.json`);
+  const allowed = opts.channels?.length && !opts.channels.includes("*") ? new Set(opts.channels) : null;
+  const mentionEverywhere = opts.mentionOnly === true;
+  const mentionIn = Array.isArray(opts.mentionOnly) && opts.mentionOnly.length ? new Set(opts.mentionOnly) : null;
+  const client = opts.client ?? await createDiscordClient();
+  let lastActiveChannelId = opts.homeChannelId ?? null;
+  client.on("messageCreate", (message) => {
+    void onMessage(message);
+  });
+  client.on("messageReactionAdd", (reaction, user) => {
+    void onReaction(reaction, user);
+  });
+  async function onReaction(reaction, user) {
+    const self = client.user;
+    if (!self || user.id === self.id || user.bot) return;
+    const full = reaction.partial && reaction.fetch ? await reaction.fetch().catch(() => null) : reaction;
+    if (!full) return;
+    const msg = full.message.partial && full.message.fetch ? await full.message.fetch().catch(() => null) : full.message;
+    if (!msg?.author) return;
+    if (msg.author.id !== self.id) return;
+    const isDM = !msg.guildId;
+    if (!isDM && allowed && !allowed.has(msg.channelId)) return;
+    const emoji = full.emoji?.name ?? (full.emoji?.id ? ":custom:" : "");
+    if (!emoji) return;
+    const who = user.displayName ?? user.username;
+    const said = (msg.cleanContent || msg.content || "").trim().slice(0, REACTION_QUOTE_CHARS);
+    const text = said ? `[${who ?? "someone"} reacted ${emoji} to what I said: "${said}"]` : `[${who ?? "someone"} reacted ${emoji} to something I said]`;
+    await will.sense({
+      text,
+      from: `discord:${user.id}`,
+      thread: `discord:${msg.channelId}`,
+      direct: isDM,
+      // Exafferent, and the near-miss is worth naming: this is ABOUT something
+      // she did, but it is not her doing it. Somebody else reacted. Reafference
+      // is the mind sensing its OWN act's consequence, not the world's response
+      // to that act — a reply would fail the same test for the same reason.
+      provenance: "exafferent",
+      ...roomLabel(msg) ? { threadName: roomLabel(msg) } : {},
+      ...who ? { speaker: who } : {}
+    });
+  }
+  async function onMessage(message) {
+    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 (!addressed && (mentionEverywhere || mentionIn?.has(message.channelId))) 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;
+    if (addressed) await message.channel.sendTyping?.().catch(() => {
+    });
+    const said = (message.cleanContent || message.content).trim();
+    const files = collectAttachments(message);
+    if (!said && files.length === 0) return;
+    const shared = await renderAttachments(
+      files,
+      speaker,
+      opts.readAttachments === false ? void 0 : fetchAttachmentText
+    );
+    const text = [said, shared].filter(Boolean).join("\n");
+    await will.sense({
+      text,
+      from: entityId,
+      thread: `discord:${message.channelId}`,
+      // `isDM` has been computed on every inbound since this bridge shipped and
+      // used only to pick a roster field. It is the one fact that makes a room
+      // the right or wrong place to say something, and the mind never saw it —
+      // which is how a follow-up promised in a DM went out to #general.
+      direct: isDM,
+      // Somebody spoke. The bridge already drops her own messages (`onMessage`
+      // returns early on `author.id === self.id`), so nothing reafferent can
+      // reach this line today — but that filter is a bridge-level deletion of
+      // a signal she is entitled to sense, not a reason for the field to lie.
+      provenance: "exafferent",
+      ...roomLabel(message) ? { threadName: roomLabel(message) } : {},
+      ...speaker ? { speaker } : {}
+    });
+  }
+  function collectAttachments(message) {
+    if (!message.attachments) return [];
+    const source = message.attachments;
+    const items = typeof source.values === "function" ? source.values() : message.attachments;
+    const out = [];
+    for (const a of items)
+      out.push({
+        name: a.name ?? "unnamed",
+        ...a.contentType ? { contentType: a.contentType } : {},
+        ...a.size != null ? { size: a.size } : {},
+        ...a.url ? { url: a.url } : {}
+      });
+    return out;
+  }
+  async function fetchAttachmentText(a) {
+    if (!a.url || !isTextual(a)) return null;
+    let host;
+    try {
+      host = new URL(a.url).hostname;
+    } catch {
+      return null;
+    }
+    if (!DISCORD_CDN_HOSTS.has(host)) {
+      log(`refusing to fetch attachment '${a.name}' from non-CDN host ${host}`);
+      return null;
+    }
+    if (a.size != null && a.size > MAX_FETCH_BYTES) {
+      log(`attachment '${a.name}' is ${a.size} bytes \u2014 naming it without reading`);
+      return null;
+    }
+    const res = await fetch(a.url, { signal: AbortSignal.timeout(1e4) });
+    if (!res.ok) {
+      log(`attachment '${a.name}' fetch failed: ${res.status}`);
+      return null;
+    }
+    return (await res.text()).slice(0, MAX_FETCH_BYTES);
+  }
+  will.effector("inspect", async (_args, ctx) => {
+    const address = (ctx.targetAddresses ?? []).find((a) => a.startsWith("discord:"));
+    if (!address) return { success: false, description: "Not something I can see on Discord." };
+    const id = address.slice("discord:".length);
+    const channel = await client.channels.fetch(id).catch(() => null);
+    if (!channel?.name) return { success: false, description: "There is nothing here I can look up." };
+    const facts = [];
+    if (channel.topic) facts.push(`it is for: ${channel.topic}`);
+    if (channel.parent?.name) facts.push(`it sits under #${channel.parent.name}`);
+    if (typeof channel.memberCount === "number")
+      facts.push(`${channel.memberCount} people are in it`);
+    if (facts.length === 0)
+      return { success: false, description: `#${channel.name} has nothing recorded about it.` };
+    const label = roomLabel({ guildId: "g", channel }) ?? `#${channel.name}`;
+    return {
+      success: true,
+      description: `Looked into ${label}.`,
+      // The room as Discord has it, in the shape Discord has it. Not flattened
+      // into a sentence for the mind's benefit — a host that reshapes its own
+      // data is deciding what the mind may notice about it, and `observation`
+      // takes whatever shape the answer already had.
+      //
+      // `summary` is the one concession: it is what the executive prompt renders,
+      // so the host says it in words rather than leaving the mind to read JSON.
+      // Everything beside it stays available.
+      observation: {
+        summary: `I looked into ${label}: ${facts.join("; ")}.`,
+        room: label,
+        address,
+        ...channel.topic ? { topic: channel.topic } : {},
+        ...channel.parent?.name ? { parent: `#${channel.parent.name}` } : {},
+        ...typeof channel.memberCount === "number" ? { memberCount: channel.memberCount } : {}
+      }
+    };
+  });
+  let closed = false;
+  will.on("message", (m) => {
+    if (!closed) void deliver(m);
+  });
+  async function deliver(m) {
+    const peer = m.to ? roster.resolve(m.to) : void 0;
+    const chunks = chunkText(m.content, DISCORD_MESSAGE_LIMIT);
+    const replyTo = m.thread?.startsWith("discord:") ? m.thread.slice("discord:".length) : void 0;
+    const channelIds = [replyTo, peer?.lastChannelId, peer?.dmChannelId, opts.homeChannelId ?? void 0, lastActiveChannelId ?? void 0];
+    for (const id of channelIds) {
+      if (!id) continue;
+      try {
+        const channel = await client.channels.fetch(id);
+        if (!channel?.send) continue;
+        for (const chunk of chunks) await channel.send(chunk);
+        return;
+      } catch {
+      }
+    }
+    if (peer) {
+      try {
+        const user = await client.users.fetch(peer.userId);
+        for (const chunk of chunks) await user.send(chunk);
+        return;
+      } catch {
+      }
+    }
+    log(`no route for utterance to '${m.to}' \u2014 dropped (${m.content.length} chars)`);
+  }
+  const bridge = {
+    kind: "discord",
+    async start() {
+      if (!client.user) {
+        const ready = new Promise((resolve) => {
+          let poll = null;
+          const done = () => {
+            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() {
+      if (closed) return;
+      closed = true;
+      roster.flush();
+      await Promise.resolve(client.destroy()).catch(() => {
+      });
+    }
+  };
+  return bridge;
+}
+async function createDiscordClient() {
+  let mod;
+  try {
+    mod = await import('discord.js');
+  } catch {
+    throw new Error("discord.js is not installed (it is an optionalDependency) \u2014 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,
+      // Neither is privileged, so this costs nothing to ask for — and without
+      // them an emoji answer never arrives and reads as being ignored.
+      GatewayIntentBits.GuildMessageReactions,
+      GatewayIntentBits.DirectMessageReactions
+    ],
+    partials: [
+      Partials.Channel,
+      // DMs arrive on uncached channels
+      // A reaction on a message this process did not cache — i.e. anything said
+      // before the last restart — is delivered partial, and without these the
+      // event is dropped before the handler sees it. That is precisely the
+      // long-running conversation the answered loop exists for.
+      Partials.Message,
+      Partials.Reaction
+    ]
+  });
+}
+function parseMentionOnly(raw) {
+  const v = raw?.trim();
+  if (!v) return false;
+  if (/^(1|true|yes)$/i.test(v)) return true;
+  if (/^(0|false|no)$/i.test(v)) return false;
+  const ids = v.split(",").map((s) => s.trim()).filter(Boolean);
+  return ids.length ? ids : false;
+}
+function parseChannels(raw) {
+  const ids = raw?.split(",").map((s) => s.trim()).filter(Boolean);
+  return ids?.length ? ids : void 0;
+}
+
+export { connectDiscord, parseChannels, parseMentionOnly };
+//# sourceMappingURL=discord.js.map
+//# sourceMappingURL=discord.js.map