@krischoichoi/channel-harness 0.6.0

package/lib/interactions/question-state.d.ts

@@ -0,0 +1,106 @@
+import type { AskUserQuestionAnswerItem, AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions/types';
+import type { ChannelTarget } from '@krischoichoi/channel-core';
+/**
+ * How a question batch is presented on a channel conversation:
+ * - `'actions'` — the adapter supports `interactiveActions`; native buttons.
+ * - `'text'`    — text-only fallback; numbered options + free-text answers.
+ *
+ * Internal to `channel-harness`; NOT part of the public Channel Contract.
+ * Decided by capability negotiation (never by channel id).
+ */
+export type QuestionPresentationMode = 'actions' | 'text';
+/**
+ * Mint a short correlation token for a text-presented question (e.g.
+ * `Q-A13F7C`). It is a route/typing correlate for group/thread replies only,
+ * NEVER an auth credential — Authorization stays with the Access Gate +
+ * `allowedSenderId`. Kept short (not a UUID) so it is comfortable to type in
+ * group chat.
+ */
+export declare function newReplyToken(prefix?: string): string;
+/** What one bound channel action button does when pressed. */
+export interface PendingQuestionAction {
+    kind: 'option' | 'custom' | 'done' | 'skip';
+    optionIndex?: number;
+}
+/** A bound action button: opaque channel-facing id -> its pending question. */
+export interface PendingQuestionActionRef {
+    pending: PendingChannelQuestion;
+    action: PendingQuestionAction;
+}
+/** Explicit lifecycle so removed objects held by an async handler stay terminal. */
+export type QuestionLifecycleState = 'pending' | 'resolved' | 'expired' | 'aborted' | 'externally-settled';
+/**
+ * One in-flight question batch as presented on one channel conversation.
+ * Transport-neutral: `key` is whatever correlation id the active backend
+ * minted (the waterfall ask key today).
+ */
+export interface PendingChannelQuestion {
+    /** Backend correlation key; echoed back on resolve/cancel. */
+    key: string;
+    sessionId: string;
+    /** Official question items, fields carried verbatim (incl. `intent`). */
+    questions: AskUserQuestionItem[];
+    answers: AskUserQuestionAnswerItem[];
+    questionIndex: number;
+    selected: Set<string>;
+    awaitingCustom: boolean;
+    state: QuestionLifecycleState;
+    processing: boolean;
+    responding: boolean;
+    target: ChannelTarget;
+    conversationKey: string;
+    /**
+     * Only the sender whose inbound turn created the active reply context may
+     * answer (existing access semantics — authorization already happened at the
+     * bridge Access Gate before the question was presented).
+     */
+    allowedSenderId: string;
+    actionIds: Set<string>;
+    /** How this batch is presented (capability-negotiated, never channel id). */
+    presentationMode: QuestionPresentationMode;
+    /**
+     * Short correlation token for group/thread text replies when the platform
+     * cannot (or does not) map `replyTo` reliably. Regenerated per question via
+     * {@link advance}. Not a secret; never a substitute for authorization.
+     */
+    replyToken?: string;
+    /** Message that a free-text response must reply to in a group or forum. */
+    promptMessageId?: string;
+    messageId?: string;
+    renderedText?: string;
+    timer?: ReturnType<typeof setTimeout>;
+}
+/**
+ * Registry + timers for in-flight channel questions. All lookups are
+ * synchronous; the class never touches adapters or backends.
+ */
+export declare class QuestionStateStore {
+    private readonly byKey;
+    private readonly byConversation;
+    private readonly actions;
+    /**
+     * Register a freshly built pending question. Returns false (and registers
+     * nothing) when either its key was already presented (mux replay of a
+     * still-pending question — rpcId is reused verbatim on stream reopen) or
+     * its conversation already has a pending question.
+     */
+    register(pending: PendingChannelQuestion): boolean;
+    getByKey(key: string): PendingChannelQuestion | undefined;
+    getByConversation(conversationKey: string): PendingChannelQuestion | undefined;
+    /** Snapshot of every in-flight question (stop()/cancel-all iteration). */
+    all(): PendingChannelQuestion[];
+    /**
+     * Mint a bounded, opaque channel-facing action id and bind it. Ids stay
+     * within platform callback-payload budgets (e.g. Telegram callback_data).
+     */
+    bindAction(pending: PendingChannelQuestion, action: PendingQuestionAction): string;
+    findAction(actionId: string): PendingQuestionActionRef | undefined;
+    /** Drop every bound action of a pending question (re-render / settle). */
+    clearActions(pending: PendingChannelQuestion): void;
+    /** Arm the one-shot cancel timer for a pending question. */
+    armTimeout(pending: PendingChannelQuestion, timeoutMs: number, onTimeout: (pending: PendingChannelQuestion) => void): void;
+    clearTimer(pending: PendingChannelQuestion): void;
+    /** Fully unregister a settled question (timer + both indexes). */
+    remove(pending: PendingChannelQuestion): void;
+}
+//# sourceMappingURL=question-state.d.ts.map

package/lib/interactions/question-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-state.d.ts","sourceRoot":"","sources":["../../src/interactions/question-state.ts"],"names":[],"mappings":"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"}

package/lib/interactions/question-state.js

@@ -0,0 +1,99 @@
+/**
+ * Pending-question state machine for channel question interactions.
+ *
+ * Owns exactly the runtime bookkeeping of an in-flight question batch:
+ * the pending registry (by backend correlation key and by channel
+ * conversation — one pending question per conversation at a time), the
+ * action-button binding table, and the cancel timer. Rendering, channel
+ * binding and answer collection live in `question-presenter.ts`; the
+ * Harness-side transport lives in the backend modules.
+ *
+ * Question/answer shapes are the official `dsh-user-questions` types
+ * (`AskUserQuestionItem` / `AskUserQuestionAnswerItem`) — every official
+ * field (`detail` / `header` / `options` / `multiSelect` / `intent`) is
+ * carried verbatim; nothing is stripped or re-encoded here.
+ */
+import { randomBytes, randomUUID } from 'node:crypto';
+/**
+ * Mint a short correlation token for a text-presented question (e.g.
+ * `Q-A13F7C`). It is a route/typing correlate for group/thread replies only,
+ * NEVER an auth credential — Authorization stays with the Access Gate +
+ * `allowedSenderId`. Kept short (not a UUID) so it is comfortable to type in
+ * group chat.
+ */
+export function newReplyToken(prefix = 'Q-') {
+    const hex = randomBytes(3).toString('hex').toUpperCase();
+    return `${prefix}${hex}`;
+}
+/**
+ * Registry + timers for in-flight channel questions. All lookups are
+ * synchronous; the class never touches adapters or backends.
+ */
+export class QuestionStateStore {
+    byKey = new Map();
+    byConversation = new Map();
+    actions = new Map();
+    /**
+     * Register a freshly built pending question. Returns false (and registers
+     * nothing) when either its key was already presented (mux replay of a
+     * still-pending question — rpcId is reused verbatim on stream reopen) or
+     * its conversation already has a pending question.
+     */
+    register(pending) {
+        if (this.byKey.has(pending.key))
+            return false;
+        if (this.byConversation.has(pending.conversationKey))
+            return false;
+        this.byKey.set(pending.key, pending);
+        this.byConversation.set(pending.conversationKey, pending);
+        return true;
+    }
+    getByKey(key) {
+        return this.byKey.get(key);
+    }
+    getByConversation(conversationKey) {
+        return this.byConversation.get(conversationKey);
+    }
+    /** Snapshot of every in-flight question (stop()/cancel-all iteration). */
+    all() {
+        return [...this.byKey.values()];
+    }
+    /**
+     * Mint a bounded, opaque channel-facing action id and bind it. Ids stay
+     * within platform callback-payload budgets (e.g. Telegram callback_data).
+     */
+    bindAction(pending, action) {
+        const id = `uq_${randomUUID().replaceAll('-', '')}`;
+        pending.actionIds.add(id);
+        this.actions.set(id, { pending, action });
+        return id;
+    }
+    findAction(actionId) {
+        return this.actions.get(actionId);
+    }
+    /** Drop every bound action of a pending question (re-render / settle). */
+    clearActions(pending) {
+        for (const id of pending.actionIds)
+            this.actions.delete(id);
+        pending.actionIds.clear();
+    }
+    /** Arm the one-shot cancel timer for a pending question. */
+    armTimeout(pending, timeoutMs, onTimeout) {
+        this.clearTimer(pending);
+        pending.timer = setTimeout(() => onTimeout(pending), timeoutMs);
+    }
+    clearTimer(pending) {
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        pending.timer = undefined;
+    }
+    /** Fully unregister a settled question (timer + both indexes). */
+    remove(pending) {
+        this.clearTimer(pending);
+        this.byKey.delete(pending.key);
+        if (this.byConversation.get(pending.conversationKey) === pending) {
+            this.byConversation.delete(pending.conversationKey);
+        }
+    }
+}
+//# sourceMappingURL=question-state.js.map

package/lib/interactions/question-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-state.js","sourceRoot":"","sources":["../../src/interactions/question-state.ts"],"names":[],"mappings":"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"}

package/lib/interactions/question-text-answer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure parser for free-text answers to a channel-presented Harness question.
+ *
+ * Non-button adapters (`interactiveActions` absent / false) still receive the
+ * question as numbered plain text; the user replies with a number, the exact
+ * option label, a multi-select index list, "跳过", or arbitrary custom text.
+ * This module turns that raw inbound text into a structured answer — nothing
+ * here touches adapters, backends, sessions or platform payloads, so it is a
+ * straightforward unit test target.
+ *
+ * Rules (no fuzzy matching on purpose — a free sentence must not be mistaken
+ * for an option):
+ *
+ * - single-select: `"1"` -> options[0]; exact label -> that option;
+ *   `"跳过"` / `"跳过本题"` -> skip; any other non-empty text -> custom.
+ * - multi-select: `1,3`, `1，3` (full-width comma) and `1 3` (whitespace
+ *   separated) select numbered options; a single exact label also counts.
+ *   Labels are returned in OPTIONS order, deduplicated. Any index out of
+ *   range -> `{ kind: 'invalid', reason: 'option-out-of-range' }`. Ordinary
+ *   text that matches no legal option -> custom.
+ * - Empty text -> invalid.
+ */
+import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions/types';
+export type ParsedQuestionTextAnswer = {
+    kind: 'skip';
+} | {
+    kind: 'selected';
+    labels: string[];
+} | {
+    kind: 'custom';
+    text: string;
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+export declare function parseQuestionTextAnswer(question: AskUserQuestionItem, rawText: string): ParsedQuestionTextAnswer;
+//# sourceMappingURL=question-text-answer.d.ts.map

package/lib/interactions/question-text-answer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-text-answer.d.ts","sourceRoot":"","sources":["../../src/interactions/question-text-answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAEjF,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAiDxC,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,MAAM,GACd,wBAAwB,CAwB1B"}

package/lib/interactions/question-text-answer.js

@@ -0,0 +1,70 @@
+const SKIP_WORDS = new Set(['跳过', '跳过本题']);
+/**
+ * Split multi-select input into candidate index tokens. Accepts full-width
+ * commas and any run of whitespace/separators.
+ */
+function splitMultiSelectIndexes(rawText) {
+    // Normalise full-width comma + any comma/space runs into a single comma.
+    return rawText
+        .replace(/[\uFF0C]/g, ',')
+        .split(/[\s,]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+}
+function isNumeric(token) {
+    return /^\d+$/.test(token);
+}
+function parseMultiSelect(question, rawText) {
+    const options = question.options ?? [];
+    const selectedLabels = new Set();
+    const tokens = splitMultiSelectIndexes(rawText);
+    for (const token of tokens) {
+        if (!isNumeric(token)) {
+            // A single exact label is allowed as one selection; anything else falls
+            // through to custom below.
+            return { kind: 'custom', text: rawText };
+        }
+        const index = Number(token) - 1;
+        if (index < 0 || index >= options.length) {
+            return { kind: 'invalid', reason: 'option-out-of-range' };
+        }
+        selectedLabels.add(options[index].label);
+    }
+    if (selectedLabels.size === 0) {
+        return { kind: 'custom', text: rawText };
+    }
+    // Output in OPTIONS order, not user input order.
+    const ordered = options
+        .filter((option) => selectedLabels.has(option.label))
+        .map((option) => option.label);
+    return { kind: 'selected', labels: ordered };
+}
+export function parseQuestionTextAnswer(question, rawText) {
+    const text = rawText.trim();
+    if (text.length === 0)
+        return { kind: 'invalid', reason: 'empty' };
+    if (SKIP_WORDS.has(text))
+        return { kind: 'skip' };
+    if (question.multiSelect && (question.options?.length ?? 0) > 0) {
+        // Only route to multi-select parsing when options exist AND the input
+        // really looks like index input. Single exact labels still work here.
+        if (question.options?.some((option) => option.label === text)) {
+            return { kind: 'selected', labels: [text] };
+        }
+        const multi = parseMultiSelect(question, text);
+        // parseMultiSelect already returns custom for non-numeric text, so a
+        // plain-text label that passed the exact match above is the only way in
+        // that doesn't already return a valid answer.
+        return multi;
+    }
+    const options = question.options ?? [];
+    const numeric = /^\d+$/.test(text) ? Number(text) - 1 : -1;
+    if (numeric >= 0 && numeric < options.length) {
+        return { kind: 'selected', labels: [options[numeric].label] };
+    }
+    const match = options.find((option) => option.label === text);
+    if (match)
+        return { kind: 'selected', labels: [match.label] };
+    return { kind: 'custom', text };
+}
+//# sourceMappingURL=question-text-answer.js.map

package/lib/interactions/question-text-answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-text-answer.js","sourceRoot":"","sources":["../../src/interactions/question-text-answer.ts"],"names":[],"mappings":"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"}

package/lib/interactions/question-waterfall-backend.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type UserQuestionService } from '@deepseek-ai/dsh-user-questions';
+import type { ChannelLogger } from '@krischoichoi/channel-core';
+import type { QuestionInteractionBackend, QuestionInteractionCancellation, QuestionInteractionResolution, QuestionInteractionSink } from './question-backend.js';
+/**
+ * Narrow view over the official `ctx.userQuestions` service — the channel
+ * only probes its presence; asks are received via the waterfall event.
+ */
+export type ChannelUserQuestionService = UserQuestionService;
+export interface WaterfallQuestionBackendOptions {
+    /** Root Cordis context the `user-questions/request` listener registers on. */
+    ctx: Context;
+    logger: ChannelLogger;
+}
+/**
+ * The channel's answerer on the official question waterfall. One listener
+ * instance serves every Agent (untagged root registration receives all
+ * agent-scoped dispatches); requests the channel cannot present are
+ * delegated to the next answerer via `next()`.
+ */
+export declare class WaterfallQuestionBackend implements QuestionInteractionBackend {
+    private readonly options;
+    readonly kind: "waterfall";
+    private sink?;
+    private readonly pending;
+    private disposeListener?;
+    constructor(options: WaterfallQuestionBackendOptions);
+    start(sink: QuestionInteractionSink): void;
+    stop(): Promise<void>;
+    resolve(submission: QuestionInteractionResolution): Promise<void>;
+    cancel(cancellation: QuestionInteractionCancellation): Promise<void>;
+    /**
+     * One official waterfall ask. The channel claims the request by presenting
+     * it on the bound conversation and parking the answer promise; a declined
+     * presentation (no bound conversation, one already pending there, adapter
+     * absent / text unsupported) delegates to the next answerer.
+     */
+    private answer;
+    /** Detach the abort listener and run the settlement exactly once. */
+    private settle;
+}
+//# sourceMappingURL=question-waterfall-backend.d.ts.map

package/lib/interactions/question-waterfall-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-waterfall-backend.d.ts","sourceRoot":"","sources":["../../src/interactions/question-waterfall-backend.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,0BAA0B,EAC1B,+BAA+B,EAC/B,6BAA6B,EAC7B,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,mBAAmB,CAAC;AAU7D,MAAM,WAAW,+BAA+B;IAC9C,8EAA8E;IAC9E,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,0BAA0B;IAO7D,OAAO,CAAC,QAAQ,CAAC,OAAO;IANpC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IAErC,OAAO,CAAC,IAAI,CAAC,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,eAAe,CAAC,CAAa;gBAER,OAAO,EAAE,+BAA+B;IAErE,KAAK,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI;IAapC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAarB,OAAO,CAAC,UAAU,EAAE,6BAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjE,MAAM,CAAC,YAAY,EAAE,+BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1E;;;;;OAKG;YACW,MAAM;IAyDpB,qEAAqE;IACrE,OAAO,CAAC,MAAM;CASf"}

package/lib/interactions/question-waterfall-backend.js

@@ -0,0 +1,162 @@
+/**
+ * Unified question backend: the official `user-questions/request` waterfall.
+ *
+ * The question domain (`ask_user_question` -> `ctx.userQuestions.ask`)
+ * dispatches a Cordis waterfall event: every interested surface composes an
+ * answerer listener, claims the request by returning an answer, or delegates
+ * with `next()` (the official service rejects with `UserQuestionError`
+ * `NO_PROVIDER` when the whole waterfall delegates). Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) admits untagged listeners globally, so ONE
+ * root-level listener serves every profile:
+ *
+ * - headless: the channel is typically the only answerer, so a declined
+ *   presentation fails the ask ("decline -> next() -> NO_PROVIDER");
+ * - web profile: the official Web UI composes its own answerer on the same
+ *   waterfall, so a channel decline DELEGATES to it.
+ *
+ * The listener is registered on the ROOT context in `start()`; an abort or
+ * teardown rejects the ask with `UserQuestionError` (`ASK_ABORTED`).
+ *
+ * ## Why the listener is PREPENDED (ordering IS a contract)
+ *
+ * The scoped dispatch admits untagged root listeners, but a Cordis waterfall
+ * is SEQUENTIAL: the first listener that returns an answer vetoes every later
+ * one. The shipped `web` profile composes the official Remote/Web answerer
+ * (`@deepseek-ai/dsh-api-remotes`) on this same event, and that fiber applies
+ * at boot — long before the bridge (it only waits for `typertGateway`, while
+ * the bridge waits for `channels`) — so a plain `ctx.on()` registration loses
+ * every channel-bound ask to the browser:
+ *
+ * - a connected client materializes the Agent scope for ANY forwarded ask and
+ *   holds it until the human answers in the Web UI (`dsh-client-ui-user-questions`
+ *   claims whenever `sessions.scopeOf(owner)` resolves), so the channel never
+ *   sees the request;
+ * - with no client connected the forwarded request is parked in the gateway
+ *   (`pendingRemoteEvents`) with nobody to deliver it to and no auto-`next()`,
+ *   so the channel still never sees it.
+ *
+ * Prepending inverts that: a channel-bound conversation claims its own ask
+ * (buttons where the platform supports them, numbered-text fallback
+ * otherwise), and every ask the channel cannot present — no binding, no
+ * active reply context, unsupported text, or one already pending on that
+ * conversation — still delegates through `next()` to the Web answerer.
+ */
+import { randomUUID } from 'node:crypto';
+import { UserQuestionError, } from '@deepseek-ai/dsh-user-questions';
+/**
+ * The channel's answerer on the official question waterfall. One listener
+ * instance serves every Agent (untagged root registration receives all
+ * agent-scoped dispatches); requests the channel cannot present are
+ * delegated to the next answerer via `next()`.
+ */
+export class WaterfallQuestionBackend {
+    options;
+    kind = 'waterfall';
+    sink;
+    pending = new Map();
+    disposeListener;
+    constructor(options) {
+        this.options = options;
+    }
+    start(sink) {
+        if (this.disposeListener)
+            return;
+        this.sink = sink;
+        // `prepend: true` — see the class header: the official Remote/Web
+        // answerer registers first in the shipped web profile and would
+        // otherwise veto every channel-bound ask.
+        this.disposeListener = this.options.ctx.on('user-questions/request', (request, next) => this.answer(request, next), { prepend: true });
+    }
+    async stop() {
+        this.sink = undefined;
+        this.disposeListener?.();
+        this.disposeListener = undefined;
+        for (const pending of [...this.pending.values()]) {
+            this.settle(pending, () => {
+                pending.reject(new UserQuestionError('channel user-questions answerer was disposed', 'ASK_ABORTED'));
+            });
+        }
+    }
+    async resolve(submission) {
+        const pending = this.pending.get(submission.key);
+        if (!pending)
+            return;
+        this.settle(pending, () => pending.resolve(submission.answer));
+    }
+    async cancel(cancellation) {
+        const pending = this.pending.get(cancellation.key);
+        if (!pending)
+            return;
+        this.settle(pending, () => {
+            pending.reject(new UserQuestionError(cancellation.reason, 'ASK_ABORTED'));
+        });
+    }
+    /**
+     * One official waterfall ask. The channel claims the request by presenting
+     * it on the bound conversation and parking the answer promise; a declined
+     * presentation (no bound conversation, one already pending there, adapter
+     * absent / text unsupported) delegates to the next answerer.
+     */
+    async answer(request, next) {
+        const sink = this.sink;
+        // An ask without its owning live agent has no session to bind to a
+        // channel conversation — never the channel's business.
+        if (!sink || request.agent === undefined)
+            return next();
+        const sessionId = String(request.agent.id);
+        const key = `waterfall-${randomUUID()}`;
+        return new Promise((resolve, reject) => {
+            const pending = {
+                key,
+                resolve,
+                reject,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            };
+            const onAbort = () => {
+                this.settle(pending, () => {
+                    reject(new UserQuestionError('ask_user_question was aborted before the user answered', 'ASK_ABORTED'));
+                });
+                // Drop the channel-side presentation (buttons/state) after the ask
+                // itself settled; a racing channel answer becomes a backend no-op.
+                void sink.questionSettledExternally(key, 'aborted');
+            };
+            pending.onAbort = onAbort;
+            request.signal?.addEventListener('abort', onAbort, { once: true });
+            // Park the pending entry BEFORE presenting: the presenter hands the key
+            // to channel interactions, which resolve through `resolve()`/`cancel()`.
+            this.pending.set(key, pending);
+            void sink
+                .questionRequested({ key, sessionId, questions: request.questions })
+                .then(async (accepted) => {
+                if (accepted || !this.pending.has(key))
+                    return;
+                // The channel declined ownership — remove the parked entry and let
+                // the next answerer (e.g. the official Web UI) take the request.
+                this.settle(pending, () => { });
+                resolve(await next());
+            })
+                .catch((error) => {
+                if (this.pending.has(key)) {
+                    this.settle(pending, () => reject(error));
+                    return;
+                }
+                // Decline-path `next()` failure (e.g. NO_PROVIDER when no further
+                // answerer claims): the parked entry is already gone, so the ask
+                // promise itself must reject instead of hanging forever.
+                reject(error);
+            });
+        });
+    }
+    /** Detach the abort listener and run the settlement exactly once. */
+    settle(pending, settle) {
+        if (!this.pending.has(pending.key))
+            return;
+        this.pending.delete(pending.key);
+        if (pending.signal && pending.onAbort) {
+            pending.signal.removeEventListener('abort', pending.onAbort);
+        }
+        pending.onAbort = undefined;
+        settle();
+    }
+}
+//# sourceMappingURL=question-waterfall-backend.js.map

package/lib/interactions/question-waterfall-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-waterfall-backend.js","sourceRoot":"","sources":["../../src/interactions/question-waterfall-backend.ts"],"names":[],"mappings":"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"}

package/lib/lifecycle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bridge lifecycle assembly (doc §4 / §40).
+ *
+ * `startBridge(ctx, config, persistence?)` wires everything together and
+ * returns a disposer with the mandated stop order (doc 4.3):
+ * 1. stop new inbound (unregister the ChannelService listener);
+ * 2. drain active turns (`whenIdle`, bounded by a timeout);
+ * 3. RECONCILE replies from the Session durable log — final-reply correctness
+ *    comes from the (durable) Session log, not from the `session/event`
+ *    listener still being attached;
+ * 4. flush any replies still marked active (`ReplyRouter.flushAll`);
+ * 5. stop listening to `session/event`;
+ * 6. dispose all owned agent handles;
+ * 7. dispose the ReplyRouter (clear timers).
+ *
+ * Persistence is an OPTIONAL capability resolved LIVE at the use site: the
+ * caller passes a resolver (`() => ctx.get('sessionPersistence')`), and the
+ * gateway's `canResume()` / probes reflect whether it is present RIGHT NOW —
+ * mounting, unmounting, or replacing the service after startup is observed on
+ * the next probe (never a startup snapshot).
+ *
+ * Two reply-context correlation listeners (`agent/inbox/claimed` and
+ * `agent/inbox/discarded`) are registered on the Cordis context; they are
+ * plain `ctx.on`, so they auto-dispose with the context and stay active for
+ * the whole bridge lifetime.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
+import type { ChannelEvent } from '@krischoichoi/channel-core';
+import type { Config } from './config.js';
+export interface BridgeLifecycle {
+    dispose(): Promise<void>;
+    handleChannelEvent(event: ChannelEvent): Promise<void>;
+}
+export declare function startBridge(ctx: Context, config: Config, resolvePersistence?: () => SessionPersistence | undefined): BridgeLifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,OAAO,KAAK,EAAkB,YAAY,EAAgD,MAAM,4BAA4B,CAAC;AAC7H,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAsB1C,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,kBAAkB,CAAC,EAAE,MAAM,kBAAkB,GAAG,SAAS,GACxD,eAAe,CAgOjB"}