@addozhang/dsh-discord 0.1.0

package/lib/lifecycle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The adapter's single cancellation root. Every timer, listener, and
+ * abortable resource the plugin opens registers here, so Cordis-owned
+ * disposal tears the whole runtime down in one effect and no callback can
+ * ever run after the plugin unloads.
+ */
+export type Disposer = () => void;
+/** Minimal event target face the root's listener helper needs. */
+export interface ListenerTarget {
+    addEventListener(name: string, handler: () => void): unknown;
+    removeEventListener(name: string, handler: () => void): unknown;
+}
+export declare class CancellationRoot {
+    private disposedState;
+    private readonly pendingTimers;
+    private readonly disposables;
+    private readonly controller;
+    /** The abort signal async work (streams, fetches) must observe. */
+    get signal(): AbortSignal;
+    /** Whether this root has been torn down; disposed roots refuse new work. */
+    get disposed(): boolean;
+    /** Run `callback` every `ms` until disposal; the timer never fires after. */
+    setInterval(callback: () => void, ms: number): void;
+    /** Run `callback` once after `ms` unless disposal happens first. */
+    setTimeout(callback: () => void, ms: number): void;
+    /** Observe `name` on `target` until disposal removes the listener. */
+    listen(target: ListenerTarget, name: string, handler: () => void): void;
+    /** Register one disposer running at disposal (reverse registration order). */
+    register(disposer: Disposer): void;
+    /**
+     * Tear everything down: clear timers, run disposers in reverse order,
+     * abort the signal, and refuse all future work. Idempotent.
+     */
+    dispose(): void;
+    private assertActive;
+}
+/**
+ * Install the plugin's cancellation root on its own Cordis fiber: the
+ * returned root lives exactly as long as the plugin and is disposed through
+ * the fiber's effect teardown.
+ */
+export declare function installCancellationRoot(ctx: {
+    effect(execute: () => () => void, label?: string): unknown;
+}): CancellationRoot;

package/lib/lifecycle.js

@@ -0,0 +1,84 @@
+/**
+ * The adapter's single cancellation root. Every timer, listener, and
+ * abortable resource the plugin opens registers here, so Cordis-owned
+ * disposal tears the whole runtime down in one effect and no callback can
+ * ever run after the plugin unloads.
+ */
+export class CancellationRoot {
+    disposedState = false;
+    pendingTimers = new Set();
+    disposables = [];
+    controller = new AbortController();
+    /** The abort signal async work (streams, fetches) must observe. */
+    get signal() {
+        return this.controller.signal;
+    }
+    /** Whether this root has been torn down; disposed roots refuse new work. */
+    get disposed() {
+        return this.disposedState;
+    }
+    /** Run `callback` every `ms` until disposal; the timer never fires after. */
+    setInterval(callback, ms) {
+        this.assertActive();
+        const timer = setInterval(() => { callback(); }, ms);
+        this.pendingTimers.add(timer);
+    }
+    /** Run `callback` once after `ms` unless disposal happens first. */
+    setTimeout(callback, ms) {
+        this.assertActive();
+        const timer = setTimeout(() => {
+            this.pendingTimers.delete(timer);
+            callback();
+        }, ms);
+        this.pendingTimers.add(timer);
+    }
+    /** Observe `name` on `target` until disposal removes the listener. */
+    listen(target, name, handler) {
+        this.assertActive();
+        target.addEventListener(name, handler);
+        this.disposables.push(() => { target.removeEventListener(name, handler); });
+    }
+    /** Register one disposer running at disposal (reverse registration order). */
+    register(disposer) {
+        this.assertActive();
+        this.disposables.push(disposer);
+    }
+    /**
+     * Tear everything down: clear timers, run disposers in reverse order,
+     * abort the signal, and refuse all future work. Idempotent.
+     */
+    dispose() {
+        if (this.disposedState)
+            return;
+        this.disposedState = true;
+        for (const timer of this.pendingTimers)
+            clearTimeout(timer);
+        this.pendingTimers.clear();
+        for (const disposer of [...this.disposables].reverse()) {
+            try {
+                disposer();
+            }
+            catch {
+                // A failing disposer must not stop the remaining teardown; the root
+                // is already marked disposed, so nothing can re-register.
+            }
+        }
+        this.disposables.length = 0;
+        this.controller.abort();
+    }
+    assertActive() {
+        if (this.disposedState) {
+            throw new TypeError('dsh-discord cancellation root is disposed; refusing new work');
+        }
+    }
+}
+/**
+ * Install the plugin's cancellation root on its own Cordis fiber: the
+ * returned root lives exactly as long as the plugin and is disposed through
+ * the fiber's effect teardown.
+ */
+export function installCancellationRoot(ctx) {
+    const root = new CancellationRoot();
+    ctx.effect(() => () => { root.dispose(); }, 'dsh-discord cancellation root');
+    return root;
+}

package/lib/policy/authorization.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The pure authorization evaluator. Two nested boundaries:
+ *
+ * 1. The Guild allowlist is the outer tenant boundary — no ownership,
+ *    permission, or role ever bypasses it.
+ * 2. Inside an allowed Guild, deny-user/deny-role rules beat every allow
+ *    rule: member grants, configured administrator grants, Discord-native
+ *    administrator authority (owner / Administrator / Manage Guild), and the
+ *    global Host-operator list alike. Bots other than the adapter itself are
+ *    refused outright.
+ *
+ * The decision ranks so callers can require a minimum level: a
+ * host-operator satisfies member and workspace-administrator requirements.
+ */
+import type { DiscordSettings } from '../settings.js';
+/** The policy slice the evaluator reads (the adapter's settings document). */
+export type PolicyTable = Pick<DiscordSettings, 'allowedGuildIds' | 'memberUserIds' | 'memberRoleIds' | 'administratorUserIds' | 'administratorRoleIds' | 'deniedUserIds' | 'deniedRoleIds' | 'hostOperatorUserIds'>;
+/** The normalized actor facts the evaluator consumes (precomputed upstream). */
+export interface AuthorizationInput {
+    guildId: string;
+    userId: string;
+    /** Role ids the wire attached to the member (callers include @everyone if desired). */
+    roleIds: readonly string[];
+    /** Discord permission bitmask as the wire carries it (string or number). */
+    memberPermissions?: string | number | undefined;
+    isGuildOwner?: boolean | undefined;
+    /** Any bot besides the adapter is unauthorized; the adapter self-filters earlier. */
+    isBot?: boolean | undefined;
+}
+/** Access levels in ascending authority order. */
+export type AccessLevel = 'member' | 'workspace-administrator' | 'host-operator';
+export type AccessDecision = {
+    allowed: true;
+    level: AccessLevel;
+} | {
+    allowed: false;
+    reason: 'guild-not-allowed' | 'bot-not-authorized' | 'denied' | 'no-grant';
+};
+/** Whether an allowed decision satisfies a required minimum level. */
+export declare function levelAtLeast(level: AccessLevel, required: AccessLevel): boolean;
+export declare function evaluateAuthorization(policy: PolicyTable, actor: AuthorizationInput): AccessDecision;

package/lib/policy/authorization.js

@@ -0,0 +1,64 @@
+/**
+ * The pure authorization evaluator. Two nested boundaries:
+ *
+ * 1. The Guild allowlist is the outer tenant boundary — no ownership,
+ *    permission, or role ever bypasses it.
+ * 2. Inside an allowed Guild, deny-user/deny-role rules beat every allow
+ *    rule: member grants, configured administrator grants, Discord-native
+ *    administrator authority (owner / Administrator / Manage Guild), and the
+ *    global Host-operator list alike. Bots other than the adapter itself are
+ *    refused outright.
+ *
+ * The decision ranks so callers can require a minimum level: a
+ * host-operator satisfies member and workspace-administrator requirements.
+ */
+const DISCORD_ADMINISTRATOR = 1n << 3n;
+const DISCORD_MANAGE_GUILD = 1n << 5n;
+function hasPermission(permissions, flag) {
+    if (permissions === undefined)
+        return false;
+    try {
+        const mask = typeof permissions === 'string' ? BigInt(permissions) : BigInt(permissions);
+        return (mask & flag) === flag;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether an allowed decision satisfies a required minimum level. */
+export function levelAtLeast(level, required) {
+    const order = ['member', 'workspace-administrator', 'host-operator'];
+    return order.indexOf(level) >= order.indexOf(required);
+}
+export function evaluateAuthorization(policy, actor) {
+    // 1. Outer boundary: the explicit Guild allowlist. Nothing bypasses it.
+    if (!policy.allowedGuildIds.includes(actor.guildId)) {
+        return { allowed: false, reason: 'guild-not-allowed' };
+    }
+    // 2. Bots other than the adapter are never authorized.
+    if (actor.isBot === true) {
+        return { allowed: false, reason: 'bot-not-authorized' };
+    }
+    // 3. Deny rules take precedence over every allow rule at every level.
+    if (policy.deniedUserIds.includes(actor.userId) || actor.roleIds.some(role => policy.deniedRoleIds.includes(role))) {
+        return { allowed: false, reason: 'denied' };
+    }
+    // 4. Host-operator: the global allowlist.
+    if (policy.hostOperatorUserIds.includes(actor.userId)) {
+        return { allowed: true, level: 'host-operator' };
+    }
+    // 5. Workspace administrators: configured ids plus Discord-native authority.
+    const configuredAdmin = policy.administratorUserIds.includes(actor.userId)
+        || actor.roleIds.some(role => policy.administratorRoleIds.includes(role));
+    const nativeAdmin = actor.isGuildOwner === true
+        || hasPermission(actor.memberPermissions, DISCORD_ADMINISTRATOR)
+        || hasPermission(actor.memberPermissions, DISCORD_MANAGE_GUILD);
+    if (configuredAdmin || nativeAdmin) {
+        return { allowed: true, level: 'workspace-administrator' };
+    }
+    // 6. Ordinary members: explicit user or role grants only.
+    if (policy.memberUserIds.includes(actor.userId) || actor.roleIds.some(role => policy.memberRoleIds.includes(role))) {
+        return { allowed: true, level: 'member' };
+    }
+    return { allowed: false, reason: 'no-grant' };
+}

package/lib/policy/disclosure.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Least-disclosure labels and output policy (amended design §3, 16.1).
+ * Workspace lists show titles disambiguated by short opaque id suffixes.
+ * Paths are not treated as sensitive for this self-hosted, trusted-Guild
+ * product: the canonical path renders in the ephemeral detail response and
+ * an abbreviated form may appear in autocomplete labels — but a path never
+ * reaches channel metadata or public (non-ephemeral) messages. User-controlled
+ * text is sanitized before it can forge Discord mentions or overflow
+ * component limits, and every outbound message carries
+ * `allowed_mentions: { parse: [] }` plus byte-wise syntax neutralization so
+ * assistant, tool, title, and error content can never ping anyone.
+ */
+/** A workspace as the adapter's listing surfaces see it. */
+export interface WorkspaceEntry {
+    id: string;
+    title: string;
+    /** Canonical path; rendered in ephemeral details, abbreviated in autocomplete labels. */
+    path?: string | undefined;
+}
+/**
+ * path abbreviation (16.1): the user's home directory collapses
+ * to a `~` prefix — `/Users/addo/Workspaces/x` → `~/Workspaces/x` — so
+ * autocomplete labels stay short without hiding the directory structure.
+ * The home path must end at a segment boundary: `/Users/addoish/x` is NOT under `/Users/addo`. Display-only;
+ * never persisted to Discord metadata.
+ */
+export declare function abbreviatePath(fullPath: string, home?: string): string;
+/** One rendered row of a Workspace list. */
+export interface WorkspaceLabel {
+    id: string;
+    title: string;
+    /** Discord-renderable label carrying no path. */
+    label: string;
+}
+/**
+ * Discord's SUPPRESS_NOTIFICATIONS message flag (1 << 12): the message will
+ * not trigger push/desktop notifications. This flag says nothing about
+ * mentions — ping prevention is the `allowed_mentions` request field below,
+ * and the syntax neutralization in policy/suppress.ts is the third layer.
+ */
+export declare const DISCORD_SUPPRESS_NOTIFICATIONS_FLAG: number;
+/**
+ * Discord's request field that disables every mention parse category: with
+ * `parse: []` no `@everyone`, user, role, or channel mention in the content
+ * pings, regardless of how the content renders. Every message create/edit
+ * the adapter sends carries this.
+ */
+export declare const ALLOWED_MENTIONS_NONE: {
+    parse: string[];
+};
+/** Discord's ephemeral message flag (only the invoker sees the message). */
+export declare const DISCORD_EPHEMERAL_FLAG: number;
+/** Ephemeral + silent: the standard adapter followup flags. */
+export declare const OUTBOUND_EPHEMERAL_FLAGS: number;
+/**
+ * The comparison key for Discord channel/thread names: Discord slugs names
+ * (lowercase, whitespace runs collapse to `-`), so a rename-dedupe check
+ * must compare both sides slugified or every restart burns a rename.
+ */
+export declare function discordChannelNameKey(text: string): string;
+/**
+ * Sanitize user-controlled text for safe rendering as a label or title:
+ * control characters and line breaks collapse, mention syntax breaks, and
+ * Discord's component length ceiling applies.
+ */
+export declare function safeTitle(text: string, maxLength?: number): string;
+/**
+ * Label a Workspace list: unique titles stay bare; duplicate titles gain a
+ * short id suffix so every label stays unambiguous without exposing paths.
+ * Escalating suffix groups grow together (4 → 8 → … chars, then the full id)
+ * and stay deterministic.
+ */
+export declare function workspaceLabels(entries: readonly WorkspaceEntry[]): WorkspaceLabel[];
+/** The opaque value a select option encodes for choosing this workspace. */
+export declare function workspaceReference(id: string): string;
+/** The inverse of workspaceReference; `undefined` for any other string. */
+export declare function parseWorkspaceReference(reference: string): string | undefined;
+export interface WorkspaceDetail {
+    id: string;
+    title: string;
+    label: string;
+    /** Canonical path; rendered when the caller is an authorized member. */
+    path?: string | undefined;
+}
+/**
+ * Project one workspace for display. `includePath` is for the ephemeral
+ * detail response (any authorized member per amended design §3); list
+ * surfaces always pass false, so a path never reaches channel metadata or
+ * public messages.
+ */
+export declare function describeWorkspace(entry: WorkspaceEntry, options: {
+    includePath: boolean;
+}): WorkspaceDetail;

package/lib/policy/disclosure.js

@@ -0,0 +1,153 @@
+/**
+ * Least-disclosure labels and output policy (amended design §3, 16.1).
+ * Workspace lists show titles disambiguated by short opaque id suffixes.
+ * Paths are not treated as sensitive for this self-hosted, trusted-Guild
+ * product: the canonical path renders in the ephemeral detail response and
+ * an abbreviated form may appear in autocomplete labels — but a path never
+ * reaches channel metadata or public (non-ephemeral) messages. User-controlled
+ * text is sanitized before it can forge Discord mentions or overflow
+ * component limits, and every outbound message carries
+ * `allowed_mentions: { parse: [] }` plus byte-wise syntax neutralization so
+ * assistant, tool, title, and error content can never ping anyone.
+ */
+import { homedir } from 'node:os';
+import { suppressMentionSyntax } from './suppress.js';
+/**
+ * path abbreviation (16.1): the user's home directory collapses
+ * to a `~` prefix — `/Users/addo/Workspaces/x` → `~/Workspaces/x` — so
+ * autocomplete labels stay short without hiding the directory structure.
+ * The home path must end at a segment boundary: `/Users/addoish/x` is NOT under `/Users/addo`. Display-only;
+ * never persisted to Discord metadata.
+ */
+export function abbreviatePath(fullPath, home = homedir()) {
+    if (fullPath === home)
+        return '~';
+    if (fullPath.startsWith(`${home}/`))
+        return `~${fullPath.slice(home.length)}`;
+    return fullPath;
+}
+/**
+ * Discord's SUPPRESS_NOTIFICATIONS message flag (1 << 12): the message will
+ * not trigger push/desktop notifications. This flag says nothing about
+ * mentions — ping prevention is the `allowed_mentions` request field below,
+ * and the syntax neutralization in policy/suppress.ts is the third layer.
+ */
+export const DISCORD_SUPPRESS_NOTIFICATIONS_FLAG = 1 << 12;
+/**
+ * Discord's request field that disables every mention parse category: with
+ * `parse: []` no `@everyone`, user, role, or channel mention in the content
+ * pings, regardless of how the content renders. Every message create/edit
+ * the adapter sends carries this.
+ */
+export const ALLOWED_MENTIONS_NONE = { parse: [] };
+/** Discord's ephemeral message flag (only the invoker sees the message). */
+export const DISCORD_EPHEMERAL_FLAG = 1 << 6;
+/** Ephemeral + silent: the standard adapter followup flags. */
+export const OUTBOUND_EPHEMERAL_FLAGS = DISCORD_EPHEMERAL_FLAG | DISCORD_SUPPRESS_NOTIFICATIONS_FLAG;
+/**
+ * The comparison key for Discord channel/thread names: Discord slugs names
+ * (lowercase, whitespace runs collapse to `-`), so a rename-dedupe check
+ * must compare both sides slugified or every restart burns a rename.
+ */
+export function discordChannelNameKey(text) {
+    return text.trim().toLowerCase().replace(/\s+/gu, '-');
+}
+/** Component label ceiling imposed by Discord. */
+const DISCORD_LABEL_MAX = 100;
+/** Length of the id tail used to disambiguate duplicate titles. */
+const DISAMBIGUATOR_TAIL = 4;
+function stripControlCharacters(text) {
+    let out = '';
+    for (const char of text) {
+        const code = char.charCodeAt(0);
+        if (code < 9 || (code > 13 && code < 32) || code === 127)
+            continue;
+        out += char;
+    }
+    return out;
+}
+function sanitizePart(text) {
+    return suppressMentionSyntax(stripControlCharacters(text)
+        .replace(/[\r\n]+/gu, ' ')
+        .replace(/ {2,}/gu, ' ')
+        .trim());
+}
+/**
+ * Sanitize user-controlled text for safe rendering as a label or title:
+ * control characters and line breaks collapse, mention syntax breaks, and
+ * Discord's component length ceiling applies.
+ */
+export function safeTitle(text, maxLength = DISCORD_LABEL_MAX) {
+    const cleaned = sanitizePart(text);
+    return cleaned.length <= maxLength ? cleaned : cleaned.slice(0, maxLength);
+}
+/**
+ * Label a Workspace list: unique titles stay bare; duplicate titles gain a
+ * short id suffix so every label stays unambiguous without exposing paths.
+ * Escalating suffix groups grow together (4 → 8 → … chars, then the full id)
+ * and stay deterministic.
+ */
+export function workspaceLabels(entries) {
+    const groups = new Map();
+    entries.forEach((entry, index) => {
+        const title = safeTitle(entry.title);
+        const group = groups.get(title) ?? [];
+        group.push(index);
+        groups.set(title, group);
+    });
+    const labels = new Array(entries.length);
+    for (const [title, indices] of groups) {
+        const single = indices[0];
+        if (indices.length === 1 && single !== undefined) {
+            labels[single] = title;
+            continue;
+        }
+        for (let tailLength = DISAMBIGUATOR_TAIL;; tailLength += DISAMBIGUATOR_TAIL) {
+            const tails = indices.map((index) => {
+                const id = entries[index]?.id ?? '';
+                return id.slice(-Math.min(tailLength, id.length));
+            });
+            const unique = new Set(tails).size === indices.length;
+            const atFullLength = indices.every(index => (entries[index]?.id.length ?? 0) <= tailLength);
+            if (unique || atFullLength) {
+                indices.forEach((index, position) => {
+                    const tail = tails[position] ?? '';
+                    labels[index] = `${title} (${tail})`;
+                });
+                break;
+            }
+        }
+    }
+    return entries.map((entry, index) => ({
+        id: entry.id,
+        title: safeTitle(entry.title),
+        label: labels[index] ?? safeTitle(entry.title),
+    }));
+}
+/** The opaque value a select option encodes for choosing this workspace. */
+export function workspaceReference(id) {
+    return `ws:${id}`;
+}
+/** The inverse of workspaceReference; `undefined` for any other string. */
+export function parseWorkspaceReference(reference) {
+    if (!reference.startsWith('ws:'))
+        return undefined;
+    const id = reference.slice(3);
+    return id === '' ? undefined : id;
+}
+/**
+ * Project one workspace for display. `includePath` is for the ephemeral
+ * detail response (any authorized member per amended design §3); list
+ * surfaces always pass false, so a path never reaches channel metadata or
+ * public messages.
+ */
+export function describeWorkspace(entry, options) {
+    const [labeled] = workspaceLabels([entry]);
+    const label = labeled?.label ?? safeTitle(entry.title);
+    return {
+        id: entry.id,
+        title: safeTitle(entry.title),
+        label,
+        ...(options.includePath && entry.path !== undefined ? { path: entry.path } : {}),
+    };
+}

package/lib/policy/guard.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The authorization middleware installed at the single normalized ingress
+ * boundary. Every event kind — messages, slash commands, autocomplete,
+ * buttons, selects, and modals — flows through this one gate, so no DSH
+ * access can precede authorization by construction: the business callback
+ * only fires with a positive, ranked decision attached. Ordinary messages
+ * deny silently; interactions deny with an explicit result the transport
+ * layer turns into an ephemeral reply.
+ */
+import { type AccessDecision, type PolicyTable } from './authorization.js';
+import { type NormalizedInboundEvent } from '../gateway/ingress.js';
+import type { DiscordSnowflake, GatewayDispatch } from '../gateway/inbound.js';
+export interface AuthorizedIngressOptions {
+    selfUserId: DiscordSnowflake;
+    /** Live policy reader so settings updates apply without re-installing. */
+    policy: () => PolicyTable;
+    /** The business boundary; only invoked with a positive decision. */
+    onEvent(event: NormalizedInboundEvent, decision: AccessDecision): void;
+}
+export type AuthorizedGateResult = {
+    accepted: true;
+    event: NormalizedInboundEvent;
+    decision: AccessDecision;
+} | {
+    accepted: false;
+    reason: string;
+    response: 'silent' | 'ephemeral-denial';
+};
+export declare function createAuthorizedIngress(options: AuthorizedIngressOptions): {
+    accept(dispatch: GatewayDispatch): AuthorizedGateResult;
+};

package/lib/policy/guard.js

@@ -0,0 +1,46 @@
+/**
+ * The authorization middleware installed at the single normalized ingress
+ * boundary. Every event kind — messages, slash commands, autocomplete,
+ * buttons, selects, and modals — flows through this one gate, so no DSH
+ * access can precede authorization by construction: the business callback
+ * only fires with a positive, ranked decision attached. Ordinary messages
+ * deny silently; interactions deny with an explicit result the transport
+ * layer turns into an ephemeral reply.
+ */
+import { evaluateAuthorization } from './authorization.js';
+import { normalizeInbound } from '../gateway/ingress.js';
+export function createAuthorizedIngress(options) {
+    const policyAt = () => options.policy();
+    function accept(dispatch) {
+        // 1. Normalization: malformed frames, DMs, bots, self-messages die here.
+        const result = normalizeInbound(dispatch, options.selfUserId);
+        if (!result.accepted) {
+            return { accepted: false, reason: result.reason, response: 'silent' };
+        }
+        // 2. Outer boundary: the Guild allowlist.
+        const event = result.event;
+        if (!policyAt().allowedGuildIds.includes(event.guildId)) {
+            return { accepted: false, reason: 'guild-not-allowed', response: 'silent' };
+        }
+        // 3. Inner boundary: deny-first member/administrator/operator evaluation.
+        const isMessage = event.kind === 'message';
+        const decision = evaluateAuthorization(policyAt(), {
+            guildId: event.guildId,
+            userId: isMessage ? event.authorId : event.actorId,
+            roleIds: event.roleIds,
+            memberPermissions: event.memberPermissions,
+            ...(isMessage ? {} : { isBot: event.isBot }),
+        });
+        if (!decision.allowed) {
+            return {
+                accepted: false,
+                reason: decision.reason,
+                // Interactions must answer (ephemeral denial); messages ignore.
+                response: isMessage ? 'silent' : 'ephemeral-denial',
+            };
+        }
+        options.onEvent(event, decision);
+        return { accepted: true, event, decision };
+    }
+    return { accept };
+}

package/lib/policy/suppress.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Mention-syntax neutralization for outbound text. Discord renders
+ * `<@id>`, `<@!id>`, `<#id>`, `<@&id>`, `@everyone`, and `@here` pings; the
+ * adapter's `allowed_mentions: { parse: [] }` request field stops them from
+ * notifying, but titles and labels can flow into surfaces the field does not
+ * cover (component labels, thread names, markdown contexts), so the syntax
+ * itself is broken with a zero-width space the renderer treats as plain text.
+ */
+/**
+ * Break every Discord mention form inside `text` so no renderer — with or
+ * without the suppression flag — can resolve it into a ping.
+ */
+export declare function suppressMentionSyntax(text: string): string;

package/lib/policy/suppress.js

@@ -0,0 +1,20 @@
+/**
+ * Mention-syntax neutralization for outbound text. Discord renders
+ * `<@id>`, `<@!id>`, `<#id>`, `<@&id>`, `@everyone`, and `@here` pings; the
+ * adapter's `allowed_mentions: { parse: [] }` request field stops them from
+ * notifying, but titles and labels can flow into surfaces the field does not
+ * cover (component labels, thread names, markdown contexts), so the syntax
+ * itself is broken with a zero-width space the renderer treats as plain text.
+ */
+const ZERO_WIDTH = '\u200b';
+/**
+ * Break every Discord mention form inside `text` so no renderer — with or
+ * without the suppression flag — can resolve it into a ping.
+ */
+export function suppressMentionSyntax(text) {
+    return text
+        .replace(/<@([!&]?)/gu, `<@$1${ZERO_WIDTH}`)
+        .replace(/<#/gu, `<#${ZERO_WIDTH}`)
+        .replaceAll('@everyone', `@${ZERO_WIDTH}everyone`)
+        .replaceAll('@here', `@${ZERO_WIDTH}here`);
+}

package/lib/settings-namespace.d.ts

@@ -0,0 +1,7 @@
+/** The plugin's settings namespace, shared by the Host registration and the
+ * browser card. Declared locally (not imported from `dsh-settings`) so the
+ * client bundle stays free of host-package value imports.
+ */
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
+/** The branded settings namespace, matching the Host plugin's registration. */
+export declare const DISCORD_SETTINGS_NAMESPACE: SettingsNamespace;

package/lib/settings-namespace.js

@@ -0,0 +1,6 @@
+/** The plugin's settings namespace, shared by the Host registration and the
+ * browser card. Declared locally (not imported from `dsh-settings`) so the
+ * client bundle stays free of host-package value imports.
+ */
+/** The branded settings namespace, matching the Host plugin's registration. */
+export const DISCORD_SETTINGS_NAMESPACE = 'dsh-discord';

package/lib/settings.d.ts

@@ -0,0 +1,37 @@
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+export { DISCORD_SETTINGS_NAMESPACE } from './settings-namespace.js';
+export type DiscordVerbosity = 'text-only' | 'essential-tools' | 'full-tools';
+/** Card language preference: follow the DSH locale, or pin Chinese/English. */
+export type Language = 'auto' | 'zh' | 'en';
+export interface DiscordSettings {
+    enabled: boolean;
+    allowedGuildIds: string[];
+    memberUserIds: string[];
+    memberRoleIds: string[];
+    administratorUserIds: string[];
+    administratorRoleIds: string[];
+    deniedUserIds: string[];
+    deniedRoleIds: string[];
+    hostOperatorUserIds: string[];
+    defaultVerbosity: DiscordVerbosity;
+    /** Discord-visible copy language for adapter messages (16.25). */
+    language: Language;
+    streamUpdateIntervalMs: number;
+    typingIntervalMs: number;
+    approvalTimeoutMs: number;
+    questionTimeoutMs: number;
+    /** Task-thread auto-archive; Discord supports exactly these four values. */
+    threadAutoArchiveMinutes: ThreadAutoArchiveMinutes;
+}
+/** The archive durations Discord's API accepts (minutes). */
+export type ThreadAutoArchiveMinutes = 60 | 1440 | 4320 | 10080;
+export declare const THREAD_AUTO_ARCHIVE_OPTIONS: readonly ThreadAutoArchiveMinutes[];
+export declare const DEFAULT_DISCORD_SETTINGS: DiscordSettings;
+export declare const DiscordSettingsSchema: z<DiscordSettings>;
+export declare function normalizeDiscordSettings(input: DiscordSettings): DiscordSettings;
+export declare function validateDiscordSettings(input: DiscordSettings): void;
+export interface DiscordSettingsSource {
+    get(): DiscordSettings;
+}
+export declare function installDiscordSettings(ctx: Context, entry: DiscordSettings, onChange: (value: DiscordSettings) => void): void;