@cursor/bdk 0.2.3 → 0.2.4

package/src/hooks.ts

@@ -1,30 +0,0 @@
-/**
- * `defineHook` — authored at `agent/hooks/<slug>.ts`.
- *
- * Hooks subscribe to the session event stream and run side effects after
- * each event is durably recorded (audit logging, metrics, persisting
- * transcripts to your own database). Handlers are observe-only.
- *
- * ```ts
- * import { defineHook } from "@cursor/bdk/hooks";
- *
- * export default defineHook({
- *   events: {
- *     async "turn.completed"(event, ctx) {
- *       const prior = await ctx.host.kv.get("last-result");
- *       const notes = await ctx.host.files.read("notes.md");
- *       console.log("turn done", ctx.session.id, event.data.usage, prior, notes);
- *     },
- *   },
- * });
- * ```
- */
-
-import { brandDefinition } from "./internal/brand.js";
-import type { HookConfig, HookDefinition } from "./types.js";
-
-export type { HookConfig, HookContext, HookDefinition, HookHandler } from "./types.js";
-
-export function defineHook(config: HookConfig): HookDefinition {
-  return brandDefinition("hook", config);
-}

package/src/index.ts

@@ -1,259 +0,0 @@
-/**
- * @cursor/bdk
- *
- * Filesystem-first framework for Cursor agents: define an agent as markdown
- * and TypeScript files under an `agent/` directory, and serve it over
- * channels with the Cursor SDK as the execution harness.
- *
- * ```ts
- * import { serve } from "@cursor/bdk";
- *
- * const handle = await serve(".", { port: 3000 });
- * console.log(`agent listening on ${handle.url}`);
- * ```
- */
-
-import { registerAuthoredModuleLoaders } from "./internal/authored-loaders.js";
-import { brandDefinition } from "./internal/brand.js";
-import { setDevMode } from "./internal/dev-mode.js";
-import { type LoadAgentProjectOptions, resolveAgentMounts } from "./internal/discovery.js";
-import { type AgentMount, startServer } from "./internal/server.js";
-import type {
-  AgentConfig,
-  AgentConfigDefinition,
-  AgentProject,
-  AgentServeHandle,
-  InstructionsConfig,
-  InstructionsDefinition,
-  ServeOptions,
-} from "./types.js";
-
-export { defineArtifacts } from "./artifacts.js";
-// Authoring helpers (also available on their focused subpath exports).
-export {
-  allowAll,
-  bearerAuth,
-  DELETE,
-  defineChannel,
-  GET,
-  localDev,
-  localDevStrict,
-  loopbackGitHubDev,
-  loopbackOnly,
-  PATCH,
-  POST,
-  PUT,
-  publicEndpoint,
-} from "./channels.js";
-export { defineConnection } from "./connections.js";
-export {
-  cursorPlugin,
-  defineExtension,
-  disable,
-  disableArtifacts,
-  disableChannel,
-  disableConnection,
-  disableHook,
-  disableInstructions,
-  disableSchedule,
-  disableSkill,
-  disableSubagent,
-  disableTool,
-} from "./extensions.js";
-export type {
-  DirEntry,
-  EditQuery,
-  EditResult,
-  FileInfo,
-  FileSystem,
-  GlobOptions,
-  GrepQuery,
-  GrepResult,
-  ListOptions,
-  SearchQuery,
-  SearchResult,
-} from "./filesystem.js";
-export {
-  DeleteNotSupportedError,
-  EditError,
-  emptyFs,
-  FILE_SYSTEM_SCAN_LIMIT,
-  FileNotFoundError,
-  hostFs,
-  InvalidGrepPatternError,
-  isFileNotFoundError,
-  NoMountError,
-  overlayFs,
-  PathError,
-  ReadOnlyMountError,
-  strReplaceOnFileSystem,
-  tempFs,
-  unionFs,
-  WriteFailedError,
-} from "./filesystem.js";
-export { defineHook } from "./hooks.js";
-export { InvalidAsOfError, VacuousTimeArgsError } from "./internal/as-of.js";
-export type {
-  ContinuationBuiltin,
-  ContinuationClaim,
-  ContinuationIdentity,
-  ContinuationSelector,
-  ConversationType,
-  MailboxContinuation,
-  ParsedContinuation,
-} from "./internal/continuation-identity.js";
-export { mintClaim } from "./internal/continuation-identity.js";
-export type { LoadAgentProjectOptions } from "./internal/discovery.js";
-export {
-  formatDiagnostics,
-  hasErrorDiagnostics,
-  isAgentProjectDir,
-  loadAgentProject,
-  loadAgentProjects,
-  projectInfo,
-  resolveAgentMounts,
-} from "./internal/discovery.js";
-export { nearestNeighborMissHint } from "./internal/filesystem/nearest.js";
-export type {
-  AgentServeGitHubTriggerEvent,
-  AgentServeGitHubTriggerTarget,
-  AgentServeOriginTriggerEvent,
-  AgentServeOriginTriggerTarget,
-  AgentServeTriggerEvent,
-  AgentServeTriggerResult,
-  AgentServeTriggerTargetResult,
-} from "./internal/handleAgentServeTrigger.js";
-export {
-  collectGitHubTriggerTargets,
-  collectOriginTriggerTargets,
-  handleAgentServeTrigger,
-} from "./internal/handleAgentServeTrigger.js";
-export {
-  MCP_CHANNEL_ID,
-  MCP_ENDPOINT_PATH,
-  mcpEndpointToolNames,
-  TOOL_MCP_ENDPOINT_PATH,
-} from "./internal/mcp-endpoint.js";
-export {
-  REMINDER_ARGS_MAX_BYTES,
-  ReminderValidationError,
-  rejectAnonymousReminderHandlers,
-  UnknownReminderError,
-} from "./internal/reminder-runner.js";
-export type { AgentMount } from "./internal/server.js";
-export {
-  SessionBusyError,
-  ToolInputError,
-  ToolNotDirectlyCallableError,
-  UnknownChannelError,
-  UnknownSessionError,
-  UnknownToolError,
-} from "./internal/session-engine.js";
-export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
-export { agentStoreMemoryBackend, fileMemoryBackend, memoryHook } from "./memory.js";
-export type { OtelConfig, OtelDefinition, OtelExporterConfig } from "./otel.js";
-export type { PromptTag } from "./prompt.js";
-export { prompt } from "./prompt.js";
-export type {
-  ReminderBusyPolicy,
-  ReminderCreateInput,
-  ReminderDefinition,
-  ReminderFireContext,
-  ReminderFireResult,
-  ReminderFollowupOptions,
-  ReminderHandlerConfig,
-  ReminderHostApi,
-  ReminderInfo,
-  ReminderReschedule,
-  ReminderScheduleKind,
-  ReminderStatus,
-  ReminderTarget,
-  ReminderUntilContext,
-} from "./reminders.js";
-export { defineReminder } from "./reminders.js";
-export { defineSchedule } from "./schedules.js";
-export { defineSkill } from "./skills.js";
-export { defineTool } from "./tools.js";
-export type * from "./types.js";
-export {
-  cursorAccountServersHasMixedWildcard,
-  DEFAULT_MODEL,
-  DIRECT_TOOL_CALL_CHANNEL_ID,
-  HttpSessionAdmitError,
-  isCursorAccountTransport,
-  isPeerConnectionTransport,
-  isSymbolicConnectionTransport,
-  isToolEffect,
-  MAX_RUNNING_TURNS_LIMIT,
-  normalizeConnectionEffects,
-  normalizeConnectionTools,
-  normalizeCursorAccountServers,
-  supportsKvCas,
-} from "./types.js";
-
-/**
- * Runtime config for an agent — authored at `agent/agent.ts` (the root
- * agent) or `agent/subagents/<id>/agent.ts` (a subagent).
- */
-export function defineAgent(config: AgentConfig): AgentConfigDefinition {
-  return brandDefinition("agent", config);
-}
-
-/**
- * Programmatic instructions — authored at `agent/instructions.ts` when the
- * system prompt needs to be generated rather than written as markdown.
- */
-export function defineInstructions(config: InstructionsConfig): InstructionsDefinition {
-  return brandDefinition("instructions", config);
-}
-
-/**
- * Discover and serve one or more agents over HTTP.
- *
- * Defaults to multi-agent layout: each agent is mounted under `/<slug>/v1/*`
- * and `/<slug>/playground`, with an index at `/`.
- *
- * - Given a directory that is itself an agent project, mounts it under its
- *   directory name as the slug.
- * - Given a directory whose immediate children are agent projects, mounts
- *   each under its directory name.
- * - Pass `mode: "single"` (or an {@link AgentProject}) for the unslugged
- *   `/v1/*` surface.
- *
- * The built-in session channel lives under `/v1/session*`, custom channels
- * under `/v1/channels/<id>`, plus `/v1/health` and `/v1/info`. Schedules run
- * on their cron cadence unless dev mode or `schedules: false` disables them.
- */
-export async function serve(
-  projectOrDir: string | AgentProject,
-  options: ServeOptions & {
-    discovery?: LoadAgentProjectOptions;
-    /**
-     * Mount layout. Defaults to `"multi"` (slugged routes + index).
-     * `"single"` serves one agent at `/v1/*` with an empty slug. Ignored when
-     * an {@link AgentProject} is passed (always single-mount).
-     */
-    mode?: "single" | "multi";
-  } = {},
-): Promise<AgentServeHandle> {
-  const { discovery, mode, ...serveOptions } = options;
-
-  // Programmatic embedders get the same authored-TypeScript loading as the
-  // CLI (idempotent; the bin registers earlier, source runs are a no-op).
-  await registerAuthoredModuleLoaders();
-
-  // Set before discovery so channel factories (constructed at import time) can
-  // relax dev-only defaults — e.g. the GitHub channel accepting unsigned
-  // loopback-forwarded deliveries. No-op outside dev.
-  setDevMode(serveOptions.dev === true);
-
-  if (typeof projectOrDir !== "string") {
-    return startServer([{ slug: "", project: projectOrDir }], serveOptions);
-  }
-
-  const mounts: AgentMount[] = await resolveAgentMounts(projectOrDir, {
-    ...discovery,
-    ...(mode === undefined ? {} : { mode }),
-  });
-  return startServer(mounts, serveOptions);
-}

package/src/internal/advertise-tools.ts

@@ -1,370 +0,0 @@
-/**
- * Advertised connection tools (`defineConnection({ advertiseTools: true })`).
- *
- * The session engine calls {@link resolveAdvertisedTools} while building
- * every local turn: for each advertising connection it lists the server's
- * tools and synthesizes a named 1:1 passthrough server tool per entry —
- * the server's own names, descriptions, and live schemas — merged into the
- * authored `agent/tools/` catalog. Because it runs at turn-build time it
- * covers every way a turn starts (dispatcher sends, follow-ups, reminder
- * fires that call the engine directly) and survives process restarts,
- * since nothing is parked in memory between turns.
- *
- * Connections with per-session `auth` are listed and called through a
- * one-off client carrying that session's headers (the registry's cached
- * per-name client would leak one session's identity into another);
- * auth-less connections go through the shared `host.mcp` registry, which
- * also covers serve-resolved transports (Cursor account bridges, peers).
- *
- * Advertised names follow the Cursor-account MCP bridge
- * (`packages/agent-serve/src/internal/cursor/account-mcp.ts`): slug
- * `[^a-zA-Z0-9_-]` to `_`, collision suffixes `_2` / `_3`, and call the
- * original advertised name. That is the same mapping `packages/agent`
- * `normalizeMcpToolName` uses for IDE/Sand MCP tools. A listing failure
- * still fails the turn rather than running it with a silently shrunken
- * toolset.
- *
- * `defineConnection({ effects })` filters the listing before names are
- * assigned: only tools whose MCP annotations classify as an intended
- * effect are advertised. Unclassified tools are omitted, not guessed.
- * `defineConnection({ tools: [...] })` keeps only the named tools.
- * `disallowedTools` drops names. A name filter that matches nothing on
- * the server fails the turn.
- * Tools whose `annotations.title` is `do-not-call` are dropped as well
- * (vendor host-UI / MCP Apps helpers that still carry `readOnlyHint`).
- */
-
-import {
-  connectionAllowsTool,
-  type DiscoveredConnection,
-  type DiscoveredTool,
-  type HostMcpCallResult,
-  type HostMcpToolInfo,
-  type JsonSchemaObject,
-  type McpToolAnnotations,
-  type ResolvedAgent,
-  type SessionInfo,
-  type ToolDefinition,
-  type ToolEffect,
-} from "../types.js";
-import { brandDefinition } from "./brand.js";
-import { describeError } from "./describe-error.js";
-import type { HostMcpOneOff } from "./mcp-host.js";
-import { sanitizeMcpToolName, suffixMcpToolName } from "./sanitize-mcp-tool-name.js";
-import { classifyAnnotationsEffect } from "./tool-policy.js";
-
-/**
- * What the resolver needs from the host MCP registry: the shared cached
- * clients for auth-less connections, and one-off clients (per-session
- * headers, never cached) for auth'd ones. `McpHost` implements this.
- */
-export interface AdvertiseHostMcp {
-  listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
-  callTool(
-    connectionName: string,
-    toolName: string,
-    args?: Record<string, unknown>,
-  ): Promise<HostMcpCallResult>;
-  oneOff(connection: DiscoveredConnection): HostMcpOneOff;
-}
-
-/**
- * Model-facing advertised names after {@link sanitizeMcpToolName} — the
- * same MCP-client shape the Cursor-account bridge documents
- * (`^[a-zA-Z0-9_-]{1,128}$`). Authored `agent/tools/` filenames stay on
- * discovery's stricter `NAME_PATTERN` (must start alphanumeric).
- */
-export const ADVERTISED_TOOL_NAME_PATTERN: RegExp = /^[A-Za-z0-9_-]{1,128}$/;
-
-const ANY_OBJECT_SCHEMA: JsonSchemaObject = {
-  type: "object",
-  additionalProperties: true,
-};
-
-/** How one advertising connection is listed and called. */
-export interface AdvertisedToolSource {
-  listTools(): Promise<HostMcpToolInfo[]>;
-  callTool(toolName: string, args: Record<string, unknown>): Promise<HostMcpCallResult>;
-}
-
-/**
- * Resolve the advertised tools for one session. Returns `[]` when no
- * connection advertises; throws (failing the turn) when a listing fails
- * or a definition is invalid.
- */
-export async function resolveAdvertisedTools(args: {
-  agent: ResolvedAgent;
-  session: SessionInfo;
-  hostMcp: AdvertiseHostMcp;
-  /**
-   * When set, a connection whose source or listing fails is reported here
-   * and skipped instead of throwing. Turns keep the throwing default (a
-   * turn must fail closed); the inspection catalog passes this so one
-   * broken connector does not hide every other tool.
-   */
-  onConnectionError?: (connection: string, error: unknown) => void;
-  /** Test seam; defaults to {@link sourceForConnection}. */
-  sourceFor?: (
-    connection: DiscoveredConnection,
-    session: SessionInfo,
-    hostMcp: AdvertiseHostMcp,
-  ) => Promise<AdvertisedToolSource>;
-}): Promise<DiscoveredTool[]> {
-  const advertising = args.agent.connections.filter(
-    connection => connection.advertiseTools === true,
-  );
-  if (advertising.length === 0) {
-    return [];
-  }
-  const sourceFor = args.sourceFor ?? sourceForConnection;
-  // Each connection's listing is a network round trip against a distinct
-  // server (auth callback, MCP initialize, tools/list), so they run
-  // concurrently; the fan-out is bounded by the agent's declared
-  // connections. Name assignment below stays in declaration order so
-  // collision suffixes do not depend on which server answered first.
-  type Listing =
-    | {
-        connection: DiscoveredConnection;
-        ok: true;
-        source: AdvertisedToolSource;
-        listed: HostMcpToolInfo[];
-      }
-    | { connection: DiscoveredConnection; ok: false; error: unknown };
-  const listings = await Promise.all(
-    advertising.map(async (connection): Promise<Listing> => {
-      try {
-        const source = await sourceFor(connection, args.session, args.hostMcp);
-        const listed = await source.listTools();
-        return {
-          connection,
-          ok: true,
-          source,
-          listed: listed.filter(info => connectionAllowsTool(connection, info.name)),
-        };
-      } catch (error) {
-        return { connection, ok: false, error };
-      }
-    }),
-  );
-  const claimed = new Set(args.agent.tools.map(tool => tool.name));
-  const resolved: DiscoveredTool[] = [];
-  for (const listing of listings) {
-    const { connection } = listing;
-    if (!listing.ok) {
-      if (args.onConnectionError !== undefined) {
-        args.onConnectionError(connection.name, listing.error);
-        continue;
-      }
-      if (connection.optional === true) {
-        continue;
-      }
-      throw new Error(
-        `Failed to list tools on advertised connection "${connection.name}": ${describeError(listing.error)}`,
-        { cause: listing.error },
-      );
-    }
-    const { source, listed } = listing;
-    if (
-      (connection.tools !== undefined || connection.disallowedTools !== undefined) &&
-      listed.length === 0
-    ) {
-      const error = new Error(
-        `Advertised connection "${connection.name}" tool filter matched no tools on the server.`,
-      );
-      if (args.onConnectionError !== undefined) {
-        args.onConnectionError(connection.name, error);
-        continue;
-      }
-      if (connection.optional === true) {
-        continue;
-      }
-      throw error;
-    }
-    const intended = listed.filter(
-      info =>
-        !isDoNotCallTool(info.annotations) &&
-        matchesIntendedEffects(info.annotations, connection.effects),
-    );
-    const exposed = exposeListedTools(intended, claimed);
-    for (const { info, exposedName } of exposed) {
-      resolved.push(toDiscoveredTool(connection, info, exposedName, source));
-      claimed.add(exposedName);
-    }
-  }
-  return resolved;
-}
-
-/**
- * The production source for one advertising connection: the shared
- * `host.mcp` registry client for auth-less connections (which also covers
- * serve-resolved transports — Cursor account bridges, peers), or a
- * registry one-off with the session's headers substituted when the
- * connection has per-session `auth`. The auth callback is evaluated once
- * per turn, here; the one-off opens a fresh client per operation so one
- * session's identity can never serve another's call.
- */
-export async function sourceForConnection(
-  connection: DiscoveredConnection,
-  session: SessionInfo,
-  hostMcp: AdvertiseHostMcp,
-): Promise<AdvertisedToolSource> {
-  if (connection.auth === undefined) {
-    return {
-      listTools: () => hostMcp.listTools(connection.name),
-      callTool: (toolName, callArgs) => hostMcp.callTool(connection.name, toolName, callArgs),
-    };
-  }
-  const transport = connection.transport;
-  if (!("url" in transport)) {
-    // Discovery rejects auth on non-URL transports; guard for callers that
-    // bypass discovery (hand-built projects).
-    throw new Error(`Connection "${connection.name}" has per-session auth but no URL transport.`);
-  }
-  const evaluated = await connection.auth(session);
-  return hostMcp.oneOff({
-    ...connection,
-    transport: {
-      ...transport,
-      headers: { ...transport.headers, ...evaluated.headers },
-    },
-  });
-}
-
-/**
- * Same catalog rule as the Cursor-account bridge: slug illegal characters,
- * then `_2` / `_3` … for colliders (including authored tools already in
- * `claimed`). Suffix assignment is stable for a colliding group: sort by
- * original advertised name, independent of `listTools` order.
- */
-function exposeListedTools(
-  listed: HostMcpToolInfo[],
-  claimed: ReadonlySet<string>,
-): Array<{ info: HostMcpToolInfo; exposedName: string }> {
-  const byBase = new Map<string, HostMcpToolInfo[]>();
-  for (const info of listed) {
-    const base = sanitizeMcpToolName(info.name);
-    const group = byBase.get(base);
-    if (group === undefined) {
-      byBase.set(base, [info]);
-    } else {
-      group.push(info);
-    }
-  }
-  const taken = new Set(claimed);
-  const exposedNameByInfo = new Map<HostMcpToolInfo, string>();
-  const sortedBases = [...byBase.keys()].sort((left, right) =>
-    left < right ? -1 : left > right ? 1 : 0,
-  );
-  for (const base of sortedBases) {
-    const group = byBase.get(base)!;
-    group.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
-    group.forEach((info, index) => {
-      let suffixIndex = index;
-      let exposedName = suffixMcpToolName(base, suffixIndex);
-      while (taken.has(exposedName)) {
-        suffixIndex++;
-        exposedName = suffixMcpToolName(base, suffixIndex);
-      }
-      taken.add(exposedName);
-      exposedNameByInfo.set(info, exposedName);
-    });
-  }
-  return listed.map(info => ({
-    info,
-    exposedName: exposedNameByInfo.get(info)!,
-  }));
-}
-
-/**
- * Vendors (Datadog MCP Apps) stamp host-UI-only helpers with this title.
- * They still look like reads (`readOnlyHint: true`), so the effects
- * filter would keep them. The model and agsh should not see them; the
- * raw MCP listing stays intact for the host.
- */
-const DO_NOT_CALL_TITLE = "do-not-call";
-
-function isDoNotCallTool(annotations: McpToolAnnotations | undefined): boolean {
-  return annotations?.title?.trim() === DO_NOT_CALL_TITLE;
-}
-
-function matchesIntendedEffects(
-  annotations: McpToolAnnotations | undefined,
-  effects: readonly ToolEffect[] | undefined,
-): boolean {
-  if (effects === undefined) {
-    return true;
-  }
-  const effect = classifyAnnotationsEffect(annotations);
-  return effect !== undefined && effects.includes(effect);
-}
-
-function toDiscoveredTool(
-  connection: DiscoveredConnection,
-  info: HostMcpToolInfo,
-  exposedName: string,
-  source: AdvertisedToolSource,
-): DiscoveredTool {
-  const description =
-    info.description === undefined || info.description.trim() === ""
-      ? `${info.name} — MCP tool on the "${connection.name}" connection, forwarded 1:1.`
-      : info.description;
-  const inputSchema = info.inputSchema ?? ANY_OBJECT_SCHEMA;
-  const outputSchema = info.outputSchema;
-  const effect =
-    connection.effects === undefined ? undefined : classifyAnnotationsEffect(info.annotations);
-  const definition: ToolDefinition = brandDefinition("tool", {
-    description,
-    inputSchema,
-    outputSchema,
-    effect,
-    execute: async (input: Record<string, unknown>) =>
-      formatMcpToolResult(
-        connection.name,
-        info.name,
-        await source.callTool(info.name, input ?? {}),
-      ),
-  } as unknown as ToolDefinition);
-  return {
-    name: exposedName,
-    description,
-    inputSchema,
-    outputSchema,
-    execution: "server",
-    needsApproval: false,
-    effect,
-    // The server's own annotations ride along (bounded at listing time), so
-    // the harness listing carries them and effect classification can read
-    // them. Absent stays absent — the fail-closed state.
-    annotations: info.annotations,
-    advertised: true,
-    connection: connection.name,
-    definition,
-  };
-}
-
-/**
- * Render an MCP call result for the model: text parts joined, non-text
- * parts noted by type, `isError` surfaced as a thrown error so the turn
- * records a tool error instead of error-shaped prose.
- */
-export function formatMcpToolResult(
-  connectionName: string,
-  toolName: string,
-  result: HostMcpCallResult,
-): string {
-  const parts = result.content.map(item =>
-    item.type === "text" && typeof item.text === "string"
-      ? item.text
-      : `[${item.type} content omitted]`,
-  );
-  const text = parts.join("\n").trim();
-  if (result.isError === true) {
-    throw new Error(text === "" ? `${connectionName} tool ${toolName} failed` : text);
-  }
-  if (text !== "") {
-    return text;
-  }
-  return result.structuredContent !== undefined
-    ? JSON.stringify(result.structuredContent, null, 2)
-    : "(empty result)";
-}