@bastani/atomic 0.8.31-alpha.4 → 0.9.0-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [0.9.0-alpha.1] - 2026-06-20
+
 ### Added
 
 - Added configurable context-window support for models that declare `contextWindowOptions`, including explicit `--context-window` CLI/settings control, a GitHub Copilot CLI-style `/model`-flow picker (numbered `Default`/`Long context` tiers with token counts), session replay, SDK/runtime/RPC APIs, and docs while preserving each model's scalar default context window. For GitHub Copilot, context windows are measured in **input (prompt) tokens** (consistent with every other provider) and derived **dynamically from GitHub's live CAPI model catalog** (`GET /models`) instead of a hardcoded model list: Atomic resolves each model's input budget as `max_prompt_tokens || max_context_window_tokens || 128_000` and, for tiered models, exposes a selectable default window (`token_prices.default.context_max`) plus a long window set to the model's full `max_context_window_tokens` (retaining `max_prompt_tokens` as the internal effective compaction/overflow budget) — gated on the user actually having the GitHub Copilot provider and cached on disk for 30 minutes (for example `github-copilot/gpt-5.5` exposes `272k` default / `1.05m` long, and the Claude/Gemini long-context models `200k` default / `1m` long). Atomic raises the local budget and sends `X-GitHub-Api-Version: 2026-06-01`, while GitHub applies the long-context billing tier server-side by prompt token count. Long-context Copilot requests consume more AI credits and require Copilot long-context/usage-based billing entitlement; offline, unauthenticated, or non-Copilot sessions leave the built-in window untouched and show no picker; custom providers and explicit model overrides can still expose their own selectable windows ([#1409](https://github.com/bastani-inc/atomic/issues/1409)).
@@ -19,10 +21,12 @@
 - Bumped the bundled upstream pi runtime libraries `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui` from `^0.79.6` to `^0.79.7` so Atomic inherits upstream v0.79.7 TUI color-scheme, Warp image, generated model catalog, and agent-core fixes.
 - Reserved `/` in theme names for automatic light/dark theme settings.
 - Replaced the bundled `browser` skill / `browse` CLI with the `playwright-cli` skill and `playwright-cli` command across `@bastani/atomic`, and bundled the new `effective-liteparse` document-extraction skill. The builtin `ralph`, `goal`, and `open-claude-design` workflows and the `debugger`/`codebase-online-researcher` subagents now drive browsers via `playwright-cli`; `open-claude-design`'s deterministic setup step ensures `playwright-cli` (`npm install -g @playwright/cli@latest`) and renames its `browse_cli_status` output to `playwright_cli_status`; and `ralph` now records a `playwright-cli` QA end-to-end proof video (`qa_video_path`) for UI-applicable/full-stack changes, references it in the implementation notes, and attaches or links it to the final pull request when `create_pr=true`. Updated the user-facing docs (workflows, SDK bash-policy examples, quickstart skills, README) to match.
-
+- Changed contributor validation to include a monorepo-wide file-length gate in Bun scripts, local `prek` hooks, and PR CI, covering tracked TS/JS/Rust files with the documented generated/vendored exclusions and no grandfathered baseline allowlist ([#1445](https://github.com/bastani-inc/atomic/issues/1445)).
+- Switched the repository to a **versionless `main`** release model (modeled on openai/codex): every `packages/*/package.json` on `main` now stays at the `0.0.0` placeholder, and the real version is materialized only on a throwaway, off-`main` `Release <version>` commit created and tagged by the new top-level `scripts/cut-release.ts` (which stamps the version inside a detached git worktree via `scripts/bump-version.ts` and pushes only the tag — `main` is never bumped). This lets a stable release and an ahead-of-stable prerelease line be cut from the same trunk without release branches, mirroring how the npm `@latest`/`@next` dist-tags are derived from the tag shape. `publish.yml` still builds and publishes from the tagged (real-version) commit and now additionally refuses to publish the `0.0.0` placeholder, and the `publish-release` Atomic workflow now lands a CHANGELOG-only release-notes PR on `main` and then stamps/tags the release off-`main` via `cut-release.ts` instead of merging a version bump into `main`, accepts an optional `base_ref` input (default `main`) so a release can be cut from a maintenance/integration branch, and accepts an optional `from_ref` input that cuts an ephemeral release from any commit/tag/branch (auto-creating a CI-gated `release/<version>`/`prerelease/<version>` branch, cutting the tag off it, then deleting it — the changelog lives on the tag only). CI `test.yml` now also runs on `release/**`/`prerelease/**` pushes so those ephemeral branches are gated. End users installing from npm are unaffected; only local/`main` dev builds report `0.0.0` for `--version`.
 
 ### Fixed
 
+- Exposed `SessionManager.usesDefaultSessionDir()` through the read-only extension session-manager surface so bundled extensions can distinguish default global session storage from non-default `--session-dir`, `ATOMIC_CODING_AGENT_SESSION_DIR`, or settings-backed session directories without path guessing ([#1444](https://github.com/bastani-inc/atomic/issues/1444)).
 - Fixed `github-copilot/*` Gemini models (for example `github-copilot/gemini-3.1-pro-preview` and `github-copilot/gemini-3.5-flash`) failing **every** chat turn with `Error: 400 invalid request body`. These models are served through GitHub's Copilot API (CAPI), which translates the OpenAI chat-completions request into a Google GenAI `GenerateContent` request and forwards tool/function JSON Schema `anyOf`/`oneOf` verbatim into Gemini's `FunctionDeclaration` schema. Gemini rejects a union whose branch is a complex **object** schema, so Google returned HTTP 400 and CAPI relabelled it `{"error":{"code":"invalid_request_body"}}`. Because Atomic's bundled `workflow` tool — and any tool using the TypeBox `Type.Union([Type.Object(...), Type.String()])` pattern for fields such as `task`, `chain`, and `parallel` — is present in normal chat turns, the request failed before the model ever ran (it was previously masked only when a fallback model existed). Atomic now sanitizes outbound tool JSON Schemas for GitHub Copilot Gemini models into the subset CAPI/Gemini honors: it resolves object/array-bearing `anyOf`/`oneOf` to their most expressive branch, converts `const`/literal unions to `enum`, collapses nullable unions to `nullable`, prunes `required` to existing properties, and drops non-portable keywords (`additionalProperties`, `patternProperties`, `$schema`, `format`, `pattern`, numeric/length bounds, `default`, `title`, etc.). The transform is gated to `github-copilot` Gemini `openai-completions` models and runs last in the provider-payload pipeline (so it also covers extension/SDK-injected tools), leaving every other provider/model payload unchanged.
 - Fixed `github-copilot/*` Gemini models getting stuck in an infinite tool-call retry loop (most visibly on the workflow `structured_output` tool). Capturing the raw CAPI stream confirmed that Gemini serializes array/object function-call arguments as **flattened indexed keys** on the wire — for example `{ keywords: ["a", "b"] }` arrives as `{ "keywords[0]": "a", "keywords[1]": "b" }` — so schema validation failed (`keywords: must have required properties keywords` and `root: must not have additional properties`) and the model re-emitted the same shape forever. Atomic now reconstructs flattened tool-call arguments (`name[i]`, `name[i].sub`, `parent.child`) back into proper arrays/objects in each tool's `prepareArguments` step, before validation runs. Gated to GitHub Copilot Gemini models at call time and a no-op for well-formed arguments, so it covers built-in, extension, SDK, and MCP tools without affecting any other provider/model.
 - Fixed `github-copilot/*` Gemini models (for example `github-copilot/gemini-3.1-pro-preview`) silently dying mid-task instead of continuing the turn. Inspecting the affected sessions and confirming against GitHub's Copilot API (CAPI) source showed two distinct degenerate stream endings that Atomic was not recovering from: (1) CAPI's `getAzureFinishReason` maps several Gemini finish reasons — `MALFORMED_FUNCTION_CALL`, `OTHER`, `LANGUAGE`, and `UNEXPECTED_TOOL_CALL` — to a bare OpenAI `finish_reason: "error"`, which `pi-ai` surfaces as `"Provider finish_reason: error"`; the auto-retry classifier's regex did not match it, so the turn ended with an empty assistant message and no retry; and (2) Gemini intermittently ends the stream with `finish_reason: "stop"`, an **empty content array**, and **0 output tokens**, which Atomic treated as a successful (if empty) turn and stopped. Atomic now treats bare `finish_reason: error`/`content_filter` as retryable and detects degenerate empty completions (no text/tool-call/thinking content **and** zero output tokens on a `stop`/`toolUse` turn) as retryable, re-issuing the request with the existing exponential-backoff path. Empty `stop` completions also no longer reset the auto-retry counter, so repeated empties stay bounded by `maxRetries` instead of retrying forever.
@@ -36,6 +40,7 @@
 - Fixed `/model` autocomplete and model-selection searches to match provider/model queries regardless of whether the provider or model token is typed first.
 - Fixed the tree navigator to horizontally pan deep entries so the selected item remains readable.
 - Fixed long-context selection for GitHub Copilot's rounded 1M model names: requesting `1m` now selects the advertised full context window when the catalog exposes it, and otherwise resolves to the largest advertised long-context window at or below the request (for example `936k` for sparse catalog payloads) instead of falling back to the short `200k` tier. Interactive/context-picker persistence now writes the effective selected budget to per-model `defaultContextWindows["provider/modelId"]` settings instead of the global `defaultContextWindow` fallback, so Copilot-specific prompt caps such as `936k`/`922k` do not leak into Anthropic, Cursor, or other providers on restart. Legacy/stale global `defaultContextWindow` values from earlier builds are now treated as optional fallbacks and ignored without warning when unsupported by the active model.
+- Suppressed the stale-update nag on versionless dev/source-tree builds. Because `main` (and direct runs like `bun packages/coding-agent/src/cli.ts`) reads the `0.0.0` placeholder from `package.json`, the startup version check always saw `0.0.0` as older than every published release and popped an "update available" banner on every dev run. The automatic startup check now treats `0.0.0` as a dev build and skips both the comparison and the npm registry call; the explicit `atomic update` command is unchanged.
 - Fixed a GitHub Copilot context-window warning on restart: after selecting a long-context window (e.g. `claude-opus-4.8` → `936k`) and reopening Atomic, startup validated the persisted selection before the (async, auth-gated) Copilot catalog loaded, so the model still looked limited to its default window and Atomic warned “Context window 936k is not supported… Supported values: 200k” and reset the choice. The model registry now seeds the Copilot context-window catalog synchronously from its on-disk cache at construction (ignoring the refresh TTL, gated on a `github-copilot` credential), so a returning user's selection is recognized immediately while the live refresh still runs in the background ([#1409](https://github.com/bastani-inc/atomic/issues/1409)).
 - Fixed context-window startup, session-switch, settings, and RPC edge cases: unknown provider fallback models no longer inherit selectable context-window options from provider defaults, fatal startup diagnostics no longer persist context-window settings, `AgentSession.setModel()` preserves an incoming target model's explicit selected context window, model-switch paths that change effective context windows now notify listeners via `context_window_changed`, the interactive context-window picker keys selection on raw token counts so colliding formatted labels never change which window is selected, RPC `set_model` returns the effective post-switch session model, and explicit startup `contextWindow` selections are journaled even when they equal the model scalar default ([#1409](https://github.com/bastani-inc/atomic/issues/1409)).
 - Fixed `AgentSession.setContextWindow()` so bare SDK/runtime calls update the active session, append `context_window_change`, and emit `context_window_changed` without persisting settings; callers must pass `{ persistDefault: true }` to update the active model's `defaultContextWindows["provider/modelId"]` setting ([#1409](https://github.com/bastani-inc/atomic/issues/1409)).

package/dist/builtin/cursor/CHANGELOG.md

@@ -2,9 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.0-alpha.1] - 2026-06-20
+
 ### Changed
 
-- Published a synchronized Atomic 0.8.31-alpha.3 prerelease; no functional Cursor provider changes were made after 0.8.30.
+- Published a synchronized Atomic 0.9.0-alpha.1 prerelease; no functional Cursor provider changes were made after 0.8.30.
+- Changed contributor validation to include the monorepo-wide file-length gate for tracked TS/JS/Rust files in local `prek` hooks and PR CI, with only documented generated/vendored exclusions and no grandfathered baseline allowlist ([#1445](https://github.com/bastani-inc/atomic/issues/1445)).
 
 ## [0.8.30] - 2026-06-17
 

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.8.31-alpha.4",
+  "version": "0.9.0-alpha.1",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.8.31-alpha.4",
+    "@bastani/atomic-natives": "0.9.0-alpha.1",
     "@bufbuild/protobuf": "^2.0.0"
   }
 }

package/dist/builtin/cursor/src/proto/protobuf-codec-json.ts

@@ -0,0 +1,44 @@
+import { fromBinary, fromJson, toBinary, toJson, type JsonValue as ProtobufJsonValue } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import { parseJsonValue, type JsonObject, type JsonValue } from "../config.js";
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export function encodeProtobufValue(value: JsonValue): Uint8Array {
+	return toBinary(ValueSchema, fromJson(ValueSchema, value as ProtobufJsonValue));
+}
+
+function encodeMcpArgValue(value: JsonValue): Uint8Array {
+	try {
+		return encodeProtobufValue(value);
+	} catch {
+		return textEncoder.encode(String(value));
+	}
+}
+
+export function encodeMcpArgsMap(args: JsonObject): Record<string, Uint8Array> {
+	const encoded: Record<string, Uint8Array> = {};
+	for (const [key, value] of Object.entries(args)) encoded[key] = encodeMcpArgValue(value);
+	return encoded;
+}
+
+function decodeMcpArgValue(value: Uint8Array): JsonValue {
+	try {
+		const decoded = toJson(ValueSchema, fromBinary(ValueSchema, value)) as ProtobufJsonValue;
+		return parseJsonValue(JSON.stringify(decoded)) ?? null;
+	} catch {
+		return textDecoder.decode(value);
+	}
+}
+
+export function decodeMcpArgsMap(args: Record<string, Uint8Array>): JsonObject {
+	const decoded: JsonObject = {};
+	for (const [key, value] of Object.entries(args)) decoded[key] = decodeMcpArgValue(value);
+	return decoded;
+}
+
+export function serializableJsonValue(value: object): JsonValue {
+	return parseJsonValue(JSON.stringify(value)) ?? {};
+}
+

package/dist/builtin/cursor/src/proto/protobuf-codec-request.ts

@@ -0,0 +1,271 @@
+import { createHash, randomUUID } from "node:crypto";
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { parseJsonObject, type JsonObject } from "../config.js";
+import type { CursorRunRequest } from "../transport.js";
+import {
+	AgentClientMessageSchema,
+	AgentConversationTurnStructureSchema,
+	AgentRunRequestSchema,
+	AssistantMessageSchema,
+	ConversationActionSchema,
+	ConversationStateStructureSchema,
+	ConversationStepSchema,
+	ConversationTurnStructureSchema,
+	McpArgsSchema,
+	McpToolCallSchema,
+	McpToolDefinitionSchema,
+	ModelDetailsSchema,
+	SelectedContextSchema,
+	ToolCallSchema,
+	UserMessageActionSchema,
+	UserMessageSchema,
+	type ConversationStateStructure,
+	type McpToolDefinition,
+	type UserMessage,
+} from "./agent_pb.js";
+import { encodeMcpArgsMap, encodeProtobufValue, serializableJsonValue } from "./protobuf-codec-json.js";
+import { createMcpToolCallResult } from "./protobuf-codec-wire.js";
+
+export interface ParsedAssistantTextStep {
+	readonly kind: "assistantText";
+	readonly text: string;
+}
+
+export interface ParsedToolCallStep {
+	readonly kind: "toolCall";
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly arguments: JsonObject;
+	result?: { readonly content: string; readonly isError: boolean };
+}
+
+export type ParsedTurnStep = ParsedAssistantTextStep | ParsedToolCallStep;
+
+export interface ParsedTurn {
+	readonly userText: string;
+	readonly steps: ParsedTurnStep[];
+}
+
+const CURSOR_PROTO_CLIENT_NAME = "pi";
+const textEncoder = new TextEncoder();
+export function buildMcpToolDefinitions(request: CursorRunRequest): readonly McpToolDefinition[] {
+	return (request.context.tools ?? []).map((tool) => {
+		const jsonSchema = serializableJsonValue(tool.parameters);
+		return create(McpToolDefinitionSchema, {
+			name: tool.name,
+			description: tool.description,
+			providerIdentifier: CURSOR_PROTO_CLIENT_NAME,
+			toolName: tool.name,
+			inputSchema: encodeProtobufValue(jsonSchema),
+		});
+	});
+}
+
+export function buildCursorRequest(
+	modelId: string,
+	systemPrompt: string,
+	userText: string,
+	turns: readonly ParsedTurn[],
+	conversationId: string,
+	checkpoint: Uint8Array | null,
+	existingBlobStore?: Map<string, Uint8Array>,
+): { readonly requestBytes: Uint8Array; readonly blobStore: Map<string, Uint8Array> } {
+	const blobStore = new Map<string, Uint8Array>(existingBlobStore ?? []);
+	const systemBlobId = storeAsBlob(textEncoder.encode(JSON.stringify({ role: "system", content: systemPrompt })), blobStore);
+	const selectedContextBlob = storeAsBlob(buildSelectedContextBlob([systemBlobId], CURSOR_PROTO_CLIENT_NAME), blobStore);
+	const conversationState = checkpoint
+		? fromBinary(ConversationStateStructureSchema, checkpoint)
+		: buildConversationState(turns, blobStore, systemBlobId, selectedContextBlob);
+	const userMessage = createUserMessage(userText, selectedContextBlob);
+	const action = create(ConversationActionSchema, {
+		action: { case: "userMessageAction", value: create(UserMessageActionSchema, { userMessage }) },
+	});
+	const modelDetails = create(ModelDetailsSchema, { modelId, displayModelId: modelId, displayName: modelId });
+	const runRequest = create(AgentRunRequestSchema, { conversationState, action, modelDetails, conversationId });
+	const clientMessage = create(AgentClientMessageSchema, {
+		message: { case: "runRequest", value: runRequest },
+	});
+	return { requestBytes: toBinary(AgentClientMessageSchema, clientMessage), blobStore };
+}
+
+function buildConversationState(
+	turns: readonly ParsedTurn[],
+	blobStore: Map<string, Uint8Array>,
+	systemBlobId: Uint8Array,
+	selectedContextBlob: Uint8Array,
+): ConversationStateStructure {
+	const turnBlobIds: Uint8Array[] = [];
+	for (const turn of turns) {
+		const userMessage = createUserMessage(turn.userText, selectedContextBlob);
+		const userMessageBlobId = storeAsBlob(toBinary(UserMessageSchema, userMessage), blobStore);
+		const stepBlobIds = turn.steps.map((step) => storeAsBlob(buildTurnStepBytes(step), blobStore));
+		const agentTurn = create(AgentConversationTurnStructureSchema, {
+			userMessage: userMessageBlobId,
+			steps: stepBlobIds,
+			requestId: randomUUID(),
+		});
+		const turnStructure = create(ConversationTurnStructureSchema, {
+			turn: { case: "agentConversationTurn", value: agentTurn },
+		});
+		turnBlobIds.push(storeAsBlob(toBinary(ConversationTurnStructureSchema, turnStructure), blobStore));
+	}
+	return create(ConversationStateStructureSchema, {
+		rootPromptMessagesJson: [systemBlobId],
+		turns: turnBlobIds,
+		todos: [],
+		pendingToolCalls: [],
+		previousWorkspaceUris: [],
+		mode: 1,
+		fileStates: {},
+		fileStatesV2: {},
+		summaryArchives: [],
+		turnTimings: [],
+		subagentStates: {},
+		selfSummaryCount: 0,
+		readPaths: [],
+		clientName: CURSOR_PROTO_CLIENT_NAME,
+	});
+}
+
+function createUserMessage(text: string, selectedContextBlob: Uint8Array): UserMessage {
+	const messageId = randomUUID();
+	return create(UserMessageSchema, {
+		text,
+		messageId,
+		selectedContext: create(SelectedContextSchema, {}),
+		mode: 1,
+		selectedContextBlob,
+		correlationId: messageId,
+	});
+}
+
+function buildTurnStepBytes(step: ParsedTurnStep): Uint8Array {
+	if (step.kind === "assistantText") {
+		return toBinary(ConversationStepSchema, create(ConversationStepSchema, {
+			message: { case: "assistantMessage", value: create(AssistantMessageSchema, { text: step.text }) },
+		}));
+	}
+	const toolName = step.toolName || "tool";
+	const mcpToolCall = create(McpToolCallSchema, {
+		args: create(McpArgsSchema, {
+			name: toolName,
+			args: encodeMcpArgsMap(step.arguments),
+			toolCallId: step.toolCallId,
+			providerIdentifier: CURSOR_PROTO_CLIENT_NAME,
+			toolName,
+		}),
+		...(step.result ? { result: createMcpToolCallResult(step.result.content, step.result.isError) } : {}),
+	});
+	return toBinary(ConversationStepSchema, create(ConversationStepSchema, {
+		message: {
+			case: "toolCall",
+			value: create(ToolCallSchema, { tool: { case: "mcpToolCall", value: mcpToolCall } }),
+		},
+	}));
+}
+
+export function parseHistoricalTurns(messages: readonly CursorRunRequest["context"]["messages"][number][]): readonly ParsedTurn[] {
+	const turns: ParsedTurn[] = [];
+	let currentTurn: { userText: string; steps: ParsedTurnStep[]; toolCallById: Map<string, ParsedToolCallStep> } | undefined;
+	const ensureTurn = (): { userText: string; steps: ParsedTurnStep[]; toolCallById: Map<string, ParsedToolCallStep> } => {
+		currentTurn ??= { userText: "", steps: [], toolCallById: new Map() };
+		return currentTurn;
+	};
+	const flushTurn = (): void => {
+		if (!currentTurn) return;
+		if (currentTurn.userText || currentTurn.steps.length > 0) turns.push({ userText: currentTurn.userText, steps: currentTurn.steps });
+		currentTurn = undefined;
+	};
+	for (const message of messages) {
+		if (message.role === "user") {
+			flushTurn();
+			currentTurn = { userText: textFromMessage(message), steps: [], toolCallById: new Map() };
+		} else if (message.role === "assistant") {
+			const turn = ensureTurn();
+			for (const part of message.content) {
+				if (part.type === "text") appendAssistantTextStep(turn.steps, part.text);
+				else if (part.type === "thinking") appendAssistantTextStep(turn.steps, part.thinking);
+				else {
+					const step: ParsedToolCallStep = { kind: "toolCall", toolCallId: part.id, toolName: part.name, arguments: parseJsonObject(JSON.stringify(part.arguments)) ?? {} };
+					turn.steps.push(step);
+					turn.toolCallById.set(step.toolCallId, step);
+				}
+			}
+		} else {
+			const turn = ensureTurn();
+			let step = turn.toolCallById.get(message.toolCallId);
+			if (!step) {
+				step = { kind: "toolCall", toolCallId: message.toolCallId, toolName: message.toolName, arguments: {} };
+				turn.steps.push(step);
+				turn.toolCallById.set(step.toolCallId, step);
+			}
+			step.result = { content: rawToolResultText(message), isError: message.isError };
+		}
+	}
+	flushTurn();
+	return turns;
+}
+
+function appendAssistantTextStep(steps: ParsedTurnStep[], text: string): void {
+	if (!text) return;
+	const last = steps.at(-1);
+	if (last?.kind === "assistantText") {
+		steps[steps.length - 1] = { kind: "assistantText", text: `${last.text}${text}` };
+		return;
+	}
+	steps.push({ kind: "assistantText", text });
+}
+
+export function extractCurrentActionText(request: CursorRunRequest): string {
+	const last = request.context.messages.at(-1);
+	return last ? textFromMessage(last) : "";
+}
+
+function rawToolResultText(message: Extract<CursorRunRequest["context"]["messages"][number], { readonly role: "toolResult" }>): string {
+	return message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n");
+}
+
+function textFromMessage(message: CursorRunRequest["context"]["messages"][number]): string {
+	if (message.role === "user") {
+		if (typeof message.content === "string") return message.content;
+		return message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("\n");
+	}
+	if (message.role === "assistant") {
+		return message.content.map((part) => {
+			if (part.type === "text") return part.text;
+			if (part.type === "thinking") return part.thinking;
+			return `toolCall:${part.id}:${part.name}:${JSON.stringify(part.arguments)}`;
+		}).join("\n");
+	}
+	return rawToolResultText(message);
+}
+
+function buildSelectedContextBlob(rootPromptBlobIds: readonly Uint8Array[], clientName: string): Uint8Array {
+	const parts: Uint8Array[] = [];
+	for (const blobId of rootPromptBlobIds) {
+		parts.push(new Uint8Array([0x0a, blobId.length, ...blobId]));
+	}
+	const clientBytes = textEncoder.encode(clientName);
+	parts.push(new Uint8Array([0xb2, 0x01, clientBytes.length, ...clientBytes]));
+	return concatBytes(...parts);
+}
+
+function storeAsBlob(data: Uint8Array, blobStore: Map<string, Uint8Array>): Uint8Array {
+	const blobId = new Uint8Array(createHash("sha256").update(data).digest());
+	blobStore.set(blobKey(blobId), data);
+	return blobId;
+}
+
+export function blobKey(blobId: Uint8Array): string {
+	return Buffer.from(blobId).toString("hex");
+}
+
+function concatBytes(...parts: readonly Uint8Array[]): Uint8Array {
+	const output = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		output.set(part, offset);
+		offset += part.length;
+	}
+	return output;
+}

package/dist/builtin/cursor/src/proto/protobuf-codec-wire.ts

@@ -0,0 +1,231 @@
+import { randomUUID } from "node:crypto";
+import { create, toBinary } from "@bufbuild/protobuf";
+import type { CursorControlMessage, CursorProtocolMessage, CursorServerMessage } from "../transport.js";
+import {
+	AgentClientMessageSchema,
+	BackgroundShellSpawnResultSchema,
+	ConversationStateStructureSchema,
+	DeleteRejectedSchema,
+	DeleteResultSchema,
+	DiagnosticsResultSchema,
+	ExecClientMessageSchema,
+	FetchErrorSchema,
+	FetchResultSchema,
+	GrepErrorSchema,
+	GrepResultSchema,
+	KvClientMessageSchema,
+	LsRejectedSchema,
+	LsResultSchema,
+	McpErrorSchema,
+	McpResultSchema,
+	McpSuccessSchema,
+	McpTextContentSchema,
+	McpToolErrorSchema,
+	McpToolResultContentItemSchema,
+	McpToolResultSchema,
+	ReadRejectedSchema,
+	ReadResultSchema,
+	RequestContextResultSchema,
+	RequestContextSchema,
+	RequestContextSuccessSchema,
+	ShellRejectedSchema,
+	ShellResultSchema,
+	ShellStreamSchema,
+	WriteRejectedSchema,
+	WriteResultSchema,
+	WriteShellStdinErrorSchema,
+	WriteShellStdinResultSchema,
+	type AgentServerMessage,
+	type ExecServerMessage,
+	type KvServerMessage,
+	type McpToolDefinition,
+} from "./agent_pb.js";
+import { decodeMcpArgsMap } from "./protobuf-codec-json.js";
+
+const NATIVE_EXEC_REJECT_REASON = "Tool not available in this environment. Use the MCP tools provided instead.";
+
+const EXEC_CASE_FIELD_NUMBERS: ReadonlyMap<string, number> = new Map([
+	["shellArgs", 2],
+	["writeArgs", 3],
+	["deleteArgs", 4],
+	["grepArgs", 5],
+	["readArgs", 7],
+	["lsArgs", 8],
+	["diagnosticsArgs", 9],
+	["requestContextArgs", 10],
+	["mcpArgs", 11],
+	["shellStreamArgs", 14],
+	["backgroundShellSpawnArgs", 16],
+	["listMcpResourcesExecArgs", 17],
+	["readMcpResourceExecArgs", 18],
+	["fetchArgs", 20],
+	["recordScreenArgs", 21],
+	["computerUseArgs", 22],
+	["writeShellStdinArgs", 23],
+]);
+
+export function decodeAgentServerMessage(message: AgentServerMessage): readonly CursorProtocolMessage[] {
+	switch (message.message.case) {
+		case "interactionUpdate": {
+			const update = message.message.value;
+			if (update.message.case === "textDelta") return update.message.value.text ? [{ type: "textDelta", text: update.message.value.text }] : [];
+			if (update.message.case === "thinkingDelta") return update.message.value.text ? [{ type: "thinkingDelta", text: update.message.value.text }] : [];
+			if (update.message.case === "tokenDelta") return [{ type: "usage", kind: "outputDelta", outputTokens: update.message.value.tokens }];
+			return [];
+		}
+		case "conversationCheckpointUpdate": {
+			const checkpointState = message.message.value;
+			const checkpoint = toBinary(ConversationStateStructureSchema, checkpointState);
+			const messages: CursorProtocolMessage[] = [{ type: "conversationCheckpoint", checkpoint }];
+			if (checkpointState.tokenDetails) messages.push({ type: "usage", kind: "checkpoint", usedTokens: checkpointState.tokenDetails.usedTokens });
+			return messages;
+		}
+		case "kvServerMessage":
+			return decodeKvServerMessage(message.message.value);
+		case "execServerMessage":
+			return decodeExecServerMessage(message.message.value);
+		case "interactionQuery":
+			return [];
+		default:
+			return [];
+	}
+}
+
+function decodeKvServerMessage(kvMessage: KvServerMessage): readonly CursorControlMessage[] {
+	if (kvMessage.message.case === "getBlobArgs") return [{ type: "kvGetBlob", id: kvMessage.id, blobId: kvMessage.message.value.blobId }];
+	if (kvMessage.message.case === "setBlobArgs") {
+		return [{ type: "kvSetBlob", id: kvMessage.id, blobId: kvMessage.message.value.blobId, blobData: kvMessage.message.value.blobData }];
+	}
+	return [];
+}
+
+function decodeExecServerMessage(execMessage: ExecServerMessage): readonly CursorProtocolMessage[] {
+	const execCase = execMessage.message.case;
+	if (execCase === "requestContextArgs") {
+		return [{ type: "requestContext", ...(execMessage.execId ? { execId: execMessage.execId } : {}), execNumericId: execMessage.id }];
+	}
+	if (execCase === "mcpArgs") {
+		const mcpArgs = execMessage.message.value;
+		return [{
+			type: "toolCall",
+			id: mcpArgs.toolCallId || randomUUID(),
+			name: mcpArgs.toolName || mcpArgs.name || "cursor_tool",
+			argumentsJson: JSON.stringify(decodeMcpArgsMap(mcpArgs.args ?? {})),
+			...(execMessage.execId ? { execId: execMessage.execId } : {}),
+			execNumericId: execMessage.id,
+		}];
+	}
+	const fieldNumber = execCase ? EXEC_CASE_FIELD_NUMBERS.get(execCase) : undefined;
+	return fieldNumber === undefined ? [] : [{ type: "nonMcpExec", fieldNumber, ...(execMessage.execId ? { execId: execMessage.execId } : {}), execNumericId: execMessage.id }];
+}
+
+export function encodeKvClientMessage(id: number, messageCase: "getBlobResult" | "setBlobResult", value: unknown): Uint8Array {
+	const response = create(KvClientMessageSchema, { id, message: { case: messageCase, value } as never });
+	const clientMessage = create(AgentClientMessageSchema, { message: { case: "kvClientMessage", value: response } });
+	return toBinary(AgentClientMessageSchema, clientMessage);
+}
+
+export function encodeRequestContextResult(message: Extract<CursorControlMessage, { readonly type: "requestContext" }>, toolDefinitions: readonly McpToolDefinition[]): Uint8Array {
+	const requestContext = create(RequestContextSchema, {
+		rules: [],
+		repositoryInfo: [],
+		tools: [...toolDefinitions],
+		gitRepos: [],
+		projectLayouts: [],
+		mcpInstructions: [],
+		fileContents: {},
+		customSubagents: [],
+	});
+	const result = create(RequestContextResultSchema, {
+		result: { case: "success", value: create(RequestContextSuccessSchema, { requestContext }) },
+	});
+	return encodeExecClientMessage(message.execNumericId, message.execId, "requestContextResult", result);
+}
+
+export function encodeNativeExecRejection(message: Extract<CursorServerMessage, { readonly type: "nonMcpExec" }>): Uint8Array | undefined {
+	const result = createNativeExecResult(message.fieldNumber);
+	return result ? encodeExecClientMessage(message.execNumericId, message.execId, result.caseName, result.value) : undefined;
+}
+
+function createNativeExecResult(fieldNumber: number): { readonly caseName: string; readonly value: unknown } | undefined {
+	switch (fieldNumber) {
+		case 2:
+			return { caseName: "shellResult", value: create(ShellResultSchema, { result: { case: "rejected", value: createShellRejected() } }) };
+		case 3:
+			return { caseName: "writeResult", value: create(WriteResultSchema, { result: { case: "rejected", value: create(WriteRejectedSchema, { path: "", reason: NATIVE_EXEC_REJECT_REASON }) } }) };
+		case 4:
+			return { caseName: "deleteResult", value: create(DeleteResultSchema, { result: { case: "rejected", value: create(DeleteRejectedSchema, { path: "", reason: NATIVE_EXEC_REJECT_REASON }) } }) };
+		case 5:
+			return { caseName: "grepResult", value: create(GrepResultSchema, { result: { case: "error", value: create(GrepErrorSchema, { error: NATIVE_EXEC_REJECT_REASON }) } }) };
+		case 7:
+			return { caseName: "readResult", value: create(ReadResultSchema, { result: { case: "rejected", value: create(ReadRejectedSchema, { path: "", reason: NATIVE_EXEC_REJECT_REASON }) } }) };
+		case 8:
+			return { caseName: "lsResult", value: create(LsResultSchema, { result: { case: "rejected", value: create(LsRejectedSchema, { path: "", reason: NATIVE_EXEC_REJECT_REASON }) } }) };
+		case 9:
+			return { caseName: "diagnosticsResult", value: create(DiagnosticsResultSchema, {}) };
+		case 14:
+			return { caseName: "shellStream", value: create(ShellStreamSchema, { event: { case: "rejected", value: createShellRejected() } }) };
+		case 16:
+			return { caseName: "backgroundShellSpawnResult", value: create(BackgroundShellSpawnResultSchema, { result: { case: "rejected", value: createShellRejected() } }) };
+		case 17:
+			return { caseName: "listMcpResourcesExecResult", value: create(McpResultSchema, {}) };
+		case 18:
+			return { caseName: "readMcpResourceExecResult", value: create(McpResultSchema, {}) };
+		case 20:
+			return { caseName: "fetchResult", value: create(FetchResultSchema, { result: { case: "error", value: create(FetchErrorSchema, { url: "", error: NATIVE_EXEC_REJECT_REASON }) } }) };
+		case 21:
+			return { caseName: "recordScreenResult", value: create(McpResultSchema, {}) };
+		case 22:
+			return { caseName: "computerUseResult", value: create(McpResultSchema, {}) };
+		case 23:
+			return { caseName: "writeShellStdinResult", value: create(WriteShellStdinResultSchema, { result: { case: "error", value: create(WriteShellStdinErrorSchema, { error: NATIVE_EXEC_REJECT_REASON }) } }) };
+		default:
+			return undefined;
+	}
+}
+
+function createShellRejected(): ReturnType<typeof create<typeof ShellRejectedSchema>> {
+	return create(ShellRejectedSchema, {
+		command: "",
+		workingDirectory: "",
+		reason: NATIVE_EXEC_REJECT_REASON,
+		isReadonly: false,
+	});
+}
+
+export function encodeExecClientMessage(execNumericId: number | undefined, execId: string | undefined, messageCase: string, value: unknown): Uint8Array {
+	const execClientMessage = create(ExecClientMessageSchema, {
+		id: execNumericId ?? 0,
+		execId: execId ?? "",
+		message: { case: messageCase, value } as never,
+	});
+	const clientMessage = create(AgentClientMessageSchema, { message: { case: "execClientMessage", value: execClientMessage } });
+	return toBinary(AgentClientMessageSchema, clientMessage);
+}
+
+export function createMcpToolResult(text: string, isError: boolean): ReturnType<typeof create<typeof McpResultSchema>> {
+	if (isError) {
+		return create(McpResultSchema, { result: { case: "error", value: create(McpErrorSchema, { error: text }) } });
+	}
+	return create(McpResultSchema, {
+		result: {
+			case: "success",
+			value: createMcpSuccess(text),
+		},
+	});
+}
+
+export function createMcpToolCallResult(text: string, isError: boolean): ReturnType<typeof create<typeof McpToolResultSchema>> {
+	if (isError) {
+		return create(McpToolResultSchema, { result: { case: "error", value: create(McpToolErrorSchema, { error: text }) } });
+	}
+	return create(McpToolResultSchema, { result: { case: "success", value: createMcpSuccess(text) } });
+}
+
+function createMcpSuccess(text: string): ReturnType<typeof create<typeof McpSuccessSchema>> {
+	return create(McpSuccessSchema, {
+		content: [create(McpToolResultContentItemSchema, { content: { case: "text", value: create(McpTextContentSchema, { text }) } })],
+		isError: false,
+	});
+}
+