@cursor/bdk 0.2.3 → 0.2.5

package/src/channels/deployments/deployments-channel.ts

@@ -1,224 +0,0 @@
-import { z } from "zod";
-
-import { defineChannel, localDevStrict, POST } from "../../channels.js";
-import { skipped, tagOutcome } from "../../internal/channel-dispatch.js";
-import {
-  deploymentEventMatches,
-  resolveDeploymentSubscriptions,
-} from "../../internal/cursor-deployment-relay.js";
-import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
-import { bindLocalIngressSend } from "../../internal/local-ingress.js";
-import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
-import {
-  DEPLOYMENT_EVENT_TYPES,
-  DEPLOYMENTS_CHANNEL_KIND,
-  type DeploymentEvent,
-  type DeploymentsChannelOptions,
-} from "./types.js";
-
-const deploymentEventSchema = z.object({
-  eventType: z.enum(DEPLOYMENT_EVENT_TYPES),
-  eventId: z.string().min(1),
-  teamId: z.number(),
-  deploySourceUri: z.string().min(1),
-  deploymentId: z.string().min(1),
-  environment: z.string().min(1),
-  service: z.string().min(1).optional(),
-  deployVersion: z.string().min(1),
-  previousVersion: z.string().min(1).optional(),
-  status: z.enum(["pending", "in_progress", "success", "failed"]),
-  occurredAtMs: z.number(),
-});
-
-/** Options used to construct a deployments channel — for host-level fan-out. */
-const deploymentsChannelOptionsByDefinition = new WeakMap<object, DeploymentsChannelOptions>();
-
-/**
- * Recover the {@link DeploymentsChannelOptions} used to build a channel
- * definition, if it was created via {@link deploymentsChannel}.
- */
-export function getDeploymentsChannelOptions(
-  definition: object,
-): DeploymentsChannelOptions | undefined {
-  return deploymentsChannelOptionsByDefinition.get(definition);
-}
-
-/**
- * Events a {@link deploymentsChannel} dispatches on, unioned from its
- * subscriptions. Published as `meta.deploymentEventTypes` so the deploy
- * manifest can extract `eventTypes`.
- *
- * A channel with no resolved subscriptions declares the full event set.
- * That covers an omitted `deploySourceUris` and the env-configured case:
- * the hosted freeze bakes hermetically (no customer env/secrets), so
- * deriving `[]` there would leave the manifest without event types and no
- * subscription edge could ever materialize (invariant 26). Capability is
- * the channel's code shape — `onEvent` handles any deployment event —
- * while sources/environments/event narrowing are runtime subscription
- * config; the hosted-admission adapter re-applies them before authored
- * code runs. Inertness is still guaranteed by scope: a deploy that names
- * no repositories binds no edges.
- */
-export function deriveDeploymentEventTypes(
-  options: Pick<DeploymentsChannelOptions, "deploySourceUris" | "events">,
-): string[] {
-  const subscriptions = resolveDeploymentSubscriptions(options);
-  if (subscriptions.length === 0) {
-    return [...DEPLOYMENT_EVENT_TYPES].sort();
-  }
-  const events = new Set<string>();
-  for (const subscription of subscriptions) {
-    for (const event of subscription.events) {
-      events.add(event);
-    }
-  }
-  return [...events].sort();
-}
-
-/**
- * Core deployment-event dispatch, used by the channel's replay route, the
- * serve host's relay fan-out, and the hosted-admission adapter. Whether the
- * event matches this channel's subscriptions is the caller's decision.
- */
-export async function dispatchDeploymentEvent(input: {
-  options: DeploymentsChannelOptions;
-  event: DeploymentEvent;
-  args: ChannelHandlerArgs;
-}): Promise<Response> {
-  await input.options.onEvent(
-    input.event,
-    bindLocalIngressSend(input.args, {
-      identity: input.options.continuation,
-      kind: DEPLOYMENTS_CHANNEL_KIND,
-      eventType: input.event.eventType,
-      payload: input.event,
-    }),
-  );
-  // "task": authored `onEvent` ran to completion without a captured send.
-  // Hosted admission only consults this when no send was captured.
-  return tagOutcome(Response.json({ ok: true }), "task");
-}
-
-/**
- * Whether this channel admits the event on a hosted pod. The hosted
- * control plane fans out on `(deploy_source, eventType, team)` edges only —
- * environments are not edge identity — so this is where the environment
- * filter (and a stale-edge guard for sources/events) lives, mirroring what
- * the v1 relay does before `onEvent`.
- *
- * A channel with NO resolved subscriptions admits everything the control
- * plane delivered. Omitting `deploySourceUris` picks that deliberately:
- * the deploy-time edges (bound from the watched repositories) already
- * carry the tenant's scope, so re-filtering here could only narrow it with
- * another tenant's list. The same holds for an env-configured channel that
- * resolves empty on a restored pod, where refusing would silently drop
- * every delivery. Same rule as {@link deriveDeploymentEventTypes}:
- * authored subscriptions narrow; a channel that names none defers to the
- * deploy scope.
- */
-export function deploymentEventMatchesChannel(
-  options: DeploymentsChannelOptions,
-  event: DeploymentEvent,
-): boolean {
-  const subscriptions = resolveDeploymentSubscriptions(options);
-  if (subscriptions.length === 0) {
-    return true;
-  }
-  return subscriptions.some(
-    subscription =>
-      subscription.deploySourceUri === event.deploySourceUri.toLowerCase() &&
-      deploymentEventMatches(subscription, event),
-  );
-}
-
-/**
- * Deployment events channel.
- *
- * ```ts
- * import { deploymentsChannel } from "@cursor/bdk/channels/deployments";
- *
- * export default deploymentsChannel({
- *   deploySourceUris: ["https://origin.cursor.com/repos/anysphere/everysphere"],
- *   environments: ["prod"],
- *   onEvent: async (event, { send }) => {
- *     await send(`${event.deploySourceUri}@${event.deployVersion} shipped to ${event.environment}`);
- *   },
- * });
- * ```
- *
- * Declarative: the channel names what it wants and handles what arrives. The
- * serve host discovers every mounted deployments channel, opens one
- * `/v0/deployment-events` relay for the process, and routes each event to the
- * channels subscribed to it — the same ownership the Slack and SCM relays
- * have. Nothing is pushed to this deployment and no shared secret exists on
- * either side.
- *
- * Hosted v2 deployments do not poll: the control plane fans verified factory
- * deployment events out on `deploy_source` subscription edges — derived from
- * the deploy's watched `repositories`, since factory records deploy sources
- * as Origin repo URLs — and delivers through hosted admission. The attached
- * adapter re-applies this channel's subscription filter — environments are
- * not edge identity — and skips before authored code runs.
- *
- * A hosted agent therefore omits `deploySourceUris`:
- *
- * ```ts
- * export default deploymentsChannel({
- *   events: ["deployment.created", "deployment.succeeded"],
- *   onEvent: async (event, { send }) => { ... },
- * });
- * ```
- *
- * The route on this channel exists for local replay (`agent-sdk` and tests):
- * POST an event body and it runs the same `onEvent`.
- */
-export function deploymentsChannel(options: DeploymentsChannelOptions): ChannelDefinition {
-  // Throws here rather than at startup, so a malformed `deploySourceUris`
-  // entry fails when the channel module is authored instead of when the host
-  // mounts it.
-  resolveDeploymentSubscriptions(options);
-  const routePath = options.path ?? "/";
-
-  const definition = defineChannel({
-    auth: options.auth ?? [localDevStrict()],
-    meta: {
-      kind: DEPLOYMENTS_CHANNEL_KIND,
-      deploymentEventTypes: deriveDeploymentEventTypes(options),
-    },
-    ...(options.onStart === undefined ? {} : { onStart: options.onStart }),
-    ...(options.onStop === undefined ? {} : { onStop: options.onStop }),
-    routes: [
-      POST(routePath, {
-        description: "Replay one deployment event onto this channel",
-        bodySchema: deploymentEventSchema,
-        handler: async (_request, args) =>
-          dispatchDeploymentEvent({
-            options,
-            event: args.body as DeploymentEvent,
-            args,
-          }),
-      }),
-    ],
-  });
-  deploymentsChannelOptionsByDefinition.set(definition, options);
-  // Hosted v2 delivery: the control plane admits a deployments mailbox item
-  // (deploy_source edge match) and posts the claim-checked factory envelope
-  // here. Environments are not edge identity, so non-matching environments
-  // (and stale-edge sources/events) are filtered to `skip` before authored
-  // code runs — the same pre-`onEvent` filter the v1 relay applies.
-  attachHostedAdmissionAdapter(definition, {
-    kind: DEPLOYMENTS_CHANNEL_KIND,
-    dispatch: async ({ payload, args }) => {
-      const parsed = deploymentEventSchema.safeParse(payload);
-      if (!parsed.success) {
-        return Response.json({ ok: false, error: "invalid_deployment_event" }, { status: 400 });
-      }
-      const event = parsed.data as DeploymentEvent;
-      if (!deploymentEventMatchesChannel(options, event)) {
-        return skipped("subscription_mismatch");
-      }
-      return dispatchDeploymentEvent({ options, event, args });
-    },
-  });
-  return definition;
-}

package/src/channels/deployments/index.ts

@@ -1,25 +0,0 @@
-/**
- * Deployment events channel pack for agent-serve.
- *
- * ```ts
- * import { deploymentsChannel } from "@cursor/bdk/channels/deployments";
- *
- * export default deploymentsChannel({
- *   deploySourceUris: ["https://origin.cursor.com/repos/anysphere/everysphere"],
- *   onEvent: (event, { send }) => send(`${event.deployVersion} shipped`),
- * });
- * ```
- *
- * The serve host owns the transport, as it does for Slack and SCM events: it
- * discovers every mounted deployments channel, opens one `/v0/deployment-events`
- * relay for the process with the host's Cursor credential, and routes each
- * event to the channels subscribed to it. The relay long-polls with a durable
- * client-owned offset, so a restart resumes rather than dropping events.
- *
- * An agent whose sessions live on another channel forwards from `onEvent`
- * into that channel rather than starting sessions here, the way a GitHub
- * relay channel dispatches into an origin channel.
- */
-
-export * from "./deployments-channel.js";
-export * from "./types.js";

package/src/channels/deployments/types.ts

@@ -1,92 +0,0 @@
-import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
-import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
-
-/** {@link ChannelMeta.kind} value used by {@link deploymentsChannel}. */
-export const DEPLOYMENTS_CHANNEL_KIND = "deployments";
-
-export const DEPLOYMENT_EVENT_TYPES = [
-  "deployment.created",
-  "deployment.succeeded",
-  "deployment.failed",
-] as const;
-export type DeploymentEventType = (typeof DEPLOYMENT_EVENT_TYPES)[number];
-
-export type DeploymentStatus = "pending" | "in_progress" | "success" | "failed";
-
-/** One deployment event, as the control plane records it. */
-export interface DeploymentEvent {
-  eventType: DeploymentEventType;
-  /** Stable id; dedupe on it if you act more than once per event. */
-  eventId: string;
-  /** Owning Cursor team. */
-  teamId: number;
-  /** The Deployment's deploy_source_uri string, case-folded. */
-  deploySourceUri: string;
-  deploymentId: string;
-  /** Environment slug, e.g. `prod`. */
-  environment: string;
-  /** Absent when the deployment records no service. */
-  service?: string;
-  deployVersion: string;
-  /** Last succeeded different SHA; omitted on the first ship. */
-  previousVersion?: string;
-  status: DeploymentStatus;
-  occurredAtMs: number;
-}
-
-/** What a deploy-source subscription asks for. */
-export interface DeploymentSubscription {
-  /**
-   * The deploy-source URI as the factory records it on a Deployment. Opaque:
-   * whatever your deployment writer puts there, matched case-insensitively.
-   */
-  deploySourceUri: string;
-  /** Omit or leave empty for every environment. */
-  environments?: readonly string[];
-  /** Defaults to `deployment.succeeded`. */
-  events?: readonly DeploymentEventType[];
-}
-
-export interface DeploymentsChannelOptions {
-  /**
-   * Deploy sources to watch, spelled exactly as your deployment writer records
-   * `Deployment.deploy_source_uri`. The field has no format — whatever the
-   * writer puts there is the key — and matching is case-insensitive but
-   * otherwise literal, so a value that does not match subscribes successfully
-   * and then receives nothing. A bare string takes the default environment and
-   * event filters.
-   *
-   * Omit on Cursor-managed hosting. The control plane binds sources from the
-   * deployment's watched repositories, and the channel admits only what it
-   * receives. An agent cannot enumerate sources for an unseen tenant.
-   *
-   * Name sources to narrow below that scope, or to drive the self-hosted
-   * relay, which has no deploy scope to inherit. On that wire `[]` means
-   * deregister, which is why deferring to the deploy scope is an omitted
-   * field and not an empty one. A live array that starts empty and is filled
-   * later is re-read on each registration heartbeat.
-   */
-  deploySourceUris?: readonly (string | DeploymentSubscription)[];
-  /**
-   * Applied to every subscription that does not set its own. Omit or leave
-   * empty for every environment.
-   */
-  environments?: readonly string[];
-  /**
-   * Applied to every subscription that does not set its own. Defaults to
-   * `deployment.succeeded`.
-   */
-  events?: readonly DeploymentEventType[];
-  /** Called for each matching event. Failures retry a few times, then skip. */
-  onEvent: (event: DeploymentEvent, args: ChannelHandlerArgs) => Promise<unknown> | unknown;
-  /** Route path for the local replay POST. Defaults to `/`. */
-  path?: string;
-  auth?: ChannelDefinition["auth"];
-  onStart?: ChannelDefinition["onStart"];
-  onStop?: ChannelDefinition["onStop"];
-  /**
-   * Continuation selector. Omit this to inherit the agent architecture's
-   * default. Set it explicitly only when migrating persisted identities.
-   */
-  continuation?: ContinuationIdentity;
-}