privateer-agent 0.9.2 → 0.10.0

package/src/channels/bridge.ts

@@ -2,15 +2,25 @@
 // RemoteBridge for the relay. It owns the policy that must be identical on every
 // platform:
 //   - allowlist    (who may drive the agent; fail-closed + silent to strangers)
+//   - mention gate  (in a shared room, only act when addressed)
 //   - serialization (one turn per conversation at a time; extra messages queue)
 //   - redaction     (chat platforms are external egress — scrub before send)
-//   - chunking      (respect the platform's per-message length cap)
+//   - chunking      (respect the platform's per-message byte cap)
+//
+// ⚠️ SECURITY — DO NOT RESOLVE QUOTED PARENTS. An inbound message may carry a
+// `replyToId`, and it is tempting to fetch that parent and inline its text into the
+// prompt for context. Don't. The allowlist gates the SENDER, not the room: on a
+// shared platform (Buzz channels, a Discord guild, a Slack channel) anyone can post,
+// and resolving quoted parents would let a non-allowlisted participant inject
+// arbitrary text into the agent's context simply by getting an admin to reply to
+// them. Threading ids are for ADDRESSING replies outward, never for pulling content
+// inward.
 //
 // The agent itself is injected as `runTurn`, so this file stays Pi-free and
 // unit-testable against a fake adapter + fake runner (see tests/channels.test.ts).
 // The Pi-backed runner lives in ./run.ts.
 
-import type { ChannelAdapter, InboundMessage } from "./types.ts";
+import type { ChannelAdapter, InboundMessage, SendOptions } from "./types.ts";
 
 // A minimal view of the permission request the gate hands us (see
 // src/permissions/gate.ts PermissionRequest). Kept local so the bridge doesn't
@@ -48,8 +58,19 @@ export interface AuditEvent {
   userId?: string;
   role?: "admin" | "member";
   detail?: string;
+  /** The platform id of the triggering message, when the platform has one — makes an
+   *  audit line traceable back to the exact message in the channel. Note we
+   *  deliberately do NOT log `mentions`: other participants' ids are third-party PII
+   *  and don't belong in an append-only file. */
+  messageId?: string;
 }
 
+/** Whether the agent answers everything in a conversation, or only when addressed.
+ *   off           — every allowlisted message runs a turn (the original behavior)
+ *   mention       — only when the message @-mentions this agent
+ *   mention-or-dm — as above, plus any 1:1 conversation */
+export type MentionGate = "off" | "mention" | "mention-or-dm";
+
 export interface MessagingBridgeConfig {
   adapter: ChannelAdapter;
   runTurn: TurnRunner;
@@ -62,15 +83,19 @@ export interface MessagingBridgeConfig {
   isAdmin: (msg: InboundMessage) => boolean;
   // Scrub secrets from every outbound message. Wired to redactText in ./run.ts.
   redact?: (text: string) => string;
+  // Should the agent answer everything, or only when addressed? Defaults to "off",
+  // preserving the original behavior for every existing platform.
+  mentionGate?: MentionGate;
   onLog?: (msg: string) => void;
   // Optional append-only security audit sink.
   onAudit?: (event: AuditEvent) => void;
 }
 
-// Stay comfortably under Telegram's 4096-char hard cap (Slack ~40k, Discord 2000 —
-// pick the tightest common bound for the shared path; a platform with a smaller cap
-// can override in its adapter later).
-const MAX_MSG = 1900;
+// Fallback per-message ceiling in BYTES, used only when an adapter doesn't declare
+// its own `maxMessageBytes`. It is the tightest common bound (Discord's 2000-char
+// cap, with headroom), so it is safe everywhere and generous nowhere — adapters
+// should declare the real figure. See channels/platforms.ts for the per-platform table.
+const DEFAULT_MAX_BYTES = 1900;
 
 // How long to wait for a yes/no approval reply before failing closed (deny).
 const APPROVAL_TIMEOUT_MS = 120_000;
@@ -94,21 +119,80 @@ export function approvalPrompt(req: ApprovalRequest): string {
   return `⚠️ Approval needed — ${req.title} (${req.kind})\n\n${detail}\n\nReply "yes" to allow or "no" to deny (times out in 2 min).`;
 }
 
-// Split text into <=max chunks, preferring newline boundaries so code/paragraphs
-// aren't cut mid-line when possible.
-export function chunkText(text: string, max = MAX_MSG): string[] {
+// The longest prefix of `s` that fits in `maxBytes` of UTF-8, cut only on code-point
+// boundaries. Iterating the string yields whole code points, so a surrogate pair is
+// never split down the middle into two replacement characters.
+function sliceByBytes(s: string, maxBytes: number): string {
+  if (Buffer.byteLength(s) <= maxBytes) return s;
+  let bytes = 0;
+  let out = "";
+  for (const ch of s) {
+    const b = Buffer.byteLength(ch);
+    if (bytes + b > maxBytes) break;
+    bytes += b;
+    out += ch;
+  }
+  return out;
+}
+
+// Split text into chunks that each fit in `maxBytes`, preferring newline boundaries
+// so code/paragraphs aren't cut mid-line when possible.
+//
+// The cap is in BYTES, not characters, because every platform's limit ultimately is:
+// a reply of emoji or CJK is up to 4x longer on the wire than its `.length` suggests,
+// and measuring in characters silently overshoots and gets the message rejected.
+export function chunkText(text: string, maxBytes = DEFAULT_MAX_BYTES): string[] {
   const out: string[] = [];
   let rest = text;
-  while (rest.length > max) {
-    let cut = rest.lastIndexOf("\n", max);
-    if (cut < max * 0.5) cut = max; // no usable newline in the back half → hard cut
-    out.push(rest.slice(0, cut));
-    rest = rest.slice(cut).replace(/^\n/, "");
+  while (Buffer.byteLength(rest) > maxBytes) {
+    let head = sliceByBytes(rest, maxBytes);
+    // A single code point wider than the cap would otherwise loop forever.
+    if (!head) head = [...rest][0] ?? "";
+    if (!head) break;
+    const nl = head.lastIndexOf("\n");
+    if (nl > 0 && nl >= head.length * 0.5) head = head.slice(0, nl); // usable newline in the back half
+    out.push(head);
+    rest = rest.slice(head.length).replace(/^\n/, "");
   }
   if (rest) out.push(rest);
   return out;
 }
 
+/**
+ * Should this message run a turn at all?
+ *
+ * In a 1:1 chat "answer everything" is right. In a shared room with other humans it
+ * is unusable noise — and worse, it means every passing remark becomes a prompt. So
+ * a channel can require being addressed.
+ *
+ * Fails CLOSED on adapters that can't report mentions: if the gate is on and
+ * `mentionsMe` is absent, the agent stays quiet rather than answering everything.
+ * Enabling a gate a platform can't honour should silence the bot, not defeat the gate.
+ */
+export function passesMentionGate(m: InboundMessage, mode: MentionGate | undefined): boolean {
+  if (!mode || mode === "off") return true;
+  if (m.mentionsMe) return true;
+  return mode === "mention-or-dm" && m.isDirect === true;
+}
+
+/**
+ * Render attachments into the prompt text.
+ *
+ * v1 is a text footer: `TurnRunner` carries only a string, so real multimodal means
+ * widening that signature and routing bytes through src/util/attachmentStore.ts.
+ * This is the seam where that would go. Deliberately out of scope for now — the URL
+ * is enough for an agent with web/read tools to act on.
+ */
+export function promptWithAttachments(m: InboundMessage): string {
+  const text = m.text.trim();
+  if (!m.attachments?.length) return text;
+  const lines = m.attachments.map((a) => {
+    const bits = [a.mediaType ?? "file", a.name, a.url ?? a.id].filter(Boolean);
+    return `[attached: ${bits.join(" — ")}]`;
+  });
+  return text ? `${text}\n\n${lines.join("\n")}` : lines.join("\n");
+}
+
 export class MessagingBridge {
   // Per-chat promise tail: each new turn chains onto the previous so turns in the
   // same conversation never interleave (they share one agent session downstream).
@@ -118,6 +202,15 @@ export class MessagingBridge {
   // Per-chat pending tool approval awaiting a yes/no reply. At most one at a time
   // per chat (turns are serialized and a turn's tool calls are sequential).
   private readonly approvals = new Map<string, (decision: "allow" | "deny") => void>();
+  // Where to attach outbound messages in each chat, so replies, approval prompts and
+  // error lines all land in the thread that triggered them rather than at the bottom
+  // of the room. Empty for platforms without threading — `sendReply` then degrades to
+  // a plain send.
+  private readonly lastInbound = new Map<string, { messageId?: string; threadRootId?: string }>();
+  // Set by stop(). Aborting a turn signals the GATE, not Pi's session.prompt() — so
+  // an in-flight turn can still resolve after teardown and try to send its answer
+  // through a closed adapter. Every send path checks this first.
+  private stopped = false;
 
   constructor(private readonly cfg: MessagingBridgeConfig) {}
 
@@ -126,13 +219,16 @@ export class MessagingBridge {
     this.log(`channel "${this.cfg.adapter.name}" listening`);
   }
 
-  stop(): void {
-    this.cfg.adapter.stop();
+  async stop(): Promise<void> {
+    this.stopped = true;
     for (const a of this.aborts.values()) a.abort();
     this.aborts.clear();
     // Fail any pending approvals closed so no turn hangs on shutdown.
     for (const resolve of this.approvals.values()) resolve("deny");
     this.approvals.clear();
+    // Last: an adapter owning a listening socket resolves only once the port is
+    // genuinely free, which a targeted platform restart depends on.
+    await this.cfg.adapter.stop();
   }
 
   // Ask the user in `chatId` to approve a gated tool action, and await their yes/no
@@ -141,6 +237,9 @@ export class MessagingBridge {
   // or shutdown all resolve to "deny". Public because the gate calls it directly
   // (via an AsyncLocalStorage handle to this bridge + the current chat id).
   requestApproval(chatId: string, req: ApprovalRequest, signal?: AbortSignal): Promise<"allow" | "deny"> {
+    // Torn down: nobody is listening for the reply, so fail closed immediately rather
+    // than prompting into a dead channel and waiting out the 2-minute timeout.
+    if (this.stopped) return Promise.resolve("deny");
     // Only one outstanding approval per chat; deny any stale one first.
     this.approvals.get(chatId)?.("deny");
 
@@ -153,7 +252,10 @@ export class MessagingBridge {
       role: "admin", // approvals only arise from admin turns (members are read-only)
       detail: this.cfg.redact ? this.cfg.redact(detail) : detail,
     });
-    void this.cfg.adapter.sendText(chatId, this.cfg.redact ? this.cfg.redact(prompt) : prompt);
+    // Threaded alongside the turn that raised it, so a busy room doesn't scatter the
+    // question away from the request that prompted it.
+    const opts = this.sendOptions(chatId);
+    void this.cfg.adapter.sendText(chatId, this.cfg.redact ? this.cfg.redact(prompt) : prompt, opts);
 
     return new Promise<"allow" | "deny">((resolve) => {
       let timer: ReturnType<typeof setTimeout>;
@@ -165,11 +267,11 @@ export class MessagingBridge {
         resolve(decision);
       };
       const onAbort = () => {
-        void this.cfg.adapter.sendText(chatId, "🚫 request interrupted — denied.");
+        void this.cfg.adapter.sendText(chatId, "🚫 request interrupted — denied.", opts);
         settle("deny");
       };
       timer = setTimeout(() => {
-        void this.cfg.adapter.sendText(chatId, "⌛ approval timed out — denied.");
+        void this.cfg.adapter.sendText(chatId, "⌛ approval timed out — denied.", opts);
         settle("deny");
       }, APPROVAL_TIMEOUT_MS);
       this.approvals.set(chatId, settle);
@@ -184,6 +286,14 @@ export class MessagingBridge {
     this.cfg.onLog?.(msg);
   }
 
+  // Where an outbound message for this chat should attach. Undefined on platforms
+  // that don't carry message ids, which every adapter accepts as "just send it".
+  private sendOptions(chatId: string): SendOptions | undefined {
+    const last = this.lastInbound.get(chatId);
+    if (!last?.messageId) return undefined;
+    return { replyTo: last.messageId, threadRoot: last.threadRootId ?? last.messageId };
+  }
+
   private audit(m: InboundMessage, event: AuditEvent["event"], detail?: string): void {
     if (!this.cfg.onAudit) return;
     const red = detail && this.cfg.redact ? this.cfg.redact(detail) : detail;
@@ -194,10 +304,12 @@ export class MessagingBridge {
       userId: m.userId,
       role: this.cfg.isAdmin(m) ? "admin" : "member",
       detail: red,
+      messageId: m.messageId,
     });
   }
 
   private onMessage(m: InboundMessage): void {
+    if (this.stopped) return; // torn down; an adapter may still flush a queued frame
     const text = m.text?.trim();
     if (!text) return;
 
@@ -240,6 +352,17 @@ export class MessagingBridge {
       return;
     }
 
+    // The mention gate sits HERE and the position is load-bearing. It must come
+    // after the approval interception and after "/stop", because neither of those
+    // carries an @mention: gating an approval reply would leave the waiting turn
+    // hanging until its 2-minute fail-closed timeout, and gating "/stop" would make
+    // the channel uninterruptible.
+    if (!passesMentionGate(m, this.cfg.mentionGate)) return;
+
+    // Remember where to attach the reply. Recorded only for messages that actually
+    // run a turn, so an approval answer can't retarget the thread mid-conversation.
+    this.lastInbound.set(m.chatId, { messageId: m.messageId, threadRootId: m.threadRootId });
+
     // Serialize per conversation: chain onto this chat's tail.
     const prev = this.tails.get(m.chatId) ?? Promise.resolve();
     const next = prev
@@ -248,7 +371,10 @@ export class MessagingBridge {
     this.tails.set(m.chatId, next);
     // Drop the tail once this was the last queued turn, so the map doesn't grow.
     void next.finally(() => {
-      if (this.tails.get(m.chatId) === next) this.tails.delete(m.chatId);
+      if (this.tails.get(m.chatId) === next) {
+        this.tails.delete(m.chatId);
+        this.lastInbound.delete(m.chatId); // the reply is out; nothing left to attach to
+      }
     });
   }
 
@@ -267,7 +393,7 @@ export class MessagingBridge {
     let buf = "";
     let result: { ok: boolean; error?: string };
     try {
-      result = await this.cfg.runTurn(chatId, m.text.trim(), (d) => (buf += d), ac.signal, {
+      result = await this.cfg.runTurn(chatId, promptWithAttachments(m), (d) => (buf += d), ac.signal, {
         userId: m.userId,
         isAdmin,
       });
@@ -279,15 +405,35 @@ export class MessagingBridge {
 
     const body = this.cfg.redact ? this.cfg.redact(buf) : buf;
 
+    // The turn may have outlived stop() (aborting reaches the gate, not Pi). Drop the
+    // answer rather than pushing it through a closed adapter — on a targeted restart
+    // the replacement bridge is already serving this chat.
+    if (this.stopped) {
+      this.log(`dropped a reply for chat ${chatId} — the channel was stopped mid-turn`);
+      return;
+    }
+
+    // Send in the thread the request came from, chaining each chunk beneath the
+    // previous one when the adapter tells us the id it just wrote — so a long,
+    // multi-chunk answer reads as one conversation rather than N siblings.
+    const opts = this.sendOptions(chatId);
+    const root = opts?.threadRoot;
+    let parent = opts?.replyTo;
+    const send = async (t: string) => {
+      const id = await this.cfg.adapter.sendText(chatId, t, parent ? { replyTo: parent, threadRoot: root } : undefined);
+      if (typeof id === "string" && id) parent = id;
+    };
+
     // Deliver any text the turn produced (even on error — a partial answer is
     // useful), then an error line if it failed.
     if (body.trim()) {
-      for (const chunk of chunkText(body)) await this.cfg.adapter.sendText(chatId, chunk);
+      const maxBytes = this.cfg.adapter.maxMessageBytes ?? DEFAULT_MAX_BYTES;
+      for (const chunk of chunkText(body, maxBytes)) await send(chunk);
     } else if (result.ok) {
-      await this.cfg.adapter.sendText(chatId, "✓ done (no text output).");
+      await send("✓ done (no text output).");
     }
     if (!result.ok) {
-      await this.cfg.adapter.sendText(chatId, `⚠️ ${result.error ?? "the agent hit an error"}`);
+      await send(`⚠️ ${result.error ?? "the agent hit an error"}`);
     }
   }
 }

package/src/channels/platforms.ts

@@ -0,0 +1,64 @@
+// The per-platform facts that BOTH the channels runtime and the app-facing config
+// control need to agree on: which platforms exist, which of their fields are
+// secrets, how big a single message may be, and whether a given config block has
+// enough in it to start.
+//
+// This file is deliberately the ONLY place those four things are declared. Before
+// it existed they were duplicated between the `startChannel` if-chain in run.ts and
+// the CHANNEL_PLATFORMS/SECRET_FIELDS constants in remote/channelsControl.ts, with
+// a "keep in sync" comment as the only thing holding them together. Adding a
+// platform now means editing this file plus wiring one adapter.
+//
+// Pi-free and dependency-free on purpose: channelsControl.ts runs inside the harbor
+// (which must be able to configure a channel that has never run), while the runtime
+// runs wherever the bots live. Both import this; neither imports the other.
+
+export const CHANNEL_PLATFORMS = ["telegram", "slack", "discord", "whatsapp"] as const;
+export type ChannelPlatform = (typeof CHANNEL_PLATFORMS)[number];
+
+export function isChannelPlatform(v: unknown): v is ChannelPlatform {
+  return typeof v === "string" && (CHANNEL_PLATFORMS as readonly string[]).includes(v);
+}
+
+// The secret (never-echoed) fields per platform — the union of the credentials each
+// platform needs to START. `secretsSet` in the app reports the PRESENCE of these by
+// name; their values never cross the wire back to the app.
+export const SECRET_FIELDS: Record<ChannelPlatform, readonly string[]> = {
+  telegram: ["botToken"],
+  slack: ["appToken", "botToken"],
+  discord: ["botToken"],
+  whatsapp: ["phoneNumberId", "accessToken", "verifyToken", "appSecret"],
+};
+
+// Per-message size ceiling, in BYTES of UTF-8 content, sitting just under each
+// platform's documented hard cap so a multi-byte reply can't overshoot:
+//   telegram 4096 chars · slack ~40k · discord 2000 chars · whatsapp 4096 chars
+// The bridge reads the adapter's own `maxMessageBytes` at send time; this table is
+// what the adapters (and outbound delivery, which has no adapter instance in hand)
+// are configured from.
+export const MAX_MESSAGE_BYTES: Record<ChannelPlatform, number> = {
+  telegram: 4000,
+  slack: 39_000,
+  discord: 1900,
+  whatsapp: 3900,
+};
+
+// Does this config block carry everything the platform needs to start? Mirrors the
+// conditions the runtime uses to decide whether to construct an adapter at all.
+//
+// NOTE this checks CREDENTIALS only. The other fail-closed requirement — at least
+// one admin or member — is deliberately NOT here: it's shared across every platform
+// and is enforced once, by the runtime and by channelsControl.save().
+export function startableFrom(platform: ChannelPlatform, block: any): boolean {
+  if (!block) return false;
+  switch (platform) {
+    case "telegram":
+      return !!block.botToken;
+    case "slack":
+      return !!block.appToken && !!block.botToken;
+    case "discord":
+      return !!block.botToken;
+    case "whatsapp":
+      return !!block.phoneNumberId && !!block.accessToken && !!block.verifyToken;
+  }
+}

package/src/channels/run.ts

@@ -106,6 +106,13 @@ function normalizePosture(v: unknown): Posture | undefined {
 }
 
 async function main() {
+  // Mark the process before anything can create a session. This runner builds its
+  // session with its own makePermissionGate (the in-chat approver below), but the
+  // shipped TUI gate extension is still auto-discovered from the shared agent dir —
+  // and with no UI bound here its local asker fails CLOSED, denying every gated tool
+  // before our approver is ever consulted. See config/inlineMoat.ts.
+  const { markInlineMoat } = await import("../config/inlineMoat.ts");
+  markInlineMoat();
   const { readFileSync, appendFileSync } = await import("node:fs");
   const { join } = await import("node:path");
   const {
@@ -131,6 +138,8 @@ async function main() {
   const { DiscordAdapter } = await import("./discord.ts");
   const { WhatsAppAdapter } = await import("./whatsapp.ts");
   const { writeChannelsStatus, HEARTBEAT_MS } = await import("./status.ts");
+  const { startableFrom } = await import("./platforms.ts");
+  const { buzzRedactionSecrets } = await import("../nostr/keys.ts");
   type ChannelAdapter = import("./types.ts").ChannelAdapter;
 
   // ── config ──────────────────────────────────────────────────────────────────
@@ -149,7 +158,10 @@ async function main() {
     : (web ? [...SAFE_TOOLS, ...WEB_TOOLS] : [...SAFE_TOOLS]);
   const defaultPosture: Posture = normalizePosture(ch.posture) ?? "approve";
   const cwd: string = ch.cwd ?? process.cwd();
-  const secrets = collectSecrets(cfg.providers);
+  // Provider API keys, plus this machine's Nostr secret if one has been minted.
+  // The agent can READ its own key file, so without this it could quote its own
+  // permanent identity into a public channel. Non-minting: absent → nothing added.
+  const secrets = [...collectSecrets(cfg.providers), ...buzzRedactionSecrets()];
   const redact = (t: string) => redactText(t, secrets);
 
   // Append-only security audit log — every prompt, approval request/decision, and
@@ -279,7 +291,7 @@ async function main() {
   sweep.unref?.();
 
   // ── build a bridge per configured platform ───────────────────────────────────
-  const bridges: { stop(): void }[] = [];
+  const bridges: { stop(): Promise<void> }[] = [];
   // Platforms with a live bridge — written to the heartbeat file so the app's
   // channels manager (running on the harbor's relay, a separate process) can show
   // a live/offline badge without talking to this process.
@@ -343,28 +355,30 @@ async function main() {
     );
   }
 
-  if (ch.telegram?.botToken) {
+  // Which credentials each platform needs to start is declared once, in
+  // channels/platforms.ts, so this list and the app's config validator can't drift.
+  if (startableFrom("telegram", ch.telegram)) {
     await startChannel(
       "telegram",
       new TelegramAdapter({ botToken: ch.telegram.botToken, onLog: log }),
       ch.telegram,
     );
   }
-  if (ch.slack?.appToken && ch.slack?.botToken) {
+  if (startableFrom("slack", ch.slack)) {
     await startChannel(
       "slack",
       new SlackAdapter({ appToken: ch.slack.appToken, botToken: ch.slack.botToken, onLog: log }),
       ch.slack,
     );
   }
-  if (ch.discord?.botToken) {
+  if (startableFrom("discord", ch.discord)) {
     await startChannel(
       "discord",
       new DiscordAdapter({ botToken: ch.discord.botToken, intents: ch.discord.intents, onLog: log }),
       ch.discord,
     );
   }
-  if (ch.whatsapp?.phoneNumberId && ch.whatsapp?.accessToken && ch.whatsapp?.verifyToken) {
+  if (startableFrom("whatsapp", ch.whatsapp)) {
     await startChannel(
       "whatsapp",
       new WhatsAppAdapter({
@@ -397,7 +411,10 @@ async function main() {
     clearInterval(sweep);
     clearInterval(heartbeat);
     writeChannelsStatus([]); // clear presence immediately, don't wait for staleness
-    for (const b of bridges) b.stop();
+    // Fire-and-forget: process exit releases every socket and port anyway, so there's
+    // nothing to wait for here. Awaiting matters for a TARGETED restart (one platform
+    // rebinding its port while the process lives on), not for shutdown.
+    for (const b of bridges) void b.stop();
     process.exit(0);
   };
   process.on("SIGINT", shutdown);

package/src/channels/types.ts

@@ -1,11 +1,29 @@
 // Messaging-channel plumbing — the inbound/conversational counterpart to the relay.
 //
 // The relay (src/remote/*) lets the Privateer app drive this terminal. A messaging
-// channel (Telegram/Slack/Discord/WhatsApp) is the SAME idea with a different
-// transport: a user's message becomes a prompt, the agent's reply goes back to the
-// channel. `ChannelAdapter` is the one platform-specific seam; everything above it
-// (allowlist, per-chat serialization, redaction, chunking) lives in MessagingBridge
-// and is shared across every platform.
+// channel (Telegram/Slack/Discord/Buzz) is the SAME idea with a different transport:
+// a user's message becomes a prompt, the agent's reply goes back to the channel.
+// `ChannelAdapter` is the one platform-specific seam; everything above it (allowlist,
+// mention gating, per-chat serialization, redaction, chunking) lives in
+// MessagingBridge and is shared across every platform.
+//
+// EVERY field beyond the original four is OPTIONAL, and that is a load-bearing
+// design choice rather than politeness: an adapter that cannot thread, cannot see
+// mentions, or carries no message ids simply omits them, and the bridge reads
+// "absent" as "this platform doesn't support it". That is what lets a rich platform
+// (Buzz: message ids, NIP-10 threads, relay-indexed mentions, Blossom attachments)
+// share one contract with a plain one, with no per-adapter branching in the bridge.
+
+/** A file or image referenced by an inbound message. */
+export interface Attachment {
+  /** The platform's content id — Buzz: the Blossom sha256. */
+  id?: string;
+  /** Fetchable by this machine. May require adapter-supplied auth. */
+  url?: string;
+  mediaType?: string;
+  name?: string;
+  bytes?: number;
+}
 
 // A normalized inbound message from any platform. `chatId` scopes the conversation
 // (so each thread keeps its own agent session); `userId` is who sent it (allowlist
@@ -16,21 +34,74 @@ export interface InboundMessage {
   userId: string;
   userName?: string;
   text: string;
+
+  /** This message's own platform id — Buzz: the nostr event id. Needed to reply
+   *  in-thread or react to it. */
+  messageId?: string;
+  /** The message this one directly answers — Buzz: NIP-10 "e" tag marked "reply". */
+  replyToId?: string;
+  /** The root of the thread this belongs to — Buzz: "e" marked "root". Equal to
+   *  `replyToId` at depth one. */
+  threadRootId?: string;
+  /** Everyone this message @-mentions, in platform-native id form. */
+  mentions?: string[];
+  /** Does it mention THIS agent? Only the adapter knows its own identity on the
+   *  platform, so the adapter reports the FACT — the bridge owns the POLICY of what
+   *  to do about it (see `mentionGate`). */
+  mentionsMe?: boolean;
+  /** True when this is a 1:1 conversation rather than a shared room — Buzz: a
+   *  channel of type "Dm". A DM is inherently addressed to the agent, so the
+   *  mention gate can let it through without an explicit @. */
+  isDirect?: boolean;
+  attachments?: Attachment[];
+}
+
+/** How an outbound message relates to the conversation. An adapter that can't
+ *  thread ignores this entirely — passing it is always safe. */
+export interface SendOptions {
+  replyTo?: string;
+  threadRoot?: string;
+}
+
+export interface OutboundMedia {
+  bytes: Uint8Array;
+  mediaType: string;
+  name?: string;
+  caption?: string;
 }
 
 // The per-platform transport. Implementations own the connection (long-poll,
-// gateway socket, or inbound webhook) and the wire format; they surface normalized
-// messages and accept plain text back. Keep them DUMB: no allowlist, no redaction,
-// no chunking — the bridge does all of that so it's written once and tested once.
+// gateway socket, relay websocket, or inbound webhook) and the wire format; they
+// surface normalized messages and accept plain text back. Keep them DUMB: no
+// allowlist, no redaction, no chunking, no gating — the bridge does all of that so
+// it's written once and tested once.
 export interface ChannelAdapter {
   readonly name: string;
+  /** This agent's own id on the platform — Buzz: its pubkey hex. Used to recognize
+   *  self-authored events and to resolve `mentionsMe`. Absent when the platform has
+   *  no stable identity for the bot. */
+  readonly selfId?: string;
+  /** Per-message ceiling in BYTES of UTF-8 content. The bridge chunks to this;
+   *  absent falls back to a conservative shared default. Before this existed the
+   *  bridge hardcoded Discord's limit for every platform. */
+  readonly maxMessageBytes?: number;
+
   // Begin receiving. Call `onMessage` for every inbound user message.
   start(onMessage: (m: InboundMessage) => void): Promise<void>;
-  // Send a reply to a conversation. The bridge guarantees `text` is already
-  // redacted and within the platform's per-message length cap.
-  sendText(chatId: string, text: string): Promise<void>;
+  /** Send a reply. The bridge guarantees `text` is already redacted and within
+   *  `maxMessageBytes`. Returns the sent message's platform id when the adapter
+   *  knows it, so the bridge can chain later chunks beneath it — returning nothing
+   *  is fine and simply means later chunks hang off the same parent. */
+  sendText(chatId: string, text: string, opts?: SendOptions): Promise<string | void>;
   // Optional "the agent is working" affordance (typing indicator). Best-effort.
   sendTyping?(chatId: string): void;
-  // Stop receiving and release the connection.
-  stop(): void;
+  /** React to a message — Buzz: NIP-25 kind 7. Best-effort; never awaited on a
+   *  path that must not fail. */
+  sendReaction?(chatId: string, messageId: string, emoji: string): Promise<void>;
+  sendMedia?(chatId: string, media: OutboundMedia, opts?: SendOptions): Promise<void>;
+  // Stop receiving and release the connection. May be async: an adapter that owns a
+  // LISTENING SOCKET (whatsapp) has to await the port actually being free, or the
+  // next start() races its own teardown and fails with EADDRINUSE. Callers must
+  // await this before restarting the same platform.
+  stop(): void | Promise<void>;
 }