@cursor/july 0.1.102 → 0.1.104

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

@@ -0,0 +1,35 @@
+/**
+ * Durable per-session Bitbucket channel state, persisted with the turn so
+ * channel stream-event handlers can rebuild a repo-bound handle without
+ * re-parsing the webhook.
+ */
+import type { BitbucketDialect } from "./types.js";
+export interface BitbucketChannelState {
+    dialect: BitbucketDialect | null;
+    /** `workspace/repo` (Cloud) or `PROJECT/repo` (Data Center), as delivered. */
+    repoFullName: string;
+    /** Cloud `repository.uuid` (braces included) when known. */
+    repoUuid: string | null;
+    pullRequestId: number | null;
+    /** Source-branch head at dispatch time, when known. */
+    headSha: string | null;
+    /** Comment id that woke the turn (comment events only). */
+    triggeringCommentId: number | null;
+    deliveryId: string | null;
+    /** Cloud-normalized event key. */
+    eventType: string | null;
+}
+export declare function emptyBitbucketChannelState(overrides?: Partial<BitbucketChannelState>): BitbucketChannelState;
+export declare function bitbucketChannelStateForEvent(input: {
+    repository: {
+        dialect: BitbucketDialect;
+        fullName: string;
+        uuid?: string;
+    };
+    pullRequestId?: number;
+    headSha?: string;
+    deliveryId?: string;
+    eventType: string;
+    triggeringCommentId?: number;
+}): BitbucketChannelState;
+//# sourceMappingURL=state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/channels/bitbucket/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uDAAuD;IACvD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kCAAkC;IAClC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,0BAA0B,CACxC,SAAS,GAAE,OAAO,CAAC,qBAAqB,CAAM,GAC7C,qBAAqB,CAYvB;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,UAAU,EAAE;QAAE,OAAO,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,qBAAqB,CAWxB"}

package/dist/channels/bitbucket/state.js

@@ -0,0 +1,21 @@
+/**
+ * Durable per-session Bitbucket channel state, persisted with the turn so
+ * channel stream-event handlers can rebuild a repo-bound handle without
+ * re-parsing the webhook.
+ */
+export function emptyBitbucketChannelState(overrides = {}) {
+    return Object.assign({ dialect: null, repoFullName: "", repoUuid: null, pullRequestId: null, headSha: null, triggeringCommentId: null, deliveryId: null, eventType: null }, overrides);
+}
+export function bitbucketChannelStateForEvent(input) {
+    var _a, _b, _c, _d, _e;
+    return emptyBitbucketChannelState({
+        dialect: input.repository.dialect,
+        repoFullName: input.repository.fullName,
+        repoUuid: (_a = input.repository.uuid) !== null && _a !== void 0 ? _a : null,
+        pullRequestId: (_b = input.pullRequestId) !== null && _b !== void 0 ? _b : null,
+        headSha: (_c = input.headSha) !== null && _c !== void 0 ? _c : null,
+        triggeringCommentId: (_d = input.triggeringCommentId) !== null && _d !== void 0 ? _d : null,
+        deliveryId: (_e = input.deliveryId) !== null && _e !== void 0 ? _e : null,
+        eventType: input.eventType,
+    });
+}

package/dist/channels/bitbucket/types.d.ts

@@ -0,0 +1,229 @@
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
+import type { AgentCloudOptions, ArtifactsApi, AuthContext, AuthPolicy, ChannelEventHandlers, ChannelStartArgs, HostContext, SendMessageFn } from "../../types.js";
+import type { BitbucketTokenProvider } from "./api.js";
+import type { BitbucketHandle } from "./binding.js";
+import type { BitbucketChannelState } from "./state.js";
+/**
+ * Which Bitbucket sent the payload. Cloud bodies carry `pullrequest` and
+ * `repository.uuid`; Data Center bodies carry `pullRequest` and
+ * `repository.project.key`.
+ */
+export type BitbucketDialect = "cloud" | "data-center";
+export interface BitbucketUser {
+    /** Cloud `uuid` (braces included) or Data Center numeric `id`. */
+    id: string;
+    displayName?: string;
+    /** Cloud `nickname` / Data Center `name`. */
+    username?: string;
+}
+export interface BitbucketRepositoryRef {
+    dialect: BitbucketDialect;
+    /**
+     * `workspace/repo` (Cloud) or `PROJECT/repo` (Data Center), as delivered.
+     * Continuation keys lowercase it; consumers should too when comparing.
+     */
+    fullName: string;
+    /** Workspace slug (Cloud) or project key (Data Center). */
+    owner: string;
+    slug: string;
+    /** Cloud `repository.uuid` (braces included). */
+    uuid?: string;
+    /** Data Center numeric repository id. */
+    id?: number;
+    /** Web URL when the payload carries one. */
+    htmlUrl?: string;
+}
+/** A pull request normalized from either dialect. */
+export interface BitbucketPullRequestEvent {
+    /**
+     * Cloud-normalized action: `created`, `updated`, `approved`, `unapproved`,
+     * `changes_request_created`, `fulfilled`, `rejected`.
+     */
+    action: string;
+    id: number;
+    title?: string;
+    description?: string | null;
+    /** `OPEN`, `MERGED`, `DECLINED`, `SUPERSEDED`. */
+    state?: string;
+    draft?: boolean;
+    sourceBranch?: string;
+    targetBranch?: string;
+    /** Source-branch head: Cloud `source.commit.hash` / DC `fromRef.latestCommit`. */
+    headSha?: string;
+    /** DC `previousFromHash` on `pr:from_ref_updated` — new commits were pushed. */
+    previousHeadSha?: string;
+    author?: BitbucketUser;
+    htmlUrl?: string;
+}
+export interface BitbucketPullRequestComment {
+    id: number;
+    body: string;
+    author?: BitbucketUser;
+    htmlUrl?: string;
+    /** Cloud `comment.inline` when the comment is anchored to a file. */
+    inline?: {
+        path?: string;
+        to?: number;
+        from?: number;
+    };
+}
+export interface BitbucketPushChange {
+    ref?: string;
+    /** Branch / tag name. */
+    name?: string;
+    before?: string;
+    after?: string;
+    type?: string;
+}
+export interface BitbucketPush {
+    changes: BitbucketPushChange[];
+}
+export interface BitbucketEventContext {
+    /** `X-Request-UUID` (Cloud) / `X-Request-Id` (DC), when present. */
+    deliveryId?: string;
+    /** Cloud-normalized event key (`pullrequest:created`, `repo:push`, …). */
+    eventType: string;
+    /** Raw `X-Event-Key` as delivered (DC keys before normalization). */
+    rawEventType: string;
+    repository: BitbucketRepositoryRef;
+    pullRequestId?: number;
+    pullRequestUrl?: string;
+    /** Raw parsed payload record, for consumers whose normalization needs more. */
+    payload: Record<string, unknown>;
+    /** `actor` on the payload — who triggered the delivery. */
+    sender?: BitbucketUser;
+    /**
+     * Repo-bound Bitbucket API (`api`, `request`, `setBuildStatus`,
+     * `createCheck`) in the delivery's dialect. Routes through the Cursor SCM
+     * proxy under `cursorAccount` + `--cursor-scm-proxy`; otherwise uses
+     * {@link BitbucketChannelOptions.token} / `BITBUCKET_TOKEN` against the
+     * dialect's API base.
+     */
+    bitbucket: BitbucketHandle;
+    /**
+     * Channel `send`. Set on every delivery path (HTTP webhook, hosted
+     * admission) so a hook can start a turn itself instead of returning
+     * `{ auth, message }` or a deferred `{ task }`.
+     */
+    send?: SendMessageFn;
+    host: HostContext;
+    artifacts: ArtifactsApi;
+}
+export type BitbucketTurnDispatch = {
+    auth: AuthContext;
+    message?: string;
+    title?: string;
+    context?: readonly string[];
+};
+/** Bound per-delivery helpers passed to a {@link BitbucketTaskDispatch.task}. */
+export interface BitbucketTaskArgs {
+    send: SendMessageFn;
+    waitUntil: (promise: Promise<unknown>) => void;
+}
+/** Run a host-side handler after the webhook is acknowledged with a 202. */
+export type BitbucketTaskDispatch = {
+    task: (args: BitbucketTaskArgs) => void | Promise<void>;
+};
+export type BitbucketDispatch = BitbucketTurnDispatch | BitbucketTaskDispatch;
+export type BitbucketDispatchResult = BitbucketDispatch | null | Promise<BitbucketDispatch | null>;
+export type BitbucketPullRequestHook = (ctx: BitbucketEventContext, pullRequest: BitbucketPullRequestEvent) => BitbucketDispatchResult;
+export type BitbucketPullRequestCommentHook = (ctx: BitbucketEventContext, comment: BitbucketPullRequestComment, pullRequest: BitbucketPullRequestEvent) => BitbucketDispatchResult;
+export type BitbucketPushHook = (ctx: BitbucketEventContext, push: BitbucketPush) => BitbucketDispatchResult;
+export type BitbucketEventHook = (ctx: BitbucketEventContext, event: {
+    eventType: string;
+    rawEventType: string;
+    payload: unknown;
+}) => BitbucketDispatchResult;
+export type BitbucketCloudOptionsResolver = (ctx: BitbucketEventContext, pullRequest: BitbucketPullRequestEvent) => AgentCloudOptions | undefined | Promise<AgentCloudOptions | undefined>;
+/** One verified Bitbucket delivery handed to {@link dispatchBitbucketWebhook}. */
+export interface BitbucketWebhookDelivery {
+    /** Cloud-normalized event key (hosted admission passes the envelope's). */
+    eventType: string;
+    /** `X-Event-Key` as delivered. Defaults to {@link eventType}. */
+    rawEventType?: string;
+    payload: Record<string, unknown>;
+    deliveryId?: string;
+}
+export interface BitbucketChannelOptions {
+    /**
+     * Use the signed-in Cursor account for inbound Bitbucket events delivered
+     * by the Cursor backend. `true` takes repo scope from the deployment;
+     * `{ repos }` (`workspace/repo` or `PROJECT/repo`) makes the channel
+     * self-contained.
+     */
+    cursorAccount?: boolean | {
+        repos: readonly string[];
+    };
+    /**
+     * Access token (or provider) for direct `ctx.bitbucket` calls when not in
+     * proxy mode. Sent as `Authorization: Bearer`. Falls back to
+     * `BITBUCKET_TOKEN`.
+     */
+    token?: string | BitbucketTokenProvider;
+    /**
+     * REST base for direct `ctx.bitbucket` calls. Defaults to
+     * `BITBUCKET_API_BASE_URL`, else api.bitbucket.org 2.0 (Cloud). Data
+     * Center deploys must set one of these; the payload's repository link is
+     * never used to pick where the token is sent.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Webhook secret for direct HTTP deliveries: `X-Hub-Signature`
+     * `sha256=<hmac>` over the raw body (both dialects). Falls back to
+     * `BITBUCKET_WEBHOOK_SECRET`. With a secret set the HMAC is the request
+     * auth; without one production stays loopback-strict and `serve --dev`
+     * admits unsigned loopback deliveries.
+     */
+    webhookSecret?: string | (() => string | undefined);
+    /**
+     * Optional repo allowlist (`workspace/repo` / `PROJECT/repo`,
+     * case-insensitive). Events from other repos are acked without a turn.
+     */
+    repos?: readonly string[];
+    /** Route auth chain; defaults follow {@link webhookSecret}. */
+    auth?: AuthPolicy[];
+    /** Route path under `/v1/channels/<name>`. Defaults to `/`. */
+    path?: string;
+    /**
+     * Pin the event keys this channel dispatches on (Cloud vocabulary; DC keys
+     * are normalized). Published as `meta.bitbucketWebhookEvents`. Defaults to
+     * the set derived from hooks.
+     */
+    webhookEvents?: readonly string[];
+    /**
+     * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
+     * engine-minted per-PR continuation unless the agent set
+     * `architecture: "v2"` (then `bitbucket.pr/v2`, or `bitbucket.none/v2`
+     * when a non-PR event is declared).
+     */
+    continuation?: ContinuationIdentity;
+    /**
+     * Decide whether an inbound pull-request event starts a turn. Return
+     * `{ auth: defaultBitbucketAuth(ctx) }` to dispatch, `null` to ignore.
+     * Without this hook the channel dispatches on `created` and on `updated`
+     * that pushed commits (Data Center `previousFromHash` differs from the
+     * head; Cloud `pullrequest:updated` carries no diff and is not dispatched).
+     */
+    onPullRequest?: BitbucketPullRequestHook;
+    /** Opt-in `pullrequest:comment_created` handler. */
+    onPullRequestComment?: BitbucketPullRequestCommentHook;
+    /** Opt-in `repo:push` handler. No default dispatch. */
+    onPush?: BitbucketPushHook;
+    /**
+     * Catch-all for event keys without a typed hook (`repo:fork`,
+     * `issue:created`, …). NOT a fallback: typed events never reach it.
+     */
+    onEvent?: BitbucketEventHook;
+    /**
+     * Per-session cloud options. Pass `true` to attach the repo using the
+     * pull request's web URL, or a resolver for custom cloud options.
+     */
+    cloud?: boolean | AgentCloudOptions | BitbucketCloudOptionsResolver;
+    /** Channel stream-event handlers. */
+    events?: ChannelEventHandlers<BitbucketChannelState>;
+    /** Called once when the server mounts this channel. */
+    onStart?: (args: ChannelStartArgs) => void | Promise<void>;
+    /** Called when the server shuts down. */
+    onStop?: () => void | Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/channels/bitbucket/types.js

@@ -0,0 +1 @@
+export {};

package/dist/channels/change-monitors/change-monitors-channel.d.ts

@@ -0,0 +1,5 @@
+import type { ChannelDefinition } from "../../types.js";
+import { type ChangeMonitorsChannelOptions } from "./types.js";
+export declare function changeMonitorsChannel(options: ChangeMonitorsChannelOptions): ChannelDefinition;
+export declare function getChangeMonitorsChannelOptions(definition: object): ChangeMonitorsChannelOptions | undefined;
+//# sourceMappingURL=change-monitors-channel.d.ts.map

package/dist/channels/change-monitors/change-monitors-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-monitors-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/change-monitors/change-monitors-channel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAEL,KAAK,4BAA4B,EAElC,MAAM,YAAY,CAAC;AA4CpB,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,iBAAiB,CAEnB;AAED,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,MAAM,GACjB,4BAA4B,GAAG,SAAS,CAE1C"}

package/dist/channels/change-monitors/change-monitors-channel.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { createFactoryResourceChannel } from "../../internal/factory-resource-channel.js";
+import { CHECKPOINT_CREATED_EVENT_TYPE, } from "./types.js";
+const checkpointResourceSchema = z
+    .object({
+    name: z.string().min(1),
+    deployment: z.string().min(1),
+    runKey: z.string().min(1),
+    evidenceSummary: z.string().min(1),
+    planRevision: z.string().optional(),
+    createTime: z.string().min(1).optional(),
+    description: z.string().optional(),
+    clear: z.object({}).passthrough().optional(),
+    issues: z
+        .object({ title: z.string().min(1) })
+        .passthrough()
+        .optional(),
+    inconclusive: z.object({}).passthrough().optional(),
+})
+    .passthrough()
+    .refine((checkpoint) => [checkpoint.clear, checkpoint.issues, checkpoint.inconclusive].filter((arm) => arm !== undefined).length === 1, { message: "checkpoint must have exactly one result arm" });
+const checkpointCreatedEventSchema = z.object({
+    eventId: z.string().min(1),
+    eventType: z.literal(CHECKPOINT_CREATED_EVENT_TYPE),
+    teamId: z.string().min(1),
+    occurredAtMs: z.number().int().nonnegative(),
+    checkpoint: checkpointResourceSchema,
+});
+const pack = createFactoryResourceChannel({
+    kind: "change_monitors",
+    eventTypes: [CHECKPOINT_CREATED_EVENT_TYPE],
+    eventSchema: checkpointCreatedEventSchema,
+    replayDescription: "Replay a Change Monitor checkpoint-created event.",
+    invalidError: "invalid change-monitor checkpoint event",
+});
+export function changeMonitorsChannel(options) {
+    return pack.channel(options);
+}
+export function getChangeMonitorsChannelOptions(definition) {
+    return pack.getOptions(definition);
+}

package/dist/channels/change-monitors/index.d.ts

@@ -0,0 +1,4 @@
+export { changeMonitorsChannel } from "./change-monitors-channel.js";
+export type { ChangeMonitorsChannelOptions, CheckpointCreatedEvent, CheckpointCreatedEventType, CheckpointResource, } from "./types.js";
+export { CHECKPOINT_CREATED_EVENT_TYPE } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/change-monitors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/change-monitors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,YAAY,EACV,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC"}

package/dist/channels/change-monitors/index.js

@@ -0,0 +1,2 @@
+export { changeMonitorsChannel } from "./change-monitors-channel.js";
+export { CHECKPOINT_CREATED_EVENT_TYPE } from "./types.js";

package/dist/channels/change-monitors/types.d.ts

@@ -0,0 +1,39 @@
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
+import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
+export declare const CHECKPOINT_CREATED_EVENT_TYPE: "checkpoint.created";
+export type CheckpointCreatedEventType = typeof CHECKPOINT_CREATED_EVENT_TYPE;
+/**
+ * Factory Checkpoint JSON (camelCase proto JSON). Exactly one result arm is
+ * set: `clear`, `issues`, or `inconclusive`. The channel does not pre-filter.
+ */
+export type CheckpointResource = {
+    name: string;
+    deployment: string;
+    runKey: string;
+    evidenceSummary: string;
+    planRevision?: string;
+    createTime?: string;
+    description?: string;
+    clear?: Record<string, unknown>;
+    issues?: {
+        title: string;
+    };
+    inconclusive?: Record<string, unknown>;
+};
+/** Factory `checkpoint.created` for every Change Monitor Checkpoint create. */
+export type CheckpointCreatedEvent = {
+    eventId: string;
+    eventType: CheckpointCreatedEventType;
+    teamId: string;
+    occurredAtMs: number;
+    checkpoint: CheckpointResource;
+};
+export type ChangeMonitorsChannelOptions = {
+    onEvent: (event: CheckpointCreatedEvent, args: ChannelHandlerArgs) => Promise<unknown> | unknown;
+    continuation?: ContinuationIdentity;
+    path?: string;
+    auth?: ChannelDefinition["auth"];
+    onStart?: ChannelDefinition["onStart"];
+    onStop?: ChannelDefinition["onStop"];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/channels/change-monitors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channels/change-monitors/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AACpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE5E,eAAO,MAAM,6BAA6B,EAAG,oBAA6B,CAAC;AAE3E,MAAM,MAAM,0BAA0B,GAAG,OAAO,6BAA6B,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,0BAA0B,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,kBAAkB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,CACP,KAAK,EAAE,sBAAsB,EAC7B,IAAI,EAAE,kBAAkB,KACrB,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAChC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,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,CAAC"}

package/dist/channels/change-monitors/types.js

@@ -0,0 +1 @@
+export const CHECKPOINT_CREATED_EVENT_TYPE = "checkpoint.created";

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

@@ -10,16 +10,16 @@ export declare function getDeploymentsChannelOptions(definition: object): Deploy
  * subscriptions. Published as `meta.deploymentEventTypes` so the deploy
  * manifest can extract `eventTypes`.
  *
- * A channel with no resolved subscriptions declares the full event set:
- * deploy sources usually come from env vars read at module load, and the
- * hosted freeze bakes hermetically (no customer env/secrets), so deriving
- * `[]` there would leave the manifest without event types and no
+ * 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 deploy sources binds no edges.
+ * no repositories binds no edges.
  */
 export declare function deriveDeploymentEventTypes(options: Pick<DeploymentsChannelOptions, "deploySourceUris" | "events">): string[];
 /**
@@ -32,8 +32,6 @@ export declare function dispatchDeploymentEvent(input: {
     event: DeploymentEvent;
     args: ChannelHandlerArgs;
 }): Promise<Response>;
-export type DeploymentsDispatchOutcome = "skip" | "task";
-export declare function getDeploymentsDispatchOutcome(response: Response): DeploymentsDispatchOutcome | undefined;
 /**
  * Whether this channel admits the event on a hosted pod. The hosted
  * control plane fans out on `(deploy_source, eventType, team)` edges only —
@@ -42,13 +40,14 @@ export declare function getDeploymentsDispatchOutcome(response: Response): Deplo
  * the v1 relay does before `onEvent`.
  *
  * A channel with NO resolved subscriptions admits everything the control
- * plane delivered: deploy sources usually come from env vars read at
- * module load, and the hosted freeze bakes hermetically (no customer env),
- * so on a restored pod an env-configured channel resolves empty — the
- * deploy-time edges (bound from the watched repositories) already carry
- * the customer's scope, and refusing here would silently drop every
- * delivery. Same posture as {@link deriveDeploymentEventTypes}: authored
- * subscriptions narrow; an unconfigured channel defers to the deploy scope.
+ * 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 declare function deploymentEventMatchesChannel(options: DeploymentsChannelOptions, event: DeploymentEvent): boolean;
 /**
@@ -80,6 +79,15 @@ export declare function deploymentEventMatchesChannel(options: DeploymentsChanne
  * 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`.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"deployments-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/deployments/deployments-channel.ts"],"names":[],"mappings":"AASA,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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,IAAI,CAAC,yBAAyB,EAAE,kBAAkB,GAAG,QAAQ,CAAC,GACtE,MAAM,EAAE,CAYV;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,CAapB;AAED,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,MAAM,CAAC;AAezD,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,QAAQ,GACjB,0BAA0B,GAAG,SAAS,CAExC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,yBAAyB,EAClC,KAAK,EAAE,eAAe,GACrB,OAAO,CAUT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,iBAAiB,CA4DnB"}
+{"version":3,"file":"deployments-channel.d.ts","sourceRoot":"","sources":["../../../src/channels/deployments/deployments-channel.ts"],"names":[],"mappings":"AAUA,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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,IAAI,CAAC,yBAAyB,EAAE,kBAAkB,GAAG,QAAQ,CAAC,GACtE,MAAM,EAAE,CAYV;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,CAapB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,yBAAyB,EAClC,KAAK,EAAE,eAAe,GACrB,OAAO,CAUT;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,yBAAyB,GACjC,iBAAiB,CAoDnB"}

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

@@ -9,6 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 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";
@@ -39,16 +40,16 @@ export function getDeploymentsChannelOptions(definition) {
  * subscriptions. Published as `meta.deploymentEventTypes` so the deploy
  * manifest can extract `eventTypes`.
  *
- * A channel with no resolved subscriptions declares the full event set:
- * deploy sources usually come from env vars read at module load, and the
- * hosted freeze bakes hermetically (no customer env/secrets), so deriving
- * `[]` there would leave the manifest without event types and no
+ * 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 deploy sources binds no edges.
+ * no repositories binds no edges.
  */
 export function deriveDeploymentEventTypes(options) {
     const subscriptions = resolveDeploymentSubscriptions(options);
@@ -78,17 +79,9 @@ export function dispatchDeploymentEvent(input) {
         }));
         // "task": authored `onEvent` ran to completion without a captured send.
         // Hosted admission only consults this when no send was captured.
-        return withDispatchOutcome(Response.json({ ok: true }), "task");
+        return tagOutcome(Response.json({ ok: true }), "task");
     });
 }
-const dispatchOutcomeByResponse = new WeakMap();
-function withDispatchOutcome(response, outcome) {
-    dispatchOutcomeByResponse.set(response, outcome);
-    return response;
-}
-export function getDeploymentsDispatchOutcome(response) {
-    return dispatchOutcomeByResponse.get(response);
-}
 /**
  * Whether this channel admits the event on a hosted pod. The hosted
  * control plane fans out on `(deploy_source, eventType, team)` edges only —
@@ -97,13 +90,14 @@ export function getDeploymentsDispatchOutcome(response) {
  * the v1 relay does before `onEvent`.
  *
  * A channel with NO resolved subscriptions admits everything the control
- * plane delivered: deploy sources usually come from env vars read at
- * module load, and the hosted freeze bakes hermetically (no customer env),
- * so on a restored pod an env-configured channel resolves empty — the
- * deploy-time edges (bound from the watched repositories) already carry
- * the customer's scope, and refusing here would silently drop every
- * delivery. Same posture as {@link deriveDeploymentEventTypes}: authored
- * subscriptions narrow; an unconfigured channel defers to the deploy scope.
+ * 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, event) {
     const subscriptions = resolveDeploymentSubscriptions(options);
@@ -142,6 +136,15 @@ export function deploymentEventMatchesChannel(options, event) {
  * 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`.
  */
@@ -183,15 +186,10 @@ export function deploymentsChannel(options) {
             }
             const event = parsed.data;
             if (!deploymentEventMatchesChannel(options, event)) {
-                return withDispatchOutcome(Response.json({
-                    ok: true,
-                    skipped: true,
-                    reason: "subscription_mismatch",
-                }), "skip");
+                return skipped("subscription_mismatch");
             }
             return dispatchDeploymentEvent({ options, event, args });
         }),
-        getOutcome: (response) => getDeploymentsDispatchOutcome(response),
     });
     return definition;
 }

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

@@ -1,4 +1,4 @@
-import type { ContinuationIdentity } from "../../continuation.js";
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
 /** {@link ChannelMeta.kind} value used by {@link deploymentsChannel}. */
 export declare const DEPLOYMENTS_CHANNEL_KIND = "deployments";
@@ -44,12 +44,18 @@ export interface DeploymentsChannelOptions {
      * and then receives nothing. A bare string takes the default environment and
      * event filters.
      *
-     * There is no team-wide subscription: every deploy source is named. An
-     * empty list is how a consumer *deregisters*, so it cannot also mean
-     * "everything". A live array that starts empty and is filled later is
-     * re-read on each registration heartbeat.
+     * Omit on hosted v2. The control plane then binds `deploy_source` edges
+     * from the deploy's watched `repositories` and the channel admits what it
+     * is sent. That is the multi-tenant shape: an agent cannot enumerate
+     * sources for a tenant it has never seen.
+     *
+     * 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)[];
+    deploySourceUris?: readonly (string | DeploymentSubscription)[];
     /**
      * Applied to every subscription that does not set its own. Omit or leave
      * empty for every environment.