@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/interactions/prompts.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ *
+ * Retention (release-readiness spec 4 §§2–4): the persisted file is
+ * version 2 — `prompts` rows plus a `settled` tombstone map carrying
+ * the settlement timestamp and outcome text. Seven days after
+ * settlement the bulky row (refs/plan) expires; the compact tombstone
+ * persists PERMANENTLY so a delayed receipt or replay can never
+ * resurrect an answerable prompt. Pending rows are never age-pruned.
+ * Pruning runs at store initialization and at most once per write (no
+ * timer), through the one `prune` helper and its boundary predicate.
+ * Refs/plans are therefore bounded by active prompts plus seven days
+ * of settled history; the tombstone set is deliberately unbounded.
+ */
+import type { MessageRef } from "@sigrun/sigrun/extension";
+import type { EngineLog } from "../log.js";
+import type { ChatAnswerPlan } from "./render.js";
+/** Settled-row retention (matches the delivery ledger's seven days). */
+export declare const PROMPT_RETENTION_MS = 604800000;
+export interface PendingPrompt {
+    readonly conversationId: number;
+    readonly callId: string;
+    readonly plan: ChatAnswerPlan;
+}
+export interface PromptStoreOptions {
+    readonly now?: () => number;
+    readonly log?: EngineLog;
+}
+export declare class PromptStore {
+    private readonly file;
+    private readonly now;
+    private readonly log;
+    private rows;
+    private settled;
+    constructor(path: string, options?: PromptStoreOptions);
+    /** 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; the refs stay until retention expires them. */
+    settle(conversationId: number, callId: string, outcome?: string): Promise<void>;
+    /**
+     * The outcome text recorded at settlement, when this identity is
+     * settled. The receipt path reads it to self-heal the prompt edit;
+     * the tombstone outlives the bulky row, so the answer survives
+     * pruning even when no editable ref remains.
+     */
+    settledOutcome(conversationId: number, callId: string, key: string): string | undefined;
+}

package/dist/interactions/prompts.js

@@ -0,0 +1,246 @@
+/**
+ * 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.
+ *
+ * Retention (release-readiness spec 4 §§2–4): the persisted file is
+ * version 2 — `prompts` rows plus a `settled` tombstone map carrying
+ * the settlement timestamp and outcome text. Seven days after
+ * settlement the bulky row (refs/plan) expires; the compact tombstone
+ * persists PERMANENTLY so a delayed receipt or replay can never
+ * resurrect an answerable prompt. Pending rows are never age-pruned.
+ * Pruning runs at store initialization and at most once per write (no
+ * timer), through the one `prune` helper and its boundary predicate.
+ * Refs/plans are therefore bounded by active prompts plus seven days
+ * of settled history; the tombstone set is deliberately unbounded.
+ */
+import { JsonFile } from "../state/json-file.js";
+/** Settled-row retention (matches the delivery ledger's seven days). */
+export const PROMPT_RETENTION_MS = 604_800_000;
+/** The persisted schema version (v1 = unversioned, `settled: string[]`). */
+const PROMPT_FILE_VERSION = 2;
+export class PromptStore {
+    file;
+    now;
+    log;
+    rows;
+    settled;
+    constructor(path, options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.log = options.log;
+        this.file = new JsonFile(path, () => ({
+            version: PROMPT_FILE_VERSION,
+            prompts: [],
+            settled: {},
+        }));
+        const state = this.file.readSync();
+        const migrated = migrate(state, this.now(), this.log);
+        // Initialization pruning rides the same helper the writes use.
+        prune(migrated, this.now());
+        // Persist the normalized/pruned shape ONLY when something changed:
+        // a legacy or repaired file must not re-migrate on every boot,
+        // while a healthy v2 file needs no rewrite at construction.
+        if (JSON.stringify(state) !== JSON.stringify(migrated)) {
+            this.file.updateSync((draft) => {
+                draft.version = migrated.version;
+                draft.prompts = migrated.prompts;
+                draft.settled = migrated.settled;
+            });
+        }
+        this.rows = migrated.prompts;
+        this.settled = migrated.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}`;
+            const tombstone = draft.settled[identity];
+            const existing = draft.prompts.find((row) => identityOf(row) === identity);
+            // Settlement is CALL-scoped, not only row-scoped. A settlement
+            // landing before the first row exists still records a marker;
+            // otherwise a later fan-out/receipt could create an answerable
+            // prompt for an already-settled interaction. A real receipt may
+            // still install refs on a surviving row for the settlement edit.
+            if (existing === undefined && draft.settled[`${conversationId}:${callId}:`] !== undefined)
+                return;
+            if (tombstone !== undefined) {
+                // A settlement raced this record. An EMPTY ref never replaces
+                // a delivered one; a REAL ref still installs while the row
+                // survives so the late receipt can self-heal the edit. Once
+                // the row is pruned, BOTH shapes are ignored — no resurrection.
+                const existing = draft.prompts.find((row) => identityOf(row) === identity);
+                if (existing === undefined)
+                    return;
+                if (ref.messageId === "")
+                    return;
+                if (existing.ref.messageId !== "")
+                    return;
+            }
+            const next = { conversationId, callId, key, ref, plan };
+            if (existing === undefined)
+                draft.prompts.push(next);
+            else
+                draft.prompts[draft.prompts.indexOf(existing)] = next;
+            prune(draft, this.now());
+        });
+        this.rows = state.prompts;
+        this.settled = 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[identityOf(row)] === undefined)
+            .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[identityOf(candidate)] === undefined);
+        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; the refs stay until retention expires them. */
+    async settle(conversationId, callId, outcome = "answered") {
+        const state = await this.file.update((draft) => {
+            const keys = [
+                `${conversationId}:${callId}:`,
+                ...draft.prompts
+                    .filter((row) => row.conversationId === conversationId && row.callId === callId)
+                    .map(identityOf),
+            ];
+            for (const identity of keys) {
+                // Re-settling an already-settled interaction keeps the FIRST
+                // settlement's timestamp and outcome: retention is measured
+                // from settlement, never extended by later writes.
+                if (draft.settled[identity] !== undefined)
+                    continue;
+                draft.settled[identity] = { at: this.now(), outcome };
+            }
+            prune(draft, this.now());
+        });
+        this.rows = state.prompts;
+        this.settled = state.settled;
+    }
+    /**
+     * The outcome text recorded at settlement, when this identity is
+     * settled. The receipt path reads it to self-heal the prompt edit;
+     * the tombstone outlives the bulky row, so the answer survives
+     * pruning even when no editable ref remains.
+     */
+    settledOutcome(conversationId, callId, key) {
+        return this.settled[`${conversationId}:${callId}:${key}`]?.outcome
+            ?? this.settled[`${conversationId}:${callId}:`]?.outcome;
+    }
+}
+/**
+ * THE retention helper (init and every write call this, at most once
+ * per write): a SETTLED row expires at `settledAt + RETENTION_MS <= now`.
+ * The tombstone itself is never pruned — it is what stops a delayed
+ * receipt from recreating an answerable prompt. Pending rows are
+ * never age-pruned.
+ */
+function prune(draft, now) {
+    draft.prompts = draft.prompts.filter((row) => {
+        const tombstone = draft.settled[identityOf(row)];
+        if (tombstone === undefined)
+            return true;
+        return tombstone.at + PROMPT_RETENTION_MS > now;
+    });
+}
+/**
+ * Normalize whatever was on disk to the v2 shape. An unversioned v1
+ * file keeps every prompt row and stamps its settled identities with
+ * the MIGRATION time (one cohort, expiring together seven days later).
+ * Individually malformed tombstones are dropped with a log line each;
+ * valid unrelated rows are never discarded. A wholly malformed JSON
+ * document never reaches here — JsonFile throws naming the path.
+ */
+function migrate(state, now, log) {
+    const prompts = Array.isArray(state.prompts) ? state.prompts : [];
+    const settled = {};
+    const raw = state.settled;
+    if (Array.isArray(raw)) {
+        // v1: bare identities, age unknown — the migration timestamp is
+        // the conservative choice (one further retention window).
+        for (const identity of raw) {
+            if (typeof identity !== "string")
+                continue;
+            settled[identity] = { at: now, outcome: "answered" };
+        }
+    }
+    else if (raw !== null && typeof raw === "object") {
+        for (const [identity, value] of Object.entries(raw)) {
+            const tombstone = value;
+            if (tombstone === null || typeof tombstone !== "object" ||
+                typeof tombstone.at !== "number" || !Number.isFinite(tombstone.at) ||
+                typeof tombstone.outcome !== "string") {
+                log?.warn(`prompts: dropping malformed settled tombstone "${identity}" (its row, if any, stays live)`);
+                continue;
+            }
+            if (!validIdentity(identity)) {
+                log?.warn(`prompts: dropping settled tombstone with a malformed identity "${identity}"`);
+                continue;
+            }
+            settled[identity] = { at: tombstone.at, outcome: tombstone.outcome };
+        }
+    }
+    else if (raw !== undefined) {
+        log?.warn("prompts: ignoring malformed settled container (expected an array or map)");
+    }
+    return { version: PROMPT_FILE_VERSION, prompts, settled };
+}
+function identityOf(row) {
+    return `${row.conversationId}:${row.callId}:${row.key}`;
+}
+/**
+ * An identity is `<conversationId>:<callId>:<key>` — a positive integer
+ * conversation id, a non-empty callId without colons, and a non-empty
+ * key (opaque binding/home keys may themselves contain colons).
+ */
+function validIdentity(identity) {
+    const separator = identity.indexOf(":");
+    if (separator <= 0)
+        return false;
+    if (!/^[1-9][0-9]*$/.test(identity.slice(0, separator)))
+        return false;
+    const rest = identity.slice(separator + 1);
+    const second = rest.indexOf(":");
+    // The empty key is the call-level settlement marker, written when
+    // settlement precedes prompt-row creation.
+    if (second === rest.length - 1)
+        return true;
+    return second > 0;
+}

package/dist/interactions/receipts.d.ts

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

package/dist/interactions/receipts.js

@@ -0,0 +1,69 @@
+/** Map a delivered interaction ledger row back to its recipient key. */
+import { enqueueSettlementEdits } from "./chat.js";
+export async function receiptForInteraction(prompts, entry, receipt, deps) {
+    // 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);
+        const conversationId = Number(match[1]);
+        await prompts.recordReceipt(conversationId, callId, entry.bindingKey, entry.chat, receipt.messageIds);
+        await healSettledPrompt(prompts, deps, conversationId, callId, entry.bindingKey, 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);
+        await healSettledPrompt(prompts, deps, conversationId, row.callId, row.key, receipt.messageIds);
+        return;
+    }
+}
+/**
+ * A real receipt for an ALREADY-settled prompt self-heals the live
+ * buttons: settlement ran with an empty ref (no edit possible, so a
+ * notice went out), and this delivered message is the one that now
+ * needs the outcome edit. The edit tag is the same the settlement
+ * path would have used, so a repeat receipt stays a no-op.
+ */
+async function healSettledPrompt(prompts, deps, conversationId, callId, key, messageIds) {
+    if (deps === undefined)
+        return;
+    if (messageIds.length === 0 || messageIds[0] === "")
+        return;
+    const outcome = prompts.settledOutcome(conversationId, callId, key);
+    if (outcome === undefined)
+        return;
+    // Tombstones outlive their bulky rows. A receipt AFTER pruning must
+    // be a true no-op: with no surviving row/ref, the settlement helper
+    // would otherwise take its fallback and enqueue duplicate notices.
+    const ref = prompts.refsOf(conversationId, callId)
+        .find((candidate) => candidate.messageId === messageIds[0]);
+    if (ref === undefined)
+        return;
+    try {
+        await enqueueSettlementEdits(deps, conversationId, callId, outcome);
+    }
+    catch (error) {
+        deps.log.error(`settled prompt receipt heal failed (${conversationId}:${callId})`, error);
+    }
+}

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;
+}