@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * sigrun-ext-gateway: the gateway engine factory (the loader contract).
+ *
+ * The sigrun extension-package contract: the default export is a factory
+ * DECLARING the host parameter (arity 1 — the host rule; a length-0
+ * factory with a defaulted first parameter would consume the host as
+ * that dependency), returning `{ extension, gateway, routes,
+ * commands }`.
+ *
+ * The extension is a bare `defineExtension({ name: "gateway" })`:
+ * the prompt section (§8.10) and the `send_message`/`list_chats` tools
+ * (§8.9) land with the tasks that own them. The `gateway` engine is
+ * built over the host at factory time (cheap closure wiring — no
+ * timers, no I/O; the pi lifecycle rule: the factory registers
+ * handlers only, `start` runs after the server listens), the admin
+ * status route (Task 2, §8.12) renders the engine's status read, and
+ * the `/pair` + `/link` slash commands (Task 4, §8.2) close over the
+ * SAME engine-wide access state the pipelines use — a webui approval
+ * and a chat-button tap drive the same pairing queue, and an issued
+ * link code redeems in the matching channel's pipeline.
+ */
+import type { SigrunHost, SigrunExtensionResult } from "@sigrun/sigrun/extension";
+/**
+ * The sigrun extension-package factory: builds the engine over the host.
+ * One factory call, one engine (the one-engine rule holds at the loader:
+ * a second declarer quarantines).
+ */
+export default function createGateway(host: SigrunHost): SigrunExtensionResult;
+export { createEngine } from "./engine.js";
+export { collectAttachments, TOO_LARGE_NOTE, VOICE_NOTE, ATTACHMENT_FAILED_NOTE } from "./inbound/media.js";
+export type { MediaDeps, CollectedAttachments } from "./inbound/media.js";
+export { createGatewayTools, RECEIPT_WAIT_MS } from "./tools.js";
+export type { ToolDeps } from "./tools.js";
+export { createChannelSection } from "./section.js";
+export type { ChannelSectionDeps } from "./section.js";
+export type { EngineDeps, EngineInternals } from "./engine.js";
+export { splitMarkdown, stripMarkdown } from "./outbound/markdown.js";
+export { renderChunks } from "./outbound/render.js";
+export type { SerializedOutbound, LedgerEntry, LedgerInput, LedgerKind, LedgerState } from "./state/ledger.js";
+export { Ledger, PRUNE_AFTER_MS } from "./state/ledger.js";
+export { DeliveryWorker, RESENT_MARKER } from "./outbound/delivery.js";
+export type { DeliveryDeps } from "./outbound/delivery.js";
+export { onRunSettled, NO_TEXT_REPLY, STOPPED } from "./outbound/settled.js";
+export { parseTarget, resolveTargets } from "./jobs.js";
+export type { DeliveryTarget, RejectedTarget, ResolvedTarget, ResolveTargetsResult, TargetDeps, } from "./jobs.js";
+export { createNotifier } from "./notify.js";
+export type { NotifyDeps } from "./notify.js";
+export type { SettledDeps, Streams } from "./outbound/settled.js";
+export { StreamRegistry } from "./outbound/stream.js";
+export type { StreamOrigin, StreamRegistryDeps } from "./outbound/stream.js";
+export { Supervisor } from "./supervisor.js";
+export type { ChannelState, ChannelStatus, StatusSink, SupervisorDeps, } from "./supervisor.js";
+export { createStatusRoute } from "./status-route.js";
+export type { GatewayStatus, StatusPairingRow, StatusRead, } from "./status-route.js";
+export { parseGatewayConfig, readConfig, DEFAULT_MEDIA_MAX_BYTES, } from "./config.js";
+export type { ChannelConfig, DmPolicy, GatewayConfig, GroupConfig, } from "./config.js";
+export { JsonFile } from "./state/json-file.js";
+export { bindingKey, BindingStore } from "./state/bindings.js";
+export type { Binding } from "./state/bindings.js";
+export { SeenSet } from "./state/seen.js";
+export { IdentityStore } from "./state/identities.js";
+export type { LinkResult, LinkVia, ResolvedUser } from "./state/identities.js";
+export { buildEnvelope } from "./inbound/envelope.js";
+export { createPipeline } from "./inbound/pipeline.js";
+export type { AccessState, PipelineDeps, PipelineOutcome, PipelineStreams, PipelineStages, Receive, SubmissionOrigin, } from "./inbound/pipeline.js";
+export { AlbumCollector, ALBUM_WINDOW_MS } from "./inbound/albums.js";
+export { ButtonTokens } from "./inbound/tokens.js";
+export type { TokenAction } from "./inbound/tokens.js";
+export { CODE_ALPHABET, newCode, normalizeCode } from "./access/codes.js";
+export { PairingStore, PAIRING_TTL_MS } from "./access/pairing.js";
+export type { PairingRequest, RequestResult } from "./access/pairing.js";
+export { LinkCodes } from "./access/link-codes.js";
+export { LoopGuard } from "./access/loop-guard.js";
+export { runPair } from "./commands/pair.js";
+export type { PairCaller, PairDeps } from "./commands/pair.js";
+export { createLinkCommand, redeemLink } from "./commands/link.js";
+export { GATEWAY_COMMANDS, chatCommandMenu, handleChatCommand, } from "./commands/chat.js";
+export type { ChatCommandContext, ChatCommandDeps, GatewayCommand, } from "./commands/chat.js";
+export type { LinkCommand, LinkCommandDeps, LinkDeps, } from "./commands/link.js";
+export { createLog, hashId } from "./log.js";
+export { planInteraction, renderInteraction } from "./interactions/render.js";
+export type { ChatAnswerPlan, RenderInteractionOptions } from "./interactions/render.js";
+export { PromptStore } from "./interactions/prompts.js";
+export { answerFromChat, createInteractionAnswerStage } from "./interactions/answer.js";
+export { createInteractionNotifier, onInteractionSettled } from "./interactions/chat.js";
+export type { EngineLog } from "./log.js";

package/dist/index.js

@@ -0,0 +1,136 @@
+/**
+ * sigrun-ext-gateway: the gateway engine factory (the loader contract).
+ *
+ * The sigrun extension-package contract: the default export is a factory
+ * DECLARING the host parameter (arity 1 — the host rule; a length-0
+ * factory with a defaulted first parameter would consume the host as
+ * that dependency), returning `{ extension, gateway, routes,
+ * commands }`.
+ *
+ * The extension is a bare `defineExtension({ name: "gateway" })`:
+ * the prompt section (§8.10) and the `send_message`/`list_chats` tools
+ * (§8.9) land with the tasks that own them. The `gateway` engine is
+ * built over the host at factory time (cheap closure wiring — no
+ * timers, no I/O; the pi lifecycle rule: the factory registers
+ * handlers only, `start` runs after the server listens), the admin
+ * status route (Task 2, §8.12) renders the engine's status read, and
+ * the `/pair` + `/link` slash commands (Task 4, §8.2) close over the
+ * SAME engine-wide access state the pipelines use — a webui approval
+ * and a chat-button tap drive the same pairing queue, and an issued
+ * link code redeems in the matching channel's pipeline.
+ */
+import { defineExtension } from "@earendil-works/pi-durable";
+import { createEngine } from "./engine.js";
+import { createStatusRoute } from "./status-route.js";
+import { runPair } from "./commands/pair.js";
+import { createLinkCommand } from "./commands/link.js";
+import { readConfig } from "./config.js";
+import { createGatewayTools } from "./tools.js";
+import { createChannelSection } from "./section.js";
+/**
+ * The sigrun extension-package factory: builds the engine over the host.
+ * One factory call, one engine (the one-engine rule holds at the loader:
+ * a second declarer quarantines).
+ */
+export default function createGateway(host) {
+    if (host.accounts === undefined) {
+        throw new Error("gateway requires sigrun core with host.accounts (multi-user M3a)");
+    }
+    const engine = createEngine(host);
+    // `/pair` (§8.2): the admin surface over the shared pairing queue.
+    // The invoke route hands the caller's principal (user + EFFECTIVE
+    // admin — the stored flag OR the persisted group grant, C8); an
+    // unnamed loopback caller gets the pinned refusal.
+    const pair = {
+        name: "pair",
+        description: "Manage pending channel pairing requests (admin)",
+        args: "[approve <code> <user> | deny <code>]",
+        run: async (ctx) => ({
+            notice: await runPair(engine.pairDeps(host), ctx.args, {
+                user: ctx.principal.user,
+                admin: ctx.principal.admin,
+            }),
+        }),
+    };
+    // `/link <channel>` (§8.2): issue a single-use self-link code bound
+    // to the invoking user and channel. `knownChannels` reads the ids the
+    // last start recorded — an engine that never started knows none, and
+    // every channel id is unknown (the honest refusal).
+    const link = createLinkCommand({
+        readConfig: () => readConfig(host),
+        linkCodes: engine.accessState().linkCodes,
+        knownChannels: engine.channelIds,
+        now: Date.now,
+    });
+    return {
+        extension: defineExtension({
+            name: "gateway",
+            tools: createGatewayTools(engine.toolDeps()),
+            sections: [createChannelSection(engine.sectionDeps())],
+        }),
+        gateway: engine,
+        // The settled-run fan-out (§8.6): boot registers this on the event
+        // bus — one call per settled run, which enqueues the finals and
+        // kicks the workers. The narrowed document read is mandatory:
+        // unlike the host bridge, it resolves in harness-only embedders
+        // without a 30 s wait.
+        runSettled: (event, api, context) => engine.settle(event, api, context),
+        interactionSettled: async (event, _api, context) => {
+            await engine.interactionSettled(event, context);
+        },
+        // Task 12 owns links as well as homes; Task 13 moves links to core's
+        // account table and narrows this cleanup to the home-chat records.
+        userDeleted: async ({ user }) => {
+            await engine.accessState().identities.forgetHomes(user);
+        },
+        // Home-chat notifications share the delivery ledger and workers;
+        // this wrapper kicks delivery after each bounded enqueue.
+        notifiers: [engine.notifier()],
+        // The admin status route (§8.12): mounts at /v1/ext/gateway/status,
+        // admin-gated by core's route mounting (the handler renders the
+        // engine's read; `pairing` rows carry the hashed sender id, never
+        // the code).
+        routes: [
+            createStatusRoute(() => ({
+                channels: engine.status().channels,
+                pairing: engine.pairingStatus(),
+            })),
+        ],
+        commands: [pair, link],
+    };
+}
+export { createEngine } from "./engine.js";
+export { collectAttachments, TOO_LARGE_NOTE, VOICE_NOTE, ATTACHMENT_FAILED_NOTE } from "./inbound/media.js";
+export { createGatewayTools, RECEIPT_WAIT_MS } from "./tools.js";
+export { createChannelSection } from "./section.js";
+export { splitMarkdown, stripMarkdown } from "./outbound/markdown.js";
+export { renderChunks } from "./outbound/render.js";
+export { Ledger, PRUNE_AFTER_MS } from "./state/ledger.js";
+export { DeliveryWorker, RESENT_MARKER } from "./outbound/delivery.js";
+export { onRunSettled, NO_TEXT_REPLY, STOPPED } from "./outbound/settled.js";
+export { parseTarget, resolveTargets } from "./jobs.js";
+export { createNotifier } from "./notify.js";
+export { StreamRegistry } from "./outbound/stream.js";
+export { Supervisor } from "./supervisor.js";
+export { createStatusRoute } from "./status-route.js";
+export { parseGatewayConfig, readConfig, DEFAULT_MEDIA_MAX_BYTES, } from "./config.js";
+export { JsonFile } from "./state/json-file.js";
+export { bindingKey, BindingStore } from "./state/bindings.js";
+export { SeenSet } from "./state/seen.js";
+export { IdentityStore } from "./state/identities.js";
+export { buildEnvelope } from "./inbound/envelope.js";
+export { createPipeline } from "./inbound/pipeline.js";
+export { AlbumCollector, ALBUM_WINDOW_MS } from "./inbound/albums.js";
+export { ButtonTokens } from "./inbound/tokens.js";
+export { CODE_ALPHABET, newCode, normalizeCode } from "./access/codes.js";
+export { PairingStore, PAIRING_TTL_MS } from "./access/pairing.js";
+export { LinkCodes } from "./access/link-codes.js";
+export { LoopGuard } from "./access/loop-guard.js";
+export { runPair } from "./commands/pair.js";
+export { createLinkCommand, redeemLink } from "./commands/link.js";
+export { GATEWAY_COMMANDS, chatCommandMenu, handleChatCommand, } from "./commands/chat.js";
+export { createLog, hashId } from "./log.js";
+export { planInteraction, renderInteraction } from "./interactions/render.js";
+export { PromptStore } from "./interactions/prompts.js";
+export { answerFromChat, createInteractionAnswerStage } from "./interactions/answer.js";
+export { createInteractionNotifier, onInteractionSettled } from "./interactions/chat.js";

package/dist/interactions/answer.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Write-gated answers originating in chat. Identity resolution belongs
+ * to the pipeline/tap caller; this module independently re-checks
+ * conversation write access immediately before answering.
+ */
+import type { JsonValue } from "@sigrun/shared/blocks";
+import type { HandlerContext, InboundEvent, SigrunHost } from "@sigrun/sigrun/extension";
+import { type BindingStore } from "../state/bindings.js";
+import { type IdentityStore } from "../state/identities.js";
+import type { PromptStore } from "./prompts.js";
+export interface AnswerDeps {
+    readonly host: SigrunHost;
+    readonly bindings: BindingStore;
+    readonly identities: IdentityStore;
+    readonly prompts: PromptStore;
+    readonly context?: HandlerContext;
+    /** Direct adapter reply (the pipeline supplies it; unit callers need not). */
+    readonly reply?: (event: InboundEvent, text: string) => Promise<void>;
+}
+export interface ChatAnswer {
+    readonly conversationId: number;
+    readonly callId: string;
+    readonly values: Record<string, JsonValue>;
+    readonly user: string | undefined;
+}
+/** Answer after proving the named chat user can still write the conversation. */
+export declare function answerFromChat(deps: AnswerDeps, answer: ChatAnswer): Promise<string>;
+/** One shared human-readable outcome for settlement edits and stale taps. */
+export declare function outcomeOf(record: {
+    readonly status: string;
+    readonly answer?: {
+        readonly values: Readonly<Record<string, JsonValue>>;
+    };
+    readonly answeredByUser?: string;
+}): string;
+export declare function summarizeValues(values: Readonly<Record<string, JsonValue>>): string;
+/** Stage 8: consume a numbered or reply-to answer, else continue admission. */
+export declare function createInteractionAnswerStage(deps: AnswerDeps & {
+    readonly configOf?: (channel: string) => Promise<import("../config.js").ChannelConfig | undefined>;
+}): (channelId: string, event: InboundEvent) => Promise<{
+    outcome: "command";
+} | undefined>;

package/dist/interactions/answer.js

@@ -0,0 +1,112 @@
+/**
+ * Write-gated answers originating in chat. Identity resolution belongs
+ * to the pipeline/tap caller; this module independently re-checks
+ * conversation write access immediately before answering.
+ */
+import { bindingKey } from "../state/bindings.js";
+import { chatProviderOf } from "../state/identities.js";
+const TERMINAL = new Set(["answered", "skipped", "expired", "cancelled"]);
+/** Answer after proving the named chat user can still write the conversation. */
+export async function answerFromChat(deps, answer) {
+    if (answer.user === undefined)
+        return "You do not have write access to this conversation.";
+    const meta = await deps.host.conversations.meta(answer.conversationId);
+    const access = await deps.host.access.accessOf({ user: answer.user }, { owner: meta.owner, sharing: meta.sharing });
+    if (access !== "write")
+        return "You do not have write access to this conversation.";
+    // Terminal-snapshot invariant: secret-bearing records are webui-plan,
+    // so no chat answer reaches a secret record. The gateway owns NO
+    // secret delivery regardless — this correlation/terminal read only
+    // INSPECTS, so it is a peek (non-consuming, masked) by construction.
+    const record = await deps.host.peekInteraction(answer.conversationId, answer.callId, deps.context ?? { abortSignal: new AbortController().signal });
+    if (record !== undefined && TERMINAL.has(record.status)) {
+        return `Already ${outcomeOf(record)}.`;
+    }
+    if (record === undefined)
+        return "That interaction is no longer available.";
+    const answered = await deps.host.answerInteraction(answer.conversationId, answer.callId, { values: answer.values }, deps.context ?? { abortSignal: new AbortController().signal }, { user: answer.user });
+    if (!answered) {
+        // A lost race: someone else's answer won. NEVER snapshotInteraction
+        // here — that read takes the WINNER's one-shot secret delivery
+        // (Review Focus 4: the delivery belongs to the winner's extension
+        // read; a losing path consuming it would destroy the secret).
+        return "Already answered.";
+    }
+    return `Answered: ${summarizeValues(answer.values)}.`;
+}
+/** One shared human-readable outcome for settlement edits and stale taps. */
+export function outcomeOf(record) {
+    const who = record.answeredByUser === undefined ? "" : ` by ${record.answeredByUser}`;
+    if (record.status === "answered") {
+        return `answered${who}: ${summarizeValues(record.answer?.values ?? {})}`;
+    }
+    return `${record.status}${who}`;
+}
+export function summarizeValues(values) {
+    const parts = Object.entries(values).map(([field, value]) => {
+        const rendered = typeof value === "string" ? value : JSON.stringify(value);
+        return `${field}=${rendered ?? "null"}`;
+    });
+    return parts.length === 0 ? "no values" : parts.join(", ");
+}
+/** Stage 8: consume a numbered or reply-to answer, else continue admission. */
+export function createInteractionAnswerStage(deps) {
+    return async (channelId, event) => {
+        const key = bindingKey(channelId, event.chat);
+        const config = await deps.configOf?.(channelId);
+        const resolved = config === undefined
+            ? await deps.host.accounts.lookup(chatProviderOf(channelId), event.sender.id)
+            : await deps.identities.userFor(config, channelId, event.sender.id);
+        const user = resolved?.user;
+        const lookupKeys = user === undefined ? [key] : [key, `user:${user}`];
+        const lookup = (read) => {
+            for (const candidate of lookupKeys) {
+                const found = read(candidate);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        };
+        let prompt;
+        const replyTarget = event.replyTo?.messageId;
+        if (replyTarget !== undefined) {
+            const replied = lookup((candidate) => deps.prompts.byReplyTo(candidate, replyTarget));
+            if (replied?.plan.kind === "text") {
+                prompt = {
+                    conversationId: replied.conversationId,
+                    callId: replied.callId,
+                    values: { [replied.plan.field]: event.text },
+                };
+            }
+        }
+        if (prompt === undefined && /^\d+$/.test(event.text.trim())) {
+            const pending = lookup((candidate) => {
+                const rows = deps.prompts.pendingInChat(candidate);
+                return rows.length === 0 ? undefined : rows;
+            });
+            if (pending?.length === 1) {
+                const selected = pending[0];
+                const plan = selected.plan;
+                if (plan.kind !== "choice")
+                    return undefined;
+                const index = Number(event.text.trim()) - 1;
+                const options = [...plan.options].sort((a, b) => Number(b.recommended === true) - Number(a.recommended === true));
+                const option = options[index];
+                if (option === undefined) {
+                    await deps.reply?.(event, `Answer number out of range (1-${options.length}).`);
+                    return { outcome: "command" };
+                }
+                prompt = {
+                    conversationId: selected.conversationId,
+                    callId: selected.callId,
+                    values: { [plan.field]: option.id },
+                };
+            }
+        }
+        if (prompt === undefined)
+            return undefined;
+        const reply = await answerFromChat(deps, { ...prompt, user });
+        await deps.reply?.(event, reply);
+        return { outcome: "command" };
+    };
+}

package/dist/interactions/chat.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Interaction notification and settlement fan-out. Handlers only enqueue
+ * durable ledger entries; delivery receipts populate PromptStore refs so
+ * settlement can edit the exact platform messages.
+ */
+import type { ChannelContribution, ExtensionLifecyclePayload, HandlerContext, NotifierContribution } from "@sigrun/sigrun/extension";
+import type { Ledger } from "../state/ledger.js";
+import type { ButtonTokens } from "../inbound/tokens.js";
+import type { EngineLog } from "../log.js";
+import { type AnswerDeps } from "./answer.js";
+export interface InteractionChatDeps extends AnswerDeps {
+    readonly ledger: Ledger;
+    readonly tokens: ButtonTokens;
+    readonly channelOf: (channel: string) => ChannelContribution | undefined;
+    readonly log: EngineLog;
+}
+/** The gateway notifier: interaction.pending plus the ordinary home notifier. */
+export declare function createInteractionNotifier(deps: InteractionChatDeps): NotifierContribution;
+/** Enqueue outcome edits/notices and retire numbered/reply-to matching. */
+export declare function onInteractionSettled(event: ExtensionLifecyclePayload["interactionSettled"], deps: InteractionChatDeps, context: HandlerContext): Promise<void>;
+/**
+ * Enqueue settlement edits and per-binding fallback outcome notices
+ * (a binding without an editable ref gets a notice). Called at settlement AND from the receipt
+ * path when a real delivery ref arrives for an ALREADY-settled prompt:
+ * settlement that beats the receipt leaves no editable ref, so the
+ * late receipt is the last chance to replace the live buttons.
+ */
+export declare function enqueueSettlementEdits(deps: InteractionChatDeps, conversationId: number, callId: string, outcome: string): Promise<void>;

package/dist/interactions/chat.js

@@ -0,0 +1,199 @@
+/**
+ * Interaction notification and settlement fan-out. Handlers only enqueue
+ * durable ledger entries; delivery receipts populate PromptStore refs so
+ * settlement can edit the exact platform messages.
+ */
+import { summarizeValues } from "./answer.js";
+import { planInteraction, renderInteraction, truncateInteractionText } from "./render.js";
+/** The gateway notifier: interaction.pending plus the ordinary home notifier. */
+export function createInteractionNotifier(deps) {
+    return {
+        name: "gateway",
+        notify: async (event) => {
+            if (event.type !== "interaction.pending")
+                return;
+            if (event.conversationId === undefined || event.callId === undefined)
+                return;
+            try {
+                await notifyInteraction(event, deps);
+            }
+            catch (error) {
+                deps.log.error(`interaction prompt failed (${event.conversationId}:${event.callId})`, error);
+            }
+        },
+    };
+}
+async function notifyInteraction(event, deps) {
+    const keys = deps.bindings.keysOf(event.conversationId);
+    const targets = [];
+    if (keys.length > 0) {
+        for (const key of keys) {
+            const binding = deps.bindings.get(key);
+            if (binding === undefined || binding.dead === true)
+                continue;
+            targets.push({ key, channel: key.split(":")[0], chat: binding.chat, bindingKey: key });
+        }
+    }
+    else if (event.user !== undefined) {
+        for (const home of deps.identities.homesOf(event.user)) {
+            targets.push({ key: `user:${event.user}`, channel: home.channel, chat: home.chat });
+        }
+    }
+    // Resolve and dedupe targets BEFORE reading the record. The read is a
+    // PEEK: the gateway owns NO secret delivery (secret records are
+    // webui-plan), so it must never consume one — peekInteraction is the
+    // non-consuming inspection read (a settled secret's one-shot delivery
+    // belongs to the owning extension's snapshotInteraction alone).
+    const pendingTargets = targets.filter((target) => !deps.prompts.has(event.conversationId, event.callId, target.key));
+    if (pendingTargets.length === 0)
+        return;
+    const context = deps.context ?? { abortSignal: new AbortController().signal };
+    const record = await deps.host.peekInteraction(event.conversationId, event.callId, context);
+    if (record === undefined || record.status !== "pending")
+        return;
+    // A settle can land while the render above awaited: re-check BEFORE
+    // the first enqueue so an already-settled interaction never gets a
+    // live prompt (the buttons would only answer "Already answered.").
+    const still = await deps.host.peekInteraction(event.conversationId, event.callId, context);
+    if (still === undefined || still.status !== "pending")
+        return;
+    for (const target of pendingTargets) {
+        const channel = deps.channelOf(target.channel);
+        if (channel === undefined) {
+            deps.log.warn(`interaction prompt skipped: no channel "${target.channel}"`);
+            continue;
+        }
+        const plan = planInteraction(still, channel.capabilities);
+        const rendered = renderInteraction(still, channel.capabilities, {
+            conversationId: event.conversationId,
+            conversationName: (await deps.host.conversations.meta(event.conversationId)).name ?? `Conversation ${event.conversationId}`,
+            ...(event.url === undefined ? {} : { link: event.url }),
+            issue: (action) => deps.tokens.issue(action.kind === "interaction"
+                ? { ...action, conversationId: event.conversationId }
+                : action),
+        });
+        // The ledger enqueue precedes the prompt row: the ledger tag is
+        // the durable dedupe, so a throwing enqueue must NOT leave a row
+        // that would suppress this target on every replay.
+        // Re-check per target immediately before its enqueue: rendering
+        // and meta lookups await, and a settle in that window must not
+        // deliver another live prompt. markEnqueued independently checks
+        // the durable call-level settlement marker as the final guard.
+        const current = await deps.host.peekInteraction(event.conversationId, event.callId, context);
+        if (current === undefined || current.status !== "pending")
+            return;
+        const enqueued = await deps.ledger.enqueue({
+            channel: target.channel,
+            ...(target.bindingKey === undefined ? {} : { bindingKey: target.bindingKey }),
+            chat: target.chat,
+            kind: "interaction",
+            message: { chat: target.chat, ...rendered },
+            tag: `interaction:${event.conversationId}:${event.callId}:${target.key}`,
+        });
+        await deps.prompts.markEnqueued(event.conversationId, event.callId, target.key, plan);
+        // A settlement between the pending peek and markEnqueued writes the
+        // call-level tombstone, so no row was reserved. Compensate the lost
+        // reservation by cancelling the still-pending prompt: otherwise its
+        // delivery would leave live buttons and duplicate the outcome notice.
+        if (enqueued !== undefined && !deps.prompts.has(event.conversationId, event.callId, target.key)) {
+            await deps.ledger.cancel(enqueued.id);
+            return;
+        }
+    }
+}
+/** Enqueue outcome edits/notices and retire numbered/reply-to matching. */
+export async function onInteractionSettled(event, deps, context) {
+    try {
+        // NEVER snapshotInteraction here: that read is the one-shot SECRET
+        // delivery (it merges the true values back once, then deletes the
+        // entry) — an outcome edit that consumed it would silently destroy
+        // the extension's only chance to receive the secret. The widened C6
+        // event carries everything chat rendering needs (the stored answer
+        // is masked by construction — secrets never persist).
+        const outcome = outcomeText(event);
+        await enqueueSettlementEdits(deps, event.conversationId, event.callId, outcome);
+        await deps.prompts.settle(event.conversationId, event.callId, outcome);
+    }
+    catch (error) {
+        deps.log.error(`interaction settlement delivery failed (${String(event.conversationId)}:${event.callId})`, error);
+    }
+}
+/** The outcome summary the settlement edit/notice carries. */
+function outcomeText(event) {
+    const who = event.answeredByUser === undefined ? "" : ` by ${event.answeredByUser}`;
+    // SAFETY: the stored answer's values are validated JsonValue (the
+    // record's answer shape); the payload types them loosely because
+    // the contract cannot import the json module's runtime shape.
+    const answerValues = (event.answer ?? {});
+    return event.status === "answered"
+        ? `answered${who}: ${summarizeValues(answerValues)}`
+        : `${event.status}${who}`;
+}
+/**
+ * Enqueue settlement edits and per-binding fallback outcome notices
+ * (a binding without an editable ref gets a notice). Called at settlement AND from the receipt
+ * path when a real delivery ref arrives for an ALREADY-settled prompt:
+ * settlement that beats the receipt leaves no editable ref, so the
+ * late receipt is the last chance to replace the live buttons.
+ */
+export async function enqueueSettlementEdits(deps, conversationId, callId, outcome) {
+    const editableBindings = new Set();
+    const refs = deps.prompts.refsOf(conversationId, callId);
+    for (const ref of refs) {
+        const id = channelForRef(deps, conversationId, callId, ref);
+        const channel = id === undefined ? undefined : deps.channelOf(id);
+        const bindingKey = deps.bindings.keysOf(conversationId).find((key) => {
+            const binding = deps.bindings.get(key);
+            return binding?.chat.chatId === ref.chat.chatId && binding.chat.threadId === ref.chat.threadId;
+        });
+        if (channel?.capabilities.edit !== undefined && channel.edit !== undefined && ref.messageId !== "") {
+            if (bindingKey !== undefined)
+                editableBindings.add(bindingKey);
+            await deps.ledger.enqueue({
+                channel: channel.id,
+                ...(bindingKey === undefined ? {} : { bindingKey }),
+                chat: ref.chat,
+                kind: "edit",
+                ref,
+                message: { chat: ref.chat, text: truncateInteractionText(`Interaction ${outcome}.`, channel.capabilities.maxMessageLength) },
+                tag: `interaction-settled:${conversationId}:${callId}:${channel.id}:${ref.messageId}`,
+            });
+        }
+    }
+    // Fallback eligibility is PER BINDING: an editable ref on one channel
+    // must not suppress the outcome notice owed to another binding whose
+    // channel cannot edit (or whose prompt has no editable ref).
+    for (const key of deps.bindings.keysOf(conversationId)) {
+        if (editableBindings.has(key))
+            continue;
+        const binding = deps.bindings.get(key);
+        const channelId = key.split(":")[0];
+        if (binding === undefined || binding.dead === true)
+            continue;
+        await deps.ledger.enqueue({
+            channel: channelId,
+            bindingKey: key,
+            chat: binding.chat,
+            kind: "notice",
+            message: { chat: binding.chat, text: `Interaction ${outcome}.` },
+            tag: `interaction-settled-notice:${conversationId}:${callId}:${key}`,
+        });
+    }
+}
+/** Recover the channel from the binding key/home prompt target. */
+function channelForRef(deps, conversationId, callId, ref) {
+    for (const key of deps.bindings.keysOf(conversationId)) {
+        const binding = deps.bindings.get(key);
+        if (binding?.chat.chatId === ref.chat.chatId && binding.chat.threadId === ref.chat.threadId)
+            return key.split(":")[0];
+    }
+    return promptChannel(deps, conversationId, callId, ref);
+}
+function promptChannel(deps, conversationId, callId, ref) {
+    // PromptStore persists refs, not a second channel mapping. The ledger's
+    // interaction entry is the authoritative channel attribution.
+    const entry = deps.ledger.list().find((candidate) => candidate.kind === "interaction" &&
+        candidate.tag?.startsWith(`interaction:${conversationId}:${callId}:`) === true &&
+        candidate.chat.chatId === ref.chat.chatId);
+    return entry?.channel;
+}