@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/host-otel.ts

@@ -1,231 +0,0 @@
-/**
- * Author-facing OpenTelemetry surface for {@link HostContext.otel}.
- *
- * Always present on `ctx.host`. Counters and histograms no-op when no meter
- * is running. `setAttributes` still tags open turn/tool spans when a
- * collector is attached. `forSession` is engine-only so a tool cannot
- * retarget another conversation's tags.
- */
-
-import type { Counter, Histogram, Meter } from "@opentelemetry/api";
-import type { HostOtelApi, HostOtelAttributes } from "../types.js";
-import type { AttrValue } from "./otel/attrs.js";
-import { attrs } from "./otel/attrs.js";
-import type { OtelCollector } from "./otel/collector.js";
-
-const METRIC_NAME = /^[A-Za-z][A-Za-z0-9_./-]*$/;
-
-const RESERVED_METRICS = new Set([
-  "cursor.token.usage",
-  "cursor.tool.calls",
-  "cursor.cost.usage",
-  "agent_sdk.session.count",
-  "agent_sdk.turn.count",
-  "agent_sdk.subagent.count",
-  "agent_sdk.http.duration",
-]);
-
-const RESERVED_ATTRIBUTES = new Set([
-  "cursor.conversation.id",
-  "agent_sdk.session_id",
-  "agent_sdk.agent",
-  "agent_sdk.turn_id",
-  "agent_sdk.framework",
-]);
-
-export interface CreateHostOtelApiOptions {
-  agentName: string;
-  meter?: Meter;
-  collector?: OtelCollector;
-  /** Session bound for join tags; prefer {@link HostOtelSessionApi.forSession}. */
-  sessionId?: string;
-}
-
-/** Engine-only binding. Not part of the public {@link HostOtelApi}. */
-export interface HostOtelSessionApi extends HostOtelApi {
-  forSession(sessionId: string): HostOtelSessionApi;
-}
-
-interface CachedInstrument {
-  kind: "counter" | "histogram";
-  instrument: Counter | Histogram;
-}
-
-interface SharedState {
-  agentName: string;
-  meter: Meter | undefined;
-  collector: OtelCollector | undefined;
-  instruments: Map<string, CachedInstrument>;
-  /** Used when no collector is attached so bound instances still share tags. */
-  sessionTags: Map<string, Record<string, AttrValue>>;
-}
-
-interface BoundState {
-  shared: SharedState;
-  sessionId: string | undefined;
-  localTags: Record<string, AttrValue>;
-}
-
-/** Build the host OpenTelemetry API for one agent process. */
-export function createHostOtelApi(options: CreateHostOtelApiOptions): HostOtelSessionApi {
-  return createBoundHostOtelApi({
-    shared: {
-      agentName: options.agentName,
-      meter: options.meter,
-      collector: options.collector,
-      instruments: new Map(),
-      sessionTags: new Map(),
-    },
-    sessionId: options.sessionId,
-    localTags: {},
-  });
-}
-
-function createBoundHostOtelApi(state: BoundState): HostOtelSessionApi {
-  const api: HostOtelSessionApi = {
-    get enabled(): boolean {
-      return state.shared.meter !== undefined;
-    },
-
-    setAttributes(attributes) {
-      const cleaned = validateAttributes(attributes);
-      if (state.sessionId === undefined) {
-        Object.assign(state.localTags, cleaned);
-        return;
-      }
-      mergeSessionTags(state, state.sessionId, cleaned);
-      state.shared.collector?.setSessionAttributes(state.sessionId, cleaned);
-    },
-
-    increment(
-      name: string,
-      valueOrAttributes?: number | HostOtelAttributes,
-      maybeAttributes?: HostOtelAttributes,
-    ) {
-      const value = typeof valueOrAttributes === "number" ? valueOrAttributes : 1;
-      const attributes =
-        typeof valueOrAttributes === "number" ? maybeAttributes : valueOrAttributes;
-      counter(state.shared, name)?.add(value, emitAttributes(state, attributes));
-    },
-
-    record(name, value, attributes) {
-      histogram(state.shared, name)?.record(value, emitAttributes(state, attributes));
-    },
-
-    forSession(sessionId) {
-      const trimmed = sessionId.trim();
-      if (trimmed === "") {
-        throw new Error("host.otel.forSession requires a non-empty session id");
-      }
-      return createBoundHostOtelApi({
-        shared: state.shared,
-        sessionId: trimmed,
-        localTags: {},
-      });
-    },
-  };
-  return api;
-}
-
-function mergeSessionTags(
-  state: BoundState,
-  sessionId: string,
-  incoming: Record<string, AttrValue>,
-): void {
-  const bag = state.shared.sessionTags.get(sessionId) ?? {};
-  Object.assign(bag, incoming);
-  state.shared.sessionTags.set(sessionId, bag);
-}
-
-function emitAttributes(
-  state: BoundState,
-  callSite: HostOtelAttributes | undefined,
-): Record<string, AttrValue> {
-  return attrs({
-    ...sessionBag(state),
-    ...validateAttributes(callSite),
-    "agent_sdk.agent": state.shared.agentName,
-    ...(state.sessionId === undefined
-      ? {}
-      : {
-          "cursor.conversation.id": state.sessionId,
-          "agent_sdk.session_id": state.sessionId,
-        }),
-  });
-}
-
-function sessionBag(state: BoundState): Record<string, AttrValue> {
-  if (state.sessionId === undefined) {
-    return state.localTags;
-  }
-  const fromCollector = state.shared.collector?.getSessionAttributes(state.sessionId);
-  const fromShared = state.shared.sessionTags.get(state.sessionId) ?? {};
-  return {
-    ...fromShared,
-    ...(fromCollector ?? {}),
-    ...state.localTags,
-  };
-}
-
-function counter(shared: SharedState, name: string): Counter | undefined {
-  validateMetricName(name);
-  if (shared.meter === undefined) {
-    return undefined;
-  }
-  const existing = shared.instruments.get(name);
-  if (existing !== undefined) {
-    if (existing.kind !== "counter") {
-      throw new Error(`host.otel metric "${name}" is already a histogram`);
-    }
-    return existing.instrument as Counter;
-  }
-  const instrument = shared.meter.createCounter(name);
-  shared.instruments.set(name, { kind: "counter", instrument });
-  return instrument;
-}
-
-function histogram(shared: SharedState, name: string): Histogram | undefined {
-  validateMetricName(name);
-  if (shared.meter === undefined) {
-    return undefined;
-  }
-  const existing = shared.instruments.get(name);
-  if (existing !== undefined) {
-    if (existing.kind !== "histogram") {
-      throw new Error(`host.otel metric "${name}" is already a counter`);
-    }
-    return existing.instrument as Histogram;
-  }
-  const instrument = shared.meter.createHistogram(name);
-  shared.instruments.set(name, { kind: "histogram", instrument });
-  return instrument;
-}
-
-function validateMetricName(name: string): void {
-  if (!METRIC_NAME.test(name)) {
-    throw new Error(`host.otel metric name "${name}" must match [A-Za-z][A-Za-z0-9_./-]*`);
-  }
-  if (RESERVED_METRICS.has(name)) {
-    throw new Error(`host.otel metric name "${name}" is reserved`);
-  }
-}
-
-function validateAttributes(attributes: HostOtelAttributes | undefined): Record<string, AttrValue> {
-  if (attributes === undefined) {
-    return {};
-  }
-  const out: Record<string, AttrValue> = {};
-  for (const [key, value] of Object.entries(attributes)) {
-    if (value === undefined) {
-      continue;
-    }
-    if (RESERVED_ATTRIBUTES.has(key)) {
-      throw new Error(`host.otel attribute "${key}" is reserved; the runtime always sets it`);
-    }
-    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
-      throw new Error(`host.otel attribute "${key}" must be a string, number, or boolean`);
-    }
-    out[key] = value;
-  }
-  return out;
-}

package/src/internal/host-platforms.ts

@@ -1,170 +0,0 @@
-/**
- * Host-side GitHub + Slack clients shared across tools, channel routes,
- * schedules, and channel packs — same injection pattern as MCP.
- */
-
-import { WebClient } from "@slack/web-api";
-import { createGitHubOctokit } from "../channels/github/api.js";
-import {
-  ensureGhCliTokenEnv,
-  hasGitHubAppCredentials,
-  resolveCredentialValue,
-  resolveGitHubInstallationId,
-  tryResolveGhAuthToken,
-} from "../channels/github/auth.js";
-import type { GitHubChannelCredentials } from "../channels/github/types.js";
-import { slackEnvKeys, tryResolveBotToken } from "../channels/slack/credentials.js";
-import type { SlackCredentials } from "../channels/slack/types.js";
-import type { HostGitHubClient, HostSlackClient } from "../types.js";
-
-export interface HostPlatforms {
-  github: HostGitHubClient;
-  slack: HostSlackClient;
-}
-
-/**
- * How ambient host GitHub auth was resolved.
- * `app` = GitHub App installation token (preferred in production).
- * `env` / `gh` = local PAT / CLI fallbacks when App creds are unset.
- */
-export type HostGitHubAuthSource = "app" | "cursor-account" | "env" | "gh" | "unavailable";
-
-export interface HostPlatformsOptions {
-  githubCredentials?: GitHubChannelCredentials;
-  /**
-   * Per-agent Slack credentials (usually from a channel `envPrefix`).
-   * When omitted, `getClient()` falls back to `SLACK_BOT_TOKEN`.
-   */
-  slackCredentials?: SlackCredentials;
-  /** Env prefix used only to name the missing-token error. */
-  slackEnvPrefix?: string;
-}
-
-/** Bot-token Slack client. Pass channel credentials so `envPrefix` is honored. */
-export function createHostSlackClient(
-  options: { credentials?: SlackCredentials; envPrefix?: string } = {},
-): HostSlackClient {
-  let slackPromise: ReturnType<HostSlackClient["getClient"]> | undefined;
-  return {
-    getClient: async () => {
-      slackPromise ??= (async () => {
-        const token = await tryResolveBotToken(options.credentials);
-        if (token === undefined) {
-          const botKey = slackEnvKeys(options.envPrefix).bot;
-          const hint =
-            options.envPrefix === undefined || options.envPrefix.trim() === ""
-              ? `${botKey} or a channel envPrefix`
-              : botKey;
-          throw new Error(`No Slack bot token available (set ${hint}).`);
-        }
-        return new WebClient(token);
-      })();
-      return slackPromise;
-    },
-  };
-}
-
-/**
- * Build host platforms from ambient credentials. Prefer App installation
- * auth when configured; otherwise fall back to PAT / `gh auth` for local
- * testing. Webhook-scoped calls should still prefer `ctx.github`.
- */
-export function createHostPlatforms(options: HostPlatformsOptions = {}): HostPlatforms {
-  let octokitPromise: ReturnType<HostGitHubClient["getOctokit"]> | undefined;
-
-  return {
-    github: {
-      getOctokit: () => {
-        octokitPromise ??= createGitHubOctokit({
-          credentials: options.githubCredentials,
-        });
-        return octokitPromise;
-      },
-    },
-    slack: createHostSlackClient({
-      credentials: options.slackCredentials,
-      envPrefix: options.slackEnvPrefix,
-    }),
-  };
-}
-
-/**
- * Detect ambient host GitHub auth without throwing.
- * Order matches {@link createGitHubOctokit}: App installation, then
- * `GITHUB_TOKEN` / `GH_TOKEN`, then `gh auth token`.
- */
-export async function resolveHostGitHubAuthSource(): Promise<HostGitHubAuthSource> {
-  if ((await hasGitHubAppCredentials()) && (await resolveGitHubInstallationId()) !== undefined) {
-    return "app";
-  }
-  const fromEnv =
-    (await resolveCredentialValue(process.env.GITHUB_TOKEN)) ??
-    (await resolveCredentialValue(process.env.GH_TOKEN));
-  if (fromEnv !== undefined) {
-    return "env";
-  }
-  const fromGh = await tryResolveGhAuthToken();
-  return fromGh === undefined ? "unavailable" : "gh";
-}
-
-/**
- * Soft boot-time GitHub auth check: log the resolved source and optionally
- * prime `github.getOctokit()` so the first request does not pay CLI latency.
- * When auth is App-backed, also export an installation token as `GH_TOKEN`
- * so tools that shell out to `gh` (a host-side `prepare_pr` tool, say)
- * authenticate on corp hosts that have no PAT / `gh
- * auth login`. Never fails serve — missing auth is logged as a warning.
- */
-export async function warmupHostGitHubAuth(options: {
-  logger: (line: string) => void;
-  github?: HostGitHubClient;
-  authSource?: HostGitHubAuthSource;
-}): Promise<HostGitHubAuthSource> {
-  const source = options.authSource ?? (await resolveHostGitHubAuthSource());
-  if (source === "unavailable") {
-    options.logger(
-      "[agent-sdk] GitHub auth: unavailable (set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID, or GITHUB_TOKEN / GH_TOKEN, or run `gh auth login`)",
-    );
-    return source;
-  }
-
-  let exportedGhToken = false;
-  if (source === "app") {
-    try {
-      exportedGhToken = await ensureGhCliTokenEnv();
-    } catch (error) {
-      options.logger(
-        `[agent-sdk] GitHub auth: failed to export GH_TOKEN for gh CLI: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  }
-
-  const label =
-    source === "cursor-account"
-      ? "Cursor account repo-scoped credential (also exported as GH_TOKEN for gh CLI)"
-      : source === "app"
-        ? exportedGhToken
-          ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
-          : "GitHub App installation token"
-        : source === "env"
-          ? "GITHUB_TOKEN/GH_TOKEN"
-          : "gh auth token";
-  if (options.github === undefined) {
-    options.logger(`[agent-sdk] GitHub auth: ${label}`);
-    return source;
-  }
-
-  try {
-    await options.github.getOctokit();
-    options.logger(`[agent-sdk] GitHub auth: ${label}`);
-  } catch (error) {
-    options.logger(
-      `[agent-sdk] GitHub auth: ${label} resolved but Octokit warmup failed: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-    );
-  }
-  return source;
-}

package/src/internal/hosted-admission-adapter.ts

@@ -1,47 +0,0 @@
-import type { ChannelHandlerArgs } from "../types.js";
-import type { HostedAdmissionPlatformHandoff } from "./hosted-delivery-protocol.js";
-
-/**
- * Hosted-admission hook a channel pack attaches to its definition.
- *
- * Hosted delivery looks this up from the mounted definition — it does not
- * switch on `channelKind`. A new forge implements `dispatch` next to its
- * webhook handler and calls {@link attachHostedAdmissionAdapter} from the
- * channel constructor. Every 2xx from `dispatch` must carry a tag from
- * `internal/channel-dispatch`; an untagged one is answered with 502
- * `channel_outcome_missing`.
- */
-export type HostedAdmissionAdapter = {
-  kind: string;
-  /**
-   * Optional wrap of the capturing `send` / `waitUntil` args (the PR
-   * channels use this to propagate background-task errors). Identity when
-   * omitted.
-   */
-  prepareArgs?(args: ChannelHandlerArgs): ChannelHandlerArgs;
-  dispatch(input: {
-    /** Mounted channel id the delivery addressed (always set by hosted delivery). */
-    channelId?: string;
-    eventType: string;
-    payload: unknown;
-    deliveryId: string;
-    args: ChannelHandlerArgs;
-    /** Mailbox key the control plane already allocated for this admission. */
-    mailboxContinuationKey?: string;
-    /** Trusted control-plane handoff (Slack placeholder ts, …). */
-    platformHandoff?: HostedAdmissionPlatformHandoff;
-  }): Promise<Response>;
-};
-
-const adapters = new WeakMap<object, HostedAdmissionAdapter>();
-
-export function attachHostedAdmissionAdapter(
-  definition: object,
-  adapter: HostedAdmissionAdapter,
-): void {
-  adapters.set(definition, adapter);
-}
-
-export function getHostedAdmissionAdapter(definition: object): HostedAdmissionAdapter | undefined {
-  return adapters.get(definition);
-}

package/src/internal/hosted-admission-context.ts

@@ -1,37 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-/**
- * A `send()` captured outside the delivery (typically at channel `onStart`,
- * which binds directly to the engine) reached the engine during a hosted
- * admission window. Running it would start a local July session on a
- * sessionless pod — invisible to the control plane, destroyed with the pod —
- * so it fails loudly instead. This is a deterministic authored bug and is
- * surfaced as a non-retryable 422 by the admission route.
- */
-export class HostedAdmissionLocalSendError extends Error {
-  constructor() {
-    super(
-      "send() reached the local engine during hosted admission. A send " +
-        "captured at channel startup (onStart) bypasses hosted capture and " +
-        "would run an invisible local session on a sessionless pod. Use the " +
-        "per-delivery send passed to the task callback " +
-        "(task: (args) => args.send(…)) instead.",
-    );
-  }
-}
-
-const admissionWindow = new AsyncLocalStorage<true>();
-
-/**
- * Run `work` inside the hosted admission window. The context follows the
- * async graph, including `waitUntil` task bodies scheduled during dispatch,
- * so the engine can refuse local sends that bypass the capture stub.
- */
-export function runDuringHostedAdmission<T>(work: () => T): T {
-  return admissionWindow.run(true, work);
-}
-
-/** True while executing inside a hosted admission window. */
-export function isDuringHostedAdmission(): boolean {
-  return admissionWindow.getStore() === true;
-}

package/src/internal/hosted-catch-protocol.ts

@@ -1,112 +0,0 @@
-/**
- * Catch ingress wire contract, July copy. The control plane keeps a
- * byte-identical copy of these constants in
- * `backend/packages/server-shared/src/agentServe/agentSdkCatch.ts`; a
- * backend drift test compares the two as text. Neither package imports the
- * other.
- *
- * A caught request is one hosted admission whose `eventType` is
- * {@link AGENT_SDK_CATCH_EVENT_TYPE} and whose `payload` is a
- * {@link CatchRequestEnvelope}: the HTTP request the control plane
- * accepted on a manifest-declared route after verifying the deployment's
- * secret. July replays it into the authored route handler; the control
- * plane never runs channel code.
- */
-
-import { isRecord } from "./is-record.js";
-
-export const AGENT_SDK_CATCH_ENVELOPE_VERSION = 1;
-export const AGENT_SDK_CATCH_EVENT_TYPE = "http.request";
-export const AGENT_SDK_CUSTOM_CHANNEL_KIND = "custom";
-export const AGENT_SDK_SESSION_EVENT_TYPE = "agentsdk.session";
-export const AGENT_SDK_HTTP_CHANNEL_ID = "http";
-export const AGENT_SDK_HTTP_CHANNEL_KIND = "http";
-export const AGENT_SDK_SESSION_RESUME_KEY_PREFIX = "cont:session:";
-export const AGENT_SDK_CATCH_MAX_BODY_BYTES: number = 256 * 1024;
-
-export const AGENT_SDK_CATCH_ROUTE_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
-export type CatchRouteMethod = (typeof AGENT_SDK_CATCH_ROUTE_METHODS)[number];
-
-export type CatchRequestEnvelope = {
-  v: 1;
-  method: CatchRouteMethod;
-  /** Channel-relative path, e.g. `/webhook`. */
-  path: string;
-  /** Raw query string without the leading `?`; empty when absent. */
-  query: string;
-  /** Lowercased header names. */
-  headers: Record<string, string>;
-  body: { encoding: "utf8" | "base64"; data: string } | null;
-  receivedAt: string;
-};
-
-/**
- * Mailbox key the control plane stamps on an explicit `ses_…` resume. The
- * suffix is the CP session id the hosted execution also names, so the
- * engine can recognise the key as "this existing session" rather than a
- * new continuation identity.
- */
-export function hostedSessionResumeKey(sessionPublicId: string): string {
-  return `${AGENT_SDK_SESSION_RESUME_KEY_PREFIX}${sessionPublicId}`;
-}
-
-const ENVELOPE_KEYS = new Set(["v", "method", "path", "query", "headers", "body", "receivedAt"]);
-const METHODS = new Set<string>(AGENT_SDK_CATCH_ROUTE_METHODS);
-const MAX_PATH_CHARS = 1024;
-const MAX_QUERY_CHARS = 4096;
-const MAX_HEADER_COUNT = 64;
-const MAX_HEADER_BYTES = 16 * 1024;
-
-/** Strict parse of a claim-checked catch envelope; anything else is undefined. */
-export function parseCatchRequestEnvelope(value: unknown): CatchRequestEnvelope | undefined {
-  if (!isRecord(value)) {
-    return undefined;
-  }
-  if (
-    Object.keys(value).some(key => !ENVELOPE_KEYS.has(key)) ||
-    value.v !== AGENT_SDK_CATCH_ENVELOPE_VERSION ||
-    typeof value.method !== "string" ||
-    !METHODS.has(value.method) ||
-    typeof value.path !== "string" ||
-    !value.path.startsWith("/") ||
-    value.path.length > MAX_PATH_CHARS ||
-    typeof value.query !== "string" ||
-    value.query.length > MAX_QUERY_CHARS ||
-    typeof value.receivedAt !== "string" ||
-    !isRecord(value.headers)
-  ) {
-    return undefined;
-  }
-  const entries = Object.entries(value.headers);
-  if (entries.length > MAX_HEADER_COUNT) {
-    return undefined;
-  }
-  let headerBytes = 0;
-  for (const [name, headerValue] of entries) {
-    if (typeof headerValue !== "string" || name !== name.toLowerCase()) {
-      return undefined;
-    }
-    headerBytes += name.length + headerValue.length;
-  }
-  if (headerBytes > MAX_HEADER_BYTES) {
-    return undefined;
-  }
-  if (value.body !== null) {
-    if (
-      !isRecord(value.body) ||
-      (value.body.encoding !== "utf8" && value.body.encoding !== "base64") ||
-      typeof value.body.data !== "string"
-    ) {
-      return undefined;
-    }
-  }
-  return value as CatchRequestEnvelope;
-}
-
-/** Raw request bytes from an envelope body; empty for a null body. */
-export function decodeCatchBody(body: CatchRequestEnvelope["body"]): Buffer {
-  if (body === null) {
-    return Buffer.alloc(0);
-  }
-  return Buffer.from(body.data, body.encoding);
-}