@cursor/bdk 0.2.23 → 0.2.25

package/dist/channels/pagerduty/defaults.js

@@ -0,0 +1,132 @@
+/**
+ * Default dispatch decisions for the PagerDuty channel: turn auth derived
+ * from the event's agent, the title and message a turn starts with, which
+ * lifecycle events dispatch when no `onIncident` hook exists, and the
+ * stream handlers that post replies back to the incident.
+ */
+import { PAGERDUTY_TOKEN_ENV, pagerDutyChannelClient } from "./api.js";
+import { resolvePagerDutySecret } from "./secrets.js";
+import { PAGERDUTY_USER_ID_ENV, resolvePagerDutySelfUserIds } from "./self-user.js";
+/**
+ * Derive the turn's auth from who made the change: a PagerDuty user, a
+ * service integration, or PagerDuty itself. The webhook subscriber is not
+ * the turn principal (same pattern as `defaultGitHubAuth`).
+ */
+export function defaultPagerDutyAuth(ctx) {
+    const agent = ctx.agent;
+    const isUser = agent?.type === "user_reference" || agent?.type === "user";
+    const attributes = {
+        conversation_kind: "incident",
+        event_type: ctx.eventType,
+        event_id: ctx.eventId,
+        issuer: ctx.accountSubdomain === undefined ? "pagerduty" : `pagerduty:${ctx.accountSubdomain}`,
+    };
+    if (ctx.incidentId !== undefined) {
+        attributes.incident_id = ctx.incidentId;
+    }
+    if (ctx.incidentKey !== undefined) {
+        attributes.incident_key = ctx.incidentKey;
+    }
+    if (ctx.deliveryId !== undefined) {
+        attributes.delivery_id = ctx.deliveryId;
+    }
+    if (agent !== undefined) {
+        attributes.subject = agent.id;
+    }
+    return {
+        authenticator: "pagerduty-webhook",
+        principalId: agent === undefined ? "pagerduty" : `pagerduty:${agent.id}`,
+        principalType: isUser ? "user" : "service",
+        attributes,
+    };
+}
+export function defaultPagerDutyTitle(ctx, incident) {
+    if (incident?.number !== undefined && incident.title !== undefined) {
+        return `PagerDuty #${incident.number}: ${incident.title}`;
+    }
+    return ctx.incidentId === undefined
+        ? `PagerDuty ${ctx.eventType}`
+        : `PagerDuty incident ${ctx.incidentId}`;
+}
+/** The facts of a lifecycle event, one per line, for the turn's first message. */
+export function defaultPagerDutyIncidentMessage(ctx, event) {
+    const incident = event.incident;
+    return [
+        `PagerDuty ${ctx.eventType}: ${incident.number === undefined ? incident.id : `#${incident.number}`}`,
+        ...(incident.title === undefined ? [] : [`Title: ${incident.title}`]),
+        ...(incident.status === undefined ? [] : [`Status: ${incident.status}`]),
+        ...(incident.urgency === undefined ? [] : [`Urgency: ${incident.urgency}`]),
+        ...(incident.service?.summary === undefined ? [] : [`Service: ${incident.service.summary}`]),
+        ...(incident.priority?.summary === undefined ? [] : [`Priority: ${incident.priority.summary}`]),
+        ...(incident.incidentKey === undefined ? [] : [`Incident key: ${incident.incidentKey}`]),
+        ...(incident.htmlUrl === undefined ? [] : [`URL: ${incident.htmlUrl}`]),
+        ...(ctx.agent?.summary === undefined ? [] : [`By: ${ctx.agent.summary}`]),
+        ...(ctx.occurredAt === undefined ? [] : [`Occurred at: ${ctx.occurredAt}`]),
+        "Handle this PagerDuty incident event.",
+    ].join("\n");
+}
+/**
+ * Default gate when no `onIncident` hook is declared: a new or reopened
+ * incident starts a turn as the event's agent. Acknowledgements,
+ * escalations, and resolves are acknowledged without one.
+ */
+export function defaultPagerDutyIncidentDispatch(ctx, event) {
+    if (event.eventType !== "incident.triggered" && event.eventType !== "incident.reopened") {
+        return null;
+    }
+    return { auth: defaultPagerDutyAuth(ctx) };
+}
+const PAGERDUTY_FAILURE_NOTE = "The agent hit an error while handling this incident. Check the agent's session for details.";
+/**
+ * Opt-in delivery (`deliverReplies: true`): post each completed assistant
+ * reply as a note on the session's incident, and a short note when a turn
+ * or session fails. Skipped when the session names no incident or is an
+ * eval run, or when the channel has no token (a read-only agent).
+ *
+ * A posted note comes back as an `incident.annotated` event, which only the
+ * echo skip keeps from starting another turn. So nothing is posted until the
+ * agent's own PagerDuty user resolves (see `selfUserIds`); until then each
+ * skipped note logs a warning.
+ */
+export function buildDefaultPagerDutyEvents(options) {
+    if (options.deliverReplies !== true) {
+        return {};
+    }
+    const postNote = async (state, content) => {
+        if (state.incidentId === null ||
+            resolvePagerDutySecret(options.token, PAGERDUTY_TOKEN_ENV) === undefined) {
+            return;
+        }
+        if ((await resolvePagerDutySelfUserIds({ options })).size === 0) {
+            console.warn(`[bdk/pagerduty] warn not posting a reply note to incident ${state.incidentId}: the agent's own PagerDuty user is unknown, so the note would come back as a new event. Set ${PAGERDUTY_USER_ID_ENV} or selfUserIds, or use a token that names one user.`);
+            return;
+        }
+        try {
+            await pagerDutyChannelClient(options).addNote({ incidentId: state.incidentId, content });
+        }
+        catch (error) {
+            console.warn(`[bdk/pagerduty] warn could not post a note to incident ${state.incidentId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    return {
+        async "message.completed"(event, channel, ctx) {
+            if (ctx.session.purpose === "eval" ||
+                event.data.parentCallId !== undefined ||
+                event.data.finishReason === "tool_call" ||
+                event.data.text === "") {
+                return;
+            }
+            await postNote(channel.state, event.data.text);
+        },
+        async "turn.failed"(_event, channel, ctx) {
+            if (ctx.session.purpose !== "eval") {
+                await postNote(channel.state, PAGERDUTY_FAILURE_NOTE);
+            }
+        },
+        async "session.failed"(_event, channel, ctx) {
+            if (ctx.session.purpose !== "eval") {
+                await postNote(channel.state, PAGERDUTY_FAILURE_NOTE);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,24 @@
+import { PAGERDUTY_INCIDENT_EVENT_TYPES } from "../../internal/continuation-identity.js";
+/** {@link ChannelMeta.kind} value used by {@link pagerdutyChannel}. */
+export declare const PAGERDUTY_CHANNEL_KIND = "pagerduty";
+/** Every v3 `event_type` that names one incident; the selector's membership. */
+export { PAGERDUTY_INCIDENT_EVENT_TYPES };
+/** Lifecycle events whose `data` is the full incident; `onIncident` receives them. */
+export declare const PAGERDUTY_INCIDENT_LIFECYCLE_EVENTS: readonly ["incident.triggered", "incident.acknowledged", "incident.unacknowledged", "incident.escalated", "incident.reassigned", "incident.delegated", "incident.resolved", "incident.reopened", "incident.priority_updated", "incident.incident_type.changed"];
+export type PagerDutyIncidentLifecycleEvent = (typeof PAGERDUTY_INCIDENT_LIFECYCLE_EVENTS)[number];
+/** `incident.annotated`: a note on the incident; `onNote` receives it. */
+export declare const PAGERDUTY_NOTE_EVENTS: readonly ["incident.annotated"];
+/** Responder requests and replies; `onResponder` receives them. */
+export declare const PAGERDUTY_RESPONDER_EVENTS: readonly ["incident.responder.added", "incident.responder.replied"];
+export interface PagerDutyWebhookEventOptions {
+    webhookEvents?: readonly string[];
+}
+/**
+ * The event types the channel publishes as `meta.pagerdutyWebhookEvents`
+ * and the deploy manifest's `eventTypes`: a pinned list, or every incident
+ * event. Every typed hook and the default dispatch fall inside that set, so
+ * an omitted selector defaults to `pagerduty.incident/v2`.
+ */
+export declare function derivePagerDutyWebhookEvents(options: PagerDutyWebhookEventOptions): string[];
+export declare function isPagerDutyIncidentLifecycleEvent(eventType: string): eventType is PagerDutyIncidentLifecycleEvent;
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AAEzF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD,gFAAgF;AAChF,OAAO,EAAE,8BAA8B,EAAE,CAAC;AAE1C,sFAAsF;AACtF,eAAO,MAAM,mCAAmC,YAC9C,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC3B,gCAAgC,CACxB,CAAC;AAEX,MAAM,MAAM,+BAA+B,GAAG,CAAC,OAAO,mCAAmC,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnG,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,YAAI,oBAAoB,CAAU,CAAC;AAErE,mEAAmE;AACnE,eAAO,MAAM,0BAA0B,YACrC,0BAA0B,EAC1B,4BAA4B,CACpB,CAAC;AAEX,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,EAAE,CAG5F;AAED,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,MAAM,GAChB,SAAS,IAAI,+BAA+B,CAE9C"}

package/dist/channels/pagerduty/events.js

@@ -0,0 +1,38 @@
+import { PAGERDUTY_INCIDENT_EVENT_TYPES } from "../../internal/continuation-identity.js";
+/** {@link ChannelMeta.kind} value used by {@link pagerdutyChannel}. */
+export const PAGERDUTY_CHANNEL_KIND = "pagerduty";
+/** Every v3 `event_type` that names one incident; the selector's membership. */
+export { PAGERDUTY_INCIDENT_EVENT_TYPES };
+/** Lifecycle events whose `data` is the full incident; `onIncident` receives them. */
+export const PAGERDUTY_INCIDENT_LIFECYCLE_EVENTS = [
+    "incident.triggered",
+    "incident.acknowledged",
+    "incident.unacknowledged",
+    "incident.escalated",
+    "incident.reassigned",
+    "incident.delegated",
+    "incident.resolved",
+    "incident.reopened",
+    "incident.priority_updated",
+    "incident.incident_type.changed",
+];
+/** `incident.annotated`: a note on the incident; `onNote` receives it. */
+export const PAGERDUTY_NOTE_EVENTS = ["incident.annotated"];
+/** Responder requests and replies; `onResponder` receives them. */
+export const PAGERDUTY_RESPONDER_EVENTS = [
+    "incident.responder.added",
+    "incident.responder.replied",
+];
+/**
+ * The event types the channel publishes as `meta.pagerdutyWebhookEvents`
+ * and the deploy manifest's `eventTypes`: a pinned list, or every incident
+ * event. Every typed hook and the default dispatch fall inside that set, so
+ * an omitted selector defaults to `pagerduty.incident/v2`.
+ */
+export function derivePagerDutyWebhookEvents(options) {
+    const events = options.webhookEvents ?? PAGERDUTY_INCIDENT_EVENT_TYPES;
+    return [...new Set(events.map((event) => event.trim()).filter(Boolean))];
+}
+export function isPagerDutyIncidentLifecycleEvent(eventType) {
+    return PAGERDUTY_INCIDENT_LIFECYCLE_EVENTS.includes(eventType);
+}

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

@@ -0,0 +1,31 @@
+/**
+ * PagerDuty v3 webhook channel pack.
+ *
+ * ```ts
+ * import { defaultPagerDutyAuth, pagerdutyChannel } from "@cursor/bdk/channels/pagerduty";
+ *
+ * // Verifies against the PAGERDUTY_WEBHOOK_SECRET deployment secret and skips
+ * // the agent's own actions: PAGERDUTY_USER_ID, else the user PAGERDUTY_TOKEN
+ * // acts as.
+ * export default pagerdutyChannel({
+ *   onIncident: (ctx) => ({ auth: defaultPagerDutyAuth(ctx) }),
+ * });
+ * ```
+ *
+ * The route verifies `X-PagerDuty-Signature` (one `v1=` HMAC-SHA256 entry
+ * per active subscription secret; any match admits). Every event for one
+ * incident key, the dedup key of the alert that opened the incident, joins
+ * one session; an incident without a key joins on its id. The agent's own
+ * actions, echoed back with its PagerDuty user as `agent`, are acknowledged
+ * without a turn.
+ */
+export * from "./api.js";
+export * from "./defaults.js";
+export * from "./events.js";
+export { pagerDutyAccountSubdomain, pagerDutyEventIncident, pagerDutyIncidentFromData, pagerDutyNoteFromData, pagerDutyResponderFromData, } from "./payload.js";
+export * from "./pagerduty-channel.js";
+export * from "./pagerduty-webhook.js";
+export { inferPagerDutySelfUserId, PAGERDUTY_USER_ID_ENV, type PagerDutySelfUserDeps, pagerDutySelfUserIdSecretName, resolvePagerDutySelfUserIds, } from "./self-user.js";
+export * from "./state.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,cAAc,CAAC;AACtB,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/channels/pagerduty/index.js

@@ -0,0 +1,30 @@
+/**
+ * PagerDuty v3 webhook channel pack.
+ *
+ * ```ts
+ * import { defaultPagerDutyAuth, pagerdutyChannel } from "@cursor/bdk/channels/pagerduty";
+ *
+ * // Verifies against the PAGERDUTY_WEBHOOK_SECRET deployment secret and skips
+ * // the agent's own actions: PAGERDUTY_USER_ID, else the user PAGERDUTY_TOKEN
+ * // acts as.
+ * export default pagerdutyChannel({
+ *   onIncident: (ctx) => ({ auth: defaultPagerDutyAuth(ctx) }),
+ * });
+ * ```
+ *
+ * The route verifies `X-PagerDuty-Signature` (one `v1=` HMAC-SHA256 entry
+ * per active subscription secret; any match admits). Every event for one
+ * incident key, the dedup key of the alert that opened the incident, joins
+ * one session; an incident without a key joins on its id. The agent's own
+ * actions, echoed back with its PagerDuty user as `agent`, are acknowledged
+ * without a turn.
+ */
+export * from "./api.js";
+export * from "./defaults.js";
+export * from "./events.js";
+export { pagerDutyAccountSubdomain, pagerDutyEventIncident, pagerDutyIncidentFromData, pagerDutyNoteFromData, pagerDutyResponderFromData, } from "./payload.js";
+export * from "./pagerduty-channel.js";
+export * from "./pagerduty-webhook.js";
+export { inferPagerDutySelfUserId, PAGERDUTY_USER_ID_ENV, pagerDutySelfUserIdSecretName, resolvePagerDutySelfUserIds, } from "./self-user.js";
+export * from "./state.js";
+export * from "./types.js";

package/dist/channels/pagerduty/pagerduty-channel.d.ts

@@ -0,0 +1,64 @@
+import { type AuthPolicy, type ChannelDefinition } from "../../types.js";
+import type { SecretAlternatives } from "../../internal/secret-alternatives.js";
+import { type PagerDutyChannelState } from "./state.js";
+import type { PagerDutyChannelOptions } from "./types.js";
+export declare function getPagerDutyChannelOptions(definition: object): PagerDutyChannelOptions | undefined;
+/**
+ * Deployment secrets the channel reads in the guest that must each be set:
+ * a named `selfUserIds`, `token`, or `from` secret. `deploy` declares them
+ * so an unset one is flagged instead of the agent waking on its own echoes
+ * or failing its write-backs.
+ */
+export declare function pagerDutyChannelCredentialSecretNames(definition: object): string[];
+/**
+ * Deployment secrets of which at least one must be set: with `selfUserIds`
+ * omitted, the agent's user comes from `PAGERDUTY_USER_ID` or is inferred
+ * from the channel's token. `deploy` warns when neither is set. A token
+ * authored in code always infers, so it needs no warning.
+ */
+export declare function pagerDutyChannelSecretAlternatives(definition: object): SecretAlternatives[];
+/**
+ * Why a `pagerdutyChannel` cannot deploy onto architecture v2 as authored,
+ * or `undefined` when it can: v2 needs a named `webhookSecret` so the
+ * control plane can verify `X-PagerDuty-Signature` before any compute starts.
+ */
+export declare function pagerDutyChannelArchitectureError(definition: object): string | undefined;
+/**
+ * The route policy for a PagerDuty v3 webhook whose secret is named: any
+ * `v1=` entry of `X-PagerDuty-Signature` must be the body's HMAC under the
+ * env var / deployment secret `secretName`, so both of a rotating pair of
+ * secrets verify. Being an {@link hmacSignatureAuth} policy, `deploy`
+ * writes it into the manifest and the control plane runs the same check
+ * at ingestion.
+ */
+export declare function pagerDutyWebhookSignatureAuth(secretName: string): AuthPolicy;
+export declare function pagerdutyChannel(options?: PagerDutyChannelOptions): ChannelDefinition<PagerDutyChannelState>;
+/** The slice of a discovered agent mount that {@link findPagerDutyChannelTargets} reads. */
+export interface PagerDutyAgentMountLike {
+    slug: string;
+    project: {
+        channels: Array<{
+            id: string;
+            definition: {
+                meta?: {
+                    kind?: string;
+                    pagerdutyWebhookEvents?: readonly string[];
+                };
+                routes?: ReadonlyArray<{
+                    method: string;
+                    path: string;
+                }>;
+            };
+        }>;
+    };
+}
+export interface PagerDutyChannelTarget {
+    slug: string;
+    channelId: string;
+    /** Route path under the channel (default `/`). */
+    routePath: string;
+    events: string[];
+}
+/** Every mounted `pagerdutyChannel()`, for `bdk pagerduty replay` and `events`. */
+export declare function findPagerDutyChannelTargets(mounts: ReadonlyArray<PagerDutyAgentMountLike>): PagerDutyChannelTarget[];
+//# sourceMappingURL=pagerduty-channel.d.ts.map

package/dist/channels/pagerduty/pagerduty-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagerduty-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/pagerduty-channel.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAe,MAAM,gBAAgB,CAAC;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAahF,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAI1D,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,GACjB,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAUlF;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAe3F;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWxF;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAO5E;AAmCD,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,uBAA4B,GACpC,iBAAiB,CAAC,qBAAqB,CAAC,CA4D1C;AAED,4FAA4F;AAC5F,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QACP,QAAQ,EAAE,KAAK,CAAC;YACd,EAAE,EAAE,MAAM,CAAC;YACX,UAAU,EAAE;gBACV,IAAI,CAAC,EAAE;oBAAE,IAAI,CAAC,EAAE,MAAM,CAAC;oBAAC,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;iBAAE,CAAC;gBACrE,MAAM,CAAC,EAAE,aAAa,CAAC;oBAAE,MAAM,EAAE,MAAM,CAAC;oBAAC,IAAI,EAAE,MAAM,CAAA;iBAAE,CAAC,CAAC;aAC1D,CAAC;SACH,CAAC,CAAC;KACJ,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,aAAa,CAAC,uBAAuB,CAAC,GAC7C,sBAAsB,EAAE,CAkB1B"}

package/dist/channels/pagerduty/pagerduty-channel.js

@@ -0,0 +1,195 @@
+import * as z from "zod/v4";
+import { allowAll, defineChannel, hmacSignatureAuth, localDevStrict, loopbackOnly, POST, } from "../../channels.js";
+import { withPropagatingBackgroundErrors } from "../../internal/channel-dispatch.js";
+import { normalizeIdentity } from "../../internal/continuation-identity.js";
+import { isDevMode } from "../../internal/dev-mode.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import { replayCatchRequest } from "../../internal/hosted-catch.js";
+import { AGENT_SDK_CATCH_EVENT_TYPE } from "../../internal/hosted-catch-protocol.js";
+import { namedWebhookSecretArchitectureError } from "../../internal/named-webhook-secret.js";
+import { isSecretRef } from "../../types.js";
+import { buildDefaultPagerDutyEvents } from "./defaults.js";
+import { derivePagerDutyWebhookEvents, PAGERDUTY_CHANNEL_KIND } from "./events.js";
+import { handlePagerDutyWebhookRequest, PAGERDUTY_SIGNATURE_HEADER, PAGERDUTY_SIGNATURE_PREFIX, PAGERDUTY_SIGNATURE_SEPARATOR, PAGERDUTY_WEBHOOK_SECRET_ENV, } from "./pagerduty-webhook.js";
+import { PAGERDUTY_TOKEN_ENV } from "./api.js";
+import { PAGERDUTY_USER_ID_ENV, pagerDutySelfUserIdSecretName } from "./self-user.js";
+import { pagerDutySecretName, resolvePagerDutySecret } from "./secrets.js";
+import { emptyPagerDutyChannelState } from "./state.js";
+const pagerDutyChannelOptionsByDefinition = new WeakMap();
+export function getPagerDutyChannelOptions(definition) {
+    return pagerDutyChannelOptionsByDefinition.get(definition);
+}
+/**
+ * Deployment secrets the channel reads in the guest that must each be set:
+ * a named `selfUserIds`, `token`, or `from` secret. `deploy` declares them
+ * so an unset one is flagged instead of the agent waking on its own echoes
+ * or failing its write-backs.
+ */
+export function pagerDutyChannelCredentialSecretNames(definition) {
+    const options = getPagerDutyChannelOptions(definition);
+    if (options === undefined) {
+        return [];
+    }
+    return [
+        ...(options.selfUserIds === undefined ? [] : [pagerDutySelfUserIdSecretName(options)]),
+        ...(isSecretRef(options.token) ? [options.token.secretName] : []),
+        ...(isSecretRef(options.from) ? [options.from.secretName] : []),
+    ].filter((name) => name !== undefined);
+}
+/**
+ * Deployment secrets of which at least one must be set: with `selfUserIds`
+ * omitted, the agent's user comes from `PAGERDUTY_USER_ID` or is inferred
+ * from the channel's token. `deploy` warns when neither is set. A token
+ * authored in code always infers, so it needs no warning.
+ */
+export function pagerDutyChannelSecretAlternatives(definition) {
+    const options = getPagerDutyChannelOptions(definition);
+    if (options === undefined || options.selfUserIds !== undefined) {
+        return [];
+    }
+    const tokenName = pagerDutySecretName(options.token, PAGERDUTY_TOKEN_ENV);
+    if (tokenName === undefined) {
+        return [];
+    }
+    return [
+        {
+            names: [PAGERDUTY_USER_ID_ENV, tokenName],
+            unsetEffect: `the PagerDuty channel cannot tell the agent's own actions apart, so echo skip is off (set ${PAGERDUTY_USER_ID_ENV}, or ${tokenName} to infer it)`,
+        },
+    ];
+}
+/**
+ * Why a `pagerdutyChannel` cannot deploy onto architecture v2 as authored,
+ * or `undefined` when it can: v2 needs a named `webhookSecret` so the
+ * control plane can verify `X-PagerDuty-Signature` before any compute starts.
+ */
+export function pagerDutyChannelArchitectureError(definition) {
+    const options = getPagerDutyChannelOptions(definition);
+    if (options === undefined) {
+        return undefined;
+    }
+    return namedWebhookSecretArchitectureError({
+        option: "pagerdutyChannel webhookSecret",
+        webhookSecret: options.webhookSecret,
+        envName: PAGERDUTY_WEBHOOK_SECRET_ENV,
+        verifies: "X-PagerDuty-Signature",
+    });
+}
+/**
+ * The route policy for a PagerDuty v3 webhook whose secret is named: any
+ * `v1=` entry of `X-PagerDuty-Signature` must be the body's HMAC under the
+ * env var / deployment secret `secretName`, so both of a rotating pair of
+ * secrets verify. Being an {@link hmacSignatureAuth} policy, `deploy`
+ * writes it into the manifest and the control plane runs the same check
+ * at ingestion.
+ */
+export function pagerDutyWebhookSignatureAuth(secretName) {
+    return hmacSignatureAuth({
+        header: PAGERDUTY_SIGNATURE_HEADER,
+        secret: secretName,
+        prefix: PAGERDUTY_SIGNATURE_PREFIX,
+        separator: PAGERDUTY_SIGNATURE_SEPARATOR,
+    });
+}
+/**
+ * Default route auth for the resolved webhook secret, the same postures as
+ * the SCM channels: a named secret is the route policy (and the control
+ * plane's catch check); a literal or getter keeps the check in the handler
+ * behind `allowAll()`.
+ *
+ * An omitted `webhookSecret` names `PAGERDUTY_WEBHOOK_SECRET`, so a
+ * zero-config channel deploys with the control plane verifying against
+ * that deployment secret. While it is unset (a fresh local checkout), the
+ * route keeps the no-secret posture: loopback-strict, and `--dev` admits
+ * loopback. Both are read per request: channel modules construct at import,
+ * and a hosted deployment receives its secrets per request.
+ */
+function defaultPagerDutyRouteAuth(webhookSecret, usesDefaultSecret) {
+    if (isSecretRef(webhookSecret)) {
+        const signature = pagerDutyWebhookSignatureAuth(webhookSecret.secretName);
+        if (!usesDefaultSecret) {
+            return [signature];
+        }
+        const whileUnset = (request, info) => {
+            if (resolvePagerDutySecret(webhookSecret, PAGERDUTY_WEBHOOK_SECRET_ENV) !== undefined) {
+                return null;
+            }
+            return (isDevMode() ? loopbackOnly() : localDevStrict())(request, info);
+        };
+        return [signature, whileUnset];
+    }
+    return [allowAll()];
+}
+export function pagerdutyChannel(options = {}) {
+    const routePath = options.path ?? "/";
+    // Always named, never read here: it deploys like an authored
+    // `{ secretName: "PAGERDUTY_WEBHOOK_SECRET" }` whether or not the shell
+    // that runs `deploy` has the value.
+    const usesDefaultSecret = options.webhookSecret === undefined;
+    const webhookSecret = options.webhookSecret ?? { secretName: PAGERDUTY_WEBHOOK_SECRET_ENV };
+    const auth = options.auth ?? defaultPagerDutyRouteAuth(webhookSecret, usesDefaultSecret);
+    const channelOptions = { ...options, webhookSecret };
+    if (channelOptions.continuation !== undefined) {
+        channelOptions.continuation = normalizeIdentity(channelOptions.continuation, PAGERDUTY_CHANNEL_KIND);
+    }
+    const definition = defineChannel({
+        auth,
+        state: emptyPagerDutyChannelState(),
+        events: { ...buildDefaultPagerDutyEvents(channelOptions), ...options.events },
+        onStart: options.onStart,
+        onStop: options.onStop,
+        meta: {
+            kind: PAGERDUTY_CHANNEL_KIND,
+            pagerdutyWebhookEvents: derivePagerDutyWebhookEvents(channelOptions),
+        },
+        routes: [
+            POST(routePath, {
+                bodySchema: z.unknown(),
+                description: "PagerDuty v3 webhook ingress",
+                handler: async (request, args) => handlePagerDutyWebhookRequest({ options: channelOptions, request, args }),
+            }),
+        ],
+    });
+    pagerDutyChannelOptionsByDefinition.set(definition, channelOptions);
+    attachHostedAdmissionAdapter(definition, {
+        kind: PAGERDUTY_CHANNEL_KIND,
+        prepareArgs: withPropagatingBackgroundErrors,
+        dispatch: async ({ channelId, eventType, payload, deliveryId, args }) => {
+            // Hosted deliveries are http.request envelopes the control plane
+            // already verified with the deployment secret and stamped with the
+            // incident's key. Replay into the route handler, which verifies
+            // X-PagerDuty-Signature again and runs the echo skip.
+            if (eventType !== AGENT_SDK_CATCH_EVENT_TYPE) {
+                return Response.json({ ok: false, error: "unsupported_pagerduty_delivery" }, { status: 400 });
+            }
+            return replayCatchRequest({
+                channelId: channelId ?? PAGERDUTY_CHANNEL_KIND,
+                deliveryId,
+                routes: definition.routes ?? [],
+                payload,
+                args,
+            });
+        },
+    });
+    return definition;
+}
+/** Every mounted `pagerdutyChannel()`, for `bdk pagerduty replay` and `events`. */
+export function findPagerDutyChannelTargets(mounts) {
+    const targets = [];
+    for (const { slug, project } of mounts) {
+        for (const channel of project.channels) {
+            const meta = channel.definition.meta;
+            if (meta?.kind !== PAGERDUTY_CHANNEL_KIND) {
+                continue;
+            }
+            const postRoute = (channel.definition.routes ?? []).find((route) => route.method === "POST");
+            targets.push({
+                slug,
+                channelId: channel.id,
+                routePath: postRoute?.path ?? "/",
+                events: [...(meta.pagerdutyWebhookEvents ?? [])],
+            });
+        }
+    }
+    return targets;
+}

package/dist/channels/pagerduty/pagerduty-webhook.d.ts

@@ -0,0 +1,70 @@
+import type { ChannelHandlerArgs } from "../../types.js";
+import type { PagerDutyChannelOptions, PagerDutyEventContext, PagerDutyWebhookDelivery } from "./types.js";
+/** Env var / deployment secret an omitted `webhookSecret` falls back to. */
+export declare const PAGERDUTY_WEBHOOK_SECRET_ENV = "PAGERDUTY_WEBHOOK_SECRET";
+/** Header PagerDuty signs v3 deliveries with: `v1=<hex>[,v1=<hex>…]`. */
+export declare const PAGERDUTY_SIGNATURE_HEADER = "x-pagerduty-signature";
+export declare const PAGERDUTY_SIGNATURE_PREFIX = "v1=";
+/** Separator between signatures while a subscription's secret rotates. */
+export declare const PAGERDUTY_SIGNATURE_SEPARATOR = ",";
+/**
+ * The secret's value for the handler's own signature check, read now: an
+ * omitted field names `PAGERDUTY_WEBHOOK_SECRET` (hosted, the addressed
+ * installation's secret), and an authored name never falls back to it.
+ */
+export declare function resolvePagerDutyWebhookSecret(options: Pick<PagerDutyChannelOptions, "webhookSecret">): string | undefined;
+/** One `X-PagerDuty-Signature` entry for a raw body: `v1=<hex>`. */
+export declare function signPagerDutyWebhookBody(input: {
+    rawBody: string | Buffer;
+    secret: string;
+}): string;
+/**
+ * True when any `v1=` entry in the header is the body's HMAC-SHA256 under
+ * any secret `secret` holds. `secret` is the named secret's value: one
+ * signing secret, or one per line when several subscriptions sign the
+ * route. Every (secret, entry) pair is compared in constant time with no
+ * early exit; malformed entries never match, and a missing header is a
+ * plain `false`.
+ */
+export declare function verifyPagerDutyWebhookSignature(input: {
+    rawBody: string | Buffer;
+    signatureHeader: string | null | undefined;
+    secret: string;
+}): boolean;
+/**
+ * True when the event is the agent's own action echoed back: its `agent`
+ * is a PagerDuty user the agent acts as. Service integrations and
+ * PagerDuty itself never count, so an alert the agent's own monitor opened
+ * still dispatches.
+ */
+export declare function isPagerDutySelfEcho(ctx: Pick<PagerDutyEventContext, "agent">, selfUserIds: ReadonlySet<string>): boolean;
+/**
+ * Accept a raw v3 body. The event type comes from the signed body's
+ * `event.event_type`, never from a header, so a captured delivery cannot be
+ * re-dispatched as another event.
+ */
+export declare function parsePagerDutyWebhookPayload(payload: unknown): PagerDutyWebhookDelivery | null;
+export declare function parsePagerDutyEventContext(delivery: PagerDutyWebhookDelivery): Omit<PagerDutyEventContext, "host" | "artifacts" | "send" | "pagerduty"> | null;
+/**
+ * Run the authored hooks for one verified PagerDuty delivery and `send()`
+ * the turn. Callers own delivery auth: the HTTP route verifies
+ * `X-PagerDuty-Signature`; hosted admission arrives verified. The v2
+ * mailbox is stamped upstream (local CP or hosted ingress), never here.
+ */
+export declare function dispatchPagerDutyWebhook(input: {
+    options: PagerDutyChannelOptions;
+    delivery: PagerDutyWebhookDelivery;
+    args: ChannelHandlerArgs;
+}): Promise<Response>;
+/**
+ * HTTP entry for one agent's PagerDuty channel: the `X-PagerDuty-Signature`
+ * check when a secret is configured, then {@link dispatchPagerDutyWebhook}.
+ * Without a secret the route auth owns admission (`serve --dev` admits
+ * loopback only; production stays loopback-strict).
+ */
+export declare function handlePagerDutyWebhookRequest(input: {
+    options: PagerDutyChannelOptions;
+    request: Request;
+    args: ChannelHandlerArgs;
+}): Promise<Response>;
+//# sourceMappingURL=pagerduty-webhook.d.ts.map

package/dist/channels/pagerduty/pagerduty-webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagerduty-webhook.d.ts","sourceRoot":"","sources":["../../../src/channels/pagerduty/pagerduty-webhook.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAiC,MAAM,gBAAgB,CAAC;AA0BxF,OAAO,KAAK,EACV,uBAAuB,EAEvB,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AACvE,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAChD,0EAA0E;AAC1E,eAAO,MAAM,6BAA6B,MAAM,CAAC;AAEjD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,eAAe,CAAC,GACtD,MAAM,GAAG,SAAS,CAEpB;AAED,oEAAoE;AACpE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAYV;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,CAAC,EACzC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,wBAAwB,GAAG,IAAI,CAO9F;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,wBAAwB,GACjC,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC,GAAG,IAAI,CAmBjF;AA+DD;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,OAAO,EAAE,uBAAuB,CAAC;IACjC,QAAQ,EAAE,wBAAwB,CAAC;IACnC,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2FpB;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,KAAK,EAAE;IACzD,OAAO,EAAE,uBAAuB,CAAC;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkCpB"}