@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/hosted-execution-latency.ts

@@ -1,301 +0,0 @@
-/**
- * Hosted-execution interactive latency: first user-visible outbound and
- * phase timings (send → waitForCompletion → durability drain → post-drain →
- * total).
- *
- * Guest OTel (`agent_sdk.hosted_execution.*`) follows the package's existing
- * guest-side OTel meter conventions (same pattern as `agent_sdk.http.duration`
- * / process-memory histograms) so guest exporters can chart phases without
- * waiting on control-plane scrape.
- *
- * Control-plane scrape of `as_hex` Server-Timing into
- * `agent_sdk.runtime.hosted_execution.*` follows the established
- * `guest_duration_ms` / `guest_network_wait_ms` path so Datadog control-plane
- * dashboards can join execute wall time with guest phases. Both are retained
- * because they feed different scrape surfaces already used in production.
- *
- * Tags stay low-cardinality: channel_kind, phase, outcome, delivery_surface.
- * Never tag message content, Slack IDs, tokens, workflow/request/session IDs.
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-import {
-  type Attributes,
-  type Counter,
-  type Histogram,
-  type Meter,
-  metrics,
-} from "@opentelemetry/api";
-
-export const HOSTED_EXECUTION_DURATION_METRIC = "agent_sdk.hosted_execution.duration_ms";
-export const HOSTED_EXECUTION_VISIBLE_REPLY_METRIC = "agent_sdk.hosted_execution.visible_reply";
-
-/** Server-Timing metric name scraped by the control plane. */
-export const HOSTED_EXECUTION_SERVER_TIMING = "as_hex";
-
-export type HostedVisibleReplyOutcome = "none" | "progress_update" | "final_post" | "error";
-
-export type HostedLatencyPhase =
-  | "to_first_visible"
-  | "first_visible_to_completion"
-  | "durability_drain"
-  | "post_drain"
-  | "total";
-
-export type HostedDeliverySurface = "slack" | "none";
-
-export type HostedExecutionLatencySnapshot = {
-  channelKind: string;
-  outcome: HostedVisibleReplyOutcome;
-  deliverySurface: HostedDeliverySurface;
-  phases: Partial<Record<HostedLatencyPhase, number>>;
-};
-
-type LatencyStore = {
-  startedAt: number;
-  channelKind: string;
-  firstVisibleAt: number | undefined;
-  firstVisibleOutcome: Exclude<HostedVisibleReplyOutcome, "none" | "error"> | undefined;
-  deliverySurface: HostedDeliverySurface;
-  visibleCounterEmitted: boolean;
-  errorEmitted: boolean;
-  finalized: boolean;
-};
-
-const latencyAls = new AsyncLocalStorage<LatencyStore>();
-
-const INSTRUMENTATION = "agent_sdk";
-
-let meterOverride: Meter | undefined;
-let durationHistogram: Histogram | undefined;
-let visibleCounter: Counter | undefined;
-let nowOverride: (() => number) | undefined;
-
-/** Monotonic clock used for latency marks (injectable in tests). */
-export function hostedExecutionNow(): number {
-  return nowOverride !== undefined ? nowOverride() : performance.now();
-}
-
-/** @internal */
-export function setHostedExecutionLatencyNowForTests(now: (() => number) | undefined): void {
-  nowOverride = now;
-}
-
-/** @internal */
-export function setHostedExecutionLatencyMeterForTests(meter: Meter | undefined): void {
-  meterOverride = meter;
-  durationHistogram = undefined;
-  visibleCounter = undefined;
-}
-
-/** @internal */
-export function resetHostedExecutionLatencyForTests(): void {
-  meterOverride = undefined;
-  durationHistogram = undefined;
-  visibleCounter = undefined;
-  nowOverride = undefined;
-}
-
-function resolveMeter(): Meter {
-  return meterOverride ?? metrics.getMeter(INSTRUMENTATION);
-}
-
-function durationInstrument(): Histogram {
-  if (durationHistogram === undefined) {
-    durationHistogram = resolveMeter().createHistogram(HOSTED_EXECUTION_DURATION_METRIC, {
-      unit: "ms",
-      description:
-        "Hosted execution interactive latency phases (first visible, completion, durability, post-drain, total)",
-    });
-  }
-  return durationHistogram;
-}
-
-function visibleInstrument(): Counter {
-  if (visibleCounter === undefined) {
-    visibleCounter = resolveMeter().createCounter(HOSTED_EXECUTION_VISIBLE_REPLY_METRIC, {
-      description:
-        "Hosted execution first-visible Slack outbound outcome (exact-once per execution)",
-    });
-  }
-  return visibleCounter;
-}
-
-export function sanitizeHostedChannelKind(value: string): string {
-  const normalized = value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9_]+/g, "_")
-    .replace(/^_+|_+$/g, "")
-    .slice(0, 64);
-  return normalized === "" ? "unknown" : normalized;
-}
-
-function baseAttrs(store: LatencyStore): Attributes {
-  return {
-    channel_kind: store.channelKind,
-    delivery_surface: store.deliverySurface,
-  };
-}
-
-/**
- * Run hosted execution work inside the latency ALS. Slack delivery marks
- * first-visible against this store; no-ops outside the window.
- */
-export function runWithHostedExecutionLatency<T>(args: { channelKind: string }, work: () => T): T {
-  const store: LatencyStore = {
-    startedAt: hostedExecutionNow(),
-    channelKind: sanitizeHostedChannelKind(args.channelKind),
-    firstVisibleAt: undefined,
-    firstVisibleOutcome: undefined,
-    deliverySurface: "none",
-    visibleCounterEmitted: false,
-    errorEmitted: false,
-    finalized: false,
-  };
-  return latencyAls.run(store, work);
-}
-
-export function isDuringHostedExecutionLatency(): boolean {
-  return latencyAls.getStore() !== undefined;
-}
-
-/**
- * Mark the first user-visible Slack outbound success. Exact-once: later
- * progress updates and final fallback posts are ignored.
- */
-export function markHostedFirstVisibleReply(args: {
-  outcome: "progress_update" | "final_post";
-  deliverySurface?: HostedDeliverySurface;
-}): boolean {
-  const store = latencyAls.getStore();
-  if (store === undefined || store.firstVisibleAt !== undefined) {
-    return false;
-  }
-  store.firstVisibleAt = hostedExecutionNow();
-  store.firstVisibleOutcome = args.outcome;
-  store.deliverySurface = args.deliverySurface ?? "slack";
-  if (!store.visibleCounterEmitted) {
-    store.visibleCounterEmitted = true;
-    visibleInstrument().add(1, {
-      ...baseAttrs(store),
-      outcome: args.outcome,
-    });
-  }
-  return true;
-}
-
-/**
- * Count a visible-outbound failure when nothing user-visible succeeded yet.
- * Exact-once; ignored after a first-visible mark or a prior error.
- */
-export function noteHostedVisibleReplyError(args?: {
-  deliverySurface?: HostedDeliverySurface;
-}): void {
-  const store = latencyAls.getStore();
-  if (store === undefined || store.errorEmitted || store.firstVisibleAt !== undefined) {
-    return;
-  }
-  store.errorEmitted = true;
-  if (args?.deliverySurface !== undefined) {
-    store.deliverySurface = args.deliverySurface;
-  } else if (store.deliverySurface === "none") {
-    store.deliverySurface = "slack";
-  }
-  if (!store.visibleCounterEmitted) {
-    store.visibleCounterEmitted = true;
-    visibleInstrument().add(1, {
-      ...baseAttrs(store),
-      outcome: "error",
-    });
-  }
-}
-
-function resolveOutcome(store: LatencyStore): HostedVisibleReplyOutcome {
-  if (store.firstVisibleOutcome !== undefined) {
-    return store.firstVisibleOutcome;
-  }
-  if (store.errorEmitted) {
-    return "error";
-  }
-  return "none";
-}
-
-/**
- * Emit phase histograms + optional none counter; return a snapshot for
- * Server-Timing. Safe to call once per ALS window.
- *
- * `endedAt` should be taken as late as possible before the execution reply
- * (or rethrow) is returned so `total` and `post_drain` include eviction and
- * diagnostic write work after durability drain.
- */
-export function finalizeHostedExecutionLatency(marks: {
-  completionAt: number;
-  drainAt: number;
-  endedAt: number;
-}): HostedExecutionLatencySnapshot | undefined {
-  const store = latencyAls.getStore();
-  if (store === undefined || store.finalized) {
-    return undefined;
-  }
-  store.finalized = true;
-
-  const outcome = resolveOutcome(store);
-  if (!store.visibleCounterEmitted) {
-    store.visibleCounterEmitted = true;
-    visibleInstrument().add(1, {
-      ...baseAttrs(store),
-      outcome: "none",
-    });
-  }
-
-  const phases: Partial<Record<HostedLatencyPhase, number>> = {
-    durability_drain: Math.max(0, marks.drainAt - marks.completionAt),
-    post_drain: Math.max(0, marks.endedAt - marks.drainAt),
-    total: Math.max(0, marks.endedAt - store.startedAt),
-  };
-  if (store.firstVisibleAt !== undefined) {
-    phases.to_first_visible = Math.max(0, store.firstVisibleAt - store.startedAt);
-    phases.first_visible_to_completion = Math.max(0, marks.completionAt - store.firstVisibleAt);
-  }
-
-  const attrs: Attributes = {
-    channel_kind: store.channelKind,
-    outcome,
-    delivery_surface: store.deliverySurface,
-  };
-  const histogram = durationInstrument();
-  for (const [phase, value] of Object.entries(phases) as Array<[HostedLatencyPhase, number]>) {
-    histogram.record(value, { ...attrs, phase });
-  }
-
-  return {
-    channelKind: store.channelKind,
-    outcome,
-    deliverySurface: store.deliverySurface,
-    phases,
-  };
-}
-
-export function formatHostedExecutionLatencyServerTiming(
-  snapshot: HostedExecutionLatencySnapshot,
-): string[] {
-  const parts: string[] = [];
-  const order: HostedLatencyPhase[] = [
-    "to_first_visible",
-    "first_visible_to_completion",
-    "durability_drain",
-    "post_drain",
-    "total",
-  ];
-  for (const phase of order) {
-    const dur = snapshot.phases[phase];
-    if (dur === undefined) {
-      continue;
-    }
-    parts.push(
-      `${HOSTED_EXECUTION_SERVER_TIMING};desc="${phase}";dur=${Math.max(0, dur).toFixed(1)};outcome="${snapshot.outcome}";ch="${snapshot.channelKind}";sf="${snapshot.deliverySurface}"`,
-    );
-  }
-  return parts;
-}

package/src/internal/hosted-managed-automation.ts

@@ -1,116 +0,0 @@
-/**
- * Managed-automation envelope slices by provider delivery id (plan 0002
- * G2), recorded at hosted admission so channel code running the delivery's
- * task (or session turn) can attach the customer's MCP servers through the
- * control-plane relay. In-memory and TTL-bounded like the hosted pending-
- * send table: the envelope slice carries names only (never credentials)
- * and evaporates with the process.
- *
- * A leaf module (protocol type import only) so product channels can read
- * it without pulling the hosted-delivery route — and its session-engine
- * dependency graph — into their bundles.
- *
- * INTERNAL: first-party multi-tenant deployment plumbing. Deliberately
- * excluded from the published `@cursor/bdk` npm package (see the `files`
- * whitelist); consumed by internal deployments via relative source imports.
- */
-
-import type { HostedAdmissionManagedAutomation } from "./hosted-delivery-protocol.js";
-
-type ManagedAutomationEntry = {
-  managedAutomation: HostedAdmissionManagedAutomation;
-  expiresAt: number;
-};
-
-/**
- * Process-wide slot for the table. Hosted engines run the compiled CLI
- * (`dist/`), which records at admission, while first-party factory agents
- * relative-import this file from `src/` and read at finalize — two module
- * instances in one process. A module-local Map would be recorded in one
- * copy and read from the other (always undefined, so a fork never sees its
- * Slack channels or MCP servers); the shared symbol keeps one table.
- */
-const MANAGED_AUTOMATION_TABLE_KEY = Symbol.for(
-  "cursor.agentkit.hostedManagedAutomationByDelivery",
-);
-
-function managedAutomationTable(): Map<string, ManagedAutomationEntry> {
-  const slots = globalThis as unknown as Record<
-    symbol,
-    Map<string, ManagedAutomationEntry> | undefined
-  >;
-  let table = slots[MANAGED_AUTOMATION_TABLE_KEY];
-  if (table === undefined) {
-    table = new Map();
-    slots[MANAGED_AUTOMATION_TABLE_KEY] = table;
-  }
-  return table;
-}
-
-/** Long enough to outlive a slow review run kicked off by the delivery. */
-const MANAGED_AUTOMATION_TTL_MS = 60 * 60_000;
-const MANAGED_AUTOMATION_MAX_ENTRIES = 10_000;
-
-export function recordHostedManagedAutomation(delivery: {
-  deliveryId: string;
-  managedAutomation?: HostedAdmissionManagedAutomation;
-}): void {
-  if (delivery.managedAutomation === undefined) {
-    console.info(
-      `[agent-sdk] hosted managedAutomation not recorded deliveryId=${delivery.deliveryId}: admission envelope carried no managedAutomation slice (non-managed delivery, or the control plane resolved no MCP servers and no Slack channels)`,
-    );
-    return;
-  }
-  const managedAutomationByDelivery = managedAutomationTable();
-  const now = Date.now();
-  for (const [key, entry] of managedAutomationByDelivery) {
-    if (entry.expiresAt <= now) {
-      managedAutomationByDelivery.delete(key);
-    }
-  }
-  if (managedAutomationByDelivery.size >= MANAGED_AUTOMATION_MAX_ENTRIES) {
-    console.info(
-      `[agent-sdk] hosted managedAutomation table full (${String(managedAutomationByDelivery.size)} entries); clearing before recording deliveryId=${delivery.deliveryId}`,
-    );
-    managedAutomationByDelivery.clear();
-  }
-  managedAutomationByDelivery.set(delivery.deliveryId, {
-    managedAutomation: delivery.managedAutomation,
-    expiresAt: now + MANAGED_AUTOMATION_TTL_MS,
-  });
-  const slackChannels = delivery.managedAutomation.slackChannels;
-  console.info(
-    `[agent-sdk] hosted managedAutomation recorded deliveryId=${delivery.deliveryId} automationUuid=${delivery.managedAutomation.automationUuid} mcpServerNames=${String(delivery.managedAutomation.mcpServerNames.length)} slackChannels=${slackChannels === undefined ? "<absent>" : JSON.stringify(slackChannels)} ttlMs=${String(MANAGED_AUTOMATION_TTL_MS)} tableSize=${String(managedAutomationByDelivery.size)}`,
-  );
-}
-
-/**
- * The managed automation the control plane attributed to a hosted delivery,
- * when the envelope carried one. Undefined for non-managed deliveries,
- * expired entries, and non-hosted (webhook/stream) dispatch paths.
- */
-export function getHostedManagedAutomation(
-  deliveryId: string,
-): HostedAdmissionManagedAutomation | undefined {
-  const managedAutomationByDelivery = managedAutomationTable();
-  const entry = managedAutomationByDelivery.get(deliveryId);
-  if (entry === undefined) {
-    console.info(
-      `[agent-sdk] hosted managedAutomation lookup miss deliveryId=${deliveryId}: no entry (never recorded in this process, or evicted) tableSize=${String(managedAutomationByDelivery.size)} knownDeliveryIds=${JSON.stringify([...managedAutomationByDelivery.keys()].slice(0, 10))}`,
-    );
-    return undefined;
-  }
-  if (entry.expiresAt <= Date.now()) {
-    console.info(
-      `[agent-sdk] hosted managedAutomation lookup expired deliveryId=${deliveryId} automationUuid=${entry.managedAutomation.automationUuid} expiredMsAgo=${String(Date.now() - entry.expiresAt)}`,
-    );
-    managedAutomationByDelivery.delete(deliveryId);
-    return undefined;
-  }
-  return entry.managedAutomation;
-}
-
-/** Drop recorded managed-automation slices (tests only). */
-export function resetHostedManagedAutomationForTest(): void {
-  managedAutomationTable().clear();
-}

package/src/internal/hosting.ts

@@ -1,114 +0,0 @@
-/**
- * Client-side mirrors of the Agent Serve hosting validation rules
- * (backend/server/src/agentServe/agentServeShared.ts). Shared by discovery
- * (`hosting` block diagnostics on `agent-sdk validate`) and the deploy /
- * secrets CLI verbs (actionable errors before any network call). The
- * backend stays authoritative — these exist so mistakes fail fast and
- * locally with the same grammar the server enforces.
- */
-
-/** `hosting.egressDomains` cap (the manifest schema and deploy body agree). */
-export const MAX_EGRESS_DOMAINS = 64;
-/** Max secrets per deployment. */
-export const MAX_SECRETS = 32;
-/** Max secret value size in bytes. */
-export const MAX_SECRET_VALUE_BYTES = 4096;
-/** Max secret name length. */
-export const MAX_SECRET_NAME_LENGTH = 64;
-/** Secret names the platform manages; user writes are rejected. */
-export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
-/** Pushed container images per team, uploads in flight included. */
-export const MAX_CONTAINER_IMAGES = 100;
-/** Compressed `docker save` tarball cap per image. */
-export const MAX_CONTAINER_IMAGE_BYTES: number = 8 * 1024 * 1024 * 1024;
-
-const CONTAINER_IMAGE_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
-
-/** Returns a human error message, or undefined when the image name is valid. */
-export function validateContainerImageName(name: string): string | undefined {
-  if (name.length >= 2 && CONTAINER_IMAGE_NAME_PATTERN.test(name)) {
-    return undefined;
-  }
-  return `Invalid image name "${name}": use 2–64 lowercase letters, digits, ".", "_" or "-", starting and ending with a letter or digit.`;
-}
-
-/**
- * Extra platform-managed env names (not `CURSOR_*`). Mirrored from
- * `@cursor/bdk/internal/cursor-hosted` so validate/secrets CLI stay in
- * sync without importing the storage backend into the CLI graph.
- * Hosted storage is HTTP-proxied; engines never see a database URL.
- */
-export const PLATFORM_HOSTED_STORAGE_SECRET_NAMES = ["AGENT_SERVE_DEPLOYMENT_ID"] as const;
-
-const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
-
-// Lowercase hostname with >=2 labels, an alphabetic TLD, and at most one
-// leading `*.` wildcard. Labels: alphanumeric with interior hyphens.
-const EGRESS_DOMAIN_PATTERN = /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]+$/;
-
-/** `host:port` asks for raw TCP egress; a wildcard host has no address to open. */
-const EGRESS_TCP_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]+:([1-9]\d{0,4})$/;
-
-/** Returns a human error message, or undefined when the domain is valid. */
-export function validateEgressDomain(domain: string): string | undefined {
-  if (EGRESS_DOMAIN_PATTERN.test(domain)) {
-    return undefined;
-  }
-  const tcp = EGRESS_TCP_PATTERN.exec(domain);
-  if (tcp !== null && Number(tcp[3]) <= 65535) {
-    return undefined;
-  }
-  return `Invalid egress domain ${JSON.stringify(domain)}: use a lowercase hostname with at least two labels and an alphabetic TLD (e.g. "api.example.com"), optionally with a single leading "*." wildcard or a trailing ":port" for raw TCP.`;
-}
-
-/**
- * Returns a human error message, or undefined when the name is a valid
- * secret name. Grammar only — reserved names are checked separately so the
- * manifest's declarative `secretNames` can mention them with a softer
- * diagnostic than the hard write-time rejection.
- */
-export function validateSecretName(name: string): string | undefined {
-  if (name.length > MAX_SECRET_NAME_LENGTH) {
-    return `Secret name ${JSON.stringify(name)} is too long (max ${MAX_SECRET_NAME_LENGTH} characters).`;
-  }
-  if (!SECRET_NAME_PATTERN.test(name)) {
-    return `Invalid secret name ${JSON.stringify(name)}: use UPPER_SNAKE_CASE starting with a letter (${SECRET_NAME_PATTERN}).`;
-  }
-  return undefined;
-}
-
-/**
- * True when the platform manages this name (`CURSOR_*` or hosted-storage
- * env vars); user writes / deletes are rejected.
- */
-export function isReservedSecretName(name: string): boolean {
-  if (name.startsWith(RESERVED_SECRET_NAME_PREFIX)) {
-    return true;
-  }
-  const upper = name.toUpperCase();
-  return (PLATFORM_HOSTED_STORAGE_SECRET_NAMES as readonly string[]).some(
-    managed => managed === upper,
-  );
-}
-
-/**
- * Human error for a secret name a user is trying to write or delete:
- * grammar plus platform-managed names (`CURSOR_*`, hosted storage).
- */
-export function validateSettableSecretName(name: string): string | undefined {
-  const nameError = validateSecretName(name);
-  if (nameError !== undefined) {
-    return nameError;
-  }
-  if (isReservedSecretName(name)) {
-    return `Secret name ${JSON.stringify(name)} is platform-managed; user secrets cannot claim CURSOR_* or reserved hosted-storage names.`;
-  }
-  return undefined;
-}
-
-const CURSOR_EVENT_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-
-/** `owner/name` — mirrors the backend's cursor-event repo grammar. */
-export function isValidCursorEventRepo(repo: string): boolean {
-  return CURSOR_EVENT_REPO_PATTERN.test(repo) && !repo.includes("..");
-}

package/src/internal/http-channel-define.ts

@@ -1,25 +0,0 @@
-/**
- * Constructor for the built-in HTTP session channel. The runtime always
- * mounts this channel; authors use `defineChannel` for custom surfaces.
- */
-
-import type { HttpChannelConfig, HttpChannelDefinition } from "../types.js";
-import { brandDefinition } from "./brand.js";
-import { normalizeIdentity } from "./continuation-identity.js";
-import { attachHttpControlPlaneAdmission } from "./http-control-plane-session.js";
-
-/**
- * Configure the built-in HTTP session channel. Used by discovery as the
- * default (and for an optional internal `agent/channels/http.ts` override).
- */
-export function httpChannel(config: HttpChannelConfig = {}): HttpChannelDefinition {
-  const definition =
-    config.continuation !== undefined
-      ? brandDefinition("http-channel", {
-          ...config,
-          continuation: normalizeIdentity(config.continuation, "http"),
-        })
-      : brandDefinition("http-channel", config);
-  attachHttpControlPlaneAdmission(definition);
-  return definition;
-}