@addozhang/dsh-discord 0.1.0

package/lib/features/prompt-submission.js

@@ -0,0 +1,47 @@
+/**
+ * At-most-once prompt submission (design.md §5, §10, task 8.4). Every prompt
+ * carries a stable request id claimed before the DSH call. A same-id/same-
+ * hash delivery never resubmits; a different hash conflicts. A rejection ends
+ * that intent — an explicit user retry mints a NEW intent. An unknown
+ * admission is recorded as `unknown` and NEVER retried automatically; the
+ * reconciler checks DSH history/queue evidence, and an explicit retry (new
+ * intent) is the user's deliberate act.
+ */
+import { hashPayload } from '../state/intents.js';
+export function createPromptSubmissionFlow(deps) {
+    async function submit(requestId, request) {
+        const contentHash = await hashPayload({ sessionId: request.sessionId, prompt: request.prompt });
+        const claim = await deps.intents.claim({
+            messageId: requestId,
+            contentHash,
+            claimedAtMs: deps.nowMs(),
+        });
+        if (claim.outcome === 'conflict')
+            return { outcome: 'conflict' };
+        if (claim.outcome === 'duplicate') {
+            return { outcome: 'already-submitted' };
+        }
+        const submitted = await deps.prompts.submit({
+            requestId,
+            sessionId: request.sessionId,
+            prompt: request.prompt,
+            mode: 'queue',
+        });
+        if (submitted.outcome === 'accepted') {
+            await deps.intents.resolve(requestId, 'succeeded', deps.nowMs());
+            return { outcome: 'accepted' };
+        }
+        if (submitted.outcome === 'rejected') {
+            await deps.intents.resolve(requestId, 'failed', deps.nowMs());
+            return { outcome: 'rejected' };
+        }
+        await deps.intents.resolve(requestId, 'unknown', deps.nowMs());
+        return { outcome: 'unknown' };
+    }
+    return {
+        submitOnce: request => submit(request.requestId, request),
+        retry(request, { newRequestId }) {
+            return submit(newRequestId, request);
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Question expiry sweep (design.md §8, task 14.4). An ask left pending past
+ * its deadline must not strand DSH's tool call forever, and the adapter has
+ * no answer to give: the sweep atomically claims the batch — losing to any
+ * user click, which then owns the question — requests cancellation of the
+ * owning adapter-controlled turn (the port is session-scoped: DSH 0.1.1
+ * cancels a session's active turn), records whether the cancellation was
+ * accepted, and only then expires the Discord controls. The sweep's
+ * dependencies carry no answer port, so it structurally cannot synthesize a
+ * response.
+ */
+import type { QuestionStore } from './question-store.js';
+/** The DSH cancellation face for the owning adapter-controlled turn. */
+export interface DshTurnCancelPort {
+    cancel(input: {
+        sessionId: string;
+        requestId: string;
+    }): Promise<{
+        outcome: 'accepted';
+    } | {
+        outcome: 'rejected';
+        reason: string;
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+/** Face that retires the rendered select menus and submit button. */
+export interface QuestionControls {
+    disable(questionRpcId: string): Promise<void>;
+}
+export interface QuestionExpiryDeps {
+    store: QuestionStore;
+    cancelPort: DshTurnCancelPort;
+    controls: QuestionControls;
+    nowMs: () => number;
+}
+export interface QuestionExpiryResult {
+    /** Question rpc ids this sweep cancelled and retired. */
+    handled: string[];
+}
+export declare function sweepExpiredQuestions(deps: QuestionExpiryDeps): Promise<QuestionExpiryResult>;
+export interface AbandonQuestionDeps {
+    store: Pick<QuestionStore, 'claim' | 'get' | 'markExpired'>;
+    cancelPort: DshTurnCancelPort;
+    nowMs: () => number;
+}
+/**
+ * The controls never reached Discord, so nobody can ever answer: cancel the
+ * owning turn immediately instead of letting the sweep wait out the deadline
+ * with DSH's tool call hanging. Same claim discipline as the sweep — a user
+ * click that somehow won the race owns the question and this is a no-op.
+ */
+export declare function abandonUnrenderableQuestion(deps: AbandonQuestionDeps, questionRpcId: string): Promise<void>;

package/lib/features/question-expiry.js

@@ -0,0 +1,56 @@
+/**
+ * Question expiry sweep (design.md §8, task 14.4). An ask left pending past
+ * its deadline must not strand DSH's tool call forever, and the adapter has
+ * no answer to give: the sweep atomically claims the batch — losing to any
+ * user click, which then owns the question — requests cancellation of the
+ * owning adapter-controlled turn (the port is session-scoped: DSH 0.1.1
+ * cancels a session's active turn), records whether the cancellation was
+ * accepted, and only then expires the Discord controls. The sweep's
+ * dependencies carry no answer port, so it structurally cannot synthesize a
+ * response.
+ */
+export async function sweepExpiredQuestions(deps) {
+    const nowMs = deps.nowMs();
+    const handled = [];
+    for (const record of deps.store.listPendingExpired(nowMs)) {
+        // Atomic claim: a user click that beat the sweep owns the answer.
+        const claim = await deps.store.claim(record.questionRpcId);
+        if (claim.outcome !== 'claimed')
+            continue;
+        const cancelled = await deps.cancelPort.cancel({
+            sessionId: record.sessionId,
+            requestId: record.requestId,
+        });
+        const outcome = cancelled.outcome === 'accepted'
+            ? 'accepted'
+            : cancelled.outcome === 'rejected'
+                ? 'rejected'
+                : 'unknown';
+        await deps.store.markExpired(record.questionRpcId, outcome, deps.nowMs());
+        // Controls expire only after the cancellation outcome is on the record.
+        await deps.controls.disable(record.questionRpcId);
+        handled.push(record.questionRpcId);
+    }
+    return { handled };
+}
+/**
+ * The controls never reached Discord, so nobody can ever answer: cancel the
+ * owning turn immediately instead of letting the sweep wait out the deadline
+ * with DSH's tool call hanging. Same claim discipline as the sweep — a user
+ * click that somehow won the race owns the question and this is a no-op.
+ */
+export async function abandonUnrenderableQuestion(deps, questionRpcId) {
+    const claim = await deps.store.claim(questionRpcId);
+    if (claim.outcome !== 'claimed')
+        return;
+    const cancelled = await deps.cancelPort.cancel({
+        sessionId: claim.record.sessionId,
+        requestId: claim.record.requestId,
+    });
+    const outcome = cancelled.outcome === 'accepted'
+        ? 'accepted'
+        : cancelled.outcome === 'rejected'
+            ? 'rejected'
+            : 'unknown';
+    await deps.store.markExpired(questionRpcId, outcome, deps.nowMs());
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Question interaction routing (design.md §8, tasks 14.2/14.3). Select
+ * answers record against the pending batch through the opaque registry;
+ * choosing the reserved "Other" value opens the custom-text modal instead of
+ * recording; modal submits record the text. Labels outside the offered
+ * options, unknown question ids, and oversized text are refused as values —
+ * never silently dropped. Only the originating user on the owning thread may
+ * answer, and an incomplete batch never reaches DSH: one complete response
+ * or nothing.
+ */
+import type { ComponentRegistry } from '../discord/components.js';
+import { CUSTOM_ANSWER_VALUE } from './question-view.js';
+import { type DraftAnswerError, type EncodedQuestionAnswer, type QuestionStore } from './question-store.js';
+export { CUSTOM_ANSWER_VALUE };
+/** The DSH respond face for questions: the answer echoes the ask's rpcId. */
+export interface DshQuestionRespondPort {
+    respond(input: {
+        rpcId: string;
+        sessionId: string;
+        answer: EncodedQuestionAnswer;
+    }): Promise<{
+        outcome: 'confirmed';
+    } | {
+        outcome: 'rejected';
+        reason: string;
+    } | {
+        outcome: 'unknown';
+    }>;
+}
+export interface QuestionRoutingDeps {
+    registry: ComponentRegistry;
+    store: QuestionStore;
+    port: DshQuestionRespondPort;
+    nowMs: () => number;
+    /** Retires the rendered controls on a submitted (terminal) outcome. */
+    controls: {
+        disable(questionRpcId: string): Promise<void>;
+    };
+}
+export interface QuestionInteractionInput {
+    customId: string;
+    userId: string;
+    threadId: string;
+}
+/** The modal descriptor the wire layer turns into a Discord modal callback. */
+export interface ModalDescriptor {
+    /** Bounded title; Discord allows 45 characters. */
+    title: string;
+    custom_id: string;
+    textInput: {
+        label: string;
+        min_length: number;
+        max_length: number;
+        required: true;
+        style: 'paragraph';
+    };
+}
+export type QuestionInteractionOutcome = {
+    outcome: 'recorded';
+    complete: boolean;
+} | {
+    outcome: 'modal-requested';
+    modal: ModalDescriptor;
+} | {
+    outcome: 'submitted';
+} | {
+    outcome: 'already-resolved';
+} | {
+    outcome: 'denied';
+} | {
+    outcome: 'unknown-control';
+} | {
+    outcome: 'invalid-answer';
+    reason: DraftAnswerError;
+} | {
+    outcome: 'incomplete';
+} | {
+    outcome: 'unresolved';
+} | {
+    outcome: 'resolved-elsewhere';
+};
+export declare function handleSelectInput(deps: QuestionRoutingDeps, input: QuestionInteractionInput & {
+    values: string[];
+}): Promise<QuestionInteractionOutcome>;
+export declare function handleModalSubmit(deps: QuestionRoutingDeps, input: QuestionInteractionInput & {
+    text: string;
+}): QuestionInteractionOutcome;
+/**
+ * A `question/resolved` frame arrived from the Host: the ask was answered or
+ * cancelled by another client. The adapter retires its controls and never
+ * submits afterwards; a resolution the adapter already recorded (the user's
+ * own answer) stays first — the remote frame only retires the controls.
+ */
+export interface RemoteResolutionDeps {
+    store: Pick<QuestionStore, 'get' | 'markResolved'>;
+    controls: {
+        disable(questionRpcId: string): Promise<void>;
+    };
+    nowMs: () => number;
+}
+export declare function handleRemoteResolution(deps: RemoteResolutionDeps, input: {
+    questionRpcId: string;
+    outcome: 'answered' | 'cancelled';
+}): Promise<{
+    outcome: 'resolved-elsewhere';
+} | {
+    outcome: 'unknown-control';
+}>;

package/lib/features/question-routing.js

@@ -0,0 +1,162 @@
+/**
+ * Question interaction routing (design.md §8, tasks 14.2/14.3). Select
+ * answers record against the pending batch through the opaque registry;
+ * choosing the reserved "Other" value opens the custom-text modal instead of
+ * recording; modal submits record the text. Labels outside the offered
+ * options, unknown question ids, and oversized text are refused as values —
+ * never silently dropped. Only the originating user on the owning thread may
+ * answer, and an incomplete batch never reaches DSH: one complete response
+ * or nothing.
+ */
+import { CUSTOM_ANSWER_VALUE } from './question-view.js';
+import { MAX_CUSTOM_LENGTH, } from './question-store.js';
+export { CUSTOM_ANSWER_VALUE };
+function parseContext(context) {
+    const questionRpcId = context['questionRpcId'];
+    const action = context['action'];
+    if (typeof questionRpcId !== 'string')
+        return undefined;
+    if (action !== 'select' && action !== 'submit' && action !== 'modal')
+        return undefined;
+    const questionId = context['questionId'];
+    return {
+        questionRpcId,
+        action,
+        ...(typeof questionId === 'string' ? { questionId } : {}),
+    };
+}
+/** Milestone 1 question authorization: the originating user, own thread, point. */
+function authorize(record, input) {
+    return input.userId === record.actorUserId && input.threadId === record.threadId;
+}
+function resolveContext(deps, customId) {
+    const resolution = deps.registry.resolve(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.questionRpcId);
+    if (record === undefined)
+        return { outcome: 'unknown-control' };
+    return { context, record };
+}
+function modalTitle(question) {
+    const title = question.length <= 45 ? question : `${question.slice(0, 44)}…`;
+    return title;
+}
+export async function handleSelectInput(deps, input) {
+    const resolved = resolveContext(deps, input.customId);
+    if ('outcome' in resolved)
+        return resolved;
+    const { context, record } = resolved;
+    if (!authorize(record, input))
+        return { outcome: 'denied' };
+    if (record.state === 'resolved' || record.state === 'submitting' || record.state === 'expired') {
+        return { outcome: 'already-resolved' };
+    }
+    if (context.action === 'submit') {
+        const drafts = record.drafts();
+        const complete = record.questions.every(question => drafts.some(draft => draft.id === question.id));
+        if (!complete)
+            return { outcome: 'incomplete' };
+        // Atomic claim: pending or an explicit retry after an unconfirmed submit.
+        const claim = await deps.store.claim(context.questionRpcId);
+        if (claim.outcome !== 'claimed')
+            return { outcome: 'already-resolved' };
+        // A port that THROWS (distinct from an unknown outcome) is still an
+        // unconfirmed submit: park unresolved so the expiry sweeps and the
+        // user's own retry stay available — never leave the ask in submitting.
+        let submitted;
+        try {
+            submitted = await deps.port.respond({
+                rpcId: record.questionRpcId,
+                sessionId: record.sessionId,
+                answer: deps.store.encodeSubmitted(context.questionRpcId),
+            });
+        }
+        catch {
+            await deps.store.markUnresolved(context.questionRpcId, deps.nowMs());
+            return { outcome: 'unresolved' };
+        }
+        if (submitted.outcome === 'confirmed') {
+            await deps.store.markResolved(context.questionRpcId, 'answered', 'user', deps.nowMs());
+            // Terminal: retire the controls so stray clicks cannot follow.
+            // (disableControl never throws; the guard keeps the settled outcome.)
+            await deps.controls.disable(context.questionRpcId).catch(() => { });
+            return { outcome: 'submitted' };
+        }
+        await deps.store.markUnresolved(context.questionRpcId, deps.nowMs());
+        return { outcome: 'unresolved' };
+    }
+    if (context.action !== 'select' || context.questionId === undefined)
+        return { outcome: 'unknown-control' };
+    // The reserved Other value opens the custom-text modal instead of
+    // recording a label answer.
+    if (input.values.includes(CUSTOM_ANSWER_VALUE)) {
+        const question = record.questions.find(item => item.id === context.questionId);
+        if (question === undefined)
+            return { outcome: 'unknown-control' };
+        const customId = deps.registry.register({
+            questionRpcId: context.questionRpcId,
+            action: 'modal',
+            questionId: question.id,
+            expiresAtMs: record.expiresAtMs,
+        });
+        return {
+            outcome: 'modal-requested',
+            modal: {
+                title: modalTitle(question.question),
+                custom_id: customId,
+                textInput: {
+                    label: question.header ?? 'Your answer',
+                    min_length: 1,
+                    max_length: MAX_CUSTOM_LENGTH,
+                    required: true,
+                    style: 'paragraph',
+                },
+            },
+        };
+    }
+    const verdict = deps.store.setDraft(context.questionRpcId, {
+        id: context.questionId,
+        selected: input.values,
+    });
+    if (!verdict.ok)
+        return { outcome: 'invalid-answer', reason: verdict.error };
+    return { outcome: 'recorded', complete: verdict.complete };
+}
+export function handleModalSubmit(deps, input) {
+    const resolved = resolveContext(deps, input.customId);
+    if ('outcome' in resolved)
+        return resolved;
+    const { context, record } = resolved;
+    if (context.action !== 'modal' || context.questionId === undefined)
+        return { outcome: 'unknown-control' };
+    if (!authorize(record, input))
+        return { outcome: 'denied' };
+    if (record.state === 'resolved' || record.state === 'submitting' || record.state === 'expired') {
+        return { outcome: 'already-resolved' };
+    }
+    if (input.text.length === 0 || input.text.length > MAX_CUSTOM_LENGTH) {
+        return { outcome: 'invalid-answer', reason: 'custom-too-long' };
+    }
+    const verdict = deps.store.setDraft(context.questionRpcId, {
+        id: context.questionId,
+        selected: [],
+        custom: input.text,
+    });
+    if (!verdict.ok)
+        return { outcome: 'invalid-answer', reason: verdict.error };
+    return { outcome: 'recorded', complete: verdict.complete };
+}
+export async function handleRemoteResolution(deps, input) {
+    const record = deps.store.get(input.questionRpcId);
+    if (record === undefined)
+        return { outcome: 'unknown-control' };
+    if (record.state !== 'resolved') {
+        await deps.store.markResolved(input.questionRpcId, input.outcome, 'remote', deps.nowMs());
+    }
+    await deps.controls.disable(input.questionRpcId);
+    return { outcome: 'resolved-elsewhere' };
+}

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

@@ -0,0 +1,124 @@
+/**
+ * Pending question records and answer drafts (design.md §8, task 14.1). One
+ * record binds the ownership facts — Session, Discord Thread, owning
+ * adapter-submitted request ID, the answerable question rpcId, originating
+ * user — plus the full question list and one draft answer per question. DSH
+ * answers an ask() as a whole batch or not at all, so drafts may accumulate
+ * but never submit until every question is answered and valid.
+ *
+ * Bounds are Discord's component limits, enforced at open as fail-closed
+ * values: a batch the adapter cannot render is refused rather than silently
+ * truncated. Records are process-local by design — a Host restart invalidates
+ * pending questions, which reconciliation (15.7) treats as unresolved.
+ */
+/** One question as the adapter carries it (labels only; details render). */
+export interface QuestionItemView {
+    id: string;
+    question: string;
+    header?: string | undefined;
+    options?: ReadonlyArray<{
+        label: string;
+        description?: string | undefined;
+    }> | undefined;
+    multiSelect: boolean;
+}
+/** The full pending batch with its ownership facts. */
+export interface QuestionBatch {
+    questionRpcId: string;
+    sessionId: string;
+    threadId: string;
+    requestId: string;
+    actorUserId: string;
+    /** The ask deadline; the expiry sweep cancels the owning turn past it. */
+    expiresAtMs: number;
+    questions: readonly QuestionItemView[];
+}
+/** One validated draft answer. */
+export interface QuestionDraft {
+    id: string;
+    selected: string[];
+    custom?: string | undefined;
+}
+/** The DSH answer shape (AskUserQuestionAnswer) the adapter submits. */
+export interface EncodedQuestionAnswer {
+    answers: Array<{
+        id: string;
+        selected: string[];
+        custom?: string | undefined;
+    }>;
+}
+/** Discord action rows per message — one select each. */
+export declare const MAX_QUESTIONS_PER_BATCH = 5;
+/** Discord string-select option bound. */
+export declare const MAX_OPTIONS_PER_QUESTION = 25;
+/** Discord select option label bound (characters). */
+export declare const MAX_LABEL_LENGTH = 100;
+/** The adapter's own custom-text bound (inside Discord's 4000). */
+export declare const MAX_CUSTOM_LENGTH = 1000;
+export type OpenBatchError = 'too-many-questions' | 'too-many-options' | 'option-label-too-long' | 'options-required' | 'duplicate';
+export type DraftAnswerError = 'unknown-question' | 'invalid-label' | 'custom-too-long';
+export type ValidateResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: DraftAnswerError;
+};
+/** Validate one draft answer against its question (pure; also used by routing). */
+export declare function validateDraftAnswer(question: QuestionItemView | undefined, draft: QuestionDraft): ValidateResult;
+/** A batch is complete exactly when every question carries a draft. */
+export declare function isCompleteDraft(questions: readonly QuestionItemView[], drafts: ReadonlyMap<string, QuestionDraft>): boolean;
+/** Encode the complete draft into the DSH answer batch (pure). */
+export declare function encodeAnswer(questions: readonly QuestionItemView[], drafts: ReadonlyMap<string, QuestionDraft>): EncodedQuestionAnswer;
+export type OpenBatchResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: OpenBatchError;
+};
+/** One pending record as callers observe it. */
+export interface QuestionRecord extends QuestionBatch {
+    state: 'pending' | 'submitting' | 'resolved' | 'unresolved' | 'expired';
+    resolvedOutcome?: 'answered' | 'cancelled' | undefined;
+    resolvedBy?: 'user' | 'remote' | undefined;
+    expiredCancel?: 'accepted' | 'rejected' | 'unknown' | undefined;
+    draft(questionId: string): QuestionDraft | undefined;
+    drafts(): QuestionDraft[];
+}
+export interface QuestionStore {
+    get(questionRpcId: string): QuestionRecord | undefined;
+    open(batch: QuestionBatch): OpenBatchResult;
+    /** Validate then persist one question's draft; reports batch completion. */
+    setDraft(questionRpcId: string, draft: QuestionDraft): {
+        ok: true;
+        complete: boolean;
+    } | {
+        ok: false;
+        error: DraftAnswerError;
+    };
+    /** Snapshot the drafts (the submitter reads them under the claim). */
+    takeDrafts(questionRpcId: string): QuestionDraft[];
+    /** Encode the current drafts into the DSH answer batch. */
+    encodeSubmitted(questionRpcId: string): EncodedQuestionAnswer;
+    /**
+     * Atomically claim the batch for submission: pending (or an explicit retry
+     * after unresolved) flips to submitting exactly once per key.
+     */
+    claim(questionRpcId: string): Promise<{
+        outcome: 'claimed';
+        record: QuestionRecord;
+    } | {
+        outcome: 'not-claimable';
+        record: QuestionRecord;
+    } | {
+        outcome: 'unknown';
+    }>;
+    /** Record a DSH-confirmed user answer; terminal. */
+    markResolved(questionRpcId: string, outcome: 'answered' | 'cancelled', by: 'user' | 'remote', atMs: number): Promise<void>;
+    /** Retain the batch in an explicit unresolved state when DSH is silent. */
+    markUnresolved(questionRpcId: string, atMs: number): Promise<void>;
+    /** Pending batches whose deadline has passed, for the expiry sweep (14.4). */
+    listPendingExpired(atMs: number): QuestionRecord[];
+    /** Record the expiry: the owning turn's cancellation outcome, controls gone. */
+    markExpired(questionRpcId: string, cancel: 'accepted' | 'rejected' | 'unknown', atMs: number): Promise<void>;
+}
+export declare function createQuestionStore(): QuestionStore;