@elizaos/agent 2.0.0-beta.2 → 2.0.3-beta.2

package/services/proactive-interaction-decider.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Proactive-interaction decider (#8792).
+ *
+ * Consumes UI interaction events (view switches today; slash/shortcut wireable
+ * the same way) and decides whether to surface a single scoped, helpful comment
+ * through the existing `routeAutonomyTextToUser` → `proactive-message` pipeline
+ * with `source: "proactive-interaction"`.
+ *
+ * Two layers, both testable in isolation:
+ *  - {@link decideProactiveComment} — the pure policy + governance decision
+ *    (injected judge / gate / clock), no runtime, no model, no network.
+ *  - {@link registerProactiveInteractionDecider} — the thin runtime wiring that
+ *    subscribes to the event bus, runs the small-model judge, and routes the
+ *    admitted comment.
+ */
+import { type IAgentRuntime, type ViewSwitchedPayload } from "@elizaos/core";
+import { type ProactiveInteractionGate } from "./proactive-interaction-gate.ts";
+/** Source tag for proactive comments driven by UI interactions. */
+export declare const PROACTIVE_INTERACTION_SOURCE = "proactive-interaction";
+/** A model judge: given a view-switch context, return an offer or null. */
+export type ProactiveJudge = (payload: ViewSwitchedPayload) => Promise<string | null>;
+export interface DecideProactiveInput {
+    payload: ViewSwitchedPayload;
+    gate: ProactiveInteractionGate;
+    judge: ProactiveJudge;
+    now: number;
+}
+export interface DecideProactiveResult {
+    /** The comment to surface, or null when none should be sent. */
+    text: string | null;
+    reason: string;
+}
+/**
+ * Decide whether to comment on a view switch. Policy + governance only:
+ *  - Skip AGENT-initiated switches — the agent already acknowledged the move
+ *    (#8788), so a second proactive comment would be double-talk.
+ *  - Require the caller-recorded switch to have settled, then ask the judge for
+ *    a scoped offer.
+ *  - A null/empty judge result means "nothing helpful to say" → silence.
+ *  - The governance gate (cooldowns / cap / dedup / debounce) makes the final
+ *    call and records the emission.
+ */
+export declare function decideProactiveComment(input: DecideProactiveInput): Promise<DecideProactiveResult>;
+/** Build the small-model judge prompt for a view switch. */
+export declare function buildProactiveJudgePrompt(payload: ViewSwitchedPayload): string;
+/** Parse the judge model output into an offer string or null. */
+export declare function parseProactiveJudgeOutput(raw: unknown): string | null;
+export interface ProactiveDeciderWiring {
+    /** Route an admitted comment to the user (proactive-message pipeline). */
+    route: (text: string) => Promise<void>;
+    gate: ProactiveInteractionGate;
+    /** Override the clock (tests). */
+    now?: () => number;
+}
+/**
+ * Subscribe the decider to the runtime event bus. Each VIEW_SWITCHED runs the
+ * small-model judge and, if the governance gate admits, routes the comment.
+ * Fire-and-forget; failures degrade silently (a missed proactive comment must
+ * never break the interaction).
+ */
+export declare function registerProactiveInteractionDecider(runtime: IAgentRuntime, wiring: ProactiveDeciderWiring): void;
+//# sourceMappingURL=proactive-interaction-decider.d.ts.map

package/services/proactive-interaction-decider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proactive-interaction-decider.d.ts","sourceRoot":"","sources":["../../src/services/proactive-interaction-decider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAEL,KAAK,aAAa,EAGlB,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,iCAAiC,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,mBAAmB,KACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5B,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,KAAK,EAAE,cAAc,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AASD,4DAA4D;AAC5D,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,MAAM,CAGR;AAED,iEAAiE;AACjE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAqBrE;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,sBAAsB,GAC7B,IAAI,CAoDN"}

package/services/proactive-interaction-decider.js

@@ -0,0 +1,145 @@
+/**
+ * Proactive-interaction decider (#8792).
+ *
+ * Consumes UI interaction events (view switches today; slash/shortcut wireable
+ * the same way) and decides whether to surface a single scoped, helpful comment
+ * through the existing `routeAutonomyTextToUser` → `proactive-message` pipeline
+ * with `source: "proactive-interaction"`.
+ *
+ * Two layers, both testable in isolation:
+ *  - {@link decideProactiveComment} — the pure policy + governance decision
+ *    (injected judge / gate / clock), no runtime, no model, no network.
+ *  - {@link registerProactiveInteractionDecider} — the thin runtime wiring that
+ *    subscribes to the event bus, runs the small-model judge, and routes the
+ *    admitted comment.
+ */
+import { EventType, logger, ModelType, } from "@elizaos/core";
+import { resolveProactiveGateConfig, } from "./proactive-interaction-gate.js";
+/** Source tag for proactive comments driven by UI interactions. */
+export const PROACTIVE_INTERACTION_SOURCE = "proactive-interaction";
+/**
+ * Decide whether to comment on a view switch. Policy + governance only:
+ *  - Skip AGENT-initiated switches — the agent already acknowledged the move
+ *    (#8788), so a second proactive comment would be double-talk.
+ *  - Require the caller-recorded switch to have settled, then ask the judge for
+ *    a scoped offer.
+ *  - A null/empty judge result means "nothing helpful to say" → silence.
+ *  - The governance gate (cooldowns / cap / dedup / debounce) makes the final
+ *    call and records the emission.
+ */
+export async function decideProactiveComment(input) {
+    const { payload, gate, judge, now } = input;
+    const surface = payload.viewId;
+    if (!surface)
+        return { text: null, reason: "no surface" };
+    if (payload.initiatedBy === "agent") {
+        return { text: null, reason: "agent-initiated (already acknowledged)" };
+    }
+    if (!gate.isSettled(surface, now)) {
+        return { text: null, reason: "debounce: surface not settled" };
+    }
+    const candidate = (await judge(payload))?.trim();
+    if (!candidate) {
+        return { text: null, reason: "judge: nothing helpful to offer" };
+    }
+    const admit = gate.tryAdmit({ surface, text: candidate, now });
+    if (!admit.admitted) {
+        return { text: null, reason: admit.reason };
+    }
+    return { text: candidate, reason: "admitted" };
+}
+const JUDGE_INSTRUCTION = [
+    "The user just switched to an app view. Decide if there is ONE specific, helpful thing you can proactively offer about that view right now.",
+    'Examples: switched to wallet → "Want me to pull your latest balances?"; opened task-coordinator → "Want me to summarize your open tasks?".',
+    "Stay silent (return none) for ambiguous or low-value switches, settings/config screens, or anything where a comment would be noise.",
+    'Respond as JSON: {"comment": <a short offer, or null>}.',
+].join("\n");
+/** Build the small-model judge prompt for a view switch. */
+export function buildProactiveJudgePrompt(payload) {
+    const where = payload.viewLabel ?? payload.viewId;
+    return `${JUDGE_INSTRUCTION}\nThe user just opened the ${where} view.`;
+}
+/** Parse the judge model output into an offer string or null. */
+export function parseProactiveJudgeOutput(raw) {
+    let obj = raw;
+    if (typeof raw === "string") {
+        const trimmed = raw
+            .trim()
+            .replace(/^```(?:json)?\s*/i, "")
+            .replace(/\s*```$/i, "");
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!obj || typeof obj !== "object")
+        return null;
+    const comment = obj.comment;
+    if (typeof comment !== "string")
+        return null;
+    const trimmed = comment.trim();
+    if (!trimmed || trimmed.toLowerCase() === "none" || trimmed === "null") {
+        return null;
+    }
+    return trimmed;
+}
+/**
+ * Subscribe the decider to the runtime event bus. Each VIEW_SWITCHED runs the
+ * small-model judge and, if the governance gate admits, routes the comment.
+ * Fire-and-forget; failures degrade silently (a missed proactive comment must
+ * never break the interaction).
+ */
+export function registerProactiveInteractionDecider(runtime, wiring) {
+    const clock = wiring.now ?? Date.now;
+    const config = resolveProactiveGateConfig();
+    wiring.gate.setConfig(config);
+    if (config.chattiness === "off") {
+        logger.debug("[proactive-interaction] disabled by config; not subscribing");
+        return;
+    }
+    const judge = async (payload) => {
+        try {
+            const raw = await runtime.useModel(ModelType.TEXT_SMALL, {
+                prompt: buildProactiveJudgePrompt(payload),
+            });
+            return parseProactiveJudgeOutput(raw);
+        }
+        catch (err) {
+            logger.debug({ err }, "[proactive-interaction] judge failed");
+            return null;
+        }
+    };
+    runtime.registerEvent(EventType.VIEW_SWITCHED, async (payload) => {
+        const viewPayload = payload;
+        const surface = viewPayload.viewId;
+        if (!surface)
+            return;
+        wiring.gate.noteSwitch(surface, clock());
+        const run = async () => {
+            try {
+                const decision = await decideProactiveComment({
+                    payload: viewPayload,
+                    gate: wiring.gate,
+                    judge,
+                    now: clock(),
+                });
+                if (decision.text) {
+                    await wiring.route(decision.text);
+                }
+            }
+            catch (err) {
+                logger.debug({ err }, "[proactive-interaction] decider failed");
+            }
+        };
+        if (config.debounceMs > 0) {
+            setTimeout(() => {
+                void run();
+            }, config.debounceMs);
+        }
+        else {
+            void run();
+        }
+    });
+}

package/services/proactive-interaction-gate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Proactive-interaction UX governance gate (#8792).
+ *
+ * The "not annoying" core: turns a stream of UI interactions (view switches,
+ * slash commands, shortcuts) into AT MOST a trickle of proactive comments. Pure
+ * and deterministic — `now` is injected, all state is in-memory — so every rule
+ * (kill-switch, global cooldown, per-surface cooldown, daily cap, textual dedup,
+ * burst debounce) is unit-testable without a runtime or a clock.
+ *
+ * It does NOT decide WHAT to say (that's the model judge) — only WHETHER a
+ * comment is allowed right now. The decider calls {@link tryAdmit} after the
+ * model produced a candidate comment; an admitted call also records the emission
+ * so subsequent calls respect the caps.
+ */
+/** How talkative proactive interaction-comments are. */
+export type ProactiveChattiness = "off" | "subtle" | "chatty";
+export interface ProactiveGateConfig {
+    /** Master verbosity. `off` disables all proactive interaction comments. */
+    chattiness: ProactiveChattiness;
+    /** Minimum gap between ANY two proactive comments. */
+    globalCooldownMs: number;
+    /** Minimum gap before re-commenting on the SAME surface. */
+    perSurfaceCooldownMs: number;
+    /** Hard cap on proactive comments in a rolling 24h window. */
+    dailyCap: number;
+    /** Suppress a comment textually identical to a recent one within this window. */
+    dedupWindowMs: number;
+    /** A surface must be "settled" (no newer switch) this long before commenting. */
+    debounceMs: number;
+}
+/** Tuning per chattiness level. `subtle` is the recommended default for new users. */
+export declare function configForChattiness(chattiness: ProactiveChattiness): ProactiveGateConfig;
+export declare const DEFAULT_PROACTIVE_GATE_CONFIG: ProactiveGateConfig;
+/** Read the kill-switch + chattiness setting from env / user setting. */
+export declare function resolveProactiveChattiness(env?: Record<string, string | undefined>, userSetting?: string | null): ProactiveChattiness;
+export declare function resolveProactiveGateConfig(env?: Record<string, string | undefined>, userSetting?: string | null): ProactiveGateConfig;
+export interface AdmitInput {
+    /** Surface key the comment is about (e.g. a view id). */
+    surface: string;
+    /** The candidate comment text (for dedup). */
+    text: string;
+    now: number;
+}
+export interface AdmitResult {
+    admitted: boolean;
+    reason: string;
+}
+/** In-memory, per-process governance state. */
+export declare class ProactiveInteractionGate {
+    private config;
+    private emissions;
+    /** Latest switch time per surface, for the debounce/settle check. */
+    private lastSwitchAt;
+    /** Most recent switch globally; older surfaces are no longer the settled one. */
+    private latestSwitch;
+    constructor(config?: ProactiveGateConfig);
+    setConfig(config: ProactiveGateConfig): void;
+    /** Record that a surface switch happened (resets its settle timer). */
+    noteSwitch(surface: string, now: number): void;
+    /** True once `debounceMs` has elapsed since the last switch to `surface`. */
+    isSettled(surface: string, now: number): boolean;
+    private pruneOlderThan;
+    /**
+     * Check every gate and, when all pass, record the emission. Returns the first
+     * failing reason so callers can log why a comment was suppressed.
+     */
+    tryAdmit(input: AdmitInput): AdmitResult;
+    reset(): void;
+}
+//# sourceMappingURL=proactive-interaction-gate.d.ts.map

package/services/proactive-interaction-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proactive-interaction-gate.d.ts","sourceRoot":"","sources":["../../src/services/proactive-interaction-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,UAAU,EAAE,mBAAmB,CAAC;IAChC,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,sFAAsF;AACtF,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,mBAAmB,GAC9B,mBAAmB,CA8BrB;AAED,eAAO,MAAM,6BAA6B,EAAE,mBACb,CAAC;AAEhC,yEAAyE;AACzE,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,mBAAmB,CAarB;AAED,wBAAgB,0BAA0B,CACxC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,mBAAmB,CAErB;AAED,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,+CAA+C;AAC/C,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAwB;IACzC,qEAAqE;IACrE,OAAO,CAAC,YAAY,CAA6B;IACjD,iFAAiF;IACjF,OAAO,CAAC,YAAY,CAA6B;gBAErC,MAAM,GAAE,mBAAmD;IAIvE,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAI5C,uEAAuE;IACvE,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9C,6EAA6E;IAC7E,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAShD,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW;IA8CxC,KAAK,IAAI,IAAI;CAKd"}

package/services/proactive-interaction-gate.js

@@ -0,0 +1,148 @@
+/**
+ * Proactive-interaction UX governance gate (#8792).
+ *
+ * The "not annoying" core: turns a stream of UI interactions (view switches,
+ * slash commands, shortcuts) into AT MOST a trickle of proactive comments. Pure
+ * and deterministic — `now` is injected, all state is in-memory — so every rule
+ * (kill-switch, global cooldown, per-surface cooldown, daily cap, textual dedup,
+ * burst debounce) is unit-testable without a runtime or a clock.
+ *
+ * It does NOT decide WHAT to say (that's the model judge) — only WHETHER a
+ * comment is allowed right now. The decider calls {@link tryAdmit} after the
+ * model produced a candidate comment; an admitted call also records the emission
+ * so subsequent calls respect the caps.
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Tuning per chattiness level. `subtle` is the recommended default for new users. */
+export function configForChattiness(chattiness) {
+    switch (chattiness) {
+        case "off":
+            return {
+                chattiness,
+                globalCooldownMs: Number.POSITIVE_INFINITY,
+                perSurfaceCooldownMs: Number.POSITIVE_INFINITY,
+                dailyCap: 0,
+                dedupWindowMs: DAY_MS,
+                debounceMs: 1_500,
+            };
+        case "chatty":
+            return {
+                chattiness,
+                globalCooldownMs: 60_000,
+                perSurfaceCooldownMs: 3 * 60_000,
+                dailyCap: 40,
+                dedupWindowMs: 15 * 60_000,
+                debounceMs: 1_000,
+            };
+        default:
+            return {
+                chattiness: "subtle",
+                globalCooldownMs: 2 * 60_000,
+                perSurfaceCooldownMs: 10 * 60_000,
+                dailyCap: 12,
+                dedupWindowMs: 30 * 60_000,
+                debounceMs: 1_500,
+            };
+    }
+}
+export const DEFAULT_PROACTIVE_GATE_CONFIG = configForChattiness("subtle");
+/** Read the kill-switch + chattiness setting from env / user setting. */
+export function resolveProactiveChattiness(env = process.env, userSetting) {
+    // Hard kill-switch mirrors the LifeOps proactive worker's env flag.
+    const disabled = env.ELIZA_DISABLE_PROACTIVE_AGENT;
+    if (disabled === "1" || disabled === "true" || disabled === "yes") {
+        return "off";
+    }
+    const raw = (userSetting ??
+        env.ELIZA_PROACTIVE_INTERACTIONS ??
+        "").toLowerCase();
+    if (raw === "off" || raw === "subtle" || raw === "chatty")
+        return raw;
+    return "subtle";
+}
+export function resolveProactiveGateConfig(env = process.env, userSetting) {
+    return configForChattiness(resolveProactiveChattiness(env, userSetting));
+}
+/** In-memory, per-process governance state. */
+export class ProactiveInteractionGate {
+    config;
+    emissions = [];
+    /** Latest switch time per surface, for the debounce/settle check. */
+    lastSwitchAt = new Map();
+    /** Most recent switch globally; older surfaces are no longer the settled one. */
+    latestSwitch = null;
+    constructor(config = DEFAULT_PROACTIVE_GATE_CONFIG) {
+        this.config = config;
+    }
+    setConfig(config) {
+        this.config = config;
+    }
+    /** Record that a surface switch happened (resets its settle timer). */
+    noteSwitch(surface, now) {
+        this.lastSwitchAt.set(surface, now);
+        this.latestSwitch = { surface, at: now };
+    }
+    /** True once `debounceMs` has elapsed since the last switch to `surface`. */
+    isSettled(surface, now) {
+        if (this.latestSwitch && this.latestSwitch.surface !== surface) {
+            return false;
+        }
+        const at = this.lastSwitchAt.get(surface);
+        if (at === undefined)
+            return true;
+        return now - at >= this.config.debounceMs;
+    }
+    pruneOlderThan(now) {
+        const cutoff = now - Math.max(DAY_MS, this.config.dedupWindowMs);
+        if (this.emissions.length === 0)
+            return;
+        this.emissions = this.emissions.filter((e) => e.at >= cutoff);
+    }
+    /**
+     * Check every gate and, when all pass, record the emission. Returns the first
+     * failing reason so callers can log why a comment was suppressed.
+     */
+    tryAdmit(input) {
+        const { surface, text, now } = input;
+        this.pruneOlderThan(now);
+        if (this.config.chattiness === "off" || this.config.dailyCap <= 0) {
+            return { admitted: false, reason: "disabled" };
+        }
+        if (!this.isSettled(surface, now)) {
+            return { admitted: false, reason: "debounce: surface not settled" };
+        }
+        // Daily cap.
+        const inDay = this.emissions.filter((e) => now - e.at < DAY_MS).length;
+        if (inDay >= this.config.dailyCap) {
+            return { admitted: false, reason: "daily cap reached" };
+        }
+        // Global cooldown.
+        const last = this.emissions.at(-1);
+        if (last && now - last.at < this.config.globalCooldownMs) {
+            return { admitted: false, reason: "global cooldown" };
+        }
+        // Per-surface cooldown.
+        const lastForSurface = [...this.emissions]
+            .reverse()
+            .find((e) => e.surface === surface);
+        if (lastForSurface &&
+            now - lastForSurface.at < this.config.perSurfaceCooldownMs) {
+            return { admitted: false, reason: "per-surface cooldown" };
+        }
+        // Textual dedup (same surface + same text within the window).
+        const normalized = text.trim().toLowerCase();
+        const dup = this.emissions.find((e) => e.surface === surface &&
+            e.text.trim().toLowerCase() === normalized &&
+            now - e.at < this.config.dedupWindowMs);
+        if (dup) {
+            return { admitted: false, reason: "duplicate of a recent comment" };
+        }
+        this.emissions.push({ surface, text, at: now });
+        return { admitted: true, reason: "ok" };
+    }
+    reset() {
+        this.emissions = [];
+        this.lastSwitchAt.clear();
+        this.latestSwitch = null;
+    }
+}

package/services/push/apns-provider.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ApnsProvider — Apple Push Notification service (HTTP/2) sender.
+ *
+ * Auth is a JWT provider token (Apple's token-based auth): an ES256 JWT signed
+ * with the team's .p8 EC private key, header `{ alg:"ES256", kid: <keyId> }`,
+ * claims `{ iss: <teamId>, iat: <now> }`. The token is reused until it nears
+ * Apple's 1-hour cap, then re-minted.
+ *
+ * Delivery POSTs to `https://api.push.apple.com/3/device/<token>` (or the
+ * sandbox host) over HTTP/2 with headers `apns-topic`, `apns-push-type:"alert"`,
+ * and `authorization: bearer <jwt>`. The payload is the standard APNs alert
+ * shape `{ aps: { alert: { title, body }, sound:"default" }, ...customData }`.
+ *
+ * VERIFIABILITY: the JWT minting (`mintToken`) and request shaping are pure and
+ * unit-tested with a throwaway P-256 key. Actual delivery hits Apple's servers
+ * and is NOT exercised in tests — it requires a real APNs auth key, a real
+ * bundle id, and a real device token.
+ */
+import { type PushMessage, type PushProvider } from "./push-types.ts";
+interface ApnsConfig {
+    /** PEM/p8 EC private key contents. */
+    key: string;
+    /** APNs auth key id (the `kid` header). */
+    keyId: string;
+    /** Apple developer team id (the `iss` claim). */
+    teamId: string;
+    /** App bundle id (the `apns-topic` header). */
+    topic: string;
+    /** Whether to target the production host. */
+    production: boolean;
+}
+/**
+ * Read APNs config from the environment, or null if not fully configured.
+ * Exported for the gating check / tests.
+ */
+export declare function readApnsConfig(env?: NodeJS.ProcessEnv): ApnsConfig | null;
+export declare class ApnsProvider implements PushProvider {
+    readonly name = "apns";
+    private readonly config;
+    private privateKey;
+    private cachedToken;
+    constructor(env?: NodeJS.ProcessEnv);
+    isConfigured(): boolean;
+    private requireConfig;
+    private getPrivateKey;
+    /**
+     * Mint (or reuse) the ES256 provider token. Public + cache-bypassing so the
+     * unit test can assert header/claims deterministically.
+     */
+    mintToken(now?: number): string;
+    /** Build the JSON payload body for one message. */
+    buildPayload(message: PushMessage): string;
+    send(token: string, message: PushMessage): Promise<void>;
+    /** POST over HTTP/2 and resolve the status + APNs `reason` (if any). */
+    private postHttp2;
+}
+export {};
+//# sourceMappingURL=apns-provider.d.ts.map

package/services/push/apns-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns-provider.d.ts","sourceRoot":"","sources":["../../../src/services/push/apns-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AAOzB,UAAU,UAAU;IAClB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,UAAU,EAAE,OAAO,CAAC;CACrB;AAWD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,UAAU,GAAG,IAAI,CAqBnB;AAED,qBAAa,YAAa,YAAW,YAAY;IAC/C,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,WAAW,CAAkD;gBAEzD,GAAG,GAAE,MAAM,CAAC,UAAwB;IAIhD,YAAY,IAAI,OAAO;IAIvB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,aAAa;IAOrB;;;OAGG;IACH,SAAS,CAAC,GAAG,GAAE,MAAmB,GAAG,MAAM;IAqB3C,mDAAmD;IACnD,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM;IAUpC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B9D,wEAAwE;IACxE,OAAO,CAAC,SAAS;CA2ClB"}