@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/run-client.ts

@@ -1,354 +0,0 @@
-/**
- * Programmatic HTTP client for agent-sdk sessions.
- *
- * Used by `agent-sdk run` and `chat --json`: create/follow a
- * session, collect the NDJSON stream until the turn parks, and return a
- * compact {@link Trajectory} plus the continuation token for follow-ups.
- */
-
-import type { AgentCloudOptions, SessionEvent, SessionPurpose } from "../types.js";
-import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
-import { buildTrajectory, type Trajectory } from "./trajectory.js";
-
-/** Thrown when a turn stream exceeds `timeoutMs`; carries the session id. */
-export class RunSessionTimeoutError extends Error {
-  constructor(
-    message: string,
-    readonly sessionId: string,
-  ) {
-    super(message);
-    this.name = "RunSessionTimeoutError";
-  }
-}
-export interface RunClientOptions extends RequestAuth {
-  baseUrl: string;
-  /** Abort a hung turn. */
-  timeoutMs?: number;
-  /** External cancel (combined with {@link timeoutMs} when both are set). */
-  signal?: AbortSignal;
-  /** Called for each stream event as it arrives (for CLI progress). */
-  onEvent?: (event: SessionEvent) => void;
-  /**
-   * Create-time session purpose. Pass `"eval"` from the eval harness so
-   * the session is marked as regression traffic. Default `"live"`.
-   */
-  purpose?: SessionPurpose;
-}
-
-export interface RunSessionResult {
-  sessionId: string;
-  continuationToken?: string;
-  baseUrl: string;
-  events: SessionEvent[];
-  trajectory: Trajectory;
-  ok: boolean;
-  /**
-   * Index to pass as `startIndex` on the next call for this session. Undefined
-   * when the turn streamed nothing, in which case reuse the previous value.
-   */
-  nextEventIndex?: number;
-}
-
-const TERMINAL_TYPES = new Set(["session.waiting", "session.completed", "session.failed"]);
-
-/**
- * Run one or more messages against a live agent-serve base URL
- * (e.g. `http://127.0.0.1:3000/weather-agent`).
- */
-export async function runSession(
-  options: RunClientOptions & {
-    messages: string[];
-    sessionId?: string;
-    continuationToken?: string;
-    /**
-     * First event index to read when resuming an existing session.
-     *
-     * The stream replays from `startIndex` and this client stops at the first
-     * terminal event, so a caller that sends several turns across separate
-     * `runSession` calls **must** pass the index after its last consumed event
-     * (see {@link RunSessionResult.nextEventIndex}). Omitting it replays the
-     * earlier turn and returns those stale events instead of the new turn's.
-     */
-    startIndex?: number;
-    /** Applied only when creating a new session (first message). */
-    workspaceDir?: string;
-    /** Applied only when creating a new session (first message). */
-    workspaceFiles?: Record<string, string>;
-    /** Applied only when creating a new session (first message). */
-    cloud?: AgentCloudOptions;
-  },
-): Promise<RunSessionResult> {
-  if (options.messages.length === 0) {
-    throw new Error("runSession requires at least one message");
-  }
-  const baseUrl = options.baseUrl.replace(/\/$/, "");
-  let sessionId = options.sessionId;
-  let continuationToken = options.continuationToken;
-  const allEvents: SessionEvent[] = [];
-  let nextEventIndex = options.startIndex ?? 0;
-
-  const auth: RequestAuth = {
-    bearerToken: options.bearerToken,
-    headers: options.headers,
-  };
-
-  for (const message of options.messages) {
-    const turn = await runOneTurn({
-      baseUrl,
-      message,
-      sessionId,
-      continuationToken,
-      startIndex: sessionId === undefined ? 0 : nextEventIndex,
-      auth,
-      timeoutMs: options.timeoutMs,
-      signal: options.signal,
-      onEvent: options.onEvent,
-      purpose: sessionId === undefined ? options.purpose : undefined,
-      workspaceDir: sessionId === undefined ? options.workspaceDir : undefined,
-      workspaceFiles: sessionId === undefined ? options.workspaceFiles : undefined,
-      cloud: sessionId === undefined ? options.cloud : undefined,
-    });
-    sessionId = turn.sessionId;
-    continuationToken = turn.continuationToken;
-    allEvents.push(...turn.events);
-    if (turn.events.length > 0) {
-      const last = turn.events[turn.events.length - 1]!;
-      nextEventIndex = last.index + 1;
-    }
-    if (!turn.ok) {
-      break;
-    }
-  }
-
-  if (sessionId === undefined) {
-    throw new Error("server did not return a session id");
-  }
-
-  const trajectory = buildTrajectory(allEvents);
-  return {
-    sessionId,
-    ...(continuationToken === undefined ? {} : { continuationToken }),
-    baseUrl,
-    events: allEvents,
-    trajectory,
-    ok: trajectory.ok,
-    nextEventIndex: allEvents.length === 0 ? undefined : nextEventIndex,
-  };
-}
-
-interface OneTurnArgs {
-  baseUrl: string;
-  message: string;
-  sessionId?: string;
-  continuationToken?: string;
-  purpose?: SessionPurpose;
-  workspaceDir?: string;
-  workspaceFiles?: Record<string, string>;
-  cloud?: AgentCloudOptions;
-  startIndex: number;
-  auth?: RequestAuth;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  onEvent?: (event: SessionEvent) => void;
-}
-
-interface OneTurnResult {
-  sessionId: string;
-  continuationToken?: string;
-  events: SessionEvent[];
-  ok: boolean;
-}
-
-async function runOneTurn(args: OneTurnArgs): Promise<OneTurnResult> {
-  let sessionId = args.sessionId;
-  let continuationToken = args.continuationToken;
-
-  if (sessionId === undefined) {
-    const body: Record<string, unknown> = { message: args.message };
-    if (args.purpose !== undefined) {
-      body.purpose = args.purpose;
-    }
-    if (args.workspaceDir !== undefined) {
-      body.workspaceDir = args.workspaceDir;
-    }
-    if (args.workspaceFiles !== undefined) {
-      body.workspaceFiles = args.workspaceFiles;
-    }
-    if (args.cloud !== undefined) {
-      body.cloud = args.cloud;
-    }
-    const created = await postJson(args.baseUrl, "/v1/session", body, args.auth);
-    if (created.status >= 400 || created.body.ok === false) {
-      throw new Error(
-        `POST /v1/session failed: ${str(created.body.error) ?? created.status} ${str(created.body.message) ?? ""}`.trim(),
-      );
-    }
-    sessionId = str(created.body.sessionId);
-    continuationToken = str(created.body.continuationToken);
-  } else {
-    const resp = await postJson(
-      args.baseUrl,
-      `/v1/session/${sessionId}`,
-      { message: args.message, continuationToken },
-      args.auth,
-    );
-    if (resp.status >= 400 || resp.body.ok === false) {
-      throw new Error(
-        `follow-up failed: ${str(resp.body.error) ?? resp.status}: ${str(resp.body.message) ?? ""}`.trim(),
-      );
-    }
-    continuationToken = str(resp.body.continuationToken) ?? continuationToken;
-  }
-
-  if (sessionId === undefined) {
-    throw new Error("server did not return a session id");
-  }
-
-  const events = await collectStream({
-    baseUrl: args.baseUrl,
-    sessionId,
-    startIndex: args.startIndex,
-    auth: args.auth,
-    timeoutMs: args.timeoutMs,
-    signal: args.signal,
-    onEvent: args.onEvent,
-  });
-
-  const turnFailed = events.some(e => e.type === "turn.failed");
-  const sessionFailed = events.some(e => e.type === "session.failed");
-  return {
-    sessionId,
-    ...(continuationToken === undefined ? {} : { continuationToken }),
-    events,
-    ok: !turnFailed && !sessionFailed,
-  };
-}
-
-async function collectStream(args: {
-  baseUrl: string;
-  sessionId: string;
-  startIndex: number;
-  auth?: RequestAuth;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-  onEvent?: (event: SessionEvent) => void;
-}): Promise<SessionEvent[]> {
-  const controller = new AbortController();
-  const onExternalAbort = (): void => {
-    controller.abort();
-  };
-  if (args.signal !== undefined) {
-    if (args.signal.aborted) {
-      controller.abort();
-    } else {
-      args.signal.addEventListener("abort", onExternalAbort, { once: true });
-    }
-  }
-  const timer =
-    args.timeoutMs === undefined ? undefined : setTimeout(() => controller.abort(), args.timeoutMs);
-
-  try {
-    const resp = await fetch(
-      `${args.baseUrl}/v1/session/${args.sessionId}/stream?startIndex=${args.startIndex}`,
-      {
-        headers: mergeRequestHeaders(args.auth),
-        signal: controller.signal,
-      },
-    );
-    if (!resp.ok || resp.body === null) {
-      throw new Error(`stream failed (${resp.status})`);
-    }
-
-    const reader = resp.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    const events: SessionEvent[] = [];
-
-    for (;;) {
-      const chunk = await reader.read();
-      if (chunk.done) {
-        break;
-      }
-      buffer += decoder.decode(chunk.value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-      let stop = false;
-      for (const line of lines) {
-        if (line.trim() === "") {
-          continue;
-        }
-        let event: SessionEvent;
-        try {
-          event = JSON.parse(line) as SessionEvent;
-        } catch {
-          continue;
-        }
-        events.push(event);
-        args.onEvent?.(event);
-        if (TERMINAL_TYPES.has(event.type)) {
-          stop = true;
-          break;
-        }
-      }
-      if (stop) {
-        break;
-      }
-    }
-    await reader.cancel().catch(() => {});
-    return events;
-  } catch (error) {
-    if (error instanceof Error && error.name === "AbortError") {
-      if (args.signal?.aborted) {
-        throw new Error("cancelled");
-      }
-      throw new RunSessionTimeoutError(
-        `turn timed out after ${args.timeoutMs ?? "?"}ms (session ${args.sessionId})`,
-        args.sessionId,
-      );
-    }
-    throw error;
-  } finally {
-    args.signal?.removeEventListener("abort", onExternalAbort);
-    if (timer !== undefined) {
-      clearTimeout(timer);
-    }
-  }
-}
-
-async function postJson(
-  baseUrl: string,
-  path: string,
-  body: unknown,
-  auth?: RequestAuth,
-): Promise<{ status: number; body: Record<string, unknown> }> {
-  const resp = await fetch(`${baseUrl}${path}`, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      ...mergeRequestHeaders(auth),
-    },
-    body: JSON.stringify(body),
-  });
-  const text = await resp.text();
-  let parsed: Record<string, unknown> = {};
-  if (text) {
-    try {
-      parsed = JSON.parse(text) as Record<string, unknown>;
-    } catch {
-      parsed = { message: text };
-    }
-  }
-  const anyrunReason = resp.headers.get("x-anyrun-failure-reason");
-  if (
-    anyrunReason !== null &&
-    anyrunReason !== "" &&
-    (parsed.message === undefined || parsed.message === "")
-  ) {
-    parsed.message = anyrunReason;
-  }
-  return { status: resp.status, body: parsed };
-}
-
-function str(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
-}

package/src/internal/runtime-dispatch-runner.ts

@@ -1,50 +0,0 @@
-/**
- * Routes each turn to the runner that owns its runtime: local and cloud
- * turns stay on the Cursor SDK runner, grokbot turns go to the Grok Bot
- * remote client (`internal/grokbot/runner.ts`), which drives the hosted
- * Grok Bot (Sand) harness through the public `/v0/grokbot` session API.
- */
-
-import type { RunnerTurnRequest, TurnOutcome } from "../types.js";
-import type {
-  AgentRunner,
-  PrewarmOutcome,
-  RunnerPrewarmRequest,
-  SteerAckOutcome,
-} from "./sdk-runner.js";
-
-export interface RuntimeDispatchingRunnerOptions {
-  sdkRunner: AgentRunner;
-  grokbot: AgentRunner;
-}
-
-export class RuntimeDispatchingRunner implements AgentRunner {
-  constructor(private readonly options: RuntimeDispatchingRunnerOptions) {}
-
-  async runTurn(request: RunnerTurnRequest): Promise<TurnOutcome> {
-    if (request.runtime === "grokbot") {
-      return this.options.grokbot.runTurn(request);
-    }
-    return this.options.sdkRunner.runTurn(request);
-  }
-
-  async steer(request: { sessionId: string; text: string }): Promise<SteerAckOutcome> {
-    return (await this.options.sdkRunner.steer?.(request)) ?? "revert_to_followup";
-  }
-
-  async prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome> {
-    // Prewarming is a local-harness concern; the engine only calls it for
-    // local-runtime agents.
-    return (
-      this.options.sdkRunner.prewarm?.(request) ?? {
-        warmed: false,
-        reason: "the Cursor SDK runner does not support prewarming",
-      }
-    );
-  }
-
-  async dispose(): Promise<void> {
-    await this.options.sdkRunner.dispose?.();
-    await this.options.grokbot.dispose?.();
-  }
-}

package/src/internal/sanitize-mcp-tool-name.ts

@@ -1,31 +0,0 @@
-/**
- * MCP tool-name sanitization shared by the Cursor-account bridge
- * (`account-mcp.ts`) and advertised connections (`advertise-tools.ts`).
- *
- * Connector display names — and the aggregate `/v1/agent/mcp` names minted
- * from them (`<serverIdentifier>-<tool>`) — can contain spaces, dots, and
- * other characters that are illegal as the tool name a model sees.
- *
- * Character class matches `packages/agent` `normalizeMcpToolName`
- * (`[^a-zA-Z0-9_-]` → `_`). Length cap and the empty fallback match the
- * account bridge (MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$`).
- * Callers that talk to the backend keep the original advertised name.
- */
-
-/** MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$` for tool names. */
-export const MAX_MCP_TOOL_NAME_LENGTH = 128;
-
-/** Connector display names can contain anything (spaces, dots, emoji). */
-export function sanitizeMcpToolName(name: string): string {
-  const cleaned = name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, MAX_MCP_TOOL_NAME_LENGTH);
-  return cleaned === "" ? "tool" : cleaned;
-}
-
-/** `base` for the first claimant, `base_2` / `base_3` … for colliders. */
-export function suffixMcpToolName(base: string, index: number): string {
-  if (index === 0) {
-    return base;
-  }
-  const suffix = `_${index + 1}`;
-  return `${base.slice(0, MAX_MCP_TOOL_NAME_LENGTH - suffix.length)}${suffix}`;
-}

package/src/internal/schedule-runner.ts

@@ -1,154 +0,0 @@
-/**
- * Cron dispatch for `agent/schedules/`. In production mode a minute-aligned
- * ticker fires matching schedules (UTC evaluation); in dev mode nothing
- * fires automatically and `POST /v1/dev/schedules/:scheduleId` dispatches a
- * schedule by hand, exactly once, through the same path.
- */
-
-import type { AgentProject, AuthContext, ChannelSession, ReceiveInput } from "../types.js";
-import { type CronExpression, parseCron } from "./cron.js";
-import { SCHEDULE_CHANNEL_PREFIX, type SessionEngine } from "./session-engine.js";
-
-export const APP_AUTH: AuthContext = {
-  authenticator: "app",
-  principalId: "agent-serve:app",
-  principalType: "runtime",
-};
-
-export class UnknownScheduleError extends Error {
-  constructor(
-    scheduleId: string,
-    readonly availableScheduleIds: string[],
-  ) {
-    super(`Unknown schedule "${scheduleId}"`);
-    this.name = "UnknownScheduleError";
-  }
-}
-
-interface PreparedSchedule {
-  name: string;
-  cron: CronExpression;
-  discovered: AgentProject["schedules"][number];
-}
-
-export class ScheduleRunner {
-  private readonly schedules: PreparedSchedule[];
-  private timer: NodeJS.Timeout | undefined;
-  private lastFiredMinute = -1;
-
-  constructor(
-    private readonly engine: SessionEngine,
-    project: AgentProject,
-    private readonly logger: (line: string) => void = () => {},
-  ) {
-    this.schedules = project.schedules.map(schedule => ({
-      name: schedule.name,
-      cron: parseCron(schedule.cron),
-      discovered: schedule,
-    }));
-  }
-
-  get scheduleIds(): string[] {
-    return this.schedules.map(schedule => schedule.name);
-  }
-
-  start(): void {
-    if (this.timer !== undefined || this.schedules.length === 0) {
-      return;
-    }
-    this.arm();
-  }
-
-  stop(): void {
-    if (this.timer !== undefined) {
-      clearTimeout(this.timer);
-      this.timer = undefined;
-    }
-  }
-
-  private arm(): void {
-    const now = Date.now();
-    const nextMinute = (Math.floor(now / 60_000) + 1) * 60_000;
-    this.timer = setTimeout(() => this.tick(), nextMinute - now + 250);
-    this.timer.unref?.();
-  }
-
-  private tick(): void {
-    const now = new Date();
-    const minute = Math.floor(now.getTime() / 60_000);
-    if (minute !== this.lastFiredMinute) {
-      this.lastFiredMinute = minute;
-      for (const schedule of this.schedules) {
-        if (schedule.cron.matches(now)) {
-          void this.dispatch(schedule.name).catch(error => {
-            this.logger(
-              `[agent-sdk] schedule "${schedule.name}" dispatch failed: ${
-                error instanceof Error ? error.message : String(error)
-              }`,
-            );
-          });
-        }
-      }
-    }
-    this.arm();
-  }
-
-  /** Fire a schedule by name, exactly once. Returns the started sessions. */
-  async dispatch(scheduleId: string): Promise<{ sessionIds: string[] }> {
-    const schedule = this.schedules.find(s => s.name === scheduleId);
-    if (schedule === undefined) {
-      throw new UnknownScheduleError(scheduleId, this.scheduleIds);
-    }
-    const definition = schedule.discovered.definition;
-    const channelId = `${SCHEDULE_CHANNEL_PREFIX}${schedule.name}`;
-
-    if (definition.markdown !== undefined) {
-      const { sessionId, done } = await this.engine.runTask({
-        channelId,
-        prompt: definition.markdown,
-        auth: APP_AUTH,
-        title: `Schedule ${schedule.name}`,
-      });
-      this.engine.trackBackground(done);
-      return { sessionIds: [sessionId] };
-    }
-
-    if (definition.run === undefined) {
-      throw new Error(`Schedule "${scheduleId}" has no markdown or run form`);
-    }
-
-    const sessionIds: string[] = [];
-    const receivePromises: Array<Promise<unknown>> = [];
-    const receive = (
-      channel: Parameters<SessionEngine["receive"]>[0],
-      input: ReceiveInput,
-    ): Promise<ChannelSession> => {
-      const promise = this.engine.receive(channel, input).then(session => {
-        sessionIds.push(session.id);
-        return session;
-      });
-      receivePromises.push(promise.catch(() => {}));
-      return promise;
-    };
-
-    await definition.run({
-      receive,
-      callTool: (toolName, input, callOptions) =>
-        this.engine.callTool(toolName, input, {
-          auth: APP_AUTH,
-          ...callOptions,
-        }),
-      waitUntil: promise => {
-        this.engine.trackBackground(promise);
-      },
-      appAuth: APP_AUTH,
-      host: this.engine.host,
-      artifacts: this.engine.artifacts,
-    });
-    // Collect ids from receive() calls the handler chose not to await
-    // (commonly wrapped in waitUntil); receive resolves at message accept,
-    // not turn completion, so this settles fast.
-    await Promise.allSettled(receivePromises);
-    return { sessionIds };
-  }
-}