@cursor/bdk 0.2.24 → 0.2.26

package/dist/channels/pagerduty/payload.js

@@ -0,0 +1,150 @@
+/**
+ * Typed views over a PagerDuty v3 webhook body. Every reader tolerates
+ * missing optional fields and returns `undefined` for a shape it does not
+ * recognize, so a new PagerDuty field never fails a delivery.
+ */
+export function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function asNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function asPositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+/** The delivery's `event` record, or `undefined` when the body is not a v3 event. */
+export function pagerDutyEventRecord(payload) {
+    const event = asRecord(asRecord(payload)?.event);
+    return asNonEmptyString(event?.event_type) === undefined ? undefined : event;
+}
+export function pagerDutyReference(value) {
+    const record = asRecord(value);
+    const id = asNonEmptyString(record?.id);
+    if (record === undefined || id === undefined) {
+        return undefined;
+    }
+    return {
+        id,
+        type: asNonEmptyString(record.type),
+        summary: asNonEmptyString(record.summary),
+        htmlUrl: asNonEmptyString(record.html_url),
+    };
+}
+function references(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((entry) => {
+        const reference = pagerDutyReference(entry);
+        return reference === undefined ? [] : [reference];
+    });
+}
+/** `data` of a lifecycle event: the full incident. */
+export function pagerDutyIncidentFromData(data) {
+    const record = asRecord(data);
+    const id = asNonEmptyString(record?.id);
+    if (record === undefined || id === undefined || record.type !== "incident") {
+        return undefined;
+    }
+    return {
+        id,
+        number: asPositiveInt(record.number),
+        title: asNonEmptyString(record.title),
+        status: asNonEmptyString(record.status),
+        urgency: asNonEmptyString(record.urgency),
+        incidentKey: asNonEmptyString(record.incident_key),
+        htmlUrl: asNonEmptyString(record.html_url),
+        createdAt: asNonEmptyString(record.created_at),
+        service: pagerDutyReference(record.service),
+        escalationPolicy: pagerDutyReference(record.escalation_policy),
+        priority: pagerDutyReference(record.priority),
+        assignees: references(record.assignees),
+        teams: references(record.teams),
+        resolveReason: asNonEmptyString(record.resolve_reason),
+    };
+}
+function incidentRef(value) {
+    const reference = pagerDutyReference(value);
+    if (reference === undefined) {
+        return undefined;
+    }
+    return { ...reference, incidentKey: asNonEmptyString(asRecord(value)?.incident_key) };
+}
+/** `data` of `incident.annotated`. */
+export function pagerDutyNoteFromData(data) {
+    const record = asRecord(data);
+    const incident = incidentRef(record?.incident);
+    if (record === undefined || incident === undefined || typeof record.content !== "string") {
+        return undefined;
+    }
+    return {
+        id: asNonEmptyString(record.id),
+        content: record.content,
+        trimmed: record.trimmed === true,
+        incident,
+    };
+}
+/** `data` of `incident.responder.added` / `.replied`. */
+export function pagerDutyResponderFromData(eventType, data) {
+    const record = asRecord(data);
+    const incident = incidentRef(record?.incident);
+    if (record === undefined || incident === undefined) {
+        return undefined;
+    }
+    return {
+        action: eventType === "incident.responder.replied" ? "replied" : "added",
+        incident,
+        user: pagerDutyReference(record.user),
+        escalationPolicy: pagerDutyReference(record.escalation_policy),
+        message: asNonEmptyString(record.message),
+        state: asNonEmptyString(record.state),
+    };
+}
+/**
+ * The incident any incident event names: `data` itself for lifecycle
+ * events, `data.incident` for sub-resources. Mirrors the continuation
+ * selector, so a hook's `ctx.incidentId` names the session's incident.
+ */
+export function pagerDutyEventIncident(event) {
+    const data = asRecord(event.data);
+    const record = asRecord(data?.incident) ??
+        (data?.type === "incident" || event.resource_type === "incident" ? data : undefined);
+    const id = asNonEmptyString(record?.id);
+    if (id === undefined) {
+        return undefined;
+    }
+    return { id, incidentKey: asNonEmptyString(record?.incident_key) };
+}
+const PAGERDUTY_HOST = /^([a-z0-9][a-z0-9-]*)\.(?:[a-z]{2}\.)?pagerduty\.com$/i;
+/**
+ * The account subdomain (`acme` for `acme.pagerduty.com` or
+ * `acme.eu.pagerduty.com`) from the first PagerDuty web URL the event
+ * carries: the incident's, the agent's, or the data's own.
+ */
+export function pagerDutyAccountSubdomain(event) {
+    const data = asRecord(event.data);
+    const candidates = [
+        asRecord(data?.incident)?.html_url,
+        data?.html_url,
+        asRecord(event.agent)?.html_url,
+        asRecord(data?.service)?.html_url,
+    ];
+    for (const candidate of candidates) {
+        const url = asNonEmptyString(candidate);
+        if (url === undefined) {
+            continue;
+        }
+        try {
+            const match = PAGERDUTY_HOST.exec(new URL(url).hostname);
+            if (match?.[1] !== undefined) {
+                return match[1].toLowerCase();
+            }
+        }
+        catch {
+            // Not a URL; try the next one.
+        }
+    }
+    return undefined;
+}

package/dist/channels/pagerduty/replay.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Synthesize PagerDuty v3 webhook bodies for `bdk pagerduty replay`, so a
+ * local `pagerdutyChannel()` can be exercised without a PagerDuty account
+ * or tunnel. The bodies follow PagerDuty's documented v3 shapes: lifecycle
+ * events carry the incident as `data`, notes carry it as `data.incident`.
+ */
+/** Event types `replay` can synthesize, in the order an incident usually sees them. */
+export declare const PAGERDUTY_REPLAYABLE_EVENTS: readonly ["incident.triggered", "incident.acknowledged", "incident.annotated", "incident.escalated", "incident.resolved", "incident.reopened"];
+export type PagerDutyReplayableEvent = (typeof PAGERDUTY_REPLAYABLE_EVENTS)[number];
+export declare const PAGERDUTY_REPLAY_DEFAULT_INCIDENT_ID = "PREPLAY1";
+/**
+ * Pick the events to replay. Accepts full names (`incident.resolved`) or
+ * the action alone (`resolved`); `*` selects every declared event that can
+ * be synthesized. Defaults to `incident.triggered`.
+ */
+export declare function selectPagerDutyReplayEvents(input: {
+    /** Event names from `--events`; omitted selects the default. */
+    requested: readonly string[] | undefined;
+    /** The event types the target channels declare. */
+    declared: readonly string[];
+}): {
+    events: PagerDutyReplayableEvent[];
+    unsupported: string[];
+};
+/**
+ * One v3 delivery body for `eventType` on `incidentId`. A trigger comes
+ * from PagerDuty itself (no `agent`); every other event is a person's
+ * action, so it dispatches rather than being skipped as the agent's echo.
+ */
+export declare function synthesizePagerDutyEvent(input: {
+    eventType: PagerDutyReplayableEvent;
+    incidentId?: string;
+    note?: string;
+}): Record<string, unknown>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/channels/pagerduty/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/replay.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,YACtC,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,CACX,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAWpF,eAAO,MAAM,oCAAoC,aAAa,CAAC;AAe/D;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,gEAAgE;IAChE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACzC,mDAAmD;IACnD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,GAAG;IAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAwBhE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,wBAAwB,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyC1B"}

package/dist/channels/pagerduty/replay.js

@@ -0,0 +1,115 @@
+/**
+ * Synthesize PagerDuty v3 webhook bodies for `bdk pagerduty replay`, so a
+ * local `pagerdutyChannel()` can be exercised without a PagerDuty account
+ * or tunnel. The bodies follow PagerDuty's documented v3 shapes: lifecycle
+ * events carry the incident as `data`, notes carry it as `data.incident`.
+ */
+import { randomUUID } from "node:crypto";
+/** Event types `replay` can synthesize, in the order an incident usually sees them. */
+export const PAGERDUTY_REPLAYABLE_EVENTS = [
+    "incident.triggered",
+    "incident.acknowledged",
+    "incident.annotated",
+    "incident.escalated",
+    "incident.resolved",
+    "incident.reopened",
+];
+const STATUS_BY_EVENT = {
+    "incident.triggered": "triggered",
+    "incident.acknowledged": "acknowledged",
+    "incident.annotated": "triggered",
+    "incident.escalated": "triggered",
+    "incident.resolved": "resolved",
+    "incident.reopened": "triggered",
+};
+export const PAGERDUTY_REPLAY_DEFAULT_INCIDENT_ID = "PREPLAY1";
+const SUBDOMAIN = "example";
+const SERVICE = {
+    id: "PSVCREP",
+    type: "service_reference",
+    summary: "replayed-service",
+    html_url: `https://${SUBDOMAIN}.pagerduty.com/service-directory/PSVCREP`,
+};
+const RESPONDER = {
+    id: "PUSERREP",
+    type: "user_reference",
+    summary: "Replay Responder",
+    html_url: `https://${SUBDOMAIN}.pagerduty.com/users/PUSERREP`,
+};
+/**
+ * Pick the events to replay. Accepts full names (`incident.resolved`) or
+ * the action alone (`resolved`); `*` selects every declared event that can
+ * be synthesized. Defaults to `incident.triggered`.
+ */
+export function selectPagerDutyReplayEvents(input) {
+    const { requested, declared } = input;
+    const replayable = new Set(PAGERDUTY_REPLAYABLE_EVENTS);
+    if (requested === undefined) {
+        return { events: ["incident.triggered"], unsupported: [] };
+    }
+    if (requested.length === 1 && requested[0] === "*") {
+        const pool = declared.length === 0 ? PAGERDUTY_REPLAYABLE_EVENTS : declared;
+        return {
+            events: PAGERDUTY_REPLAYABLE_EVENTS.filter((event) => pool.includes(event)),
+            unsupported: [],
+        };
+    }
+    const events = [];
+    const unsupported = [];
+    for (const raw of requested) {
+        const name = raw.startsWith("incident.") ? raw : `incident.${raw}`;
+        if (replayable.has(name)) {
+            events.push(name);
+        }
+        else {
+            unsupported.push(raw);
+        }
+    }
+    return { events, unsupported };
+}
+/**
+ * One v3 delivery body for `eventType` on `incidentId`. A trigger comes
+ * from PagerDuty itself (no `agent`); every other event is a person's
+ * action, so it dispatches rather than being skipped as the agent's echo.
+ */
+export function synthesizePagerDutyEvent(input) {
+    const incidentId = input.incidentId ?? PAGERDUTY_REPLAY_DEFAULT_INCIDENT_ID;
+    const incidentUrl = `https://${SUBDOMAIN}.pagerduty.com/incidents/${incidentId}`;
+    const data = input.eventType === "incident.annotated"
+        ? {
+            id: `PNOTE${randomUUID().slice(0, 6).toUpperCase()}`,
+            type: "incident_note",
+            content: input.note ?? "Replayed note from bdk pagerduty replay.",
+            trimmed: false,
+            incident: {
+                id: incidentId,
+                type: "incident_reference",
+                html_url: incidentUrl,
+            },
+        }
+        : {
+            id: incidentId,
+            type: "incident",
+            number: 1,
+            title: "Replayed incident from bdk pagerduty replay",
+            status: STATUS_BY_EVENT[input.eventType],
+            urgency: "high",
+            incident_key: `replay-${incidentId}`,
+            html_url: incidentUrl,
+            created_at: new Date().toISOString(),
+            service: SERVICE,
+            assignees: [RESPONDER],
+            teams: [],
+        };
+    return {
+        event: {
+            id: randomUUID(),
+            event_type: input.eventType,
+            resource_type: "incident",
+            occurred_at: new Date().toISOString(),
+            agent: input.eventType === "incident.triggered" ? null : RESPONDER,
+            client: { name: "bdk pagerduty replay" },
+            data,
+        },
+    };
+}

package/dist/channels/pagerduty/secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How a PagerDuty setting turns into a value. An omitted setting reads its
+ * well-known env var / deployment secret, which on Cursor hosting is the
+ * addressed installation's own secret of that name. An authored
+ * `{ secretName }` reads that secret instead and never falls back.
+ */
+import { type WebhookSecretValue } from "../../internal/named-webhook-secret.js";
+/**
+ * The secret name a setting reads: the authored `{ secretName }`, the
+ * default name when the setting is omitted, or `undefined` for a literal
+ * or getter authored in code.
+ */
+export declare function pagerDutySecretName(value: WebhookSecretValue | undefined, defaultName: string): string | undefined;
+/** The setting's value, read now; blank counts as unset. */
+export declare function resolvePagerDutySecret(value: WebhookSecretValue | undefined, defaultName: string): string | undefined;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/channels/pagerduty/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/secrets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wCAAwC,CAAC;AAGhD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,GAAG,SAAS,EACrC,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAKpB;AAED,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,GAAG,SAAS,EACrC,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAEpB"}

package/dist/channels/pagerduty/secrets.js

@@ -0,0 +1,23 @@
+/**
+ * How a PagerDuty setting turns into a value. An omitted setting reads its
+ * well-known env var / deployment secret, which on Cursor hosting is the
+ * addressed installation's own secret of that name. An authored
+ * `{ secretName }` reads that secret instead and never falls back.
+ */
+import { resolveWebhookSecretValue, } from "../../internal/named-webhook-secret.js";
+import { isSecretRef } from "../../types.js";
+/**
+ * The secret name a setting reads: the authored `{ secretName }`, the
+ * default name when the setting is omitted, or `undefined` for a literal
+ * or getter authored in code.
+ */
+export function pagerDutySecretName(value, defaultName) {
+    if (value === undefined) {
+        return defaultName;
+    }
+    return isSecretRef(value) ? value.secretName : undefined;
+}
+/** The setting's value, read now; blank counts as unset. */
+export function resolvePagerDutySecret(value, defaultName) {
+    return resolveWebhookSecretValue(value ?? { secretName: defaultName });
+}

package/dist/channels/pagerduty/self-user.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The PagerDuty user the agent acts as, for skipping its own echoed
+ * actions. Precedence: the authored `selfUserIds`, then the
+ * `PAGERDUTY_USER_ID` env var / deployment secret, then inference from the
+ * deployment's `PAGERDUTY_TOKEN`.
+ *
+ * Inference asks `GET /users/me`, which PagerDuty serves only to a
+ * user-level REST API key or an OAuth user token. An account-level REST
+ * API key or an OAuth app token has no user of its own; with
+ * `PAGERDUTY_FROM_EMAIL` set, the user whose email matches it exactly (the
+ * `From` user those tokens write as) is used instead. Results are cached
+ * in memory per credential set, never in agent storage.
+ */
+import { type PagerDutyClientOptions } from "./api.js";
+import type { PagerDutyChannelOptions } from "./types.js";
+/** Env var / deployment secret naming the agent's own PagerDuty user id. */
+export declare const PAGERDUTY_USER_ID_ENV = "PAGERDUTY_USER_ID";
+export interface PagerDutySelfUserDeps {
+    fetch?: typeof fetch;
+    now?: () => number;
+    warn?: (line: string) => void;
+}
+/**
+ * The secret the agent's user id is read from: a named `selfUserIds`, else
+ * `PAGERDUTY_USER_ID`. `undefined` when the ids are authored in code.
+ */
+export declare function pagerDutySelfUserIdSecretName(options: Pick<PagerDutyChannelOptions, "selfUserIds">): string | undefined;
+/**
+ * The user ids the agent acts as, resolved per delivery. Authored ids, a
+ * getter, or a named secret are used as given and never fall back. With
+ * nothing authored, `PAGERDUTY_USER_ID` (one id) wins, else the id inferred
+ * from the channel's token (`PAGERDUTY_TOKEN` unless `token` is set).
+ * Empty when none resolves, which turns echo skip off.
+ */
+export declare function resolvePagerDutySelfUserIds(input: {
+    options: Pick<PagerDutyChannelOptions, "selfUserIds" | "token" | "from" | "apiBaseUrl">;
+    deps?: PagerDutySelfUserDeps;
+}): Promise<ReadonlySet<string>>;
+/**
+ * The user the channel's token acts as (`token`, else `PAGERDUTY_TOKEN`),
+ * cached for an hour per base URL, token, and `From` email (an unresolved
+ * answer for five minutes). `undefined` without a token or when PagerDuty
+ * names no single user.
+ */
+export declare function inferPagerDutySelfUserId(input?: {
+    credentials?: Pick<PagerDutyClientOptions, "token" | "from" | "apiBaseUrl">;
+    deps?: PagerDutySelfUserDeps;
+}): Promise<string | undefined>;
+/** Forget every inferred user, so the next delivery asks PagerDuty again. */
+export declare function clearPagerDutySelfUserCache(): void;
+//# sourceMappingURL=self-user.d.ts.map

package/dist/channels/pagerduty/self-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-user.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/self-user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAWzD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,aAAa,CAAC,GACpD,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAAC,KAAK,EAAE;IACvD,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC,CAAC;IACxF,IAAI,CAAC,EAAE,qBAAqB,CAAC;CAC9B,GAAG,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAiB/B;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,GAAE;IACL,WAAW,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC,CAAC;IAC5E,IAAI,CAAC,EAAE,qBAAqB,CAAC;CACzB,GACL,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiD7B;AAED,6EAA6E;AAC7E,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/channels/pagerduty/self-user.js

@@ -0,0 +1,157 @@
+/**
+ * The PagerDuty user the agent acts as, for skipping its own echoed
+ * actions. Precedence: the authored `selfUserIds`, then the
+ * `PAGERDUTY_USER_ID` env var / deployment secret, then inference from the
+ * deployment's `PAGERDUTY_TOKEN`.
+ *
+ * Inference asks `GET /users/me`, which PagerDuty serves only to a
+ * user-level REST API key or an OAuth user token. An account-level REST
+ * API key or an OAuth app token has no user of its own; with
+ * `PAGERDUTY_FROM_EMAIL` set, the user whose email matches it exactly (the
+ * `From` user those tokens write as) is used instead. Results are cached
+ * in memory per credential set, never in agent storage.
+ */
+import { createHash } from "node:crypto";
+import { isSecretRef } from "../../types.js";
+import { PAGERDUTY_FROM_EMAIL_ENV, PAGERDUTY_TOKEN_ENV, pagerDutyApiBaseUrl, pagerDutyAuthorizationHeader, } from "./api.js";
+import { resolvePagerDutySecret } from "./secrets.js";
+/** Env var / deployment secret naming the agent's own PagerDuty user id. */
+export const PAGERDUTY_USER_ID_ENV = "PAGERDUTY_USER_ID";
+const RESOLVED_TTL_MS = 60 * 60 * 1000;
+const UNRESOLVED_TTL_MS = 5 * 60 * 1000;
+const LOOKUP_TIMEOUT_MS = 5_000;
+const MAX_CACHED_CREDENTIALS = 256;
+const inferredSelfUsers = new Map();
+/**
+ * The secret the agent's user id is read from: a named `selfUserIds`, else
+ * `PAGERDUTY_USER_ID`. `undefined` when the ids are authored in code.
+ */
+export function pagerDutySelfUserIdSecretName(options) {
+    if (options.selfUserIds === undefined) {
+        return PAGERDUTY_USER_ID_ENV;
+    }
+    return isSecretRef(options.selfUserIds) ? options.selfUserIds.secretName : undefined;
+}
+/**
+ * The user ids the agent acts as, resolved per delivery. Authored ids, a
+ * getter, or a named secret are used as given and never fall back. With
+ * nothing authored, `PAGERDUTY_USER_ID` (one id) wins, else the id inferred
+ * from the channel's token (`PAGERDUTY_TOKEN` unless `token` is set).
+ * Empty when none resolves, which turns echo skip off.
+ */
+export async function resolvePagerDutySelfUserIds(input) {
+    const options = input.options;
+    const selfUserIds = options.selfUserIds;
+    if (selfUserIds !== undefined) {
+        const ids = isSecretRef(selfUserIds)
+            ? [resolvePagerDutySecret(selfUserIds, selfUserIds.secretName) ?? ""]
+            : typeof selfUserIds === "function"
+                ? (selfUserIds() ?? [])
+                : selfUserIds;
+        return new Set(ids.map((id) => id.trim()).filter(Boolean));
+    }
+    const configured = resolvePagerDutySecret(undefined, PAGERDUTY_USER_ID_ENV);
+    if (configured !== undefined) {
+        return new Set([configured]);
+    }
+    const inferred = await inferPagerDutySelfUserId({ credentials: options, deps: input.deps });
+    return new Set(inferred === undefined ? [] : [inferred]);
+}
+/**
+ * The user the channel's token acts as (`token`, else `PAGERDUTY_TOKEN`),
+ * cached for an hour per base URL, token, and `From` email (an unresolved
+ * answer for five minutes). `undefined` without a token or when PagerDuty
+ * names no single user.
+ */
+export async function inferPagerDutySelfUserId(input = {}) {
+    const credentials = input.credentials ?? {};
+    const deps = input.deps ?? {};
+    const token = resolvePagerDutySecret(credentials.token, PAGERDUTY_TOKEN_ENV);
+    if (token === undefined) {
+        return undefined;
+    }
+    const from = resolvePagerDutySecret(credentials.from, PAGERDUTY_FROM_EMAIL_ENV);
+    const baseUrl = pagerDutyApiBaseUrl(credentials.apiBaseUrl);
+    const key = createHash("sha256")
+        .update(`${baseUrl}\n${token}\n${from ?? ""}`)
+        .digest("hex");
+    const now = deps.now ?? Date.now;
+    const cached = inferredSelfUsers.get(key);
+    if (cached !== undefined && cached.expiresAt > now()) {
+        return cached.userId;
+    }
+    const entry = {
+        expiresAt: now() + UNRESOLVED_TTL_MS,
+        userId: lookUpSelfUser({ baseUrl, token, from, fetch: deps.fetch ?? fetch }).then((userId) => {
+            if (userId === undefined) {
+                (deps.warn ?? console.warn)(`[bdk/pagerduty] warn ${PAGERDUTY_TOKEN_ENV} names no single PagerDuty user (an account-level key or app token needs ${PAGERDUTY_FROM_EMAIL_ENV} set to one user's email); set ${PAGERDUTY_USER_ID_ENV} to skip the agent's own actions`);
+            }
+            else {
+                entry.expiresAt = now() + RESOLVED_TTL_MS;
+            }
+            return userId;
+        }, (error) => {
+            (deps.warn ?? console.warn)(`[bdk/pagerduty] warn could not look up the agent's PagerDuty user; echo skip is off until it resolves: ${error instanceof Error ? error.message : String(error)}`);
+            return undefined;
+        }),
+    };
+    inferredSelfUsers.delete(key);
+    inferredSelfUsers.set(key, entry);
+    while (inferredSelfUsers.size > MAX_CACHED_CREDENTIALS) {
+        const oldest = inferredSelfUsers.keys().next().value;
+        if (oldest === undefined) {
+            break;
+        }
+        inferredSelfUsers.delete(oldest);
+    }
+    return entry.userId;
+}
+/** Forget every inferred user, so the next delivery asks PagerDuty again. */
+export function clearPagerDutySelfUserCache() {
+    inferredSelfUsers.clear();
+}
+async function lookUpSelfUser(input) {
+    const get = async (path) => input.fetch(`${input.baseUrl}${path}`, {
+        method: "GET",
+        headers: {
+            Accept: "application/vnd.pagerduty+json;version=2",
+            Authorization: pagerDutyAuthorizationHeader(input.token),
+        },
+        signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+    });
+    const me = await get("/users/me");
+    if (me.ok) {
+        const id = userIdOf((await me.json()).user);
+        if (id !== undefined) {
+            return id;
+        }
+    }
+    else {
+        await me.body?.cancel();
+        if (me.status === 401 || me.status >= 500) {
+            throw new Error(`GET /users/me answered ${me.status}`);
+        }
+    }
+    if (input.from === undefined) {
+        return undefined;
+    }
+    const email = input.from.toLowerCase();
+    const found = await get(`/users?query=${encodeURIComponent(input.from)}&limit=100`);
+    if (!found.ok) {
+        await found.body?.cancel();
+        throw new Error(`GET /users?query= answered ${found.status}`);
+    }
+    const users = (await found.json()).users;
+    const matches = (Array.isArray(users) ? users : []).filter((user) => typeof user === "object" &&
+        user !== null &&
+        typeof user.email === "string" &&
+        user.email.toLowerCase() === email);
+    return matches.length === 1 ? userIdOf(matches[0]) : undefined;
+}
+function userIdOf(user) {
+    if (typeof user !== "object" || user === null) {
+        return undefined;
+    }
+    const id = user.id;
+    return typeof id === "string" && id.trim() !== "" ? id.trim() : undefined;
+}

package/dist/channels/pagerduty/state.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Durable per-session PagerDuty channel state, persisted with the turn so
+ * stream-event handlers can address the incident without re-parsing the
+ * webhook.
+ */
+export interface PagerDutyChannelState {
+    /** Incident the latest dispatched event named. */
+    incidentId: string | null;
+    incidentNumber: number | null;
+    /** That incident's dedup key, when the event carried one. */
+    incidentKey: string | null;
+    serviceId: string | null;
+    /** v3 `event_type` that woke the turn. */
+    eventType: string | null;
+    /** v3 `event.id` that woke the turn. */
+    eventId: string | null;
+    deliveryId: string | null;
+    occurredAt: string | null;
+}
+export declare function emptyPagerDutyChannelState(overrides?: Partial<PagerDutyChannelState>): PagerDutyChannelState;
+export declare function pagerDutyChannelStateForEvent(input: {
+    eventType: string;
+    eventId: string;
+    incidentId?: string;
+    incidentNumber?: number;
+    incidentKey?: string;
+    serviceId?: string;
+    deliveryId?: string;
+    occurredAt?: string;
+}): PagerDutyChannelState;
+//# sourceMappingURL=state.d.ts.map

package/dist/channels/pagerduty/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wCAAwC;IACxC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAgB,0BAA0B,CACxC,SAAS,GAAE,OAAO,CAAC,qBAAqB,CAAM,GAC7C,qBAAqB,CAYvB;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,qBAAqB,CAWxB"}

package/dist/channels/pagerduty/state.js

@@ -0,0 +1,30 @@
+/**
+ * Durable per-session PagerDuty channel state, persisted with the turn so
+ * stream-event handlers can address the incident without re-parsing the
+ * webhook.
+ */
+export function emptyPagerDutyChannelState(overrides = {}) {
+    return {
+        incidentId: null,
+        incidentNumber: null,
+        incidentKey: null,
+        serviceId: null,
+        eventType: null,
+        eventId: null,
+        deliveryId: null,
+        occurredAt: null,
+        ...overrides,
+    };
+}
+export function pagerDutyChannelStateForEvent(input) {
+    return emptyPagerDutyChannelState({
+        incidentId: input.incidentId ?? null,
+        incidentNumber: input.incidentNumber ?? null,
+        incidentKey: input.incidentKey ?? null,
+        serviceId: input.serviceId ?? null,
+        eventType: input.eventType,
+        eventId: input.eventId,
+        deliveryId: input.deliveryId ?? null,
+        occurredAt: input.occurredAt ?? null,
+    });
+}