@cursor/bdk 0.2.1

package/src/internal/deploy-manifest.ts

@@ -0,0 +1,361 @@
+/**
+ * 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 {
+  type CatchAuthDeclaration,
+  catchAuthDeclaration,
+  isPublicEndpointPolicy,
+} from "../channels.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
+import type { AgentProject, AgentProjectInfo } from "../types.js";
+import {
+  applyAgentContinuationDefaults,
+  channelContinuationIdentity,
+  channelDeclaredEventTypes,
+  handshakeChannelContinuation,
+} from "./continuation-channel.js";
+import { CONTINUATION_SELECTORS, type ContinuationIdentity } from "./continuation-identity.js";
+import { projectInfo, runtimeArchitectureCompatibilityError } from "./discovery.js";
+import { packageGitSha, 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 continuationIdentitySchema = z.enum(CONTINUATION_SELECTORS);
+
+const CATCH_MAX_ROUTES = 32;
+const CATCH_MAX_AUTH_POLICIES = 4;
+
+const catchDeclarationSchema = z.object({
+  routes: z
+    .array(
+      z.object({
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+        path: z.string().min(1).max(1024),
+      }),
+    )
+    .min(1)
+    .max(CATCH_MAX_ROUTES),
+  auth: z
+    .array(
+      z.discriminatedUnion("kind", [
+        z.object({
+          kind: z.literal("header"),
+          header: z.string().min(1).max(128),
+          secret: z.string().min(1).max(64),
+        }),
+        z.object({
+          kind: z.literal("hmac-sha256"),
+          header: z.string().min(1).max(128),
+          secret: z.string().min(1).max(64),
+          prefix: z.string().max(32).optional(),
+        }),
+        z.object({ kind: z.literal("public") }),
+      ]),
+    )
+    .min(1)
+    .max(CATCH_MAX_AUTH_POLICIES),
+});
+
+const slackReplyDeclarationSchema = z.object({
+  mode: z.literal("agentic"),
+  ack: z.string().regex(/^[a-z0-9_+-]{1,50}$/),
+  placeholder: z
+    .string()
+    .regex(/^(?!.*(?:<!|<@))[^\r\n]{2,80}$/)
+    .optional(),
+});
+
+const agentDeployManifestV1Schema = z.object({
+  manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
+  generatedAtMs: z.number().int().nonnegative(),
+  cliVersion: z.string().min(1),
+  cliGitSha: z
+    .string()
+    .regex(/^[0-9a-f]{40,64}$/)
+    .optional(),
+  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(),
+    architecture: z.enum(["v1", "v2"]).optional(),
+    persistent: z.boolean().optional(),
+    image: z.string().min(2).max(64).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(),
+          continuation: continuationIdentitySchema,
+          catch: catchDeclarationSchema.optional(),
+          slackReply: slackReplyDeclarationSchema.optional(),
+          slackChannelPosts: z.array(z.string().min(1).max(80)).max(64).optional(),
+        }),
+      )
+      .max(64),
+  }),
+  // Full `projectInfo` payload — opaque to the wire contract.
+  info: z.record(z.unknown()),
+});
+
+export interface AgentDeployManifestDeclarations {
+  egressDomains: string[];
+  publicRoutePaths: string[];
+  /** Where this runtime mirrors framework-owned sessions and event chunks. */
+  frameworkStorage?: "cursor-hosted" | "other" | "none";
+  /**
+   * Hosted architecture this release deploys onto. `"v2"` selects the v2
+   * control plane; omitted channel constructors inherit kind `/v2`
+   * continuation defaults. Omit or `"v1"` keeps engine minting.
+   */
+  architecture?: "v1" | "v2";
+  persistent?: boolean;
+  /** `hosting.image`: the team container image the deployed agent runs in. */
+  image?: string;
+  /**
+   * Mounted channels with their kinds and per-channel event capability.
+   * Scope keys are installation config and are never extracted here.
+   * Omitted channel `continuation` is `/v1` (engine minting) unless the
+   * agent set `architecture: "v2"`, which stamps kind `/v2` defaults
+   * (`github.pr/v2`, `slack.thread/v2`, `origin.pr/v2`,
+   * `deployments.deployment/v2`). Per-channel selectors still override type.
+   */
+  channels: Array<{
+    id: string;
+    kind?: string;
+    eventTypes?: string[];
+    continuation: ContinuationIdentity;
+    /**
+     * Static Slack response settings the control plane may apply before the
+     * hosted runtime starts. Present only for `slack` channels in agentic mode.
+     */
+    slackReply?: AgentDeployManifestSlackReplyDeclaration;
+    /**
+     * The channel-watch allowlist (`engagement.channelPosts.allow`).
+     * Present only for `slack` channels that watch channel posts. The
+     * control plane materializes channel-scoped subscription edges from
+     * the channel-id entries so posts outside the allowlist drop at
+     * ingress.
+     */
+    slackChannelPosts?: string[];
+    /**
+     * Control-plane catch routes: present only for an authored channel
+     * whose auth chain carries a `sharedSecretAuth` / `hmacSignatureAuth`
+     * policy. The control plane accepts exactly these `(method, path)`
+     * pairs and verifies the named deployment secret before any compute.
+     */
+    catch?: AgentDeployManifestCatchDeclaration;
+  }>;
+}
+
+export interface AgentDeployManifestCatchDeclaration {
+  routes: Array<{
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+  }>;
+  auth: CatchAuthDeclaration[];
+}
+
+export interface AgentDeployManifestSlackReplyDeclaration {
+  mode: "agentic";
+  /** Normalized Slack emoji name without colons. */
+  ack: string;
+  /** Exact static replaceable first line. */
+  placeholder?: string;
+}
+
+export interface AgentDeployManifestV1 {
+  manifestVersion: 1;
+  /** Unix ms at extraction. */
+  generatedAtMs: number;
+  /** `@cursor/bdk` version that produced the manifest. */
+  cliVersion: string;
+  /** Git commit for a checkout-built `@cursor/bdk`; absent for npm builds. */
+  cliGitSha?: 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; cliGitSha?: string },
+): AgentDeployManifestV1 {
+  const runtimeArchitectureError = runtimeArchitectureCompatibilityError(project.agent);
+  if (runtimeArchitectureError !== undefined) {
+    throw new Error(runtimeArchitectureError);
+  }
+  applyAgentContinuationDefaults(project);
+  const channels = project.channels.map(channel => {
+    const handshake = handshakeChannelContinuation(channel);
+    if (!handshake.ok) {
+      throw new Error(handshake.error);
+    }
+    const kind = channel.definition.meta?.kind;
+    const meta = channel.definition.meta;
+    const declaredEvents = channelDeclaredEventTypes(channel.definition.meta);
+    const eventTypes = declaredEvents === undefined ? undefined : [...declaredEvents].sort();
+    return {
+      id: channel.id,
+      kind,
+      eventTypes,
+      continuation: channelContinuationIdentity(channel.definition),
+      catch: channelCatchDeclaration(channel.definition),
+      ...(kind === "slack" && meta?.slackReply !== undefined
+        ? { slackReply: meta.slackReply }
+        : {}),
+      ...(kind === "slack" && meta?.slackChannelPosts !== undefined
+        ? { slackChannelPosts: [...meta.slackChannelPosts] }
+        : {}),
+    };
+  });
+
+  // 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}`);
+
+  const manifest: AgentDeployManifestV1 = {
+    manifestVersion: DEPLOY_MANIFEST_VERSION,
+    generatedAtMs: options?.nowMs ?? Date.now(),
+    cliVersion: options?.cliVersion ?? packageVersion(),
+    cliGitSha: options?.cliGitSha ?? packageGitSha(),
+    declarations: {
+      egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
+      publicRoutePaths,
+      // Deploy manifests describe Cursor-hosted deployments. When the agent
+      // authors no storage, framework-storage-selection.ts injects the
+      // platform Cursor-hosted mirror for both v1 and v2.
+      frameworkStorage:
+        project.storage === undefined
+          ? "cursor-hosted"
+          : isCursorHostedStorage(project.storage)
+            ? "cursor-hosted"
+            : "other",
+      ...(project.agent.architecture === undefined
+        ? {}
+        : { architecture: project.agent.architecture }),
+      persistent: project.agent.persistent,
+      ...(project.agent.hosting?.image === undefined ? {} : { image: project.agent.hosting.image }),
+      channels,
+    },
+    info: projectInfo(project),
+  };
+  const validation = agentDeployManifestV1Schema.safeParse(manifest);
+  if (!validation.success) {
+    const issues = validation.error.issues
+      .map(issue => `${issue.path.join(".")}: ${issue.message}`)
+      .join("; ");
+    throw new Error(`Invalid Agent SDK deploy manifest: ${issues}`);
+  }
+  return manifest;
+}
+
+/**
+ * Catch declaration for one authored channel: its routes, gated by the
+ * catch-capable policies in its auth chain (`sharedSecretAuth`,
+ * `hmacSignatureAuth`, or `publicEndpoint()` for handler-verified routes).
+ * A routed channel with none of those declares nothing and is not reachable
+ * through the catch API.
+ */
+export function channelCatchDeclaration(
+  definition: AgentProject["channels"][number]["definition"],
+): AgentDeployManifestCatchDeclaration | undefined {
+  const routes = definition.routes ?? [];
+  if (routes.length === 0) {
+    return undefined;
+  }
+  const declared = (definition.auth ?? [])
+    .map(catchAuthDeclaration)
+    .filter(declaration => declaration !== undefined);
+  if (declared.length === 0) {
+    return undefined;
+  }
+  // An auth chain is any-of, so `publicEndpoint()` beside secret policies
+  // admits everything locally and on the control plane alike. Declare one
+  // `public` entry (the control plane then decrypts nothing) but keep the
+  // shared-secret header policies next to it: they are what the control
+  // plane uses to strip those header values before the request is
+  // claim-checked, and senders keep sending the secret regardless of
+  // whether anything still checks it. HMAC policies carry body digests,
+  // not secrets, so nothing is lost by dropping them.
+  const isPublic = declared.some(policy => policy.kind === "public");
+  const auth = isPublic
+    ? [{ kind: "public" as const }, ...declared.filter(policy => policy.kind === "header")]
+    : declared;
+  if (routes.length > CATCH_MAX_ROUTES) {
+    if (isPublic) {
+      // publicEndpoint() channels deployed before catch existed; they stay
+      // reachable the way they were (not through catch) rather than
+      // failing the deploy.
+      return undefined;
+    }
+    throw new Error(
+      `Catch channels may declare at most ${CATCH_MAX_ROUTES} routes (got ${routes.length}).`,
+    );
+  }
+  if (auth.length > CATCH_MAX_AUTH_POLICIES) {
+    throw new Error(
+      isPublic
+        ? `Catch channels may declare at most ${CATCH_MAX_AUTH_POLICIES} auth policies; publicEndpoint() plus ${String(auth.length - 1)} sharedSecretAuth() policies is ${String(auth.length)}. Drop publicEndpoint() or the shared-secret policies it makes dead.`
+        : `Catch channels may declare at most ${CATCH_MAX_AUTH_POLICIES} secret policies (got ${auth.length}).`,
+    );
+  }
+  return {
+    routes: routes.map(route => ({ method: route.method, path: route.path })),
+    auth,
+  };
+}
+
+/**
+ * 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;
+}

package/src/internal/deploy-source.ts

@@ -0,0 +1,144 @@
+/**
+ * Infer `agent-sdk deploy` git source fields from a local checkout.
+ *
+ * From an agent directory inside a git repo with an `origin` remote, the
+ * CLI can fill `--repo` / `--ref` / `--path` so `agent-sdk deploy` (no
+ * flags) is enough. Explicit flags always win.
+ */
+
+import { execFile } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** Injectable git runner (cwd + args → stdout, or undefined on failure). */
+export type GitRunner = (args: readonly string[], cwd: string) => Promise<string | undefined>;
+
+export interface InferredDeploySource {
+  gitRepoUrl?: string;
+  gitRef?: string;
+  /** Agent directory relative to the repo root (posix). Omitted at root. */
+  agentPath?: string;
+}
+
+const defaultGitRunner: GitRunner = async (args, cwd) => {
+  try {
+    const { stdout } = await execFileAsync("git", [...args], { cwd });
+    const trimmed = stdout.trim();
+    return trimmed === "" ? undefined : trimmed;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Normalize a git remote URL to the https form the control plane accepts
+ * (`https://host/owner/repo`, no `.git` suffix). Returns undefined for
+ * unrecognized shapes.
+ *
+ * Accepts HTTPS, `git@host:path`, GitHub org-scoped SSH
+ * (`org-123@github.com:owner/repo.git`), and `ssh://user@host[:port]/path`.
+ */
+export function httpsGitRepoUrlFromRemote(remote: string): string | undefined {
+  let url = remote.trim();
+  if (url === "") {
+    return undefined;
+  }
+
+  // SCP-like SSH: user@host:owner/repo(.git) — includes git@ and GitHub
+  // org deploy keys (org-NNNN@github.com:…).
+  const scpMatch = /^([^@/\s]+)@([^:/\s]+):(.+)$/.exec(url);
+  if (scpMatch !== null) {
+    const host = scpMatch[2]!;
+    const path = scpMatch[3]!;
+    url = `https://${host}/${path}`;
+  } else if (/^ssh:\/\//i.test(url)) {
+    // ssh://user@host[:port]/owner/repo → https://host/owner/repo
+    try {
+      const ssh = new URL(url);
+      const path = ssh.pathname.replace(/^\/+/, "");
+      if (ssh.hostname === "" || path === "") {
+        return undefined;
+      }
+      url = `https://${ssh.hostname}/${path}`;
+    } catch {
+      return undefined;
+    }
+  } else if (!/^https?:\/\//i.test(url)) {
+    return undefined;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  const path = parsed.pathname
+    .replace(/\.git$/i, "")
+    .replace(/\/+$/, "")
+    .replace(/^\/+/, "");
+  if (path === "" || !path.includes("/")) {
+    return undefined;
+  }
+  // Use hostname (not host) so ssh://…@github.com:22/… does not keep :22.
+  return `https://${parsed.hostname}/${path}`;
+}
+
+/**
+ * Path of `dir` relative to `gitRoot`, using `/` separators. Undefined when
+ * `dir` is outside the root; omitted (undefined) when `dir` *is* the root
+ * so the control plane treats the agent as living at the repo root.
+ */
+export function agentPathRelativeToGitRoot(dir: string, gitRoot: string): string | undefined {
+  const absDir = resolve(dir);
+  const absRoot = resolve(gitRoot);
+  const rel = relative(absRoot, absDir);
+  if (rel === "") {
+    return undefined;
+  }
+  // Outside the repo (or a Windows drive mismatch) → cannot infer.
+  if (rel.startsWith("..") || rel.split(sep).includes("..")) {
+    return undefined;
+  }
+  return rel.split(sep).join("/");
+}
+
+/**
+ * Probe the git checkout containing `dir` for deploy source fields.
+ * Missing pieces stay undefined.
+ */
+export async function inferDeployGitSource(
+  dir: string,
+  options?: { git?: GitRunner },
+): Promise<InferredDeploySource> {
+  const git = options?.git ?? defaultGitRunner;
+  const absDir = resolve(dir);
+
+  const gitRoot = await git(["rev-parse", "--show-toplevel"], absDir);
+  if (gitRoot === undefined) {
+    return {};
+  }
+
+  const remote = await git(["remote", "get-url", "origin"], gitRoot);
+  const gitRepoUrl = remote === undefined ? undefined : httpsGitRepoUrlFromRemote(remote);
+
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], gitRoot);
+  let gitRef: string | undefined;
+  if (branch !== undefined && branch !== "HEAD") {
+    gitRef = branch;
+  } else {
+    // Detached HEAD — pin the exact commit so the control plane still
+    // has something concrete to build.
+    gitRef = await git(["rev-parse", "HEAD"], gitRoot);
+  }
+
+  const agentPath = agentPathRelativeToGitRoot(absDir, gitRoot);
+
+  return {
+    gitRepoUrl,
+    gitRef,
+    agentPath,
+  };
+}

package/src/internal/describe-error.ts

@@ -0,0 +1,32 @@
+/** Stable string for logging / HTTP error bodies. */
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function describeErrorCode(error: unknown): string | undefined {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const numericCode = (error as { code?: unknown }).code;
+    if (numericCode === 1) {
+      return "canceled";
+    }
+    if (numericCode === 14) {
+      return "unavailable";
+    }
+    if (numericCode === 2) {
+      return "unknown";
+    }
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error as { name?: unknown }).name === "AbortError"
+  ) {
+    return "ABORT_ERR";
+  }
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return undefined;
+  }
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" && code.length <= 64 ? code : undefined;
+}

package/src/internal/dev-mode.ts

@@ -0,0 +1,20 @@
+/**
+ * Process-wide dev-mode flag.
+ *
+ * Channels are constructed at module import time (during discovery), before a
+ * channel factory like `githubChannel()` ever sees the server's `--dev` flag.
+ * `serve()` sets this flag *before* discovery so those factories can relax
+ * dev-only defaults (e.g. the GitHub channel admitting loopback-forwarded
+ * webhook deliveries without a signing secret). It never affects prod: outside
+ * `--dev` the flag stays false and strict defaults apply.
+ */
+
+let devMode = false;
+
+export function setDevMode(value: boolean): void {
+  devMode = value;
+}
+
+export function isDevMode(): boolean {
+  return devMode;
+}