@noxsoft/anima 2.0.0

package/dist/plugin-sdk/infra/format-time/format-datetime.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Centralized date/time formatting utilities.
+ *
+ * All formatters are timezone-aware, using Intl.DateTimeFormat.
+ * Consolidates duplicated formatUtcTimestamp / formatZonedTimestamp / resolveExplicitTimezone
+ * that previously lived in envelope.ts and session-updates.ts.
+ */
+/**
+ * Validate an IANA timezone string. Returns the string if valid, undefined otherwise.
+ */
+export declare function resolveTimezone(value: string): string | undefined;
+export type FormatTimestampOptions = {
+    /** Include seconds in the output. Default: false */
+    displaySeconds?: boolean;
+};
+export type FormatZonedTimestampOptions = FormatTimestampOptions & {
+    /** IANA timezone string (e.g., 'America/New_York'). Default: system timezone */
+    timeZone?: string;
+};
+/**
+ * Format a Date as a UTC timestamp string.
+ *
+ * Without seconds: `2024-01-15T14:30Z`
+ * With seconds:    `2024-01-15T14:30:05Z`
+ */
+export declare function formatUtcTimestamp(date: Date, options?: FormatTimestampOptions): string;
+/**
+ * Format a Date with timezone display using Intl.DateTimeFormat.
+ *
+ * Without seconds: `2024-01-15 14:30 EST`
+ * With seconds:    `2024-01-15 14:30:05 EST`
+ *
+ * Returns undefined if Intl formatting fails.
+ */
+export declare function formatZonedTimestamp(date: Date, options?: FormatZonedTimestampOptions): string | undefined;

package/dist/plugin-sdk/infra/format-time/format-duration.d.ts

@@ -0,0 +1,23 @@
+export type FormatDurationSecondsOptions = {
+    decimals?: number;
+    unit?: "s" | "seconds";
+};
+export type FormatDurationCompactOptions = {
+    /** Add space between units: "2m 5s" instead of "2m5s". Default: false */
+    spaced?: boolean;
+};
+export declare function formatDurationSeconds(ms: number, options?: FormatDurationSecondsOptions): string;
+/** Precise decimal-seconds output: "500ms" or "1.23s". Input is milliseconds. */
+export declare function formatDurationPrecise(ms: number, options?: FormatDurationSecondsOptions): string;
+/**
+ * Compact compound duration: "500ms", "45s", "2m5s", "1h30m".
+ * With `spaced`: "45s", "2m 5s", "1h 30m".
+ * Omits trailing zero components: "1m" not "1m 0s", "2h" not "2h 0m".
+ * Returns undefined for null/undefined/non-finite/non-positive input.
+ */
+export declare function formatDurationCompact(ms?: number | null, options?: FormatDurationCompactOptions): string | undefined;
+/**
+ * Rounded single-unit duration for display: "500ms", "5s", "3m", "2h", "5d".
+ * Returns fallback string for null/undefined/non-finite input.
+ */
+export declare function formatDurationHuman(ms?: number | null, fallback?: string): string;

package/dist/plugin-sdk/infra/format-time/format-relative.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Centralized relative-time formatting utilities.
+ *
+ * Consolidates 7+ scattered implementations (formatAge, formatAgeShort, formatAgo,
+ * formatRelativeTime, formatElapsedTime) into two functions:
+ *
+ * - `formatTimeAgo(durationMs)` — format a duration as "5m ago" / "5m" (for known elapsed time)
+ * - `formatRelativeTimestamp(epochMs)` — format an epoch timestamp relative to now (handles future)
+ */
+export type FormatTimeAgoOptions = {
+    /** Append "ago" suffix. Default: true. When false, returns bare unit: "5m", "2h" */
+    suffix?: boolean;
+    /** Return value for invalid/null/negative input. Default: "unknown" */
+    fallback?: string;
+};
+/**
+ * Format a duration (in ms) as a human-readable relative time.
+ *
+ * Input: how many milliseconds ago something happened.
+ *
+ * With suffix (default):  "just now", "5m ago", "3h ago", "2d ago"
+ * Without suffix:         "0s", "5m", "3h", "2d"
+ */
+export declare function formatTimeAgo(durationMs: number | null | undefined, options?: FormatTimeAgoOptions): string;
+export type FormatRelativeTimestampOptions = {
+    /** If true, fall back to short date (e.g. "Oct 5") for timestamps >7 days. Default: false */
+    dateFallback?: boolean;
+    /** IANA timezone for date fallback display */
+    timezone?: string;
+    /** Return value for invalid/null input. Default: "n/a" */
+    fallback?: string;
+};
+/**
+ * Format an epoch timestamp relative to now.
+ *
+ * Handles both past ("5m ago") and future ("in 5m") timestamps.
+ * Optionally falls back to a short date for timestamps older than 7 days.
+ */
+export declare function formatRelativeTimestamp(timestampMs: number | null | undefined, options?: FormatRelativeTimestampOptions): string;

package/dist/plugin-sdk/infra/git-commit.d.ts

@@ -0,0 +1,4 @@
+export declare const resolveCommitHash: (options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => string | null;

package/dist/plugin-sdk/infra/heartbeat-active-hours.d.ts

@@ -0,0 +1,5 @@
+import type { AnimaConfig } from "../config/config.js";
+import type { AgentDefaultsConfig } from "../config/types.agent-defaults.js";
+type HeartbeatConfig = AgentDefaultsConfig["heartbeat"];
+export declare function isWithinActiveHours(cfg: AnimaConfig, heartbeat?: HeartbeatConfig, nowMs?: number): boolean;
+export {};

package/dist/plugin-sdk/infra/heartbeat-events-filter.d.ts

@@ -0,0 +1,3 @@
+export declare function buildCronEventPrompt(pendingEvents: string[]): string;
+export declare function isExecCompletionEvent(evt: string): boolean;
+export declare function isCronSystemEvent(evt: string): boolean;

package/dist/plugin-sdk/infra/heartbeat-events.d.ts

@@ -0,0 +1,21 @@
+export type HeartbeatIndicatorType = "ok" | "alert" | "error";
+export type HeartbeatEventPayload = {
+    ts: number;
+    status: "sent" | "ok-empty" | "ok-token" | "skipped" | "failed";
+    to?: string;
+    accountId?: string;
+    preview?: string;
+    durationMs?: number;
+    hasMedia?: boolean;
+    reason?: string;
+    /** The channel this heartbeat was sent to. */
+    channel?: string;
+    /** Whether the message was silently suppressed (showOk: false). */
+    silent?: boolean;
+    /** Indicator type for UI status display. */
+    indicatorType?: HeartbeatIndicatorType;
+};
+export declare function resolveIndicatorType(status: HeartbeatEventPayload["status"]): HeartbeatIndicatorType | undefined;
+export declare function emitHeartbeatEvent(evt: Omit<HeartbeatEventPayload, "ts">): void;
+export declare function onHeartbeatEvent(listener: (evt: HeartbeatEventPayload) => void): () => void;
+export declare function getLastHeartbeatEvent(): HeartbeatEventPayload | null;

package/dist/plugin-sdk/infra/heartbeat-runner.d.ts

@@ -0,0 +1,45 @@
+import type { ChannelHeartbeatDeps } from "../channels/plugins/types.js";
+import type { AnimaConfig } from "../config/config.js";
+import type { AgentDefaultsConfig } from "../config/types.agent-defaults.js";
+import type { OutboundSendDeps } from "./outbound/deliver.js";
+import { type RuntimeEnv } from "../runtime.js";
+import { isCronSystemEvent } from "./heartbeat-events-filter.js";
+import { type HeartbeatRunResult } from "./heartbeat-wake.js";
+type HeartbeatDeps = OutboundSendDeps & ChannelHeartbeatDeps & {
+    runtime?: RuntimeEnv;
+    getQueueSize?: (lane?: string) => number;
+    nowMs?: () => number;
+};
+export declare function setHeartbeatsEnabled(enabled: boolean): void;
+type HeartbeatConfig = AgentDefaultsConfig["heartbeat"];
+export type HeartbeatSummary = {
+    enabled: boolean;
+    every: string;
+    everyMs: number | null;
+    prompt: string;
+    target: string;
+    model?: string;
+    ackMaxChars: number;
+};
+export { isCronSystemEvent };
+export type HeartbeatRunner = {
+    stop: () => void;
+    updateConfig: (cfg: AnimaConfig) => void;
+};
+export declare function isHeartbeatEnabledForAgent(cfg: AnimaConfig, agentId?: string): boolean;
+export declare function resolveHeartbeatSummaryForAgent(cfg: AnimaConfig, agentId?: string): HeartbeatSummary;
+export declare function resolveHeartbeatIntervalMs(cfg: AnimaConfig, overrideEvery?: string, heartbeat?: HeartbeatConfig): number | null;
+export declare function resolveHeartbeatPrompt(cfg: AnimaConfig, heartbeat?: HeartbeatConfig): string;
+export declare function runHeartbeatOnce(opts: {
+    cfg?: AnimaConfig;
+    agentId?: string;
+    heartbeat?: HeartbeatConfig;
+    reason?: string;
+    deps?: HeartbeatDeps;
+}): Promise<HeartbeatRunResult>;
+export declare function startHeartbeatRunner(opts: {
+    cfg?: AnimaConfig;
+    runtime?: RuntimeEnv;
+    abortSignal?: AbortSignal;
+    runOnce?: typeof runHeartbeatOnce;
+}): HeartbeatRunner;

package/dist/plugin-sdk/infra/heartbeat-visibility.d.ts

@@ -0,0 +1,17 @@
+import type { AnimaConfig } from "../config/config.js";
+import type { GatewayMessageChannel } from "../utils/message-channel.js";
+export type ResolvedHeartbeatVisibility = {
+    showOk: boolean;
+    showAlerts: boolean;
+    useIndicator: boolean;
+};
+/**
+ * Resolve heartbeat visibility settings for a channel.
+ * Supports both deliverable channels (telegram, signal, etc.) and webchat.
+ * For webchat, uses channels.defaults.heartbeat since webchat doesn't have per-channel config.
+ */
+export declare function resolveHeartbeatVisibility(params: {
+    cfg: AnimaConfig;
+    channel: GatewayMessageChannel;
+    accountId?: string;
+}): ResolvedHeartbeatVisibility;

package/dist/plugin-sdk/infra/heartbeat-wake.d.ts

@@ -0,0 +1,27 @@
+export type HeartbeatRunResult = {
+    status: "ran";
+    durationMs: number;
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "failed";
+    reason: string;
+};
+export type HeartbeatWakeHandler = (opts: {
+    reason?: string;
+}) => Promise<HeartbeatRunResult>;
+/**
+ * Register (or clear) the heartbeat wake handler.
+ * Returns a disposer function that clears this specific registration.
+ * Stale disposers (from previous registrations) are no-ops, preventing
+ * a race where an old runner's cleanup clears a newer runner's handler.
+ */
+export declare function setHeartbeatWakeHandler(next: HeartbeatWakeHandler | null): () => void;
+export declare function requestHeartbeatNow(opts?: {
+    reason?: string;
+    coalesceMs?: number;
+}): void;
+export declare function hasHeartbeatWakeHandler(): boolean;
+export declare function hasPendingHeartbeatWake(): boolean;
+export declare function resetHeartbeatWakeStateForTests(): void;

package/dist/plugin-sdk/infra/home-dir.d.ts

@@ -0,0 +1,7 @@
+export declare function resolveEffectiveHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string | undefined;
+export declare function resolveRequiredHomeDir(env?: NodeJS.ProcessEnv, homedir?: () => string): string;
+export declare function expandHomePrefix(input: string, opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+}): string;

package/dist/plugin-sdk/infra/http-body.d.ts

@@ -0,0 +1,46 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const DEFAULT_WEBHOOK_MAX_BODY_BYTES: number;
+export declare const DEFAULT_WEBHOOK_BODY_TIMEOUT_MS = 30000;
+export type RequestBodyLimitErrorCode = "PAYLOAD_TOO_LARGE" | "REQUEST_BODY_TIMEOUT" | "CONNECTION_CLOSED";
+type RequestBodyLimitErrorInit = {
+    code: RequestBodyLimitErrorCode;
+    message?: string;
+};
+export declare class RequestBodyLimitError extends Error {
+    readonly code: RequestBodyLimitErrorCode;
+    readonly statusCode: number;
+    constructor(init: RequestBodyLimitErrorInit);
+}
+export declare function isRequestBodyLimitError(error: unknown, code?: RequestBodyLimitErrorCode): error is RequestBodyLimitError;
+export declare function requestBodyErrorToText(code: RequestBodyLimitErrorCode): string;
+export type ReadRequestBodyOptions = {
+    maxBytes: number;
+    timeoutMs?: number;
+    encoding?: BufferEncoding;
+};
+export declare function readRequestBodyWithLimit(req: IncomingMessage, options: ReadRequestBodyOptions): Promise<string>;
+export type ReadJsonBodyResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+    code: RequestBodyLimitErrorCode | "INVALID_JSON";
+};
+export type ReadJsonBodyOptions = ReadRequestBodyOptions & {
+    emptyObjectOnEmpty?: boolean;
+};
+export declare function readJsonBodyWithLimit(req: IncomingMessage, options: ReadJsonBodyOptions): Promise<ReadJsonBodyResult>;
+export type RequestBodyLimitGuard = {
+    dispose: () => void;
+    isTripped: () => boolean;
+    code: () => RequestBodyLimitErrorCode | null;
+};
+export type RequestBodyLimitGuardOptions = {
+    maxBytes: number;
+    timeoutMs?: number;
+    responseFormat?: "json" | "text";
+    responseText?: Partial<Record<RequestBodyLimitErrorCode, string>>;
+};
+export declare function installRequestBodyLimitGuard(req: IncomingMessage, res: ServerResponse, options: RequestBodyLimitGuardOptions): RequestBodyLimitGuard;
+export {};

package/dist/plugin-sdk/infra/json-file.d.ts

@@ -0,0 +1,2 @@
+export declare function loadJsonFile(pathname: string): unknown;
+export declare function saveJsonFile(pathname: string, data: unknown): void;

package/dist/plugin-sdk/infra/net/fetch-guard.d.ts

@@ -0,0 +1,21 @@
+import { type LookupFn, type SsrFPolicy } from "./ssrf.js";
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type GuardedFetchOptions = {
+    url: string;
+    fetchImpl?: FetchLike;
+    init?: RequestInit;
+    maxRedirects?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    policy?: SsrFPolicy;
+    lookupFn?: LookupFn;
+    pinDns?: boolean;
+    auditContext?: string;
+};
+export type GuardedFetchResult = {
+    response: Response;
+    finalUrl: string;
+    release: () => Promise<void>;
+};
+export declare function fetchWithSsrFGuard(params: GuardedFetchOptions): Promise<GuardedFetchResult>;
+export {};

package/dist/plugin-sdk/infra/net/ssrf.d.ts

@@ -0,0 +1,32 @@
+import { lookup as dnsLookupCb } from "node:dns";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { type Dispatcher } from "undici";
+export declare class SsrFBlockedError extends Error {
+    constructor(message: string);
+}
+export type LookupFn = typeof dnsLookup;
+export type SsrFPolicy = {
+    allowPrivateNetwork?: boolean;
+    allowedHostnames?: string[];
+    hostnameAllowlist?: string[];
+};
+export declare function isPrivateIpAddress(address: string): boolean;
+export declare function isBlockedHostname(hostname: string): boolean;
+export declare function createPinnedLookup(params: {
+    hostname: string;
+    addresses: string[];
+    fallback?: typeof dnsLookupCb;
+}): typeof dnsLookupCb;
+export type PinnedHostname = {
+    hostname: string;
+    addresses: string[];
+    lookup: typeof dnsLookupCb;
+};
+export declare function resolvePinnedHostnameWithPolicy(hostname: string, params?: {
+    lookupFn?: LookupFn;
+    policy?: SsrFPolicy;
+}): Promise<PinnedHostname>;
+export declare function resolvePinnedHostname(hostname: string, lookupFn?: LookupFn): Promise<PinnedHostname>;
+export declare function createPinnedDispatcher(pinned: PinnedHostname): Dispatcher;
+export declare function closeDispatcher(dispatcher?: Dispatcher | null): Promise<void>;
+export declare function assertPublicHostname(hostname: string, lookupFn?: LookupFn): Promise<void>;

package/dist/plugin-sdk/infra/node-pairing.d.ts

@@ -0,0 +1,62 @@
+export type NodePairingPendingRequest = {
+    requestId: string;
+    nodeId: string;
+    displayName?: string;
+    platform?: string;
+    version?: string;
+    coreVersion?: string;
+    uiVersion?: string;
+    deviceFamily?: string;
+    modelIdentifier?: string;
+    caps?: string[];
+    commands?: string[];
+    permissions?: Record<string, boolean>;
+    remoteIp?: string;
+    silent?: boolean;
+    isRepair?: boolean;
+    ts: number;
+};
+export type NodePairingPairedNode = {
+    nodeId: string;
+    token: string;
+    displayName?: string;
+    platform?: string;
+    version?: string;
+    coreVersion?: string;
+    uiVersion?: string;
+    deviceFamily?: string;
+    modelIdentifier?: string;
+    caps?: string[];
+    commands?: string[];
+    bins?: string[];
+    permissions?: Record<string, boolean>;
+    remoteIp?: string;
+    createdAtMs: number;
+    approvedAtMs: number;
+    lastConnectedAtMs?: number;
+};
+export type NodePairingList = {
+    pending: NodePairingPendingRequest[];
+    paired: NodePairingPairedNode[];
+};
+export declare function listNodePairing(baseDir?: string): Promise<NodePairingList>;
+export declare function getPairedNode(nodeId: string, baseDir?: string): Promise<NodePairingPairedNode | null>;
+export declare function requestNodePairing(req: Omit<NodePairingPendingRequest, "requestId" | "ts" | "isRepair">, baseDir?: string): Promise<{
+    status: "pending";
+    request: NodePairingPendingRequest;
+    created: boolean;
+}>;
+export declare function approveNodePairing(requestId: string, baseDir?: string): Promise<{
+    requestId: string;
+    node: NodePairingPairedNode;
+} | null>;
+export declare function rejectNodePairing(requestId: string, baseDir?: string): Promise<{
+    requestId: string;
+    nodeId: string;
+} | null>;
+export declare function verifyNodeToken(nodeId: string, token: string, baseDir?: string): Promise<{
+    ok: boolean;
+    node?: NodePairingPairedNode;
+}>;
+export declare function updatePairedNodeMetadata(nodeId: string, patch: Partial<Omit<NodePairingPairedNode, "nodeId" | "token" | "createdAtMs" | "approvedAtMs">>, baseDir?: string): Promise<void>;
+export declare function renamePairedNode(nodeId: string, displayName: string, baseDir?: string): Promise<NodePairingPairedNode | null>;

package/dist/plugin-sdk/infra/node-shell.d.ts

@@ -0,0 +1 @@
+export declare function buildNodeShellCommand(command: string, platform?: string | null): string[];

package/dist/plugin-sdk/infra/openclaw-root.d.ts

@@ -0,0 +1,10 @@
+export declare function resolveAnimaPackageRoot(opts: {
+    cwd?: string;
+    argv1?: string;
+    moduleUrl?: string;
+}): Promise<string | null>;
+export declare function resolveAnimaPackageRootSync(opts: {
+    cwd?: string;
+    argv1?: string;
+    moduleUrl?: string;
+}): string | null;

package/dist/plugin-sdk/infra/outbound/abort.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility for checking AbortSignal state and throwing a standard AbortError.
+ */
+/**
+ * Throws an AbortError if the given signal has been aborted.
+ * Use at async checkpoints to support cancellation.
+ */
+export declare function throwIfAborted(abortSignal?: AbortSignal): void;

package/dist/plugin-sdk/infra/outbound/channel-adapters.d.ts

@@ -0,0 +1,6 @@
+import type { ChannelId } from "../../channels/plugins/types.js";
+export type ChannelMessageAdapter = {
+    supportsEmbeds: boolean;
+    buildCrossContextEmbeds?: (originLabel: string) => unknown[];
+};
+export declare function getChannelMessageAdapter(channel: ChannelId): ChannelMessageAdapter;

package/dist/plugin-sdk/infra/outbound/channel-selection.d.ts

@@ -0,0 +1,11 @@
+import type { AnimaConfig } from "../../config/config.js";
+import { type DeliverableMessageChannel } from "../../utils/message-channel.js";
+export type MessageChannelId = DeliverableMessageChannel;
+export declare function listConfiguredMessageChannels(cfg: AnimaConfig): Promise<MessageChannelId[]>;
+export declare function resolveMessageChannelSelection(params: {
+    cfg: AnimaConfig;
+    channel?: string | null;
+}): Promise<{
+    channel: MessageChannelId;
+    configured: MessageChannelId[];
+}>;

package/dist/plugin-sdk/infra/outbound/channel-target.d.ts

@@ -0,0 +1,6 @@
+export declare const CHANNEL_TARGET_DESCRIPTION = "Recipient/channel: E.164 for WhatsApp/Signal, Telegram chat id/@username, Discord/Slack channel/user, or iMessage handle/chat_id";
+export declare const CHANNEL_TARGETS_DESCRIPTION = "Recipient/channel targets (same format as --target); accepts ids or names when the directory is available.";
+export declare function applyTargetToParams(params: {
+    action: string;
+    args: Record<string, unknown>;
+}): void;

package/dist/plugin-sdk/infra/outbound/deliver.d.ts

@@ -0,0 +1,77 @@
+import type { ReplyPayload } from "../../auto-reply/types.js";
+import type { AnimaConfig } from "../../config/config.js";
+import type { sendMessageDiscord } from "../../discord/send.js";
+import type { sendMessageIMessage } from "../../imessage/send.js";
+import type { sendMessageSlack } from "../../slack/send.js";
+import type { sendMessageTelegram } from "../../telegram/send.js";
+import type { sendMessageWhatsApp } from "../../web/outbound.js";
+import type { OutboundIdentity } from "./identity.js";
+import type { NormalizedOutboundPayload } from "./payloads.js";
+import type { OutboundChannel } from "./targets.js";
+import { sendMessageSignal } from "../../signal/send.js";
+export type { NormalizedOutboundPayload } from "./payloads.js";
+export { normalizeOutboundPayloads } from "./payloads.js";
+type SendMatrixMessage = (to: string, text: string, opts?: {
+    mediaUrl?: string;
+    replyToId?: string;
+    threadId?: string;
+    timeoutMs?: number;
+}) => Promise<{
+    messageId: string;
+    roomId: string;
+}>;
+export type OutboundSendDeps = {
+    sendWhatsApp?: typeof sendMessageWhatsApp;
+    sendTelegram?: typeof sendMessageTelegram;
+    sendDiscord?: typeof sendMessageDiscord;
+    sendSlack?: typeof sendMessageSlack;
+    sendSignal?: typeof sendMessageSignal;
+    sendIMessage?: typeof sendMessageIMessage;
+    sendMatrix?: SendMatrixMessage;
+    sendMSTeams?: (to: string, text: string, opts?: {
+        mediaUrl?: string;
+    }) => Promise<{
+        messageId: string;
+        conversationId: string;
+    }>;
+};
+export type OutboundDeliveryResult = {
+    channel: Exclude<OutboundChannel, "none">;
+    messageId: string;
+    chatId?: string;
+    channelId?: string;
+    roomId?: string;
+    conversationId?: string;
+    timestamp?: number;
+    toJid?: string;
+    pollId?: string;
+    meta?: Record<string, unknown>;
+};
+type DeliverOutboundPayloadsCoreParams = {
+    cfg: AnimaConfig;
+    channel: Exclude<OutboundChannel, "none">;
+    to: string;
+    accountId?: string;
+    payloads: ReplyPayload[];
+    replyToId?: string | null;
+    threadId?: string | number | null;
+    identity?: OutboundIdentity;
+    deps?: OutboundSendDeps;
+    gifPlayback?: boolean;
+    abortSignal?: AbortSignal;
+    bestEffort?: boolean;
+    onError?: (err: unknown, payload: NormalizedOutboundPayload) => void;
+    onPayload?: (payload: NormalizedOutboundPayload) => void;
+    mirror?: {
+        sessionKey: string;
+        agentId?: string;
+        text?: string;
+        mediaUrls?: string[];
+    };
+    silent?: boolean;
+};
+type DeliverOutboundPayloadsParams = DeliverOutboundPayloadsCoreParams & {
+    /** @internal Skip write-ahead queue (used by crash-recovery to avoid re-enqueueing). */
+    skipQueue?: boolean;
+};
+export declare function deliverOutboundPayloads(params: DeliverOutboundPayloadsParams): Promise<OutboundDeliveryResult[]>;

package/dist/plugin-sdk/infra/outbound/delivery-queue.d.ts

@@ -0,0 +1,103 @@
+import type { ReplyPayload } from "../../auto-reply/types.js";
+import type { AnimaConfig } from "../../config/config.js";
+import type { OutboundChannel } from "./targets.js";
+declare const MAX_RETRIES = 5;
+export interface QueuedDelivery {
+    id: string;
+    enqueuedAt: number;
+    channel: Exclude<OutboundChannel, "none">;
+    to: string;
+    accountId?: string;
+    /**
+     * Original payloads before plugin hooks. On recovery, hooks re-run on these
+     * payloads — this is intentional since hooks are stateless transforms and
+     * should produce the same result on replay.
+     */
+    payloads: ReplyPayload[];
+    threadId?: string | number | null;
+    replyToId?: string | null;
+    bestEffort?: boolean;
+    gifPlayback?: boolean;
+    silent?: boolean;
+    mirror?: {
+        sessionKey: string;
+        agentId?: string;
+        text?: string;
+        mediaUrls?: string[];
+    };
+    retryCount: number;
+    lastError?: string;
+}
+/** Ensure the queue directory (and failed/ subdirectory) exist. */
+export declare function ensureQueueDir(stateDir?: string): Promise<string>;
+/** Persist a delivery entry to disk before attempting send. Returns the entry ID. */
+export declare function enqueueDelivery(params: {
+    channel: Exclude<OutboundChannel, "none">;
+    to: string;
+    accountId?: string;
+    payloads: ReplyPayload[];
+    threadId?: string | number | null;
+    replyToId?: string | null;
+    bestEffort?: boolean;
+    gifPlayback?: boolean;
+    silent?: boolean;
+    mirror?: {
+        sessionKey: string;
+        agentId?: string;
+        text?: string;
+        mediaUrls?: string[];
+    };
+}, stateDir?: string): Promise<string>;
+/** Remove a successfully delivered entry from the queue. */
+export declare function ackDelivery(id: string, stateDir?: string): Promise<void>;
+/** Update a queue entry after a failed delivery attempt. */
+export declare function failDelivery(id: string, error: string, stateDir?: string): Promise<void>;
+/** Load all pending delivery entries from the queue directory. */
+export declare function loadPendingDeliveries(stateDir?: string): Promise<QueuedDelivery[]>;
+/** Move a queue entry to the failed/ subdirectory. */
+export declare function moveToFailed(id: string, stateDir?: string): Promise<void>;
+/** Compute the backoff delay in ms for a given retry count. */
+export declare function computeBackoffMs(retryCount: number): number;
+export type DeliverFn = (params: {
+    cfg: AnimaConfig;
+    channel: Exclude<OutboundChannel, "none">;
+    to: string;
+    accountId?: string;
+    payloads: ReplyPayload[];
+    threadId?: string | number | null;
+    replyToId?: string | null;
+    bestEffort?: boolean;
+    gifPlayback?: boolean;
+    silent?: boolean;
+    mirror?: {
+        sessionKey: string;
+        agentId?: string;
+        text?: string;
+        mediaUrls?: string[];
+    };
+    skipQueue?: boolean;
+}) => Promise<unknown>;
+export interface RecoveryLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/**
+ * On gateway startup, scan the delivery queue and retry any pending entries.
+ * Uses exponential backoff and moves entries that exceed MAX_RETRIES to failed/.
+ */
+export declare function recoverPendingDeliveries(opts: {
+    deliver: DeliverFn;
+    log: RecoveryLogger;
+    cfg: AnimaConfig;
+    stateDir?: string;
+    /** Override for testing — resolves instead of using real setTimeout. */
+    delay?: (ms: number) => Promise<void>;
+    /** Maximum wall-clock time for recovery in ms. Remaining entries are deferred to next restart. Default: 60 000. */
+    maxRecoveryMs?: number;
+}): Promise<{
+    recovered: number;
+    failed: number;
+    skipped: number;
+}>;
+export { MAX_RETRIES };