@addozhang/dsh-discord 0.1.0

package/lib/discord/delivery.js

@@ -0,0 +1,31 @@
+/**
+ * Per-route delivery queues with nonce delivery identity. Writes to one
+ * Discord route (a channel, an interaction token) serialize FIFO so edits can
+ * never reorder terminal output; distinct routes proceed concurrently. A
+ * nonce identifies one in-process delivery claim and cannot be reused while
+ * known, which turns a double-send race into a loud local failure instead of
+ * duplicate Discord output.
+ */
+export function createRouteQueues() {
+    const activeNonces = new Map();
+    const tails = new Map();
+    function enqueue(route, op, identity) {
+        if (activeNonces.has(identity.nonce)) {
+            throw new TypeError(`delivery nonce '${identity.nonce}' is still known; duplicate claims are refused`);
+        }
+        const tail = tails.get(route) ?? Promise.resolve();
+        const run = tail.then(op, op);
+        // A failed op must not poison its route's tail.
+        tails.set(route, run.then(() => undefined, () => undefined));
+        // The release is registered before the caller can observe `run`, so a
+        // nonce is always forgettable by the time the caller's await resumes.
+        const release = () => {
+            if (activeNonces.get(identity.nonce) === run)
+                activeNonces.delete(identity.nonce);
+        };
+        void run.then(release, release);
+        activeNonces.set(identity.nonce, run);
+        return run;
+    }
+    return { enqueue };
+}

package/lib/discord/interaction-lifecycle.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Interaction response lifecycle. Discord grants exactly one callback per
+ * interaction inside a 3-second ack deadline and a webhook token with a
+ * bounded lifetime. This module models that budget as a state machine whose
+ * every rule violation is a plain value: double acknowledgements,
+ * past-deadline callbacks, and expired tokens refuse locally without a wire
+ * call, and wire-side unknown outcomes propagate untouched — the adapter
+ * never invents success it did not observe.
+ */
+import type { RestResult } from './rest.js';
+/** The interaction identity Discord delivered. */
+export interface InteractionHandle {
+    id: string;
+    token: string;
+    applicationId: string;
+}
+/** The two wire faces an interaction can use. */
+export interface InteractionWire {
+    callback(body: Record<string, unknown>): Promise<RestResult<unknown>>;
+    followUp(body: Record<string, unknown>): Promise<RestResult<unknown>>;
+}
+export interface LifecycleOptions {
+    /** Callback budget in ms; Discord's contract is 3000. */
+    ackDeadlineMs?: number;
+    /** Webhook token budget in ms; Discord's contract is 15 minutes. */
+    tokenLifetimeMs?: number;
+    /** Injectable clock for deterministic tests. */
+    now?: () => number;
+}
+export type LifecycleOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    error: 'already-acknowledged' | 'not-acknowledged' | 'past-ack-deadline' | 'token-expired' | 'wire-rejected' | 'wire-unknown';
+    detail?: string;
+};
+export declare function createInteractionSession(wire: InteractionWire, options?: LifecycleOptions): {
+    readonly state: 'fresh' | 'responded' | 'deferred';
+    respond(data: Record<string, unknown>): Promise<LifecycleOutcome>;
+    defer(): Promise<LifecycleOutcome>;
+    followUp(data: Record<string, unknown>): Promise<LifecycleOutcome>;
+};

package/lib/discord/interaction-lifecycle.js

@@ -0,0 +1,78 @@
+/**
+ * Interaction response lifecycle. Discord grants exactly one callback per
+ * interaction inside a 3-second ack deadline and a webhook token with a
+ * bounded lifetime. This module models that budget as a state machine whose
+ * every rule violation is a plain value: double acknowledgements,
+ * past-deadline callbacks, and expired tokens refuse locally without a wire
+ * call, and wire-side unknown outcomes propagate untouched — the adapter
+ * never invents success it did not observe.
+ */
+const DEFAULT_ACK_DEADLINE_MS = 3_000;
+const DEFAULT_TOKEN_LIFETIME_MS = 15 * 60_000;
+/** Discord's "Unknown interaction" code: the token no longer resolves. */
+const UNKNOWN_INTERACTION_CODE = 10062;
+/** Ephemeral message flag: only the invoking user sees the response. */
+const EPHEMERAL_FLAG = 64;
+const DISCORD_CALLBACK_RESPOND = 4;
+const DISCORD_CALLBACK_DEFER = 5;
+export function createInteractionSession(wire, options = {}) {
+    const ackDeadlineMs = options.ackDeadlineMs ?? DEFAULT_ACK_DEADLINE_MS;
+    const tokenLifetimeMs = options.tokenLifetimeMs ?? DEFAULT_TOKEN_LIFETIME_MS;
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    let state = 'fresh';
+    function withinAckDeadline() {
+        return now() - startedAt <= ackDeadlineMs;
+    }
+    function acknowledge(body) {
+        if (state !== 'fresh') {
+            return Promise.resolve({ ok: false, error: 'already-acknowledged' });
+        }
+        if (!withinAckDeadline()) {
+            return Promise.resolve({ ok: false, error: 'past-ack-deadline' });
+        }
+        return wire.callback(body).then((result) => {
+            if (result.outcome === 'completed') {
+                state = body['type'] === DISCORD_CALLBACK_DEFER ? 'deferred' : 'responded';
+                return { ok: true };
+            }
+            if (result.outcome === 'rejected') {
+                if (result.error.code === UNKNOWN_INTERACTION_CODE) {
+                    return { ok: false, error: 'token-expired' };
+                }
+                return { ok: false, error: 'wire-rejected', detail: result.error.message };
+            }
+            return { ok: false, error: 'wire-unknown', detail: result.reason };
+        });
+    }
+    return {
+        get state() {
+            return state;
+        },
+        respond(data) {
+            return acknowledge({ type: DISCORD_CALLBACK_RESPOND, data: { flags: EPHEMERAL_FLAG, ...data } });
+        },
+        defer() {
+            return acknowledge({ type: DISCORD_CALLBACK_DEFER, data: { flags: EPHEMERAL_FLAG } });
+        },
+        followUp(data) {
+            if (state === 'fresh') {
+                return Promise.resolve({ ok: false, error: 'not-acknowledged' });
+            }
+            if (now() - startedAt > tokenLifetimeMs) {
+                return Promise.resolve({ ok: false, error: 'token-expired' });
+            }
+            return wire.followUp({ flags: EPHEMERAL_FLAG, ...data }).then((result) => {
+                if (result.outcome === 'completed')
+                    return { ok: true };
+                if (result.outcome === 'rejected') {
+                    if (result.error.code === UNKNOWN_INTERACTION_CODE) {
+                        return { ok: false, error: 'token-expired' };
+                    }
+                    return { ok: false, error: 'wire-rejected', detail: result.error.message };
+                }
+                return { ok: false, error: 'wire-unknown', detail: result.reason };
+            });
+        },
+    };
+}

package/lib/discord/rest.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The typed Discord REST adapter. Every request resolves to exactly one of
+ * three outcomes — `completed`, `rejected`, or `unknown` — because cross-system
+ * delivery is never provably once: a refused request (4xx, exhausted 429) is
+ * definitive, while an unobservable outcome (network failure, abort,
+ * exhausted 5xx) may or may not have been applied and must be reconciled,
+ * never blindly retried by callers.
+ */
+export type RestMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+/** The untyped wire face injected for testability (fetch-shaped). */
+export interface FetchRequest {
+    readonly method: RestMethod;
+    readonly url: string;
+    readonly path: string;
+    readonly headers: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}
+export type FetchLike = (request: FetchRequest) => Promise<Response>;
+/** Discord's structured error body (subset the adapter reasons about). */
+export interface DiscordError {
+    code: number | string;
+    message: string;
+}
+export type RestResult<T> = {
+    outcome: 'completed';
+    status: number;
+    body: T;
+} | {
+    outcome: 'rejected';
+    status: number;
+    error: DiscordError;
+} | {
+    outcome: 'unknown';
+    reason: 'network-unreachable' | 'aborted';
+};
+export interface RestClientConfig {
+    token: string;
+    /** REST base; production points at https://discord.com/api/v10. */
+    apiBase?: string;
+}
+export interface RestClientOptions {
+    /** Extra attempts after the first; each 429/5xx retry consumes one. */
+    maxRetries?: number;
+    /** Base delay for 5xx backoff (doubles per attempt). */
+    backoffBaseMs?: number;
+    /** Cap for any single wait, so a hostile Retry-After cannot stall the adapter. */
+    maxDelayMs?: number;
+}
+export declare function createRestClient(config: RestClientConfig, options?: RestClientOptions, fetchLike?: FetchLike): {
+    request<T>(method: RestMethod, path: string, body?: unknown, init?: {
+        signal?: AbortSignal;
+    }): Promise<RestResult<T>>;
+};
+/**
+ * The route bucket a request counts against (discord-transport spec,
+ * "Rate-limit-aware delivery"): the first two path segments carry Discord's
+ * major parameters — `channels/:id`, `guilds/:id`, `webhooks/:id` — so every
+ * write into one channel shares one bucket and serializes behind it.
+ */
+export declare function routeBucketOf(path: string): string;
+export interface SharedRestClient {
+    request<T>(method: RestMethod, path: string, body?: unknown, init?: {
+        signal?: AbortSignal;
+    }): Promise<RestResult<T>>;
+}
+/**
+ * A process-wide REST client whose requests serialize per route bucket.
+ * Composition creates ONE shared instance (instead of a client per
+ * interaction) so concurrent sends, edits, and typing refreshes into the
+ * same channel never race the bucket's rate budget; distinct buckets run
+ * concurrently. Retries and outcome mapping stay the underlying client's.
+ */
+export declare function createSharedRestClient(config: RestClientConfig, options?: RestClientOptions, fetchLike?: FetchLike): SharedRestClient;

package/lib/discord/rest.js

@@ -0,0 +1,149 @@
+/**
+ * The typed Discord REST adapter. Every request resolves to exactly one of
+ * three outcomes — `completed`, `rejected`, or `unknown` — because cross-system
+ * delivery is never provably once: a refused request (4xx, exhausted 429) is
+ * definitive, while an unobservable outcome (network failure, abort,
+ * exhausted 5xx) may or may not have been applied and must be reconciled,
+ * never blindly retried by callers.
+ */
+const DEFAULT_API_BASE = 'https://discord.com/api/v10';
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_BASE_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+const sleep = (ms) => {
+    return new Promise(resolve => { setTimeout(resolve, ms); });
+};
+function parseDelayMs(response, fallbackMs, capMs) {
+    const header = response.headers.get('retry-after');
+    const seconds = header === null ? Number.NaN : Number.parseFloat(header);
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return fallbackMs;
+    return Math.min(seconds * 1_000, capMs);
+}
+function readError(body) {
+    if (typeof body === 'object' && body !== null) {
+        const record = body;
+        const code = record['code'];
+        const message = record['message'];
+        if ((typeof code === 'number' || typeof code === 'string') && typeof message === 'string') {
+            return { code, message };
+        }
+    }
+    return { code: 'unknown-discord-error', message: 'unparseable error body' };
+}
+export function createRestClient(config, options = {}, fetchLike) {
+    const apiBase = config.apiBase ?? DEFAULT_API_BASE;
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const backoffBaseMs = options.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+    const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+    const doFetch = fetchLike ?? (async (request) => {
+        const init = { method: request.method, headers: request.headers };
+        if (request.body !== undefined)
+            init.body = request.body;
+        if (request.signal !== undefined)
+            init.signal = request.signal;
+        return fetch(request.url, init);
+    });
+    async function attempt(request) {
+        try {
+            const response = await doFetch(request);
+            const text = await response.text();
+            let body;
+            try {
+                body = text === '' ? undefined : JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+            if (response.ok) {
+                return { outcome: 'completed', status: response.status, body: body };
+            }
+            const error = readError(body);
+            if (response.status === 429) {
+                // Discord did not apply the request; honor its Retry-After (bounded).
+                return { retry: '429', delayMs: parseDelayMs(response, backoffBaseMs, maxDelayMs) };
+            }
+            if (response.status >= 500) {
+                return { retry: '5xx' };
+            }
+            return { outcome: 'rejected', status: response.status, error };
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                return { outcome: 'unknown', reason: 'aborted' };
+            }
+            return { retry: 'network' };
+        }
+    }
+    async function request(method, path, body, init) {
+        for (let attemptNo = 0; attemptNo <= maxRetries; attemptNo += 1) {
+            if (init?.signal?.aborted === true) {
+                return { outcome: 'unknown', reason: 'aborted' };
+            }
+            const fetchRequest = {
+                method,
+                url: `${apiBase}${path}`,
+                path,
+                headers: {
+                    'authorization': `Bot ${config.token}`,
+                    ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                ...(init?.signal === undefined ? {} : { signal: init.signal }),
+            };
+            const outcome = await attempt(fetchRequest);
+            if ('retry' in outcome) {
+                const isFinalAttempt = attemptNo === maxRetries;
+                if (outcome.retry === '429') {
+                    // A 429 on the last attempt is a definitive rejection, not unknown:
+                    // Discord answered and refused, so the request was never applied.
+                    if (isFinalAttempt) {
+                        return { outcome: 'rejected', status: 429, error: { code: 'rate-limited', message: 'rate limit retries exhausted' } };
+                    }
+                    await sleep(outcome.delayMs);
+                    continue;
+                }
+                if (isFinalAttempt) {
+                    return { outcome: 'unknown', reason: 'network-unreachable' };
+                }
+                await sleep(Math.min(backoffBaseMs * 2 ** attemptNo, maxDelayMs));
+                continue;
+            }
+            return outcome;
+        }
+        return { outcome: 'unknown', reason: 'network-unreachable' };
+    }
+    return { request };
+}
+/**
+ * The route bucket a request counts against (discord-transport spec,
+ * "Rate-limit-aware delivery"): the first two path segments carry Discord's
+ * major parameters — `channels/:id`, `guilds/:id`, `webhooks/:id` — so every
+ * write into one channel shares one bucket and serializes behind it.
+ */
+export function routeBucketOf(path) {
+    const segments = path.split('/').filter(segment => segment.length > 0);
+    return segments.slice(0, 2).join('/');
+}
+/**
+ * A process-wide REST client whose requests serialize per route bucket.
+ * Composition creates ONE shared instance (instead of a client per
+ * interaction) so concurrent sends, edits, and typing refreshes into the
+ * same channel never race the bucket's rate budget; distinct buckets run
+ * concurrently. Retries and outcome mapping stay the underlying client's.
+ */
+export function createSharedRestClient(config, options = {}, fetchLike) {
+    const client = createRestClient(config, options, fetchLike);
+    const chains = new Map();
+    return {
+        request(method, path, body, init) {
+            const bucket = routeBucketOf(path);
+            const tail = chains.get(bucket) ?? Promise.resolve();
+            const run = tail.then(() => client.request(method, path, body, init));
+            // The bucket chain never rejects: a failed request must not wedge or
+            // discard the requests queued behind it.
+            chains.set(bucket, run.then(() => undefined, () => undefined));
+            return run;
+        },
+    };
+}

package/lib/discord/selector.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Autocomplete filtering and select-menu pagination as pure models. Discord
+ * caps autocomplete and select components at 25 entries; filtering ranks
+ * prefix matches above substring matches case-insensitively, and the pager
+ * budgets navigation entries into the same 25-slot limit so a page is always
+ * directly renderable as one component.
+ */
+/** A selectable entry as Discord renders it. */
+export interface SelectorOption {
+    label: string;
+    value: string;
+    description?: string;
+}
+/** Discord's hard cap for autocomplete choices and select-menu options. */
+export declare const DISCORD_SELECT_LIMIT = 25;
+/** Sentinel value shape for navigation entries; wrapped into opaque ids later. */
+export interface SelectorPage<T extends SelectorOption = SelectorOption> {
+    items: T[];
+    pageIndex: number;
+    pageCount: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    /** Value of the prev/next navigation entries present on this page. */
+    navValues: {
+        prev?: string;
+        next?: string;
+    };
+}
+/**
+ * Rank and cut options for an autocomplete response: empty queries keep the
+ * original order; otherwise prefix matches outrank substring matches and
+ * non-matches are dropped, ties keep input order.
+ */
+export declare function filterAutocomplete(options: readonly SelectorOption[], query: string, limit?: number): SelectorOption[];
+/**
+ * Slice options into one renderable page. Navigation entries spend slots of
+ * the same 25-entry budget. Out-of-range indices clamp into range.
+ */
+export declare function paginateSelector<T extends SelectorOption>(options: readonly T[], requestedIndex: number, sentinel?: string): SelectorPage<T>;

package/lib/discord/selector.js

@@ -0,0 +1,70 @@
+/**
+ * Autocomplete filtering and select-menu pagination as pure models. Discord
+ * caps autocomplete and select components at 25 entries; filtering ranks
+ * prefix matches above substring matches case-insensitively, and the pager
+ * budgets navigation entries into the same 25-slot limit so a page is always
+ * directly renderable as one component.
+ */
+/** Discord's hard cap for autocomplete choices and select-menu options. */
+export const DISCORD_SELECT_LIMIT = 25;
+/**
+ * Rank and cut options for an autocomplete response: empty queries keep the
+ * original order; otherwise prefix matches outrank substring matches and
+ * non-matches are dropped, ties keep input order.
+ */
+export function filterAutocomplete(options, query, limit = DISCORD_SELECT_LIMIT) {
+    const needle = query.trim().toLowerCase();
+    if (needle === '')
+        return options.slice(0, limit);
+    const prefix = [];
+    const substring = [];
+    for (const option of options) {
+        const haystack = option.label.toLowerCase();
+        if (haystack.startsWith(needle))
+            prefix.push(option);
+        else if (haystack.includes(needle))
+            substring.push(option);
+    }
+    return [...prefix, ...substring].slice(0, limit);
+}
+/**
+ * Derive a self-consistent page budget: a single page needs no navigation and
+ * holds 25 entries; two pages hold 24 data entries each (one nav slot);
+ * three or more pages hold 23 (middle pages need prev and next). The chosen
+ * page count always re-derives from its own per-page budget.
+ */
+function computeBudget(total) {
+    if (total <= DISCORD_SELECT_LIMIT)
+        return { pageCount: 1, perPage: DISCORD_SELECT_LIMIT };
+    for (const perPage of [DISCORD_SELECT_LIMIT - 1, DISCORD_SELECT_LIMIT - 2]) {
+        const pageCount = Math.ceil(total / perPage);
+        const requiredPerPage = pageCount === 2 ? DISCORD_SELECT_LIMIT - 1 : DISCORD_SELECT_LIMIT - 2;
+        if (perPage === requiredPerPage)
+            return { pageCount, perPage };
+    }
+    const perPage = DISCORD_SELECT_LIMIT - 2;
+    return { pageCount: Math.ceil(total / perPage), perPage };
+}
+/**
+ * Slice options into one renderable page. Navigation entries spend slots of
+ * the same 25-entry budget. Out-of-range indices clamp into range.
+ */
+export function paginateSelector(options, requestedIndex, sentinel = '__page__') {
+    const { pageCount, perPage } = computeBudget(options.length);
+    const pageIndex = Math.min(Math.max(requestedIndex, 0), pageCount - 1);
+    const hasPrev = pageIndex > 0;
+    const hasNext = pageIndex < pageCount - 1;
+    const navValues = {};
+    if (hasPrev)
+        navValues.prev = `${sentinel}:${String(pageIndex - 1)}`;
+    if (hasNext)
+        navValues.next = `${sentinel}:${String(pageIndex + 1)}`;
+    return {
+        items: options.slice(pageIndex * perPage, (pageIndex + 1) * perPage),
+        pageIndex,
+        pageCount,
+        hasPrev,
+        hasNext,
+        navValues,
+    };
+}

package/lib/discord/thread-port.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The REST-backed DiscordThreadPort (anchored source-message thread model). Thread creation
+ * is anchored to the source message (`message_id`): Discord moves the user's
+ * task message into the thread as its durable first post, so the thread
+ * opens with what reads exactly like the user's own task post. Crash-window
+ * recovery matches a thread by its anchored first message (the source
+ * message id). The author is joined to the thread so it appears in their
+ * sidebar. Outcomes map one-to-one onto the port's contract; retry policy
+ * belongs to the shared REST client.
+ */
+import type { DiscordThreadPort } from '../features/thread-creation.js';
+import type { RestMethod, RestResult } from './rest.js';
+/** Scripted route outcome for tests (shape mirrors RestClient outcomes). */
+export type ScriptedRoute = {
+    outcome: 'completed';
+    body: unknown;
+    status?: number;
+} | {
+    outcome: 'rejected';
+    status?: number;
+    error?: {
+        code: number | string;
+        message: string;
+    };
+} | {
+    outcome: 'unknown';
+    reason?: 'network-unreachable' | 'aborted';
+};
+/** The narrow request face this port needs (SharedRestClient-compatible). */
+export interface ThreadPortRest {
+    request<T>(method: RestMethod, path: string, body?: unknown): Promise<RestResult<T>>;
+}
+export interface ThreadPortOptions {
+    /** Live archive-duration reader (Discord accepts 60/1440/4320/10080). */
+    autoArchiveMinutes?: () => number | undefined;
+}
+export declare function createRestThreadPort(rest: ThreadPortRest, options?: ThreadPortOptions): DiscordThreadPort;

package/lib/discord/thread-port.js

@@ -0,0 +1,58 @@
+/**
+ * The REST-backed DiscordThreadPort (anchored source-message thread model). Thread creation
+ * is anchored to the source message (`message_id`): Discord moves the user's
+ * task message into the thread as its durable first post, so the thread
+ * opens with what reads exactly like the user's own task post. Crash-window
+ * recovery matches a thread by its anchored first message (the source
+ * message id). The author is joined to the thread so it appears in their
+ * sidebar. Outcomes map one-to-one onto the port's contract; retry policy
+ * belongs to the shared REST client.
+ */
+/** Bound the crash-recovery scan: never walk an unbounded thread list. */
+const MAX_THREADS_SCANNED = 25;
+/** OneDay auto-archive is the default; the deployment can widen or narrow it. */
+const DEFAULT_AUTO_ARCHIVE_MINUTES = 1440;
+export function createRestThreadPort(rest, options = {}) {
+    return {
+        async createThread(request) {
+            // Anchored creation uses the documented message-scoped route: Discord
+            // moves the source message into the thread as its first post. The
+            // channel-scoped route ignores a `message_id` body field, so anchoring
+            // silently no-ops there (seen live).
+            const made = await rest.request('POST', `/channels/${request.parentChannelId}/messages/${request.sourceMessageId}/threads`, {
+                name: request.name,
+                type: 11,
+                auto_archive_duration: options.autoArchiveMinutes?.() ?? DEFAULT_AUTO_ARCHIVE_MINUTES,
+            });
+            if (made.outcome === 'completed' && typeof made.body?.id === 'string') {
+                return { outcome: 'completed', threadId: made.body.id };
+            }
+            return made.outcome === 'rejected' ? { outcome: 'failed' } : { outcome: 'unknown' };
+        },
+        async findThreadBySource(request) {
+            // Active-thread listing is GUILD-scoped only: the channel-scoped
+            // `threads/active` route does not exist in the Discord API (archived
+            // listing is the only channel-level one), so recovery would 404 forever.
+            const listed = await rest.request('GET', `/guilds/${request.guildId}/threads/active`);
+            if (listed.outcome !== 'completed')
+                return { outcome: 'not-found' };
+            const threads = Array.isArray(listed.body?.threads) ? listed.body.threads : [];
+            for (const thread of threads.slice(0, MAX_THREADS_SCANNED)) {
+                const oldest = await rest.request('GET', `/channels/${thread.id}/messages?after=0&limit=1`);
+                if (oldest.outcome !== 'completed')
+                    continue;
+                const first = Array.isArray(oldest.body) ? oldest.body[0] : undefined;
+                if (first?.id === request.sourceMessageId) {
+                    return { outcome: 'found', threadId: thread.id };
+                }
+            }
+            return { outcome: 'not-found' };
+        },
+        async joinThread(request) {
+            // Idempotent per Discord (joining an existing member answers 2xx);
+            // callers treat this as best-effort and never fail the task on it.
+            const joined = await rest.request('PUT', `/channels/${request.threadId}/thread-members/${request.userId}`);
+            return joined.outcome === 'completed' ? { outcome: 'completed' } : { outcome: 'failed' };
+        },
+    };
+}