@sigrun/ext-gateway 0.0.0-stage → 0.1.1

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,111 @@
+/**
+ * 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 this consuming read. Widening the planner
+    // requires a non-consuming snapshot before any terminal path reads one.
+    const record = await deps.host.snapshotInteraction(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,20 @@
+/**
+ * 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>;

package/dist/interactions/chat.js

@@ -0,0 +1,155 @@
+/**
+ * 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. snapshotInteraction
+    // consumes a settled secret's one-shot delivery, even when we then return.
+    // Final-review follow-up: core should offer a non-consuming snapshot read.
+    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.snapshotInteraction(event.conversationId, event.callId, context);
+    if (record === undefined || record.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(record, channel.capabilities);
+        const rendered = renderInteraction(record, 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),
+        });
+        await deps.prompts.markEnqueued(event.conversationId, event.callId, target.key, plan);
+        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}`,
+        });
+    }
+}
+/** 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 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 ?? {});
+        const outcome = event.status === "answered"
+            ? `answered${who}: ${summarizeValues(answerValues)}`
+            : `${event.status}${who}`;
+        const editableChannels = new Set();
+        const refs = deps.prompts.refsOf(event.conversationId, event.callId);
+        for (const ref of refs) {
+            const id = channelForRef(deps, event.conversationId, event.callId, ref);
+            const channel = id === undefined ? undefined : deps.channelOf(id);
+            if (channel?.capabilities.edit !== undefined && channel.edit !== undefined && ref.messageId !== "") {
+                editableChannels.add(channel.id);
+                const bindingKey = deps.bindings.keysOf(event.conversationId).find((key) => {
+                    const binding = deps.bindings.get(key);
+                    return binding?.chat.chatId === ref.chat.chatId && binding.chat.threadId === ref.chat.threadId;
+                });
+                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:${event.conversationId}:${event.callId}:${channel.id}:${ref.messageId}`,
+                });
+            }
+        }
+        if (editableChannels.size === 0) {
+            for (const key of deps.bindings.keysOf(event.conversationId)) {
+                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:${event.conversationId}:${event.callId}:${key}`,
+                });
+            }
+        }
+        await deps.prompts.settle(event.conversationId, event.callId);
+    }
+    catch (error) {
+        deps.log.error(`interaction settlement delivery failed (${String(event.conversationId)}:${event.callId})`, error);
+    }
+}
+/** 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;
+}

package/dist/interactions/prompts.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Durable chat-prompt bookkeeping. Ledger delivery receipts become
+ * MessageRefs here; pending reads stay synchronous for inbound stage 8.
+ * Settled prompts stop matching numbered/reply-to answers; their refs
+ * remain so settlement can edit the delivered platform message.
+ */
+import type { MessageRef } from "@sigrun/sigrun/extension";
+import type { ChatAnswerPlan } from "./render.js";
+export interface PendingPrompt {
+    readonly conversationId: number;
+    readonly callId: string;
+    readonly plan: ChatAnswerPlan;
+}
+export declare class PromptStore {
+    private readonly file;
+    private rows;
+    private settled;
+    constructor(path: string);
+    /** Record a delivered prompt ref (idempotent for one recipient key). */
+    record(conversationId: number, callId: string, key: string, ref: MessageRef, plan: ChatAnswerPlan): Promise<void>;
+    /** All delivered message refs for settlement edits (including settled). */
+    refsOf(conversationId: number, callId: string): readonly MessageRef[];
+    /** Whether this recipient/chat already has a prompt recorded. */
+    has(conversationId: number, callId: string, key: string): boolean;
+    /** Recipient identities for opaque-key receipt correlation. */
+    pendingRecipients(conversationId: number): readonly {
+        callId: string;
+        key: string;
+    }[];
+    /** Recipient keys for receipt correlation (opaque binding keys may contain colons). */
+    keysOf(conversationId: number, callId: string): readonly string[];
+    /** Unsettled choice/text prompts in one chat (bound key or user home key). */
+    pendingInChat(bindingKey: string): readonly PendingPrompt[];
+    /** Find the prompt behind a reply-to platform message id. */
+    byReplyTo(bindingKey: string, messageId: string): PendingPrompt | undefined;
+    /** A recipient has been enqueued even before its receipt supplies a ref. */
+    markEnqueued(conversationId: number, callId: string, key: string, plan: ChatAnswerPlan): Promise<void>;
+    /** Install the real refs after the interaction ledger entry is delivered. */
+    recordReceipt(conversationId: number, callId: string, key: string, chat: MessageRef["chat"], messageIds: readonly string[]): Promise<void>;
+    /** Retire pending answers while preserving refs for the settlement edit. */
+    settle(conversationId: number, callId: string): Promise<void>;
+}