@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/deploy-manifest.ts

@@ -1,361 +0,0 @@
-/**
- * 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

@@ -1,144 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-/** 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

@@ -1,20 +0,0 @@
-/**
- * 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;
-}