@cursor/july 0.1.73 → 0.1.75

package/AGENTS.md

@@ -22,8 +22,8 @@ Any PR that changes this package's **source** (`src/`, `playground/`,
 CLI, shipped `skills/` / `templates/` — runtime behavior that goes out
 in `@cursor/july`) **must bump** `version` in `package.json` in the
 **same PR**. On 0.x, bump the patch (`0.1.N` → `0.1.N+1`). Do not
-publish from the PR; merging the bump is what lets the `july-release`
-pipeline cut. Docs-only, tests-only, and edits to this file do not
+publish from the PR; merging the bump to `main` auto-triggers
+`july-release`. Docs-only, tests-only, and edits to this file do not
 need a bump.
 
 ## Skills
@@ -31,7 +31,9 @@ need a bump.
 Before scaffolding, wiring channels, writing evals, or deploying, **read the
 matching skill under `skills/<task>/SKILL.md`** (paths
 below are relative to this package). Those files ship with `@cursor/july`.
-Open them directly — there are no `.cursor/skills/` stubs for authoring.
+Cloud agents get the same published skills (except `operate`) via
+`GetManagedSkills`, which reads these files. Open them directly — there
+are no `.cursor/skills/` stubs for authoring.
 
 | Skill | Read it when |
 | --- | --- |
@@ -155,11 +157,14 @@ export default defineEvalConfig({
 - `init` with no directory prints this setup guide (does not scaffold).
   `init <dir>` scaffolds (skipping existing files), runs `npm install`,
   offers to install/update package skills into
-  `~/.cursor/skills/agentkit/` (TTY only; always overwrites with the
-  package copy), links `agent-sdk` onto the npm global bin (so bare
-  `agent-sdk` works on PATH), runs `login` and waits when unsigned, then
-  prints `cd` (when needed) and `agent-sdk dev`. `--json` still installs but never blocks
-  on login or skill install; it prints
+  `~/.cursor/skills/agentsdk/` (TTY only; always overwrites with the
+  package copy, with `alwaysApply: true` so Cursor injects them).
+  Consumer installs already copy those skills in postinstall; the
+  source checkout does not. Links `agent-sdk` onto the
+  npm global bin (so bare `agent-sdk` works on PATH), runs `login` and
+  waits when unsigned, then prints `cd` (when needed) and `agent-sdk dev`.
+  `--json` still installs but never blocks on login or skill install; it
+  prints
   `{ ok, directory, created, skipped, installed, installError, cliOnPath, cliLinkError, next }`.
 - `chat --json --message "..."` talks to a running server and prints a trajectory.
 

package/dist/bin/agent-serve.js

@@ -181,11 +181,13 @@ Commands:
               -> MCP). Review the project, then run \`validate\` / \`dev\`.
               Warnings never fail the command.
   install-skills
-              Install (or refresh) the Agent SDK skills for coding agents in
-              ~/.cursor/skills/agentkit and print where they landed. \`init\`
-              offers this once, interactively, and skips it when the prompt
-              goes unanswered; this command never asks. --print previews
-              without writing.
+              Refresh the Agent SDK skills for coding agents in
+              ~/.cursor/skills/agentsdk and print where they landed.
+              Installed copies set alwaysApply so Cursor injects them
+              into context. \`npm install\` / \`npx\` already copies them
+              (postinstall); this command overwrites with the package
+              version without asking. \`init\` also offers a TTY refresh.
+              --print previews without writing.
   mcp         Serve this agent's MCP endpoint over stdio for MCP clients
               that spawn local servers (e.g. Cursor). Proxies
               newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves

package/dist/channels/checks.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 declare function openCiCheck<TConclusion extends string = CiCheckConclusion>(writer: CiCheckWriter<TConclusion>, input?: Pick<CiCheckCreateInput, "status" | "detailsUrl" | "output">): Promise<CiCheck<TConclusion> & CiCheckRef>;
+/**
+ * Rebuild a {@link CiCheck} handle around an existing run (e.g. after a
+ * process restart). No write happens until the first update.
+ */
+export declare function resumeCiCheck<TConclusion extends string = CiCheckConclusion>(writer: CiCheckWriter<TConclusion>, ref?: CiCheckRef): CiCheck<TConclusion> & CiCheckRef;
+//# sourceMappingURL=checks.d.ts.map

package/dist/channels/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../src/channels/checks.ts"],"names":[],"mappings":"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"}

package/dist/channels/checks.js

@@ -0,0 +1,86 @@
+/**
+ * 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">`).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * 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 function openCiCheck(writer, input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const ref = yield writer({
+            status: (_a = input === null || input === void 0 ? void 0 : input.status) !== null && _a !== void 0 ? _a : "in_progress",
+            startedAt: new Date().toISOString(),
+            detailsUrl: input === null || input === void 0 ? void 0 : input.detailsUrl,
+            output: input === null || input === void 0 ? void 0 : 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(writer, ref) {
+    let id = ref === null || ref === void 0 ? void 0 : ref.id;
+    let url = ref === null || ref === void 0 ? void 0 : ref.url;
+    const write = (write) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const next = yield writer(write);
+        id = (_a = next === null || next === void 0 ? void 0 : next.id) !== null && _a !== void 0 ? _a : id;
+        url = (_b = next === null || next === void 0 ? void 0 : next.url) !== null && _b !== void 0 ? _b : url;
+    });
+    return {
+        get id() {
+            return id;
+        },
+        get url() {
+            return url;
+        },
+        update: (update) => write(Object.assign(Object.assign({}, 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/dist/channels/deployments/deployments-channel.d.ts

@@ -0,0 +1,44 @@
+import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
+import { type DeploymentEvent, type DeploymentsChannelOptions } from "./types.js";
+/**
+ * Recover the {@link DeploymentsChannelOptions} used to build a channel
+ * definition, if it was created via {@link deploymentsChannel}.
+ */
+export declare function getDeploymentsChannelOptions(definition: object): DeploymentsChannelOptions | undefined;
+/**
+ * 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 declare function dispatchDeploymentEvent(input: {
+    options: DeploymentsChannelOptions;
+    event: DeploymentEvent;
+    args: ChannelHandlerArgs;
+}): Promise<Response>;
+/**
+ * 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 declare function deploymentsChannel(options: DeploymentsChannelOptions): ChannelDefinition;
+//# sourceMappingURL=deployments-channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deployments-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/deployments/deployments-channel.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAqBpB;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,GACjB,yBAAyB,GAAG,SAAS,CAEvC;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE;IACnD,OAAO,EAAE,yBAAyB,CAAC;IACnC,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAGpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,iBAAiB,CA0BnB"}

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

@@ -0,0 +1,92 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { z } from "zod";
+import { defineChannel, localDevStrict, POST } from "../../channels.js";
+import { resolveDeploymentSubscriptions } from "../../internal/cursor-deployment-relay.js";
+import { DEPLOYMENT_EVENT_TYPES, DEPLOYMENTS_CHANNEL_KIND, } 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();
+/**
+ * Recover the {@link DeploymentsChannelOptions} used to build a channel
+ * definition, if it was created via {@link deploymentsChannel}.
+ */
+export function getDeploymentsChannelOptions(definition) {
+    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 function dispatchDeploymentEvent(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield 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) {
+    var _a, _b;
+    // 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 = (_a = options.path) !== null && _a !== void 0 ? _a : "/";
+    const definition = defineChannel(Object.assign(Object.assign(Object.assign({ auth: (_b = options.auth) !== null && _b !== void 0 ? _b : [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: (_request, args) => __awaiter(this, void 0, void 0, function* () {
+                    return dispatchDeploymentEvent({
+                        options,
+                        event: args.body,
+                        args,
+                    });
+                }),
+            }),
+        ] }));
+    deploymentsChannelOptionsByDefinition.set(definition, options);
+    return definition;
+}

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

@@ -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";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/deployments/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC"}

package/dist/channels/deployments/index.js

@@ -0,0 +1,25 @@
+/**
+ * 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/dist/channels/deployments/types.d.ts

@@ -0,0 +1,69 @@
+import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
+/** {@link ChannelMeta.kind} value used by {@link deploymentsChannel}. */
+export declare const DEPLOYMENTS_CHANNEL_KIND = "deployments";
+export declare const DEPLOYMENT_EVENT_TYPES: readonly ["deployment.created", "deployment.succeeded"];
+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"];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/channels/deployments/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channels/deployments/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE5E,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,gBAAgB,CAAC;AAEtD,eAAO,MAAM,sBAAsB,YACjC,oBAAoB,EACpB,sBAAsB,CACd,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEhF,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,gBAAgB,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,0CAA0C;IAC1C,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;OAWG;IACH,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,sBAAsB,CAAC,EAAE,CAAC;IACpD;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,6EAA6E;IAC7E,OAAO,EAAE,CACP,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,kBAAkB,KACrB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAChC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;CACtC"}

package/dist/channels/deployments/types.js

@@ -0,0 +1,6 @@
+/** {@link ChannelMeta.kind} value used by {@link deploymentsChannel}. */
+export const DEPLOYMENTS_CHANNEL_KIND = "deployments";
+export const DEPLOYMENT_EVENT_TYPES = [
+    "deployment.created",
+    "deployment.succeeded",
+];

package/dist/channels/github/checks.d.ts

@@ -1,70 +1,35 @@
 /**
- * Generic CI checks (GitHub Checks API) for agent authors.
+ * GitHub CI checks (Checks API) — the GitHub {@link CiCheckWriter} behind the
+ * shared check lifecycle in `../checks.js`.
  *
- * `createGitHubCheck` opens a merge-box check run on a commit and returns a
- * handle for updating and concluding it, so an agent can report its own CI
- * result (name, summary, and a "Details" link — e.g. the agent session run).
- * Works with any client exposing `getOctokit()` (`ctx.github`,
+ * `createGitHubCheck` opens a merge-box check run on a commit and returns the
+ * shared `CiCheck` handle; `resumeGitHubCheck` rebuilds one from a stored
+ * check-run id. Works with any client exposing `getOctokit()` (`ctx.github`,
  * `ctx.host.github`), and is also reachable as `ctx.github.createCheck(...)`.
  *
  * Posting checks needs `checks:write`. With `cursorAccount`, declare
  * `githubChannel({ checks: true })` so the hosted lease is minted on the
  * `contents-write` tier; GitHub App / PAT credentials need the equivalent
- * permission.
+ * permission. API failures are normalized into `GitHubApiError`.
  */
 import type { Octokit } from "@octokit/rest";
-import { type GitHubCheckRunConclusion, type GitHubCheckRunStatus } from "./api.js";
+import { type CiCheck, type CiCheckConcludeInput, type CiCheckCreateInput, type CiCheckOutput, type CiCheckRef, type CiCheckUpdateInput } from "../checks.js";
 /** Any client that can hand out an authenticated Octokit. */
 export interface GitHubCheckClient {
     getOctokit(): Promise<Octokit>;
 }
-/** Output shown on the check page (both fields required by GitHub). */
-export interface GitHubCheckOutput {
-    /** Heading on the check page. */
-    title: string;
-    /** Markdown body (supports links, e.g. `[View session](…)`). */
-    summary: string;
-}
-export interface GitHubCheckCreateInput {
+export type GitHubCheckOutput = CiCheckOutput;
+export type GitHubCheckUpdateInput = CiCheckUpdateInput;
+export type GitHubCheckConcludeInput = CiCheckConcludeInput;
+/** A created check run. All methods throw `GitHubApiError` on API failure. */
+export type GitHubCheck = CiCheck & CiCheckRef;
+export interface GitHubCheckCreateInput extends CiCheckCreateInput {
     /** Client used for every API call on the returned handle. */
     github: GitHubCheckClient;
     /** Repository owner login, e.g. `"acme"`. */
     owner: string;
     /** Repository name, e.g. `"widgets"`. */
     repo: string;
-    /** 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?: GitHubCheckOutput;
-}
-export interface GitHubCheckUpdateInput {
-    status?: GitHubCheckRunStatus;
-    conclusion?: GitHubCheckRunConclusion;
-    detailsUrl?: string;
-    output?: GitHubCheckOutput;
-}
-export interface GitHubCheckConcludeInput {
-    /** Final result shown in the merge box. */
-    conclusion: GitHubCheckRunConclusion;
-    detailsUrl?: string;
-    output?: GitHubCheckOutput;
-}
-/** A created check run. All methods throw `GitHubApiError` on API failure. */
-export interface GitHubCheck {
-    /** Check run id (for reuse across process restarts). */
-    readonly id: number;
-    /** GitHub web URL of the check run page, when returned by the API. */
-    readonly url: string | undefined;
-    /** Patch status / output / details link while the check is running. */
-    update(input: GitHubCheckUpdateInput): Promise<void>;
-    /** Complete the check with a conclusion (sets `completed_at`). */
-    conclude(input: GitHubCheckConcludeInput): Promise<void>;
 }
 /**
  * Create a CI check run on a commit and return a handle for later updates.

package/dist/channels/github/checks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../../src/channels/github/checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAElB,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,6DAA6D;IAC7D,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,MAAM,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;IAClC,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,UAAU,CAAC,EAAE,wBAAwB,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,2CAA2C;IAC3C,UAAU,EAAE,wBAAwB,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,WAAW,CAAC,CA8BtB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,WAAW,CAoCd"}
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../../src/channels/github/checks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,kBAAkB,EAIxB,MAAM,cAAc,CAAC;AAGtB,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAC9C,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AACxD,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,CAAC;AAE5D,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,6DAA6D;IAC7D,MAAM,EAAE,iBAAiB,CAAC;IAC1B,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAkED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAEtB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,GAAG,WAAW,CAKd"}