@sigrun/ext-gateway 0.0.0-stage → 0.1.1

package/dist/interactions/prompts.js

@@ -0,0 +1,96 @@
+/**
+ * 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 { JsonFile } from "../state/json-file.js";
+export class PromptStore {
+    file;
+    rows;
+    settled;
+    constructor(path) {
+        this.file = new JsonFile(path, () => ({ prompts: [], settled: [] }));
+        const state = this.file.readSync();
+        this.rows = state.prompts;
+        this.settled = new Set(state.settled);
+    }
+    /** Record a delivered prompt ref (idempotent for one recipient key). */
+    async record(conversationId, callId, key, ref, plan) {
+        const state = await this.file.update((draft) => {
+            const identity = `${conversationId}:${callId}:${key}`;
+            // A settlement raced the receipt: preserve the newly delivered
+            // ref for the edit, never re-open the prompt for answers.
+            if (draft.settled.includes(identity) && ref.messageId === "")
+                return;
+            const existing = draft.prompts.find((row) => row.conversationId === conversationId && row.callId === callId && row.key === key);
+            const next = { conversationId, callId, key, ref, plan };
+            if (existing === undefined)
+                draft.prompts.push(next);
+            else
+                draft.prompts[draft.prompts.indexOf(existing)] = next;
+        });
+        this.rows = state.prompts;
+        this.settled = new Set(state.settled);
+    }
+    /** All delivered message refs for settlement edits (including settled). */
+    refsOf(conversationId, callId) {
+        return this.rows
+            .filter((row) => row.conversationId === conversationId && row.callId === callId)
+            .map((row) => row.ref);
+    }
+    /** Whether this recipient/chat already has a prompt recorded. */
+    has(conversationId, callId, key) {
+        return this.rows.some((row) => row.conversationId === conversationId && row.callId === callId && row.key === key);
+    }
+    /** Recipient identities for opaque-key receipt correlation. */
+    pendingRecipients(conversationId) {
+        return this.rows
+            .filter((row) => row.conversationId === conversationId)
+            .map((row) => ({ callId: row.callId, key: row.key }));
+    }
+    /** Recipient keys for receipt correlation (opaque binding keys may contain colons). */
+    keysOf(conversationId, callId) {
+        return this.rows
+            .filter((row) => row.conversationId === conversationId && row.callId === callId)
+            .map((row) => row.key);
+    }
+    /** Unsettled choice/text prompts in one chat (bound key or user home key). */
+    pendingInChat(bindingKey) {
+        return this.rows
+            .filter((row) => row.key === bindingKey && !this.settled.has(identityOf(row)))
+            .map((row) => ({ conversationId: row.conversationId, callId: row.callId, plan: row.plan }));
+    }
+    /** Find the prompt behind a reply-to platform message id. */
+    byReplyTo(bindingKey, messageId) {
+        const row = this.rows.find((candidate) => candidate.key === bindingKey &&
+            candidate.ref.messageId === messageId &&
+            !this.settled.has(identityOf(candidate)));
+        return row === undefined
+            ? undefined
+            : { conversationId: row.conversationId, callId: row.callId, plan: row.plan };
+    }
+    /** A recipient has been enqueued even before its receipt supplies a ref. */
+    async markEnqueued(conversationId, callId, key, plan) {
+        await this.record(conversationId, callId, key, { chat: { chatId: "", chatType: "dm" }, messageId: "" }, plan);
+    }
+    /** Install the real refs after the interaction ledger entry is delivered. */
+    async recordReceipt(conversationId, callId, key, chat, messageIds) {
+        const existing = this.rows.find((row) => row.conversationId === conversationId && row.callId === callId && row.key === key);
+        await this.record(conversationId, callId, key, { chat, messageId: messageIds[0] ?? "" }, existing?.plan ?? { kind: "webui" });
+    }
+    /** Retire pending answers while preserving refs for the settlement edit. */
+    async settle(conversationId, callId) {
+        const state = await this.file.update((draft) => {
+            const keys = draft.prompts
+                .filter((row) => row.conversationId === conversationId && row.callId === callId)
+                .map(identityOf);
+            draft.settled = [...new Set([...draft.settled, ...keys])];
+        });
+        this.rows = state.prompts;
+        this.settled = new Set(state.settled);
+    }
+}
+function identityOf(row) {
+    return `${row.conversationId}:${row.callId}:${row.key}`;
+}

package/dist/interactions/receipts.d.ts

@@ -0,0 +1,6 @@
+/** Map a delivered interaction ledger row back to its recipient key. */
+import type { LedgerEntry } from "../state/ledger.js";
+import type { PromptStore } from "./prompts.js";
+export declare function receiptForInteraction(prompts: PromptStore, entry: LedgerEntry, receipt: {
+    readonly messageIds: readonly string[];
+}): Promise<void>;

package/dist/interactions/receipts.js

@@ -0,0 +1,36 @@
+/** Map a delivered interaction ledger row back to its recipient key. */
+export async function receiptForInteraction(prompts, entry, receipt) {
+    // The receipt is authoritative: an early settlement may have removed
+    // the pending row, but the delivered message still needs an edit ref.
+    if (entry.bindingKey !== undefined) {
+        const match = entry.tag?.match(/^interaction:(\d+):(.+)$/);
+        if (match === null || match === undefined)
+            return;
+        const suffix = `:${entry.bindingKey}`;
+        if (!match[2].endsWith(suffix))
+            return;
+        const callId = match[2].slice(0, -suffix.length);
+        await prompts.recordReceipt(Number(match[1]), callId, entry.bindingKey, entry.chat, receipt.messageIds);
+        return;
+    }
+    const tag = entry.tag;
+    if (tag === undefined || !tag.startsWith("interaction:"))
+        return;
+    const rest = tag.slice("interaction:".length);
+    const separator = rest.indexOf(":");
+    if (separator < 0)
+        return;
+    const conversationId = Number(rest.slice(0, separator));
+    const afterConversation = rest.slice(separator + 1);
+    if (!Number.isInteger(conversationId))
+        return;
+    // Unbound home keys have no ledger bindingKey; the pending rows'
+    // callIds are the other side of the persisted identity.
+    for (const row of prompts.pendingRecipients(conversationId)) {
+        const suffix = `${row.callId}:${row.key}`;
+        if (afterConversation !== suffix)
+            continue;
+        await prompts.recordReceipt(conversationId, row.callId, row.key, entry.chat, receipt.messageIds);
+        return;
+    }
+}

package/dist/interactions/render.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deterministic chat presentation for a generic interaction record.
+ * The planner admits only answers chat can represent faithfully; every
+ * other root form stays in the webui (notably secrets and open choices).
+ */
+import { type ChoiceOption } from "@sigrun/shared/blocks";
+import type { InteractionRecord } from "@sigrun/shared/interactions";
+import type { ChannelCapabilities, OutboundMessage } from "@sigrun/sigrun/extension";
+import type { TokenAction } from "../inbound/tokens.js";
+/** The answer shapes a chat can collect without losing form semantics. */
+export type ChatAnswerPlan = {
+    readonly kind: "choice";
+    readonly field: string;
+    readonly options: readonly ChoiceOption[];
+    readonly buttons: boolean;
+} | {
+    readonly kind: "text";
+    readonly field: string;
+} | {
+    readonly kind: "webui";
+};
+export interface RenderInteractionOptions {
+    readonly conversationName: string;
+    readonly link?: string;
+    /** The conversation stamped into each interaction token. */
+    readonly conversationId?: number;
+    /** Mint the opaque transport-private action carried by each button. */
+    readonly issue: (action: TokenAction & {
+        readonly kind: "interaction";
+    }) => string;
+}
+/** Plan the one answer mechanism the record's root form supports in chat. */
+export declare function planInteraction(record: InteractionRecord, caps: ChannelCapabilities): ChatAnswerPlan;
+/** Render the generic record and its chat-specific answer affordance. */
+export declare function renderInteraction(record: InteractionRecord, caps: ChannelCapabilities, opts: RenderInteractionOptions): {
+    text: string;
+    buttons?: OutboundMessage["buttons"];
+};
+export declare function truncateInteractionText(text: string, max: number): string;

package/dist/interactions/render.js

@@ -0,0 +1,122 @@
+/**
+ * Deterministic chat presentation for a generic interaction record.
+ * The planner admits only answers chat can represent faithfully; every
+ * other root form stays in the webui (notably secrets and open choices).
+ */
+import { toText } from "@sigrun/shared/blocks";
+import { renderChunks } from "../outbound/render.js";
+/** Plan the one answer mechanism the record's root form supports in chat. */
+export function planInteraction(record, caps) {
+    const root = record.body?.root;
+    if (root?.type !== "form")
+        return { kind: "webui" };
+    const fields = root.children.filter((child) => child.type !== "section");
+    // A section can carry arbitrary presentation/field nesting. Planning
+    // only the flat root form avoids claiming a subset of a richer form.
+    if (fields.length !== root.children.length)
+        return { kind: "webui" };
+    const choices = fields.filter((field) => field.type === "choice");
+    if (choices.length === 1 &&
+        fields.every((field) => field.type === "choice" ||
+            ((field.type === "text" || field.type === "longtext") && field.required !== true))) {
+        const choice = choices[0];
+        if (choice.multi !== true &&
+            choice.allowOther === undefined &&
+            Array.isArray(choice.options)) {
+            return {
+                kind: "choice",
+                field: choice.name,
+                options: choice.options,
+                buttons: choice.options.length <= (caps.buttons?.max ?? 0),
+            };
+        }
+    }
+    if (fields.length === 1 && (fields[0].type === "text" || fields[0].type === "longtext")) {
+        return { kind: "text", field: fields[0].name };
+    }
+    return { kind: "webui" };
+}
+/** Render the generic record and its chat-specific answer affordance. */
+export function renderInteraction(record, caps, opts) {
+    const plan = planInteraction(record, caps);
+    const lines = [];
+    if (record.body !== undefined) {
+        const projected = plan.kind === "choice" ? withoutFormFields(record.body) : record.body;
+        const text = toText(projected, {}, { width: 60, locale: "en" });
+        if (text !== "")
+            lines.push(text);
+    }
+    if (opts.conversationName !== "")
+        lines.push(`Conversation: ${opts.conversationName}`);
+    let buttons;
+    if (plan.kind === "choice") {
+        const options = [...plan.options].sort((a, b) => Number(b.recommended === true) - Number(a.recommended === true));
+        const label = choiceLabel(record.body, plan.field);
+        if (label !== "")
+            lines.push(label);
+        if (plan.buttons) {
+            const row = options.map((option) => ({
+                label: truncateLabel(option.label, caps.buttons?.labelMax),
+                data: opts.issue({
+                    kind: "interaction",
+                    field: plan.field,
+                    conversationId: opts.conversationId ?? 0,
+                    callId: record.callId,
+                    optionId: option.id,
+                }),
+                ...(option.tone === "bad" ? { style: "danger" } : {}),
+            }));
+            const perRow = Math.max(1, caps.buttons?.perRow ?? row.length);
+            const rows = [];
+            for (let index = 0; index < row.length; index += perRow)
+                rows.push(row.slice(index, index + perRow));
+            buttons = rows;
+        }
+        else {
+            options.forEach((option, index) => lines.push(`${index + 1}. ${option.label}`));
+            lines.push("Reply with a number.");
+        }
+    }
+    else if (plan.kind === "text") {
+        lines.push("Reply to this message to answer.");
+    }
+    else {
+        lines.push("Answer this in the webui");
+        if (opts.link !== undefined)
+            lines.push(opts.link);
+    }
+    // The body projection is plain text; the capability formatter still
+    // runs so native/plain channels get the same §8.6 treatment as finals.
+    const formatted = renderChunks(lines.join("\n"), caps).join("\n");
+    return {
+        text: truncateInteractionText(formatted, caps.maxMessageLength),
+        ...(buttons === undefined ? {} : { buttons }),
+    };
+}
+/** Omit form fields when buttons/the numbered list replace their rendering. */
+function withoutFormFields(tree) {
+    if (tree.root.type !== "form")
+        return tree;
+    const root = { ...tree.root, children: tree.root.children.filter((child) => child.type === "section") };
+    return { ...tree, root };
+}
+function choiceLabel(body, name) {
+    if (body?.root.type !== "form")
+        return "";
+    const field = body.root.children.find((child) => child.type === "choice" && child.name === name);
+    return field?.type === "choice" && typeof field.label === "string" ? field.label : "";
+}
+function truncateLabel(label, max) {
+    // Literal options are a planner requirement, so their labels are text.
+    const text = typeof label === "string" ? label : "";
+    return max === undefined ? text : text.slice(0, Math.max(0, max));
+}
+export function truncateInteractionText(text, max) {
+    const limit = Math.max(1, max);
+    if (text.length <= limit)
+        return text;
+    const note = "\n… full details in the webui";
+    if (limit <= note.length)
+        return text.slice(0, limit);
+    return `${text.slice(0, limit - note.length).trimEnd()}${note}`;
+}

package/dist/jobs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Job delivery targets (spec §8.8): a channel alone means the owner's
+ * home DM; an explicit chat must be that home DM or a chat bound to a
+ * conversation the owner can write. This policy gate is shared by job
+ * delivery and the chat-facing message tools.
+ */
+import type { ChatRef, SigrunHost } from "@sigrun/sigrun/extension";
+import type { BindingStore } from "./state/bindings.js";
+import type { IdentityStore } from "./state/identities.js";
+export interface DeliveryTarget {
+    readonly channel: string;
+    readonly chatId?: string;
+}
+export interface ResolvedTarget {
+    readonly channel: string;
+    readonly chat: ChatRef;
+}
+export interface RejectedTarget {
+    readonly target: string;
+    readonly reason: string;
+}
+export interface ResolveTargetsResult {
+    readonly resolved: readonly ResolvedTarget[];
+    readonly rejected: readonly RejectedTarget[];
+}
+export interface TargetDeps {
+    readonly host: SigrunHost;
+    readonly bindings: BindingStore;
+    readonly identities: IdentityStore;
+}
+/** Parse `<channel>` or `<channel>:<chatId>`; the chat id is opaque. */
+export declare function parseTarget(target: string): DeliveryTarget | undefined;
+/** Resolve and authorize each target independently; no target aborts the rest. */
+export declare function resolveTargets(deps: TargetDeps, owner: string, targets: readonly string[]): Promise<ResolveTargetsResult>;

package/dist/jobs.js

@@ -0,0 +1,72 @@
+/**
+ * Job delivery targets (spec §8.8): a channel alone means the owner's
+ * home DM; an explicit chat must be that home DM or a chat bound to a
+ * conversation the owner can write. This policy gate is shared by job
+ * delivery and the chat-facing message tools.
+ */
+const CHANNEL_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Parse `<channel>` or `<channel>:<chatId>`; the chat id is opaque. */
+export function parseTarget(target) {
+    const separator = target.indexOf(":");
+    const channel = separator === -1 ? target : target.slice(0, separator);
+    const chatId = separator === -1 ? undefined : target.slice(separator + 1);
+    if (!CHANNEL_PATTERN.test(channel) || chatId === "")
+        return undefined;
+    return chatId === undefined ? { channel } : { channel, chatId };
+}
+/** Resolve and authorize each target independently; no target aborts the rest. */
+export async function resolveTargets(deps, owner, targets) {
+    const resolved = [];
+    const rejected = [];
+    const homes = deps.identities.homesOf(owner);
+    const bindings = deps.bindings.entries();
+    for (const target of targets) {
+        const parsed = parseTarget(target);
+        if (parsed === undefined) {
+            rejected.push({ target, reason: "invalid target grammar" });
+            continue;
+        }
+        const home = homes.find((entry) => entry.channel === parsed.channel);
+        if (parsed.chatId === undefined) {
+            if (home === undefined) {
+                rejected.push({ target, reason: `no home chat on channel "${parsed.channel}"` });
+            }
+            else {
+                resolved.push({ channel: parsed.channel, chat: home.chat });
+            }
+            continue;
+        }
+        if (home?.chat.chatId === parsed.chatId) {
+            resolved.push({ channel: parsed.channel, chat: home.chat });
+            continue;
+        }
+        const binding = findChatBinding(bindings, parsed.channel, parsed.chatId);
+        if (binding?.dead === true) {
+            rejected.push({ target, reason: "chat is gone" });
+            continue;
+        }
+        const meta = binding === undefined
+            ? undefined
+            : await deps.host.conversations.meta(binding.conversationId);
+        const access = meta === undefined
+            ? "none"
+            : await deps.host.access.accessOf({ user: owner }, { owner: meta.owner, sharing: meta.sharing });
+        if (binding === undefined || access !== "write") {
+            rejected.push({ target, reason: "chat is not bound to a writable conversation" });
+            continue;
+        }
+        resolved.push({ channel: parsed.channel, chat: binding.chat });
+    }
+    return { resolved, rejected };
+}
+/** Find a chat without guessing its thread id or group/DM type. */
+function findChatBinding(bindings, channel, chatId) {
+    const prefix = `${channel}:default:`;
+    for (const [key, binding] of Object.entries(bindings)) {
+        if (!key.startsWith(prefix))
+            continue;
+        if (binding?.chat.chatId === chatId)
+            return binding;
+    }
+    return undefined;
+}

package/dist/log.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Engine logging + id hashing (spec §8.0/§8.12): one scoped console
+ * logger with a per-process `once` dedupe (per-key — a repeated warn
+ * fires a single line, never one per event), and `hashId` — the
+ * non-reversible form sender ids take in status output.
+ */
+/** The irreversible form a platform sender id takes in operator-facing
+ *  output: the sha256 digest's first 8 hex chars (the plan's pinned
+ *  format — enough to correlate without leaking the raw platform id). */
+export declare function hashId(id: string): string;
+/** One scoped logger: console methods plus a per-key `once`. */
+export interface EngineLog {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string, error?: unknown): void;
+    debug(msg: string): void;
+    /** Emit `msg` at `level` ONCE per process per `key` (per-key dedupe). */
+    once(key: string, level: "info" | "warn", msg: string): void;
+}
+/** Build the scoped console logger (the `gateway:` prefix names the engine). */
+export declare function createLog(scope: string): EngineLog;

package/dist/log.js

@@ -0,0 +1,42 @@
+/**
+ * Engine logging + id hashing (spec §8.0/§8.12): one scoped console
+ * logger with a per-process `once` dedupe (per-key — a repeated warn
+ * fires a single line, never one per event), and `hashId` — the
+ * non-reversible form sender ids take in status output.
+ */
+import { createHash } from "node:crypto";
+/** The irreversible form a platform sender id takes in operator-facing
+ *  output: the sha256 digest's first 8 hex chars (the plan's pinned
+ *  format — enough to correlate without leaking the raw platform id). */
+export function hashId(id) {
+    return createHash("sha256").update(id).digest("hex").slice(0, 8);
+}
+/** The emitted-once keys this process has already logged. */
+const onceLogged = new Set();
+/** Build the scoped console logger (the `gateway:` prefix names the engine). */
+export function createLog(scope) {
+    const prefix = `gateway: ${scope}`.trim();
+    return {
+        info: (msg) => console.info(`${prefix} ${msg}`),
+        warn: (msg) => console.warn(`${prefix} ${msg}`),
+        error: (msg, error) => {
+            if (error === undefined)
+                console.error(`${prefix} ${msg}`);
+            else
+                console.error(`${prefix} ${msg}`, error);
+        },
+        // debug rides the console's debug channel: visible when the
+        // environment enables it, silent otherwise.
+        debug: (msg) => console.debug(`${prefix} ${msg}`),
+        once: (key, level, msg) => {
+            const onceKey = `${prefix} ${key}`;
+            if (onceLogged.has(onceKey))
+                return;
+            onceLogged.add(onceKey);
+            if (level === "info")
+                console.info(`${prefix} ${msg}`);
+            else
+                console.warn(`${prefix} ${msg}`);
+        },
+    };
+}

package/dist/notify.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The home-chat notifier (spec §8.8): core chooses the recipients; the
+ * engine turns each event into durable ledger entries for that user's
+ * home DMs. Handlers only enqueue — channel workers own platform I/O.
+ */
+import type { NotifierContribution, SigrunHost } from "@sigrun/sigrun/extension";
+import type { BindingStore } from "./state/bindings.js";
+import type { IdentityStore } from "./state/identities.js";
+import type { Ledger } from "./state/ledger.js";
+import type { GatewayConfig } from "./config.js";
+import type { EngineLog } from "./log.js";
+export interface NotifyDeps {
+    readonly host: SigrunHost;
+    readonly bindings: BindingStore;
+    readonly identities: IdentityStore;
+    readonly ledger: Ledger;
+    readonly readConfig: () => Promise<GatewayConfig>;
+    readonly log: EngineLog;
+}
+/** Build the factory-result notifier over the engine's shared stores. */
+export declare function createNotifier(deps: NotifyDeps): NotifierContribution;

package/dist/notify.js

@@ -0,0 +1,57 @@
+/**
+ * The home-chat notifier (spec §8.8): core chooses the recipients; the
+ * engine turns each event into durable ledger entries for that user's
+ * home DMs. Handlers only enqueue — channel workers own platform I/O.
+ */
+/** Build the factory-result notifier over the engine's shared stores. */
+export function createNotifier(deps) {
+    return {
+        name: "home",
+        notify: async (event) => {
+            try {
+                await notify(event, deps);
+            }
+            catch (error) {
+                // A notice must never break core's other notifier deliveries;
+                // the event is best-effort, but its loss is always visible.
+                deps.log.error(`home notification failed (${event.type})`, error);
+            }
+        },
+    };
+}
+async function notify(event, deps) {
+    // Task 9 owns chat presentation for interaction records.
+    if (event.type === "interaction.pending")
+        return;
+    if (event.user === undefined)
+        return;
+    const config = await deps.readConfig();
+    if (!config.notify.home)
+        return;
+    if (event.type === "run.settled") {
+        if (event.conversationId === undefined)
+            return;
+        // The settled fan-out owns bound conversations; a second notice
+        // here would duplicate the answer the chat just received.
+        if (deps.bindings.keysOf(event.conversationId).length > 0)
+            return;
+        const meta = await deps.host.conversations.meta(event.conversationId);
+        // New-conversation jobs are unbound, but their delivery and
+        // job.failed paths own notices. Core's run.settled carries no
+        // outcome, so the false success notice on a failed job run needs
+        // a core-contract event change and is ledgered for final review.
+        if (meta.jobId !== undefined)
+            return;
+    }
+    const text = event.type === "run.settled"
+        ? `Reply ready — ${event.body}${event.url === undefined ? "" : `\n${event.url}`}`
+        : `${event.title}\n${event.body}${event.url === undefined ? "" : `\n${event.url}`}`;
+    for (const home of deps.identities.homesOf(event.user)) {
+        await deps.ledger.enqueue({
+            channel: home.channel,
+            chat: home.chat,
+            kind: "notice",
+            message: { chat: home.chat, text },
+        });
+    }
+}