@addozhang/dsh-discord 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 addozhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @addozhang/dsh-discord
+
+Discord-first adapter for [DeepSeek Harness](https://github.com/deepseek-ai) — run DSH sessions from a Discord guild: mention the bot to open a task thread, steer and stop turns, answer approvals and questions inline, and watch the answer stream in.
+
+## Features
+
+- **Mention-driven sessions** — an authorized `@bot <task>` in a bound channel anchors a thread (the author's message becomes the first post), creates the DSH session, and submits the prompt at most once. Follow-ups inside the thread queue without a mention.
+- **Stream rendering** — typing indicators, a single edited head message, per-tool activity rows, fenced long-answer splitting, one-time finalize; the activity message is deleted when the turn ends.
+- **Approvals & questions** — DSH ask frames become Discord buttons, select menus, and a free-text modal; ownership is enforced (the asker — or the thread owner on later turns — clicks), expiry sweeps fail closed, and remote resolution retires the controls.
+- **Session control** — `/steer`, `/stop`, `/queue list|remove` with turn-ownership checks; `/project bind|list|info` for guild↔workspace binding; `/guild forget` for operator cleanup.
+- **Settings card** — token onboarding (paste + Connect; stored in the Host credential service, never in settings or logs), connect/disconnect, guild allowlist, thread auto-archive, and bot language (follow the DSH language, or pin 中文/English).
+- **Bilingual copy** — every Discord-visible string ships in Chinese and English, selected live from the card.
+- **Hardened by design** — deny-first authorization inside an explicit guild allowlist, byte-level mention neutralization plus `allowed_mentions` on every wire body, at-most-once DSH submission with unknown-preserving reconciliation, and durable bindings that survive restarts.
+
+## Install
+
+The adapter runs as a DSH plugin bundle inside a web profile:
+
+```sh
+pnpm build && pnpm pack --pack-destination /tmp
+cd "$DSH_HOME/profiles/<your-profile>"
+pnpm add file:/tmp/addozhang-dsh-discord-0.1.0.tgz
+```
+
+and register it in the profile's `package.json`:
+
+```json
+{
+  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@addozhang/dsh-discord"] } }
+}
+```
+
+> Publishing to npm is pending (account unavailable). Until then, install from the packed tarball.
+
+## Setup
+
+1. Boot the profile and open the web UI.
+2. In **Settings → Discord**, paste the bot token (Discord Developer Portal → your application → Bot → Reset Token) and press **Connect**. The token is stored by the Host credential service — never in settings, logs, or the client.
+3. Fill in the allowed servers (server IDs via Discord's Developer Mode → right-click → Copy Server ID) and invite the bot to those guilds.
+4. Mention the bot in a bound channel to start a session.
+
+## Commands
+
+| Command | Where | What |
+|---|---|---|
+| `/project bind` | any channel | bind the guild to a workspace (admin; provisions the home channel) |
+| `/project list` / `info` | any channel | list workspaces / inspect this channel's binding |
+| `/queue list`, `/queue remove` | session thread | inspect and trim the pending queue |
+| `/steer`, `/stop` | session thread | steer or cancel the running turn (owner only) |
+| `/model`, `/preset`, `/skill` | per context | model/preset defaults and skill runs |
+| `/host status` | any channel | connection and version |
+| `/guild forget` | any channel | operator-only removal of adapter records |
+
+## Development
+
+```sh
+pnpm install --ignore-scripts
+pnpm test          # 642 tests incl. gateway/REST twin E2E
+pnpm typecheck
+pnpm lint
+pnpm build         # lib + client bundle
+```
+
+The implementation follows the OpenSpec change at `openspec/changes/build-discord-native-adapter/` (design, capability specs, verification checklist, review reports).
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# The dsh-discord bundle patch: mounts the embedded Discord adapter into the
+# Web profile's Host plugin tree. The row injects every required DSH service,
+# so activation waits until the Host provides them; the plugin's own startup
+# validation (task 1.3) fails loud when a dependency is present but
+# incompatible.
+#
+# The browser half is declared through this package's `dsh.client` manifest,
+# so the modules node half scans it into the browser roster automatically and
+# no client row is needed here.
+
+- insert:
+    - id: dsh-discord
+      name: '@addozhang/dsh-discord'
+      inject: [apiProxy, credentials, settings, storageDomain, connection]

package/lib/client/DiscordSettingsCard.d.ts

@@ -0,0 +1,6 @@
+/** The Discord adapter's plugin settings card: connection status, guild allowlist, and output behavior. */
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { DiscordCardFace } from './card-controller.js';
+/** Props the runtime binds for the Discord settings card. */
+export type DiscordSettingsCardProps = PropsRuntime<"settings.section"> & PropsLocale<'dsh-discord'> & InjectFace<DiscordCardFace>;
+export declare function DiscordSettingsCard(props: DiscordSettingsCardProps): import("react/jsx-runtime").JSX.Element | null;

package/lib/client/PluginCard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One plugin card's chrome: a disclosure header naming the plugin, the card's
+ * form state, and the save/discard footer. Disclosure is card-local reading
+ * state; staged edits outlive collapsing and mark the header unsaved.
+ */
+import { type ReactNode } from 'react';
+import type { CardShell } from './card-form.js';
+/** Copy keys the host settings section provides to every card. */
+export interface PluginCardCopy {
+    expand: string;
+    collapse: string;
+    unsaved: string;
+    readOnly: string;
+    saveFailed: string;
+    discard: string;
+    save: string;
+    saving: string;
+}
+/** Props for the Discord adapter's card chrome. */
+export interface PluginCardProps {
+    /** Card copy from the section locale. */
+    copy: PluginCardCopy;
+    /** Card title. */
+    title: string;
+    /** Monochrome mark rendered before the title. */
+    icon?: ReactNode;
+    /** Line describing what this card's settings govern. */
+    description: string;
+    /** The card's form state. */
+    state: CardShell;
+    /** Write every staged edit. */
+    onSave: () => void;
+    /** Drop every staged edit. */
+    onDiscard: () => void;
+    /** The plugin's controls. */
+    children: ReactNode;
+}
+/**
+ * Render the Discord adapter card chrome.
+ * @param props - the card's copy, state, and controls.
+ * @returns the card, or nothing when the namespace is unavailable.
+ */
+export declare function PluginCard(props: PluginCardProps): ReactNode;

package/lib/client/card-controller.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The card's registration-side controller. It owns the staged form over one
+ * bound settings scope and exposes the inject face the slot registration
+ * hands to the component: the edit actions plus the `discordCard` snapshot
+ * store the framework binds as the `useDiscordCard` selector hook.
+ */
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import type { AdapterStatusView } from '../features/adapter-status.js';
+import type { DiscordSettings } from '../settings.js';
+import { type CardManagement, type DiscordCardFace, type DiscordCardState } from './card-form.js';
+export declare class DiscordCardController {
+    private readonly form;
+    private management;
+    constructor(scope: SettingsScope<DiscordSettings>);
+    /** Attach the token write/connect path once the RPC face is known. */
+    setManagement(management: CardManagement): void;
+    /** Publish the Host's sanitized connection status onto the card. */
+    setStatus(view: AdapterStatusView | undefined): void;
+    /** Build the face the registration's inject factory returns per entry. */
+    face(): DiscordCardFace;
+}
+export type { DiscordCardFace, DiscordCardState };

package/lib/client/card-form.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The Discord card's staged form model.
+ *
+ * A card stages what the user types and writes it only on save. Each field
+ * shows its effective value and whether the user layer carries it — presence,
+ * not value comparison, marks an override. A field is invalid when its draft
+ * is not a list of Discord IDs, which blocks the save rather than dropping it.
+ */
+import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+import type { AdapterStatusView } from '../features/adapter-status.js';
+import type { DiscordSettings } from '../settings.js';
+import { type AdapterStatusPresentation } from './settings-model.js';
+/** One field as its control renders it. */
+export interface CardFieldState {
+    text: string;
+    overridden: boolean;
+    invalid: boolean;
+}
+/** Form state the card chrome shares. */
+export interface CardShell {
+    available: boolean;
+    writable: boolean;
+    dirty: boolean;
+    invalid: boolean;
+    saving: boolean;
+    failed: boolean;
+}
+/** The edit actions a card's slot entry injects. */
+export interface CardActions {
+    edit: (field: string, text: string) => void;
+    resetField: (field: string) => void;
+    save: () => void;
+    discard: () => void;
+}
+/** The ID list fields this card edits, in display order. */
+export declare const DISCORD_ID_FIELDS: readonly ["allowedGuildIds", "memberUserIds", "memberRoleIds", "administratorUserIds", "administratorRoleIds", "deniedUserIds", "deniedRoleIds", "hostOperatorUserIds"];
+/** The single-choice numeric field this card edits. */
+export declare const ARCHIVE_FIELD: "threadAutoArchiveMinutes";
+/** The adapter copy language field this card edits (16.25). */
+export declare const LANGUAGE_FIELD: "language";
+export type DiscordCardField = typeof DISCORD_ID_FIELDS[number] | typeof ARCHIVE_FIELD | typeof LANGUAGE_FIELD;
+/** The adapter copy languages, as select choices (labels are endonyms). */
+export declare const LANGUAGE_CHOICES: ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+/** The archive durations Discord accepts, as select choices. */
+export declare const ARCHIVE_CHOICES: ReadonlyArray<{
+    value: string;
+    label: string;
+}>;
+/** What the Discord card renders. */
+export type DiscordCardState = CardShell & Record<DiscordCardField, CardFieldState> & {
+    /** The Host's sanitized connection status, once reported. */
+    status: AdapterStatusPresentation | undefined;
+};
+/** The write path for the bot token and the connect trigger. The token
+ * value never enters card state — it flows client → Host over the plugin
+ * management channel and is stored in the credential service. */
+export interface CardManagement {
+    /** Store the token durably and refresh the credential status. */
+    setToken(value: string): Promise<void>;
+    /** Re-run the adapter start chain with the stored credential. */
+    connect(): void;
+    /** Operator-initiated offline; the stored credential is kept. */
+    disconnect(): void;
+    /** Pull the Host status now instead of waiting for the next poll. */
+    refresh(): void;
+}
+/** The registration-side face the Discord card's slot entry injects. */
+export interface DiscordCardFace extends CardActions {
+    hooks: {
+        /** Card snapshot bound by the renderer. */
+        discordCard: SnapshotStore<DiscordCardState>;
+    };
+    management?: CardManagement | undefined;
+}
+/**
+ * Stages the Discord card's ID-list edits over its settings namespace and
+ * writes them on save. Outcomes are read back from the namespace: the Host is
+ * the only authority on whether a value was accepted.
+ */
+export declare class DiscordCardForm {
+    private readonly scope;
+    private readonly staged;
+    private readonly listeners;
+    private saving;
+    private failed;
+    private status;
+    constructor(scope: SettingsScope<DiscordSettings>);
+    /**
+     * Publish the Host's sanitized status view. Edits, saves, and failures
+     * never touch it — connection state is the Host's report, not form state.
+     */
+    setStatus(view: AdapterStatusView | undefined): void;
+    /** Publish the card state the renderer reads through its bound selector. */
+    bind(): SnapshotStore<DiscordCardState>;
+    /** Build the edit, reset, save, and discard actions bound to this form. */
+    actions(): CardActions;
+    private project;
+    private fieldState;
+    private currentText;
+    private snapshot;
+    private userLayer;
+    private stored;
+    private plan;
+    private clear;
+    private store;
+    private save;
+    private publish;
+}

package/lib/client/fields.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hand-written control for the Discord settings card. It renders one field's
+ * label, staged text, override badge, and reset action. Nothing here writes:
+ * the card's save is the single point where a draft becomes a document write.
+ */
+import type { ReactNode } from 'react';
+export interface FieldProps {
+    /** Stable id associating the label with its control. */
+    id: string;
+    /** Visible label. */
+    label: string;
+    /** One-line explanation rendered under the control. */
+    hint: string;
+    /** Draft text this control renders. */
+    text: string;
+    /** True when saving would leave a user-layer entry for this field. */
+    overridden: boolean;
+    /** True when the draft is not a value this field accepts. */
+    invalid: boolean;
+    /** Copy for the overridden badge. */
+    overriddenLabel: string;
+    /** Copy for the reset control. */
+    resetLabel: string;
+    /** Copy shown in place of the hint while the draft is invalid. */
+    invalidLabel: string;
+    /** Disables the control while the document is read-only. */
+    disabled: boolean;
+    /** Stage draft text. */
+    onEdit: (text: string) => void;
+    /** Stage a clear so the field re-inherits the composition layer. */
+    onReset: () => void;
+}
+/** One choice in a SelectField. */
+export interface SelectOption {
+    value: string;
+    label: string;
+}
+/**
+ * A staged single-choice field (native select) sharing the ID field's
+ * head layout: label, override badge, reset, and a hint/invalid note.
+ */
+export declare function SelectField(props: FieldProps & {
+    options: readonly SelectOption[];
+}): ReactNode;
+/**
+ * A staged multi-line Discord ID field.
+ * @param props - the field's copy, its staged text, and the edit actions.
+ * @returns the labelled control.
+ */
+export declare function ValueField(props: FieldProps): ReactNode;

package/lib/client/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Discord adapter's browser half. It binds the plugin's settings
+ * namespace scope on its own fiber, owns the card controller, and registers
+ * the settings card into the Plugins section's tab list until unload.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** Stable Cordis plugin name for diagnostics. */
+export declare const name = "dsh-discord-client";
+/** Client services the card needs: settings transport, slot registry, plugin RPC channel, and locale. */
+export declare const inject: string[];
+/** Mount the Discord settings card into the Plugins section. */
+export declare function apply(ctx: ClientContext): void;

package/lib/client/nav-icon.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The settings navigation is Host-rendered: its per-section icon mapping
+ * (`navIcon(id)` in the general-settings bundle) knows only the built-in
+ * sections and falls back to a gear for every plugin-contributed entry, and
+ * the slot registration has no icon field. This shim watches for the nav cell
+ * whose label reads "Discord" and swaps its gear for the monochrome Discord
+ * mark, styled by the Host's own navIcon class. Idempotent: the replacement
+ * carries a data marker, so re-running the sweep after our own mutation is a
+ * no-op.
+ */
+import type { ReactNode } from 'react';
+/** The Discord mark, monochrome: it inherits the surrounding text color. */
+export declare function DiscordMark({ size }: {
+    size?: number;
+}): ReactNode;
+/**
+ * Install the nav-icon shim and keep it applied while the settings dialog
+ * mounts and re-renders.
+ * @returns the disposer releasing the mutation observer.
+ */
+export declare function installDiscordNavIcon(): () => void;

package/lib/client/settings-model.d.ts

@@ -0,0 +1,49 @@
+import type { AdapterStatusView } from '../features/adapter-status.js';
+import type { DiscordSettings } from '../settings.js';
+export interface DiscordSettingsDraft {
+    enabled: boolean;
+    allowedGuildIds: string;
+    memberUserIds: string;
+    memberRoleIds: string;
+    administratorUserIds: string;
+    administratorRoleIds: string;
+    deniedUserIds: string;
+    deniedRoleIds: string;
+    hostOperatorUserIds: string;
+    defaultVerbosity: DiscordSettings['defaultVerbosity'];
+    language: DiscordSettings['language'];
+    threadAutoArchiveMinutes: DiscordSettings['threadAutoArchiveMinutes'];
+    streamUpdateIntervalMs: number;
+    typingIntervalMs: number;
+    approvalTimeoutMs: number;
+    questionTimeoutMs: number;
+}
+export declare function serializeIdList(value: string): string[];
+export declare function createSettingsDraft(value: Partial<DiscordSettings>): DiscordSettingsDraft;
+export declare function presentCredentialStatus(info: {
+    configured: boolean;
+    writable: boolean;
+    source?: string;
+}): {
+    label: string;
+    writable: boolean;
+    source?: string;
+};
+/** The card status line's presentation: locale keys plus an action flag. */
+export interface AdapterStatusPresentation {
+    connectionKey: DiscordStatusConnectionKey;
+    hintKey?: DiscordStatusHintKey | undefined;
+    actionable: boolean;
+    /** Whether the credential service already holds a token. */
+    tokenConfigured: boolean;
+}
+/** Locale keys the card renders for each connection condition. */
+export type DiscordStatusConnectionKey = 'discordStatusConnected' | 'discordStatusConnecting' | 'discordStatusDisconnected' | 'discordStatusInvalidToken' | 'discordStatusIntentsBlocked' | 'discordStatusPermissionsBlocked';
+/** Locale keys for each actionable hint the Host can send. */
+export type DiscordStatusHintKey = 'discordHintConfigureToken' | 'discordHintTokenRejected' | 'discordHintEnableIntents' | 'discordHintGatewayClosed' | 'discordHintChannelPermissions';
+/**
+ * Distill the Host's sanitized status view into the card's copy keys. The
+ * projection never carries secrets; this mapping adds none either — only
+ * stable locale keys and whether the condition demands user action.
+ */
+export declare function presentAdapterStatus(view: AdapterStatusView): AdapterStatusPresentation;

package/lib/client/slot-contract.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The settings surface's slot and locale contracts this card consumes. The
+ * slot entry types come from the settings domain base (`dsh-client-ui-settings`,
+ * the canonical home of every settings slot type); this module adds the
+ * locale namespace the Discord card's copy lives in. Importing it is what
+ * merges the declarations into this program.
+ */
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'dsh-discord': keyof DiscordPluginsLocale;
+    }
+}
+/** Copy keys the Discord card renders; every key must have a dictionary entry. */
+interface DiscordPluginsLocale {
+    discordTitle: string;
+    discordDescription: string;
+    discordAllowedGuildIds: string;
+    discordGuildIdHelp: string;
+    discordLanguageAuto: string;
+    discordTokenLabel: string;
+    discordTokenPlaceholder: string;
+    discordTokenConnect: string;
+    discordTokenConnecting: string;
+    discordTokenHelp: string;
+    discordTokenSaved: string;
+    discordTokenReconnectHint: string;
+    discordDisconnect: string;
+    discordThreadAutoArchive: string;
+    discordThreadAutoArchiveHint: string;
+    discordLanguage: string;
+    discordLanguageHint: string;
+    discordInvalidLanguage: string;
+    discordInvalidIds: string;
+    discordInvalidArchive: string;
+    discordStatusConnected: string;
+    discordStatusConnecting: string;
+    discordStatusDisconnected: string;
+    discordStatusInvalidToken: string;
+    discordStatusIntentsBlocked: string;
+    discordStatusPermissionsBlocked: string;
+    discordHintConfigureToken: string;
+    discordHintTokenRejected: string;
+    discordHintEnableIntents: string;
+    discordHintGatewayClosed: string;
+    discordHintChannelPermissions: string;
+    reset: string;
+    expand: string;
+    collapse: string;
+    unsaved: string;
+    readOnly: string;
+    saveFailed: string;
+    discard: string;
+    save: string;
+    saving: string;
+    overridden: string;
+}
+export {};

package/lib/client/snapshot-store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal snapshot store matching the client runtime's `SnapshotStore`
+ * contract. The runtime's `/client` artifact is a browser-only lazy-CJS
+ * factory, so the card implements the same interface locally and imports the
+ * contract type only.
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+/** Create an immutable-snapshot store with synchronous notification. */
+export declare function createLocalSnapshotStore<T>(initial: T): SnapshotStore<T>;