@spinabot/brigade 1.6.1 → 1.7.0

package/dist/agents/channels/discord/modals.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Discord modal (form) building + submission decoding (Fix 3b).
+ *
+ * A modal is opened with `interaction.showModal(modal)` in response to a button
+ * press; on submit Discord delivers a `ModalSubmitInteraction` whose `fields`
+ * accessor yields each text input's value keyed by the field's custom_id. This
+ * module:
+ *   - {@link buildDiscordModal} turns a registry {@link DiscordModalEntry} into a
+ *     discord.js `ModalBuilder` (text inputs only — Discord's STABLE modals
+ *     support only text inputs, which is correct for v1). It takes the discord.js
+ *     builder constructors as an argument so a non-Discord boot never imports
+ *     them and tests can inject lightweight fakes.
+ *   - {@link extractModalFieldValues} reads the submitted values off a
+ *     `ModalSubmitInteraction` defensively (pure — no discord.js).
+ *   - {@link formatModalSubmissionText} renders a readable turn body from the
+ *     entry's field labels + the submitted values (pure).
+ *
+ * The submission is routed as a NORMAL inbound message (`onMessage`) carrying the
+ * formatted text — a filled form is a typed turn, not a button tap — so the agent
+ * sees the labels + values exactly as a person would type them.
+ */
+import { type DiscordModalEntry, type DiscordModalField } from "./modal-registry.js";
+/** The custom_id key the modal itself carries: `modal:<modalId>`. */
+export declare const DISCORD_MODAL_CUSTOM_ID_PREFIX = "modal:";
+/** Wrap a modal id into the modal's custom_id marker. */
+export declare function buildDiscordModalCustomId(modalId: string): string;
+/** True when a pressed-button / submitted-modal custom_id is a modal marker. */
+export declare function isDiscordModalCustomId(value: string | undefined): boolean;
+/** Strip the marker, returning the modal id (or "" when not a modal marker). */
+export declare function decodeDiscordModalCustomId(value: string | undefined): string;
+/**
+ * The discord.js builder constructors {@link buildDiscordModal} needs. Injected
+ * (rather than imported) so a non-Discord boot never loads discord.js and tests
+ * inject fakes. The real values are `discord.ModalBuilder`, `ActionRowBuilder`,
+ * and `TextInputBuilder`.
+ */
+export interface DiscordModalBuilderDeps {
+    ModalBuilder: new () => DiscordModalBuilderLike;
+    ActionRowBuilder: new () => DiscordModalRowBuilderLike;
+    TextInputBuilder: new () => DiscordTextInputBuilderLike;
+}
+interface DiscordModalBuilderLike {
+    setCustomId(id: string): this;
+    setTitle(title: string): this;
+    addComponents(...rows: unknown[]): this;
+}
+interface DiscordModalRowBuilderLike {
+    addComponents(...inputs: unknown[]): this;
+}
+interface DiscordTextInputBuilderLike {
+    setCustomId(id: string): this;
+    setLabel(label: string): this;
+    setStyle(style: number): this;
+    setRequired(required: boolean): this;
+    setPlaceholder(placeholder: string): this;
+}
+/**
+ * Build a discord.js `ModalBuilder` from a registry entry. Each field becomes a
+ * `TextInputBuilder` in its own `ActionRowBuilder` (Discord requires one input
+ * per row). Title + labels are capped to Discord's limits. `title` is the modal
+ * heading; pass it explicitly since the registry stores the form fields, not the
+ * heading.
+ */
+export declare function buildDiscordModal(deps: DiscordModalBuilderDeps, params: {
+    modalId: string;
+    title: string;
+    entry: DiscordModalEntry;
+}): DiscordModalBuilderLike;
+/** The minimal `ModalSubmitInteraction.fields` surface we read. */
+interface DiscordModalSubmitFieldsLike {
+    /** discord.js: returns the submitted string value for a field custom_id. */
+    getTextInputValue?: (customId: string) => string;
+    /** Some shapes expose a raw field collection; read it as a fallback. */
+    fields?: Map<string, {
+        value?: string;
+    }> | Iterable<{
+        customId?: string;
+        value?: string;
+    }>;
+}
+/**
+ * Pull the submitted `{ fieldId → value }` map off a modal-submit interaction,
+ * for the given entry's fields. Reads via `getTextInputValue` first (the stable
+ * discord.js accessor), falling back to a raw fields collection. Fully guarded —
+ * a missing value yields "".
+ */
+export declare function extractModalFieldValues(interaction: {
+    fields?: DiscordModalSubmitFieldsLike;
+} | undefined, fields: DiscordModalField[]): Record<string, string>;
+/**
+ * Render a readable turn body from a modal submission. Each filled field is a
+ * `Label: value` line; an empty field is shown as `Label: (empty)` so the agent
+ * sees the full form. A leading `[form]` marker tags the turn like `[button]`
+ * does for a tap, so the agent can recognize a form submission.
+ */
+export declare function formatModalSubmissionText(entry: {
+    fields: DiscordModalField[];
+}, values: Record<string, string>): string;
+export type { DiscordModalField };
+//# sourceMappingURL=modals.d.ts.map

package/dist/agents/channels/discord/modals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modals.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/discord/modals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA4B,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE/G,qEAAqE;AACrE,eAAO,MAAM,8BAA8B,WAAW,CAAC;AAEvD,yDAAyD;AACzD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEzE;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5E;AAMD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACvC,YAAY,EAAE,UAAU,uBAAuB,CAAC;IAChD,gBAAgB,EAAE,UAAU,0BAA0B,CAAC;IACvD,gBAAgB,EAAE,UAAU,2BAA2B,CAAC;CACxD;AAED,UAAU,uBAAuB;IAChC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACxC;AACD,UAAU,0BAA0B;IACnC,aAAa,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAC1C;AACD,UAAU,2BAA2B;IACpC,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAChC,IAAI,EAAE,uBAAuB,EAC7B,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GAClE,uBAAuB,CAiBzB;AAED,mEAAmE;AACnE,UAAU,4BAA4B;IACrC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,wEAAwE;IACxE,MAAM,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,QAAQ,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACtC,WAAW,EAAE;IAAE,MAAM,CAAC,EAAE,4BAA4B,CAAA;CAAE,GAAG,SAAS,EAClE,MAAM,EAAE,iBAAiB,EAAE,GACzB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6BxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE;IAAE,MAAM,EAAE,iBAAiB,EAAE,CAAA;CAAE,EACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,MAAM,CAQR;AAED,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/agents/channels/discord/modals.js

@@ -0,0 +1,124 @@
+/**
+ * Discord modal (form) building + submission decoding (Fix 3b).
+ *
+ * A modal is opened with `interaction.showModal(modal)` in response to a button
+ * press; on submit Discord delivers a `ModalSubmitInteraction` whose `fields`
+ * accessor yields each text input's value keyed by the field's custom_id. This
+ * module:
+ *   - {@link buildDiscordModal} turns a registry {@link DiscordModalEntry} into a
+ *     discord.js `ModalBuilder` (text inputs only — Discord's STABLE modals
+ *     support only text inputs, which is correct for v1). It takes the discord.js
+ *     builder constructors as an argument so a non-Discord boot never imports
+ *     them and tests can inject lightweight fakes.
+ *   - {@link extractModalFieldValues} reads the submitted values off a
+ *     `ModalSubmitInteraction` defensively (pure — no discord.js).
+ *   - {@link formatModalSubmissionText} renders a readable turn body from the
+ *     entry's field labels + the submitted values (pure).
+ *
+ * The submission is routed as a NORMAL inbound message (`onMessage`) carrying the
+ * formatted text — a filled form is a typed turn, not a button tap — so the agent
+ * sees the labels + values exactly as a person would type them.
+ */
+import { DISCORD_TEXT_INPUT_STYLE } from "./modal-registry.js";
+/** The custom_id key the modal itself carries: `modal:<modalId>`. */
+export const DISCORD_MODAL_CUSTOM_ID_PREFIX = "modal:";
+/** Wrap a modal id into the modal's custom_id marker. */
+export function buildDiscordModalCustomId(modalId) {
+    return `${DISCORD_MODAL_CUSTOM_ID_PREFIX}${modalId}`;
+}
+/** True when a pressed-button / submitted-modal custom_id is a modal marker. */
+export function isDiscordModalCustomId(value) {
+    return typeof value === "string" && value.startsWith(DISCORD_MODAL_CUSTOM_ID_PREFIX);
+}
+/** Strip the marker, returning the modal id (or "" when not a modal marker). */
+export function decodeDiscordModalCustomId(value) {
+    if (!isDiscordModalCustomId(value))
+        return "";
+    return value.slice(DISCORD_MODAL_CUSTOM_ID_PREFIX.length);
+}
+/** Discord caps a modal title at 45 chars + a text-input label at 45 chars. */
+const DISCORD_MODAL_TITLE_MAX = 45;
+const DISCORD_MODAL_LABEL_MAX = 45;
+/**
+ * Build a discord.js `ModalBuilder` from a registry entry. Each field becomes a
+ * `TextInputBuilder` in its own `ActionRowBuilder` (Discord requires one input
+ * per row). Title + labels are capped to Discord's limits. `title` is the modal
+ * heading; pass it explicitly since the registry stores the form fields, not the
+ * heading.
+ */
+export function buildDiscordModal(deps, params) {
+    const modal = new deps.ModalBuilder()
+        .setCustomId(buildDiscordModalCustomId(params.modalId))
+        .setTitle((params.title || "Form").slice(0, DISCORD_MODAL_TITLE_MAX));
+    const rows = [];
+    for (const field of params.entry.fields) {
+        const input = new deps.TextInputBuilder()
+            .setCustomId(field.id)
+            .setLabel((field.label || field.id).slice(0, DISCORD_MODAL_LABEL_MAX))
+            .setStyle(field.style === "paragraph" ? DISCORD_TEXT_INPUT_STYLE.paragraph : DISCORD_TEXT_INPUT_STYLE.short)
+            .setRequired(field.required !== false);
+        if (field.placeholder)
+            input.setPlaceholder(field.placeholder);
+        const row = new deps.ActionRowBuilder().addComponents(input);
+        rows.push(row);
+    }
+    modal.addComponents(...rows);
+    return modal;
+}
+/**
+ * Pull the submitted `{ fieldId → value }` map off a modal-submit interaction,
+ * for the given entry's fields. Reads via `getTextInputValue` first (the stable
+ * discord.js accessor), falling back to a raw fields collection. Fully guarded —
+ * a missing value yields "".
+ */
+export function extractModalFieldValues(interaction, fields) {
+    const out = {};
+    const accessor = interaction?.fields;
+    // Build a fallback id→value map from a raw collection once, if present.
+    const fallback = new Map();
+    const rawFields = accessor?.fields;
+    if (rawFields) {
+        if (rawFields instanceof Map) {
+            for (const [id, v] of rawFields)
+                fallback.set(id, typeof v?.value === "string" ? v.value : "");
+        }
+        else {
+            for (const v of rawFields) {
+                if (typeof v?.customId === "string")
+                    fallback.set(v.customId, typeof v.value === "string" ? v.value : "");
+            }
+        }
+    }
+    for (const field of fields) {
+        let value = "";
+        if (typeof accessor?.getTextInputValue === "function") {
+            try {
+                value = accessor.getTextInputValue(field.id) ?? "";
+            }
+            catch {
+                value = fallback.get(field.id) ?? "";
+            }
+        }
+        else {
+            value = fallback.get(field.id) ?? "";
+        }
+        out[field.id] = typeof value === "string" ? value : "";
+    }
+    return out;
+}
+/**
+ * Render a readable turn body from a modal submission. Each filled field is a
+ * `Label: value` line; an empty field is shown as `Label: (empty)` so the agent
+ * sees the full form. A leading `[form]` marker tags the turn like `[button]`
+ * does for a tap, so the agent can recognize a form submission.
+ */
+export function formatModalSubmissionText(entry, values) {
+    const lines = ["[form]"];
+    for (const field of entry.fields) {
+        const raw = values[field.id];
+        const value = typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : "(empty)";
+        lines.push(`${field.label || field.id}: ${value}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=modals.js.map

package/dist/agents/channels/discord/modals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modals.js","sourceRoot":"","sources":["../../../../src/agents/channels/discord/modals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,wBAAwB,EAAkD,MAAM,qBAAqB,CAAC;AAE/G,qEAAqE;AACrE,MAAM,CAAC,MAAM,8BAA8B,GAAG,QAAQ,CAAC;AAEvD,yDAAyD;AACzD,MAAM,UAAU,yBAAyB,CAAC,OAAe;IACxD,OAAO,GAAG,8BAA8B,GAAG,OAAO,EAAE,CAAC;AACtD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,sBAAsB,CAAC,KAAyB;IAC/D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC;AACtF,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,0BAA0B,CAAC,KAAyB;IACnE,IAAI,CAAC,sBAAsB,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC9C,OAAQ,KAAgB,CAAC,KAAK,CAAC,8BAA8B,CAAC,MAAM,CAAC,CAAC;AACvE,CAAC;AAED,+EAA+E;AAC/E,MAAM,uBAAuB,GAAG,EAAE,CAAC;AACnC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AA8BnC;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAChC,IAA6B,EAC7B,MAAoE;IAEpE,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,YAAY,EAAE;SACnC,WAAW,CAAC,yBAAyB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;SACtD,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC;IACvE,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,gBAAgB,EAAE;aACvC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;aACrB,QAAQ,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC;aACrE,QAAQ,CAAC,KAAK,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,wBAAwB,CAAC,SAAS,CAAC,CAAC,CAAC,wBAAwB,CAAC,KAAK,CAAC;aAC3G,WAAW,CAAC,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC;QACxC,IAAI,KAAK,CAAC,WAAW;YAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;IACD,KAAK,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7B,OAAO,KAAK,CAAC;AACd,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACtC,WAAkE,EAClE,MAA2B;IAE3B,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,WAAW,EAAE,MAAM,CAAC;IACrC,wEAAwE;IACxE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,SAAS,GAAG,QAAQ,EAAE,MAAM,CAAC;IACnC,IAAI,SAAS,EAAE,CAAC;QACf,IAAI,SAAS,YAAY,GAAG,EAAE,CAAC;YAC9B,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,SAAS;gBAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChG,CAAC;aAAM,CAAC;YACP,KAAK,MAAM,CAAC,IAAI,SAA4D,EAAE,CAAC;gBAC9E,IAAI,OAAO,CAAC,EAAE,QAAQ,KAAK,QAAQ;oBAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC3G,CAAC;QACF,CAAC;IACF,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,IAAI,OAAO,QAAQ,EAAE,iBAAiB,KAAK,UAAU,EAAE,CAAC;YACvD,IAAI,CAAC;gBACJ,KAAK,GAAG,QAAQ,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YACpD,CAAC;YAAC,MAAM,CAAC;gBACR,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YACtC,CAAC;QACF,CAAC;aAAM,CAAC;YACP,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QACtC,CAAC;QACD,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACxC,KAAsC,EACtC,MAA8B;IAE9B,MAAM,KAAK,GAAa,CAAC,QAAQ,CAAC,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7B,MAAM,KAAK,GAAG,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC"}

package/dist/agents/channels/discord/permission-audit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Discord channel-permission audit — the #2 Discord footgun after the MESSAGE
+ * CONTENT intent.
+ *
+ * A bot can be "connected" and still silently fail to post because its role
+ * lacks `View Channel` + `Send Messages` in a specific channel (or a channel
+ * permission OVERWRITE denies it). This module computes the bot's EFFECTIVE
+ * permissions per channel the same way Discord does — base @everyone + the
+ * bot's role permissions, then the channel's permission overwrites (deny then
+ * allow, applied @everyone → roles → member) — and reports which channels are
+ * missing the two required bits.
+ *
+ * Self-contained REST (no `discord.js`): `GET /channels/{id}` →
+ * `GET /guilds/{guildId}` (roles) → `GET /guilds/{guildId}/members/{botId}`
+ * (the bot's roles), plus a one-time `GET /users/@me` for the bot id. Injectable
+ * fetch (tests stub it); never throws — a per-channel failure surfaces as an
+ * `error` row, never an exception. Only NUMERIC ids are audited; a non-numeric
+ * key is reported unresolved so the operator fixes the config.
+ */
+/** Per-channel audit result. */
+export interface DiscordChannelPermissionResult {
+    channelId: string;
+    /** True when the bot has every required bit (or Administrator). */
+    ok: boolean;
+    /** Required permission names the bot is MISSING (empty when ok). */
+    missingRequired: string[];
+    /** Best-effort error when the channel couldn't be evaluated. */
+    error?: string;
+}
+/** Overall audit result. */
+export interface DiscordPermissionAuditResult {
+    channels: DiscordChannelPermissionResult[];
+    /** Count of supplied ids that weren't numeric snowflakes (can't be audited). */
+    unresolvedChannels: number;
+}
+/**
+ * Audit the bot's `ViewChannel` + `SendMessages` in each supplied channel id.
+ * Non-numeric ids are counted under `unresolvedChannels` and skipped (Discord
+ * ids are numeric snowflakes — a name/slug key can't be resolved via REST). The
+ * bot user id is fetched once via `/users/@me`. Best-effort + never throws.
+ */
+export declare function auditDiscordChannelPermissions(token: string, channelIds: string[], fetchImpl?: typeof fetch): Promise<DiscordPermissionAuditResult>;
+//# sourceMappingURL=permission-audit.d.ts.map

package/dist/agents/channels/discord/permission-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-audit.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/discord/permission-audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAeH,gCAAgC;AAChC,MAAM,WAAW,8BAA8B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,EAAE,EAAE,OAAO,CAAC;IACZ,oEAAoE;IACpE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,4BAA4B;AAC5B,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,EAAE,8BAA8B,EAAE,CAAC;IAC3C,gFAAgF;IAChF,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AA+HD;;;;;GAKG;AACH,wBAAsB,8BAA8B,CACnD,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAAE,EACpB,SAAS,GAAE,OAAO,KAAa,GAC7B,OAAO,CAAC,4BAA4B,CAAC,CAuDvC"}

package/dist/agents/channels/discord/permission-audit.js

@@ -0,0 +1,192 @@
+/**
+ * Discord channel-permission audit — the #2 Discord footgun after the MESSAGE
+ * CONTENT intent.
+ *
+ * A bot can be "connected" and still silently fail to post because its role
+ * lacks `View Channel` + `Send Messages` in a specific channel (or a channel
+ * permission OVERWRITE denies it). This module computes the bot's EFFECTIVE
+ * permissions per channel the same way Discord does — base @everyone + the
+ * bot's role permissions, then the channel's permission overwrites (deny then
+ * allow, applied @everyone → roles → member) — and reports which channels are
+ * missing the two required bits.
+ *
+ * Self-contained REST (no `discord.js`): `GET /channels/{id}` →
+ * `GET /guilds/{guildId}` (roles) → `GET /guilds/{guildId}/members/{botId}`
+ * (the bot's roles), plus a one-time `GET /users/@me` for the bot id. Injectable
+ * fetch (tests stub it); never throws — a per-channel failure surfaces as an
+ * `error` row, never an exception. Only NUMERIC ids are audited; a non-numeric
+ * key is reported unresolved so the operator fixes the config.
+ */
+/** Discord permission bits (bigint). */
+const PERM_ADMINISTRATOR = 1n << 3n;
+const PERM_VIEW_CHANNEL = 1n << 10n;
+const PERM_SEND_MESSAGES = 1n << 11n;
+const DISCORD_API_BASE = "https://discord.com/api/v10";
+/** Required permissions a bot needs to operate in a channel. */
+const REQUIRED = [
+    { bit: PERM_VIEW_CHANNEL, name: "ViewChannel" },
+    { bit: PERM_SEND_MESSAGES, name: "SendMessages" },
+];
+/** A numeric snowflake id (Discord ids are decimal strings). */
+function isNumericId(value) {
+    return /^\d+$/.test(value.trim());
+}
+/** Apply an overwrite's deny then allow to a running permission bitfield. */
+function applyOverwrite(perms, ow) {
+    let next = perms;
+    if (ow.deny) {
+        try {
+            next &= ~BigInt(ow.deny);
+        }
+        catch {
+            /* malformed bitstring — ignore */
+        }
+    }
+    if (ow.allow) {
+        try {
+            next |= BigInt(ow.allow);
+        }
+        catch {
+            /* malformed bitstring — ignore */
+        }
+    }
+    return next;
+}
+/** Authenticated GET → parsed JSON object, or throws with a compact message. */
+async function getJson(url, token, fetchImpl) {
+    const res = await fetchImpl(url, {
+        method: "GET",
+        headers: { Authorization: `Bot ${token}`, "content-type": "application/json" },
+    });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+    }
+    return (await res.json());
+}
+/**
+ * Compute the bot's effective permission bitfield in one channel, mirroring
+ * Discord's resolution order: base (@everyone role + the bot's roles), then
+ * @everyone overwrite, then the bot's role overwrites, then the bot's member
+ * overwrite. Administrator short-circuits to "all". Returns the bitfield.
+ */
+function computeEffectivePermissions(params) {
+    const { botId, guildId, channel, guild, member } = params;
+    const rolesById = new Map();
+    for (const role of guild.roles ?? []) {
+        if (typeof role.id !== "string")
+            continue;
+        let bits = 0n;
+        try {
+            bits = role.permissions ? BigInt(role.permissions) : 0n;
+        }
+        catch {
+            bits = 0n;
+        }
+        rolesById.set(role.id, bits);
+    }
+    // Base = @everyone (role id === guildId) + each of the bot's roles.
+    let perms = rolesById.get(guildId) ?? 0n;
+    const memberRoleIds = Array.isArray(member.roles) ? member.roles : [];
+    for (const roleId of memberRoleIds) {
+        perms |= rolesById.get(roleId) ?? 0n;
+    }
+    // Administrator → all permissions, overwrites ignored.
+    if ((perms & PERM_ADMINISTRATOR) === PERM_ADMINISTRATOR) {
+        return ~0n;
+    }
+    const overwrites = Array.isArray(channel.permission_overwrites) ? channel.permission_overwrites : [];
+    // @everyone overwrite.
+    for (const ow of overwrites) {
+        if (ow.id === guildId)
+            perms = applyOverwrite(perms, ow);
+    }
+    // The bot's role overwrites (accumulate allow/deny across them).
+    let roleAllow = 0n;
+    let roleDeny = 0n;
+    for (const ow of overwrites) {
+        if (ow.type === 0 && ow.id && memberRoleIds.includes(ow.id)) {
+            try {
+                if (ow.deny)
+                    roleDeny |= BigInt(ow.deny);
+                if (ow.allow)
+                    roleAllow |= BigInt(ow.allow);
+            }
+            catch {
+                /* ignore malformed */
+            }
+        }
+    }
+    perms &= ~roleDeny;
+    perms |= roleAllow;
+    // The bot's member overwrite (highest precedence).
+    for (const ow of overwrites) {
+        if (ow.id === botId)
+            perms = applyOverwrite(perms, ow);
+    }
+    return perms;
+}
+/**
+ * Audit the bot's `ViewChannel` + `SendMessages` in each supplied channel id.
+ * Non-numeric ids are counted under `unresolvedChannels` and skipped (Discord
+ * ids are numeric snowflakes — a name/slug key can't be resolved via REST). The
+ * bot user id is fetched once via `/users/@me`. Best-effort + never throws.
+ */
+export async function auditDiscordChannelPermissions(token, channelIds, fetchImpl = fetch) {
+    const clean = (token ?? "").trim();
+    const ids = (channelIds ?? []).map((c) => (c ?? "").trim()).filter(Boolean);
+    const numeric = ids.filter(isNumericId);
+    const unresolvedChannels = ids.length - numeric.length;
+    if (!clean || numeric.length === 0) {
+        return { channels: [], unresolvedChannels };
+    }
+    // Resolve the bot user id once (needed for the member overwrite + member fetch).
+    let botId = "";
+    try {
+        const me = await getJson(`${DISCORD_API_BASE}/users/@me`, clean, fetchImpl);
+        botId = typeof me?.id === "string" ? me.id : "";
+    }
+    catch {
+        botId = "";
+    }
+    if (!botId) {
+        return {
+            channels: numeric.map((channelId) => ({
+                channelId,
+                ok: false,
+                missingRequired: REQUIRED.map((r) => r.name),
+                error: "could not resolve bot identity (/users/@me failed)",
+            })),
+            unresolvedChannels,
+        };
+    }
+    const channels = [];
+    for (const channelId of numeric) {
+        try {
+            const channel = await getJson(`${DISCORD_API_BASE}/channels/${channelId}`, clean, fetchImpl);
+            const guildId = typeof channel.guild_id === "string" ? channel.guild_id : "";
+            if (!guildId) {
+                // A DM / group channel has no guild perms — treat as ok (the bot can
+                // always send to a DM it can fetch).
+                channels.push({ channelId, ok: true, missingRequired: [] });
+                continue;
+            }
+            const [guild, member] = await Promise.all([
+                getJson(`${DISCORD_API_BASE}/guilds/${guildId}`, clean, fetchImpl),
+                getJson(`${DISCORD_API_BASE}/guilds/${guildId}/members/${botId}`, clean, fetchImpl),
+            ]);
+            const perms = computeEffectivePermissions({ botId, guildId, channel, guild, member });
+            const missingRequired = REQUIRED.filter((r) => (perms & r.bit) !== r.bit).map((r) => r.name);
+            channels.push({ channelId, ok: missingRequired.length === 0, missingRequired });
+        }
+        catch (err) {
+            channels.push({
+                channelId,
+                ok: false,
+                missingRequired: REQUIRED.map((r) => r.name),
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { channels, unresolvedChannels };
+}
+//# sourceMappingURL=permission-audit.js.map

package/dist/agents/channels/discord/permission-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-audit.js","sourceRoot":"","sources":["../../../../src/agents/channels/discord/permission-audit.ts"],"names":[],"mappings":"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"}

package/dist/agents/channels/discord/plugin.d.ts

@@ -39,6 +39,7 @@ import type { BrigadeConfig } from "../../../config/types.js";
 import { type ChannelAdapter, type ChannelOutboundTarget, type ChannelPlugin, type StartChannelsArgs } from "../sdk.js";
 import { type ResolvedDiscordAccount } from "./account-config.js";
 import { type DiscordProbeResult } from "./probe.js";
+import { type DiscordPermissionAuditResult } from "./permission-audit.js";
 /** Dependencies the gateway hands the plugin to drive turns + replies. */
 export interface DiscordPluginDeps {
     /** Boot-time default agent for routing fallbacks. */
@@ -55,15 +56,30 @@ export interface DiscordPluginDeps {
         accountId: string;
     }) => ChannelAdapter;
 }
+/** Probe result + optional channel-permission audit (Phase 5 diagnostics). */
+export type DiscordProbeWithAudit = DiscordProbeResult & {
+    /** Channel-permission audit for the configured guild channels, when run. */
+    permissionAudit?: DiscordPermissionAuditResult;
+};
 /** Operator-grade view of a per-account bot — exposed via attached helpers. */
 export interface DiscordPluginRuntimeView {
     /** Currently-running account ids. */
     startedAccountIds(): string[];
     /** Look up the per-account adapter (or undefined when the account isn't started). */
     getAdapter(accountId: string): ChannelAdapter | undefined;
-    /** Run a `/users/@me` probe for an account (for status / doctor). */
-    probeAccount(accountId: string, cfg: BrigadeConfig): Promise<DiscordProbeResult>;
+    /**
+     * Run a `/users/@me` probe for an account (for status / doctor). Also runs the
+     * channel-permission audit over any configured guild channels (Phase 5).
+     */
+    probeAccount(accountId: string, cfg: BrigadeConfig): Promise<DiscordProbeWithAudit>;
 }
+/**
+ * Collect the numeric guild channel ids configured under
+ * `channels.discord.guilds.<guildId>.channels.<channelId>` so the permission
+ * audit knows which channels to check. Non-numeric keys are passed through too —
+ * the audit reports them as unresolved. Returns [] when none are configured.
+ */
+export declare function collectConfiguredDiscordChannelIds(cfg: BrigadeConfig): string[];
 /** Plugin handle with the extra per-account introspection surface attached. */
 export type DiscordPluginHandle = ChannelPlugin<ResolvedDiscordAccount> & DiscordPluginRuntimeView;
 /** Construct the plugin instance, capturing per-account runtime state in closure. */

package/dist/agents/channels/discord/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/discord/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAON,KAAK,cAAc,EAOnB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAKlB,KAAK,iBAAiB,EAEtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAMN,KAAK,sBAAsB,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAkBnE,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IACjC,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,UAAU,EAAE,MAAM,aAAa,CAAC;IAChC,mEAAmE;IACnE,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACtC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CACjE;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACxC,qCAAqC;IACrC,iBAAiB,IAAI,MAAM,EAAE,CAAC;IAC9B,qFAAqF;IACrF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D,qEAAqE;IACrE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjF;AAED,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC,sBAAsB,CAAC,GAAG,wBAAwB,CAAC;AAqBnG,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CA6NhF;AAOD,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/agents/channels/discord/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAON,KAAK,cAAc,EAOnB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAKlB,KAAK,iBAAiB,EAEtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAMN,KAAK,sBAAsB,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAkC,KAAK,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAoB1G,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IACjC,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,UAAU,EAAE,MAAM,aAAa,CAAC;IAChC,mEAAmE;IACnE,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACtC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,cAAc,CAAC;CACjE;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,GAAG;IACxD,4EAA4E;IAC5E,eAAe,CAAC,EAAE,4BAA4B,CAAC;CAC/C,CAAC;AAEF,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACxC,qCAAqC;IACrC,iBAAiB,IAAI,MAAM,EAAE,CAAC;IAC9B,qFAAqF;IACrF,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D;;;OAGG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACpF;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,EAAE,CAe/E;AAED,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC,sBAAsB,CAAC,GAAG,wBAAwB,CAAC;AAqBnG,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CA4QhF;AAOD,yEAAyE;AACzE,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,CAAC"}

package/dist/agents/channels/discord/plugin.js

@@ -43,6 +43,9 @@ import { buildBundledCommands, createInboundPipelineContext, createSubsystemLogg
 import { listDiscordAccountIds, resolveDiscordAccount, resolveDiscordBotToken, DISCORD_CHANNEL_ID, DISCORD_DEFAULT_ACCOUNT_ID, } from "./account-config.js";
 import { createDiscordAdapter, DISCORD_CAPABILITIES } from "./adapter.js";
 import { probeDiscord } from "./probe.js";
+import { auditDiscordChannelPermissions } from "./permission-audit.js";
+import { collectDiscordSecurityAuditFindings } from "./security-audit.js";
+import { collectDiscordStatusIssues } from "./status-issues.js";
 const log = createSubsystemLogger("channels/discord/plugin");
 // Single source of truth for the channel's user-facing metadata lives in the
 // import-light `bundled-channel-metas` module (re-exported via the SDK barrel),
@@ -50,6 +53,32 @@ const log = createSubsystemLogger("channels/discord/plugin");
 // `DISCORD_CHANNEL_META.id` is the same canonical `"discord"` string as
 // `DISCORD_CHANNEL_ID`.
 const DISCORD_META = DISCORD_CHANNEL_META;
+/**
+ * Collect the numeric guild channel ids configured under
+ * `channels.discord.guilds.<guildId>.channels.<channelId>` so the permission
+ * audit knows which channels to check. Non-numeric keys are passed through too —
+ * the audit reports them as unresolved. Returns [] when none are configured.
+ */
+export function collectConfiguredDiscordChannelIds(cfg) {
+    const slot = cfg.channels?.[DISCORD_CHANNEL_ID];
+    const guilds = slot && typeof slot === "object" ? slot.guilds : undefined;
+    if (!guilds || typeof guilds !== "object")
+        return [];
+    const ids = new Set();
+    for (const guildValue of Object.values(guilds)) {
+        if (!guildValue || typeof guildValue !== "object")
+            continue;
+        const channels = guildValue.channels;
+        if (!channels || typeof channels !== "object")
+            continue;
+        for (const channelKey of Object.keys(channels)) {
+            const key = channelKey.trim();
+            if (key)
+                ids.add(key);
+        }
+    }
+    return [...ids];
+}
 /** Build the per-account approval capability — the native component prompt + approver gate. */
 function buildApprovalCapability(adapter, accountId) {
     return {
@@ -200,13 +229,28 @@ export function createDiscordPlugin(deps) {
         probeAccount: async (accountId, cfg) => {
             const token = resolveDiscordBotToken(cfg, accountId);
             const result = await probeDiscord({ token });
+            // Channel-permission audit over any configured guild channels (Phase 5).
+            // Best-effort: skipped when the token / probe failed (nothing to check
+            // against), or when no channels are configured.
+            let permissionAudit;
+            const channelIds = collectConfiguredDiscordChannelIds(cfg);
+            if (result.ok && token && channelIds.length > 0) {
+                try {
+                    permissionAudit = await auditDiscordChannelPermissions(token, channelIds);
+                }
+                catch {
+                    /* never fail the probe on the audit */
+                }
+            }
             // Surface the started adapter's liveness signal alongside the /users/@me
             // reachability check (observability only — never changes `ok`).
             const live = accountRuntimes.get(accountId)?.adapter;
-            if (live && typeof live.lastEventAt === "function") {
-                return { ...result, lastEventAt: live.lastEventAt() };
-            }
-            return result;
+            const lastEventAt = live && typeof live.lastEventAt === "function" ? live.lastEventAt() : undefined;
+            return {
+                ...result,
+                ...(lastEventAt !== undefined ? { lastEventAt } : {}),
+                ...(permissionAudit ? { permissionAudit } : {}),
+            };
         },
         config: {
             listAccountIds: (cfg) => listDiscordAccountIds(cfg),
@@ -294,6 +338,31 @@ export function createDiscordPlugin(deps) {
                 { path: "channels.discord.accounts.*.botToken", description: "Discord bot token (per account)" },
             ],
         },
+        // Supplementary security audit (Phase 5): warn on name-based (mutable)
+        // allow-list entries. Consumed by `brigade doctor` via the central
+        // `channel-security-registry.ts` collector.
+        security: {
+            collectAuditFindings: (ctx) => collectDiscordSecurityAuditFindings({ cfg: ctx.sourceConfig, accountId: ctx.accountId }),
+        },
+        // Structured status rollup (Phase 5): intent + permission issues. The
+        // central status surface stashes the probe/audit on each account snapshot
+        // (under `probe` / `audit`); this adapts those into Discord status issues.
+        status: {
+            collectStatusIssues: (accounts) => collectDiscordStatusIssues(accounts.map((snap) => {
+                const s = snap;
+                return {
+                    accountId: typeof s.accountId === "string" ? s.accountId : "",
+                    ...(s.probe ? { probe: s.probe } : {}),
+                    // The audit may ride on the probe (probeAccount attaches it) or be
+                    // stashed directly on the snapshot.
+                    ...(s.probe?.permissionAudit
+                        ? { audit: s.probe.permissionAudit }
+                        : s.audit
+                            ? { audit: s.audit }
+                            : {}),
+                };
+            })),
+        },
     };
 }
 /** Default adapter factory — threads the per-account scope. */