pi-cursor-sdk 0.1.55 → 0.1.57

package/src/cursor-cloud-options.ts

@@ -0,0 +1,206 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { AgentModeOption, AgentOptions, ModelSelection } from "@cursor/sdk";
+import { isCursorCloudEnvironmentType, type CursorResolvedSdkConfig } from "./cursor-config.js";
+
+export interface CursorCloudLocalState {
+	insideGitRepo: boolean;
+	dirty: boolean;
+	unpushed: boolean;
+}
+
+export interface CursorCloudPreflightIssue {
+	code:
+		| "cloud_ack_required"
+		| "context_handoff_required"
+		| "local_state_not_allowed"
+		| "env_forwarding_not_implemented"
+		| "cloud_environment_type_invalid"
+		| "cloud_environment_type_required"
+		| "cloud_environment_repo_conflict"
+		| "cloud_branch_repo_required"
+		| "cloud_repo_invalid";
+	message: string;
+}
+
+export interface CursorCloudPreflightResult {
+	ok: boolean;
+	issues: CursorCloudPreflightIssue[];
+}
+
+type GitRunner = (cwd: string, args: string[]) => string | undefined;
+
+const CLOUD_REPO_URL_MESSAGE = "Cursor cloud repository must be an HTTPS repository URL without embedded credentials, query parameters, or fragments.";
+
+export function parseCursorCloudRepositoryUrl(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed) return undefined;
+	try {
+		const url = new URL(trimmed);
+		if (
+			url.protocol !== "https:" ||
+			url.username !== "" ||
+			url.password !== "" ||
+			url.search !== "" ||
+			url.hash !== "" ||
+			url.pathname === "/"
+		) return undefined;
+		return trimmed;
+	} catch {
+		return undefined;
+	}
+}
+
+function git(cwd: string, args: string[]): string | undefined {
+	try {
+		return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+	} catch {
+		return undefined;
+	}
+}
+
+function hasGitMetadata(cwd: string): boolean {
+	let current = cwd;
+	while (true) {
+		if (existsSync(join(current, ".git"))) return true;
+		const parent = dirname(current);
+		if (parent === current) return false;
+		current = parent;
+	}
+}
+
+export function inspectCursorCloudLocalState(cwd: string, runGit: GitRunner = git): CursorCloudLocalState {
+	const insideGitRepo = runGit(cwd, ["rev-parse", "--is-inside-work-tree"]);
+	if (insideGitRepo !== "true") {
+		return hasGitMetadata(cwd)
+			? { insideGitRepo: true, dirty: true, unpushed: true }
+			: { insideGitRepo: false, dirty: false, unpushed: false };
+	}
+	const status = runGit(cwd, ["status", "--porcelain=v1"]);
+	const dirty = status === undefined || status.length > 0;
+	const hasHead = runGit(cwd, ["rev-parse", "--verify", "HEAD"]) !== undefined;
+	const upstream = runGit(cwd, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+	const ahead = upstream ? runGit(cwd, ["rev-list", "--count", "@{upstream}..HEAD"]) : undefined;
+	const aheadCount = ahead === undefined ? Number.NaN : Number(ahead);
+	const unpushed = hasHead && (!upstream || !Number.isFinite(aheadCount) || aheadCount > 0);
+	return { insideGitRepo: true, dirty, unpushed };
+}
+
+export function buildCursorCloudAgentOptions(options: {
+	apiKey: string;
+	modelSelection: ModelSelection;
+	agentMode: AgentModeOption;
+	resolvedConfig: CursorResolvedSdkConfig;
+	name?: string;
+}): AgentOptions {
+	const { resolvedConfig } = options;
+	const environment = resolvedConfig.cloud.environment.value;
+	const environmentType = environment?.type;
+	const environmentName = environment?.name;
+	const configuredRepo = resolvedConfig.cloud.repo.value;
+	const repo = parseCursorCloudRepositoryUrl(configuredRepo);
+	if (configuredRepo && !repo) throw new Error(CLOUD_REPO_URL_MESSAGE);
+	const cloud = {
+		...(isCursorCloudEnvironmentType(environmentType)
+			? {
+					env: {
+						type: environmentType,
+						...(environmentName ? { name: environmentName } : {}),
+					},
+				}
+			: {}),
+		...(repo
+			? {
+					repos: [
+						{
+							url: repo,
+							...(resolvedConfig.cloud.branch.value ? { startingRef: resolvedConfig.cloud.branch.value } : {}),
+						},
+					],
+				}
+			: {}),
+		...(resolvedConfig.cloud.directPush.value ? { workOnCurrentBranch: true } : {}),
+	};
+	return {
+		apiKey: options.apiKey,
+		model: options.modelSelection,
+		mode: options.agentMode,
+		...(options.name ? { name: options.name } : {}),
+		cloud,
+	};
+}
+
+export function preflightCursorCloudRuntime(options: {
+	resolvedConfig: CursorResolvedSdkConfig;
+	localState?: CursorCloudLocalState;
+	hasPriorContext?: boolean;
+}): CursorCloudPreflightResult {
+	const { resolvedConfig } = options;
+	const issues: CursorCloudPreflightIssue[] = [];
+	if (!resolvedConfig.cloud.acknowledged.value) {
+		issues.push({
+			code: "cloud_ack_required",
+			message: "Cursor cloud runtime requires first-use acknowledgement; run /cursor-runtime cloud in an interactive session or pass --cursor-cloud-ack / PI_CURSOR_CLOUD_ACK=1.",
+		});
+	}
+	if (options.hasPriorContext && resolvedConfig.cloud.contextHandoff.value === "never") {
+		issues.push({
+			code: "context_handoff_required",
+			message: "Cursor cloud runtime needs --cursor-cloud-context=fresh or --cursor-cloud-context=bootstrap for sessions with prior pi context.",
+		});
+	}
+	if (
+		options.localState?.insideGitRepo &&
+		(options.localState.dirty || options.localState.unpushed) &&
+		!resolvedConfig.cloud.allowLocalState.value
+	) {
+		issues.push({
+			code: "local_state_not_allowed",
+			message: "Cursor cloud runtime cannot see dirty or unpushed local state; pass --cursor-cloud-allow-local-state only after accepting that risk.",
+		});
+	}
+	if (resolvedConfig.cloud.envNames.value.length > 0 || resolvedConfig.cloud.envFromFiles.value) {
+		issues.push({
+			code: "env_forwarding_not_implemented",
+			message: "Cursor cloud env forwarding is not implemented; use Cursor-native environment setup such as .cursor/environment.json or dashboard-managed secrets.",
+		});
+	}
+	if (resolvedConfig.cloud.repo.value && !parseCursorCloudRepositoryUrl(resolvedConfig.cloud.repo.value)) {
+		issues.push({
+			code: "cloud_repo_invalid",
+			message: CLOUD_REPO_URL_MESSAGE,
+		});
+	}
+	if (resolvedConfig.cloud.branch.value && !resolvedConfig.cloud.repo.value) {
+		issues.push({
+			code: "cloud_branch_repo_required",
+			message: "Cursor cloud branch/ref requires --cursor-cloud-repo because the installed Cursor SDK supports startingRef only on cloud.repos entries.",
+		});
+	}
+	const environment = resolvedConfig.cloud.environment.value;
+	if (environment?.type && !isCursorCloudEnvironmentType(environment.type)) {
+		issues.push({
+			code: "cloud_environment_type_invalid",
+			message: `Invalid Cursor cloud environment type "${environment.type}"; expected cloud, pool, or machine.`,
+		});
+	}
+	if (environment?.name && !environment.type) {
+		issues.push({
+			code: "cloud_environment_type_required",
+			message: "Cursor cloud environment name requires --cursor-cloud-env-type=cloud|pool|machine or PI_CURSOR_CLOUD_ENV_TYPE.",
+		});
+	}
+	if (environment?.type === "cloud" && environment.name && resolvedConfig.cloud.repo.value) {
+		issues.push({
+			code: "cloud_environment_repo_conflict",
+			message: "Cursor cloud named environments cannot be combined with --cursor-cloud-repo; omit the repo or use a pool/machine environment.",
+		});
+	}
+	return { ok: issues.length === 0, issues };
+}
+
+export function formatCursorCloudPreflightError(result: CursorCloudPreflightResult): string {
+	const details = result.issues.map((issue) => `- ${issue.message}`).join("\n");
+	return `Cursor cloud runtime is not ready to start.\n${details}\nUse --cursor-runtime local or /cursor-runtime local to run with the local Cursor SDK agent.`;
+}

package/src/cursor-cloud-reporting.ts

@@ -0,0 +1,246 @@
+import type { Run, RunResult, SDKAgent, SDKArtifact, TokenUsage } from "@cursor/sdk";
+import { truncateCursorDisplayLine } from "./cursor-display-text.js";
+import { scrubSensitiveText } from "./cursor-sensitive-text.js";
+import { asRecord, getArray, getNumber, getRecord, getString } from "./cursor-record-utils.js";
+
+const DEFAULT_CURSOR_CLOUD_API_BASE_URL = "https://api.cursor.com";
+const CLOUD_REPORT_TIMEOUT_MS = 5000;
+const MAX_CLOUD_ID_DISPLAY_LENGTH = 160;
+const MAX_CLOUD_REPO_DISPLAY_LENGTH = 240;
+const MAX_CLOUD_BRANCH_DISPLAY_LENGTH = 160;
+const MAX_CLOUD_ARTIFACT_DISPLAY_LENGTH = 240;
+export const MAX_CLOUD_REPORT_BRANCHES = 5;
+export const MAX_CLOUD_REPORT_ARTIFACTS = 10;
+
+export interface CursorCloudUsageReport {
+	totalUsage?: TokenUsage;
+	runUsage?: TokenUsage;
+}
+
+export interface CursorCloudRunBranch {
+	repoUrl: string;
+	branch?: string;
+	prUrl?: string;
+}
+
+export interface CursorCloudRunReport {
+	agentId: string;
+	runId: string;
+	branches: CursorCloudRunBranch[];
+	artifacts?: SDKArtifact[];
+	usage?: CursorCloudUsageReport;
+}
+
+export interface FetchCursorCloudRawUsageOptions {
+	agentId: string;
+	runId?: string;
+	apiKey: string | undefined;
+	baseUrl?: string;
+	fetchImpl?: typeof fetch;
+	timeoutMs?: number;
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs = CLOUD_REPORT_TIMEOUT_MS): Promise<T | undefined> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<undefined>((resolve) => {
+		timer = setTimeout(() => resolve(undefined), timeoutMs);
+		timer.unref?.();
+	});
+	return Promise.race([promise.catch(() => undefined), timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
+function fetchJsonWithAbortTimeout(
+	fetchImpl: typeof fetch,
+	url: URL,
+	init: RequestInit,
+	timeoutMs = CLOUD_REPORT_TIMEOUT_MS,
+): Promise<unknown> {
+	const controller = new AbortController();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const request = (async () => {
+		const response = await fetchImpl(url, { ...init, signal: controller.signal });
+		if (!response.ok) return undefined;
+		return response.json();
+	})().catch(() => undefined);
+	const timeout = new Promise<undefined>((resolve) => {
+		timer = setTimeout(() => {
+			controller.abort();
+			resolve(undefined);
+		}, timeoutMs);
+		timer.unref?.();
+	});
+	return Promise.race([request, timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
+function readNonnegativeNumber(record: Record<string, unknown> | undefined, key: string): number | undefined {
+	const value = getNumber(record, key);
+	return value !== undefined && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function readTokenUsage(value: unknown): TokenUsage | undefined {
+	const record = asRecord(value);
+	const inputTokens = readNonnegativeNumber(record, "inputTokens");
+	const outputTokens = readNonnegativeNumber(record, "outputTokens");
+	const cacheReadTokens = readNonnegativeNumber(record, "cacheReadTokens");
+	const cacheWriteTokens = readNonnegativeNumber(record, "cacheWriteTokens");
+	const totalTokens = readNonnegativeNumber(record, "totalTokens");
+	if (
+		inputTokens === undefined ||
+		outputTokens === undefined ||
+		cacheReadTokens === undefined ||
+		cacheWriteTokens === undefined ||
+		totalTokens === undefined
+	) return undefined;
+	const reasoningTokens = readNonnegativeNumber(record, "reasoningTokens");
+	return {
+		inputTokens,
+		outputTokens,
+		cacheReadTokens,
+		cacheWriteTokens,
+		totalTokens,
+		...(reasoningTokens === undefined ? {} : { reasoningTokens }),
+	};
+}
+
+function readNonemptyString(record: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = getString(record, key);
+	return value && truncateCursorDisplayLine(value) ? value : undefined;
+}
+
+function normalizeBranches(value: unknown): CursorCloudRunBranch[] {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((item) => {
+		const record = asRecord(item);
+		const repoUrl = readNonemptyString(record, "repoUrl");
+		if (!repoUrl) return [];
+		const branch = readNonemptyString(record, "branch");
+		const prUrl = readNonemptyString(record, "prUrl");
+		return branch || prUrl ? [{ repoUrl, ...(branch ? { branch } : {}), ...(prUrl ? { prUrl } : {}) }] : [];
+	});
+}
+
+function normalizeArtifacts(value: unknown): SDKArtifact[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) return undefined;
+	return value.flatMap((item) => {
+		const record = asRecord(item);
+		const path = readNonemptyString(record, "path");
+		const sizeBytes = readNonnegativeNumber(record, "sizeBytes");
+		const updatedAt = readNonemptyString(record, "updatedAt");
+		return path && sizeBytes !== undefined && updatedAt ? [{ path, sizeBytes, updatedAt }] : [];
+	});
+}
+
+function normalizeUsage(value: unknown): CursorCloudUsageReport | undefined {
+	const record = asRecord(value);
+	const totalUsage = readTokenUsage(getRecord(record, "totalUsage"));
+	const runUsage = readTokenUsage(getRecord(record, "runUsage"));
+	return totalUsage || runUsage ? { ...(totalUsage ? { totalUsage } : {}), ...(runUsage ? { runUsage } : {}) } : undefined;
+}
+
+export async function fetchCursorCloudRawUsage(
+	options: FetchCursorCloudRawUsageOptions,
+): Promise<CursorCloudUsageReport | undefined> {
+	if (!options.apiKey || typeof options.fetchImpl !== "function" && typeof fetch !== "function") return undefined;
+	try {
+		const baseUrl = options.baseUrl ?? DEFAULT_CURSOR_CLOUD_API_BASE_URL;
+		const url = new URL(`/v1/agents/${encodeURIComponent(options.agentId)}/usage`, baseUrl);
+		if (options.runId) url.searchParams.set("runId", options.runId);
+		const fetchImpl = options.fetchImpl ?? fetch;
+		const body = asRecord(await fetchJsonWithAbortTimeout(fetchImpl, url, {
+			headers: {
+				Authorization: `Bearer ${options.apiKey}`,
+				"x-cursor-client-type": "sdk",
+			},
+		}, options.timeoutMs));
+		const runs = getArray(body, "runs") ?? [];
+		const matchingRun = options.runId
+			? runs.map(asRecord).find((run) => getString(run, "id") === options.runId)
+			: undefined;
+		return normalizeUsage({
+			totalUsage: getRecord(body, "totalUsage"),
+			runUsage: getRecord(matchingRun, "usage"),
+		});
+	} catch {
+		return undefined;
+	}
+}
+
+export async function collectCursorCloudRunReport(options: {
+	agent: SDKAgent;
+	run: Run;
+	waitResult: RunResult;
+	apiKey: string | undefined;
+}): Promise<CursorCloudRunReport> {
+	const listArtifacts = options.agent.listArtifacts;
+	const [artifactResult, usage] = await Promise.all([
+		typeof listArtifacts === "function" ? withTimeout(listArtifacts.call(options.agent)) : undefined,
+		fetchCursorCloudRawUsage({ agentId: options.run.agentId, runId: options.run.id, apiKey: options.apiKey }),
+	]);
+	const waitBranches = getArray(getRecord(asRecord(options.waitResult), "git"), "branches");
+	const runBranches = getArray(getRecord(asRecord(options.run), "git"), "branches");
+	return {
+		agentId: options.run.agentId,
+		runId: options.run.id,
+		branches: normalizeBranches(waitBranches ?? runBranches),
+		artifacts: normalizeArtifacts(artifactResult),
+		usage: normalizeUsage(usage),
+	};
+}
+
+function formatTokenUsage(usage: TokenUsage): string {
+	const parts = [
+		`input ${usage.inputTokens.toLocaleString("en-US")}`,
+		`output ${usage.outputTokens.toLocaleString("en-US")}`,
+		`cache read ${usage.cacheReadTokens.toLocaleString("en-US")}`,
+		`cache write ${usage.cacheWriteTokens.toLocaleString("en-US")}`,
+		`total ${usage.totalTokens.toLocaleString("en-US")}`,
+	];
+	if (usage.reasoningTokens !== undefined) parts.splice(2, 0, `reasoning ${usage.reasoningTokens.toLocaleString("en-US")}`);
+	return parts.join(", ");
+}
+
+function remoteDisplayString(value: unknown, maxLength: number, apiKey: string | undefined): string {
+	return typeof value === "string" ? truncateCursorDisplayLine(scrubSensitiveText(value, apiKey), maxLength) : "";
+}
+
+function formatBranchLine(branch: CursorCloudRunBranch, apiKey: string | undefined): string[] {
+	const lines: string[] = [];
+	const branchName = remoteDisplayString(branch.branch, MAX_CLOUD_BRANCH_DISPLAY_LENGTH, apiKey);
+	const repoUrl = remoteDisplayString(branch.repoUrl, MAX_CLOUD_REPO_DISPLAY_LENGTH, apiKey);
+	const prUrl = remoteDisplayString(branch.prUrl, MAX_CLOUD_REPO_DISPLAY_LENGTH, apiKey);
+	if (branchName) lines.push(`- branch: ${branchName}${repoUrl ? ` (${repoUrl})` : ""}`);
+	if (prUrl) lines.push(`- PR: ${prUrl}`);
+	return lines;
+}
+
+export function formatCursorCloudRunReport(report: CursorCloudRunReport, options: { apiKey?: string } = {}): string {
+	const agentId = remoteDisplayString(report.agentId, MAX_CLOUD_ID_DISPLAY_LENGTH, options.apiKey) || "unknown";
+	const runId = remoteDisplayString(report.runId, MAX_CLOUD_ID_DISPLAY_LENGTH, options.apiKey) || "unknown";
+	const branches = normalizeBranches(report.branches);
+	const artifacts = normalizeArtifacts(report.artifacts);
+	const lines = ["Cursor cloud run:", `- agent: ${agentId}`, `- run: ${runId}`];
+	for (const branch of branches.slice(0, MAX_CLOUD_REPORT_BRANCHES)) lines.push(...formatBranchLine(branch, options.apiKey));
+	if (branches.length > MAX_CLOUD_REPORT_BRANCHES) lines.push(`- branches: +${branches.length - MAX_CLOUD_REPORT_BRANCHES} more`);
+	if (artifacts) {
+		if (artifacts.length === 0) {
+			lines.push("- artifacts: none");
+		} else {
+			lines.push("- artifacts:");
+			for (const artifact of artifacts.slice(0, MAX_CLOUD_REPORT_ARTIFACTS)) {
+				const path = remoteDisplayString(artifact.path, MAX_CLOUD_ARTIFACT_DISPLAY_LENGTH, options.apiKey);
+				const updatedAt = remoteDisplayString(artifact.updatedAt, MAX_CLOUD_ARTIFACT_DISPLAY_LENGTH, options.apiKey);
+				lines.push(`  - ${path} (${artifact.sizeBytes.toLocaleString("en-US")} bytes, updated ${updatedAt})`);
+			}
+			if (artifacts.length > MAX_CLOUD_REPORT_ARTIFACTS) lines.push(`  - +${artifacts.length - MAX_CLOUD_REPORT_ARTIFACTS} more`);
+		}
+	}
+	const normalizedUsage = normalizeUsage(report.usage);
+	const usage = normalizedUsage?.runUsage ?? normalizedUsage?.totalUsage;
+	if (usage) lines.push(`- raw usage (display only): ${formatTokenUsage(usage)}`);
+	return scrubSensitiveText(`${lines.join("\n")}\n`, options.apiKey);
+}