dsh-connect 0.9.0 → 0.9.2

package/lib/interaction.js

@@ -2,6 +2,15 @@ import { messages } from "./i18n.js";
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Whether the host has already given up on a request (its signal fired).
+ * A free function on purpose: reading `req.signal?.aborted` directly and
+ * re-checking it later would be narrowed away by the first check's early
+ * return, even though the signal can fire across an `await`.
+ */
+function hostCancelled(signal) {
+    return signal?.aborted === true;
+}
 /**
  * Decode a free-text chat reply into the answer for one question. Exact label
  * match wins; otherwise space/comma separated numbers are mapped onto the
@@ -40,9 +49,8 @@ function decodeChoice(q, choice) {
     return { selected: [opt.label] };
 }
 /**
- * Bridge user choices and permission approvals from DSH into the chat channel.
- * Subscribes once to the host mux stream; frames for connect-bound sessions are
- * rendered as interactive cards and answered via `apiProxy.respond`.
+ * Answer the host's user-question and approval waterfalls from the chat
+ * channel. Registered once, eagerly, at construction time.
  */
 export class InteractionBridge {
     ctx;
@@ -50,27 +58,29 @@ export class InteractionBridge {
     bindings;
     config;
     pending = new Map();
-    started = false;
-    apiProxy;
-    controller;
     constructor(ctx, adapters, bindings, config) {
         this.ctx = ctx;
         this.adapters = adapters;
         this.bindings = bindings;
         this.config = config;
-        this.ctx.effect(() => () => this.controller?.abort(), "connect: interaction bridge");
+        const seam = ctx;
+        ctx.effect(() => this.register(seam, "user-questions/request", this.answerQuestion.bind(this)), "connect: user-questions answerer");
+        ctx.effect(() => this.register(seam, "approval/request", this.answerApproval.bind(this)), "connect: approval answerer");
+        ctx.effect(() => () => {
+            // Teardown: unblock every in-flight card so its loop unwinds.
+            for (const p of [...this.pending.values()])
+                this.settle(p);
+        }, "connect: interaction bridge");
     }
-    /** Open the mux subscription (idempotent). No-op when the host api-proxy is absent. */
-    start() {
-        if (this.started)
-            return;
-        const apiProxy = this.ctx.get("apiProxy");
-        if (apiProxy?.events?.mux === undefined || apiProxy.respond === undefined)
-            return;
-        this.started = true;
-        this.apiProxy = apiProxy;
-        this.controller = new AbortController();
-        void this.run(this.controller.signal);
+    /** Register one waterfall listener, tolerating a host without the event API. */
+    register(seam, name, listener) {
+        try {
+            return seam.on(name, listener, { prepend: true });
+        }
+        catch (error) {
+            this.log(`connect: could not register the "${name}" answerer: ${String(error)}`);
+            return () => undefined;
+        }
     }
     /** Whether a question/approval is waiting on an answer in this chat. */
     pendingFor(chatKey) {
@@ -90,254 +100,153 @@ export class InteractionBridge {
         this.recordAnswer(p, q.id, answer);
         return true;
     }
-    async run(signal) {
-        const stream = this.apiProxy.events.mux({ rpcId: "connect-interaction", payload: {} }, signal);
-        try {
-            for await (const { rpcId, payload } of stream) {
-                try {
-                    this.onFrame(rpcId, payload);
-                }
-                catch (error) {
-                    this.log(`connect: interaction frame handler error: ${String(error)}`);
-                }
-            }
-        }
-        catch (error) {
-            this.log(`connect: interaction mux stream closed: ${String(error)}`);
-        }
-    }
-    onFrame(rpcId, payload) {
-        switch (payload.type) {
-            case "question/requested": {
-                const sessionId = String(payload.sessionId ?? "");
-                const questions = Array.isArray(payload.questions) ? payload.questions : [];
-                if (sessionId === "" || questions.length === 0)
-                    return;
-                for (const target of this.targetsFor(sessionId)) {
-                    this.presentQuestion(target, rpcId, sessionId, questions);
-                }
-                break;
-            }
-            case "approval/requested": {
-                const sessionId = String(payload.sessionId ?? "");
-                const approvalId = String(payload.approvalId ?? "");
-                if (sessionId === "" || approvalId === "")
-                    return;
-                const toolName = String(payload.toolName ?? "?");
-                const reason = typeof payload.reason === "string" ? payload.reason : undefined;
-                for (const target of this.targetsFor(sessionId)) {
-                    this.presentApproval(target, rpcId, sessionId, approvalId, toolName, reason);
-                }
-                break;
-            }
-            case "question/resolved": {
-                // Someone (Web GUI or this bridge) answered/cancelled the ask.
-                const questionRpcId = String(payload.questionRpcId ?? "");
-                for (const p of [...this.pending.values()]) {
-                    if (p.kind === "question" && p.rpcId === questionRpcId)
-                        this.settle(p);
-                }
-                break;
-            }
-            case "session/event": {
-                const event = payload.event;
-                if (event?.type !== "turn/end")
-                    return;
-                const sessionId = String(payload.sessionId ?? "");
-                for (const p of [...this.pending.values()]) {
-                    if (p.sessionId === sessionId)
-                        this.settle(p);
-                }
-                break;
-            }
-            default:
-                break;
-        }
-    }
-    /** Every connect-bound chat that currently uses this session (active or mirrored). */
-    targetsFor(sessionId) {
-        const out = [];
-        for (const binding of this.bindings.list()) {
-            if (binding.sessionId !== sessionId && binding.webMirrorSessionId !== sessionId)
-                continue;
-            const adapter = this.adapters.get(binding.channel);
-            if (adapter === undefined)
-                continue;
-            out.push({ binding, adapter });
-        }
-        return out;
-    }
-    presentQuestion(target, rpcId, sessionId, questions) {
-        // One pending ask per session — a replayed frame after the mux reopens
-        // must not stack duplicate cards.
-        for (const p of this.pending.values()) {
-            if (p.sessionId === sessionId)
-                return;
-        }
+    // ── user-questions/request ─────────────────────────────────────────────────
+    async answerQuestion(req, next) {
+        const questions = Array.isArray(req.questions) ? req.questions : [];
+        const sessionId = req.agent?.id;
+        if (sessionId === undefined || sessionId === "" || questions.length === 0)
+            return next();
+        if (hostCancelled(req.signal))
+            return next();
+        const target = this.claimTarget(sessionId);
+        if (target === undefined)
+            return next();
         const interaction = {
             kind: "question",
             chatKey: target.binding.chatKey,
             chatType: target.binding.chatType,
             adapter: target.adapter,
             sessionId,
-            rpcId,
             language: target.binding.language ?? this.config.language,
             questions,
             answers: new Map(),
             current: 0,
+            waiters: new Set(),
             controller: new AbortController(),
             settled: false,
         };
         this.pending.set(interaction.chatKey, interaction);
-        this.stepQuestion(interaction);
-    }
-    presentApproval(target, rpcId, sessionId, approvalId, toolName, reason) {
-        for (const p of this.pending.values()) {
-            if (p.sessionId === sessionId)
-                return;
-        }
-        const interaction = {
-            kind: "approval",
-            chatKey: target.binding.chatKey,
-            chatType: target.binding.chatType,
-            adapter: target.adapter,
-            sessionId,
-            rpcId,
-            approvalId,
-            toolName,
-            ...(reason === undefined ? {} : { reason }),
-            language: target.binding.language ?? this.config.language,
-            controller: new AbortController(),
-            settled: false,
-        };
-        this.pending.set(interaction.chatKey, interaction);
-        void this.presentApprovalLoop(interaction);
-    }
-    /** Advance to the next unanswered question, or settle once all are answered. */
-    stepQuestion(interaction) {
-        while (interaction.current < interaction.questions.length &&
-            interaction.answers.has(interaction.questions[interaction.current].id)) {
-            interaction.current += 1;
+        const onAbort = () => this.settle(interaction);
+        req.signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const answers = await this.runQuestions(interaction);
+            if (answers === undefined)
+                return next();
+            const t = messages(interaction.language);
+            await interaction.adapter.sendText(this.outbound(interaction), t.answerReceived).catch(() => undefined);
+            this.log(`connect: answered ${answers.length} question(s) from ${interaction.chatKey}`);
+            return { answers };
         }
-        if (interaction.current >= interaction.questions.length) {
-            void this.settleQuestion(interaction);
-            return;
+        catch (error) {
+            // The card could not be delivered (or the channel errored): hand the
+            // request back so the Web GUI — or the host's fail-closed default — gets it.
+            this.log(`connect: question presentation failed (${interaction.chatKey}): ${String(error)}`);
+            return next();
         }
-        const q = interaction.questions[interaction.current];
-        const hasOptions = Array.isArray(q.options) && q.options.length > 0;
-        if (hasOptions) {
-            void this.presentQuestionButtons(interaction, q);
+        finally {
+            req.signal?.removeEventListener("abort", onAbort);
+            this.settle(interaction);
         }
-        else {
-            void this.presentQuestionText(interaction, q);
+    }
+    /** Ask every question in turn. `undefined` = the flow was interrupted. */
+    async runQuestions(interaction) {
+        for (let i = 0; i < interaction.questions.length; i += 1) {
+            interaction.current = i;
+            const q = interaction.questions[i];
+            if (interaction.answers.has(q.id))
+                continue;
+            const answered = await this.askOne(interaction, q);
+            if (!answered)
+                return undefined;
         }
+        return interaction.questions.map((q) => {
+            const a = interaction.answers.get(q.id);
+            const custom = a?.custom?.trim();
+            return {
+                id: q.id,
+                selected: a?.selected ?? [],
+                ...(custom === undefined || custom === "" ? {} : { custom }),
+            };
+        });
     }
-    async presentQuestionButtons(interaction, q) {
+    async askOne(interaction, q) {
+        const options = Array.isArray(q.options) ? q.options : [];
+        if (options.length === 0)
+            return this.askByText(interaction, q);
         const t = messages(interaction.language);
-        const options = (q.options ?? []).map((o, i) => ({
-            id: `q:${q.id}:${i}`,
-            label: o.label,
-        }));
         const prompt = {
             title: t.questionCardTitle,
             description: this.questionPromptText(interaction, q),
-            options,
+            options: options.map((o, i) => ({ id: `q:${q.id}:${i}`, label: o.label })),
             footer: q.multiSelect === true ? `${t.questionCardHint}\n${t.questionMultiHint}` : t.questionCardHint,
         };
-        // One answered question steps the interaction to the next one; settling is
-        // the flow's job (stepQuestion → settleQuestion), not this loop's.
-        await this.presentLoop(interaction, prompt, (choice) => {
-            if (choice === undefined)
-                return undefined;
-            const answer = decodeChoice(q, choice);
-            if (answer === undefined)
-                return undefined;
-            this.recordAnswer(interaction, q.id, answer);
-            return "answered";
-        });
+        while (!interaction.controller.signal.aborted && !interaction.settled) {
+            const { choice, messageId } = await interaction.adapter.promptChoice(this.outbound(interaction), prompt, interaction.messageId, interaction.controller.signal);
+            // An adapter aborted before presenting has no card to point at; keep the
+            // last real id so the next round still targets the right message.
+            if (messageId !== "")
+                interaction.messageId = messageId;
+            if (choice !== undefined) {
+                const answer = decodeChoice(q, choice);
+                if (answer !== undefined) {
+                    this.recordAnswer(interaction, q.id, answer);
+                    return true;
+                }
+                continue;
+            }
+            // The card expired without a tap. Re-present the same card in place so
+            // the choice stays clickable for as long as the agent is waiting.
+            if (interaction.controller.signal.aborted || interaction.settled)
+                break;
+            await delay(1000);
+        }
+        return false;
     }
-    async presentQuestionText(interaction, q) {
+    /** Options-free question: the user answers by sending an ordinary message. */
+    async askByText(interaction, q) {
         const t = messages(interaction.language);
         const target = this.outbound(interaction);
         await interaction.adapter.sendText(target, t.questionTextHint(q.question)).catch(() => undefined);
         while (!interaction.controller.signal.aborted && !interaction.settled) {
             if (interaction.answers.has(q.id))
-                return;
-            await delay(60_000);
-            if (interaction.controller.signal.aborted || interaction.settled || interaction.answers.has(q.id))
-                return;
+                return true;
+            const waited = await this.waitForAnswer(interaction, 60_000);
+            if (waited === "answered")
+                return true;
+            if (waited === "stopped")
+                return false;
             await interaction.adapter.sendText(target, t.questionWaiting(q.question)).catch(() => undefined);
         }
-    }
-    async presentApprovalLoop(interaction) {
-        const t = messages(interaction.language);
-        const prompt = {
-            title: t.approvalCardTitle,
-            description: t.approvalAsk(interaction.toolName, interaction.reason),
-            options: [
-                { id: "approval:allow", label: t.approveLabel },
-                { id: "approval:reject", label: t.rejectLabel },
-            ],
-        };
-        const result = await this.presentLoop(interaction, prompt, async (choice, messageId) => {
-            if (choice !== "approval:allow" && choice !== "approval:reject")
-                return undefined;
-            const outcome = choice === "approval:allow" ? "allowed-once" : "rejected";
-            // Submit the decision through the host respond path and wait for the
-            // verdict — this is what tells the user whether their tap actually took
-            // effect (the Web GUI may have answered first, or the request expired).
-            const accepted = await this.respond(interaction.rpcId, {
-                sessionId: interaction.sessionId,
-                approvalId: interaction.approvalId,
-                outcome,
-            });
-            if (accepted) {
-                // Replace the buttons with a clear "done" state so the user sees the
-                // decision landed even if the chat keeps streaming afterwards.
-                await interaction.adapter
-                    .closeMenu(messageId, t.approvalDone(outcome, interaction.toolName))
-                    .catch(() => undefined);
-            }
-            else {
-                // Not accepted: the approval was already handled elsewhere, or is
-                // stale. Say so explicitly instead of silently ignoring the tap.
-                await interaction.adapter
-                    .closeMenu(messageId, t.approvalStale)
-                    .catch(() => undefined);
-                await interaction.adapter
-                    .sendText(this.outbound(interaction), t.approvalStale)
-                    .catch(() => undefined);
-            }
-            return "answered";
-        });
-        if (result === "answered")
-            this.settle(interaction);
+        return false;
     }
     /**
-     * Keep one interactive card alive until the user answers (or the ask is
-     * cancelled). The channel's choice prompt expires after its own idle
-     * timeout; on expiry the same card is re-presented in place so the choice
-     * stays clickable for as long as the agent waits. Resolves `"answered"`
-     * when `onChoice` accepted a choice, `"stopped"` otherwise.
-     *
-     * `onChoice` may be async and receives the card's message id (for feedback
-     * such as updating the card once the decision is delivered). A thrown
-     * `onChoice` error resolves the loop as `"stopped"` (best-effort channel).
+     * Wait until an answer is recorded, the flow stops, or `timeoutMs` elapses.
+     * Resolves (never rejects) and always removes its own listener and timer.
      */
-    async presentLoop(interaction, prompt, onChoice) {
-        while (!interaction.controller.signal.aborted && !interaction.settled) {
-            try {
-                const { choice, messageId } = await interaction.adapter.promptChoice(this.outbound(interaction), prompt, interaction.messageId);
-                interaction.messageId = messageId;
-                if ((await onChoice(choice, messageId)) === "answered")
-                    return "answered";
-            }
-            catch {
-                return "stopped";
-            }
-            await delay(1200);
-        }
-        return "stopped";
+    waitForAnswer(interaction, timeoutMs) {
+        return new Promise((resolve) => {
+            let done = false;
+            let timer;
+            const finish = (result) => {
+                if (done)
+                    return;
+                done = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                interaction.waiters.delete(onWake);
+                interaction.controller.signal.removeEventListener("abort", onStop);
+                resolve(result);
+            };
+            const onWake = () => finish("answered");
+            const onStop = () => finish("stopped");
+            interaction.waiters.add(onWake);
+            interaction.controller.signal.addEventListener("abort", onStop, { once: true });
+            timer = setTimeout(() => finish("timeout"), timeoutMs);
+            timer.unref?.();
+            // The signal may have fired between the loop check and this registration.
+            if (interaction.controller.signal.aborted)
+                finish("stopped");
+        });
     }
     questionPromptText(interaction, q) {
         const t = messages(interaction.language);
@@ -352,57 +261,109 @@ export class InteractionBridge {
         if (interaction.answers.has(qid))
             return;
         interaction.answers.set(qid, answer);
-        this.stepQuestion(interaction);
-    }
-    /** All questions answered — deliver the answers through the host respond path. */
-    async settleQuestion(interaction) {
-        if (interaction.settled)
-            return;
-        interaction.settled = true;
-        const answers = interaction.questions.map((q) => {
-            const a = interaction.answers.get(q.id);
-            return {
-                id: q.id,
-                selected: a?.selected ?? [],
-                ...(a?.custom !== undefined && a.custom.trim() !== "" ? { custom: a.custom.trim() } : {}),
-            };
-        });
-        const accepted = await this.respond(interaction.rpcId, {
-            sessionId: interaction.sessionId,
-            answer: { answers },
-        });
-        const t = messages(interaction.language);
-        if (accepted) {
-            await interaction.adapter.sendText(this.outbound(interaction), t.answerReceived).catch(() => undefined);
-        }
-        else {
-            // The host did not accept the answers (already answered elsewhere, or
-            // the question expired) — tell the user their reply had no effect.
-            await interaction.adapter.sendText(this.outbound(interaction), t.questionStale).catch(() => undefined);
-        }
-        this.settle(interaction);
+        for (const wake of [...interaction.waiters])
+            wake();
     }
-    async respond(rpcId, value) {
-        if (this.apiProxy?.respond === undefined)
-            return false;
+    // ── approval/request ───────────────────────────────────────────────────────
+    async answerApproval(req, next) {
+        const sessionId = req.agent?.id;
+        if (sessionId === undefined || sessionId === "" || hostCancelled(req.signal))
+            return next();
+        const target = this.claimTarget(sessionId);
+        if (target === undefined)
+            return next();
+        const t = messages(target.binding.language ?? this.config.language);
+        const interaction = {
+            kind: "approval",
+            chatKey: target.binding.chatKey,
+            chatType: target.binding.chatType,
+            adapter: target.adapter,
+            sessionId,
+            language: target.binding.language ?? this.config.language,
+            toolName: req.toolName,
+            ...(req.reason === undefined ? {} : { reason: req.reason }),
+            controller: new AbortController(),
+            settled: false,
+        };
+        this.pending.set(interaction.chatKey, interaction);
+        const onAbort = () => this.settle(interaction);
+        req.signal?.addEventListener("abort", onAbort, { once: true });
+        const prompt = {
+            title: t.approvalCardTitle,
+            description: t.approvalAsk(req.toolName, req.reason),
+            options: [
+                { id: "approval:allow", label: t.approveLabel },
+                { id: "approval:reject", label: t.rejectLabel },
+            ],
+        };
         try {
-            const res = await this.apiProxy.respond({
-                type: "client-response",
-                rpcId,
-                result: { ok: true, value },
-            });
-            return res?.accepted === true;
+            while (!interaction.controller.signal.aborted && !interaction.settled) {
+                const { choice, messageId } = await interaction.adapter.promptChoice(this.outbound(interaction), prompt, interaction.messageId, interaction.controller.signal);
+                if (messageId !== "")
+                    interaction.messageId = messageId;
+                if (choice !== "approval:allow" && choice !== "approval:reject") {
+                    if (interaction.controller.signal.aborted || interaction.settled)
+                        break;
+                    // Card expired without a tap — re-present it and keep waiting. The
+                    // host cancels the request itself if it stops caring (its signal
+                    // fires, which aborts us and lands on `next()` below).
+                    await delay(1000);
+                    continue;
+                }
+                if (hostCancelled(req.signal)) {
+                    // Decided, but too late: the host already gave up on this request.
+                    await interaction.adapter.closeMenu(messageId, t.approvalStale).catch(() => undefined);
+                    return next();
+                }
+                const outcome = choice === "approval:allow" ? "allowed-once" : "rejected";
+                // Replace the buttons with a clear "done" state so the user sees the
+                // decision landed even if the chat keeps streaming afterwards.
+                await interaction.adapter.closeMenu(messageId, t.approvalDone(outcome, req.toolName)).catch(() => undefined);
+                this.log(`connect: approval ${outcome} for ${req.toolName} from ${interaction.chatKey}`);
+                return outcome;
+            }
+            return next();
         }
         catch (error) {
-            this.log(`connect: interaction respond failed: ${String(error)}`);
-            return false;
+            this.log(`connect: approval presentation failed (${interaction.chatKey}): ${String(error)}`);
+            return next();
+        }
+        finally {
+            req.signal?.removeEventListener("abort", onAbort);
+            this.settle(interaction);
+        }
+    }
+    // ── shared ─────────────────────────────────────────────────────────────────
+    /**
+     * Pick the one chat that owns `sessionId` and can actually present a prompt.
+     *
+     * Only the first match is claimed: two cards for one question would leave the
+     * second one unanswerable (the answer is delivered to the agent, not to a
+     * specific card), and the Web GUI would render a duplicate.
+     *
+     * The `web` channel is a GUI mirror whose outbound face is a no-op by design
+     * — it can neither show a card nor report a tap, so claiming it would spin
+     * the re-present loop forever. Declining it leaves the request to the host's
+     * own forwarder, which is precisely the Web GUI.
+     */
+    claimTarget(sessionId) {
+        for (const binding of this.bindings.list()) {
+            if (binding.sessionId !== sessionId && binding.webMirrorSessionId !== sessionId)
+                continue;
+            const adapter = this.adapters.get(binding.channel);
+            if (adapter === undefined || adapter.supportsChoices === false)
+                continue;
+            if (this.pending.has(binding.chatKey))
+                continue;
+            return { binding, adapter };
         }
+        return undefined;
     }
-    /** Stop presenting and drop the interaction (answered, cancelled, or the turn ended). */
+    /** Stop presenting and drop the interaction (answered, cancelled, or torn down). */
     settle(interaction) {
+        interaction.settled = true;
         if (this.pending.get(interaction.chatKey) === interaction)
             this.pending.delete(interaction.chatKey);
-        interaction.settled = true;
         interaction.controller.abort();
     }
     outbound(p) {