@cursor/july 0.1.62 → 0.1.68

package/src/internal/deploy-client.ts

@@ -11,6 +11,7 @@
  */
 
 import { z } from "zod";
+import type { AgentDeployManifestV1 } from "./deploy-manifest.js";
 import {
   MAX_SECRET_VALUE_BYTES,
   MAX_SECRETS,
@@ -74,6 +75,12 @@ export type DeploySource = {
    * `X-Agent-Alias-Token` (channels authored with `publicEndpoint()`).
    */
   publicRoutePaths?: string[];
+  /**
+   * Offline deploy manifest (Wd): derived declarations + `/v1/info`
+   * payload, extracted at deploy time with no VM. Optional — servers that
+   * predate manifest storage strip unknown fields.
+   */
+  manifest?: AgentDeployManifestV1;
 };
 
 const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
@@ -422,6 +429,7 @@ export class AgentServeDeployClient {
     teamId: number;
     slug: string;
     source: DeploySource;
+    template?: string;
   }): Promise<DeployAccepted> {
     const slugError = validateDeploymentSlug(args.slug);
     if (slugError !== undefined) {
@@ -453,13 +461,34 @@ export class AgentServeDeployClient {
         : { egressAllowedDomains: args.source.egressAllowedDomains }),
       // JSON.stringify drops undefined keys.
       publicRoutePaths: args.source.publicRoutePaths,
+      ...(args.source.manifest === undefined
+        ? {}
+        : { manifest: args.source.manifest }),
+      template: args.template,
     };
-    const raw = await this.request({
-      method: "POST",
-      path: "/internal/agent-serve/deployments",
-      body,
-      context: { verb: "deploy", slug: args.slug },
-    });
+    const send = (): Promise<unknown> =>
+      this.request({
+        method: "POST",
+        path: "/internal/agent-serve/deployments",
+        body,
+        context: { verb: "deploy", slug: args.slug },
+      });
+    let raw: unknown;
+    try {
+      raw = await send();
+    } catch (error) {
+      const unsupportedTemplate =
+        args.template !== undefined &&
+        error instanceof DeployApiError &&
+        error.status === 400 &&
+        error.message.toLowerCase().includes("template") &&
+        /unrecognized|unknown/i.test(error.message);
+      if (!unsupportedTemplate) {
+        throw error;
+      }
+      delete body.template;
+      raw = await send();
+    }
     return deployAcceptedSchema.parse(raw);
   }
 

package/src/internal/deploy-manifest.ts

@@ -0,0 +1,167 @@
+/**
+ * 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): GitHub webhook events the mounted channels can
+ *   dispatch on, 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 `githubChannel()` publishes its
+ * derived event set on `ChannelMeta.githubWebhookEvents` (computed by
+ * `deriveGitHubWebhookEvents` from the declared hooks). The manifest is the
+ * union across mounted channels; a project with no GitHub channel gets no
+ * `githubWebhookEvents` key at all — such a deployment subscribes to
+ * nothing, regardless of the repos configured at deploy time.
+ */
+
+import { z } from "zod";
+import { isPublicEndpointPolicy } from "../channels.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
+import type { AgentProject, AgentProjectInfo } from "../types.js";
+import { projectInfo } from "./discovery.js";
+import { packageVersion } from "./distribution.js";
+
+export const DEPLOY_MANIFEST_VERSION: 1 = 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({
+    githubWebhookEvents: z.array(z.string().min(1).max(64)).max(64).optional(),
+    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(),
+        })
+      )
+      .max(64),
+  }),
+  // Full `projectInfo` payload — opaque to the wire contract.
+  info: z.record(z.unknown()),
+});
+
+export interface AgentDeployManifestDeclarations {
+  /**
+   * Union of every mounted GitHub channel's derived webhook events.
+   * Absent (not empty) when the project mounts no GitHub channel.
+   */
+  githubWebhookEvents?: string[];
+  egressDomains: string[];
+  publicRoutePaths: string[];
+  /** Where this runtime mirrors framework-owned sessions and event chunks. */
+  frameworkStorage?: "cursor-hosted" | "other" | "none";
+  /**
+   * Mounted channels with their kinds. The control plane derives the
+   * continuation identity (session key) for **defined** kinds it knows
+   * ("github", "slack"); a custom channel with no kind gets per-deployment
+   * serialization until a declared continuation config exists (a future
+   * schema field — reserved, deliberately not implemented yet). This is
+   * what lets the CP compute workflow/session identity before any engine
+   * runs.
+   */
+  channels: Array<{ id: string; kind?: 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 function buildAgentDeployManifest(
+  project: AgentProject,
+  options?: { nowMs?: number; cliVersion?: string }
+): AgentDeployManifestV1 {
+  const events = new Set<string>();
+  for (const channel of project.channels) {
+    for (const event of channel.definition.meta?.githubWebhookEvents ?? []) {
+      events.add(event);
+    }
+  }
+
+  // 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) =>
+      (channel.definition.auth ?? []).some(isPublicEndpointPolicy)
+    )
+    .map((channel) => `/v1/channels/${channel.id}`);
+
+  return {
+    manifestVersion: DEPLOY_MANIFEST_VERSION,
+    generatedAtMs: options?.nowMs ?? Date.now(),
+    cliVersion: options?.cliVersion ?? packageVersion(),
+    declarations: {
+      ...(events.size === 0 ? {} : { githubWebhookEvents: [...events].sort() }),
+      egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
+      publicRoutePaths,
+      frameworkStorage:
+        project.storage === undefined
+          ? "none"
+          : isCursorHostedStorage(project.storage)
+            ? "cursor-hosted"
+            : "other",
+      channels: project.channels.map((channel) => ({
+        id: channel.id,
+        ...(channel.definition.meta?.kind === undefined
+          ? {}
+          : { kind: channel.definition.meta.kind }),
+      })),
+    },
+    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: unknown
+): AgentDeployManifestV1 | undefined {
+  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 as unknown as AgentDeployManifestV1)
+    : undefined;
+}