@addozhang/dsh-discord 0.1.0

package/lib/features/adapter-status.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Sanitized adapter status for the settings surface (design.md §3, task 2.3;
+ * plugin-foundation spec). The Host distills credential presence and Gateway
+ * observations into one small value — machine-readable condition plus a
+ * stable hint key the card resolves to copy — that by construction has no
+ * slot for the token or any raw provider response. The value reaches the Web
+ * card through the plugin's loopback RPC channel, the same seam dsh
+ * establishes for plugin management surfaces.
+ */
+/** Credential presence for the fixed bot-token reference (never its value). */
+export type TokenPresence = 'configured' | 'unconfigured';
+/** What the Gateway is doing, distilled from the composition layer's watches. */
+export type GatewayObservation = 'connected' | 'connecting' | 'disconnected' | {
+    kind: 'terminal-close';
+    code: number;
+};
+/** Non-connection facts worth surfacing (channel permissions, 5.x territory). */
+export type StatusDetail = 'missing-channel-permissions';
+/** The conditions the settings surface can name. */
+export type ConnectionCondition = 'connected' | 'connecting' | 'disconnected' | 'invalid-token' | 'intents-blocked' | 'permissions-blocked';
+/** Stable hint keys; the card owns the human copy. */
+export type StatusHint = 'configure-token' | 'token-rejected' | 'enable-intents' | 'gateway-closed' | 'channel-permissions';
+export interface AdapterStatusView {
+    token: TokenPresence;
+    connection: ConnectionCondition;
+    hint?: StatusHint | undefined;
+}
+export interface AdapterStatusInput {
+    token: TokenPresence;
+    gateway: GatewayObservation;
+    detail?: StatusDetail | undefined;
+}
+export declare function projectAdapterStatus(input: AdapterStatusInput): AdapterStatusView;
+/** Latest observed facts; the projection is always derivable on demand. */
+export interface AdapterStatusTracker {
+    setCredential(view: {
+        configured: boolean;
+        source?: string;
+        writable?: boolean;
+    }): void;
+    setGateway(observation: GatewayObservation): void;
+    setDetail(detail: StatusDetail | undefined): void;
+    project(): AdapterStatusView;
+}
+export declare function createAdapterStatusTracker(): AdapterStatusTracker;
+/** The plugin RPC channel; the client bundle calls the same constant. */
+export declare const DISCORD_RPC_CHANNEL = "/dsh-discord";
+/** The one endpoint this channel serves. */
+export declare const STATUS_ENDPOINT = "adapter.status";
+/** The Host connection service's RPC face (duck-typed; dsh owns the real type). */
+export interface ConnectionRpc {
+    rpc: {
+        handle(channel: string, handler: (endpoint: string, payload: unknown, signal: {
+            aborted: boolean;
+        } | undefined) => Promise<{
+            ok: true;
+            value: unknown;
+        } | {
+            ok: false;
+            error: {
+                code: string;
+                message: string;
+            };
+        }>, options: {
+            authority: 'loopback' | 'trusted-host';
+        }): () => void;
+    };
+}
+type RpcAnswer = {
+    ok: true;
+    value: AdapterStatusView | Record<string, unknown>;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * The channel's handler: exactly one endpoint, value-shaped failures, and no
+ * access to anything beyond the projection.
+ */
+export declare function createAdapterStatusRpcHandler(tracker: AdapterStatusTracker): (endpoint: string, payload: unknown, signal: {
+    aborted: boolean;
+} | undefined) => Promise<RpcAnswer>;
+/** Extra host faces the management channel can exercise. */
+export interface ManagementChannelDeps {
+    tracker: AdapterStatusTracker;
+    /** Store the bot token into the writable credential layer. */
+    setToken?: ((value: string) => Promise<void>) | undefined;
+    /** Re-run the adapter start chain (the card's Connect button). */
+    connect?: (() => void) | undefined;
+    /** Operator-initiated offline (the card's Disconnect button). */
+    disconnect?: (() => void) | undefined;
+    /** Guilds the bot is a member of, sanitized (id + name only). */
+    guilds?: (() => Promise<Array<{
+        id: string;
+        name: string;
+    }>>) | undefined;
+}
+/**
+ * The management channel's handler: status (with guild names when
+ * discoverable), credential write, and a connect trigger. Unknown endpoints
+ * fail as values; nothing here can read the token back.
+ */
+export declare function createAdapterManagementHandler(deps: ManagementChannelDeps): (endpoint: string, payload: unknown, signal: {
+    aborted: boolean;
+} | undefined) => Promise<RpcAnswer>;
+/** Register the management channel; returns the connection service's disposer. */
+export declare function installAdapterStatusRpc(connection: ConnectionRpc, tracker: AdapterStatusTracker, deps?: ManagementChannelDeps): () => void;
+export {};

package/lib/features/adapter-status.js

@@ -0,0 +1,103 @@
+/**
+ * Sanitized adapter status for the settings surface (design.md §3, task 2.3;
+ * plugin-foundation spec). The Host distills credential presence and Gateway
+ * observations into one small value — machine-readable condition plus a
+ * stable hint key the card resolves to copy — that by construction has no
+ * slot for the token or any raw provider response. The value reaches the Web
+ * card through the plugin's loopback RPC channel, the same seam dsh
+ * establishes for plugin management surfaces.
+ */
+/** Discord's authentication-failure close: the token itself is rejected. */
+const AUTH_FAILURE_CLOSE = 4004;
+/** Discord's invalid/disallowed-intent closes: the config, not the token. */
+const INTENT_REJECTION_CLOSES = new Set([4013, 4014]);
+export function projectAdapterStatus(input) {
+    if (input.token === 'unconfigured') {
+        return { token: input.token, connection: 'disconnected', hint: 'configure-token' };
+    }
+    if (input.detail === 'missing-channel-permissions' && input.gateway !== 'connected') {
+        return { token: input.token, connection: 'permissions-blocked', hint: 'channel-permissions' };
+    }
+    if (typeof input.gateway === 'object') {
+        if (input.gateway.code === AUTH_FAILURE_CLOSE) {
+            return { token: input.token, connection: 'invalid-token', hint: 'token-rejected' };
+        }
+        if (INTENT_REJECTION_CLOSES.has(input.gateway.code)) {
+            return { token: input.token, connection: 'intents-blocked', hint: 'enable-intents' };
+        }
+        return { token: input.token, connection: 'disconnected', hint: 'gateway-closed' };
+    }
+    // connected / connecting / disconnected-by-observation carry no hint of
+    // their own: nothing actionable has been observed yet.
+    return { token: input.token, connection: input.gateway };
+}
+export function createAdapterStatusTracker() {
+    let token = 'unconfigured';
+    let gateway = 'disconnected';
+    let detail = undefined;
+    return {
+        setCredential(view) {
+            token = view.configured ? 'configured' : 'unconfigured';
+        },
+        setGateway(observation) {
+            gateway = observation;
+        },
+        setDetail(next) {
+            detail = next;
+        },
+        project() {
+            return projectAdapterStatus({ token, gateway, ...(detail === undefined ? {} : { detail }) });
+        },
+    };
+}
+/** The plugin RPC channel; the client bundle calls the same constant. */
+export const DISCORD_RPC_CHANNEL = '/dsh-discord';
+/** The one endpoint this channel serves. */
+export const STATUS_ENDPOINT = 'adapter.status';
+/**
+ * The channel's handler: exactly one endpoint, value-shaped failures, and no
+ * access to anything beyond the projection.
+ */
+export function createAdapterStatusRpcHandler(tracker) {
+    return createAdapterManagementHandler({ tracker });
+}
+/**
+ * The management channel's handler: status (with guild names when
+ * discoverable), credential write, and a connect trigger. Unknown endpoints
+ * fail as values; nothing here can read the token back.
+ */
+export function createAdapterManagementHandler(deps) {
+    return (endpoint, payload, signal) => {
+        if (signal?.aborted) {
+            return Promise.resolve({ ok: false, error: { code: 'cancelled', message: 'The request was cancelled.' } });
+        }
+        if (endpoint === STATUS_ENDPOINT) {
+            if (deps.guilds === undefined)
+                return Promise.resolve({ ok: true, value: deps.tracker.project() });
+            return deps.guilds().then((guilds) => ({ ok: true, value: { ...deps.tracker.project(), guilds } }), () => ({ ok: true, value: deps.tracker.project() }));
+        }
+        if (endpoint === 'adapter.connect' && deps.connect !== undefined) {
+            deps.connect();
+            return Promise.resolve({ ok: true, value: { connecting: true } });
+        }
+        if (endpoint === 'adapter.disconnect' && deps.disconnect !== undefined) {
+            deps.disconnect();
+            return Promise.resolve({ ok: true, value: { stopped: true } });
+        }
+        if (endpoint === 'credentials.set' && deps.setToken !== undefined) {
+            const value = payload?.value;
+            const text = typeof value === 'string' ? value.trim() : '';
+            if (text === '') {
+                return Promise.resolve({ ok: false, error: { code: 'bad-request', message: 'empty token' } });
+            }
+            return deps.setToken(text).then(() => ({ ok: true, value: { saved: true } }), (cause) => ({ ok: false, error: { code: 'credential-rejected', message: String(cause) } }));
+        }
+        return Promise.resolve({ ok: false, error: { code: 'bad-request', message: `Unknown ${DISCORD_RPC_CHANNEL} endpoint.` } });
+    };
+}
+/** Register the management channel; returns the connection service's disposer. */
+export function installAdapterStatusRpc(connection, tracker, deps = { tracker }) {
+    return connection.rpc.handle(DISCORD_RPC_CHANNEL, createAdapterManagementHandler(deps), {
+        authority: 'loopback',
+    });
+}

package/lib/features/approval-expiry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Approval expiry sweep (design.md §8, task 13.4). An approval whose deadline
+ * passes while still pending fails closed: the sweep claims it atomically —
+ * losing to any concurrent click — submits `rejected` through the record's
+ * rpcId, and marks the Discord controls expired only AFTER the outcome is
+ * recorded. When DSH does not confirm the rejection, the record keeps an
+ * explicit unresolved state and the controls stay live: nothing is claimed
+ * as answered, and the user's own click remains the retry path (the sweep
+ * never auto-retries).
+ */
+import type { DshApprovalRespondPort } from './approval-routing.js';
+import type { ApprovalStore } from './approval-store.js';
+/** Face that retires the rendered Allow once / Reject controls. */
+export interface ExpiredControls {
+    disable(approvalId: string): Promise<void>;
+}
+export interface ApprovalExpiryDeps {
+    store: ApprovalStore;
+    port: DshApprovalRespondPort;
+    controls: ExpiredControls;
+    nowMs: () => number;
+}
+export interface ExpirySweepResult {
+    /** Approval ids this sweep rejected and retired. */
+    handled: string[];
+}
+export declare function sweepExpiredApprovals(deps: ApprovalExpiryDeps): Promise<ExpirySweepResult>;

package/lib/features/approval-expiry.js

@@ -0,0 +1,36 @@
+/**
+ * Approval expiry sweep (design.md §8, task 13.4). An approval whose deadline
+ * passes while still pending fails closed: the sweep claims it atomically —
+ * losing to any concurrent click — submits `rejected` through the record's
+ * rpcId, and marks the Discord controls expired only AFTER the outcome is
+ * recorded. When DSH does not confirm the rejection, the record keeps an
+ * explicit unresolved state and the controls stay live: nothing is claimed
+ * as answered, and the user's own click remains the retry path (the sweep
+ * never auto-retries).
+ */
+export async function sweepExpiredApprovals(deps) {
+    const nowMs = deps.nowMs();
+    const handled = [];
+    for (const record of deps.store.listPendingExpired(nowMs)) {
+        // Atomic claim: a click that beat the sweep owns the answer instead.
+        const claim = await deps.store.claim(record.approvalId);
+        if (claim.outcome !== 'claimed')
+            continue;
+        const submitted = await deps.port.respond({
+            rpcId: record.rpcId,
+            sessionId: record.sessionId,
+            approvalId: record.approvalId,
+            outcome: 'rejected',
+        });
+        if (submitted.outcome === 'confirmed') {
+            await deps.store.markResolved(record.approvalId, 'rejected', deps.nowMs());
+            // Controls expire only after the outcome is on the record.
+            await deps.controls.disable(record.approvalId);
+            handled.push(record.approvalId);
+            continue;
+        }
+        await deps.store.markUnresolved(record.approvalId, deps.nowMs());
+        handled.push(record.approvalId);
+    }
+    return { handled };
+}

package/lib/features/approval-routing.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Approval click routing (design.md §8, tasks 13.2/13.3). One pipeline per
+ * component click: resolve the opaque custom_id, validate ownership, claim
+ * the record atomically, submit exactly one DSH response, and settle the
+ * record from what DSH actually confirmed. Losers of a race, stale controls,
+ * and denials never reach DSH; an unconfirmed submit parks the approval in
+ * an explicit unresolved state — it is never reported as answered.
+ */
+import type { ComponentRegistry } from '../discord/components.js';
+import { type ApprovalOutcome, type ApprovalStore } from './approval-store.js';
+/** The DSH respond face: the answerable server-request echo (approvals.d.ts). */
+export interface DshApprovalRespondPort {
+    respond(input: {
+        rpcId: string;
+        sessionId: string;
+        approvalId: string;
+        outcome: ApprovalOutcome;
+    }): Promise<{
+        outcome: 'confirmed';
+    } | {
+        outcome: 'rejected';
+        reason: string;
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+export interface ApprovalRoutingDeps {
+    registry: ComponentRegistry;
+    store: ApprovalStore;
+    port: DshApprovalRespondPort;
+    nowMs: () => number;
+}
+export interface ApprovalClickInput {
+    customId: string;
+    userId: string;
+    threadId: string;
+}
+export type ApprovalClickOutcome = {
+    outcome: 'submitted';
+    action: 'allow' | 'reject';
+} | {
+    outcome: 'already-resolved';
+} | {
+    outcome: 'denied';
+} | {
+    outcome: 'unknown-control';
+} | {
+    outcome: 'unresolved';
+};
+export declare function handleApprovalClick(deps: ApprovalRoutingDeps, click: ApprovalClickInput): Promise<ApprovalClickOutcome>;

package/lib/features/approval-routing.js

@@ -0,0 +1,57 @@
+/**
+ * Approval click routing (design.md §8, tasks 13.2/13.3). One pipeline per
+ * component click: resolve the opaque custom_id, validate ownership, claim
+ * the record atomically, submit exactly one DSH response, and settle the
+ * record from what DSH actually confirmed. Losers of a race, stale controls,
+ * and denials never reach DSH; an unconfirmed submit parks the approval in
+ * an explicit unresolved state — it is never reported as answered.
+ */
+import { authorizeApprovalClick } from './approval-store.js';
+/** Registry contexts carry only these two facts plus their expiry. */
+function parseContext(context) {
+    const approvalId = context['approvalId'];
+    const action = context['action'];
+    if (typeof approvalId !== 'string' || (action !== 'allow' && action !== 'reject'))
+        return undefined;
+    return { approvalId, action };
+}
+export async function handleApprovalClick(deps, click) {
+    const resolution = deps.registry.resolve(click.customId, deps.nowMs());
+    if (!resolution.found)
+        return { outcome: 'unknown-control' };
+    const context = parseContext(resolution.context);
+    if (context === undefined)
+        return { outcome: 'unknown-control' };
+    const record = deps.store.get(context.approvalId);
+    if (record === undefined)
+        return { outcome: 'unknown-control' };
+    const decision = authorizeApprovalClick(record, click);
+    if (!decision.allowed)
+        return { outcome: 'denied' };
+    const claim = await deps.store.claim(context.approvalId);
+    if (claim.outcome !== 'claimed')
+        return { outcome: 'already-resolved' };
+    const outcome = context.action === 'allow' ? 'allowed-once' : 'rejected';
+    // A port that THROWS (distinct from an unknown outcome) is still an
+    // unconfirmed submit: park unresolved so the expiry sweep and the user's
+    // own retry stay available — never leave the approval in submitting.
+    let submitted;
+    try {
+        submitted = await deps.port.respond({
+            rpcId: decision.respond.rpcId,
+            sessionId: decision.respond.sessionId,
+            approvalId: decision.respond.approvalId,
+            outcome,
+        });
+    }
+    catch {
+        await deps.store.markUnresolved(context.approvalId, deps.nowMs());
+        return { outcome: 'unresolved' };
+    }
+    if (submitted.outcome === 'confirmed') {
+        await deps.store.markResolved(context.approvalId, outcome, deps.nowMs());
+        return { outcome: 'submitted', action: context.action };
+    }
+    await deps.store.markUnresolved(context.approvalId, deps.nowMs());
+    return { outcome: 'unresolved' };
+}

package/lib/features/approval-store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pending approval records and ownership validation (design.md §6/§8, tasks
+ * 13.2/13.3). One record binds every ownership fact — Session, Discord
+ * Thread, the owning adapter-submitted request ID, the DSH rpcId, the
+ * approval ID, and the originating Discord user — and is the ONLY source of
+ * respond data: the wire carries an opaque key, so nothing can be spoofed
+ * through a click. Opening is idempotent per approval ID (the mux replays
+ * still-pending requests on reconnect), and Milestone 1 authorization is
+ * exactly the originating user on the owning thread — administrators
+ * included are denied.
+ */
+export type ApprovalState = 'pending' | 'submitting' | 'resolved' | 'unresolved';
+export type ApprovalOutcome = 'allowed-once' | 'rejected';
+export interface ApprovalRecord {
+    approvalId: string;
+    sessionId: string;
+    /** The owning Discord thread; clicks from any other thread are denied. */
+    threadId: string;
+    /** The owning adapter-submitted turn's durable request ID. */
+    requestId: string;
+    /** The answerable server-request rpcId the response must echo. */
+    rpcId: string;
+    /** The Discord user who submitted the owning turn. */
+    actorUserId: string;
+    toolName: string;
+    reason?: string | undefined;
+    expiresAtMs: number;
+    state: ApprovalState;
+    resolvedOutcome?: ApprovalOutcome | undefined;
+    resolvedAtMs?: number | undefined;
+}
+/** Minimal durable face (the domain's KvTable provides it). */
+export interface ApprovalTable {
+    get(approvalId: string): ApprovalRecord | undefined;
+    put(approvalId: string, record: ApprovalRecord): Promise<void>;
+}
+export interface ApprovalStore {
+    get(approvalId: string): ApprovalRecord | undefined;
+    /** Register a pending approval; a replay keeps the original record. */
+    open(record: ApprovalRecord): void;
+    /**
+     * Atomically claim the approval for submission: pending (or an explicit
+     * user retry after unresolved) flips to submitting exactly once per
+     * serialized key; submitting and resolved records never re-claim.
+     */
+    claim(approvalId: string): Promise<{
+        outcome: 'claimed';
+        record: ApprovalRecord;
+    } | {
+        outcome: 'not-claimable';
+        record: ApprovalRecord;
+    } | {
+        outcome: 'unknown';
+    }>;
+    /** Record a DSH-confirmed outcome; terminal. */
+    markResolved(approvalId: string, outcome: ApprovalOutcome, atMs: number): Promise<void>;
+    /** Retain the record in an explicit unresolved state when DSH is silent. */
+    markUnresolved(approvalId: string, atMs: number): Promise<void>;
+    /** Pending records whose deadline has passed, for the expiry sweep (13.4). */
+    listPendingExpired(atMs: number): ApprovalRecord[];
+}
+export declare function createApprovalStore(table: ApprovalTable): ApprovalStore;
+export interface ApprovalClick {
+    userId: string;
+    threadId: string;
+    /** Present for context only: administrators hold no approval privilege. */
+    isAdministrator?: boolean | undefined;
+}
+export type ApprovalDecision = {
+    allowed: true;
+    /** Respond data built solely from the record, for apiProxy.respond. */
+    respond: {
+        rpcId: string;
+        sessionId: string;
+        approvalId: string;
+    };
+    requestId: string;
+} | {
+    allowed: false;
+    reason: 'not-owner';
+};
+/**
+ * Milestone 1 approval authorization: the originating user on the owning
+ * thread, point. Administrative or moderator standing grants nothing.
+ */
+export declare function authorizeApprovalClick(record: ApprovalRecord, click: ApprovalClick): ApprovalDecision;

package/lib/features/approval-store.js

@@ -0,0 +1,119 @@
+/**
+ * Pending approval records and ownership validation (design.md §6/§8, tasks
+ * 13.2/13.3). One record binds every ownership fact — Session, Discord
+ * Thread, the owning adapter-submitted request ID, the DSH rpcId, the
+ * approval ID, and the originating Discord user — and is the ONLY source of
+ * respond data: the wire carries an opaque key, so nothing can be spoofed
+ * through a click. Opening is idempotent per approval ID (the mux replays
+ * still-pending requests on reconnect), and Milestone 1 authorization is
+ * exactly the originating user on the owning thread — administrators
+ * included are denied.
+ */
+/** Per-key serialization: operations on one approval never interleave. */
+function serialized(chains, key, op) {
+    const tail = chains.get(key) ?? Promise.resolve();
+    const run = tail.then(op, op);
+    chains.set(key, run.then(() => undefined, () => undefined));
+    return run;
+}
+/**
+ * How long a terminal approval record lingers in the id index past its
+ * deadline before listing prunes it — the resolved-interaction retention
+ * semantics of design.md §10 (7 days), applied to the store's own index.
+ */
+const RESOLVED_INTERACTION_RETENTION_MS = 7 * 24 * 60 * 60_000;
+export function createApprovalStore(table) {
+    const chains = new Map();
+    /** In-memory id index; enumeration reads through and prunes itself. */
+    const knownIds = new Set();
+    function snapshot() {
+        const records = [];
+        for (const approvalId of knownIds) {
+            const record = table.get(approvalId);
+            if (record === undefined) {
+                knownIds.delete(approvalId);
+                continue;
+            }
+            records.push(record);
+        }
+        return records;
+    }
+    function prunePastRetention(nowMs) {
+        for (const record of snapshot()) {
+            const settled = record.state === 'resolved' || record.state === 'unresolved';
+            if (settled && nowMs - record.expiresAtMs > RESOLVED_INTERACTION_RETENTION_MS) {
+                knownIds.delete(record.approvalId);
+            }
+        }
+    }
+    function mutate(approvalId, change) {
+        return serialized(chains, approvalId, async () => {
+            const existing = table.get(approvalId);
+            if (existing === undefined)
+                return undefined;
+            const next = change(existing);
+            await table.put(approvalId, next);
+            return next;
+        });
+    }
+    return {
+        get: approvalId => table.get(approvalId),
+        open(record) {
+            const existing = table.get(record.approvalId);
+            if (existing !== undefined)
+                return;
+            knownIds.add(record.approvalId);
+            void table.put(record.approvalId, record);
+        },
+        claim(approvalId) {
+            return serialized(chains, approvalId, async () => {
+                const existing = table.get(approvalId);
+                if (existing === undefined)
+                    return { outcome: 'unknown' };
+                // An unresolved record still demands an answer; a fresh explicit
+                // click is that answer. Everything else is settled or in flight.
+                const claimable = existing.state === 'pending' || existing.state === 'unresolved';
+                if (!claimable)
+                    return { outcome: 'not-claimable', record: existing };
+                const claimed = { ...existing, state: 'submitting' };
+                await table.put(approvalId, claimed);
+                return { outcome: 'claimed', record: claimed };
+            });
+        },
+        markResolved(approvalId, outcome, atMs) {
+            return mutate(approvalId, record => ({
+                ...record,
+                state: 'resolved',
+                resolvedOutcome: outcome,
+                resolvedAtMs: atMs,
+            })).then(() => undefined);
+        },
+        markUnresolved(approvalId, atMs) {
+            return mutate(approvalId, record => ({ ...record, state: 'unresolved', resolvedAtMs: atMs }))
+                .then(() => undefined);
+        },
+        listPendingExpired(atMs) {
+            prunePastRetention(atMs);
+            const expired = [];
+            for (const record of snapshot()) {
+                if (record.state === 'pending' && atMs >= record.expiresAtMs)
+                    expired.push(record);
+            }
+            return expired;
+        },
+    };
+}
+/**
+ * Milestone 1 approval authorization: the originating user on the owning
+ * thread, point. Administrative or moderator standing grants nothing.
+ */
+export function authorizeApprovalClick(record, click) {
+    if (click.userId !== record.actorUserId || click.threadId !== record.threadId) {
+        return { allowed: false, reason: 'not-owner' };
+    }
+    return {
+        allowed: true,
+        respond: { rpcId: record.rpcId, sessionId: record.sessionId, approvalId: record.approvalId },
+        requestId: record.requestId,
+    };
+}

package/lib/features/approval-view.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Approval control rendering (design.md §8, task 13.1). A pending DSH
+ * approval renders as Allow once / Reject buttons whose custom_ids are
+ * opaque registry keys minted per control — session, rpc, approval, tool,
+ * and reason data never ride the Discord wire. Visible text reuses the
+ * activity surface's safe allowlisted labels (generic fallback) and the
+ * outbound mention posture: the host-supplied reason is mention-neutralized
+ * and bounded before display.
+ */
+import type { ComponentRegistry } from '../discord/components.js';
+import { DISCORD_SUPPRESS_NOTIFICATIONS_FLAG } from '../policy/disclosure.js';
+/** Discord interactive-component ids (action row = 1, button = 2). */
+declare const ACTION_ROW = 1;
+declare const BUTTON = 2;
+declare const BUTTON_STYLE_SUCCESS = 3;
+declare const BUTTON_STYLE_DANGER = 4;
+export interface ApprovalViewInput {
+    registry: ComponentRegistry;
+    sessionId: string;
+    rpcId: string;
+    approvalId: string;
+    toolName: string;
+    reason?: string | undefined;
+    /** The approval deadline; the controls expire with it (13.4). */
+    expiresAtMs: number;
+}
+export interface ApprovalButton {
+    type: typeof BUTTON;
+    style: typeof BUTTON_STYLE_SUCCESS | typeof BUTTON_STYLE_DANGER;
+    label: string;
+    custom_id: string;
+}
+export interface ApprovalViewPayload {
+    content: string;
+    flags: typeof DISCORD_SUPPRESS_NOTIFICATIONS_FLAG;
+    components: Array<{
+        type: typeof ACTION_ROW;
+        components: ApprovalButton[];
+    }>;
+}
+/**
+ * Render one pending approval. Both controls resolve through the registry to
+ * `{ approvalId, action, expiresAtMs }`, so routing (13.2/13.3) recovers the
+ * pending record from durable state, never from the wire.
+ */
+export declare function renderApprovalControls(input: ApprovalViewInput): ApprovalViewPayload;
+export {};