npm - @cursor/july - Versions diffs - 0.1.74 → 0.1.76 - Mend

@cursor/july 0.1.74 → 0.1.76

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (140) hide show

package/dist/channels/checks.d.ts +111 -0
package/dist/channels/checks.d.ts.map +1 -0
package/dist/channels/checks.js +86 -0
package/dist/channels/deployments/deployments-channel.d.ts +44 -0
package/dist/channels/deployments/deployments-channel.d.ts.map +1 -0
package/dist/channels/deployments/deployments-channel.js +92 -0
package/dist/channels/deployments/index.d.ts +26 -0
package/dist/channels/deployments/index.d.ts.map +1 -0
package/dist/channels/deployments/index.js +25 -0
package/dist/channels/deployments/types.d.ts +69 -0
package/dist/channels/deployments/types.d.ts.map +1 -0
package/dist/channels/deployments/types.js +6 -0
package/dist/channels/github/checks.d.ts +13 -48
package/dist/channels/github/checks.d.ts.map +1 -1
package/dist/channels/github/checks.js +56 -64
package/dist/channels/origin/api.d.ts +100 -0
package/dist/channels/origin/api.d.ts.map +1 -0
package/dist/channels/origin/api.js +225 -0
package/dist/channels/origin/binding.d.ts +44 -0
package/dist/channels/origin/binding.d.ts.map +1 -0
package/dist/channels/origin/binding.js +45 -0
package/dist/channels/origin/checks.d.ts +107 -0
package/dist/channels/origin/checks.d.ts.map +1 -0
package/dist/channels/origin/checks.js +145 -0
package/dist/channels/origin/index.d.ts +3 -0
package/dist/channels/origin/index.d.ts.map +1 -1
package/dist/channels/origin/index.js +3 -0
package/dist/channels/origin/origin-channel.d.ts +4 -4
package/dist/channels/origin/origin-channel.d.ts.map +1 -1
package/dist/channels/origin/origin-channel.js +12 -2
package/dist/channels/origin/types.d.ts +36 -0
package/dist/channels/origin/types.d.ts.map +1 -1
package/dist/channels.d.ts +1 -0
package/dist/channels.d.ts.map +1 -1
package/dist/channels.js +1 -0
package/dist/docs/404.html +2 -2
package/dist/docs/ab.html +3 -3
package/dist/docs/assets/{app.BETd-WqU.js → app.b8bhB2SV.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.DGZeXVqn.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.wEaGEmV9.js → VPLocalSearchBox.lLSeIyWw.js} +1 -1
package/dist/docs/assets/chunks/{theme.DNDicFOP.js → theme.C_owesa-.js} +2 -2
package/dist/docs/assets/{reference_channels.md.MN8iDy8V.js → reference_channels.md.G5GysZ7e.js} +2 -2
package/dist/docs/assets/{reference_channels.md.MN8iDy8V.lean.js → reference_channels.md.G5GysZ7e.lean.js} +1 -1
package/dist/docs/building-with-agents.html +3 -3
package/dist/docs/concepts.html +3 -3
package/dist/docs/deployment.html +3 -3
package/dist/docs/evals.html +3 -3
package/dist/docs/example-agents/approval-buddy.html +3 -3
package/dist/docs/example-agents/benny.html +3 -3
package/dist/docs/example-agents/bugbot.html +3 -3
package/dist/docs/example-agents/codebase-wiki.html +3 -3
package/dist/docs/example-agents/codeowners-review.html +3 -3
package/dist/docs/example-agents/concierge.html +3 -3
package/dist/docs/example-agents/fsd.html +3 -3
package/dist/docs/example-agents/index.html +3 -3
package/dist/docs/example-agents/knowledge-base.html +3 -3
package/dist/docs/example-agents/oncall.html +3 -3
package/dist/docs/example-agents/security-reviewer.html +3 -3
package/dist/docs/example-agents/slack-agent.html +3 -3
package/dist/docs/example-agents/weather-agent.html +3 -3
package/dist/docs/guides/agent-to-agent.html +3 -3
package/dist/docs/guides/cloud-runtime.html +3 -3
package/dist/docs/guides/convert-automation.html +3 -3
package/dist/docs/guides/github.html +3 -3
package/dist/docs/guides/human-in-the-loop.html +3 -3
package/dist/docs/guides/mcp-oauth.html +3 -3
package/dist/docs/guides/opentelemetry.html +3 -3
package/dist/docs/guides/slack.html +3 -3
package/dist/docs/guides/webhooks.html +3 -3
package/dist/docs/hashmap.json +1 -1
package/dist/docs/hillclimbing.html +3 -3
package/dist/docs/index.html +3 -3
package/dist/docs/quickstart.html +3 -3
package/dist/docs/reference/agent-config.html +3 -3
package/dist/docs/reference/artifacts.html +3 -3
package/dist/docs/reference/channels.html +5 -5
package/dist/docs/reference/cli.html +3 -3
package/dist/docs/reference/connections.html +3 -3
package/dist/docs/reference/hooks.html +3 -3
package/dist/docs/reference/http-api.html +3 -3
package/dist/docs/reference/instructions.html +3 -3
package/dist/docs/reference/playground.html +3 -3
package/dist/docs/reference/project-layout.html +3 -3
package/dist/docs/reference/prompt.html +3 -3
package/dist/docs/reference/schedules.html +3 -3
package/dist/docs/reference/sessions.html +3 -3
package/dist/docs/reference/skills.html +3 -3
package/dist/docs/reference/subagents.html +3 -3
package/dist/docs/reference/tools.html +3 -3
package/dist/docs/scaffolding-agents.html +3 -3
package/dist/docs/storage.html +3 -3
package/dist/docs/templates/agentic-owners.html +3 -3
package/dist/docs/templates/demo.html +3 -3
package/dist/docs/templates/pr-autofixer.html +3 -3
package/dist/docs/templates/security-reviewer.html +3 -3
package/dist/docs/templates/triage.html +3 -3
package/dist/docs/troubleshooting.html +3 -3
package/dist/internal/authored-alias-hooks.d.ts +12 -0
package/dist/internal/authored-alias-hooks.d.ts.map +1 -1
package/dist/internal/authored-alias-hooks.js +60 -8
package/dist/internal/authored-loaders.d.ts +5 -3
package/dist/internal/authored-loaders.d.ts.map +1 -1
package/dist/internal/authored-loaders.js +13 -4
package/dist/internal/cursor-deployment-relay.d.ts +77 -0
package/dist/internal/cursor-deployment-relay.d.ts.map +1 -0
package/dist/internal/cursor-deployment-relay.js +201 -0
package/dist/internal/deployment-scm-event-stream.js +4 -4
package/dist/internal/distribution.d.ts.map +1 -1
package/dist/internal/distribution.js +1 -0
package/dist/internal/review-comments.d.ts +62 -0
package/dist/internal/review-comments.d.ts.map +1 -1
package/dist/internal/review-comments.js +199 -0
package/dist/internal/server.d.ts.map +1 -1
package/dist/internal/server.js +114 -5
package/dist/playground/assets/{index-D_8I9TM0.js → index-BWqjJcRo.js} +1 -1
package/dist/playground/assets/index-Bfwz2yLN.css +1 -0
package/dist/playground/index.html +2 -2
package/docs/reference/channels.md +15 -0
package/package.json +7 -1
package/src/channels/checks.ts +185 -0
package/src/channels/deployments/deployments-channel.ts +109 -0
package/src/channels/deployments/index.ts +26 -0
package/src/channels/deployments/types.ts +80 -0
package/src/channels/github/checks.ts +90 -115
package/src/channels/origin/api.ts +318 -0
package/src/channels/origin/binding.ts +96 -0
package/src/channels/origin/checks.ts +250 -0
package/src/channels/origin/index.ts +3 -0
package/src/channels/origin/origin-channel.ts +18 -6
package/src/channels/origin/types.ts +37 -0
package/src/channels.ts +16 -0
package/src/internal/authored-alias-hooks.ts +75 -7
package/src/internal/authored-loaders.ts +15 -4
package/src/internal/cursor-deployment-relay.ts +274 -0
package/src/internal/deployment-scm-event-stream.ts +4 -4
package/src/internal/distribution.ts +1 -0
package/src/internal/review-comments.ts +286 -0
package/src/internal/server.ts +149 -0
package/dist/docs/assets/chunks/@localSearchIndexroot.DM5INS71.js +0 -1
package/dist/playground/assets/index-M3nSMc6_.css +0 -1

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-D_8I9TM0.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-M3nSMc6_.css">
+    <script type="module" crossorigin src="./assets/index-BWqjJcRo.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-Bfwz2yLN.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/reference/channels.md CHANGED Viewed

@@ -217,6 +217,21 @@ replay and live forwarding. Author `agent/channels/github.ts` with
 converge a merge-box check and sticky PR comment from default stream
 events. Guide: [GitHub](../guides/github.md).
+**Deployments** (`@cursor/july/channels/deployments`): pull transport
+over `/v0/deployment-events`. Subscribe per repository with `repos`,
+narrow with `environments` / `events`, and handle each event in
+`onEvent`. `repos` must match `Deployment.repository` as your deployment
+writer records it; the field has no format, and matching is
+case-insensitive but otherwise literal.
+Author `agent/channels/deployments.ts` with `deploymentsChannel()`. The
+serve host discovers every mounted deployments channel, runs one relay
+for the process against the union of their repositories, and routes each
+event to the channels that asked for it — the same ownership the Slack
+and SCM relays have. It authenticates with the host credential and keeps
+a durable offset, so a restart resumes rather than dropping events. An
+empty `repos` list mounts the channel but starts no relay for it, so an
+env-configured agent stays inert until its repositories are set.
 For other platforms like Discord or Teams, use the authored
 `defineChannel` webhook form.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.74",
+  "version": "0.1.76",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -77,6 +77,12 @@
       "import": "./dist/channels/origin/index.js",
       "default": "./dist/channels/origin/index.js"
     },
+    "./channels/deployments": {
+      "anysphere-source": "./src/channels/deployments/index.ts",
+      "types": "./dist/channels/deployments/index.d.ts",
+      "import": "./dist/channels/deployments/index.js",
+      "default": "./dist/channels/deployments/index.js"
+    },
     "./skills": {
       "anysphere-source": "./src/skills.ts",
       "types": "./dist/skills.d.ts",

package/src/channels/checks.ts ADDED Viewed

@@ -0,0 +1,185 @@
+/**
+ * CI checks, shared across SCMs.
+ *
+ * The check lifecycle lives here once: `openCiCheck` opens a run (defaults
+ * `in_progress`, stamps `startedAt`), the returned {@link CiCheck} handle
+ * patches it (`update`) and completes it (`conclude`, stamps `completedAt`),
+ * and `resumeCiCheck` rebuilds a handle after a restart. Each SCM plugs in
+ * with one {@link CiCheckWriter} — a function that persists a single desired
+ * check state on its API (GitHub Checks API create/patch, Origin's keyed
+ * upsert, …) and owns any transport state such as a server-assigned run id.
+ *
+ * Agent code should usually stay one level higher, on {@link CiChecksClient}:
+ * both `ctx.github` and `ctx.origin` satisfy it, so a check reporter written
+ * once works on either forge:
+ *
+ * ```ts
+ * async function reportCheck(checks: CiChecksClient, sha: string) {
+ *   const check = await checks.createCheck({ name: "My Agent", sha });
+ *   // …do the work…
+ *   await check.conclude({
+ *     conclusion: "success",
+ *     output: { title: "Done", summary: "All good." },
+ *   });
+ * }
+ * ```
+ *
+ * {@link CiCheckConclusion} is the common subset every SCM accepts; an SCM
+ * with extras widens it through the generic parameter (e.g. Origin's
+ * `CiCheck<CiCheckConclusion | "stale">`).
+ */
+/** Output shown on the check page. */
+export interface CiCheckOutput {
+  /** Heading on the check page. */
+  title: string;
+  /** Markdown body (supports links, e.g. `[View session](…)`). */
+  summary: string;
+  /** Optional detailed markdown body. */
+  text?: string;
+}
+export type CiCheckStatus = "queued" | "in_progress" | "completed";
+/** Final results accepted by every SCM. */
+export type CiCheckConclusion =
+  | "action_required"
+  | "cancelled"
+  | "failure"
+  | "neutral"
+  | "skipped"
+  | "success"
+  | "timed_out";
+export interface CiCheckUpdateInput<
+  TConclusion extends string = CiCheckConclusion,
+> {
+  status?: CiCheckStatus;
+  conclusion?: TConclusion;
+  detailsUrl?: string;
+  output?: CiCheckOutput;
+}
+export interface CiCheckConcludeInput<
+  TConclusion extends string = CiCheckConclusion,
+> {
+  /** Final result shown in the merge box. */
+  conclusion: TConclusion;
+  detailsUrl?: string;
+  output?: CiCheckOutput;
+}
+/** SCM-side reference to a check run, when the SCM reports one. */
+export interface CiCheckRef {
+  /** Server-assigned run id (GitHub check-run number, Origin `cr_…`). */
+  id?: number | string;
+  /** Web URL of the check run page. */
+  url?: string;
+}
+/** A created check run, whichever SCM it lives on. */
+export interface CiCheck<TConclusion extends string = CiCheckConclusion> {
+  /** Patch status / output / details link while the check is running. */
+  update(input: CiCheckUpdateInput<TConclusion>): Promise<void>;
+  /** Complete the check with a conclusion (stamps `completedAt`). */
+  conclude(input: CiCheckConcludeInput<TConclusion>): Promise<void>;
+}
+export interface CiCheckCreateInput {
+  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
+  name: string;
+  /** Commit the check attaches to (usually the PR head SHA). */
+  sha: string;
+  /** Initial status. Defaults to `"in_progress"`. */
+  status?: "queued" | "in_progress";
+  /** "Details" link on the check, e.g. the agent session run URL. */
+  detailsUrl?: string;
+  /** Title + markdown summary shown on the check page. */
+  output?: CiCheckOutput;
+}
+/**
+ * Anything that can open a CI check on its bound repository — `ctx.github`,
+ * `ctx.origin`, or the `bindOriginChecks` adapter.
+ */
+export interface CiChecksClient<
+  TConclusion extends string = CiCheckConclusion,
+> {
+  createCheck(input: CiCheckCreateInput): Promise<CiCheck<TConclusion>>;
+}
+/** One desired check state for a writer to persist. */
+export interface CiCheckWrite<TConclusion extends string = CiCheckConclusion>
+  extends CiCheckUpdateInput<TConclusion> {
+  startedAt?: string;
+  completedAt?: string;
+}
+/**
+ * The per-SCM extension point: persist one {@link CiCheckWrite} on the SCM
+ * (create-then-patch, keyed upsert, …). Bound to a repo + check identity at
+ * construction; owns transport state (e.g. the created run id) across calls.
+ * May return a {@link CiCheckRef} to expose on the handle.
+ */
+export type CiCheckWriter<TConclusion extends string = CiCheckConclusion> = (
+  write: CiCheckWrite<TConclusion>
+) => Promise<CiCheckRef | undefined>;
+/**
+ * Open a check run through `writer` and return a handle for later updates.
+ * SCM modules wrap this (`createGitHubCheck`, `createOriginCheck`); channels
+ * expose it repo-bound as `ctx.github.createCheck` / `ctx.origin.createCheck`.
+ */
+export async function openCiCheck<
+  TConclusion extends string = CiCheckConclusion,
+>(
+  writer: CiCheckWriter<TConclusion>,
+  input?: Pick<CiCheckCreateInput, "status" | "detailsUrl" | "output">
+): Promise<CiCheck<TConclusion> & CiCheckRef> {
+  const ref = await writer({
+    status: input?.status ?? "in_progress",
+    startedAt: new Date().toISOString(),
+    detailsUrl: input?.detailsUrl,
+    output: input?.output,
+  });
+  return resumeCiCheck(writer, ref);
+}
+/**
+ * Rebuild a {@link CiCheck} handle around an existing run (e.g. after a
+ * process restart). No write happens until the first update.
+ */
+export function resumeCiCheck<TConclusion extends string = CiCheckConclusion>(
+  writer: CiCheckWriter<TConclusion>,
+  ref?: CiCheckRef
+): CiCheck<TConclusion> & CiCheckRef {
+  let id = ref?.id;
+  let url = ref?.url;
+  const write = async (write: CiCheckWrite<TConclusion>): Promise<void> => {
+    const next = await writer(write);
+    id = next?.id ?? id;
+    url = next?.url ?? url;
+  };
+  return {
+    get id() {
+      return id;
+    },
+    get url() {
+      return url;
+    },
+    update: (update) =>
+      write({
+        ...update,
+        completedAt:
+          update.status === "completed" ? new Date().toISOString() : undefined,
+      }),
+    conclude: (conclude) =>
+      write({
+        status: "completed",
+        conclusion: conclude.conclusion,
+        completedAt: new Date().toISOString(),
+        detailsUrl: conclude.detailsUrl,
+        output: conclude.output,
+      }),
+  };
+}

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

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { defineChannel, localDevStrict, POST } from "../../channels.js";
+import { resolveDeploymentSubscriptions } from "../../internal/cursor-deployment-relay.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(),
+  repo: z.string().min(1),
+  deploymentId: z.string().min(1),
+  environment: z.string().min(1),
+  service: z.string().min(1).optional(),
+  sha: z.string().min(1),
+  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);
+}
+/**
+ * Core deployment-event dispatch, used by the channel's replay route and by
+ * the serve host's relay fan-out. 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, input.args);
+  return Response.json({ ok: true });
+}
+/**
+ * Deployment events channel.
+ *
+ * ```ts
+ * import { deploymentsChannel } from "@cursor/july/channels/deployments";
+ *
+ * export default deploymentsChannel({
+ *   repos: ["repos/anysphere/everysphere"], // as your writer records it
+ *   environments: ["prod"],
+ *   onEvent: async (event, { send }) => {
+ *     await send(`${event.repo}@${event.sha} 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.
+ *
+ * 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 `repos` 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 },
+    ...(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);
+  return definition;
+}

package/src/channels/deployments/index.ts ADDED Viewed

@@ -0,0 +1,26 @@
+/**
+ * Deployment events channel pack for agent-serve.
+ *
+ * ```ts
+ * import { deploymentsChannel } from "@cursor/july/channels/deployments";
+ *
+ * export default deploymentsChannel({
+ *   repos: ["repos/anysphere/everysphere"], // as your writer records it
+ *   environments: ["prod"],
+ *   onEvent: (event, { send }) => send(`${event.sha} 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 ADDED Viewed

@@ -0,0 +1,80 @@
+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",
+] 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 repository string, case-folded. */
+  repo: string;
+  deploymentId: string;
+  /** Environment slug, e.g. `prod`. */
+  environment: string;
+  /** Absent when the deployment records no service. */
+  service?: string;
+  sha: string;
+  status: DeploymentStatus;
+  occurredAtMs: number;
+}
+/** What a repository subscription asks for. */
+export interface DeploymentSubscription {
+  /**
+   * The repository string as the factory records it on a Deployment. Opaque:
+   * whatever your deployment writer puts there, matched case-insensitively.
+   */
+  repo: string;
+  /** Omit or leave empty for every environment. */
+  environments?: readonly string[];
+  /** Defaults to `deployment.succeeded`. */
+  events?: readonly DeploymentEventType[];
+}
+export interface DeploymentsChannelOptions {
+  /**
+   * Repositories to watch, spelled exactly as your deployment writer records
+   * `Deployment.repository`. 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.
+   *
+   * There is no team-wide subscription: every repository is named. At least
+   * one is required — an empty list is how a consumer *deregisters*, so it
+   * cannot also mean "everything".
+   */
+  repos: 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"];
+}