@moxxy/plugin-channel-discord 0.27.0

package/src/channel/message-handler.test.ts

@@ -0,0 +1,295 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { VaultStore, createStaticKeySource, deriveKey, generateSalt } from '@moxxy/plugin-vault';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { DISCORD_AUTHORIZED_USER_KEY } from '../keys.js';
+import type { InboundMessage } from '../schema.js';
+import { extractInboundMessage, MAX_CONTENT_CHARS } from '../schema.js';
+import { DiscordApprovalResolver } from '../approval.js';
+import { DiscordPermissionResolver } from '../permission.js';
+import { AllowListStore } from './allow-list-store.js';
+import { PairingHandler } from './pairing-handler.js';
+import {
+  handleInboundMessage,
+  type InboundContext,
+  type MessageHandlerCallbacks,
+  type MessageHandlerState,
+} from './message-handler.js';
+
+const PAIRED = '111111111111';
+const STRANGER = '222222222222';
+const GUILD = '333333333333';
+const CHAN = '444444444444';
+const DM_CHAN = '555555555555';
+
+let tmp: string;
+let vault: VaultStore;
+let pairing: PairingHandler;
+let allowList: AllowListStore;
+let approvalResolver: DiscordApprovalResolver;
+let permissionResolver: DiscordPermissionResolver;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-dc-msg-'));
+  vault = new VaultStore({
+    filePath: path.join(tmp, 'vault.json'),
+    keySource: createStaticKeySource(deriveKey('test', generateSalt())),
+  });
+  pairing = new PairingHandler({ vault });
+  allowList = new AllowListStore(vault);
+  approvalResolver = new DiscordApprovalResolver();
+  permissionResolver = new DiscordPermissionResolver();
+});
+
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+async function pairAs(userId: string): Promise<void> {
+  await vault.set(DISCORD_AUTHORIZED_USER_KEY, userId);
+  await pairing.loadAuthorized();
+}
+
+function msg(overrides: Partial<InboundMessage> = {}): InboundMessage {
+  return {
+    id: '999999999999',
+    content: 'hello',
+    channelId: DM_CHAN,
+    guildId: null,
+    authorId: PAIRED,
+    authorIsBot: false,
+    attachments: [],
+    ...overrides,
+  };
+}
+
+interface Ctxed {
+  ctx: InboundContext;
+  replies: string[];
+}
+
+function makeCtx(m: InboundMessage): Ctxed {
+  const replies: string[] = [];
+  return {
+    replies,
+    ctx: {
+      msg: m,
+      channel: { send: async () => ({ edit: async () => undefined }) },
+      reply: async (text: string) => {
+        replies.push(text);
+      },
+    },
+  };
+}
+
+function makeState(overrides: Partial<MessageHandlerState> = {}): MessageHandlerState {
+  return {
+    session: null,
+    busy: false,
+    turnController: null,
+    awaitingApprovalText: null,
+    handle: null,
+    botUserId: null,
+    ...overrides,
+  };
+}
+
+function makeCallbacks(overrides: Partial<MessageHandlerCallbacks> = {}): MessageHandlerCallbacks & {
+  runUserTurn: ReturnType<typeof vi.fn>;
+  runVoiceMessage: ReturnType<typeof vi.fn>;
+} {
+  const runUserTurn = vi.fn(async () => undefined);
+  const runVoiceMessage = vi.fn(async () => false);
+  return {
+    setAwaitingApprovalText: () => undefined,
+    toggleYolo: () => false,
+    setYolo: () => undefined,
+    runUserTurn,
+    runVoiceMessage,
+    ...overrides,
+  } as never;
+}
+
+function deps() {
+  return { pairing, allowList, approvalResolver, permissionResolver };
+}
+
+describe('handleInboundMessage — gating (every session-reaching path)', () => {
+  it('drops an unpaired DM with pairing guidance (no window armed)', async () => {
+    const { ctx, replies } = makeCtx(msg({ authorId: STRANGER }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies.join(' ')).toMatch(/pairing window/i);
+  });
+
+  it('issues a pairing code to an unpaired DM when the window is armed', async () => {
+    pairing.arm();
+    const { ctx, replies } = makeCtx(msg({ authorId: STRANGER }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies[0]).toMatch(/pairing code/i);
+  });
+
+  it('silently drops unpaired GUILD messages (no server spam)', async () => {
+    pairing.arm();
+    const { ctx, replies } = makeCtx(msg({ authorId: STRANGER, guildId: GUILD, channelId: CHAN }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies).toEqual([]);
+  });
+
+  it('drops a foreign user in a guild even when the channel is allow-listed', async () => {
+    await pairAs(PAIRED);
+    await allowList.add(CHAN);
+    const { ctx, replies } = makeCtx(msg({ authorId: STRANGER, guildId: GUILD, channelId: CHAN }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies).toEqual([]);
+  });
+
+  it('blocks the paired user in a non-allow-listed guild channel with a hint', async () => {
+    await pairAs(PAIRED);
+    const { ctx, replies } = makeCtx(msg({ guildId: GUILD, channelId: CHAN }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies[0]).toMatch(/\/allow/);
+  });
+
+  it('/allow from the paired user opts a guild channel in; messages then flow', async () => {
+    await pairAs(PAIRED);
+    const first = makeCtx(msg({ guildId: GUILD, channelId: CHAN, content: '/allow' }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(first.ctx, makeState(), deps(), cb);
+    expect(first.replies[0]).toMatch(/✓/);
+    expect(allowList.has(CHAN)).toBe(true);
+
+    const second = makeCtx(msg({ guildId: GUILD, channelId: CHAN, content: 'do the thing' }));
+    await handleInboundMessage(second.ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).toHaveBeenCalledWith(second.ctx, 'do the thing');
+  });
+
+  it('/deny removes a guild channel from the allow-list', async () => {
+    await pairAs(PAIRED);
+    await allowList.add(CHAN);
+    const { ctx, replies } = makeCtx(msg({ guildId: GUILD, channelId: CHAN, content: '/deny' }));
+    await handleInboundMessage(ctx, makeState(), deps(), makeCallbacks());
+    expect(replies[0]).toMatch(/removed/);
+    expect(allowList.has(CHAN)).toBe(false);
+  });
+
+  it('never reacts to bot-authored messages (paired or not)', async () => {
+    await pairAs(PAIRED);
+    const { ctx, replies } = makeCtx(msg({ authorIsBot: true }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies).toEqual([]);
+  });
+
+  it('drops oversized content at the validation boundary (extractInboundMessage)', () => {
+    const raw = {
+      id: '999999999999',
+      content: 'x'.repeat(MAX_CONTENT_CHARS + 1),
+      channelId: DM_CHAN,
+      guildId: null,
+      author: { id: PAIRED, bot: false },
+      attachments: null,
+    };
+    expect(extractInboundMessage(raw)).toBeNull();
+    // Under the cap it validates.
+    expect(extractInboundMessage({ ...raw, content: 'ok' })).not.toBeNull();
+  });
+});
+
+describe('handleInboundMessage — dispatch', () => {
+  it('runs a user turn for a paired DM', async () => {
+    await pairAs(PAIRED);
+    const { ctx } = makeCtx(msg({ content: 'what time is it' }));
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runUserTurn).toHaveBeenCalledWith(ctx, 'what time is it');
+  });
+
+  it('refuses new prompts while busy', async () => {
+    await pairAs(PAIRED);
+    const { ctx, replies } = makeCtx(msg());
+    const cb = makeCallbacks();
+    await handleInboundMessage(ctx, makeState({ busy: true }), deps(), cb);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+    expect(replies[0]).toMatch(/still working/);
+  });
+
+  it('/cancel aborts the in-flight turn even while busy', async () => {
+    await pairAs(PAIRED);
+    const controller = new AbortController();
+    const { ctx, replies } = makeCtx(msg({ content: '/cancel' }));
+    await handleInboundMessage(
+      ctx,
+      makeState({ busy: true, turnController: controller }),
+      deps(),
+      makeCallbacks(),
+    );
+    expect(controller.signal.aborted).toBe(true);
+    expect(replies[0]).toMatch(/cancelling/);
+  });
+
+  it('captures awaiting-approval text before the busy guard', async () => {
+    await pairAs(PAIRED);
+    // Wire a decider so confirm() parks as pending (id 'appr_1').
+    approvalResolver.setDecider(async () => undefined);
+    const pendingDecision = approvalResolver.confirm({
+      title: 't',
+      body: 'b',
+      options: [{ id: 'redraft', label: 'Redraft', requestsText: true }],
+      defaultOptionId: 'redraft',
+    } as never);
+
+    const setAwaiting = vi.fn();
+    const { ctx, replies } = makeCtx(msg({ content: 'my feedback here' }));
+    await handleInboundMessage(
+      ctx,
+      makeState({ busy: true, awaitingApprovalText: { approvalId: 'appr_1', optionId: 'redraft' } }),
+      deps(),
+      makeCallbacks({ setAwaitingApprovalText: setAwaiting }),
+    );
+    expect(setAwaiting).toHaveBeenCalledWith(null);
+    expect(replies[0]).toMatch(/✓ submitted/);
+    await expect(pendingDecision).resolves.toEqual({ optionId: 'redraft', text: 'my feedback here' });
+  });
+
+  it('routes registry slash commands through session.commands', async () => {
+    await pairAs(PAIRED);
+    const handler = vi.fn(async () => ({ kind: 'text', text: 'info output' }));
+    const session = {
+      id: 'sess',
+      commands: { get: (name: string) => (name === 'info' ? { handler } : undefined) },
+    } as unknown as Session;
+    const { ctx, replies } = makeCtx(msg({ content: '/info' }));
+    await handleInboundMessage(ctx, makeState({ session }), deps(), makeCallbacks());
+    expect(handler).toHaveBeenCalled();
+    expect(replies[0]).toBe('info output');
+  });
+
+  it('dispatches audio attachments to the voice path instead of a text turn', async () => {
+    await pairAs(PAIRED);
+    const { ctx } = makeCtx(
+      msg({
+        content: '',
+        attachments: [
+          { id: '888888888888', url: 'https://cdn.example/x.ogg', contentType: 'audio/ogg', size: 100, name: 'v.ogg' },
+        ],
+      }),
+    );
+    const cb = makeCallbacks({ runVoiceMessage: vi.fn(async () => true) });
+    await handleInboundMessage(ctx, makeState(), deps(), cb);
+    expect(cb.runVoiceMessage).toHaveBeenCalledWith(ctx);
+    expect(cb.runUserTurn).not.toHaveBeenCalled();
+  });
+});

package/src/channel/message-handler.ts

@@ -0,0 +1,195 @@
+import type { ChannelHandle, ClientSession as Session } from '@moxxy/sdk';
+import { gateInbound } from '../allow-list.js';
+import type { InboundMessage } from '../schema.js';
+import type { DiscordApprovalResolver } from '../approval.js';
+import type { DiscordPermissionResolver } from '../permission.js';
+import type { AllowListStore } from './allow-list-store.js';
+import type { ChannelLogger, SendableChannelLike } from './discord-like.js';
+import type { PairingHandler } from './pairing-handler.js';
+import { runSlash } from './slash-handler.js';
+
+export interface AwaitingApprovalText {
+  approvalId: string;
+  optionId: string;
+}
+
+/** A validated inbound message plus the transport bits needed to answer it. */
+export interface InboundContext {
+  readonly msg: InboundMessage;
+  readonly channel: SendableChannelLike;
+  reply(text: string): Promise<unknown>;
+}
+
+export interface MessageHandlerState {
+  readonly session: Session | null;
+  readonly busy: boolean;
+  readonly turnController: AbortController | null;
+  readonly awaitingApprovalText: AwaitingApprovalText | null;
+  readonly handle: ChannelHandle | null;
+  /** The bot's own user id (ignore self-authored messages defensively). */
+  readonly botUserId: string | null;
+}
+
+export interface MessageHandlerDeps {
+  readonly pairing: PairingHandler;
+  readonly allowList: AllowListStore;
+  readonly approvalResolver: DiscordApprovalResolver;
+  readonly permissionResolver: DiscordPermissionResolver;
+  readonly logger?: ChannelLogger;
+}
+
+export interface MessageHandlerCallbacks {
+  readonly setAwaitingApprovalText: (state: AwaitingApprovalText | null) => void;
+  readonly toggleYolo: () => boolean;
+  readonly setYolo: (value: boolean) => void;
+  /** Handle `/voice [on|off|status]` — persist + apply, return the reply text. */
+  readonly voice: (arg: string) => Promise<string>;
+  readonly runUserTurn: (ctx: InboundContext, text: string) => Promise<void>;
+  /** Handle audio attachments (voice messages). Returns true when it consumed
+   *  the message (so the text path is skipped). */
+  readonly runVoiceMessage: (ctx: InboundContext) => Promise<boolean>;
+}
+
+/**
+ * Top-level dispatch for inbound Discord messages. Every session-reaching path
+ * is behind the pairing + allow-list gate (AGENTS.md A46: gate EVERY path):
+ * validation happened upstream (the caller only builds an {@link
+ * InboundContext} from a zod-validated extraction), authorization happens
+ * here, and only then do approval-capture / cancel / slash / turn paths run.
+ */
+export async function handleInboundMessage(
+  ctx: InboundContext,
+  state: MessageHandlerState,
+  deps: MessageHandlerDeps,
+  cb: MessageHandlerCallbacks,
+): Promise<void> {
+  const { msg } = ctx;
+  // Never react to bots (including ourselves) — bot-to-bot loops.
+  if (msg.authorIsBot || (state.botUserId != null && msg.authorId === state.botUserId)) return;
+
+  const text = msg.content.trim();
+  const verdict = gateInbound(msg, deps.pairing.authorizedUserId(), deps.allowList.snapshot());
+
+  if (!verdict.ok) {
+    if (verdict.reason === 'not-paired' || verdict.reason === 'foreign-user') {
+      // DMs get pairing guidance (a fresh code when a window is armed, a
+      // rejection for a foreign account); guild messages are dropped silently
+      // so an unpaired bot can't be made to spam a server.
+      if (msg.guildId == null) {
+        const reply = deps.pairing.handleUnpairedDm(msg.authorId);
+        if (reply) await ctx.reply(reply);
+      }
+      return;
+    }
+    // Paired user in a guild channel that isn't allow-listed: /allow opts the
+    // channel in (this is the ONE command that must work pre-allow-list —
+    // it's how the list gets populated); anything else gets a hint.
+    if (text === '/allow') {
+      await deps.allowList.add(msg.channelId);
+      await ctx.reply('✓ this channel can now drive moxxy. Use /deny here to revoke.');
+      return;
+    }
+    await ctx.reply('This channel is not allow-listed. Send /allow here to enable it.');
+    return;
+  }
+
+  if (!text && msg.attachments.length === 0) return;
+
+  // Capture awaiting-text BEFORE the busy guard so the user can answer an
+  // approval text prompt even while the strategy is technically mid-turn
+  // (it's pending on us).
+  if (state.awaitingApprovalText && text) {
+    const { approvalId, optionId } = state.awaitingApprovalText;
+    cb.setAwaitingApprovalText(null);
+    const handled = deps.approvalResolver.resolvePendingWithText(approvalId, optionId, text);
+    await ctx.reply(handled ? `✓ submitted (${optionId})` : 'that approval is no longer pending');
+    return;
+  }
+
+  // /cancel works even while busy; everything else routes below.
+  if (text === '/cancel') {
+    if (state.turnController && !state.turnController.signal.aborted) {
+      state.turnController.abort('user cancel');
+      await ctx.reply('cancelling current turn…');
+    } else {
+      await ctx.reply('nothing to cancel.');
+    }
+    return;
+  }
+
+  if (text === '/deny' && msg.guildId != null) {
+    const removed = await deps.allowList.remove(msg.channelId);
+    await ctx.reply(removed ? '✓ channel removed from the allow-list.' : 'this channel was not allow-listed.');
+    return;
+  }
+  if (text === '/allow' && msg.guildId != null) {
+    await ctx.reply('this channel is already allow-listed.');
+    return;
+  }
+
+  if (text.startsWith('/')) {
+    if (!state.session) return;
+    const [head, ...rest] = text.split(/\s+/);
+    const reply = await runSlash(head!.slice(1), rest.join(' '), state.session, {
+      toggleYolo: cb.toggleYolo,
+      voice: cb.voice,
+      performSessionAction: (action, notice) =>
+        performSessionAction(action, notice, state, deps, cb),
+    });
+    if (reply) await ctx.reply(reply.length > 1_900 ? reply.slice(0, 1_899) + '…' : reply);
+    return;
+  }
+
+  // Voice messages / audio uploads take the transcribe-then-turn path.
+  if (await cb.runVoiceMessage(ctx)) return;
+  if (!text) return;
+
+  if (state.busy) {
+    await ctx.reply('I am still working on the previous prompt. Send /cancel to abort it.');
+    return;
+  }
+
+  await cb.runUserTurn(ctx, text);
+}
+
+/**
+ * Channel-side handler for `session-action` outputs from registered commands.
+ * Mirrors the Telegram channel's semantics; returns the reply text. Shared by
+ * the plain-text slash path (above) and the interaction (slash-command) path
+ * in the channel.
+ */
+export async function performSessionAction(
+  action: 'new' | 'clear' | 'exit',
+  notice: string | undefined,
+  state: Pick<MessageHandlerState, 'session' | 'turnController' | 'handle'>,
+  deps: Pick<MessageHandlerDeps, 'approvalResolver' | 'permissionResolver'>,
+  cb: Pick<MessageHandlerCallbacks, 'setAwaitingApprovalText' | 'setYolo'>,
+): Promise<string> {
+  if (!state.session) return 'session is not ready yet.';
+  if (action === 'exit') {
+    // Fire the stop AFTER we return so the reply can still be delivered.
+    setTimeout(() => void state.handle?.stop('user /exit'), 250);
+    return notice ?? 'closing Discord channel';
+  }
+  if (action === 'clear') {
+    return `✓ ${notice ?? 'cleared'}`;
+  }
+  // action === 'new'
+  if (state.turnController && !state.turnController.signal.aborted) {
+    state.turnController.abort('user reset');
+  }
+  cb.setYolo(false);
+  cb.setAwaitingApprovalText(null);
+  deps.approvalResolver.abortAll('session reset');
+  deps.permissionResolver.abortAll('session reset');
+  // Wipe the history at its source (RemoteSession.reset() asks the runner; a
+  // mirror-only log.clear() would desync) and only claim success when the
+  // reset actually happened (AGENTS.md A10).
+  try {
+    if (typeof state.session.reset === 'function') await state.session.reset();
+    else state.session.log.clear();
+  } catch (err) {
+    return `⚠ /new failed: ${err instanceof Error ? err.message : String(err)} — history NOT cleared`;
+  }
+  return `✓ ${notice ?? 'new session — conversation history cleared'}`;
+}

package/src/channel/pairing-handler.ts

@@ -0,0 +1,147 @@
+import type { VaultStore } from '@moxxy/plugin-vault';
+import {
+  armPairing,
+  clearDiscordPairing,
+  confirmPendingCode,
+  createDiscordPairingState,
+  isUserAuthorized,
+  mintCodeForPeer,
+  pairingPhase,
+  type DiscordPairingDecision,
+  type DiscordPairingPhase,
+  type DiscordPairingState,
+} from '../pairing.js';
+import { DISCORD_AUTHORIZED_USER_KEY, parseAuthorizedUser } from '../keys.js';
+
+/** Result returned by {@link PairingHandler.confirmCode}. */
+export type PairingConfirmResult =
+  | { ok: true; userId: string }
+  | { ok: false; reason: 'mismatch' | 'expired' | 'not-pending'; message: string };
+
+export interface PairingHandlerOptions {
+  readonly vault: VaultStore;
+  readonly logger?: {
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+/**
+ * Owns the pairing state machine + vault persistence for the DM code flow
+ * (see `../pairing.ts` for the flow + security property). The channel feeds it
+ * DMs from unauthorized users ({@link handleUnpairedDm}) and the terminal
+ * wizard feeds it pasted codes ({@link confirmCode}).
+ */
+export class PairingHandler {
+  private state: DiscordPairingState = createDiscordPairingState();
+  private readonly opts: PairingHandlerOptions;
+  private readonly pairedListeners = new Set<(userId: string) => void>();
+
+  constructor(opts: PairingHandlerOptions) {
+    this.opts = opts;
+  }
+
+  async loadAuthorized(): Promise<void> {
+    const raw = await this.opts.vault.get(DISCORD_AUTHORIZED_USER_KEY);
+    const authorizedUserId = parseAuthorizedUser(raw);
+    if (authorizedUserId == null && raw) {
+      this.opts.logger?.warn(
+        'discord pairing: stored user id is not a snowflake — treating as unpaired',
+        { raw },
+      );
+    }
+    this.state = createDiscordPairingState({ authorizedUserId });
+  }
+
+  phase(): DiscordPairingPhase {
+    return pairingPhase(this.state);
+  }
+
+  isAuthorized(userId: string): boolean {
+    return isUserAuthorized(this.state, userId);
+  }
+
+  authorizedUserId(): string | null {
+    return this.state.kit.phase === 'paired' ? this.state.kit.authorizedPeer : null;
+  }
+
+  /** Arm the pairing window: unauthorized DMs will now be issued codes. */
+  arm(): void {
+    this.state = armPairing(this.state);
+  }
+
+  unpair(): void {
+    this.state = clearDiscordPairing(this.state);
+  }
+
+  /**
+   * Subscribe to "a user just became authorized" — fires once each time pairing
+   * completes. The `pair` terminal flow uses it to print success; the channel
+   * uses it to flip its connect-state. Returns an unsubscribe function.
+   */
+  onPaired(listener: (userId: string) => void): () => void {
+    this.pairedListeners.add(listener);
+    return () => this.pairedListeners.delete(listener);
+  }
+
+  /**
+   * An unauthorized user DMed the bot. Returns the reply text to DM back:
+   * a freshly minted one-time code (window armed), a nudge to open a window,
+   * or a foreign-account rejection. Null when no reply is warranted.
+   */
+  handleUnpairedDm(userId: string): string | null {
+    const decision = mintCodeForPeer(this.state, userId);
+    this.state = decision.state;
+    const action = decision.action;
+    if (action.kind === 'code-minted') {
+      this.opts.logger?.info?.('discord pairing: code minted', { userId });
+      return (
+        `Your one-time pairing code is: **${action.code}**\n` +
+        'Paste it into the moxxy terminal (`moxxy discord pair`) to finish pairing.'
+      );
+    }
+    if (action.kind === 'still-paired') return 'Already paired — send me a prompt.';
+    if (action.kind === 'reject') return action.message;
+    return null;
+  }
+
+  /**
+   * The operator pasted a code into the terminal. On match the pending DM user
+   * is authorized + persisted. The vault write happens BEFORE listeners fire so
+   * a `pair`-flow exit right after success never loses the pairing.
+   */
+  async confirmCode(rawCode: string): Promise<PairingConfirmResult> {
+    const decision = confirmPendingCode(this.state, rawCode);
+    return this.applyConfirmDecision(decision);
+  }
+
+  private async applyConfirmDecision(
+    decision: DiscordPairingDecision,
+  ): Promise<PairingConfirmResult> {
+    this.state = decision.state;
+    const action = decision.action;
+    if (action.kind === 'paired') {
+      await this.opts.vault.set(DISCORD_AUTHORIZED_USER_KEY, action.userId);
+      this.emitPaired(action.userId);
+      return { ok: true, userId: action.userId };
+    }
+    if (action.kind === 'still-paired') return { ok: true, userId: action.userId };
+    if (action.kind === 'mismatch') return { ok: false, reason: 'mismatch', message: action.message };
+    if (action.kind === 'expired') return { ok: false, reason: 'expired', message: action.message };
+    if (action.kind === 'not-pending' || action.kind === 'reject') {
+      return { ok: false, reason: 'not-pending', message: action.message };
+    }
+    // 'code-minted' can't come out of a confirm; treat as a mismatch.
+    return { ok: false, reason: 'mismatch', message: 'unexpected pairing state' };
+  }
+
+  private emitPaired(userId: string): void {
+    for (const listener of this.pairedListeners) {
+      try {
+        listener(userId);
+      } catch (err) {
+        this.opts.logger?.warn('discord pairing paired-listener threw', { err: String(err) });
+      }
+    }
+  }
+}

package/src/channel/permission-prompt.ts

@@ -0,0 +1,54 @@
+import type { PendingToolCall, PermissionContext } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { DiscordPermissionResolver } from '../permission.js';
+import { BUTTON_STYLE, button, packRows } from './components.js';
+import type { ChannelLogger, SendableChannelLike } from './discord-like.js';
+
+export interface PermissionPromptDeps {
+  readonly channel: SendableChannelLike | null;
+  readonly session: Session | null;
+  readonly resolver: DiscordPermissionResolver;
+  readonly yolo: boolean;
+  readonly logger?: ChannelLogger;
+}
+
+function truncate(s: string, max: number): string {
+  return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+
+/**
+ * Render a button-row permission prompt for a pending tool call (the Discord
+ * mapping of Telegram's inline keyboard). The decider promise resolves when
+ * the paired user clicks a button (routed back via the interaction handler)
+ * or when the resolver aborts on stop.
+ */
+export async function askForPermission(
+  call: PendingToolCall,
+  ctx: PermissionContext,
+  deps: PermissionPromptDeps,
+): Promise<void> {
+  void ctx;
+  if (!deps.channel || !deps.session) return;
+  // YOLO short-circuit: resolve immediately without rendering a prompt.
+  if (deps.yolo) {
+    deps.resolver.resolvePending(call.callId, { mode: 'allow', reason: 'yolo mode' });
+    return;
+  }
+  const rows = packRows([
+    button(`perm:${call.callId}:allow`, 'Allow once', BUTTON_STYLE.success),
+    button(`perm:${call.callId}:allow_session`, 'Allow session', BUTTON_STYLE.primary),
+    button(`perm:${call.callId}:deny`, 'Deny', BUTTON_STYLE.danger),
+  ]);
+  const description = deps.session.tools.get(call.name)?.description ?? '';
+  const summary =
+    `🔐 **Tool permission requested**\n` +
+    `Tool: \`${call.name}\`\n` +
+    (description ? `Desc: ${truncate(description, 200)}\n` : '') +
+    `Input: \`${truncate(JSON.stringify(call.input), 300)}\``;
+  try {
+    await deps.channel.send({ content: summary, components: rows });
+  } catch (err) {
+    deps.logger?.warn('discord permission send failed', { err: String(err) });
+    deps.resolver.resolvePending(call.callId, { mode: 'deny', reason: 'unable to render prompt' });
+  }
+}