@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/cloud-merge.ts

@@ -1,51 +0,0 @@
-import type { AgentCloudOptions, AgentRuntime } from "../types.js";
-
-/**
- * Merge a per-session cloud override over the agent's static cloud config.
- *
- * Session-scoped `repos` / `env` / scalar flags win (so a channel can point
- * a cloud agent at a specific PR per session), and `envVars` are deep-merged
- * with the override taking precedence per key. Returns the defined side when
- * only one is present. Named fields keep base/override precedence explicit
- * at every call site.
- */
-export function mergeCloudOptions(args: {
-  base: AgentCloudOptions | undefined;
-  override: AgentCloudOptions | undefined;
-}): AgentCloudOptions | undefined {
-  const { base, override } = args;
-  if (base === undefined) {
-    return override;
-  }
-  if (override === undefined) {
-    return base;
-  }
-  return {
-    ...base,
-    ...override,
-    ...(base.envVars !== undefined || override.envVars !== undefined
-      ? { envVars: { ...base.envVars, ...override.envVars } }
-      : {}),
-  };
-}
-
-/**
- * Session turn runtime: a per-session `cloud` attach forces cloud even when
- * the agent defaults to local (chat server tools + Drive handoff). A
- * grokbot agent refuses the attach — silently moving its session onto a
- * cloud VM would swap the harness (and the box) out from under it.
- */
-export function resolveSessionRuntime(args: {
-  agentRuntime: AgentRuntime;
-  cloudOverride: AgentCloudOptions | undefined;
-}): AgentRuntime {
-  if (args.cloudOverride === undefined) {
-    return args.agentRuntime;
-  }
-  if (args.agentRuntime === "grokbot") {
-    throw new Error(
-      'Grok Bot sessions cannot attach cloud agents: per-session `cloud` options are not supported on runtime: "grokbot". Refusing the session rather than moving it onto a cloud VM.',
-    );
-  }
-  return "cloud";
-}

package/src/internal/cloud-turn-cost.ts

@@ -1,159 +0,0 @@
-/**
- * Recover token usage / billed cost for cloud turns that finished without
- * either field on `turn.completed`.
- *
- * Cloud `run.wait()` often drops streamed usage after SSE reconnect, and
- * older engines never persisted cost. The playground Trace tab only renders
- * what is on the event, so historical sessions stay blank unless we backfill
- * from `Agent.getUsage` when the stream is read.
- */
-
-import type { ModelSetting, SessionEvent, TurnCost, TurnUsage } from "../types.js";
-import { modelSettingId, turnCostFromCents } from "./turn-cost.js";
-
-export interface CloudRunUsage {
-  runId: string;
-  usage: TurnUsage;
-  cost?: { rawCostCents: number; chargedCents: number };
-}
-
-export interface CloudAgentUsage {
-  usage: TurnUsage;
-  cost?: { rawCostCents: number; chargedCents: number };
-  runs: CloudRunUsage[];
-}
-
-export function usageTokenSum(usage: TurnUsage | undefined): number {
-  if (usage === undefined) {
-    return 0;
-  }
-  return usage.inputTokens + usage.outputTokens + usage.cacheReadTokens + usage.cacheWriteTokens;
-}
-
-export function isUnpricedCompletedTurn(event: SessionEvent): boolean {
-  return (
-    event.type === "turn.completed" &&
-    usageTokenSum(event.data.usage) <= 0 &&
-    event.data.cost === undefined
-  );
-}
-
-export function cloudSdkAgentIdFromEvents(events: ReadonlyArray<SessionEvent>): string | undefined {
-  let sdkAgentId: string | undefined;
-  for (const event of events) {
-    if (event.type !== "agent.bound") {
-      continue;
-    }
-    const id = event.data.sdkAgentId.trim();
-    if (id.startsWith("bc-")) {
-      sdkAgentId = id;
-    }
-  }
-  return sdkAgentId;
-}
-
-/**
- * Copy usage/cost onto unpriced `turn.completed` events. Returns undefined
- * when the snapshot cannot be attributed safely (multiple unmatched turns).
- */
-export function applyCloudUsageToEvents(
-  events: ReadonlyArray<SessionEvent>,
-  billed: CloudAgentUsage,
-  model: ModelSetting,
-): SessionEvent[] | undefined {
-  const completedIndexes: number[] = [];
-  const unpricedIndexes: number[] = [];
-  for (let i = 0; i < events.length; i++) {
-    const event = events[i];
-    if (event === undefined || event.type !== "turn.completed") {
-      continue;
-    }
-    completedIndexes.push(i);
-    if (isUnpricedCompletedTurn(event)) {
-      unpricedIndexes.push(i);
-    }
-  }
-  if (unpricedIndexes.length === 0) {
-    return [...events];
-  }
-
-  const patches = new Map<number, { usage: TurnUsage; cost: TurnCost | undefined }>();
-  if (
-    unpricedIndexes.length === 1 &&
-    completedIndexes.length === 1 &&
-    usageTokenSum(billed.usage) > 0
-  ) {
-    const index = unpricedIndexes[0];
-    if (index !== undefined) {
-      patches.set(index, {
-        usage: billed.usage,
-        cost: turnCostFromBilled(model, billed.cost),
-      });
-    }
-  } else if (
-    billed.runs.length === unpricedIndexes.length &&
-    billed.runs.every(run => usageTokenSum(run.usage) > 0)
-  ) {
-    for (let i = 0; i < unpricedIndexes.length; i++) {
-      const index = unpricedIndexes[i];
-      const run = billed.runs[i];
-      if (index === undefined || run === undefined) {
-        return undefined;
-      }
-      patches.set(index, {
-        usage: run.usage,
-        cost: turnCostFromBilled(model, run.cost),
-      });
-    }
-  } else {
-    return undefined;
-  }
-
-  return events.map((event, index) => {
-    const patch = patches.get(index);
-    if (patch === undefined || event.type !== "turn.completed") {
-      return event;
-    }
-    return {
-      ...event,
-      data: {
-        ...event.data,
-        usage: patch.usage,
-        ...(patch.cost === undefined ? {} : { cost: patch.cost }),
-      },
-    };
-  });
-}
-
-function turnCostFromBilled(
-  model: ModelSetting,
-  cost: { rawCostCents: number; chargedCents: number } | undefined,
-): TurnCost | undefined {
-  if (cost === undefined) {
-    return undefined;
-  }
-  return turnCostFromCents({
-    model: modelSettingId(model),
-    cost,
-    source: "usage",
-  });
-}
-
-export function mapSdkTokenUsage(usage: {
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadTokens: number;
-  cacheWriteTokens: number;
-  reasoningTokens?: number;
-}): TurnUsage {
-  const mapped: TurnUsage = {
-    inputTokens: usage.inputTokens,
-    outputTokens: usage.outputTokens,
-    cacheReadTokens: usage.cacheReadTokens,
-    cacheWriteTokens: usage.cacheWriteTokens,
-  };
-  if (usage.reasoningTokens !== undefined) {
-    mapped.reasoningTokens = usage.reasoningTokens;
-  }
-  return mapped;
-}

package/src/internal/connection-env.ts

@@ -1,106 +0,0 @@
-/**
- * `${NAME}` expansion for MCP connection credentials, applied when a
- * transport is built instead of when its module is imported.
- *
- * Discovery imports `mcp-connections/*.ts` once, at startup. A hosted
- * deployment has none of its secrets in the environment at that point: the
- * control plane binds them per request and `consumeHostedBoundSecrets` copies
- * them into `process.env` at the top of the turn. A `process.env.TOKEN` read
- * inside `defineConnection` therefore captures an empty value for the life of
- * the process, while a `"Bearer ${TOKEN}"` template stays verbatim on the
- * transport and resolves here, each time a client opens.
- */
-
-import { createHash } from "node:crypto";
-import type { ConnectionTransport } from "../types.js";
-
-/** `${NAME}`, plus the `mcp.json` spelling `${env:NAME}`. */
-const ENV_TEMPLATE = /\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)\}/g;
-
-type Env = Record<string, string | undefined>;
-
-/** Credential-bearing values of a transport: HTTP headers or stdio env. */
-function credentials(transport: ConnectionTransport): Record<string, string> | undefined {
-  if ("url" in transport) {
-    return transport.headers;
-  }
-  if ("command" in transport) {
-    return transport.env;
-  }
-  return undefined;
-}
-
-function expand(value: string, env: Env): string {
-  return value.replace(ENV_TEMPLATE, (_match, name: string) => env[name] ?? "");
-}
-
-/** The same object back when nothing templates, so callers can compare by identity. */
-function expandRecord(
-  values: Record<string, string> | undefined,
-  env: Env,
-): Record<string, string> | undefined {
-  if (values === undefined) {
-    return undefined;
-  }
-  const expanded: Record<string, string> = {};
-  let changed = false;
-  for (const [key, value] of Object.entries(values)) {
-    expanded[key] = expand(value, env);
-    changed ||= expanded[key] !== value;
-  }
-  return changed ? expanded : values;
-}
-
-/**
- * Substitute `${NAME}` in the transport's headers (http/sse) or env (stdio)
- * from the environment as it stands now. An unset variable resolves to an
- * empty string, as reading it in the module would have.
- */
-export function resolveConnectionEnvTemplates<T extends ConnectionTransport>(
-  transport: T,
-  env: Env = process.env,
-): T {
-  if ("url" in transport) {
-    const headers = expandRecord(transport.headers, env);
-    return headers === transport.headers ? transport : ({ ...transport, headers } as T);
-  }
-  if ("command" in transport) {
-    const spawnEnv = expandRecord(transport.env, env);
-    return spawnEnv === transport.env ? transport : ({ ...transport, env: spawnEnv } as T);
-  }
-  return transport;
-}
-
-/** Variables a transport templates that the environment does not define, in first-seen order. */
-export function unresolvedConnectionEnvNames(
-  transport: ConnectionTransport,
-  env: Env = process.env,
-): string[] {
-  const missing = new Set<string>();
-  for (const value of Object.values(credentials(transport) ?? {})) {
-    for (const match of value.matchAll(ENV_TEMPLATE)) {
-      const name = match[1];
-      if (name !== undefined && env[name] === undefined) {
-        missing.add(name);
-      }
-    }
-  }
-  return [...missing];
-}
-
-/**
- * Identifies the credentials a client would open with right now, so a cached
- * client is recognizable as stale once the environment changes underneath it.
- * Hashed rather than stored, so the cache key is not a second copy of the
- * secret.
- */
-export function connectionCredentialsFingerprint(
-  transport: ConnectionTransport,
-  env: Env = process.env,
-): string {
-  const resolved = credentials(resolveConnectionEnvTemplates(transport, env));
-  if (resolved === undefined) {
-    return "";
-  }
-  return createHash("sha256").update(JSON.stringify(resolved)).digest("hex");
-}

package/src/internal/continuation-channel.ts

@@ -1,233 +0,0 @@
-import { getBitbucketChannelOptions } from "../channels/bitbucket/bitbucket-channel.js";
-import { getChangeMonitorsChannelOptions } from "../channels/change-monitors/change-monitors-channel.js";
-import { getDeploymentsChannelOptions } from "../channels/deployments/deployments-channel.js";
-import { getGitHubChannelOptions } from "../channels/github/github-channel.js";
-import { getGitLabChannelOptions } from "../channels/gitlab/gitlab-channel.js";
-import { getIssuesChannelOptions } from "../channels/issues/issues-channel.js";
-import { getOriginChannelOptions } from "../channels/origin/origin-channel.js";
-import { getSlackChannelOptions } from "../channels/slack/slack-channel.js";
-import type {
-  AgentArchitecture,
-  ChannelDefinition,
-  ChannelMeta,
-  HttpChannelDefinition,
-} from "../types.js";
-import {
-  type ContinuationIdentity,
-  type ContinuationProtocolVersion,
-  defaultContinuationSelector,
-  handshakeContinuation,
-  normalizeIdentity,
-  omittedV2MembershipDowngrade,
-  omittedV2TypedType,
-} from "./continuation-identity.js";
-
-type ContinuationChannelOptions = {
-  continuation?: ContinuationIdentity;
-};
-
-const CONTINUATION_CHANNEL_PACKS: ReadonlyArray<{
-  kind:
-    | "github"
-    | "slack"
-    | "origin"
-    | "gitlab"
-    | "bitbucket"
-    | "deployments"
-    | "change_monitors"
-    | "issues";
-  getOptions: (definition: object) => ContinuationChannelOptions | undefined;
-  usesDeclaredEvents: boolean;
-}> = [
-  {
-    kind: "gitlab",
-    getOptions: getGitLabChannelOptions,
-    usesDeclaredEvents: true,
-  },
-  {
-    kind: "bitbucket",
-    getOptions: getBitbucketChannelOptions,
-    usesDeclaredEvents: true,
-  },
-  {
-    kind: "github",
-    getOptions: getGitHubChannelOptions,
-    usesDeclaredEvents: true,
-  },
-  {
-    kind: "slack",
-    getOptions: getSlackChannelOptions,
-    usesDeclaredEvents: false,
-  },
-  {
-    kind: "origin",
-    getOptions: getOriginChannelOptions,
-    usesDeclaredEvents: true,
-  },
-  {
-    kind: "deployments",
-    getOptions: getDeploymentsChannelOptions,
-    usesDeclaredEvents: true,
-  },
-  {
-    kind: "change_monitors",
-    getOptions: getChangeMonitorsChannelOptions,
-    usesDeclaredEvents: true,
-  },
-  {
-    kind: "issues",
-    getOptions: getIssuesChannelOptions,
-    usesDeclaredEvents: true,
-  },
-];
-
-export function channelContinuationIdentity(definition: object | undefined): ContinuationIdentity {
-  if (definition === undefined) {
-    return defaultContinuationSelector();
-  }
-  for (const pack of CONTINUATION_CHANNEL_PACKS) {
-    const options = pack.getOptions(definition);
-    if (options !== undefined) {
-      return normalizeIdentity(options.continuation, pack.kind);
-    }
-  }
-  return defaultContinuationSelector();
-}
-
-export function httpContinuationIdentity(
-  httpChannel: HttpChannelDefinition | undefined,
-): ContinuationIdentity {
-  return normalizeIdentity(httpChannel?.continuation, "http");
-}
-
-/**
- * Stamp `/v2` continuation defaults onto channel constructors that omitted
- * `continuation` when the agent deploys onto v2 architecture. GitHub/Origin
- * type (`pr` / `issue` / `none`) follows declared webhook events.
- * Deployments default to `deployments.deployment/v2`. Change Monitors
- * and issues default to `change_monitors.checkpoint/v2` and
- * `issues.issue/v2`.
- * Explicit per-channel selectors are left alone. Idempotent.
- */
-export function applyAgentContinuationDefaults(project: {
-  agent: { architecture?: AgentArchitecture };
-  channels: ReadonlyArray<{ definition: object }>;
-  httpChannel: HttpChannelDefinition;
-}): void {
-  if (project.agent.architecture !== "v2") {
-    return;
-  }
-  for (const channel of project.channels) {
-    stampOmittedChannelContinuation(channel.definition, "v2");
-  }
-  if (project.httpChannel.continuation === undefined) {
-    project.httpChannel.continuation = defaultContinuationSelector("http", "v2");
-  }
-}
-
-/**
- * Warn when an omitted `/v2` selector became type `none` because one
- * declared event sits outside the kind membership. Call before
- * {@link applyAgentContinuationDefaults} so the omitted field is still
- * visible. An explicit `*.none/v2` pin stays silent.
- */
-export function warnOmittedContinuationDowngrades(input: {
-  architecture?: AgentArchitecture;
-  channels: ReadonlyArray<{ id: string; definition: object }>;
-  warn: (id: string, message: string) => void;
-}): void {
-  if (input.architecture !== "v2") {
-    return;
-  }
-  for (const channel of input.channels) {
-    const events = channelDeclaredEventTypes((channel.definition as ChannelDefinition).meta);
-    for (const pack of CONTINUATION_CHANNEL_PACKS) {
-      const options = pack.getOptions(channel.definition);
-      if (options === undefined) {
-        continue;
-      }
-      if (options.continuation !== undefined) {
-        break;
-      }
-      const downgrade = omittedV2MembershipDowngrade(
-        pack.kind,
-        pack.usesDeclaredEvents ? events : undefined,
-      );
-      if (downgrade !== undefined) {
-        input.warn(channel.id, omittedContinuationDowngradeMessage(pack.kind, downgrade));
-      }
-      break;
-    }
-  }
-}
-
-function omittedContinuationDowngradeMessage(
-  kind: string,
-  downgrade: {
-    selector: ContinuationIdentity;
-    unexpected: readonly string[];
-  },
-): string {
-  const membership = omittedV2TypedType(kind) ?? kind;
-  return (
-    `omitted continuation stamped ${downgrade.selector} because ` +
-    `${downgrade.unexpected.join(", ")} ${
-      downgrade.unexpected.length === 1 ? "is" : "are"
-    } not in the ${membership} membership; every delivery on this ` +
-    `channel starts a fresh session. Pin continuation: "${downgrade.selector}" ` +
-    `if that is intended, or drop the event.`
-  );
-}
-
-function stampOmittedChannelContinuation(
-  definition: object,
-  version: ContinuationProtocolVersion,
-): void {
-  const events = channelDeclaredEventTypes((definition as ChannelDefinition).meta);
-  for (const pack of CONTINUATION_CHANNEL_PACKS) {
-    const options = pack.getOptions(definition);
-    if (options === undefined) {
-      continue;
-    }
-    if (options.continuation === undefined) {
-      options.continuation = defaultContinuationSelector(
-        pack.kind,
-        version,
-        pack.usesDeclaredEvents ? events : undefined,
-      );
-    }
-    return;
-  }
-}
-
-/** Kind-specific event lists on `ChannelMeta`; a definition sets at most one. */
-export function channelDeclaredEventTypes(
-  meta: ChannelMeta | undefined,
-): readonly string[] | undefined {
-  return (
-    meta?.githubWebhookEvents ??
-    meta?.originWebhookEvents ??
-    meta?.gitlabWebhookEvents ??
-    meta?.bitbucketWebhookEvents ??
-    meta?.deploymentEventTypes ??
-    meta?.factoryEventTypes ??
-    meta?.slackEventTypes
-  );
-}
-
-export function handshakeChannelContinuation(input: {
-  id: string;
-  definition: ChannelDefinition;
-}): { ok: true } | { ok: false; error: string } {
-  const kind = input.definition.meta?.kind;
-  const eventTypes = channelDeclaredEventTypes(input.definition.meta);
-  const result = handshakeContinuation({
-    kind,
-    eventTypes,
-    identity: channelContinuationIdentity(input.definition),
-  });
-  if (!result.ok) {
-    return { ok: false, error: `channel ${input.id}: ${result.error}` };
-  }
-  return result;
-}