@addozhang/dsh-discord 0.1.0

package/lib/stream/markdown.js

@@ -0,0 +1,95 @@
+/**
+ * Markdown-aware splitting (design.md §8, task 11.6). Fenced code blocks stay
+ * balanced across chunk boundaries: a cut inside a fence closes it at the end
+ * of the earlier chunk and reopens it — same language — at the top of the
+ * next. Output ending inside a fence gets the fence closed. GFM tables are
+ * wrapped into fences (wrapGfmTables) before splitting, so they ride the
+ * same balance guarantee.
+ */
+import { splitMessage } from './splitter.js';
+const FENCE_PATTERN = /^\s*(```[a-zA-Z0-9_-]*)\s*$/u;
+/** Append a closing fence when `text` ends inside an open block. */
+export function closeOpenFences(text) {
+    const lines = text.split('\n');
+    let open = false;
+    for (const line of lines) {
+        if (FENCE_PATTERN.test(line))
+            open = !open;
+    }
+    return open ? `${text}\n\`\`\`` : text;
+}
+function rebalanceChunk(chunk, state) {
+    const lines = chunk.split('\n');
+    const out = [];
+    if (state.open !== '') {
+        out.push(state.open);
+    }
+    for (const line of lines) {
+        if (state.open !== '') {
+            out.push(line);
+            if (line.trim() === '```') {
+                state.open = '';
+            }
+            continue;
+        }
+        const match = FENCE_PATTERN.exec(line);
+        if (match !== null) {
+            state.open = match[1] ?? '```';
+        }
+        out.push(line);
+    }
+    if (state.open !== '') {
+        out.push('```');
+    }
+    return out.join('\n');
+}
+/**
+ * Split like the base splitter, then rebalance fences across chunks: each
+ * chunk renders as well-formed Markdown on its own, and fence language
+ * markers survive the boundary.
+ */
+export function splitMarkdownAware(text, limit) {
+    const base = splitMessage(text, limit);
+    const state = { open: '' };
+    const rebalanced = base.map(chunk => rebalanceChunk(chunk, state));
+    return rebalanced.filter(chunk => chunk.trim() !== '');
+}
+const TABLE_DELIMITER_ROW = /^\s*\|(\s*:?-{3,}:?\s*\|)+\s*$/u;
+function isTableRow(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith('|') && trimmed.endsWith('|');
+}
+/**
+ * Discord does not render GFM tables: raw pipe rows collapse into ragged
+ * text. A table region outside any fence — a header row, a delimiter row,
+ * then body rows — is wrapped in a fence so Discord renders it as aligned
+ * monospace. Regions inside fences are left untouched, and the resulting
+ * fences are ordinary balanced fences to the splitter.
+ */
+export function wrapGfmTables(text) {
+    const lines = text.split('\n');
+    const out = [];
+    let inFence = false;
+    let index = 0;
+    while (index < lines.length) {
+        const line = lines[index] ?? '';
+        if (FENCE_PATTERN.test(line)) {
+            inFence = !inFence;
+            out.push(line);
+            index += 1;
+            continue;
+        }
+        if (!inFence && isTableRow(line)
+            && TABLE_DELIMITER_ROW.test(lines[index + 1] ?? '')) {
+            let end = index;
+            while (end < lines.length && isTableRow(lines[end] ?? ''))
+                end += 1;
+            out.push('```', ...lines.slice(index, end), '```');
+            index = end;
+            continue;
+        }
+        out.push(line);
+        index += 1;
+    }
+    return out.join('\n');
+}

package/lib/stream/outbound.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The single outbound message builder (design.md §8, task 11.7). Every
+ * message path — assistant answers, tool views, titles, errors — constructs
+ * its payload here, where mention prevention is layered three ways: the
+ * `allowed_mentions: { parse: [] }` request field (the API-level guarantee),
+ * silent-delivery flags, and byte-wise syntax neutralization, so a renderer
+ * that bypassed one layer still could not resolve a ping.
+ */
+/** Discord message flags the adapter always sets (silent delivery). */
+export declare const OUTBOUND_MESSAGE_FLAGS: number;
+export type OutboundContentKind = 'assistant' | 'tool' | 'title' | 'error';
+export interface OutboundMessage {
+    content: string;
+    flags: number;
+    /** No parse category allowed: nothing in the content can ping. */
+    allowed_mentions: {
+        parse: string[];
+    };
+}
+/**
+ * Build one outbound payload. Titles are additionally length-capped (they
+ * render into headers and badges); all content is mention-neutralized.
+ */
+export declare function buildOutboundMessage(input: {
+    kind: OutboundContentKind;
+    content: string;
+}): OutboundMessage;

package/lib/stream/outbound.js

@@ -0,0 +1,25 @@
+/**
+ * The single outbound message builder (design.md §8, task 11.7). Every
+ * message path — assistant answers, tool views, titles, errors — constructs
+ * its payload here, where mention prevention is layered three ways: the
+ * `allowed_mentions: { parse: [] }` request field (the API-level guarantee),
+ * silent-delivery flags, and byte-wise syntax neutralization, so a renderer
+ * that bypassed one layer still could not resolve a ping.
+ */
+import { ALLOWED_MENTIONS_NONE, DISCORD_SUPPRESS_NOTIFICATIONS_FLAG, safeTitle } from '../policy/disclosure.js';
+import { wrapGfmTables } from './markdown.js';
+import { suppressMentionSyntax } from '../policy/suppress.js';
+/** Discord message flags the adapter always sets (silent delivery). */
+export const OUTBOUND_MESSAGE_FLAGS = DISCORD_SUPPRESS_NOTIFICATIONS_FLAG;
+/**
+ * Build one outbound payload. Titles are additionally length-capped (they
+ * render into headers and badges); all content is mention-neutralized.
+ */
+export function buildOutboundMessage(input) {
+    const content = input.kind === 'title'
+        ? safeTitle(input.content)
+        : input.kind === 'assistant'
+            ? suppressMentionSyntax(wrapGfmTables(input.content))
+            : suppressMentionSyntax(input.content);
+    return { content, flags: OUTBOUND_MESSAGE_FLAGS, allowed_mentions: ALLOWED_MENTIONS_NONE };
+}

package/lib/stream/render-fence.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Render generation and terminal fences (design.md §8, task 11.4). Every
+ * async edit belongs to a generation; a late chunk from a superseded
+ * generation is dropped, never overwriting newer output. `finalize` is the
+ * terminal fence: it freezes the final content, and after it nothing —
+ * stale or current — mutates what Discord saw.
+ */
+export interface PublishResult {
+    published: boolean;
+    visible: string;
+}
+export type FinalizeResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: 'stale-generation' | 'already-final';
+};
+export interface RenderFence {
+    /** Open a new generation and return its id. */
+    beginGeneration(): number;
+    current(): number;
+    visible(): string;
+    isFinal(): boolean;
+    publish(content: string, generation: number): PublishResult;
+    finalize(generation: number, finalContent: string): FinalizeResult;
+}
+export declare function createRenderFence(): RenderFence;

package/lib/stream/render-fence.js

@@ -0,0 +1,37 @@
+/**
+ * Render generation and terminal fences (design.md §8, task 11.4). Every
+ * async edit belongs to a generation; a late chunk from a superseded
+ * generation is dropped, never overwriting newer output. `finalize` is the
+ * terminal fence: it freezes the final content, and after it nothing —
+ * stale or current — mutates what Discord saw.
+ */
+export function createRenderFence() {
+    let generation = 0;
+    let visible = '';
+    let final = false;
+    return {
+        beginGeneration() {
+            generation += 1;
+            return generation;
+        },
+        current: () => generation,
+        visible: () => visible,
+        isFinal: () => final,
+        publish(content, gen) {
+            if (final || gen !== generation) {
+                return { published: false, visible };
+            }
+            visible = content;
+            return { published: true, visible };
+        },
+        finalize(gen, finalContent) {
+            if (final)
+                return { ok: false, error: 'already-final' };
+            if (gen !== generation)
+                return { ok: false, error: 'stale-generation' };
+            visible = finalContent;
+            final = true;
+            return { ok: true };
+        },
+    };
+}

package/lib/stream/render-model.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The per-thread render model (design.md §8, tasks 11.1 + 11.2). Each DSH
+ * assistant message owns ONE logical Discord answer: preceding text deltas
+ * coalesce into it, the authoritative `assistant/message` supersedes them, an
+ * interruption keeps the visible prefix with a marker, and a later Step opens
+ * another logical answer rather than overwriting an earlier one. Events for
+ * unknown turns are dropped, never fatal — the reconciler owns recovery.
+ */
+export interface RenderAnswer {
+    turnId: string;
+    stepId: string;
+    text: string;
+    authoritative: boolean;
+    interrupted: boolean;
+}
+export interface RenderSnapshot {
+    turnOpen: boolean;
+    turnId: string | undefined;
+    answers: RenderAnswer[];
+}
+export interface ThreadRenderModel {
+    beginTurn(input: {
+        turnId: string;
+    }): void;
+    endTurn(input: {
+        turnId: string;
+    }): void;
+    beginStep(input: {
+        turnId: string;
+        stepId: string;
+    }): void;
+    appendDelta(input: {
+        turnId: string;
+        stepId: string;
+        text: string;
+    }): void;
+    setAuthoritative(input: {
+        turnId: string;
+        stepId: string;
+        text: string;
+    }): void;
+    interrupt(input: {
+        turnId: string;
+        stepId: string;
+    }): void;
+    snapshot(): RenderSnapshot;
+}
+export declare function createThreadRenderModel(): ThreadRenderModel;

package/lib/stream/render-model.js

@@ -0,0 +1,68 @@
+/**
+ * The per-thread render model (design.md §8, tasks 11.1 + 11.2). Each DSH
+ * assistant message owns ONE logical Discord answer: preceding text deltas
+ * coalesce into it, the authoritative `assistant/message` supersedes them, an
+ * interruption keeps the visible prefix with a marker, and a later Step opens
+ * another logical answer rather than overwriting an earlier one. Events for
+ * unknown turns are dropped, never fatal — the reconciler owns recovery.
+ */
+export function createThreadRenderModel() {
+    let turnId;
+    let turnOpen = false;
+    const answers = new Map();
+    function answerKey(stepId) {
+        return `${turnId ?? ''}:${stepId}`;
+    }
+    function ensureAnswer(stepId) {
+        const key = answerKey(stepId);
+        let answer = answers.get(key);
+        if (answer === undefined) {
+            answer = { turnId: turnId ?? '', stepId, text: '', authoritative: false, interrupted: false };
+            answers.set(key, answer);
+        }
+        return answer;
+    }
+    return {
+        beginTurn(input) {
+            if (input.turnId === turnId && turnOpen)
+                return;
+            turnId = input.turnId;
+            turnOpen = true;
+            // Answers belong to their turn: a new turn opens a fresh list.
+            answers.clear();
+        },
+        endTurn(input) {
+            if (input.turnId === turnId)
+                turnOpen = false;
+        },
+        beginStep(input) {
+            if (input.turnId !== turnId)
+                return;
+            ensureAnswer(input.stepId);
+        },
+        appendDelta(input) {
+            if (input.turnId !== turnId)
+                return;
+            const answer = ensureAnswer(input.stepId);
+            if (answer.authoritative || answer.interrupted)
+                return;
+            answer.text += input.text;
+        },
+        setAuthoritative(input) {
+            if (input.turnId !== turnId)
+                return;
+            const answer = ensureAnswer(input.stepId);
+            answer.text = input.text;
+            answer.authoritative = true;
+        },
+        interrupt(input) {
+            if (input.turnId !== turnId)
+                return;
+            const answer = ensureAnswer(input.stepId);
+            answer.interrupted = true;
+        },
+        snapshot() {
+            return { turnOpen, turnId, answers: [...answers.values()] };
+        },
+    };
+}

package/lib/stream/splitter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The base message splitter (design.md §8, task 11.5). Breaks prefer line
+ * boundaries, then word boundaries, then a hard cut — iterating by code
+ * points so surrogate pairs (emoji) never split mid-pair. Every chunk is
+ * non-empty and within Discord's message limit.
+ */
+export declare const DISCORD_MESSAGE_LIMIT = 2000;
+export declare function splitMessage(text: string, limit?: number): string[];

package/lib/stream/splitter.js

@@ -0,0 +1,58 @@
+/**
+ * The base message splitter (design.md §8, task 11.5). Breaks prefer line
+ * boundaries, then word boundaries, then a hard cut — iterating by code
+ * points so surrogate pairs (emoji) never split mid-pair. Every chunk is
+ * non-empty and within Discord's message limit.
+ */
+export const DISCORD_MESSAGE_LIMIT = 2_000;
+/** Code-point-safe slice: never splits a surrogate pair. */
+function safeSlice(text, start, end) {
+    let end2 = Math.min(end, text.length);
+    if (end2 < text.length) {
+        const code = text.charCodeAt(end2 - 1);
+        const next = text.charCodeAt(end2);
+        // High surrogate at the last position followed by a low surrogate: pull back.
+        if (code >= 0xD800 && code <= 0xDBFF && next >= 0xDC00 && next <= 0xDFFF) {
+            end2 -= 1;
+        }
+    }
+    return text.slice(start, end2);
+}
+export function splitMessage(text, limit = DISCORD_MESSAGE_LIMIT) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return [];
+    if (trimmed.length <= limit)
+        return [trimmed];
+    const chunks = [];
+    let rest = trimmed;
+    while (rest.length > limit) {
+        const window = rest.slice(0, limit + 1);
+        // Prefer the last line break inside the window.
+        let cut = window.lastIndexOf('\n');
+        if (cut <= 0) {
+            // Then the last word boundary.
+            cut = window.lastIndexOf(' ');
+        }
+        if (cut <= 0) {
+            // Hard cut at a code-point boundary.
+            cut = limit;
+        }
+        const chunk = safeSlice(rest, 0, cut).trim();
+        if (chunk !== '')
+            chunks.push(chunk);
+        let advance = cut === limit ? limit : cut + 1;
+        // safeSlice may have pulled the chunk boundary back one code unit to
+        // avoid splitting a surrogate pair; the next chunk must start at that
+        // pulled-back position, never at the dangling low surrogate.
+        const hi = rest.charCodeAt(advance - 1);
+        const lo = rest.charCodeAt(advance);
+        if (hi >= 0xD800 && hi <= 0xDBFF && lo >= 0xDC00 && lo <= 0xDFFF)
+            advance -= 1;
+        rest = rest.slice(advance);
+    }
+    const tail = rest.trim();
+    if (tail !== '')
+        chunks.push(tail);
+    return chunks;
+}

package/lib/stream/tool-view.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The bounded tool activity surface (design.md §8, task 11.8). Parallel tool
+ * calls each own one status row keyed by `callId`. Labels come from a safe
+ * allowlist (generic fallback otherwise — an unknown tool name never reaches
+ * Discord). Raw arguments and output are accepted for correlation but are
+ * structurally excluded from every render. Verbosity gates visibility:
+ * `text-only` renders nothing; `essential-tools` and `full-tools` render the
+ * same bounded rows in Milestone 1.
+ */
+import type { DiscordVerbosity } from '../settings.js';
+export type ToolState = 'running' | 'succeeded' | 'failed' | 'interrupted';
+export interface ToolRow {
+    callId: string;
+    label: string;
+    state: ToolState;
+    /** Host-presented title (command / call title); falls back to the label. */
+    title: string | undefined;
+}
+/** The safe label for a tool name: allowlisted categories, generic fallback. */
+export declare function toolLabel(toolName: string): string;
+export interface ToolRecordInput {
+    callId: string;
+    toolName: string;
+    state: ToolState;
+    /** Accepted for correlation only; never rendered. */
+    rawArguments?: string | undefined;
+    rawOutput?: string | undefined;
+    /**
+     * The Host presentation view's title (a terminal call's command, or the
+     * call title) — Host-curated disclosure, rendered sanitized + truncated.
+     */
+    title?: string | undefined;
+}
+export interface ToolActivitySurface {
+    record(input: ToolRecordInput): void;
+    render(): ToolRow[];
+}
+export declare function createToolActivitySurface(options: {
+    verbosity: DiscordVerbosity;
+}): ToolActivitySurface;

package/lib/stream/tool-view.js

@@ -0,0 +1,39 @@
+/**
+ * The bounded tool activity surface (design.md §8, task 11.8). Parallel tool
+ * calls each own one status row keyed by `callId`. Labels come from a safe
+ * allowlist (generic fallback otherwise — an unknown tool name never reaches
+ * Discord). Raw arguments and output are accepted for correlation but are
+ * structurally excluded from every render. Verbosity gates visibility:
+ * `text-only` renders nothing; `essential-tools` and `full-tools` render the
+ * same bounded rows in Milestone 1.
+ */
+/** Safe, category-level labels for allowlisted tools. */
+const TOOL_LABELS = {
+    bash: 'Shell',
+    read: 'Read file',
+    write: 'Write file',
+    edit: 'Edit file',
+    grep: 'Search',
+    glob: 'Find files',
+    web: 'Web',
+};
+/** The safe label for a tool name: allowlisted categories, generic fallback. */
+export function toolLabel(toolName) {
+    return TOOL_LABELS[toolName] ?? 'Tool';
+}
+export function createToolActivitySurface(options) {
+    const rows = new Map();
+    return {
+        record(input) {
+            if (options.verbosity === 'text-only')
+                return;
+            rows.set(input.callId, {
+                callId: input.callId,
+                label: toolLabel(input.toolName),
+                state: input.state,
+                title: input.title,
+            });
+        },
+        render: () => [...rows.values()],
+    };
+}

package/lib/stream/typing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The typing keepalive lifecycle (design.md §8, task 11.9). Typing starts
+ * when a Turn produces work and refreshes on an interval; an owning
+ * interaction pauses it (the interaction owns attention); completion,
+ * cancellation, and failure all stop it; disposal is terminal — no trigger
+ * can fire after the plugin tears the surface down.
+ */
+export type TypingStopReason = 'completed' | 'cancelled' | 'failed' | 'disposed';
+export type TypingPauseReason = 'interaction';
+export interface TypingLifecycle {
+    start(): void;
+    pause(reason: TypingPauseReason): void;
+    resume(): void;
+    stop(reason?: TypingStopReason): void;
+    dispose(): void;
+}
+export declare function createTypingLifecycle(options: {
+    trigger: () => void | Promise<void>;
+    intervalMs: number;
+    /** Observes a failed trigger; the interval keeps the indicator honest. */
+    onFailure?: (cause: unknown) => void;
+}): TypingLifecycle;

package/lib/stream/typing.js

@@ -0,0 +1,58 @@
+/**
+ * The typing keepalive lifecycle (design.md §8, task 11.9). Typing starts
+ * when a Turn produces work and refreshes on an interval; an owning
+ * interaction pauses it (the interaction owns attention); completion,
+ * cancellation, and failure all stop it; disposal is terminal — no trigger
+ * can fire after the plugin tears the surface down.
+ */
+export function createTypingLifecycle(options) {
+    let state = 'idle';
+    let timer;
+    const fire = () => {
+        // The trigger runs detached (fire-and-forget by contract); without this
+        // catch a rejecting trigger (e.g. a credential resolution failure) would
+        // be an unhandled rejection and kill the process.
+        void Promise.resolve(options.trigger()).catch((cause) => {
+            options.onFailure?.(cause);
+        });
+    };
+    function clearTimer() {
+        if (timer !== undefined) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    }
+    return {
+        start() {
+            if (state !== 'idle')
+                return;
+            state = 'running';
+            fire();
+            timer = setInterval(fire, options.intervalMs);
+        },
+        pause(reason) {
+            void reason;
+            if (state !== 'running')
+                return;
+            state = 'paused';
+            clearTimer();
+        },
+        resume() {
+            if (state !== 'paused')
+                return;
+            state = 'running';
+            fire();
+            timer = setInterval(fire, options.intervalMs);
+        },
+        stop(reason = 'completed') {
+            void reason;
+            if (state === 'stopped')
+                return;
+            state = 'stopped';
+            clearTimer();
+        },
+        dispose() {
+            this.stop('disposed');
+        },
+    };
+}

package/lib/stream/update-scheduler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The streaming update scheduler (design.md §8, task 11.3). Rapid chunks
+ * coalesce: content is remembered as "latest" and one flush per interval
+ * carries it to Discord — and because a flush may be an in-flight REST edit,
+ * the scheduler serializes: while a flush runs, new content only waits; the
+ * next flush fires only when both the interval elapsed AND the content
+ * changed. A failed flush is observed HERE (the scheduler runs detached, so
+ * its rejection would otherwise be unhandled), reported through
+ * `onFlushError`, and retried on the next schedule.
+ */
+export interface UpdateScheduler {
+    schedule(content: string): void;
+    dispose(): void;
+}
+export declare function createUpdateScheduler(options: {
+    minIntervalMs: number;
+    onFlush(content: string): Promise<void>;
+    /** Observes a failed flush; unset, failures are still contained silently. */
+    onFlushError?: (cause: unknown) => void;
+}): UpdateScheduler;

package/lib/stream/update-scheduler.js

@@ -0,0 +1,65 @@
+/**
+ * The streaming update scheduler (design.md §8, task 11.3). Rapid chunks
+ * coalesce: content is remembered as "latest" and one flush per interval
+ * carries it to Discord — and because a flush may be an in-flight REST edit,
+ * the scheduler serializes: while a flush runs, new content only waits; the
+ * next flush fires only when both the interval elapsed AND the content
+ * changed. A failed flush is observed HERE (the scheduler runs detached, so
+ * its rejection would otherwise be unhandled), reported through
+ * `onFlushError`, and retried on the next schedule.
+ */
+export function createUpdateScheduler(options) {
+    let disposed = false;
+    let latest;
+    let lastFlushed;
+    let timer;
+    let flushing = false;
+    function scheduleNext(now) {
+        if (disposed || now === undefined || now === lastFlushed)
+            return;
+        if (timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void runFlush();
+        }, options.minIntervalMs);
+    }
+    async function runFlush() {
+        if (disposed || flushing)
+            return;
+        const content = latest;
+        if (content === undefined || content === lastFlushed)
+            return;
+        flushing = true;
+        try {
+            await options.onFlush(content);
+            lastFlushed = content;
+        }
+        catch (cause) {
+            // The flush runs detached (void runFlush()), so this catch is the only
+            // thing standing between a failing delivery and a process-killing
+            // unhandled rejection. lastFlushed stays put: the next schedule retries.
+            options.onFlushError?.(cause);
+        }
+        finally {
+            flushing = false;
+            // Content that arrived during the flush gets its own interval now.
+            scheduleNext(latest);
+        }
+    }
+    return {
+        schedule(content) {
+            if (disposed)
+                return;
+            latest = content;
+            scheduleNext(content);
+        },
+        dispose() {
+            disposed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+    };
+}