@cursor/july 0.1.62 → 0.1.73

package/dist/internal/deploy-manifest.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Offline deploy manifest (workstream Wd of
+ * `docs/agent-serve/agent-sdk-event-ingress-plan.md`, Wd-0/Wd-1).
+ *
+ * The manifest is every piece of deployment metadata that is statically
+ * derivable from the agent project — extracted at build/deploy time, with no
+ * VM, no engine, and no network — so the control plane can store it before
+ * any pod starts and keep answering metadata questions while a deployment is
+ * offline or hibernated.
+ *
+ * Two layers with different stability contracts:
+ *
+ * - `declarations` is the **versioned wire contract** consumed by the
+ *   control plane (Wd-2): per-channel event capabilities, egress domains,
+ *   and public route paths. Validated by {@link agentDeployManifestV1Schema};
+ *   the CP stores these as columns / column views. Repos are deliberately
+ *   NOT here — which repos a deployment watches is per-instance deploy
+ *   configuration, not a property of the code.
+ * - `info` is the full static project description — the same payload the
+ *   engine serves at `GET /v1/info` (`projectInfo`). Stored opaquely by the
+ *   CP so `/v1/info`-class reads can be served for offline deployments
+ *   (Wd-5). Its shape evolves with the SDK and is intentionally not pinned
+ *   by the wire schema beyond "is an object".
+ *
+ * Event derivation note: each mounted channel publishes its event set in its
+ * own `channels[].eventTypes` declaration. A project with no GitHub channel
+ * subscribes to no GitHub events, regardless of configured repository scope.
+ * Keep that capability per-channel: do not reintroduce a provider-wide event
+ * union for control-plane consumers.
+ */
+import type { AgentProject, AgentProjectInfo } from "../types.js";
+export declare const DEPLOY_MANIFEST_VERSION: 1;
+export interface AgentDeployManifestDeclarations {
+    egressDomains: string[];
+    publicRoutePaths: string[];
+    /** Where this runtime mirrors framework-owned sessions and event chunks. */
+    frameworkStorage?: "cursor-hosted" | "other" | "none";
+    /**
+     * Mounted channels with their kinds and per-channel event capability.
+     * Scope keys are installation config and are never extracted here.
+     * Continuation is opt-in: without a deterministic selector key, every
+     * inbound event starts a fresh session. Selector encoding remains open.
+     */
+    channels: Array<{
+        id: string;
+        kind?: string;
+        eventTypes?: string[];
+    }>;
+}
+export interface AgentDeployManifestV1 {
+    manifestVersion: 1;
+    /** Unix ms at extraction. */
+    generatedAtMs: number;
+    /** `@cursor/july` version that produced the manifest. */
+    cliVersion: string;
+    declarations: AgentDeployManifestDeclarations;
+    /**
+     * Full `projectInfo` payload (see `GET /v1/info`). Opaque to the wire
+     * contract; the CP stores it verbatim.
+     */
+    info: AgentProjectInfo;
+}
+/**
+ * Extract the offline deploy manifest from a loaded project. Pure: no
+ * network, no filesystem beyond what `loadAgentProject` already read.
+ */
+export declare function buildAgentDeployManifest(project: AgentProject, options?: {
+    nowMs?: number;
+    cliVersion?: string;
+}): AgentDeployManifestV1;
+/**
+ * Parse an untrusted manifest (round-trip check for the CLI's own output;
+ * the CP re-validates server-side with its own copy of the contract).
+ */
+export declare function parseAgentDeployManifest(raw: unknown): AgentDeployManifestV1 | undefined;
+//# sourceMappingURL=deploy-manifest.d.ts.map

package/dist/internal/deploy-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-manifest.d.ts","sourceRoot":"","sources":["../../src/internal/deploy-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIlE,eAAO,MAAM,uBAAuB,EAAE,CAAK,CAAC;AA6B5C,MAAM,WAAW,+BAA+B;IAC9C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,eAAe,GAAG,OAAO,GAAG,MAAM,CAAC;IACtD;;;;;OAKG;IACH,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,CAAC,CAAC;IACnB,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,+BAA+B,CAAC;IAC9C;;;OAGG;IACH,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,qBAAqB,CA2CvB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,GACX,qBAAqB,GAAG,SAAS,CAOnC"}

package/dist/internal/deploy-manifest.js

@@ -0,0 +1,117 @@
+/**
+ * Offline deploy manifest (workstream Wd of
+ * `docs/agent-serve/agent-sdk-event-ingress-plan.md`, Wd-0/Wd-1).
+ *
+ * The manifest is every piece of deployment metadata that is statically
+ * derivable from the agent project — extracted at build/deploy time, with no
+ * VM, no engine, and no network — so the control plane can store it before
+ * any pod starts and keep answering metadata questions while a deployment is
+ * offline or hibernated.
+ *
+ * Two layers with different stability contracts:
+ *
+ * - `declarations` is the **versioned wire contract** consumed by the
+ *   control plane (Wd-2): per-channel event capabilities, egress domains,
+ *   and public route paths. Validated by {@link agentDeployManifestV1Schema};
+ *   the CP stores these as columns / column views. Repos are deliberately
+ *   NOT here — which repos a deployment watches is per-instance deploy
+ *   configuration, not a property of the code.
+ * - `info` is the full static project description — the same payload the
+ *   engine serves at `GET /v1/info` (`projectInfo`). Stored opaquely by the
+ *   CP so `/v1/info`-class reads can be served for offline deployments
+ *   (Wd-5). Its shape evolves with the SDK and is intentionally not pinned
+ *   by the wire schema beyond "is an object".
+ *
+ * Event derivation note: each mounted channel publishes its event set in its
+ * own `channels[].eventTypes` declaration. A project with no GitHub channel
+ * subscribes to no GitHub events, regardless of configured repository scope.
+ * Keep that capability per-channel: do not reintroduce a provider-wide event
+ * union for control-plane consumers.
+ */
+import { z } from "zod";
+import { isPublicEndpointPolicy } from "../channels.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
+import { projectInfo } from "./discovery.js";
+import { packageVersion } from "./distribution.js";
+export const DEPLOY_MANIFEST_VERSION = 1;
+/**
+ * Versioned wire contract for the CP-consumed declaration fields. Kept
+ * module-private (the package builds with isolated declarations); consumers
+ * use {@link parseAgentDeployManifest} and the explicit interfaces below.
+ */
+const agentDeployManifestV1Schema = z.object({
+    manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
+    generatedAtMs: z.number().int().nonnegative(),
+    cliVersion: z.string().min(1),
+    declarations: z.object({
+        egressDomains: z.array(z.string().min(1)).max(64),
+        publicRoutePaths: z.array(z.string().min(1)).max(64),
+        frameworkStorage: z.enum(["cursor-hosted", "other", "none"]).optional(),
+        channels: z
+            .array(z.object({
+            id: z.string().min(1).max(128),
+            kind: z.string().min(1).max(32).optional(),
+            eventTypes: z.array(z.string().min(1).max(64)).max(64).optional(),
+        }))
+            .max(64),
+    }),
+    // Full `projectInfo` payload — opaque to the wire contract.
+    info: z.record(z.unknown()),
+});
+/**
+ * Extract the offline deploy manifest from a loaded project. Pure: no
+ * network, no filesystem beyond what `loadAgentProject` already read.
+ */
+export function buildAgentDeployManifest(project, options) {
+    var _a;
+    var _b, _c, _d;
+    const channels = project.channels.map((channel) => {
+        var _a, _b, _c;
+        const kind = (_a = channel.definition.meta) === null || _a === void 0 ? void 0 : _a.kind;
+        const githubEvents = (_b = channel.definition.meta) === null || _b === void 0 ? void 0 : _b.githubWebhookEvents;
+        const originEvents = (_c = channel.definition.meta) === null || _c === void 0 ? void 0 : _c.originWebhookEvents;
+        const eventTypes = githubEvents !== undefined
+            ? [...githubEvents].sort()
+            : originEvents !== undefined
+                ? [...originEvents].sort()
+                : undefined;
+        return {
+            id: channel.id,
+            kind,
+            eventTypes,
+        };
+    });
+    // Same mapping as `july deploy` (cli-deploy.ts): channels declared public
+    // via `publicEndpoint()` become alias-token-free route prefixes.
+    const publicRoutePaths = project.channels
+        .filter((channel) => { var _a; return ((_a = channel.definition.auth) !== null && _a !== void 0 ? _a : []).some(isPublicEndpointPolicy); })
+        .map((channel) => `/v1/channels/${channel.id}`);
+    return {
+        manifestVersion: DEPLOY_MANIFEST_VERSION,
+        generatedAtMs: (_b = options === null || options === void 0 ? void 0 : options.nowMs) !== null && _b !== void 0 ? _b : Date.now(),
+        cliVersion: (_c = options === null || options === void 0 ? void 0 : options.cliVersion) !== null && _c !== void 0 ? _c : packageVersion(),
+        declarations: {
+            egressDomains: [...((_d = (_a = project.agent.hosting) === null || _a === void 0 ? void 0 : _a.egressDomains) !== null && _d !== void 0 ? _d : [])],
+            publicRoutePaths,
+            frameworkStorage: project.storage === undefined
+                ? "none"
+                : isCursorHostedStorage(project.storage)
+                    ? "cursor-hosted"
+                    : "other",
+            channels,
+        },
+        info: projectInfo(project),
+    };
+}
+/**
+ * Parse an untrusted manifest (round-trip check for the CLI's own output;
+ * the CP re-validates server-side with its own copy of the contract).
+ */
+export function parseAgentDeployManifest(raw) {
+    const parsed = agentDeployManifestV1Schema.safeParse(raw);
+    // `info` is opaque to the wire schema (validated as a plain object) but
+    // typed as AgentProjectInfo for producers/consumers inside the SDK.
+    return parsed.success
+        ? parsed.data
+        : undefined;
+}

package/dist/internal/deployment-scm-event-stream.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Deployment-scoped SCM event intake for hosted multi-tenant agents.
+ *
+ * Instead of receiving HMAC-signed webhook forwards from the backend (which
+ * required a shared `GITHUB_WEBHOOK_SECRET` / forward-secret pair), the
+ * engine pulls its deliveries from the control plane's deployment-scoped
+ * event stream:
+ *
+ *   GET /internal/agent-serve/automation-agent-sdk/events
+ *
+ * authenticated with the engine pod's `CURSOR_API_KEY` — the same
+ * credential (and server-side deployment allowlist) that authorizes the
+ * consuming agent's customer list read. The backend writes each envelope's
+ * `installationId` itself from the verified GitHub delivery, so agent-side
+ * tenant binding does not depend on an HMAC-covered payload.
+ *
+ * Each envelope is stubbed into a GitHub-shaped `pull_request` webhook body
+ * and POSTed to this process's own github channel route over loopback
+ * (admitted by the channel's no-secret `localDevStrict` policy), so the
+ * consuming agent's whole pipeline — Zod parse, cursorAccount credential
+ * lease, customer routing, tools — runs unchanged. Loopback (rather than
+ * the in-process `handleAgentServeTrigger` fan-out the `--cursor-events`
+ * relay uses) is deliberate: this stream is started from a channel's
+ * `onStart`, which cannot reach the serve-level mount/handler wiring.
+ *
+ * Offsets are client-owned (`<ms>-<seq>` Redis stream ids) and persisted
+ * under the state dir so a restart resumes where it left off instead of
+ * dropping deliveries (the old push path was fire-and-forget).
+ *
+ * INTERNAL: first-party host plumbing shared by agents in `factory/*`.
+ * Consumed via relative source imports, following
+ * `tenant-mcp/run-mcp-registry.ts`. Policy (which deliveries to act on,
+ * tenant routing) stays in the consuming agent; this module is transport
+ * only.
+ */
+export interface AgentSdkScmPullRequestMeta {
+    number: number;
+    url: string;
+    title: string;
+    body?: string | null | undefined;
+    draft?: boolean | undefined;
+    merged?: boolean | undefined;
+    authorLogin?: string | undefined;
+    headRef: string;
+    headSha: string;
+    baseRef: string;
+    baseSha?: string | undefined;
+}
+/** One entry from the deployment-scoped control-plane event stream. */
+export interface AgentSdkScmEventEnvelope {
+    provider: "github";
+    eventName: string;
+    deliveryId: string;
+    repo: string;
+    receivedAtMs: number;
+    action: string;
+    /** Tenant-binding material, written by the control plane. */
+    installationId: number;
+    pullRequest: AgentSdkScmPullRequestMeta;
+    occurredAtMs?: number | undefined;
+}
+/** Unknown envelope shapes return undefined (skipped, forward compat). */
+export declare function parseAgentSdkScmEventEnvelope(value: unknown): AgentSdkScmEventEnvelope | undefined;
+/** Whether a webhook body was self-dispatched by this event stream. */
+export declare function isDeploymentEventStreamPayload(payload: unknown): boolean;
+/**
+ * Stub a GitHub-shaped `pull_request` webhook body from an envelope —
+ * enough for agent-serve's pull_request Zod schema, plus `installation.id`
+ * so the channel's `ctx.installationId` tenant binding keeps working, plus
+ * the {@link isDeploymentEventStreamPayload} source marker.
+ * Pure — exported for tests.
+ */
+export declare function envelopeToGitHubPayload(envelope: AgentSdkScmEventEnvelope): Record<string, unknown>;
+export interface AgentSdkEventStreamOptions {
+    logger?: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+    /** Injected for tests (default `process.argv`). */
+    argv?: readonly string[];
+    /**
+     * Prefix for the consumer-scoped env overrides
+     * `<prefix>_SELF_WEBHOOK_URL` and `<prefix>_EVENTS_STATE_DIR`
+     * (default `AGENT_SERVE`; e.g. the security reviewer passes
+     * `SECURITY_REVIEWER` to keep its existing deployment env vars working).
+     */
+    envPrefix?: string;
+    /** Log-line prefix (default `agent-sdk/deployment-events`). */
+    logLabel?: string;
+    /**
+     * Offset state directory name under `<cwd>/.agent-serve`
+     * (default `deployment-events`). Consumers with persisted offsets must
+     * keep their historical name or a restart re-anchors at `$`.
+     */
+    stateDirName?: string;
+}
+/**
+ * Port the serve process is actually listening on, read from its own argv.
+ *
+ * The channel runs inside the serve process, so `--port <n>` / `--port=<n>`
+ * on the command line is authoritative. Hosted-platform engines start with
+ * `--port 26100` and export no `PORT` env, so guessing a fixed default posts
+ * self-dispatches at a port nothing listens on ("fetch failed" for every
+ * delivery).
+ */
+export declare function servePortFromArgv(argv: readonly string[]): string | undefined;
+export interface AgentSdkEventStream {
+    stop(): Promise<void>;
+}
+/**
+ * Start the pull loop. Returns undefined (with a log line) when required
+ * config is missing so `serve` still starts — mirroring how other relays
+ * degrade instead of failing the host.
+ */
+export declare function startAgentSdkEventStream(options?: AgentSdkEventStreamOptions): AgentSdkEventStream | undefined;
+//# sourceMappingURL=deployment-scm-event-stream.d.ts.map

package/dist/internal/deployment-scm-event-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-scm-event-stream.d.ts","sourceRoot":"","sources":["../../src/internal/deployment-scm-event-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AA2BH,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,uEAAuE;AACvE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,0BAA0B,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAiED,0EAA0E;AAC1E,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,wBAAwB,GAAG,SAAS,CAqCtC;AA8CD,uEAAuE;AACvE,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,wBAAwB,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BzB;AAmDD,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,0BAA0B;IAC1B,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,mDAAmD;IACnD,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAkB7E;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAeD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,GAAG,SAAS,CAwLjC"}