@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/turn-cost.ts

@@ -1,136 +0,0 @@
-/**
- * Dollar cost for an agent turn, computed by the Cloud Agents
- * `POST /v1/models/estimate-cost` endpoint (billed usage events when an
- * agent/conversation id is known, otherwise live catalog pricing).
- */
-
-import type { ModelSetting, TurnCost, TurnUsage } from "../types.js";
-import { cursorExternalApiUrl, resolveApiKey } from "./cursor/credentials.js";
-
-export interface UsageCostCents {
-  rawCostCents: number;
-  chargedCents: number;
-}
-
-export interface EstimateTurnCostInput {
-  model: ModelSetting;
-  usage?: TurnUsage;
-  agentId?: string;
-  conversationId?: string;
-  runId?: string;
-}
-
-export type EstimateTurnCostFn = (input: EstimateTurnCostInput) => Promise<TurnCost | undefined>;
-
-export function modelSettingId(model: ModelSetting): string {
-  return typeof model === "string" ? model : model.id;
-}
-
-/**
- * This estimate-cost client treats OpenAI-compat usage as **provider-gross**
- * (local playground: `prompt_tokens` includes `cachedPromptTokens`). Catalog
- * `costForBaseTier` assumes Anthropic / billing-style disjoint nets and ADDs
- * `cacheRead × cachedRate` on top of `input × inputRate`, so we send
- * `input − cache` for Grok / xAI / GPT / o-series.
- *
- * Non-OpenAI-compat models are left alone. `input < cache` is only a
- * defensive clamp (avoid a negative uncached count), not a detector for
- * billed / openaiProxy-shaped tokens. Cloud catalog fallback with already-
- * netted OpenAI-compat usage is out of scope here.
- */
-export function isOpenAiCompatGrossCacheModel(model: ModelSetting): boolean {
-  const id = modelSettingId(model).toLowerCase();
-  return (
-    id.includes("grok") || id.includes("xai") || id.includes("gpt") || /(^|[-_/])o[1-9]/.test(id)
-  );
-}
-
-export function toCatalogDisjointUsage(usage: TurnUsage, model?: ModelSetting): TurnUsage {
-  if (model === undefined || !isOpenAiCompatGrossCacheModel(model)) {
-    return usage;
-  }
-  const cachedTokens = usage.cacheReadTokens + usage.cacheWriteTokens;
-  if (cachedTokens === 0 || usage.inputTokens < cachedTokens) {
-    return usage;
-  }
-  return {
-    ...usage,
-    inputTokens: usage.inputTokens - cachedTokens,
-  };
-}
-
-export function roundCostUsd(usd: number): number {
-  return Math.round(usd * 1e6) / 1e6;
-}
-
-export function turnCostFromCents(args: {
-  model: string | ModelSetting;
-  cost: UsageCostCents;
-  source: TurnCost["source"];
-}): TurnCost {
-  const totalUsd = roundCostUsd(args.cost.chargedCents / 100);
-  const model = typeof args.model === "string" ? args.model : modelSettingId(args.model);
-  return {
-    totalUsd,
-    inputUsd: 0,
-    outputUsd: 0,
-    cacheReadUsd: 0,
-    cacheWriteUsd: 0,
-    model,
-    source: args.source,
-    rawCostCents: args.cost.rawCostCents,
-    chargedCents: args.cost.chargedCents,
-  };
-}
-
-interface EstimateCostApiResponse {
-  model?: string;
-  cost?: UsageCostCents;
-  source?: "usage" | "catalog";
-}
-
-export async function estimateTurnCostFromApi(
-  input: EstimateTurnCostInput,
-): Promise<TurnCost | undefined> {
-  const resolved = await resolveApiKey();
-  if (resolved === undefined) {
-    return undefined;
-  }
-  const model = modelSettingId(input.model);
-  const catalogUsage =
-    input.usage === undefined ? undefined : toCatalogDisjointUsage(input.usage, input.model);
-  const response = await fetch(`${cursorExternalApiUrl()}/v1/models/estimate-cost`, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${resolved.apiKey}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({
-      model,
-      inputTokens: catalogUsage?.inputTokens,
-      outputTokens: catalogUsage?.outputTokens,
-      cacheReadTokens: catalogUsage?.cacheReadTokens,
-      cacheWriteTokens: catalogUsage?.cacheWriteTokens,
-      agentId: input.agentId,
-      conversationId: input.conversationId,
-      runId: input.runId,
-    }),
-  });
-  if (!response.ok) {
-    return undefined;
-  }
-  let body: EstimateCostApiResponse;
-  try {
-    body = (await response.json()) as EstimateCostApiResponse;
-  } catch {
-    return undefined;
-  }
-  if (typeof body.cost?.rawCostCents !== "number" || typeof body.cost.chargedCents !== "number") {
-    return undefined;
-  }
-  return turnCostFromCents({
-    model: body.model ?? model,
-    cost: body.cost,
-    source: body.source === "usage" ? "usage" : "catalog",
-  });
-}

package/src/internal/turn-governor.ts

@@ -1,145 +0,0 @@
-/**
- * FIFO admission of model turns under `concurrency.maxRunningTurns`
- * (see {@link AgentConcurrencyOptions}). One governor per session engine:
- * every turn acquires a slot before its SDK run starts and releases it when
- * the run settles, so at most `maxRunningTurns` turns execute at once and
- * the rest wait in arrival order instead of failing.
- *
- * Waiting is cancellable: the engine passes the turn's abort signal, so a
- * follow-up that preempts a queued turn (or an explicit `interrupt()`)
- * removes the waiter without ever running it.
- */
-
-import type { AgentConcurrencyOptions } from "../types.js";
-
-export interface TurnPermit {
-  /** Return the slot. Idempotent; wakes the oldest waiter, if any. */
-  release(): void;
-}
-
-export interface AcquireTurnSlotArgs {
-  sessionId: string;
-  /** Abort waiting (preemption / interrupt). Ignored once a slot is held. */
-  signal?: AbortSignal;
-  /**
-   * Called synchronously when the turn must wait, with its 1-based
-   * position among waiting turns at enqueue time.
-   */
-  onQueued?: (position: number) => void;
-}
-
-interface TurnWaiter {
-  sessionId: string;
-  grant: (permit: TurnPermit) => void;
-  cancel: () => void;
-  cleanup: () => void;
-}
-
-export class TurnGovernor {
-  /** The configured ceiling, or undefined for unlimited. */
-  readonly maxRunningTurns: number | undefined;
-  private running = 0;
-  private readonly waiters: TurnWaiter[] = [];
-  /** Sessions currently waiting for a slot (at most one turn per session). */
-  private readonly queuedSessions = new Set<string>();
-
-  constructor(concurrency: AgentConcurrencyOptions | undefined) {
-    this.maxRunningTurns = concurrency?.maxRunningTurns;
-  }
-
-  /** True when a `maxRunningTurns` ceiling is configured. */
-  get limited(): boolean {
-    return this.maxRunningTurns !== undefined;
-  }
-
-  /** True while `sessionId` has a turn waiting for a slot. */
-  isQueued(sessionId: string): boolean {
-    return this.queuedSessions.has(sessionId);
-  }
-
-  /** Turns currently waiting for a slot. */
-  get queuedCount(): number {
-    return this.waiters.length;
-  }
-
-  /** Turns currently holding a slot. */
-  get runningCount(): number {
-    return this.running;
-  }
-
-  /**
-   * Acquire a turn slot. Resolves with a permit once a slot is free (FIFO
-   * behind earlier waiters), or with `undefined` when the abort signal
-   * fires while waiting — the turn must then settle as cancelled without
-   * running. Unlimited governors grant immediately.
-   */
-  acquire(args: AcquireTurnSlotArgs): Promise<TurnPermit | undefined> {
-    const limit = this.maxRunningTurns;
-    if (limit === undefined) {
-      return Promise.resolve(NO_OP_PERMIT);
-    }
-    if (this.running < limit && this.waiters.length === 0) {
-      return Promise.resolve(this.grantSlot());
-    }
-    // Saturated. A turn that is already preempted never enqueues.
-    if (args.signal?.aborted === true) {
-      return Promise.resolve(undefined);
-    }
-    return new Promise<TurnPermit | undefined>(resolve => {
-      const waiter: TurnWaiter = {
-        sessionId: args.sessionId,
-        grant: permit => resolve(permit),
-        cancel: () => resolve(undefined),
-        cleanup: () => {
-          this.queuedSessions.delete(args.sessionId);
-          args.signal?.removeEventListener("abort", onAbort);
-        },
-      };
-      const onAbort = (): void => {
-        const index = this.waiters.indexOf(waiter);
-        if (index === -1) {
-          return;
-        }
-        this.waiters.splice(index, 1);
-        waiter.cleanup();
-        waiter.cancel();
-      };
-      this.waiters.push(waiter);
-      this.queuedSessions.add(args.sessionId);
-      args.signal?.addEventListener("abort", onAbort, { once: true });
-      args.onQueued?.(this.waiters.length);
-    });
-  }
-
-  /** Take a slot and build its (idempotent) release handle. */
-  private grantSlot(): TurnPermit {
-    this.running += 1;
-    let released = false;
-    return {
-      release: () => {
-        if (released) {
-          return;
-        }
-        released = true;
-        this.running -= 1;
-        this.wakeNextWaiter();
-      },
-    };
-  }
-
-  private wakeNextWaiter(): void {
-    const limit = this.maxRunningTurns;
-    if (limit === undefined || this.running >= limit) {
-      return;
-    }
-    const waiter = this.waiters.shift();
-    if (waiter === undefined) {
-      return;
-    }
-    waiter.cleanup();
-    waiter.grant(this.grantSlot());
-  }
-}
-
-/** Permit handed out by unlimited governors. */
-const NO_OP_PERMIT: TurnPermit = { release: () => {} };

package/src/internal/turn-lease-store.ts

@@ -1,144 +0,0 @@
-/**
- * Durable per-session turn ownership: `activeTurns` is in-memory, so servers
- * sharing a state root would otherwise both run the same session.
- *
- * Exclusion, staleness and liveness refresh come from `proper-lockfile`, which
- * the monorepo already uses for the git cache. Hand-rolling them means
- * inferring that a process died — timeouts, heartbeats, and a takeover path
- * that has to stay atomic while removing another owner's claim. That is where
- * the subtle races live, and none of it is specific to turns.
- *
- * Liveness is lock age, not pid: containers have separate PID namespaces.
- */
-
-import { mkdir } from "node:fs/promises";
-import { join } from "node:path";
-import * as lockfile from "proper-lockfile";
-
-/** A held turn lease. Releasing is idempotent. */
-export interface TurnLease {
-  release(): Promise<void>;
-}
-
-/** Reject path traversal; session ids are opaque strings from the caller. */
-function safeKey(sessionId: string): string {
-  const sanitized = sessionId
-    .trim()
-    .replace(/[^a-zA-Z0-9._-]+/g, "_")
-    .replace(/^\.+/, "")
-    .replace(/\.+/g, "_")
-    .slice(0, 180);
-  return sanitized === "" ? "_empty" : sanitized;
-}
-
-interface HeldLock {
-  release: () => Promise<void>;
-  /** The coalesce drain nests turns, so the same session is acquired twice. */
-  refs: number;
-}
-
-export class TurnLeaseStore {
-  private readonly dir: string;
-  private readonly staleMs: number;
-  /** Locks this process holds. Their release closures cannot live on disk. */
-  private readonly held = new Map<string, HeldLock>();
-
-  constructor(dir: string, options: { ttlMs?: number } = {}) {
-    this.dir = dir;
-    // Several refreshes, so a slow owner is not mistaken for a dead one.
-    this.staleMs = options.ttlMs ?? 30_000;
-  }
-
-  private path(sessionId: string): string {
-    return join(this.dir, `${safeKey(sessionId)}.lease`);
-  }
-
-  /**
-   * Undefined when another process holds this session and is still refreshing.
-   *
-   * `onCompromised` fires when the lock is lost mid-turn — the owner stalled
-   * past the stale window and a successor took over. No lease scheme can stop
-   * that; the callback is how the displaced turn learns to stand down instead
-   * of answering alongside its successor.
-   */
-  async acquire(sessionId: string, onCompromised?: () => void): Promise<TurnLease | undefined> {
-    const existing = this.held.get(sessionId);
-    if (existing !== undefined) {
-      existing.refs += 1;
-      return this.handle(sessionId);
-    }
-
-    await mkdir(this.dir, { recursive: true });
-    let release: () => Promise<void>;
-    try {
-      release = await lockfile.lock(this.path(sessionId), {
-        realpath: false,
-        retries: 0,
-        stale: this.staleMs,
-        // How often the library refreshes the lock's mtime while we hold it.
-        update: 5_000,
-        onCompromised: () => {
-          this.held.delete(sessionId);
-          onCompromised?.();
-        },
-      });
-    } catch {
-      // Held elsewhere, or the store is unusable. Either way this process must
-      // not run the turn: coalescing costs latency, two servers on one session
-      // costs the conversation.
-      return undefined;
-    }
-    this.held.set(sessionId, { release, refs: 1 });
-    return this.handle(sessionId);
-  }
-
-  private handle(sessionId: string): TurnLease {
-    let released = false;
-    return {
-      release: async () => {
-        if (released) {
-          return;
-        }
-        released = true;
-        const lock = this.held.get(sessionId);
-        if (lock === undefined) {
-          return;
-        }
-        lock.refs -= 1;
-        if (lock.refs > 0) {
-          return;
-        }
-        this.held.delete(sessionId);
-        // Throws if the lock was already compromised, which is not our problem
-        // to solve here: the successor owns it.
-        await lock.release().catch(() => {});
-      },
-    };
-  }
-
-  /** Graceful shutdown: drop every claim so a successor need not wait it out. */
-  async releaseAll(): Promise<void> {
-    for (const [sessionId, lock] of [...this.held]) {
-      this.held.delete(sessionId);
-      await lock.release().catch(() => {});
-    }
-  }
-
-  /**
-   * The session is running in another server process. Mirrors the engine's
-   * in-memory `isTurnRunning`, which only ever sees this process.
-   */
-  async runningElsewhere(sessionId: string): Promise<boolean> {
-    if (this.held.has(sessionId)) {
-      return false;
-    }
-    try {
-      return await lockfile.check(this.path(sessionId), {
-        realpath: false,
-        stale: this.staleMs,
-      });
-    } catch {
-      return false;
-    }
-  }
-}

package/src/internal/turn-outbox.ts

@@ -1,77 +0,0 @@
-/**
- * Hand-off of a message to the server that holds the session's turn lease.
- *
- * Blue/green replicas share a state root but not a process, and only the
- * lease holder can admit a message to its running turn. A server that
- * receives a message for a turn it does not own drops it here, under
- * `<stateRoot>/outbox/<sessionId>`; the holder takes everything out while its
- * turn runs and once more after releasing the lease. Local messages never
- * touch this.
- */
-
-import { randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
-export interface OutboxItem<T> {
-  message: string;
-  options: T;
-}
-
-function safeKey(sessionId: string): string {
-  const sanitized = sessionId
-    .trim()
-    .replace(/[^a-zA-Z0-9._-]+/g, "_")
-    .replace(/^\.+/, "")
-    .replace(/\.+/g, "_")
-    .slice(0, 180);
-  return sanitized === "" ? "_empty" : sanitized;
-}
-
-export class TurnOutbox<T> {
-  private readonly rootDir: string;
-
-  constructor(rootDir: string) {
-    this.rootDir = rootDir;
-  }
-
-  private dir(sessionId: string): string {
-    return join(this.rootDir, safeKey(sessionId));
-  }
-
-  async post(sessionId: string, item: OutboxItem<T>): Promise<void> {
-    const dir = this.dir(sessionId);
-    await mkdir(dir, { recursive: true });
-    // Timestamp first so a listing sorts in arrival order.
-    const path = join(dir, `${Date.now()}-${randomUUID()}.json`);
-    await writeFile(`${path}.tmp`, `${JSON.stringify(item)}\n`, "utf8");
-    await rename(`${path}.tmp`, path);
-  }
-
-  /** Remove and return everything posted, in arrival order. */
-  async takeAll(sessionId: string): Promise<OutboxItem<T>[]> {
-    const dir = this.dir(sessionId);
-    let names: string[];
-    try {
-      names = await readdir(dir);
-    } catch {
-      return [];
-    }
-    const items: OutboxItem<T>[] = [];
-    for (const name of names.filter(n => n.endsWith(".json")).sort()) {
-      const path = join(dir, name);
-      try {
-        const raw = await readFile(path, "utf8");
-        await unlink(path);
-        items.push(JSON.parse(raw) as OutboxItem<T>);
-      } catch {
-        // Taken by the holder between readdir and here.
-      }
-    }
-    return items;
-  }
-
-  async clear(sessionId: string): Promise<void> {
-    await rm(this.dir(sessionId), { recursive: true, force: true });
-  }
-}