@moxxy/plugin-channel-discord 0.27.0

package/src/pairing.ts

@@ -0,0 +1,178 @@
+import { randomCode } from '@moxxy/plugin-vault';
+import {
+  clearHostCodePairing,
+  createHostCodeState,
+  greetPeer,
+  isPeerAuthorized,
+  openHostCodeWindow,
+  submitPeerCode,
+  type HostCodeAction,
+  type HostCodeState,
+} from '@moxxy/channel-kit';
+
+/**
+ * Discord pairing — the kit's host-code machine, driven over DM in the
+ * "bot replies with a code, operator pastes it in the terminal" direction.
+ *
+ * Flow (the wizard/`moxxy discord pair` arms it):
+ *   1. The channel starts with a pairing window ARMED (no code yet).
+ *   2. An unauthorized user DMs the bot → we mint a one-time code bound to
+ *      THAT user ({@link mintCodeForPeer} = `openHostCodeWindow` with the
+ *      DM-ing user recorded as the pending peer) and DM the code back.
+ *   3. The operator pastes the code into the terminal wizard →
+ *      {@link confirmPendingCode} (`submitPeerCode` against the pending peer).
+ *      On match the DM-ing user becomes the authorized principal.
+ *
+ * Security property: the code only ever lives in the candidate's DM, so
+ * pasting it in the terminal proves the operator controls (or trusts) that
+ * Discord account. A different user DM-ing while armed re-mints the window
+ * for themselves — which STALES the earlier code, so the operator's paste of
+ * the legitimate code then mismatches and pairing simply retries; an attacker
+ * can never be authorized unless the operator pastes the ATTACKER's code
+ * (which only exists in the attacker's DM).
+ *
+ * The transitions live in `@moxxy/channel-kit` (generic over the peer id —
+ * a Discord user id string here); this module keeps the Discord-shaped state
+ * (armed flag + pending peer) and maps the kit's semantic action kinds to
+ * Discord-worded messages.
+ */
+
+export type DiscordPairingPhase = 'idle' | 'armed' | 'awaiting-host-code' | 'paired' | 'expired';
+
+export interface DiscordPairingState {
+  /** Kit machine state; peer = Discord user id. */
+  readonly kit: HostCodeState<string>;
+  /** A pairing window is armed (codes will be minted for DM-ing users). */
+  readonly armed: boolean;
+  /** The user the CURRENT code was minted for (null when none outstanding). */
+  readonly pendingUserId: string | null;
+}
+
+export interface DiscordPairingDecision {
+  readonly state: DiscordPairingState;
+  readonly action:
+    | { kind: 'code-minted'; userId: string; code: string }
+    | { kind: 'paired'; userId: string }
+    | { kind: 'still-paired'; userId: string }
+    | { kind: 'reject'; message: string }
+    | { kind: 'mismatch'; message: string }
+    | { kind: 'not-pending'; message: string }
+    | { kind: 'expired'; message: string };
+}
+
+const MSG_FOREIGN_USER = 'This bot is paired with a different Discord account. Access denied.';
+const MSG_NOT_ARMED =
+  'No pairing window is open. Run `moxxy discord pair` in the moxxy terminal first, then DM me again.';
+const MSG_NOT_PENDING = 'No pairing code is outstanding. DM the bot first — it replies with a code.';
+const MSG_MISMATCH =
+  "That code didn't match. Check the code in the bot's most recent DM reply and try again.";
+const MSG_EXPIRED = 'The pairing code expired. DM the bot again for a fresh one.';
+
+export function createDiscordPairingState(
+  opts: { authorizedUserId?: string | null } = {},
+): DiscordPairingState {
+  return {
+    kit: createHostCodeState<string>({ authorizedPeer: opts.authorizedUserId ?? null }),
+    armed: false,
+    pendingUserId: null,
+  };
+}
+
+export function pairingPhase(state: DiscordPairingState): DiscordPairingPhase {
+  if (state.kit.phase === 'paired') return 'paired';
+  if (state.kit.phase === 'awaiting-host-code') return 'awaiting-host-code';
+  if (state.kit.phase === 'expired') return 'expired';
+  return state.armed ? 'armed' : 'idle';
+}
+
+/** Arm the pairing window: DM-ing users will now be issued one-time codes. */
+export function armPairing(state: DiscordPairingState): DiscordPairingState {
+  return { ...state, armed: true };
+}
+
+export function isUserAuthorized(state: DiscordPairingState, userId: string): boolean {
+  return isPeerAuthorized(state.kit, userId);
+}
+
+export function clearDiscordPairing(state: DiscordPairingState): DiscordPairingState {
+  return {
+    kit: clearHostCodePairing(state.kit),
+    armed: state.armed,
+    pendingUserId: null,
+  };
+}
+
+/**
+ * An unauthorized user DMed the bot while a window may be armed. Mints a
+ * one-time code bound to that user (re-arming replaces any earlier pending
+ * code — see the module doc for why that fails safe) or rejects with the
+ * appropriate wording.
+ */
+export function mintCodeForPeer(
+  state: DiscordPairingState,
+  userId: string,
+  code: string = randomCode(6),
+): DiscordPairingDecision {
+  const greeted = greetPeer(state.kit, userId);
+  if (greeted.action.kind === 'still-paired') {
+    return { state, action: { kind: 'still-paired', userId } };
+  }
+  if (greeted.action.kind === 'rejected-foreign-peer') {
+    return { state, action: { kind: 'reject', message: MSG_FOREIGN_USER } };
+  }
+  if (!state.armed) {
+    return { state, action: { kind: 'reject', message: MSG_NOT_ARMED } };
+  }
+  const opened = openHostCodeWindow(state.kit, { code });
+  return {
+    state: { kit: opened.state, armed: true, pendingUserId: userId },
+    action: { kind: 'code-minted', userId, code: opened.code },
+  };
+}
+
+/** Map a kit action to the Discord-worded decision, reusing `state` when the
+ *  machine didn't transition. */
+function mapConfirmAction(
+  state: DiscordPairingState,
+  kitState: HostCodeState<string>,
+  action: HostCodeAction<string>,
+): DiscordPairingDecision {
+  switch (action.kind) {
+    case 'paired':
+      return {
+        state: { kit: kitState, armed: false, pendingUserId: null },
+        action: { kind: 'paired', userId: action.peer },
+      };
+    case 'still-paired':
+      return { state, action: { kind: 'still-paired', userId: action.peer } };
+    case 'rejected-foreign-peer':
+      return { state, action: { kind: 'reject', message: MSG_FOREIGN_USER } };
+    case 'window-open-hint':
+    case 'no-window':
+    case 'not-pending':
+      return { state, action: { kind: 'not-pending', message: MSG_NOT_PENDING } };
+    case 'expired':
+      return {
+        state: { kit: kitState, armed: state.armed, pendingUserId: null },
+        action: { kind: 'expired', message: MSG_EXPIRED },
+      };
+    case 'mismatch':
+      return { state, action: { kind: 'mismatch', message: MSG_MISMATCH } };
+  }
+}
+
+/**
+ * The operator pasted a code into the terminal wizard. Compared against the
+ * code minted for the CURRENT pending user; on match that user is authorized.
+ */
+export function confirmPendingCode(
+  state: DiscordPairingState,
+  rawCode: string,
+  now: number = Date.now(),
+): DiscordPairingDecision {
+  if (state.pendingUserId == null) {
+    return { state, action: { kind: 'not-pending', message: MSG_NOT_PENDING } };
+  }
+  const decision = submitPeerCode(state.kit, state.pendingUserId, rawCode, now);
+  return mapConfirmAction(state, decision.state, decision.action);
+}

package/src/permission.ts

@@ -0,0 +1,70 @@
+import type {
+  PendingToolCall,
+  PermissionContext,
+  PermissionDecision,
+  PermissionResolver,
+} from '@moxxy/sdk';
+
+export interface PendingPermission {
+  readonly callId: string;
+  readonly call: PendingToolCall;
+  readonly ctx: PermissionContext;
+  readonly resolve: (decision: PermissionDecision) => void;
+}
+
+/**
+ * Permission resolver that defers each tool call to an external decider (the
+ * Discord bot, which renders a button row and waits for a click). The channel
+ * registers an interaction handler that invokes `resolvePending(callId,
+ * decision)` when the paired user clicks a button. Mirrors the Telegram
+ * resolver's shape (pending map + setDecider + abortAll) — the button
+ * click arrives on a different code path than the check, so the shared
+ * `createDeferredPermissionResolver` (whose prompt must RETURN the decision)
+ * doesn't fit; the abortAll contract is preserved here instead.
+ */
+export class DiscordPermissionResolver implements PermissionResolver {
+  readonly name = 'discord';
+  private readonly pending = new Map<string, PendingPermission>();
+  private readonly sessionAllows = new Set<string>();
+  private deciderFn: ((call: PendingToolCall, ctx: PermissionContext) => Promise<void>) | null =
+    null;
+
+  setDecider(fn: (call: PendingToolCall, ctx: PermissionContext) => Promise<void>): void {
+    this.deciderFn = fn;
+  }
+
+  async check(call: PendingToolCall, ctx: PermissionContext): Promise<PermissionDecision> {
+    if (this.sessionAllows.has(call.name)) {
+      return { mode: 'allow_session', reason: 'allow_session previously granted' };
+    }
+    if (!this.deciderFn) {
+      return { mode: 'deny', reason: 'no decider attached (bot not running)' };
+    }
+    const decision = await new Promise<PermissionDecision>((resolve) => {
+      this.pending.set(call.callId, { callId: call.callId, call, ctx, resolve });
+      this.deciderFn!(call, ctx).catch((err) => {
+        this.pending.delete(call.callId);
+        resolve({ mode: 'deny', reason: err instanceof Error ? err.message : String(err) });
+      });
+    });
+    if (decision.mode === 'allow_session') this.sessionAllows.add(call.name);
+    return decision;
+  }
+
+  /** Called by the interaction handler when a permission button is clicked. */
+  resolvePending(callId: string, decision: PermissionDecision): boolean {
+    const pending = this.pending.get(callId);
+    if (!pending) return false;
+    this.pending.delete(callId);
+    pending.resolve(decision);
+    return true;
+  }
+
+  /** Deny every in-flight prompt — MUST run on channel stop so callers don't hang. */
+  abortAll(reason = 'channel closed'): void {
+    for (const pending of this.pending.values()) {
+      pending.resolve({ mode: 'deny', reason });
+    }
+    this.pending.clear();
+  }
+}

package/src/render.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import type { MoxxyEvent } from '@moxxy/sdk';
+import { DiscordTurnRenderer, splitForDiscord } from './render.js';
+
+const ev = (partial: Record<string, unknown>): MoxxyEvent => partial as unknown as MoxxyEvent;
+
+describe('DiscordTurnRenderer', () => {
+  it('accumulates chunks, prefers the final assistant message, reports updates', () => {
+    const r = new DiscordTurnRenderer();
+    expect(r.accept(ev({ type: 'assistant_chunk', delta: 'Hel' }))).toBe(true);
+    expect(r.accept(ev({ type: 'assistant_chunk', delta: 'lo' }))).toBe(true);
+    expect(r.snapshot()).toBe('Hello');
+    expect(r.accept(ev({ type: 'assistant_message', content: 'Hello, world.' }))).toBe(true);
+    expect(r.snapshot()).toBe('Hello, world.');
+    // Unknown events don't change the frame.
+    expect(r.accept(ev({ type: 'user_prompt', content: 'x' }))).toBe(false);
+  });
+
+  it('renders tool activity as a quote block with statuses', () => {
+    const r = new DiscordTurnRenderer();
+    r.accept(ev({ type: 'tool_call_requested', callId: 'c1', name: 'read_file', input: { path: '/tmp/x' } }));
+    expect(r.snapshot()).toContain('> - `read_file` (path=/tmp/x) — running…');
+    r.accept(ev({ type: 'tool_result', callId: 'c1', ok: true, output: 'ok' }));
+    expect(r.snapshot()).toMatch(/`read_file`.*— done /);
+    r.accept(ev({ type: 'tool_call_requested', callId: 'c2', name: 'bash', input: {} }));
+    r.accept(ev({ type: 'tool_call_denied', callId: 'c2', reason: 'denied by user' }));
+    expect(r.snapshot()).toContain('denied: denied by user');
+  });
+
+  it('surfaces error events', () => {
+    const r = new DiscordTurnRenderer();
+    r.accept(ev({ type: 'error', kind: 'provider', message: 'boom' }));
+    expect(r.snapshot()).toContain('❗ **provider**: boom');
+  });
+
+  it('reset clears everything', () => {
+    const r = new DiscordTurnRenderer();
+    r.accept(ev({ type: 'assistant_chunk', delta: 'x' }));
+    r.reset();
+    expect(r.snapshot()).toBe('');
+  });
+});
+
+describe('splitForDiscord (2000-char cap)', () => {
+  it('returns single part under the limit and [] for empty', () => {
+    expect(splitForDiscord('hi')).toEqual(['hi']);
+    expect(splitForDiscord('')).toEqual([]);
+  });
+
+  it('splits on newline boundaries and keeps every part under the cap', () => {
+    const line = 'a'.repeat(80);
+    const text = Array.from({ length: 60 }, () => line).join('\n'); // ~4860 chars
+    const parts = splitForDiscord(text, 500);
+    expect(parts.length).toBeGreaterThan(1);
+    for (const p of parts) expect(p.length).toBeLessThanOrEqual(500);
+    // No content lost: rejoining with newlines reproduces the original lines.
+    expect(parts.join('\n')).toBe(text);
+  });
+
+  it('closes and reopens a code fence across a cut (with its info string)', () => {
+    const fenceBody = Array.from({ length: 50 }, (_, i) => `line ${i}`).join('\n');
+    const text = 'intro\n```diff\n' + fenceBody + '\n```\noutro';
+    const parts = splitForDiscord(text, 120);
+    expect(parts.length).toBeGreaterThan(1);
+    for (const p of parts) expect(p.length).toBeLessThanOrEqual(120);
+    // Every part is fence-balanced (an even number of ``` markers).
+    for (const p of parts) {
+      const fences = p.match(/```/g) ?? [];
+      expect(fences.length % 2).toBe(0);
+    }
+    // A middle part reopens with the original info string.
+    const middle = parts.slice(1, -1);
+    expect(middle.some((p) => p.startsWith('```diff\n'))).toBe(true);
+  });
+
+  it('handles oversized single lines (no newline under the budget)', () => {
+    const text = 'x'.repeat(5000);
+    const parts = splitForDiscord(text, 1000);
+    expect(parts.join('')).toBe(text);
+    for (const p of parts) expect(p.length).toBeLessThanOrEqual(1000);
+  });
+});

package/src/render.ts

@@ -0,0 +1,228 @@
+import type { MoxxyEvent } from '@moxxy/sdk';
+
+/**
+ * Discord messages cap at 2000 chars; leave margin for the fence-reopen text a
+ * split may prepend to a tail part.
+ */
+export const DISCORD_MESSAGE_LIMIT = 1_900;
+
+/**
+ * Accumulates one turn's events into a single Discord-markdown string (the
+ * frame the pump sends/edits). Discord renders standard markdown natively
+ * (bold, `code`, ``` fences, > quotes), so — unlike Telegram — no HTML
+ * conversion pass is needed; the assistant body passes through as-is with a
+ * compact tool-activity quote block above it.
+ *
+ * Structure of a frame:
+ *
+ *   > -  `tool_name` (args) — done 0.4s
+ *   > -  `another_tool` (args) — running…
+ *
+ *   <assistant body>
+ *
+ *   <error if any>
+ */
+type ToolStatus =
+  | { kind: 'pending'; startedAt: number }
+  | { kind: 'ok'; ms: number }
+  | { kind: 'err'; ms: number; message: string }
+  | { kind: 'denied'; reason: string };
+
+interface ToolEntry {
+  readonly name: string;
+  readonly inputPreview: string;
+  status: ToolStatus;
+}
+
+export class DiscordTurnRenderer {
+  private chunks: string[] = [];
+  private finalAssistant: string | null = null;
+  private readonly tools = new Map<string, ToolEntry>();
+  private notices: string[] = [];
+  private errorLine: string | null = null;
+  private lastFrame = '';
+
+  /** Returns true when the event changed the frame (schedule an edit). */
+  accept(event: MoxxyEvent): boolean {
+    switch (event.type) {
+      case 'assistant_chunk':
+        this.chunks.push(event.delta);
+        break;
+      case 'assistant_message':
+        this.finalAssistant = event.content;
+        this.chunks = [];
+        break;
+      case 'tool_call_requested':
+        this.tools.set(String(event.callId), {
+          name: event.name,
+          inputPreview: previewArgs(event.input),
+          status: { kind: 'pending', startedAt: Date.now() },
+        });
+        break;
+      case 'tool_call_denied': {
+        const entry = this.tools.get(String(event.callId));
+        if (entry) entry.status = { kind: 'denied', reason: event.reason };
+        break;
+      }
+      case 'tool_result': {
+        const entry = this.tools.get(String(event.callId));
+        if (!entry) break;
+        const started = entry.status.kind === 'pending' ? entry.status.startedAt : Date.now();
+        const ms = Date.now() - started;
+        entry.status = event.ok
+          ? { kind: 'ok', ms }
+          : {
+              kind: 'err',
+              ms,
+              message: `${event.error?.kind ?? 'error'}: ${event.error?.message ?? ''}`,
+            };
+        break;
+      }
+      case 'skill_invoked':
+        this.notices.push(`💡 skill: **${event.name}**`);
+        break;
+      case 'error':
+        this.errorLine = `❗ **${event.kind}**: ${event.message}`;
+        break;
+      default:
+        break;
+    }
+    const frame = this.snapshot();
+    const changed = frame !== this.lastFrame;
+    this.lastFrame = frame;
+    return changed;
+  }
+
+  snapshot(): string {
+    const parts: string[] = [];
+    const activity = this.renderActivity();
+    if (activity) parts.push(activity);
+    const body = this.finalText();
+    if (body) parts.push(body);
+    if (this.errorLine) parts.push(this.errorLine);
+    return parts.join('\n\n').trim();
+  }
+
+  /** The assistant body alone (no activity/error block) — the text a voice
+   *  reply speaks. Empty for a tool-only turn. */
+  finalText(): string {
+    return (this.finalAssistant ?? this.chunks.join('')).trim();
+  }
+
+  reset(): void {
+    this.chunks = [];
+    this.finalAssistant = null;
+    this.tools.clear();
+    this.notices = [];
+    this.errorLine = null;
+    this.lastFrame = '';
+  }
+
+  private renderActivity(): string | null {
+    const lines: string[] = [];
+    const tools = [...this.tools.values()];
+    const visible = tools.slice(-10);
+    const hidden = tools.length - visible.length;
+    if (hidden > 0) lines.push(`… ${hidden} earlier tool call${hidden === 1 ? '' : 's'} hidden`);
+    for (const t of visible) {
+      const args = t.inputPreview ? ` (${t.inputPreview})` : '';
+      lines.push(`- \`${t.name}\`${args} — ${statusBadge(t.status)}`);
+    }
+    for (const n of this.notices.slice(-5)) lines.push(n);
+    if (lines.length === 0) return null;
+    return lines.map((l) => `> ${l}`).join('\n');
+  }
+}
+
+function statusBadge(status: ToolStatus): string {
+  switch (status.kind) {
+    case 'pending':
+      return 'running…';
+    case 'ok':
+      return `done ${fmtElapsed(status.ms)}`;
+    case 'err':
+      return `error: ${status.message.slice(0, 80)}`;
+    case 'denied':
+      return `denied: ${status.reason.slice(0, 80)}`;
+  }
+}
+
+function fmtElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m ${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+function truncJson(value: unknown, max = 60): string {
+  const s = typeof value === 'string' ? value : (JSON.stringify(value) ?? '');
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + '…';
+}
+
+function previewArgs(input: unknown): string {
+  if (input == null || (typeof input === 'object' && Object.keys(input as object).length === 0)) {
+    return '';
+  }
+  if (typeof input === 'string') return truncJson(input);
+  try {
+    const obj = input as Record<string, unknown>;
+    const keys = Object.keys(obj).slice(0, 3);
+    const pairs = keys.map((k) => `${k}=${truncJson(obj[k], 20)}`);
+    const tail = Object.keys(obj).length > keys.length ? ', …' : '';
+    return pairs.join(', ') + tail;
+  } catch {
+    return truncJson(input);
+  }
+}
+
+/**
+ * Split Discord markdown into <=`limit`-char parts that each render sanely on
+ * their own (mirrors `splitForTelegram`'s shape, adapted from HTML tags to the
+ * one markdown construct that breaks when cut: a ``` code fence). Cuts prefer
+ * a newline at/under the budget; if the cut lands inside an open fence, the
+ * fence is closed at the head part's end and reopened (with its original
+ * info-string, e.g. ```diff) at the tail's start, so every part is
+ * independently valid. Parts are separate Discord messages, so the newline a
+ * cut lands on is consumed (not carried into the tail).
+ */
+export function splitForDiscord(text: string, limit: number = DISCORD_MESSAGE_LIMIT): string[] {
+  if (text.length <= limit) return text ? [text] : [];
+  const out: string[] = [];
+  /** The fence opener carried over from the previous part (reopened at its head). */
+  let carryFence: string | null = null;
+  let remaining = text;
+  while (remaining.length > limit) {
+    const prefix = carryFence ? carryFence + '\n' : '';
+    // The reopened fence + a possible closing fence eat into the budget.
+    const budget = Math.max(1, limit - prefix.length - '\n```'.length);
+    let idx = Math.min(budget, remaining.length);
+    const nl = remaining.lastIndexOf('\n', idx);
+    if (nl > 0) idx = nl;
+    const openFence = openFenceAt(remaining, idx, carryFence);
+    const head = prefix + remaining.slice(0, idx) + (openFence ? '\n```' : '');
+    out.push(head);
+    carryFence = openFence;
+    remaining = remaining.slice(idx);
+    // Drop the leading newline the cut left behind (it was consumed by the cut
+    // point, and the reopened fence supplies its own).
+    if (remaining.startsWith('\n')) remaining = remaining.slice(1);
+  }
+  if (remaining) out.push((carryFence ? carryFence + '\n' : '') + remaining);
+  return out;
+}
+
+/**
+ * Is a ``` fence open at `idx`? Returns the fence's opening line (e.g.
+ * "```diff") when open, else null. `seed` is the fence carried into this part
+ * from the previous split (the text below it starts inside that fence).
+ */
+function openFenceAt(text: string, idx: number, seed: string | null): string | null {
+  let open: string | null = seed;
+  const scan = text.slice(0, idx);
+  const fenceRe = /(?:^|\n)(```[^\n]*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = fenceRe.exec(scan)) !== null) {
+    open = open === null ? m[1]! : null;
+  }
+  return open;
+}

package/src/schema.ts

@@ -0,0 +1,94 @@
+/**
+ * Inbound-payload validation (AGENTS.md invariant: zod-validate every inbound
+ * frame/body before it touches the session). discord.js hands us rich class
+ * instances; we extract ONLY the primitive fields the channel consumes into a
+ * plain record and validate + size-cap that, so a malformed/hostile payload is
+ * dropped at the boundary instead of flowing into handlers.
+ */
+import { z } from '@moxxy/sdk';
+import { snowflakeSchema } from './keys.js';
+
+/**
+ * Hard cap on inbound message text we accept. Discord caps user messages at
+ * 4000 chars (Nitro); anything past this is not a legitimate prompt, so we
+ * drop it rather than truncate (a silently truncated prompt is worse than a
+ * clear rejection).
+ */
+export const MAX_CONTENT_CHARS = 8_000;
+
+/** Hard cap on an inbound audio attachment we will buffer for transcription. */
+export const MAX_AUDIO_BYTES = 20 * 1024 * 1024;
+
+const attachmentSchema = z.object({
+  id: snowflakeSchema,
+  url: z.string().url().max(2_048),
+  contentType: z.string().max(256).nullable(),
+  size: z.number().int().nonnegative(),
+  name: z.string().max(1_024).nullable(),
+});
+
+export const inboundMessageSchema = z.object({
+  id: snowflakeSchema,
+  /** Raw message text (may be empty for attachment-only messages). */
+  content: z.string().max(MAX_CONTENT_CHARS),
+  channelId: snowflakeSchema,
+  /** Null for DMs. */
+  guildId: snowflakeSchema.nullable(),
+  authorId: snowflakeSchema,
+  authorIsBot: z.boolean(),
+  attachments: z.array(attachmentSchema).max(16),
+});
+
+export type InboundMessage = z.infer<typeof inboundMessageSchema>;
+export type InboundAttachment = z.infer<typeof attachmentSchema>;
+
+/** The structural slice of a discord.js Message we extract fields from. */
+export interface RawMessageLike {
+  readonly id?: unknown;
+  readonly content?: unknown;
+  readonly channelId?: unknown;
+  readonly guildId?: unknown;
+  readonly author?: { readonly id?: unknown; readonly bot?: unknown } | null;
+  readonly attachments?: {
+    values?(): IterableIterator<{
+      readonly id?: unknown;
+      readonly url?: unknown;
+      readonly contentType?: unknown;
+      readonly size?: unknown;
+      readonly name?: unknown;
+    }>;
+  } | null;
+}
+
+/**
+ * Extract + validate the fields we consume from a discord.js Message. Returns
+ * null when the payload doesn't validate (wrong shapes, oversized content,
+ * missing ids) — the caller drops it with a warning.
+ */
+export function extractInboundMessage(msg: RawMessageLike): InboundMessage | null {
+  const attachments: unknown[] = [];
+  try {
+    for (const a of msg.attachments?.values?.() ?? []) {
+      attachments.push({
+        id: a?.id,
+        url: a?.url,
+        contentType: a?.contentType ?? null,
+        size: a?.size,
+        name: a?.name ?? null,
+      });
+    }
+  } catch {
+    return null;
+  }
+  const candidate = {
+    id: msg.id,
+    content: msg.content,
+    channelId: msg.channelId,
+    guildId: msg.guildId ?? null,
+    authorId: msg.author?.id,
+    authorIsBot: msg.author?.bot === true,
+    attachments,
+  };
+  const parsed = inboundMessageSchema.safeParse(candidate);
+  return parsed.success ? parsed.data : null;
+}