@cursor/bdk 0.2.1

package/dist/internal/scm/pr-url.js

@@ -0,0 +1,152 @@
+/**
+ * Provider-neutral PR URL parse. GitHub.com plus the Origin page shapes
+ * humans paste: cursor.com/codebase (canonical), origin.cursor.com, and the
+ * retired review-host shape that older links and stored PR records still
+ * carry.
+ *
+ * {@link parseScmPrUrl} is the wider parse the review seams use: it also
+ * recognizes GitLab merge requests (`/-/merge_requests/<iid>` on any host),
+ * Bitbucket Cloud / Data Center pull requests, and GitHub Enterprise Server
+ * (`/<owner>/<repo>/pull/<n>` on a host that is none of the above). The
+ * narrow {@link parsePrUrl} keeps its github.com + Origin contract for the
+ * free-text callers (Slack `pr-ref`) where "any host with /pull/N" would be
+ * too eager.
+ */
+const ORIGIN_PAGE = /^origin(-[a-z0-9]+)?\.cursor\.com$/i;
+/**
+ * Retired Origin UI host. Accepted on input only, for links minted before
+ * the move to cursor.com/codebase; every canonical URL this module emits is
+ * the cursor.com shape.
+ */
+const LEGACY_REVIEW_CURSOR_HOSTS = new Set(["review.cursor.com"]);
+function positiveInt(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        return undefined;
+    }
+    return n;
+}
+function parsed(provider, host, owner, repo, number, url) {
+    if (owner === undefined ||
+        owner === "" ||
+        repo === undefined ||
+        repo === "" ||
+        number === undefined) {
+        return undefined;
+    }
+    const canonical = url !== null && url !== void 0 ? url : (provider === "origin"
+        ? `https://cursor.com/codebase/${owner}/${repo}/pull/${number}`
+        : `https://${host}/${owner}/${repo}/pull/${number}`);
+    return { provider, owner, repo, number, url: canonical, host };
+}
+/** Strip Slack mrkdwn wrappers and trailing punctuation before `URL`. */
+function normalizeRaw(raw) {
+    return raw
+        .trim()
+        .replace(/^[<[]+/, "")
+        .replace(/[>\].,;]+$/, "");
+}
+function isGithubDotCom(host) {
+    return host === "github.com" || host === "www.github.com";
+}
+/** github.com and Origin only — the contract free-text PR references use. */
+export function parsePrUrl(raw) {
+    const wide = parseScmPrUrl(raw);
+    if (wide === undefined) {
+        return undefined;
+    }
+    if (wide.provider === "origin") {
+        return Object.assign(Object.assign({}, wide), { provider: "origin" });
+    }
+    if (wide.provider === "github" && isGithubDotCom(wide.host)) {
+        return Object.assign(Object.assign({}, wide), { provider: "github" });
+    }
+    return undefined;
+}
+/**
+ * Every provider shape, including GitHub Enterprise Server. The GitLab and
+ * Bitbucket path shapes are unambiguous on any host; a plain
+ * `/<owner>/<repo>/pull/<n>` on a host that is not github.com, Origin,
+ * GitLab, or Bitbucket is taken as GHES (the only remaining forge with that
+ * route). Callers that must not accept arbitrary hosts use
+ * {@link parsePrUrl}.
+ */
+export function parseScmPrUrl(raw) {
+    let url;
+    try {
+        url = new URL(normalizeRaw(raw));
+    }
+    catch (_a) {
+        return undefined;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        return undefined;
+    }
+    const parts = url.pathname.split("/").filter(Boolean);
+    const host = url.hostname.toLowerCase();
+    if (ORIGIN_PAGE.test(host) && parts.length >= 4 && parts[2] === "github") {
+        return parsed("origin", host, parts[0], parts[1], positiveInt(parts[3]));
+    }
+    if ((host === "cursor.com" || host === "www.cursor.com") &&
+        parts[0] === "codebase" &&
+        parts.length >= 5 &&
+        parts[3] === "pull") {
+        return parsed("origin", host, parts[1], parts[2], positiveInt(parts[4]));
+    }
+    if (LEGACY_REVIEW_CURSOR_HOSTS.has(host) && parts[0] === "pr") {
+        if (parts.length >= 5 && parts[3] === "github") {
+            return parsed("origin", host, parts[1], parts[2], positiveInt(parts[4]));
+        }
+        if (parts.length >= 4) {
+            return parsed("origin", host, parts[1], parts[2], positiveInt(parts[3]));
+        }
+    }
+    // GitLab MR page: /<group>/[<subgroup>/…]<project>/-/merge_requests/<iid>
+    const separator = parts.indexOf("-");
+    if (separator >= 2 &&
+        parts[separator + 1] === "merge_requests" &&
+        parts.length >= separator + 3) {
+        const owner = parts.slice(0, separator - 1).join("/");
+        const repo = parts[separator - 1];
+        const number = positiveInt(parts[separator + 2]);
+        return parsed("gitlab", host, owner, repo, number, number === undefined
+            ? undefined
+            : `https://${host}/${owner}/${repo}/-/merge_requests/${number}`);
+    }
+    // Bitbucket Cloud: bitbucket.org/<workspace>/<slug>/pull-requests/<id>
+    if ((host === "bitbucket.org" || host === "www.bitbucket.org") &&
+        parts.length >= 4 &&
+        parts[2] === "pull-requests") {
+        const number = positiveInt(parts[3]);
+        return parsed("bitbucket", "bitbucket.org", parts[0], parts[1], number, number === undefined
+            ? undefined
+            : `https://bitbucket.org/${parts[0]}/${parts[1]}/pull-requests/${number}`);
+    }
+    // Bitbucket Data Center: [/<context>]/projects/<KEY>/repos/<slug>/pull-requests/<id>
+    // (personal repos: /users/<name>/repos/<slug>/…, full name `~name/slug`).
+    const dc = parts.findIndex((part, index) => (part === "projects" || part === "users") &&
+        parts[index + 2] === "repos" &&
+        parts[index + 4] === "pull-requests");
+    if (dc !== -1 && parts.length >= dc + 6) {
+        const number = positiveInt(parts[dc + 5]);
+        const owner = parts[dc] === "users" ? `~${parts[dc + 1]}` : parts[dc + 1];
+        const slug = parts[dc + 3];
+        const context = parts.slice(0, dc).join("/");
+        return parsed("bitbucket", host, owner, slug, number, number === undefined
+            ? undefined
+            : `${url.origin}/${context === "" ? "" : `${context}/`}${parts.slice(dc, dc + 4).join("/")}/pull-requests/${number}`);
+    }
+    // GitHub (dotcom or Enterprise Server): /<owner>/<repo>/pull/<n>. Checked
+    // last so the forge-specific shapes above win on shared hosts.
+    if (parts.length >= 4 &&
+        parts[2] === "pull" &&
+        !ORIGIN_PAGE.test(host) &&
+        !/(^|\.)cursor\.com$/.test(host)) {
+        const githubHost = isGithubDotCom(host) ? "github.com" : host;
+        return parsed("github", githubHost, parts[0], parts[1], positiveInt(parts[3]));
+    }
+    return undefined;
+}

package/dist/internal/sdk-runner.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Executes turns on the Cursor harness through `@cursor/sdk`.
+ * Each framework session maps 1:1 to an SDK agent. Local agents use the
+ * session id as the SDK agent id and materialize a workspace for project
+ * settings; cloud agents use Cursor cloud (`bc-…` ids) with optional
+ * `cloud` options from `defineAgent`.
+ */
+import { type LocalAgentStore, type ModelSelection, type RunResult } from "@cursor/sdk";
+import { type ModelSetting, type RunnerTurnRequest, type TurnOutcome } from "../types.js";
+import type { ConversationMirror } from "./conversation-mirror.js";
+/** Mirrors @cursor/sdk's SteerAckOutcome; the published dist may predate it. */
+export type SteerAckOutcome = "complete_delivered" | "revert_to_followup";
+/** Internal seam between the session engine and the Cursor SDK harness. */
+export interface AgentRunner {
+    runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+    steer?(request: {
+        sessionId: string;
+        text: string;
+    }): Promise<SteerAckOutcome>;
+    /**
+     * Resolve a local workspace before any session needs it, so the first turn
+     * is not the one that pays for it. Best effort, hence the reported outcome:
+     * a runner that cannot warm must say so rather than let a caller log
+     * success over a workspace that was never touched.
+     */
+    prewarm?(request: RunnerPrewarmRequest): Promise<PrewarmOutcome>;
+    dispose?(): Promise<void>;
+}
+/**
+ * The parts of a turn that decide which local executor it runs on. Must stay
+ * a subset of {@link RunnerTurnRequest} — anything that disagrees warms an
+ * executor no turn will ask for.
+ */
+export type RunnerPrewarmRequest = Pick<RunnerTurnRequest, "workspaceDir" | "runnerStateDir" | "sandbox" | "tools" | "disallowedTools" | "mcpServers" | "perSendMcpServers" | "subagents" | "model">;
+/** Whether a workspace was actually resolved, and why not when it wasn't. */
+export type PrewarmOutcome = {
+    readonly warmed: true;
+} | {
+    readonly warmed: false;
+    readonly reason: string;
+};
+/**
+ * How long a non-`--dev` serve holds workspace scans (rules, skills,
+ * `AGENTS.md`, ignore files). The SDK default is 20s for an editor whose
+ * files move under it; agent-serve checkouts only change on deploy, so a
+ * missed mid-process edit is the right trade. `CURSOR_RIPWALK_CACHE_TTL_MS`
+ * still wins when set. `--dev` leaves the 20s default so skill edits show up.
+ */
+export declare const SERVE_WORKSPACE_SCAN_CACHE_TTL_MS: number;
+/**
+ * Resolve the SDK workspace-scan TTL for this serve. `undefined` means "do
+ * not call `Cursor.configure`" and leave the SDK at its 20s editor default.
+ */
+export declare function resolveServeWorkspaceScanCacheTtlMs(args: {
+    dev: boolean;
+    env?: NodeJS.ProcessEnv;
+}): number | undefined;
+export interface CursorSdkRunnerOptions {
+    /** Cursor API key. Defaults to the `CURSOR_API_KEY` environment variable. */
+    apiKey?: string;
+    /**
+     * Conversation store override. Defaults to a JSONL store under the
+     * engine's state root; install `sqlite3` and pass an SQLite-backed
+     * `LocalAgentStore` for heavy multi-session concurrency.
+     */
+    store?: LocalAgentStore;
+    /**
+     * Durable mirror for local conversations (v2 hosted engines). Hydrated
+     * before `Agent.resume` so a follow-up landing on a fresh pod finds the
+     * conversation, and persisted — awaited — after each local turn settles,
+     * because a hosted pod can be parked right after the execution reply.
+     */
+    conversationMirror?: ConversationMirror;
+    /** Diagnostics for degraded paths (resume-miss fallback). */
+    logger?: (line: string) => void;
+    /**
+     * Hold workspace scans this long (ms). Applied via `Cursor.configure` so
+     * each new local executor reuses the walk. Omit to keep the SDK 20s default.
+     */
+    workspaceScanCacheTtlMs?: number;
+}
+/**
+ * The backend's `NotLoggedIn` copy ("Authentication error" title, "try
+ * logging out and back in." detail) as it surfaces through SDK RunResults.
+ * Deliberately narrow: this gates a one-shot in-place retry, and matching
+ * broader error text would retry turns that a fresh transport cannot fix.
+ */
+export declare function isAuthErrorMessage(message: string | undefined): boolean;
+/**
+ * The SDK rejects a selection the credential's catalog does not list with
+ * this copy, thrown from `Agent.create` / `Agent.resume` before the turn
+ * streams anything. Matched on the message because the SDK uses its generic
+ * configuration error here.
+ */
+export declare function isUnavailableModelSelectionMessage(message: string | undefined): boolean;
+export declare function isUnavailableModelSelectionError(error: unknown): boolean;
+/**
+ * Inference / provider capacity on the selected model. `wait()` stores the
+ * connect status on `error.code` and strips `[code]` from the message, so
+ * both must be checked. `[unavailable]` in text is the connect status, not
+ * a loose "temporarily unavailable" substring.
+ */
+export declare function isModelCapacityError(message: string | undefined, code?: string | undefined): boolean;
+export declare function isModelCapacityErrorMessage(message: string | undefined): boolean;
+/** Catalog refusal or capacity: the authored fallback list can still save the turn. */
+export declare function shouldFallbackToNextModel(message: string | undefined, code?: string | undefined): boolean;
+export declare function shouldFallbackToNextModelOnError(error: unknown): boolean;
+export declare class CursorSdkRunner implements AgentRunner {
+    private readonly options;
+    private readonly agents;
+    private readonly activeRuns;
+    private readonly stores;
+    private readonly prewarmReleases;
+    constructor(options?: CursorSdkRunnerOptions);
+    runTurn(request: RunnerTurnRequest): Promise<TurnOutcome>;
+    /**
+     * One model attempt, plus the existing in-place transport retry (expired
+     * cloud stream, or a follow-up auth failure) on that same model. Model
+     * fallback is the caller's job: this returns the error outcome when a
+     * fresh handle cannot fix it.
+     */
+    private runTurnWithTransportRetry;
+    private logModelFallback;
+    private runTurnAttempt;
+    steer(request: {
+        sessionId: string;
+        text: string;
+    }): Promise<SteerAckOutcome>;
+    /**
+     * Build the local executor for a workspace before any session asks for it.
+     * The warmed executor is reference counted, so the lease is held until
+     * {@link dispose}; dropping it early would tear the workspace back down.
+     */
+    prewarm(request: RunnerPrewarmRequest): Promise<PrewarmOutcome>;
+    /**
+     * Drop the cached SDK agent for this session, if one is open.
+     *
+     * Hosted v2 parks and hibernates this process as soon as the execution
+     * reply lands on non-interactive channels. A leftover handle still holds
+     * the pre-freeze Connect/HTTP2 session; the next wake then reuses it and
+     * `AgentService/Run` never starts. Call after `waitForCompletion` so the
+     * hibernate snapshot has an empty cache. Slack's interactive hot-window
+     * still reuses handles because that path does not go through hosted
+     * delivery.
+     */
+    evictSession(sessionId: string): void;
+    dispose(): Promise<void>;
+    private getAgent;
+    /**
+     * Drop a cached handle and close it best-effort to release its transport
+     * and executor lease. Identity-checked so a turn that lost a race with a
+     * newer open cannot evict the replacement handle.
+     */
+    private evictAgent;
+    private log;
+    /**
+     * Re-resolve on every turn. Hosted freeze snapshots listen unsigned; the
+     * binder drops `CURSOR_API_KEY` / `CURSOR_API_KEY_FILE` at task time into
+     * the already-running process, which must not have closed over `undefined`.
+     */
+    private requireApiKey;
+    private buildSharedOptions;
+    /**
+     * The options that decide which local executor a turn runs on. Prewarming
+     * goes through here too, so a warmed workspace is the one turns land on.
+     */
+    private buildLocalOptions;
+    private openAgent;
+    private openLocalAgent;
+    private openCloudAgent;
+    private resolveStore;
+    /**
+     * Mirror the settled turn's conversation. Persist failures are logged and
+     * dropped — a durable-mirror outage must not fail a turn that already ran.
+     */
+    private persistConversation;
+    private getStore;
+}
+/** Cloud agent ids minted by the server are `bc-…`; those always resume. */
+export declare function isServerMintedCloudAgentId(id: string): boolean;
+/**
+ * `Agent.resume` on a store with no row for the agent ("Agent <id> not
+ * found", surfaced by every built-in {@link LocalAgentStore} backend).
+ * Deliberately narrow: transient store/transport failures must propagate
+ * rather than silently fork the thread onto a fresh conversation.
+ */
+export declare function isLocalAgentNotFoundError(error: unknown, agentId: string): boolean;
+export declare function toModelSelection(model: ModelSetting): ModelSelection;
+export declare function runErrorMessage(result: Pick<RunResult, "error">): string;
+//# sourceMappingURL=sdk-runner.d.ts.map

package/dist/internal/sdk-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-runner.d.ts","sourceRoot":"","sources":["../../src/internal/sdk-runner.ts"],"names":[],"mappings":"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"}