@cursor/july 0.1.61 → 0.1.68

package/src/internal/cli-deploy.ts

@@ -22,6 +22,7 @@ import {
   SIGN_IN_HINT,
 } from "./cursor/credentials.js";
 import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
+import { readDeployTemplate } from "./cursor-agent-template.js";
 import {
   AgentServeDeployClient,
   type DeleteAccepted,
@@ -38,6 +39,10 @@ import {
   TERMINAL_DEPLOY_STATUSES,
   validateDeploymentSlug,
 } from "./deploy-client.js";
+import {
+  type AgentDeployManifestV1,
+  buildAgentDeployManifest,
+} from "./deploy-manifest.js";
 import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
 import {
   type ChildAgentDir,
@@ -661,11 +666,19 @@ async function deployOne(
     ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
     publicRoutePaths:
       publicRoutePaths.length === 0 ? undefined : publicRoutePaths,
+    // Offline metadata extraction (Wd): the CP persists this before any VM
+    // starts. Directories without an agent project send no manifest.
+    ...(manifest === undefined ? {} : { manifest: manifest.deployManifest }),
   };
 
   let accepted: DeployAccepted;
   try {
-    accepted = await ctx.client.deploy({ teamId: ctx.teamId, slug, source });
+    accepted = await ctx.client.deploy({
+      teamId: ctx.teamId,
+      slug,
+      source,
+      template: readDeployTemplate(dir),
+    });
   } catch (error) {
     return renderApiError(error, ctx.err);
   }
@@ -851,6 +864,13 @@ interface DeployManifest {
    * (only `/v1/channels/…` subtrees can be public); surfaced as a warning.
    */
   httpChannelPublicEndpoint: boolean;
+  /**
+   * The offline deploy manifest (Wd): derived event declarations, channel
+   * kinds, egress, routes, and the full `/v1/info` payload. Attached to the
+   * deploy request so the control plane stores metadata before any VM
+   * starts; servers that predate manifest storage strip the field.
+   */
+  deployManifest: AgentDeployManifestV1;
 }
 
 /**
@@ -875,6 +895,7 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
     httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(
       isPublicEndpointPolicy
     ),
+    deployManifest: buildAgentDeployManifest(project),
   };
 }
 

package/src/internal/cli-manifest.ts

@@ -0,0 +1,63 @@
+/**
+ * `july manifest` — print the offline deploy manifest (Wd-1 of
+ * `docs/agent-serve/agent-sdk-event-ingress-plan.md`).
+ *
+ * Loads the agent project from disk and emits the statically-derived
+ * metadata the control plane stores at deploy time: declared GitHub webhook
+ * events, egress domains, public routes, and the full `/v1/info` payload.
+ * Runs entirely offline — no VM, no engine, no network.
+ */
+
+import {
+  buildAgentDeployManifest,
+  parseAgentDeployManifest,
+} from "./deploy-manifest.js";
+import { isAgentProjectDir, loadAgentProject } from "./discovery.js";
+
+export interface CmdManifestOptions {
+  dir: string;
+  /** Compact single-line JSON (machine consumption); default pretty. */
+  json?: boolean;
+  /** Test seams. */
+  out?: (line: string) => void;
+  err?: (line: string) => void;
+}
+
+export async function cmdManifest(
+  options: CmdManifestOptions
+): Promise<number> {
+  const out = options.out ?? ((line: string) => process.stdout.write(line));
+  const err = options.err ?? ((line: string) => process.stderr.write(line));
+
+  if (!(await isAgentProjectDir(options.dir))) {
+    err(
+      `No agent project found at ${options.dir} (expected an agent.ts default-exporting defineAgent({ ... })).\n`
+    );
+    return 1;
+  }
+
+  const project = await loadAgentProject(options.dir);
+  for (const diagnostic of project.diagnostics) {
+    err(`${diagnostic.severity}: ${diagnostic.message}\n`);
+  }
+  if (project.diagnostics.some((d) => d.severity === "error")) {
+    return 1;
+  }
+
+  const manifest = buildAgentDeployManifest(project);
+  // Round-trip through the wire schema so `july manifest` can never emit
+  // something the control plane contract would reject.
+  if (
+    parseAgentDeployManifest(JSON.parse(JSON.stringify(manifest))) === undefined
+  ) {
+    err("internal error: generated manifest failed schema validation\n");
+    return 1;
+  }
+
+  out(
+    options.json === true
+      ? `${JSON.stringify(manifest)}\n`
+      : `${JSON.stringify(manifest, null, 2)}\n`
+  );
+  return 0;
+}

package/src/internal/cli-slack.ts

@@ -402,7 +402,16 @@ function writePendingAdminWait(
       ? poll.oauthAuthorizeUrl
       : undefined;
   ctx.err(`Waiting for a Slack admin to approve the app${appSuffix}.\n\n`);
-  if (requestUrl !== undefined) {
+  if (poll.approvalRequest === "pending") {
+    // Already in the admin queue: nothing to file, so no browser hop.
+    ctx.err(
+      ctx.dim(`  Approval request sent; workspace owners were notified.\n\n`)
+    );
+    if (requestUrl !== undefined) {
+      ctx.err(ctx.dim(`  Send a reminder from:\n\n`));
+      ctx.err(`  ${requestUrl}\n\n`);
+    }
+  } else if (requestUrl !== undefined) {
     ctx.err(
       ctx.dim(
         `  Slack will notify workspace owners once the request is in their queue.\n` +

package/src/internal/cursor-agent-template.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MAX = 64;
+const TEMPLATE_NAMES = [
+  "agentic-owners",
+  "demo",
+  "pr-autofixer",
+  "security-reviewer",
+  "triage-linear",
+  "triage-jira",
+] as const;
+export type TemplateName = (typeof TEMPLATE_NAMES)[number];
+const NAMES = new Set<string>(TEMPLATE_NAMES);
+
+export function canonicalTemplateName(name: string): string {
+  return name === "triage" ? "triage-linear" : name;
+}
+
+export function isTemplateName(name: string): name is TemplateName {
+  return NAMES.has(name);
+}
+
+/** Raw scaffold marker. Validation depends on the consuming boundary. */
+export function readCursorAgentTemplate(rootDir: string): string | undefined {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(rootDir, "package.json"), "utf8")
+    ) as {
+      cursorAgentTemplate?: unknown;
+    };
+    const stamp = pkg.cursorAgentTemplate;
+    return typeof stamp === "string" ? stamp : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readDeployTemplate(rootDir: string): string | undefined {
+  const stamp = readCursorAgentTemplate(rootDir);
+  if (stamp === undefined || stamp.length === 0 || stamp.length > MAX) {
+    return undefined;
+  }
+  const name = canonicalTemplateName(stamp);
+  return isTemplateName(name) ? name : undefined;
+}

package/src/internal/cursor-event-relay.ts

@@ -91,7 +91,7 @@ export type CursorScmWorkflowRunMeta = CursorScmCiBaseMeta & {
   workflowId?: number;
 };
 
-/** One event delivered by `GET /v0/scm-events` (metadata only). */
+/** One event delivered by `GET /v0/scm-events`. */
 export interface CursorScmEvent {
   offset: string;
   provider: string;
@@ -99,6 +99,8 @@ export interface CursorScmEvent {
   deliveryId?: string;
   repo: string;
   receivedAtMs: number;
+  /** Verified webhook body when the API stored it. */
+  payload?: unknown;
   /** Webhook `action` when present. */
   action?: string;
   /** PR number when the delivery is PR-scoped. */
@@ -235,6 +237,11 @@ function readDispatchError(body: unknown): string | undefined {
   return typeof error === "string" && error !== "" ? error : undefined;
 }
 
+/** Stored webhook body, or a metadata stub for older stream entries. */
+export function scmEventToGitHubPayload(event: CursorScmEvent): unknown {
+  return event.payload ?? scmMetadataToGitHubPayload(event);
+}
+
 /**
  * Minimal GitHub webhook body from an SCM-events metadata envelope.
  * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid

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;
+}