@addozhang/dsh-discord 0.1.0

package/lib/features/turn-ownership.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Adapter-owned active Turn tracking (design.md §6, task 9.4). Discord owns a
+ * Turn only through its durable submitted request ID — a session that is
+ * merely running (DSH Web, an external submitter) grants no control. The
+ * tracker keeps one active turn per session: later submissions queue without
+ * taking ownership, and a completed turn stops being controllable until the
+ * next adapter submission registers.
+ */
+export interface RegisteredTurn {
+    sessionId: string;
+    requestId: string;
+    threadId: string;
+}
+export type RegisterResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: 'turn-already-active';
+};
+export type ControlDecision = {
+    allowed: true;
+    requestId: string;
+} | {
+    allowed: false;
+    reason: 'not-adapter-owned' | 'no-active-turn';
+};
+export interface TurnTracker {
+    register(turn: RegisteredTurn): RegisterResult;
+    complete(requestId: string): void;
+    authorizeControl(input: {
+        sessionId: string;
+        threadId: string;
+        /** Whether DSH reports the session as running; running alone grants nothing. */
+        sessionRunning?: boolean | undefined;
+    }): ControlDecision;
+    /** The active turn for a session, if the adapter owns one. */
+    active(sessionId: string): RegisteredTurn | undefined;
+}
+export declare function createTurnTracker(): TurnTracker;

package/lib/features/turn-ownership.js

@@ -0,0 +1,40 @@
+/**
+ * Adapter-owned active Turn tracking (design.md §6, task 9.4). Discord owns a
+ * Turn only through its durable submitted request ID — a session that is
+ * merely running (DSH Web, an external submitter) grants no control. The
+ * tracker keeps one active turn per session: later submissions queue without
+ * taking ownership, and a completed turn stops being controllable until the
+ * next adapter submission registers.
+ */
+export function createTurnTracker() {
+    const activeTurns = new Map();
+    return {
+        register(turn) {
+            const existing = activeTurns.get(turn.sessionId);
+            if (existing !== undefined)
+                return { ok: false, error: 'turn-already-active' };
+            activeTurns.set(turn.sessionId, turn);
+            return { ok: true };
+        },
+        complete(requestId) {
+            for (const [sessionId, turn] of activeTurns) {
+                if (turn.requestId === requestId)
+                    activeTurns.delete(sessionId);
+            }
+        },
+        authorizeControl({ sessionId, threadId, sessionRunning }) {
+            const turn = activeTurns.get(sessionId);
+            if (turn === undefined) {
+                // A running session the adapter never submitted belongs to someone
+                // else (DSH Web); with no turn at all there is simply nothing to control.
+                return sessionRunning === true
+                    ? { allowed: false, reason: 'not-adapter-owned' }
+                    : { allowed: false, reason: 'no-active-turn' };
+            }
+            if (turn.threadId !== threadId)
+                return { allowed: false, reason: 'not-adapter-owned' };
+            return { allowed: true, requestId: turn.requestId };
+        },
+        active: sessionId => activeTurns.get(sessionId),
+    };
+}

package/lib/features/unbound-mention.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Unbound-channel mentions and Workspace creation (design.md §4, Non-Goals).
+ * A mention in an unbound channel never creates a Session: it answers with an
+ * ephemeral bind affordance whose guidance depends on the actor's authority.
+ * Workspace creation is a Milestone-1 non-goal, so the request is refused
+ * explicitly — the filesystem port exists only to prove no mutation can
+ * happen, and the refusal is ephemeral like every other denial.
+ */
+import type { AccessDecision } from '../policy/authorization.js';
+/** What the unbound-mention handler should render. */
+export type UnboundMentionPlan = {
+    outcome: 'bind-affordance';
+    audience: 'administrator' | 'member';
+} | {
+    outcome: 'none';
+};
+/**
+ * Decide the response for a mention arriving on an unbound channel. Denied
+ * and non-granted actors were already refused upstream; for them (and for
+ * bound channels) there is nothing to add.
+ */
+export declare function planUnboundMention(input: {
+    decision: AccessDecision;
+    isBound: boolean;
+}): UnboundMentionPlan;
+/**
+ * The filesystem-shaped surface the creation flow WOULD use. Declared only so
+ * the refusal can be tested against it: an implementation reaching for the
+ * filesystem is a spec violation.
+ */
+export interface FilesystemPort {
+    stat(path: string): Promise<unknown>;
+    mkdir(path: string): Promise<unknown>;
+}
+export type WorkspaceCreationResult = {
+    outcome: 'refused';
+    reason: 'workspace-creation-unavailable';
+    response: 'ephemeral';
+};
+/**
+ * Milestone 1 never creates directories or registers new Workspaces: refuse
+ * explicitly, touch nothing, and answer ephemerally.
+ */
+export declare function planWorkspaceCreation(_request: {
+    requestedPath: string;
+    actorId: string;
+}, deps: {
+    filesystem: FilesystemPort;
+}): Promise<WorkspaceCreationResult>;

package/lib/features/unbound-mention.js

@@ -0,0 +1,31 @@
+/**
+ * Unbound-channel mentions and Workspace creation (design.md §4, Non-Goals).
+ * A mention in an unbound channel never creates a Session: it answers with an
+ * ephemeral bind affordance whose guidance depends on the actor's authority.
+ * Workspace creation is a Milestone-1 non-goal, so the request is refused
+ * explicitly — the filesystem port exists only to prove no mutation can
+ * happen, and the refusal is ephemeral like every other denial.
+ */
+/**
+ * Decide the response for a mention arriving on an unbound channel. Denied
+ * and non-granted actors were already refused upstream; for them (and for
+ * bound channels) there is nothing to add.
+ */
+export function planUnboundMention(input) {
+    if (input.isBound)
+        return { outcome: 'none' };
+    if (!input.decision.allowed)
+        return { outcome: 'none' };
+    return {
+        outcome: 'bind-affordance',
+        audience: input.decision.level === 'member' ? 'member' : 'administrator',
+    };
+}
+/**
+ * Milestone 1 never creates directories or registers new Workspaces: refuse
+ * explicitly, touch nothing, and answer ephemerally.
+ */
+export function planWorkspaceCreation(_request, deps) {
+    void deps.filesystem;
+    return Promise.resolve({ outcome: 'refused', reason: 'workspace-creation-unavailable', response: 'ephemeral' });
+}

package/lib/features/workspace-channel.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-workspace Discord channel naming and placement (design.md §4). A
+ * successful bind may provision the workspace's home channel under the
+ * adapter's category. The name is a Discord-safe slug of the Workspace
+ * display title (never a path); placement reuses a same-name channel only
+ * when it is unbound or already serves this Workspace — a channel bound to
+ * another Workspace is never stolen, a suffixed sibling is created instead.
+ */
+/** Discord text-channel name: lowercase letters, digits, hyphen, underscore. */
+export declare function workspaceChannelName(title: string): string;
+/** How the existing binding relates to the Workspace being bound. */
+export type ChannelBindingState = 'unbound' | 'this-workspace' | 'other-workspace';
+export type WorkspaceChannelPlacement = {
+    outcome: 'reuse';
+    channelId: string;
+    needsBind: boolean;
+} | {
+    outcome: 'create';
+    name: string;
+};
+export interface WorkspaceChannelCandidate {
+    id: string;
+    name: string;
+    parentId: string | undefined;
+}
+/**
+ * Decide create-vs-reuse for the workspace channel, add-project
+ * style. The Workspace's existing home channel (any channel of this guild
+ * already bound to this Workspace) wins outright: reuse without rebinding —
+ * one Workspace, one channel. Otherwise a same-name channel under the
+ * category is reused only when unbound; a channel serving another Workspace
+ * is never stolen, and a `-2` sibling is created instead.
+ */
+export declare function planWorkspaceChannel(options: {
+    channels: ReadonlyArray<WorkspaceChannelCandidate>;
+    categoryId: string;
+    desiredName: string;
+    bindingOf: (channelId: string) => ChannelBindingState;
+    /** A channel of this guild already bound to this Workspace, when known. */
+    existingForWorkspace?: string | undefined;
+}): WorkspaceChannelPlacement;

package/lib/features/workspace-channel.js

@@ -0,0 +1,47 @@
+/**
+ * Per-workspace Discord channel naming and placement (design.md §4). A
+ * successful bind may provision the workspace's home channel under the
+ * adapter's category. The name is a Discord-safe slug of the Workspace
+ * display title (never a path); placement reuses a same-name channel only
+ * when it is unbound or already serves this Workspace — a channel bound to
+ * another Workspace is never stolen, a suffixed sibling is created instead.
+ */
+/** Discord text-channel name: lowercase letters, digits, hyphen, underscore. */
+export function workspaceChannelName(title) {
+    const trimmed = title.trim();
+    const slug = trimmed
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-_]+|[-_]+$/g, '')
+        .slice(0, 90)
+        .replace(/[-_]+$/g, '');
+    // Non-ASCII titles slugify to nothing; the raw title is Discord-legal and
+    // preserves the name a user actually chose.
+    return slug === '' ? trimmed.slice(0, 90) : slug;
+}
+/**
+ * Decide create-vs-reuse for the workspace channel, add-project
+ * style. The Workspace's existing home channel (any channel of this guild
+ * already bound to this Workspace) wins outright: reuse without rebinding —
+ * one Workspace, one channel. Otherwise a same-name channel under the
+ * category is reused only when unbound; a channel serving another Workspace
+ * is never stolen, and a `-2` sibling is created instead.
+ */
+export function planWorkspaceChannel(options) {
+    if (options.existingForWorkspace !== undefined) {
+        return { outcome: 'reuse', channelId: options.existingForWorkspace, needsBind: false };
+    }
+    const sameName = options.channels.filter(channel => channel.parentId === options.categoryId && channel.name === options.desiredName);
+    const reusable = sameName.find(channel => options.bindingOf(channel.id) !== 'other-workspace');
+    if (reusable !== undefined) {
+        return {
+            outcome: 'reuse',
+            channelId: reusable.id,
+            needsBind: options.bindingOf(reusable.id) === 'unbound',
+        };
+    }
+    if (sameName.length === 0)
+        return { outcome: 'create', name: options.desiredName };
+    return { outcome: 'create', name: `${options.desiredName}-2` };
+}

package/lib/gateway/gateway.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The Discord Gateway state machine, driven entirely through an injected
+ * socket factory so every behavior is testable with fake sockets and fake
+ * clocks. One instance owns at most one live socket; every generation change
+ * (reconnect or replacement) invalidates all callbacks captured by the
+ * previous socket, so a stale close can never schedule duplicate reconnects
+ * or deliver events after disposal.
+ */
+/** The subset of the WebSocket face the machine uses. */
+export interface GatewaySocket {
+    readonly url: string;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    terminate(): void;
+    onopen: (() => void) | null;
+    onmessage: ((data: string) => void) | null;
+    onclose: ((code: number) => void) | null;
+    onerror: ((error: Error) => void) | null;
+}
+export type GatewaySocketFactory = (url: string) => GatewaySocket;
+/** One forwarded Gateway dispatch frame (opcode 0). */
+export interface GatewayDispatch {
+    t: string;
+    s: number | null;
+    op: number;
+    d: unknown;
+}
+export interface GatewayOptions {
+    url: string;
+    /** Resolved per connection attempt; never retained between attempts. */
+    tokenProvider: () => Promise<string>;
+    /** Gateway intent bitmask to identify with. */
+    intents: number;
+    socketFactory: GatewaySocketFactory;
+    /** Every validated opcode-0 dispatch, including READY. */
+    onDispatch(event: GatewayDispatch): void;
+    /** A terminal close code was received; the machine will not reconnect. */
+    onTerminalClose(code: number): void;
+    /** A reconnect was scheduled; attempt is 1-based. */
+    onBackoffScheduled?(attempt: number, delayMs: number): void;
+    /** First retry delay; doubles per attempt up to `backoffCapMs`. */
+    backoffBaseMs?: number;
+    backoffCapMs?: number;
+}
+/** Close codes Discord defines as non-recoverable for this session shape. */
+export declare const TERMINAL_CLOSE_CODES: readonly number[];
+export interface GatewayHandle {
+    dispose(): void;
+}
+export declare function startGateway(options: GatewayOptions): GatewayHandle;

package/lib/gateway/gateway.js

@@ -0,0 +1,229 @@
+/**
+ * The Discord Gateway state machine, driven entirely through an injected
+ * socket factory so every behavior is testable with fake sockets and fake
+ * clocks. One instance owns at most one live socket; every generation change
+ * (reconnect or replacement) invalidates all callbacks captured by the
+ * previous socket, so a stale close can never schedule duplicate reconnects
+ * or deliver events after disposal.
+ */
+/** Close codes Discord defines as non-recoverable for this session shape. */
+export const TERMINAL_CLOSE_CODES = [4004, 4010, 4011, 4012, 4013, 4014];
+const OPCODE_DISPATCH = 0;
+const OPCODE_HEARTBEAT = 1;
+const OPCODE_IDENTIFY = 2;
+const OPCODE_RESUME = 6;
+const OPCODE_RECONNECT = 7;
+const OPCODE_INVALID_SESSION = 9;
+const OPCODE_HELLO = 10;
+const OPCODE_HEARTBEAT_ACK = 11;
+/** A recoverable close code: Discord allows session resume. */
+const RECOVERABLE_CLOSE = 4000;
+/**
+ * Grace period after a heartbeat-miss `terminate()`. The production socket
+ * adapter terminates via a graceful close handshake, which a partitioned
+ * peer never answers — without this fallback the machine would sit silently
+ * dead with no onclose and no reconnect.
+ */
+const TERMINATE_FALLBACK_MS = 5_000;
+export function startGateway(options) {
+    const backoffBaseMs = options.backoffBaseMs ?? 1_000;
+    const backoffCapMs = options.backoffCapMs ?? 60_000;
+    let disposed = false;
+    let generation = 0;
+    let heartbeatTimer;
+    let reconnectTimer;
+    let terminateFallbackTimer;
+    let heartbeatAcked = true;
+    let lastSeq = null;
+    let sessionId;
+    let backoffAttempt = 0;
+    let currentSocket;
+    function clearTimers() {
+        if (heartbeatTimer !== undefined) {
+            clearInterval(heartbeatTimer);
+            heartbeatTimer = undefined;
+        }
+        if (reconnectTimer !== undefined) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = undefined;
+        }
+        if (terminateFallbackTimer !== undefined) {
+            clearTimeout(terminateFallbackTimer);
+            terminateFallbackTimer = undefined;
+        }
+    }
+    function send(socket, op, d) {
+        socket.send(JSON.stringify({ op, d }));
+    }
+    function connect() {
+        if (disposed)
+            return;
+        generation += 1;
+        const liveGeneration = generation;
+        heartbeatAcked = true;
+        void options.tokenProvider().then((token) => {
+            if (disposed || liveGeneration !== generation)
+                return;
+            const socket = options.socketFactory(options.url);
+            currentSocket = socket;
+            socket.onopen = () => {
+                if (disposed || liveGeneration !== generation)
+                    return;
+            };
+            socket.onmessage = (data) => {
+                if (disposed || liveGeneration !== generation)
+                    return;
+                handleFrame(socket, data, token, liveGeneration);
+            };
+            socket.onclose = (code) => {
+                if (disposed || liveGeneration !== generation)
+                    return;
+                handleClose(code);
+            };
+            socket.onerror = () => {
+                if (disposed || liveGeneration !== generation)
+                    return;
+                // The close frame follows with the real code; nothing to do here.
+            };
+        }).catch(() => {
+            // Token resolution failed: recoverable, retry through the same backoff.
+            if (disposed || liveGeneration !== generation)
+                return;
+            handleClose(RECOVERABLE_CLOSE);
+        });
+    }
+    function handleFrame(socket, data, token, liveGeneration) {
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed !== 'object' || parsed === null)
+            return;
+        const frame = parsed;
+        if (typeof frame['op'] !== 'number')
+            return;
+        switch (frame['op']) {
+            case OPCODE_HELLO: {
+                const hello = frame['d'];
+                if (typeof hello !== 'object' || hello === null)
+                    return;
+                const interval = hello['heartbeat_interval'];
+                if (typeof interval !== 'number' || interval <= 0)
+                    return;
+                heartbeatAcked = true;
+                // A resumed session re-receives HELLO: retire the old timer first so
+                // intervals never stack.
+                if (heartbeatTimer !== undefined)
+                    clearInterval(heartbeatTimer);
+                heartbeatTimer = setInterval(() => {
+                    if (disposed || liveGeneration !== generation)
+                        return;
+                    if (!heartbeatAcked) {
+                        currentSocket?.terminate();
+                        // The adapter's terminate may be a graceful close, which a dead
+                        // peer never answers — onclose can then stay silent for minutes.
+                        // Arm a one-shot fallback so the reconnect machinery runs
+                        // regardless of socket-adapter behavior.
+                        if (terminateFallbackTimer === undefined) {
+                            terminateFallbackTimer = setTimeout(() => {
+                                terminateFallbackTimer = undefined;
+                                if (disposed || liveGeneration !== generation)
+                                    return;
+                                if (currentSocket === socket)
+                                    handleClose(RECOVERABLE_CLOSE);
+                            }, TERMINATE_FALLBACK_MS);
+                        }
+                        return;
+                    }
+                    heartbeatAcked = false;
+                    send(socket, OPCODE_HEARTBEAT, lastSeq);
+                }, interval);
+                if (sessionId !== undefined) {
+                    send(socket, OPCODE_RESUME, { token, session_id: sessionId, seq: lastSeq });
+                }
+                else {
+                    // Discord rejects an IDENTIFY without the properties block (op 9
+                    // invalid session → close 4000): os/browser/device are required.
+                    send(socket, OPCODE_IDENTIFY, {
+                        token,
+                        intents: options.intents,
+                        properties: { os: 'linux', browser: 'dsh-discord', device: 'dsh-discord' },
+                    });
+                }
+                return;
+            }
+            case OPCODE_HEARTBEAT_ACK: {
+                heartbeatAcked = true;
+                return;
+            }
+            case OPCODE_DISPATCH: {
+                const seq = frame['s'];
+                if (typeof seq === 'number')
+                    lastSeq = seq;
+                const type = frame['t'];
+                const payload = frame['d'];
+                if (type === 'READY' && typeof payload === 'object' && payload !== null) {
+                    const id = payload['session_id'];
+                    if (typeof id === 'string')
+                        sessionId = id;
+                    backoffAttempt = 0;
+                }
+                options.onDispatch({
+                    t: typeof type === 'string' ? type : '',
+                    s: typeof seq === 'number' ? seq : null,
+                    op: OPCODE_DISPATCH,
+                    d: payload,
+                });
+                return;
+            }
+            case OPCODE_RECONNECT: {
+                // Server-requested recycle: closing drives the resume path.
+                currentSocket?.close(RECOVERABLE_CLOSE);
+                return;
+            }
+            case OPCODE_INVALID_SESSION: {
+                if (frame['d'] !== true) {
+                    // Not resumable: forget the session so the next HELLO identifies fresh.
+                    sessionId = undefined;
+                    lastSeq = null;
+                }
+                // Discord closes the socket right after op 9; that close reconnects.
+                currentSocket?.close(RECOVERABLE_CLOSE);
+                return;
+            }
+            default:
+        }
+    }
+    function handleClose(code) {
+        console.error('[dsh-discord] gateway close:', code);
+        clearTimers();
+        if (disposed)
+            return;
+        if (TERMINAL_CLOSE_CODES.includes(code)) {
+            options.onTerminalClose(code);
+            return;
+        }
+        backoffAttempt += 1;
+        const delayMs = Math.min(backoffBaseMs * 2 ** (backoffAttempt - 1), backoffCapMs);
+        options.onBackoffScheduled?.(backoffAttempt, delayMs);
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            connect();
+        }, delayMs);
+    }
+    connect();
+    return {
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearTimers();
+            generation += 1;
+            currentSocket?.close(1000, 'plugin disposal');
+            currentSocket = undefined;
+        },
+    };
+}

package/lib/gateway/inbound.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Normalized inbound Gateway events. Every Discord dispatch this module
+ * accepts is untrusted wire data: validation failures are values, never
+ * throws, so one malformed payload can never break the dispatch loop. Only
+ * guild-scoped events the adapter understands survive this boundary; DMs and
+ * foreign event shapes are rejected here, before any business logic runs.
+ */
+/** A Discord snowflake-shaped string. */
+export type DiscordSnowflake = string;
+/** Validate the snowflake shape of an untrusted string. */
+export declare function isDiscordSnowflake(value: unknown): value is DiscordSnowflake;
+/** Raw untrusted dispatch: an event name plus its unvalidated payload. */
+export interface GatewayDispatch {
+    t: string;
+    d?: unknown;
+}
+/** Why a dispatch was rejected; discrimination keeps rejection handling total. */
+export type IngestRejectReason = 'unsupported-event' | 'malformed-payload' | 'bot-authored' | 'non-guild-event';
+export type IngestResult = {
+    accepted: true;
+    event: NormalizedMessage | NormalizedInteraction;
+} | {
+    accepted: false;
+    reason: IngestRejectReason;
+};
+/** A validated guild message with its mention-stripped content. */
+export interface NormalizedMessage {
+    kind: 'message';
+    messageId: DiscordSnowflake;
+    guildId: DiscordSnowflake;
+    channelId: DiscordSnowflake;
+    authorId: DiscordSnowflake;
+    /** Role ids the wire attached to the member (empty when absent). */
+    roleIds: string[];
+    /** Permission bitmask string from the member, when the wire carried one. */
+    memberPermissions: string | undefined;
+    /** Content after stripping every bot-mention token and trimming. */
+    content: string;
+    /** Whether the message explicitly mentioned the adapter's bot user. */
+    mentionedBot: boolean;
+    /** The snowflake of the message this one replies to, when present and valid. */
+    repliedToId: DiscordSnowflake | undefined;
+}
+/** A validated guild interaction with its actor identity. */
+export interface NormalizedInteraction {
+    kind: 'interaction';
+    interactionId: DiscordSnowflake;
+    /** Discord interaction type (2=command, 3=component, 4=autocomplete, 5=modal). */
+    interactionType: number;
+    guildId: DiscordSnowflake;
+    channelId: DiscordSnowflake;
+    actorId: DiscordSnowflake;
+    roleIds: string[];
+    /** Permission bitmask string from the member, when the wire carried one. */
+    memberPermissions: string | undefined;
+    /** The component interaction's parent message (control editing). */
+    componentMessageId: string | undefined;
+    /** Select-menu values (string selects only). */
+    selectValues: string[];
+    /** Modal text fields, flattened from the action rows (custom_id + value). */
+    modalFields: Array<{
+        customId: string;
+        value: string;
+    }>;
+    /** Whether the invoking user is itself a bot; such invocations are denied. */
+    isBot: boolean;
+    /** Slash-command name for command/autocomplete interactions, when present. */
+    commandName: string | undefined;
+    /** The opaque interaction data table, normalized for downstream routing. */
+    data: Record<string, unknown>;
+}
+/**
+ * Detect and strip the adapter's own mention (`<@id>` or `<@!id>`) from
+ * message content. Other users' mentions are left intact; a mention-only
+ * message yields empty text.
+ */
+export declare function extractBotMention(content: string, selfUserId: DiscordSnowflake): {
+    mentioned: boolean;
+    text: string;
+};
+/**
+ * Validate and normalize one untrusted Gateway dispatch. Returns a rejection
+ * value for every unsupported or malformed input and never throws.
+ */
+export declare function parseGatewayDispatch(dispatch: GatewayDispatch, selfUserId: DiscordSnowflake): IngestResult;