@odience-network/paperclip-plugin-telegram-enhanced 0.2.0

package/dist/file-routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-routing.js","sourceRoot":"","sources":["../src/file-routing.ts"],"names":[],"mappings":"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"}

package/dist/formatters.d.ts

@@ -0,0 +1,31 @@
+import type { PluginEvent } from "@paperclipai/plugin-sdk";
+import type { SendMessageOptions } from "./telegram-api.js";
+type FormattedMessage = {
+    text: string;
+    options: SendMessageOptions;
+};
+export type IssueLinksOpts = {
+    baseUrl?: string;
+    issuePrefix?: string;
+};
+/**
+ * Build the text for a resolved approval/decision card.
+ *
+ * Ported from the tue-Jonas fork (TWX-619): rather than collapsing the card to
+ * a bare status line, preserve the original card context (issue identifier,
+ * title, description) and append a resolution footer so the message stays
+ * legible after the buttons are removed. Falls back to just the footer when no
+ * original text is available. The original text from Telegram is plain (entity
+ * formatting stripped), so it is MarkdownV2-escaped before being re-sent.
+ */
+export declare function formatResolvedDecision(originalText: string | undefined | null, decision: "approved" | "rejected", actor: string): string;
+export declare function formatIssueCreated(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatIssueAssigned(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatIssueDone(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatIssueBlocked(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatBoardMention(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatApprovalCreated(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatAgentError(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatAgentRunStarted(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export declare function formatAgentRunFinished(event: PluginEvent, opts?: IssueLinksOpts): FormattedMessage;
+export {};

package/dist/formatters.js

@@ -0,0 +1,336 @@
+import { escapeMarkdownV2, truncateAtWord } from "./telegram-api.js";
+function esc(s) {
+    return escapeMarkdownV2(s);
+}
+function bold(s) {
+    return `*${esc(s)}*`;
+}
+function code(s) {
+    return `\`${esc(s)}\``;
+}
+function isExternalUrl(url) {
+    return !!url && url.startsWith("https://");
+}
+function issueLink(identifier, opts) {
+    if (opts?.baseUrl && opts?.issuePrefix) {
+        const url = `${opts.baseUrl}/${opts.issuePrefix}/issues/${identifier}`;
+        return `[${esc(identifier)}](${url})`;
+    }
+    return bold(identifier);
+}
+function issueButton(identifier, opts) {
+    if (opts?.baseUrl && opts?.issuePrefix && isExternalUrl(opts.baseUrl)) {
+        return { text: `Open ${identifier} ↗`, url: `${opts.baseUrl}/${opts.issuePrefix}/issues/${identifier}` };
+    }
+    return null;
+}
+function agentButton(agentId, label, publicUrl) {
+    if (publicUrl && isExternalUrl(publicUrl)) {
+        return { text: label, url: `${publicUrl}/agents/${agentId}` };
+    }
+    return null;
+}
+function runButton(agentId, runId, publicUrl) {
+    if (publicUrl && isExternalUrl(publicUrl) && runId) {
+        return { text: "View Run ↗", url: `${publicUrl}/agents/${agentId}/runs/${runId}` };
+    }
+    return null;
+}
+/**
+ * Build the text for a resolved approval/decision card.
+ *
+ * Ported from the tue-Jonas fork (TWX-619): rather than collapsing the card to
+ * a bare status line, preserve the original card context (issue identifier,
+ * title, description) and append a resolution footer so the message stays
+ * legible after the buttons are removed. Falls back to just the footer when no
+ * original text is available. The original text from Telegram is plain (entity
+ * formatting stripped), so it is MarkdownV2-escaped before being re-sent.
+ */
+export function formatResolvedDecision(originalText, decision, actor) {
+    const icon = decision === "approved" ? "✅" : "❌";
+    const label = decision === "approved" ? "Approved" : "Rejected";
+    const footer = `${esc(icon)} ${bold(label)} by ${esc(actor)}`;
+    const trimmed = (originalText ?? "").trim();
+    if (!trimmed)
+        return footer;
+    return `${esc(trimmed)}\n\n${footer}`;
+}
+function classifyAgentError(errorMessage) {
+    if (/timed?\s*out|timeout/i.test(errorMessage))
+        return "Agent Timeout";
+    if (/limit|rate.?limit|quota/i.test(errorMessage))
+        return "Agent Rate Limit";
+    return "Agent Error";
+}
+export function formatIssueCreated(event, opts) {
+    const p = event.payload;
+    const identifier = String(p.identifier ?? event.entityId);
+    const title = String(p.title ?? "Untitled");
+    const status = p.status ? String(p.status) : null;
+    const priority = p.priority ? String(p.priority) : null;
+    const assigneeName = p.assigneeName ? String(p.assigneeName) : null;
+    const projectName = p.projectName ? String(p.projectName) : null;
+    const lines = [
+        `${esc("📋")} ${bold("Issue Created")}: ${issueLink(identifier, opts)}`,
+        bold(title),
+    ];
+    const meta = [];
+    if (status)
+        meta.push(`Status: ${code(status)}`);
+    if (priority)
+        meta.push(`Priority: ${code(priority)}`);
+    if (assigneeName)
+        meta.push(`Assignee: ${esc(assigneeName)}`);
+    if (projectName)
+        meta.push(`Project: ${esc(projectName)}`);
+    if (meta.length > 0)
+        lines.push(meta.join(" \\| "));
+    if (p.description) {
+        const desc = truncateAtWord(String(p.description), 200);
+        lines.push(`\n${esc(">")} ${esc(desc)}`);
+    }
+    const button = issueButton(identifier, opts);
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            ...(button ? { inlineKeyboard: [[button]] } : {}),
+        },
+    };
+}
+export function formatIssueAssigned(event, opts) {
+    const p = event.payload;
+    const prev = p._previous ?? {};
+    const identifier = String(p.identifier ?? event.entityId);
+    const title = String(p.title ?? "Untitled");
+    const assigneeName = p.assigneeName ? String(p.assigneeName) : null;
+    const prevAssigneeName = prev.assigneeName ? String(prev.assigneeName) : null;
+    const lines = [
+        `${esc("🎯")} ${bold("Issue Assigned")}: ${issueLink(identifier, opts)}`,
+        bold(title),
+    ];
+    if (assigneeName) {
+        lines.push(prevAssigneeName
+            ? `Assignee: ${esc(prevAssigneeName)} ${esc("→")} ${esc(assigneeName)}`
+            : `Assignee: ${esc(assigneeName)}`);
+    }
+    else {
+        lines.push(esc("Unassigned"));
+    }
+    const button = issueButton(identifier, opts);
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            ...(button ? { inlineKeyboard: [[button]] } : {}),
+        },
+    };
+}
+export function formatIssueDone(event, opts) {
+    const p = event.payload;
+    const identifier = String(p.identifier ?? event.entityId);
+    const title = String(p.title ?? "");
+    const comment = p.comment ? String(p.comment) : null;
+    const lines = [
+        `${esc("✅")} ${bold("Issue Completed")}: ${issueLink(identifier, opts)}`,
+        `${bold(title)} ${esc("is now done.")}`,
+    ];
+    if (comment) {
+        const truncated = truncateAtWord(comment, 300);
+        lines.push(`\n${esc(">")} ${esc(truncated)}`);
+    }
+    const button = issueButton(identifier, opts);
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            ...(button ? { inlineKeyboard: [[button]] } : {}),
+        },
+    };
+}
+export function formatIssueBlocked(event, opts) {
+    const p = event.payload;
+    const identifier = String(p.identifier ?? event.entityId);
+    const title = String(p.title ?? "Untitled");
+    const assigneeName = p.assigneeName ? String(p.assigneeName) : null;
+    const reason = p.comment ? String(p.comment) : null;
+    const lines = [
+        `${esc("🚫")} ${bold("Issue Blocked")}: ${issueLink(identifier, opts)}`,
+        bold(title),
+    ];
+    if (assigneeName)
+        lines.push(`Assignee: ${esc(assigneeName)}`);
+    if (reason) {
+        const truncated = truncateAtWord(reason, 300);
+        lines.push(`\n${esc(">")} ${esc(truncated)}`);
+    }
+    const button = issueButton(identifier, opts);
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            ...(button ? { inlineKeyboard: [[button]] } : {}),
+        },
+    };
+}
+export function formatBoardMention(event, opts) {
+    const p = event.payload;
+    const identifier = String(p.identifier ?? p.issueIdentifier ?? p.issueId ?? event.entityId);
+    const title = p.title ?? p.issueTitle ? String(p.title ?? p.issueTitle) : null;
+    const author = p.authorName ?? p.author ?? p.userName ?? p.agentName;
+    const authorName = author ? String(author) : null;
+    const body = String(p.body ?? p.comment ?? p.text ?? "");
+    const lines = [
+        `${esc("📣")} ${bold("Board Mention")}: ${issueLink(identifier, opts)}`,
+    ];
+    if (title)
+        lines.push(bold(title));
+    if (authorName)
+        lines.push(`From: ${esc(authorName)}`);
+    if (body) {
+        const truncated = truncateAtWord(body, 300);
+        lines.push(`\n${esc(">")} ${esc(truncated)}`);
+    }
+    const button = issueButton(identifier, opts);
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            ...(button ? { inlineKeyboard: [[button]] } : {}),
+        },
+    };
+}
+export function formatApprovalCreated(event, opts) {
+    const p = event.payload;
+    const approvalType = String(p.type ?? "unknown");
+    const approvalId = String(p.approvalId ?? event.entityId);
+    const title = String(p.title ?? "Approval Requested");
+    const description = p.description ? String(p.description) : null;
+    const agentName = p.agentName ? String(p.agentName) : null;
+    const lines = [
+        `${esc("🔔")} ${bold("Approval Requested")}`,
+        bold(title),
+    ];
+    if (agentName)
+        lines.push(`Agent: ${esc(agentName)} \\| Type: ${code(approvalType)}`);
+    if (description)
+        lines.push(`\n${esc(truncateAtWord(description, 300))}`);
+    // Add linked issues if present
+    const linkedIssues = Array.isArray(p.linkedIssues) ? p.linkedIssues : [];
+    if (linkedIssues.length > 0) {
+        lines.push(`\n${bold(`Linked Issues (${String(linkedIssues.length)})`)}`);
+        for (const issue of linkedIssues.slice(0, 5)) {
+            const issueId = String(issue.identifier ?? "?");
+            const issueParts = [`${issueLink(issueId, opts)} ${esc(String(issue.title ?? ""))}`];
+            const issueMeta = [];
+            if (issue.status)
+                issueMeta.push(String(issue.status));
+            if (issue.priority)
+                issueMeta.push(String(issue.priority));
+            if (issue.assignee)
+                issueMeta.push(`-> ${String(issue.assignee)}`);
+            if (issueMeta.length > 0)
+                issueParts.push(`\\(${esc(issueMeta.join(" | "))}\\)`);
+            lines.push(issueParts.join(" "));
+        }
+    }
+    const keyboard = [
+        [
+            { text: "Approve", callback_data: `approve_${approvalId}` },
+            { text: "Reject", callback_data: `reject_${approvalId}` },
+        ],
+    ];
+    // Add deep link to the first linked issue if available
+    if (linkedIssues.length > 0) {
+        const firstIssueId = String(linkedIssues[0].identifier ?? "");
+        if (firstIssueId) {
+            const btn = issueButton(firstIssueId, opts);
+            if (btn)
+                keyboard.push([btn]);
+        }
+    }
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            inlineKeyboard: keyboard,
+        },
+    };
+}
+export function formatAgentError(event, opts) {
+    const p = event.payload;
+    const agentId = String(p.agentId ?? event.entityId);
+    const agentName = String(p.agentName ?? p.name ?? agentId);
+    const errorMessage = String(p.error ?? p.message ?? "Unknown error");
+    const runId = p.runId ? String(p.runId) : null;
+    const companyName = p.companyName ? String(p.companyName) : null;
+    const issueIdentifier = p.issueIdentifier ? String(p.issueIdentifier) : null;
+    const issueTitle = p.issueTitle ? String(p.issueTitle) : null;
+    const lines = [
+        `${esc("❌")} ${bold(classifyAgentError(errorMessage))}`,
+        `Agent: ${bold(agentName)}`,
+    ];
+    if (companyName)
+        lines.push(`Company: ${esc(companyName)}`);
+    if (issueIdentifier) {
+        lines.push(issueTitle
+            ? `Issue: ${issueLink(issueIdentifier, opts)} ${esc("—")} ${esc(issueTitle)}`
+            : `Issue: ${issueLink(issueIdentifier, opts)}`);
+    }
+    lines.push(`\n${code(truncateAtWord(errorMessage, 500))}`);
+    const buttons = [
+        runButton(agentId, runId, opts?.baseUrl),
+        issueIdentifier ? issueButton(issueIdentifier, opts) : null,
+        agentButton(agentId, "View Agent ↗", opts?.baseUrl),
+    ].filter((button) => Boolean(button));
+    return {
+        text: lines.join("\n"),
+        options: {
+            parseMode: "MarkdownV2",
+            ...(buttons.length > 0 ? { inlineKeyboard: [buttons] } : {}),
+        },
+    };
+}
+export function formatAgentRunStarted(event, opts) {
+    const p = event.payload;
+    const agentId = String(p.agentId ?? event.entityId);
+    const agentName = String(p.agentName ?? agentId);
+    const runId = p.runId ? String(p.runId) : null;
+    const buttons = [];
+    if (opts?.baseUrl && isExternalUrl(opts.baseUrl)) {
+        const url = runId
+            ? `${opts.baseUrl}/agents/${agentId}/runs/${runId}`
+            : `${opts.baseUrl}/agents/${agentId}`;
+        buttons.push({ text: "View Run ↗", url });
+    }
+    return {
+        text: `${esc("▶️")} ${bold(agentName)} ${esc("started a new run")}`,
+        options: {
+            parseMode: "MarkdownV2",
+            disableNotification: true,
+            ...(buttons.length > 0 ? { inlineKeyboard: [buttons] } : {}),
+        },
+    };
+}
+export function formatAgentRunFinished(event, opts) {
+    const p = event.payload;
+    const agentId = String(p.agentId ?? event.entityId);
+    const agentName = String(p.agentName ?? agentId);
+    const runId = p.runId ? String(p.runId) : null;
+    const buttons = [];
+    if (opts?.baseUrl && isExternalUrl(opts.baseUrl)) {
+        const url = runId
+            ? `${opts.baseUrl}/agents/${agentId}/runs/${runId}`
+            : `${opts.baseUrl}/agents/${agentId}`;
+        buttons.push({ text: "View Run ↗", url });
+    }
+    return {
+        text: `${esc("⏹️")} ${bold(agentName)} ${esc("completed successfully")}`,
+        options: {
+            parseMode: "MarkdownV2",
+            disableNotification: true,
+            ...(buttons.length > 0 ? { inlineKeyboard: [buttons] } : {}),
+        },
+    };
+}
+//# sourceMappingURL=formatters.js.map

package/dist/formatters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.js","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { default as manifest } from "./manifest.js";
+export { TelegramAdapter } from "./adapter.js";
+export type { PlatformAdapter, MessageRef, ActionButton, SendOpts } from "./adapter.js";
+export { EscalationManager } from "./escalation.js";
+export type { EscalationEvent, EscalationResponse, EscalationReason } from "./escalation.js";
+export type { ChatSession } from "./acp-bridge.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { default as manifest } from "./manifest.js";
+export { TelegramAdapter } from "./adapter.js";
+export { EscalationManager } from "./escalation.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/interaction-delivery.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Interaction-notification dedupe + idempotency guard.
+ *
+ * Ported (logic only) from the tue-Jonas fork — `paperclip-plugin-telegram`
+ * TWX-136 (commits 8d1f0a2, 32caca9, 17ad4c6, 7bcbab0). The upstream change
+ * tracked deliveries in a host DB migration (`001_interaction_deliveries.sql`).
+ * We re-implement against our module layout and back the delivery-tracking
+ * state with the SDK key/value store (`ctx.state`) so the plugin does not take
+ * on a host migration dependency.
+ *
+ * Why this exists: Paperclip's core can re-emit the same plugin event for a
+ * single underlying change (route logging + heartbeat reconciliation), and a
+ * worker can crash or be retried mid-send. Both produce duplicate Telegram
+ * notifications. This guard claims a durable delivery slot before sending,
+ * skips work when a slot is already delivered (idempotency), and releases the
+ * claim when a send fails so a later retry can re-attempt (no lost messages).
+ *
+ * The in-memory sliding-window dedupe in `worker.ts` remains as a cheap
+ * fast-path for the burst case; this guard is the durable backstop that
+ * survives worker restarts and guarantees at-most-once delivery per key.
+ */
+import type { PluginContext } from "@paperclipai/plugin-sdk";
+/** Default window after which a still-`pending` claim is treated as abandoned. */
+export declare const DEFAULT_CLAIM_STALE_MS = 60000;
+export type DeliveryStatus = "pending" | "delivered";
+export interface DeliveryRecord {
+    status: DeliveryStatus;
+    /** ISO timestamp the most recent claim was taken. */
+    claimedAt: string;
+    /** ISO timestamp the notification was confirmed sent. */
+    deliveredAt?: string;
+    /** Telegram message id of the delivered notification, when known. */
+    messageId?: number;
+    /** Number of times a claim has been taken for this key (best-effort). */
+    attempts: number;
+}
+export type ClaimOutcome = "claimed" | "already_delivered" | "in_flight";
+export interface ClaimResult {
+    outcome: ClaimOutcome;
+    record: DeliveryRecord;
+}
+export interface DeliveryGuardOptions {
+    /**
+     * How long a `pending` (claimed-but-unsent) slot is honored before it is
+     * considered abandoned and may be re-claimed. Guards against a worker that
+     * crashed between claim and send leaving a permanently stuck slot.
+     */
+    staleMs?: number;
+    /** Injectable clock for deterministic tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Build a deterministic, collision-resistant state key for a delivery slot.
+ *
+ * Callers pass the logically-significant parts of the notification (chat,
+ * topic, entity, event, and any handler-specific discriminator). The same
+ * logical notification must always produce the same key; distinct
+ * notifications must not collide.
+ */
+export declare function buildDeliveryKey(...parts: Array<string | number | null | undefined>): string;
+/**
+ * Attempt to claim a delivery slot.
+ *
+ * - `already_delivered` — a prior attempt completed; skip the send (idempotent).
+ * - `in_flight` — another attempt holds a fresh `pending` claim; skip to avoid a
+ *   duplicate. (Stale `pending` claims are reclaimed and return `claimed`.)
+ * - `claimed` — caller owns the slot and must send, then call
+ *   {@link markDelivered} on success or {@link releaseDelivery} on failure.
+ */
+export declare function claimDelivery(ctx: PluginContext, key: string, options?: DeliveryGuardOptions): Promise<ClaimResult>;
+/** Mark a previously-claimed slot as delivered (idempotent terminal state). */
+export declare function markDelivered(ctx: PluginContext, key: string, messageId?: number, options?: DeliveryGuardOptions): Promise<void>;
+/**
+ * Release an unsent claim so a future retry can re-attempt delivery.
+ *
+ * Only releases slots that are still `pending` — a `delivered` slot is a
+ * terminal success and must never be cleared, or duplicates would resume.
+ */
+export declare function releaseDelivery(ctx: PluginContext, key: string): Promise<void>;
+/**
+ * Run `send` under the idempotency guard.
+ *
+ * Claims the slot, and on `claimed` invokes `send`. A truthy/`number` result is
+ * recorded as delivered (and returned); a falsy result or a thrown error
+ * releases the claim so a retry can re-send. When the slot is already delivered
+ * or another attempt is in-flight, `send` is not invoked and `null` is returned.
+ *
+ * @returns the value from `send` on a fresh successful delivery, otherwise `null`.
+ */
+export declare function withIdempotentDelivery<T extends number | undefined | null>(ctx: PluginContext, key: string, send: () => Promise<T>, options?: DeliveryGuardOptions): Promise<T | null>;

package/dist/interaction-delivery.js

@@ -0,0 +1,142 @@
+/**
+ * Interaction-notification dedupe + idempotency guard.
+ *
+ * Ported (logic only) from the tue-Jonas fork — `paperclip-plugin-telegram`
+ * TWX-136 (commits 8d1f0a2, 32caca9, 17ad4c6, 7bcbab0). The upstream change
+ * tracked deliveries in a host DB migration (`001_interaction_deliveries.sql`).
+ * We re-implement against our module layout and back the delivery-tracking
+ * state with the SDK key/value store (`ctx.state`) so the plugin does not take
+ * on a host migration dependency.
+ *
+ * Why this exists: Paperclip's core can re-emit the same plugin event for a
+ * single underlying change (route logging + heartbeat reconciliation), and a
+ * worker can crash or be retried mid-send. Both produce duplicate Telegram
+ * notifications. This guard claims a durable delivery slot before sending,
+ * skips work when a slot is already delivered (idempotency), and releases the
+ * claim when a send fails so a later retry can re-attempt (no lost messages).
+ *
+ * The in-memory sliding-window dedupe in `worker.ts` remains as a cheap
+ * fast-path for the burst case; this guard is the durable backstop that
+ * survives worker restarts and guarantees at-most-once delivery per key.
+ */
+/** Default window after which a still-`pending` claim is treated as abandoned. */
+export const DEFAULT_CLAIM_STALE_MS = 60_000;
+const STATE_KEY_PREFIX = "interaction_delivery_";
+/**
+ * Build a deterministic, collision-resistant state key for a delivery slot.
+ *
+ * Callers pass the logically-significant parts of the notification (chat,
+ * topic, entity, event, and any handler-specific discriminator). The same
+ * logical notification must always produce the same key; distinct
+ * notifications must not collide.
+ */
+export function buildDeliveryKey(...parts) {
+    const joined = parts
+        .map((p) => (p === null || p === undefined ? "" : String(p)))
+        .join("|");
+    // Sanitize to keep the composite state key readable and storage-safe.
+    return joined.replace(/[^A-Za-z0-9._:|-]/g, "_");
+}
+function stateScope(key) {
+    return { scopeKind: "instance", stateKey: `${STATE_KEY_PREFIX}${key}` };
+}
+async function readRecord(ctx, key) {
+    const raw = (await ctx.state.get(stateScope(key)));
+    if (!raw || typeof raw !== "object")
+        return null;
+    if (raw.status !== "pending" && raw.status !== "delivered")
+        return null;
+    return raw;
+}
+/**
+ * Attempt to claim a delivery slot.
+ *
+ * - `already_delivered` — a prior attempt completed; skip the send (idempotent).
+ * - `in_flight` — another attempt holds a fresh `pending` claim; skip to avoid a
+ *   duplicate. (Stale `pending` claims are reclaimed and return `claimed`.)
+ * - `claimed` — caller owns the slot and must send, then call
+ *   {@link markDelivered} on success or {@link releaseDelivery} on failure.
+ */
+export async function claimDelivery(ctx, key, options = {}) {
+    const now = options.now ?? Date.now;
+    const staleMs = options.staleMs ?? DEFAULT_CLAIM_STALE_MS;
+    const existing = await readRecord(ctx, key);
+    if (existing?.status === "delivered") {
+        return { outcome: "already_delivered", record: existing };
+    }
+    if (existing?.status === "pending") {
+        const age = now() - Date.parse(existing.claimedAt);
+        if (Number.isFinite(age) && age < staleMs) {
+            return { outcome: "in_flight", record: existing };
+        }
+        // Stale claim — reclaim it (previous attempt likely crashed mid-send).
+    }
+    const record = {
+        status: "pending",
+        claimedAt: new Date(now()).toISOString(),
+        attempts: (existing?.attempts ?? 0) + 1,
+    };
+    await ctx.state.set(stateScope(key), record);
+    return { outcome: "claimed", record };
+}
+/** Mark a previously-claimed slot as delivered (idempotent terminal state). */
+export async function markDelivered(ctx, key, messageId, options = {}) {
+    const now = options.now ?? Date.now;
+    const existing = await readRecord(ctx, key);
+    const record = {
+        status: "delivered",
+        claimedAt: existing?.claimedAt ?? new Date(now()).toISOString(),
+        deliveredAt: new Date(now()).toISOString(),
+        attempts: existing?.attempts ?? 1,
+        ...(messageId !== undefined ? { messageId } : {}),
+    };
+    await ctx.state.set(stateScope(key), record);
+}
+/**
+ * Release an unsent claim so a future retry can re-attempt delivery.
+ *
+ * Only releases slots that are still `pending` — a `delivered` slot is a
+ * terminal success and must never be cleared, or duplicates would resume.
+ */
+export async function releaseDelivery(ctx, key) {
+    const existing = await readRecord(ctx, key);
+    if (!existing || existing.status === "delivered")
+        return;
+    if (typeof ctx.state.delete === "function") {
+        await ctx.state.delete(stateScope(key));
+    }
+    else {
+        // Fallback for hosts/mocks without delete: null out the slot.
+        await ctx.state.set(stateScope(key), null);
+    }
+}
+/**
+ * Run `send` under the idempotency guard.
+ *
+ * Claims the slot, and on `claimed` invokes `send`. A truthy/`number` result is
+ * recorded as delivered (and returned); a falsy result or a thrown error
+ * releases the claim so a retry can re-send. When the slot is already delivered
+ * or another attempt is in-flight, `send` is not invoked and `null` is returned.
+ *
+ * @returns the value from `send` on a fresh successful delivery, otherwise `null`.
+ */
+export async function withIdempotentDelivery(ctx, key, send, options = {}) {
+    const claim = await claimDelivery(ctx, key, options);
+    if (claim.outcome !== "claimed")
+        return null;
+    let result;
+    try {
+        result = await send();
+    }
+    catch (err) {
+        await releaseDelivery(ctx, key);
+        throw err;
+    }
+    if (result === null || result === undefined) {
+        await releaseDelivery(ctx, key);
+        return null;
+    }
+    await markDelivered(ctx, key, typeof result === "number" ? result : undefined, options);
+    return result;
+}
+//# sourceMappingURL=interaction-delivery.js.map