@cursor/bdk 0.2.3 → 0.2.5

package/src/otel.ts

@@ -1,320 +0,0 @@
-/**
- * OpenTelemetry for Agent SDK — author `agent/otel.ts`, pass `serve({ otel })`,
- * or set `OTEL_EXPORTER_OTLP_ENDPOINT` (standard OTel env).
- *
- * ```ts
- * import { defineOtel } from "@cursor/bdk/internal/otel";
- *
- * export default defineOtel({
- *   serviceName: "cursor",
- *   exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
- * });
- *
- * // Hosted v2: re-read env on flush after deployment secrets bind.
- * export default defineOtel(() => resolveMyOtelConfig());
- * ```
- *
- * Internal only: Cursor factory agents. Not a public Agent SDK export.
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-import { context, trace } from "@opentelemetry/api";
-import { brandDefinition } from "./internal/brand.js";
-
-export type OtelSignal = "traces" | "metrics" | "logs";
-
-/** One OTLP destination. Multiple entries fan out. */
-export interface OtelExporterConfig {
-  /**
-   * OTLP base URL (`https://otel.example.com`) or signal path
-   * (`…/v1/traces`). Signal paths are stripped to the base; the runtime
-   * re-appends `/v1/{signal}`.
-   */
-  url: string;
-  /** Extra HTTP headers (merged with `OTEL_EXPORTER_OTLP_HEADERS`). */
-  headers?: Record<string, string>;
-  /**
-   * Wire format. Default `http/protobuf` (matches Cursor enterprise OTLP).
-   * Use `http/json` for collectors that only accept JSON.
-   */
-  protocol?: "http/json" | "http/protobuf";
-  /**
-   * Restrict this destination to these signals. Default: all enabled
-   * signals. Set by env when per-signal `OTEL_EXPORTER_OTLP_*_ENDPOINT`
-   * vars differ.
-   */
-  signals?: OtelSignal[];
-}
-
-export interface OtelTraceOptions {
-  /** Sample ratio in `[0, 1]`. Default `1`. */
-  sampleRatio?: number;
-}
-
-export interface OtelMetricOptions {
-  /** Export interval in ms. Default `10000`. */
-  exportIntervalMillis?: number;
-}
-
-export interface OtelLogOptions {
-  /**
-   * Include user prompt text on log records / span events.
-   * Default false; also toggled by `OTEL_LOG_USER_PROMPTS=1`.
-   */
-  userPrompts?: boolean;
-  /**
-   * Include tool argument / result payloads and failure text (truncated).
-   * Default false; also `OTEL_LOG_TOOL_CONTENT=1`.
-   */
-  toolContent?: boolean;
-}
-
-/**
- * Authored / programmatic OTel config. Empty config still enables when
- * standard `OTEL_EXPORTER_OTLP_*` env vars are set.
- */
-export interface OtelConfig {
-  /**
-   * Resource `service.name`. Default: `OTEL_SERVICE_NAME` or `"cursor"`
-   * (same as enterprise export) so Agent SDK signals join org streams.
-   */
-  serviceName?: string;
-  /** Resource `service.version`. */
-  serviceVersion?: string;
-  /** Extra resource attributes on every signal. */
-  resourceAttributes?: Record<string, string>;
-  /**
-   * OTLP destinations. Default: from `OTEL_EXPORTER_OTLP_ENDPOINT` /
-   * per-signal `*_TRACES_ENDPOINT` etc. Empty with no env = disabled.
-   */
-  exporters?: OtelExporterConfig[];
-  /** Traces on/off or options. Default on. */
-  traces?: boolean | OtelTraceOptions;
-  /** Metrics on/off or options. Default on. */
-  metrics?: boolean | OtelMetricOptions;
-  /** Logs on/off or options. Default off (opt-in content). */
-  logs?: boolean | OtelLogOptions;
-}
-
-export type OtelDefinition = OtelConfig & { readonly __agentServe: "otel" };
-
-/** Re-read authored config after bake (hosted v2 binds secrets later). */
-export type OtelConfigFactory = () => OtelConfig;
-
-/**
- * Hidden factory on {@link OtelDefinition}. Not enumerable so
- * `pickAuthoredOtel` compares the bake-time snapshot, not the thunk.
- */
-export const OTEL_CONFIG_RESOLVE: symbol = Symbol.for("anysphere.july.otel.configResolve");
-
-/**
- * Author OpenTelemetry export under `agent/otel.ts`.
- * Import from `@cursor/bdk/internal/otel`, not `@cursor/bdk`.
- */
-export function defineOtel(config: OtelConfig | OtelConfigFactory = {}): OtelDefinition {
-  const resolve: OtelConfigFactory = typeof config === "function" ? config : () => config;
-  const snapshot = resolve();
-  validateOtelConfig(snapshot);
-  const def = brandDefinition("otel", snapshot);
-  Object.defineProperty(def, OTEL_CONFIG_RESOLVE, {
-    value: resolve,
-    enumerable: false,
-  });
-  return def;
-}
-
-/** Invoke a `defineOtel(() => …)` factory, or return the static snapshot. */
-export function resolveOtelDefinition(def: OtelConfig): OtelConfig {
-  const resolve = (def as unknown as Record<symbol, OtelConfigFactory | undefined>)[
-    OTEL_CONFIG_RESOLVE
-  ];
-  if (resolve === undefined) {
-    return def;
-  }
-  const next = resolve();
-  validateOtelConfig(next);
-  return next;
-}
-
-function validateOtelConfig(config: OtelConfig): void {
-  if (config.exporters !== undefined) {
-    for (const exporter of config.exporters) {
-      if (typeof exporter.url !== "string" || exporter.url.length === 0) {
-        throw new Error("defineOtel: exporters[].url must be a non-empty string");
-      }
-      if (
-        exporter.protocol !== undefined &&
-        exporter.protocol !== "http/json" &&
-        exporter.protocol !== "http/protobuf"
-      ) {
-        throw new Error('defineOtel: exporters[].protocol must be "http/json" or "http/protobuf"');
-      }
-      assertSignals(exporter.signals);
-    }
-  }
-  if (config.resourceAttributes !== undefined) {
-    for (const [key, value] of Object.entries(config.resourceAttributes)) {
-      if (typeof value !== "string") {
-        throw new Error(`defineOtel: resourceAttributes.${key} must be a string`);
-      }
-    }
-  }
-  assertSampleRatio(config.traces);
-}
-
-function assertSignals(signals: OtelSignal[] | undefined): void {
-  if (signals === undefined) {
-    return;
-  }
-  if (signals.length === 0) {
-    throw new Error("defineOtel: exporters[].signals must be non-empty");
-  }
-  for (const signal of signals) {
-    if (signal !== "traces" && signal !== "metrics" && signal !== "logs") {
-      throw new Error('defineOtel: exporters[].signals must be "traces" | "metrics" | "logs"');
-    }
-  }
-}
-
-function assertSampleRatio(traces: OtelConfig["traces"]): void {
-  if (traces === undefined || typeof traces === "boolean") {
-    return;
-  }
-  const ratio = traces.sampleRatio;
-  if (ratio === undefined) {
-    return;
-  }
-  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
-    throw new Error("defineOtel: traces.sampleRatio must be in [0, 1]");
-  }
-}
-
-export const TRACEPARENT_HEADER = "traceparent";
-/** Cursor backend prefers this; `remoteSpanContextFromRequest` falls back to W3C. */
-export const BACKEND_TRACEPARENT_HEADER = "backend-traceparent";
-
-export function formatTraceparent(spanContext: {
-  traceId: string;
-  spanId: string;
-  traceFlags: number;
-}): string | undefined {
-  if (!trace.isSpanContextValid(spanContext)) {
-    return undefined;
-  }
-  return `00-${spanContext.traceId}-${
-    spanContext.spanId
-  }-${spanContext.traceFlags.toString(16).padStart(2, "0")}`;
-}
-
-/**
- * Copy the active span onto outbound headers as W3C `traceparent` and
- * Cursor `backend-traceparent`. No-op when no valid span is active.
- *
- * Prefers the Agent SDK ALS (`instrumentHttp`, `runInTurn`,
- * `runInCall`). Falls back to the `@anysphere/context` process-wide
- * ALS: `createSpan` does not bind OTel API context, and SPAN keys
- * are per `@opentelemetry/api` copy.
- */
-export function injectActiveTraceContext(headers: {
-  get(name: string): string | null;
-  set(name: string, value: string): void;
-}): void {
-  const span = trace.getSpan(context.active()) ?? getContextTracerSpan();
-  if (span === undefined) {
-    return;
-  }
-  const traceparent = formatTraceparent(span.spanContext());
-  if (traceparent === undefined) {
-    return;
-  }
-  headers.set(TRACEPARENT_HEADER, traceparent);
-  headers.set(BACKEND_TRACEPARENT_HEADER, traceparent);
-}
-
-/** W3C `traceparent` for the active span, or undefined if none. */
-export function activeTraceparent(): string | undefined {
-  const headers = new Headers();
-  injectActiveTraceContext(headers);
-  return headers.get(TRACEPARENT_HEADER) ?? undefined;
-}
-
-/**
- * Copy the active span onto every outbound `fetch`. Agents should not
- * wrap their own Connect / MCP clients for this — `createOtelRuntime`
- * installs it on `globalThis.fetch` when traces are on.
- */
-function headersForFetch(input: RequestInfo | URL, init?: RequestInit): Headers {
-  // Fetch: `init.headers` replaces `Request` headers. If `init` omits
-  // headers (`fetch(request, { signal })`), keep the Request's.
-  const headers = new Headers(
-    init?.headers !== undefined
-      ? init.headers
-      : input instanceof Request
-        ? input.headers
-        : undefined,
-  );
-  injectActiveTraceContext(headers);
-  return headers;
-}
-
-export function instrumentedFetch(base: typeof fetch = fetch): typeof fetch {
-  return (input, init) => {
-    const headers = headersForFetch(input, init);
-    if (input instanceof Request && init === undefined) {
-      return base(new Request(input, { headers }));
-    }
-    return base(input, { ...init, headers });
-  };
-}
-
-const OUTBOUND_FETCH_INSTALLED = Symbol.for("anysphere.july.otel.outboundFetch");
-
-/** Idempotent. Safe to call from `createOtelRuntime` on every serve. */
-export function installOutboundFetchInstrumentation(): void {
-  const slots = globalThis as unknown as Record<symbol, boolean>;
-  if (slots[OUTBOUND_FETCH_INSTALLED] === true) {
-    return;
-  }
-  slots[OUTBOUND_FETCH_INSTALLED] = true;
-  globalThis.fetch = instrumentedFetch(globalThis.fetch);
-}
-
-/** Must match `@anysphere/context` `ACTIVE_OTEL_SPAN_ALS`. */
-const ACTIVE_OTEL_SPAN_ALS = Symbol.for("anysphere.context.activeOtelSpanAls");
-
-function ensureContextTracerAls(): void {
-  const slots = globalThis as unknown as Record<symbol, unknown>;
-  if (slots[ACTIVE_OTEL_SPAN_ALS] === undefined) {
-    slots[ACTIVE_OTEL_SPAN_ALS] = new AsyncLocalStorage();
-  }
-}
-
-ensureContextTracerAls();
-
-function getContextTracerSpan():
-  | {
-      spanContext: () => {
-        traceId: string;
-        spanId: string;
-        traceFlags: number;
-      };
-    }
-  | undefined {
-  const als = (
-    globalThis as unknown as Record<
-      symbol,
-      {
-        getStore?: () =>
-          | {
-              spanContext: () => {
-                traceId: string;
-                spanId: string;
-                traceFlags: number;
-              };
-            }
-          | undefined;
-      }
-    >
-  )[ACTIVE_OTEL_SPAN_ALS];
-  return als?.getStore?.();
-}

package/src/prompt.ts

@@ -1,80 +0,0 @@
-/**
- * Dedented multi-line strings for prompts, errors, and tool descriptions.
- *
- * Indent the body to match surrounding TypeScript; the common leading
- * whitespace is stripped. A leading newline after `` prompt` `` is dropped so
- * the usual multiline form stays flush in source.
- *
- * ```ts
- * import { prompt } from "@cursor/bdk";
- *
- * export default defineTool({
- *   description: prompt`
- *     Deploy Anyship services for a merged PR.
- *     Enforces HITL outside business hours.
- *   `,
- *   // ...
- * });
- *
- * throw new Error(prompt`
- *   It is outside business hours.
- *   Use request_author_approval.
- * `);
- *
- * // GitHub channel `context` wants string[]:
- * context: prompt.lines`
- *   Merged PR detected: ${url}.
- *
- *   Run the deploy flow.
- * `
- * ```
- */
-
-function dedentLines(strings: TemplateStringsArray, values: readonly unknown[]): string[] {
-  let text = "";
-  for (let i = 0; i < strings.length; i++) {
-    text += strings[i] ?? "";
-    if (i < values.length) {
-      text += String(values[i]);
-    }
-  }
-  // Common form is prompt`\n  …\n`; drop the opening newline only.
-  if (text.startsWith("\n")) {
-    text = text.slice(1);
-  }
-  text = text.replace(/(?:\n[ \t]*)+$/u, "");
-
-  const lines = text.split("\n");
-  let minIndent = Number.POSITIVE_INFINITY;
-  for (const line of lines) {
-    if (line.trim() === "") {
-      continue;
-    }
-    const indent = /^[ \t]*/u.exec(line)?.[0]?.length ?? 0;
-    if (indent < minIndent) {
-      minIndent = indent;
-    }
-  }
-  if (!Number.isFinite(minIndent)) {
-    minIndent = 0;
-  }
-  return lines.map(line => (line.trim() === "" ? "" : line.slice(minIndent)));
-}
-
-export type PromptTag = {
-  (strings: TemplateStringsArray, ...values: unknown[]): string;
-  /** Same as {@link prompt}, but as separate lines (e.g. GitHub `context`). */
-  lines(strings: TemplateStringsArray, ...values: unknown[]): string[];
-};
-
-/** Dedented multi-line string (blank lines preserved). */
-export const prompt: PromptTag = Object.assign(
-  function prompt(strings: TemplateStringsArray, ...values: unknown[]): string {
-    return dedentLines(strings, values).join("\n");
-  },
-  {
-    lines(strings: TemplateStringsArray, ...values: unknown[]): string[] {
-      return dedentLines(strings, values);
-    },
-  },
-);

package/src/reminders.ts

@@ -1,65 +0,0 @@
-/**
- * Runtime reminders — per-session durable wakes — and named handlers
- * authored at `agent/reminders/<name>.ts`.
- *
- * ```ts
- * import { defineReminder } from "@cursor/bdk/reminders";
- * import type { ReminderCreateInput } from "@cursor/bdk/reminders";
- *
- * // agent/reminders/verdict_recheck.ts
- * export default defineReminder({
- *   async run({ args, followup }) {
- *     await followup({ message: `Recheck ${String(args.headSha)}` });
- *     return { action: "delivered" };
- *   },
- * });
- *
- * import verdictRecheck from "./reminders/verdict_recheck.js";
- *
- * // Recurring ≈ setInterval; one-shot ≈ setTimeout.
- * await host.reminders?.create({
- *   purpose: "ci_recheck",
- *   channelId: session.channelId,
- *   continuationToken: session.continuationKey!,
- *   delay: "2h",
- *   handler: verdictRecheck,
- *   args: { headSha: "abc" },
- * });
- * ```
- *
- * Distinct from `defineSchedule` (deploy-time global cron under
- * `agent/schedules/`). Reminders are created at runtime and bound to a
- * channel continuation. Prefer named `handler` + serializable `args` for
- * hosted v2 durability; anonymous `run` remains on local and hosted v1.
- */
-
-import { brandDefinition } from "./internal/brand.js";
-import type { ReminderDefinition, ReminderHandlerConfig } from "./types.js";
-
-export type {
-  ReminderBusyPolicy,
-  ReminderCreateInput,
-  ReminderDefinition,
-  ReminderFireContext,
-  ReminderFireResult,
-  ReminderFollowupOptions,
-  ReminderHandlerConfig,
-  ReminderHostApi,
-  ReminderInfo,
-  ReminderReschedule,
-  ReminderScheduleKind,
-  ReminderStatus,
-  ReminderTarget,
-  ReminderUntilContext,
-} from "./types.js";
-
-/**
- * Brand a named reminder handler for `agent/reminders/<name>.ts`.
- * The registry name is the module stem (not a field on the definition).
- */
-export function defineReminder(config: ReminderHandlerConfig): ReminderDefinition {
-  if (typeof config.run !== "function") {
-    throw new Error("defineReminder requires a `run` function");
-  }
-  return brandDefinition("reminder", config);
-}

package/src/schedules.ts

@@ -1,31 +0,0 @@
-/**
- * `defineSchedule` — authored at `agent/schedules/<name>.ts`.
- *
- * A schedule starts the agent on a cron cadence instead of waiting for an
- * inbound message. The markdown form is fire-and-forget task mode; the
- * handler form hands work off to a channel (and can call MCP via `args.host.mcp`):
- *
- * ```ts
- * import { defineSchedule } from "@cursor/bdk/schedules";
- *
- * export default defineSchedule({
- *   cron: "0 9 * * 1-5",
- *   markdown: "Summarize open incidents and post to the metrics endpoint.",
- * });
- * ```
- *
- * The same fire-and-forget form can be written as a plain markdown file with
- * `cron:` frontmatter (`agent/schedules/<name>.md`).
- */
-
-import { brandDefinition } from "./internal/brand.js";
-import type { ScheduleConfig, ScheduleDefinition } from "./types.js";
-
-export type { ScheduleConfig, ScheduleDefinition, ScheduleHandlerArgs } from "./types.js";
-
-export function defineSchedule(config: ScheduleConfig): ScheduleDefinition {
-  if ((config.markdown === undefined) === (config.run === undefined)) {
-    throw new Error("defineSchedule requires exactly one of `markdown` or `run`");
-  }
-  return brandDefinition("schedule", config);
-}

package/src/skills.ts

@@ -1,27 +0,0 @@
-/**
- * `defineSkill` — authored at `agent/skills/<name>.ts`.
- *
- * Most skills are plain markdown files (`agent/skills/<name>.md`) or packaged
- * directories (`agent/skills/<name>/SKILL.md` plus sibling files). Reach for
- * `defineSkill` when markdown can't express what you need, such as generated
- * content or inline sibling files:
- *
- * ```ts
- * import { defineSkill } from "@cursor/bdk/skills";
- *
- * export default defineSkill({
- *   description: "Research unfamiliar topics before answering.",
- *   markdown: "Gather evidence first, then answer with the key facts.",
- *   files: { "references/checklist.md": "# Checklist\n\n- Find sources.\n" },
- * });
- * ```
- */
-
-import { brandDefinition } from "./internal/brand.js";
-import type { SkillConfig, SkillDefinition } from "./types.js";
-
-export type { SkillConfig, SkillDefinition } from "./types.js";
-
-export function defineSkill(config: SkillConfig): SkillDefinition {
-  return brandDefinition("skill", config);
-}