@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/handleAgentServeTrigger.ts

@@ -1,286 +0,0 @@
-/**
- * Unified entry for dispatching agent-serve triggers from an external ingress
- * (e.g. the Cursor backend GitHub webhook or Origin cursor-internal tap).
- * Mirrors Automations' `handleAutomationTrigger`.
- *
- * Callers must authenticate the delivery before invoking this (the backend
- * verifies GitHub HMAC at `/github_webhook` and Origin v1ed at the
- * cursor-internal app). This fan-out does not re-check signatures — same
- * trust model as Bugbot after `verifyGithubRequest`.
- *
- * Each agent's `onPullRequest` / `onComment` / … hooks decide whether to run.
- */
-
-import {
-  dispatchGitHubWebhook,
-  getGitHubChannelOptions,
-} from "../channels/github/github-channel.js";
-import type { GitHubChannelOptions } from "../channels/github/types.js";
-import {
-  dispatchOriginWebhook,
-  getOriginChannelOptions,
-  originIngressExtractPayload,
-  parseOriginWebhookEnvelope,
-} from "../channels/origin/origin-channel.js";
-import type { OriginChannelOptions } from "../channels/origin/types.js";
-import type { ChannelHandlerArgs } from "../types.js";
-import { bindLocalIngressSend, type RouteLocalIngressContinuation } from "./local-ingress.js";
-
-export interface AgentServeGitHubTriggerTarget {
-  /** Agent mount slug (empty string in single-agent mode). */
-  slug: string;
-  /** Options from the agent's `githubChannel({ ... })` definition. */
-  options: GitHubChannelOptions;
-  /** Per-agent channel handler args (`send`, `waitUntil`, `host`, …). */
-  args: ChannelHandlerArgs;
-}
-
-export interface AgentServeGitHubTriggerEvent {
-  type: "github";
-  /** Raw webhook body (signature already verified by the caller). */
-  bodyText: string;
-  eventName: string | null;
-  deliveryId?: string;
-  targets: AgentServeGitHubTriggerTarget[];
-  /** Local CP ingest. Defaults to {@link routeLocalIngressContinuation}. */
-  routeContinuation?: RouteLocalIngressContinuation;
-}
-
-export interface AgentServeOriginTriggerTarget {
-  slug: string;
-  options: OriginChannelOptions;
-  args: ChannelHandlerArgs;
-}
-
-export interface AgentServeOriginTriggerEvent {
-  type: "origin";
-  /** Origin envelope JSON (signature already verified by the caller). */
-  bodyText: string;
-  targets: AgentServeOriginTriggerTarget[];
-  /** Local CP ingest. Defaults to {@link routeLocalIngressContinuation}. */
-  routeContinuation?: RouteLocalIngressContinuation;
-}
-
-export type AgentServeTriggerEvent = AgentServeGitHubTriggerEvent | AgentServeOriginTriggerEvent;
-
-export interface AgentServeTriggerTargetResult {
-  slug: string;
-  status: number;
-  body: unknown;
-}
-
-export interface AgentServeTriggerResult {
-  ok: boolean;
-  event: string | null;
-  targets: AgentServeTriggerTargetResult[];
-}
-
-/**
- * Build fan-out targets from mounted agent projects that export a github
- * channel created via {@link githubChannel}.
- */
-export function collectGitHubTriggerTargets(input: {
-  mounts: Array<{
-    slug: string;
-    channels: Array<{ id: string; definition: object }>;
-    buildHandlerArgs: (channelId: string) => ChannelHandlerArgs;
-  }>;
-}): AgentServeGitHubTriggerTarget[] {
-  const targets: AgentServeGitHubTriggerTarget[] = [];
-  for (const mount of input.mounts) {
-    for (const channel of mount.channels) {
-      const options = getGitHubChannelOptions(channel.definition);
-      if (options === undefined) {
-        continue;
-      }
-      targets.push({
-        slug: mount.slug,
-        options,
-        args: mount.buildHandlerArgs(channel.id),
-      });
-    }
-  }
-  return targets;
-}
-
-/**
- * Build fan-out targets from mounted agent projects that export an origin
- * channel created via {@link originChannel}.
- */
-export function collectOriginTriggerTargets(input: {
-  mounts: Array<{
-    slug: string;
-    channels: Array<{ id: string; definition: object }>;
-    buildHandlerArgs: (channelId: string) => ChannelHandlerArgs;
-  }>;
-}): AgentServeOriginTriggerTarget[] {
-  const targets: AgentServeOriginTriggerTarget[] = [];
-  for (const mount of input.mounts) {
-    for (const channel of mount.channels) {
-      const options = getOriginChannelOptions(channel.definition);
-      if (options === undefined) {
-        continue;
-      }
-      targets.push({
-        slug: mount.slug,
-        options,
-        args: mount.buildHandlerArgs(channel.id),
-      });
-    }
-  }
-  return targets;
-}
-
-/**
- * Dispatch an agent-serve trigger. GitHub and Origin webhook fan-out.
- */
-export async function handleAgentServeTrigger(
-  event: AgentServeTriggerEvent,
-): Promise<AgentServeTriggerResult> {
-  switch (event.type) {
-    case "github":
-      return handleAgentServeGitHubTrigger(event);
-    case "origin":
-      return handleAgentServeOriginTrigger(event);
-    default: {
-      const _: never = event;
-      throw new Error(`handleAgentServeTrigger: unknown event type: ${String(_)}`);
-    }
-  }
-}
-
-async function handleAgentServeGitHubTrigger(
-  event: AgentServeGitHubTriggerEvent,
-): Promise<AgentServeTriggerResult> {
-  if (event.eventName === "ping") {
-    return {
-      ok: true,
-      event: "ping",
-      targets: [],
-    };
-  }
-
-  let payload: unknown;
-  try {
-    payload = JSON.parse(event.bodyText) as unknown;
-  } catch {
-    return {
-      ok: false,
-      event: event.eventName,
-      targets: [
-        {
-          slug: "",
-          status: 400,
-          body: { ok: false, error: "invalid_json" },
-        },
-      ],
-    };
-  }
-
-  const targets: AgentServeTriggerTargetResult[] = [];
-  for (const target of event.targets) {
-    const args =
-      event.eventName === null
-        ? target.args
-        : bindLocalIngressSend(target.args, {
-            identity: target.options.continuation,
-            kind: "github",
-            eventType: event.eventName,
-            payload,
-            ...(event.routeContinuation === undefined
-              ? {}
-              : { routeContinuation: event.routeContinuation }),
-          });
-    const response = await dispatchGitHubWebhook({
-      options: target.options,
-      eventName: event.eventName,
-      payload,
-      deliveryId: event.deliveryId,
-      args,
-    });
-    targets.push(await triggerTargetResult(target.slug, response));
-  }
-
-  return {
-    ok: true,
-    event: event.eventName,
-    targets,
-  };
-}
-
-async function handleAgentServeOriginTrigger(
-  event: AgentServeOriginTriggerEvent,
-): Promise<AgentServeTriggerResult> {
-  let payload: unknown;
-  try {
-    payload = JSON.parse(event.bodyText) as unknown;
-  } catch {
-    return {
-      ok: false,
-      event: null,
-      targets: [
-        {
-          slug: "",
-          status: 400,
-          body: { ok: false, error: "invalid_json" },
-        },
-      ],
-    };
-  }
-
-  const envelope = parseOriginWebhookEnvelope(payload);
-  if (envelope === null) {
-    return {
-      ok: false,
-      event: null,
-      targets: [
-        {
-          slug: "",
-          status: 400,
-          body: { ok: false, error: "invalid_origin_payload" },
-        },
-      ],
-    };
-  }
-
-  const targets: AgentServeTriggerTargetResult[] = [];
-  for (const target of event.targets) {
-    const response = await dispatchOriginWebhook({
-      options: target.options,
-      envelope,
-      args: bindLocalIngressSend(target.args, {
-        identity: target.options.continuation,
-        kind: "origin",
-        eventType: envelope.event.type,
-        payload: originIngressExtractPayload(envelope),
-        ...(event.routeContinuation === undefined
-          ? {}
-          : { routeContinuation: event.routeContinuation }),
-      }),
-    });
-    targets.push(await triggerTargetResult(target.slug, response));
-  }
-
-  return {
-    ok: true,
-    event: envelope.event.type,
-    targets,
-  };
-}
-
-async function triggerTargetResult(
-  slug: string,
-  response: Response,
-): Promise<AgentServeTriggerTargetResult> {
-  let body: unknown;
-  try {
-    body = await response.json();
-  } catch {
-    body = { ok: false, error: "invalid_response_json" };
-  }
-  return {
-    slug,
-    status: response.status,
-    body,
-  };
-}

package/src/internal/host-files.ts

@@ -1,341 +0,0 @@
-/**
- * Author-facing durable file storage for {@link HostContext.files}.
- *
- * On Cursor-managed hosting the bytes live in the deployment's durable
- * store; otherwise they land under `--state-root/files` on local disk, which
- * is what makes `host.files` work self-hosted with no storage service at all.
- *
- * Everything that decides *which* bytes an author may reach lives here rather
- * than in the sink: scope selection, path validation, and key minting through
- * {@link fileKeys}. A sink only ever sees a fully-qualified opaque key, so an
- * authored sink — including one a customer wrote against their own Dropbox —
- * cannot be steered into another deployment's or another session's files.
- */
-
-import { join, normalize, sep } from "node:path";
-import {
-  FilePathRejectedError,
-  FileSessionRequiredError,
-  type FileSink,
-  type FileSinkEntry,
-  FileTooLargeError,
-  fileKeys,
-} from "../files.js";
-import {
-  cursorHostedFiles,
-  isCursorHostedFilesAvailable,
-} from "../files-backends/cursor-hosted.js";
-import { localFiles } from "../files-backends/local-fs.js";
-import type {
-  HostFileEntry,
-  HostFileStat,
-  HostFilesApi,
-  HostFilesCapabilities,
-  HostFilesScope,
-} from "../types.js";
-
-export interface CreateHostFilesApiOptions {
-  agentName: string;
-  /** Local disk root for the default sink. Required unless `sink` is supplied. */
-  stateRoot?: string;
-  /** Explicit sink override (tests). Omitted → hosted store or local disk. */
-  sink?: FileSink;
-  /** Session bound for `scope: "session"` calls; prefer {@link HostFilesApi.forSession}. */
-  sessionId?: string;
-  /** Environment consulted when choosing the default sink (tests). */
-  env?: NodeJS.ProcessEnv;
-}
-
-/** Build the host file API for one agent process. */
-export function createHostFilesApi(options: CreateHostFilesApiOptions): HostFilesApi {
-  const sink = options.sink ?? createDefaultSink(options);
-  return createBoundHostFilesApi({
-    agentName: options.agentName,
-    sink,
-    ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
-  });
-}
-
-/**
- * Pick the default sink.
- *
- * On Cursor-managed hosting the durable store is the only correct answer —
- * falling back to pod-local disk there would accept writes that vanish with
- * the pod, which is the failure this surface exists to remove. Off hosting,
- * local disk keeps `serve --dev`, replay, fixtures, and evals working with no
- * storage service. This is the gate all six hosted agents write by hand in
- * their `agent/storage.ts`; resolving it here means authors do not repeat it.
- */
-function createDefaultSink(options: CreateHostFilesApiOptions): FileSink {
-  if (isCursorHostedFilesAvailable(options.env ?? process.env)) {
-    return cursorHostedFiles();
-  }
-  if (options.stateRoot === undefined) {
-    throw new Error(
-      "createHostFilesApi needs a stateRoot for the default local-disk sink, or an explicit sink",
-    );
-  }
-  return localFiles({
-    filesRoot: join(options.stateRoot, "files"),
-    stripKeyPrefix: localKeyPrefix(options.agentName),
-  });
-}
-
-/** On-disk layout drops the framework key prefix so paths stay navigable. */
-function localKeyPrefix(agentName: string): string {
-  return fileKeys.deploymentPrefix(agentName).replace(/deployment\/$/, "");
-}
-
-interface BoundState {
-  agentName: string;
-  sink: FileSink;
-  sessionId?: string;
-}
-
-function createBoundHostFilesApi(state: BoundState): HostFilesApi {
-  const sinkCaps = state.sink.capabilities ?? {};
-  const capabilities: HostFilesCapabilities = {
-    conflictDetection: sinkCaps.etags === true,
-    materialized:
-      sinkCaps.materialized === true && typeof state.sink.materializedPath === "function",
-    ...(sinkCaps.maxBytes === undefined ? {} : { maxBytes: sinkCaps.maxBytes }),
-  };
-
-  const keyFor = (path: string, scope: HostFilesScope | undefined): string =>
-    mintKey(state, path, scope);
-
-  const api: HostFilesApi = {
-    capabilities,
-
-    forSession(sessionId: string): HostFilesApi {
-      const trimmed = sessionId.trim();
-      if (trimmed === "") {
-        throw new FileSessionRequiredError("host.files.forSession requires a non-empty session id");
-      }
-      return createBoundHostFilesApi({ ...state, sessionId: trimmed });
-    },
-
-    async read(path, options): Promise<string | undefined> {
-      const bytes = await api.readBytes(path, options);
-      return bytes === undefined
-        ? undefined
-        : Buffer.from(bytes).toString(options?.encoding ?? "utf8");
-    },
-
-    async readBytes(path, options): Promise<Uint8Array | undefined> {
-      const found = await state.sink.get(keyFor(path, options?.scope));
-      if (found === undefined) {
-        return undefined;
-      }
-      return found instanceof Uint8Array ? found : found.body;
-    },
-
-    async write(path, data, options): Promise<void> {
-      const key = keyFor(path, options?.scope);
-      const body = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
-      const maxBytes = capabilities.maxBytes;
-      if (maxBytes !== undefined && body.byteLength > maxBytes) {
-        throw new FileTooLargeError(key, body.byteLength, maxBytes);
-      }
-      await state.sink.put(
-        key,
-        body,
-        options?.ifMatch === undefined ? undefined : { ifMatch: options.ifMatch },
-      );
-    },
-
-    async remove(path, options): Promise<void> {
-      await state.sink.delete(keyFor(path, options?.scope));
-    },
-
-    async exists(path, options): Promise<boolean> {
-      return (await api.stat(path, options)) !== undefined;
-    },
-
-    async stat(path, options): Promise<HostFileStat | undefined> {
-      const key = keyFor(path, options?.scope);
-      const entry = await statKey(state.sink, key);
-      if (entry === undefined) {
-        return undefined;
-      }
-      return {
-        size: entry.size,
-        ...(entry.mtimeMs === undefined ? {} : { mtimeMs: entry.mtimeMs }),
-        ...(entry.etag === undefined ? {} : { etag: entry.etag }),
-      };
-    },
-
-    async list(prefix, options): Promise<HostFileEntry[]> {
-      const scopePrefix = mintPrefix(state, options?.scope);
-      const rel = prefix === undefined ? "" : normalizeRelPath(prefix, true);
-      const entries = await state.sink.list(`${scopePrefix}${rel}`);
-      const out: HostFileEntry[] = [];
-      for (const entry of entries) {
-        if (!entry.key.startsWith(scopePrefix)) {
-          // A sink that widens the prefix must not leak keys from another
-          // scope through a listing.
-          continue;
-        }
-        out.push({
-          path: entry.key.slice(scopePrefix.length),
-          size: entry.size,
-          ...(entry.mtimeMs === undefined ? {} : { mtimeMs: entry.mtimeMs }),
-        });
-      }
-      return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
-    },
-
-    materializedPath(path, options): string | undefined {
-      if (!capabilities.materialized) {
-        return undefined;
-      }
-      return state.sink.materializedPath?.(keyFor(path, options?.scope));
-    },
-  };
-  return api;
-}
-
-async function statKey(sink: FileSink, key: string): Promise<FileSinkEntry | undefined> {
-  if (typeof sink.stat === "function") {
-    return await sink.stat(key);
-  }
-  const entries = await sink.list(key);
-  return entries.find(entry => entry.key === key);
-}
-
-// ============================================================================
-// Key minting
-// ============================================================================
-
-function mintKey(state: BoundState, path: string, scope: HostFilesScope | undefined): string {
-  const rel = normalizeRelPath(path, false);
-  const resolved = resolveScope(state, scope);
-  if (resolved.kind === "session") {
-    return fileKeys.session(state.agentName, resolved.sessionId, rel);
-  }
-  return resolved.partition === undefined
-    ? fileKeys.deployment(state.agentName, rel)
-    : fileKeys.deploymentPartition(state.agentName, resolved.partition, rel);
-}
-
-function mintPrefix(state: BoundState, scope: HostFilesScope | undefined): string {
-  const resolved = resolveScope(state, scope);
-  if (resolved.kind === "session") {
-    return fileKeys.sessionPrefix(state.agentName, resolved.sessionId);
-  }
-  const base = fileKeys.deploymentPrefix(state.agentName);
-  return resolved.partition === undefined ? base : `${base}${resolved.partition}/`;
-}
-
-type ResolvedScope =
-  | { kind: "session"; sessionId: string }
-  | { kind: "deployment"; partition?: string };
-
-function resolveScope(state: BoundState, scope: HostFilesScope | undefined): ResolvedScope {
-  if (scope === "deployment") {
-    return { kind: "deployment" };
-  }
-  if (scope !== undefined && typeof scope === "object") {
-    if (scope.kind === "deployment") {
-      return scope.partition === undefined
-        ? { kind: "deployment" }
-        : { kind: "deployment", partition: segment(scope.partition) };
-    }
-    const explicit = scope.sessionId ?? state.sessionId;
-    return { kind: "session", sessionId: requireSession(explicit) };
-  }
-  // Default and explicit `"session"` both bind to the caller's own session, so
-  // a relative path can never be re-read as another session's.
-  return { kind: "session", sessionId: requireSession(state.sessionId) };
-}
-
-function requireSession(sessionId: string | undefined): string {
-  if (sessionId === undefined || sessionId.trim() === "") {
-    throw new FileSessionRequiredError(
-      "host.files needs a session in scope: call forSession(sessionId), pass { scope: { kind: 'session', sessionId } }, or use { scope: 'deployment' }",
-    );
-  }
-  return segment(sessionId);
-}
-
-/**
- * Normalize an author path into key-relative form. Rejects traversal, NUL,
- * backslashes, trailing slashes, and the `.cursor*` prefix the Agent Store
- * reserves for Cursor-managed content — refusing here turns an opaque failure
- * deep in a sink (or a 400 from the hosted API, which accepts each path in
- * exactly one spelling) into one the author can act on, and keeps the rule
- * identical across sinks.
- */
-function normalizeRelPath(path: string, allowEmpty: boolean): string {
-  if (typeof path !== "string") {
-    throw new FilePathRejectedError("host.files path must be a string");
-  }
-  const trimmed = path.trim().replace(/^\/+/, "");
-  if (trimmed === "") {
-    if (allowEmpty) {
-      return "";
-    }
-    throw new FilePathRejectedError("host.files path must be non-empty");
-  }
-  if (trimmed.includes("\0")) {
-    throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
-  }
-  // A backslash is a separator on Windows and a literal on POSIX, so a key
-  // minted from one would name different objects on different hosts — and the
-  // hosted API refuses it. Same rule as `segment()` below.
-  if (trimmed.includes("\\")) {
-    throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
-  }
-  // On an object path, a trailing slash would mint a key ending in "/" — an
-  // empty "directory marker" object, never what an author writing a file
-  // meant, and refused by the hosted API. A listing prefix (`allowEmpty`) is
-  // a different thing: there a trailing slash legitimately scopes to a
-  // directory's contents.
-  if (!allowEmpty && trimmed.endsWith("/")) {
-    throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
-  }
-  const normalized = normalize(trimmed).split(sep).join("/");
-  if (
-    normalized === ".." ||
-    normalized === "." ||
-    normalized.startsWith("../") ||
-    normalized.includes("/../") ||
-    normalized.endsWith("/..")
-  ) {
-    throw new FilePathRejectedError(`host.files path is not allowed: ${path}`);
-  }
-  for (const part of normalized.split("/")) {
-    if (isReservedSegment(part)) {
-      throw new FilePathRejectedError(
-        `host.files path segment "${part}" is reserved for Cursor-managed content: ${path}`,
-      );
-    }
-  }
-  return normalized;
-}
-
-/** One key segment (session id, partition): no separators, no traversal. */
-function segment(value: string): string {
-  const trimmed = value.trim();
-  if (
-    trimmed === "" ||
-    trimmed === "." ||
-    trimmed === ".." ||
-    trimmed.includes("/") ||
-    trimmed.includes("\\") ||
-    trimmed.includes("\0")
-  ) {
-    throw new FilePathRejectedError(`host.files key segment is not allowed: ${value}`);
-  }
-  if (isReservedSegment(trimmed)) {
-    throw new FilePathRejectedError(
-      `host.files key segment "${trimmed}" is reserved for Cursor-managed content`,
-    );
-  }
-  return trimmed;
-}
-
-/** Mirrors the server's reserved-prefix rule (`AGENT_STORE_RESERVED_CURSOR_PATH_PREFIX`). */
-function isReservedSegment(value: string): boolean {
-  return value.toLowerCase().startsWith(".cursor");
-}

package/src/internal/host-kv.ts

@@ -1,81 +0,0 @@
-/**
- * Author-facing durable JSON KV for {@link HostContext.kv}.
- *
- * When `defineStorage` is authored and exposes `get`, values live in that
- * sink under {@link storageKeys.kv}. Otherwise they land as one JSON file
- * per key under `--state-root/kv` (local dogfood / no durable plug-in).
- */
-
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { storageKeys } from "../storage.js";
-import type { HostKvApi, JsonValue } from "../types.js";
-import type { AuthorKvStore } from "./storage-roles.js";
-
-export interface CreateHostKvApiOptions {
-  agentName: string;
-  stateRoot: string;
-  /**
-   * Author KV backend. Narrowed to {@link AuthorKvStore} so this path cannot
-   * reach framework session state, which is headed somewhere else entirely.
-   */
-  storage?: AuthorKvStore;
-}
-
-/** Build the host KV API for one agent process. */
-export function createHostKvApi(options: CreateHostKvApiOptions): HostKvApi {
-  const storage = options.storage;
-  if (storage?.supportsAuthorKv === true) {
-    return {
-      get: key => storage.kvGet(normalizeAuthorKey(key)),
-      put: (key, value) => storage.kvPut(normalizeAuthorKey(key), value),
-      delete: key => storage.kvDelete(normalizeAuthorKey(key)),
-    };
-  }
-  return createFilesystemKvApi({
-    agentName: options.agentName,
-    stateRoot: options.stateRoot,
-  });
-}
-
-function createFilesystemKvApi(options: { agentName: string; stateRoot: string }): HostKvApi {
-  const dir = join(options.stateRoot, "kv");
-  const filePath = (authorKey: string): string =>
-    join(dir, `${encodeURIComponent(storageKeys.kv(options.agentName, authorKey))}.json`);
-
-  return {
-    async get(key): Promise<JsonValue | undefined> {
-      const authorKey = normalizeAuthorKey(key);
-      try {
-        return JSON.parse(await readFile(filePath(authorKey), "utf8")) as JsonValue;
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-          return undefined;
-        }
-        throw error;
-      }
-    },
-
-    async put(key, value): Promise<void> {
-      const authorKey = normalizeAuthorKey(key);
-      await mkdir(dir, { recursive: true });
-      const target = filePath(authorKey);
-      const tmp = join(dir, `.tmp-${randomUUID()}`);
-      await writeFile(tmp, JSON.stringify(value), "utf8");
-      await rename(tmp, target);
-    },
-
-    async delete(key): Promise<void> {
-      const authorKey = normalizeAuthorKey(key);
-      await rm(filePath(authorKey), { force: true });
-    },
-  };
-}
-
-function normalizeAuthorKey(key: string): string {
-  if (typeof key !== "string" || key.trim() === "") {
-    throw new Error("host.kv key must be a non-empty string");
-  }
-  return key;
-}