@bastani/atomic 0.8.28-alpha.4 → 0.8.29-alpha.2

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added support for local `-e <dir>` extension sources to borrow project-local Atomic resources from `<dir>/.atomic`, legacy `<dir>/.pi`, and `<dir>/.agents/skills` after resolving trust for that extension source, preserving package-manager provenance and explicit-path workflow forwarding while avoiding untrusted borrowed resources ([#1354](https://github.com/bastani-inc/atomic/issues/1354)).
+- Added a prototype Rust/N-API Cursor HTTP/2 native transport binding through the generated `@bastani/atomic-natives` NAPI-RS package, so Atomic can use an in-process native HTTP/2 client without requiring Node.js on `PATH`.
+- Added the experimental bundled `@bastani/cursor` provider scaffold so `/login` can offer Cursor OAuth, estimated fallback exposes `cursor/composer-2`, and Cursor model mapping/streaming hooks are available behind an isolated HTTP/2 Connect transport boundary with production-default protobuf decoding, buffered Connect frames, write-before-headers Run streaming, stable Cursor conversation ids, schema-correct Cursor MCP tool advertisement, Cursor MCP tool-call decoding with protobuf `Value` or raw UTF-8/JSON arguments and exec-id metadata, same-stream MCP tool-result resume, abort/idle cleanup for paused tool streams, Connect end-stream error classification, exact live model id fidelity without static default injection, fast/thinking catalog grouping, and usage-delta accumulation.
+- Added the opt-in `createStructuredOutputTool({ schema, capture, output, name })` factory for terminating machine-readable final answers with schema-as-parameters validation, flat `details`, in-process capture, flat private `output.json` capture plus `output.meta.json` sidecar metadata, and prompt guidance for exact-once use without registering `structured_output` in normal agent sessions by default ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+
+### Changed
+
+- Bumped the bundled upstream pi runtime libraries `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui` from `^0.79.1` to `^0.79.3`, bringing the latest upstream provider, model, agent-core, and TUI compatibility fixes into `@bastani/atomic`.
+- Updated the structured-output extension example and SDK/workflow/extension docs to use the canonical factory instead of hand-rolled `terminate: true` wrappers, and documented that schema-specific calls pass fields directly rather than through `{ value: ... }` ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Enforced top-level object schemas for `structured_output` factory registration, with guidance to wrap array or primitive final values in object fields, made custom-named factory tools advertise the configured name in prompt metadata, and documented that text print mode recognizes factory-created custom structured-output tools without treating every terminating tool as printable ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Clarified SDK, extension, and workflow guidance that structured-output tools are opt-in custom tools, with workflow stages/tasks/chains/parallel items receiving `structured_output` only when they declare a `schema` and subagent children receiving it only when `outputSchema` is enabled ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+
+### Fixed
+
+- Fixed the root `@bastani/atomic` package export to include a `default` condition alongside the ESM import target, improving compatibility with loaders that select default export conditions.
+- Fixed extension custom UI focus deferral so full-screen overlays can keep keyboard focus while a parent/main-chat inline custom UI is pending, then focus that pending UI when the overlay is hidden; already-aborted custom UI calls no longer invoke factories or emit host custom-UI state changes ([#1353](https://github.com/bastani-inc/atomic/issues/1353)).
+- Fixed text print mode to emit trailing terminating JSON from factory-created structured-output tools, including custom tool names such as `final_decision`, instead of only recognizing the canonical `structured_output` name ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed terminating `structured_output` results to opt out of oversized-result persistence so large final JSON stays inline instead of being replaced by a `<persisted-output>` pointer ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed cross-process structured-output file capture to preserve flat schema-valid params in `output.json` and write call metadata to an `output.meta.json` sidecar so parent readback can reject stale or non-final captures instead of accepting any schema-valid `output.json` payload by existence alone ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed bundled subagent handling so explicit empty `tools: []` plus `outputSchema` grants only the schema-backed `structured_output` runtime tool instead of restoring default tools ([#1350](https://github.com/bastani-inc/atomic/issues/1350)).
+- Fixed prerelease publishing for native Atomic artifacts by allowing the `@bastani/atomic-natives` package metadata in release-preparation verification, running native artifact builds on architecture-matched Blacksmith and macOS runners, and documenting the two-package publish flow while keeping npm provenance publishing on GitHub-hosted Ubuntu.
+- Fixed the bundled experimental Cursor provider to honor per-request stream deadlines across open/read/resume writes, reset timed-out or aborted streams, clean up replaced paused turns safely, catch cleanup cancellation failures, tolerate non-MCP Cursor exec protocol messages without ending assistant turns, and align Run requests with Cursor's private CLI protocol by using blob/KV conversation state plus request-context tool-definition responses without the unsupported custom system-prompt field ([#1286](https://github.com/bastani-inc/atomic/issues/1286)).
+- Fixed release archive startup for the bundled experimental Cursor provider by declaring `@bufbuild/protobuf` as an `@bastani/atomic` runtime dependency, covering Cursor in the bundled-package dependency metadata guard, and smoke-checking Cursor/protobuf assets in native archives ([#1286](https://github.com/bastani-inc/atomic/issues/1286)).
+
+### Security
+
+- Kept Cursor credentials OAuth-only with token/header and PKCE poll-secret redaction and no localhost proxy, while moving Cursor HTTP/2 to a bundled Rust/N-API native binding and no longer sending the current working directory as `previousWorkspaceUris` by default.
+
+## [0.8.28] - 2026-06-11
+
+### Added
+
+- Added optional inline free-form text entry to the `ask_user_question` TUI's **Chat about this** footer row. Non-empty typed chat text now returns as a `kind: "chat"` answer surfaced to the agent without the legacy stop/wait termination envelope, while empty submissions keep the existing sentinel behavior.
+- Added session-scoped `bashPolicy` support for the built-in `bash` tool, with exact/prefix/command-string-glob/regex rules, deny-over-allow precedence, segment-aware parsing by default, fail-closed validation of invalid policies, and conservative rejection of compound heads, redirections, assignments, and non-literal command heads before shell execution.
+- Ported the upstream project-trust store and resolver foundation: project trust decisions are remembered, `--approve`/`--no-approve` affect runtime trust state, untrusted sessions skip project-local extensions/resources/context/system-prompt discovery and refuse project-setting writes, startup migrations and project config reads are trust-gated, and a new `/trust` slash command with the upstream `TrustSelectorComponent` lets saved project-trust decisions be reviewed and changed in-session.
+- Added upstream pi 0.76.0-0.79.1 coding-agent compatibility exports for package asset path helpers, CLI argument parsing (`Args`, `parseArgs`), `SettingsManagerCreateOptions`, image conversion (`convertToPng`), and RPC extension UI request/response types, plus the shared JSON comment/trailing-comma stripping utility used by model configuration migrations.
+- Added the upstream `project-trust`, `git-merge-and-resolve`, `input-transform-streaming`, and Gondolin tool-routing example extensions adapted to Atomic package identity, shared `warnDeprecation`/`openBrowser` utilities, upstream `docs/security.md` and `docs/containerization.md` rebranded for Atomic, and extensive upstream regression coverage.
+
+### Changed
+
+- Changed Atomic compaction to be verbatim-only across manual `/compact`, automatic threshold/overflow compaction, SDK/RPC compaction, and extension-triggered compaction. All compaction now records validated `context_compaction` deletion targets and rebuilds active context with retained transcript content verbatim and unchanged; retained file paths, exact commands, error strings, and line numbers are never paraphrased.
+- Changed compaction extension hooks (`session_before_compact`, `session_compact`) to receive verbatim context-compaction preparations/results and allow cancellation or locally validated deletion requests instead of custom generated summaries.
+- Changed the verbatim compaction critical-overflow recovery prompt to evict in an explicit priority order (removable reasoning traces first, then removable user/custom/summary context) while preserving existing safety/retention rules ([#1308](https://github.com/bastani-inc/atomic/issues/1308)).
+- Changed the bundled builtin `deep-research-codebase`, `goal`, `ralph`, and `open-claude-design` workflows to use `anthropic/claude-fable-5:xhigh` as the primary planner/reviewer/design model, demoting each previous primary to the head of the fallback chain ([#1345](https://github.com/bastani-inc/atomic/pull/1345)).
+- Bumped the bundled upstream pi libraries `@earendil-works/pi-agent-core`, `@earendil-works/pi-ai`, and `@earendil-works/pi-tui` from `^0.78.1` to `^0.79.1`, bringing in Claude Fable 5 and Azure metadata updates, GPT-5 token/context metadata fixes, provider thinking-payload compatibility updates, autocomplete/CJK prompt rendering fixes, and keyboard-protocol fallback improvements.
+- Ported upstream prompt-template argument default handling and added `${N:-default}` positional default support in prompt templates, matching upstream slash-template substitution behavior without recursively expanding argument/default values.
+
+### Fixed
+
+- Fixed oversized tool-call results flooding model context by persisting large results to disk (`<sessionDir>/tool-results/<toolCallId>.txt`) and returning a compact `<persisted-output>` message with the file path and a 2KB head preview when a result exceeds the 50,000-character system cap or a lower per-tool cap; tools can opt out via `maxResultSizeChars: Infinity`, and persistence degrades gracefully for images or write failures ([#1322](https://github.com/bastani-inc/atomic/issues/1322)).
+- Fixed the Read tool to block text file-read results above 50,000 characters and return incremental-read guidance, including byte-slice guidance for oversized single-line selections ([#1323](https://github.com/bastani-inc/atomic/issues/1323)).
+- Fixed `AgentSession.prompt` surfacing the confusing `No API key found for undefined` error when a model never resolved to a real provider; the prompt path now fails fast with a clear `Unknown model: "<id>" did not resolve to an available provider` message.
+- Hardened prompt-template argument substitution against polynomial-time regex backtracking (ReDoS) by length-bounding the `${N:-default}` default-value capture.
+- Fixed provider auth-status reporting for explicit `$ENV_VAR` config values, preserved uppercase literal credentials during config-value migrations (including legacy `~/.pi/agent` roots), preserved `models.json` JSONC comments/formatting during migration, and accepted the upstream `supportsDeveloperRole` flag for custom OpenAI Responses models.
+- Fixed RPC client requests to reject promptly when the child agent process exits or its stdio fails, completed the RPC-mode output/backpressure and `excludeFromContext` bash-command port, and preserved steering/follow-up queue modes across extension-triggered RPC session reloads.
+- Fixed SDK provider stream options so HTTP idle timeouts and WebSocket connect timeouts from settings are forwarded to provider streams while preserving per-request overrides.
+- Fixed interactive startup input handling so prompts submitted before the main input loop is installed are queued instead of dropped, and fixed signal-triggered shutdown ordering so extension `session_shutdown` cleanup runs before terminal restore writes.
+- Fixed the initial `--resume` session picker and all-sessions pane to honor a custom `--session-dir`.
+- Fixed plain metadata commands (`--version`, `--help`, `--list-models`) to keep their output on stdout for scripts/completions while keeping auto-install/startup chatter off stdout.
+- Fixed OAuth login dialog prompt/manual input rendering so submitted values remain stable, auth storage writes to consistently use `0600` file mode, and self-update command generation to bypass package-manager minimum-release-age delays.
+- Fixed changelog link normalization to produce Atomic repository/tag-pinned links from local package links and legacy pi-mono URLs, wired into startup and `/changelog` output.
+- Fixed WSL repositories on Windows-mounted paths to poll Git `HEAD` changes so the footer branch display updates reliably, plus footer cache-hit-rate display, settings selector default project-trust editing, tool self-render image rendering, and collapsed tool-output hint styling.
+- Rebranded provider attribution headers (OpenRouter, NVIDIA NIM) and the Gondolin VM session label to Atomic identity, matched OpenRouter-compatible custom endpoints by exact hostname, and corrected README/RPC/session-format/SDK/example docs to use `atomic`, `ATOMIC_*`, and `.atomic` as primary with legacy `PI_*`/`.pi` labeled as such.
+- Fixed extension command contexts to expose live base system-prompt options, hid `streamingBehavior` from idle input handlers, continued agent turns for follow-ups queued during `agent_end` handlers, and ported upstream tool path rendering with terminal hyperlink support for edit tool output.
+
+### Removed
+
+- Removed the legacy summary-compaction runtime path, summary prompts, `CompactionEntry` active-context injection, `CompactionSummaryMessage` active message type, custom compaction instructions (`CompactOptions.customInstructions`, RPC `compact.customInstructions`, `/compact [instructions]`), `compaction.keepRecentTokens` setting, summary-compaction public exports, and summary-compaction docs and examples. Historical `type:"compaction"` JSONL lines on disk are inert and are not injected into active LLM context.
+
+### Security
+
+- Bumped the transitive `shell-quote` dependency from `1.8.3` to `1.8.4` in the `examples/extensions/sandbox` lockfile, resolving the critical advisory [GHSA-w7jw-789q-3m8p](https://github.com/advisories/GHSA-w7jw-789q-3m8p).
+
 ## [0.8.28-alpha.4] - 2026-06-11
 
 ### Changed

package/dist/builtin/cursor/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Added a prototype Rust/N-API HTTP/2 native binding and loader so the Cursor transport uses the generated `@bastani/atomic-natives` NAPI-RS package without requiring Node.js on `PATH`.
+- Added the `@bastani/cursor` bundled provider scaffold with Cursor PKCE OAuth, token refresh, estimated/live model mapping, transport isolation, stream adapter hooks, lifecycle cleanup, and fake-transport tests.
+- Added a safe production UUID generator path for Cursor login, refresh, and streaming, plus an injectable HTTP/2 Connect transport boundary with frame helpers and protocol-codec seams for live Cursor RPC work.
+- Added the production-default minimal Cursor protobuf codec, buffered Connect frame decoder, HTTP/2 non-2xx/session/stream lifecycle error classification, and stricter live-discovery fallback policy.
+- Hardened Cursor Run streaming to write the initial Connect frame before response headers, eagerly observe stream/session terminal events, encode conversation/tool context, decode Cursor `execServerMessage.mcpArgs` tool calls with protobuf `Value` arguments and field-order-independent exec ids, classify Connect end-stream errors, parse checkpoint token details without counting `max_tokens` as output, and accumulate usage deltas without zeroing missing checkpoint fields.
+- Preserved live Cursor model id fidelity by exposing advertised fast/thinking ids instead of synthesizing absent base ids.
+- Added a token-free live model catalog cache with atomic writes, cached startup registration, best-effort auth-first refresh discovery, and bounded first-stream rediscovery cleanup.
+- Corrected Cursor MCP tool advertisement to encode Cursor's `McpTools` wrapper schema, stopped injecting static `composer-2` defaults into successful live or cached-live catalogs, and added stable conversation ids plus same-stream MCP tool-result resume for Cursor tool turns.
+- Hardened Cursor's private protocol edge by accepting raw UTF-8/JSON MCP argument bytes in addition to protobuf `Value` arguments, correlating historical tool results with their originating tool calls, preserving fast/thinking model modes as separate catalog groups, treating ambiguous effort-like suffixes such as `-max` as standalone model names without sibling evidence, and cancelling paused tool streams on abort or idle timeout.
+
+### Fixed
+
+- Fixed Cursor tool-call continuations by background-pumping Run stream frames while Atomic executes tools, so request-context/KV/control frames are answered before the next public message is consumed and paused turns no longer appear frozen after the first tool call.
+- Added bounded Cursor auth and transport request deadlines, cancelled paused streams when tool-result resume writes fail, and synchronized the Bun lockfile for the bundled Cursor package.
+- Fixed Cursor stream timeout and lifecycle edge cases so per-request deadlines bound stream open/read/resume writes, timeout exits reset instead of gracefully closing streams, paused-turn abort/idle/replacement cleanup cannot leak or cancel a replacement turn, and non-MCP Cursor exec protocol messages are tolerated without ending the assistant turn ([#1286](https://github.com/bastani-inc/atomic/issues/1286)).
+- Aligned Cursor Run request handling with the private Cursor CLI protocol by omitting the unsupported custom system-prompt field, serving conversation-state blobs through same-stream KV responses, returning MCP tool definitions from request-context responses, rejecting native Cursor execs so the model falls back to MCP tools, and pausing pending tool calls when Cursor waits for results without a terminal frame ([#1286](https://github.com/bastani-inc/atomic/issues/1286)).
+- Fixed live Cursor models disappearing after CLI restart by rediscovering the live catalog on `session_start` from stored Cursor OAuth credentials when the cached catalog is missing or stale, so live-only models such as Composer 2.5 can be restored without requiring another login.
+
+### Security
+
+- Cursor credentials are handled through Atomic OAuth storage only; Authorization headers, token-like diagnostics, and Cursor PKCE poll verifier/UUID values are redacted, and HTTP/2 is handled by the bundled native transport without a localhost proxy or Node subprocess.

package/dist/builtin/cursor/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Bastani, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+Attribution: small implementation facts and endpoint/protocol notes were adapted
+from the MIT-licensed pi-cursor-provider project by Netanel Draiman
+(https://github.com/ndraiman/pi-cursor-provider). This package does not copy the
+provider wholesale and does not include its local proxy implementation.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/builtin/cursor/README.md

@@ -0,0 +1,22 @@
+# @bastani/cursor
+
+First-party Atomic provider for Cursor subscription models.
+
+## Status
+
+This package registers `cursor` via Atomic's bundled extension provider API. `/login` shows **Cursor** and stores credentials through Atomic OAuth storage (`~/.atomic/agent/auth.json`). The login URL and PKCE polling behavior intentionally match the MIT-licensed [`ndraiman/pi-cursor-provider`](https://github.com/ndraiman/pi-cursor-provider) reference: `callbacks.onAuth({ url: loginUrl })`, no extra login warning/instruction copy, and polling `api2.cursor.sh/auth/poll` until Cursor returns tokens.
+
+The runtime protocol is also aligned to `ndraiman/pi-cursor-provider` at commit `82fc4e73f9ae820d87b34ac36713b18989910a36`: Atomic vendors the reference `cursor-models-raw.json` and generated `proto/agent_pb.ts`, and builds Cursor request/control messages through `@bufbuild/protobuf` descriptors instead of hand-maintained protobuf bytes. HTTP/2 itself is handled by the generated `@bastani/atomic-natives` Rust/N-API package rather than a separate local proxy.
+
+The unavoidable Atomic-specific integration difference is the provider surface: Atomic exposes a native `cursor-agent` `streamSimple` provider instead of the reference package's localhost OpenAI-compatible proxy. The Cursor auth/model/protocol bytes should otherwise stay reference-derived.
+
+## Limitations
+
+- Text input only. Vision/image content is rejected.
+- Cursor's private API may change without notice.
+- HTTP/2 transport requires the bundled `@bastani/atomic-natives` Rust/N-API native client for the current platform.
+- Credentials are OAuth-only. Do not pass Cursor tokens via command-line args, environment variables, logs, or local proxy processes.
+
+## Attribution
+
+Cursor auth, model fallback, and generated protobuf behavior are derived from the MIT-licensed `ndraiman/pi-cursor-provider` project.

package/dist/builtin/cursor/index.ts

@@ -0,0 +1,9 @@
+export { default } from "./src/provider.js";
+export { registerCursorProvider, type CursorProviderConfig, type CursorProviderHost, type CursorProviderRegistrationOptions, type CursorProviderRuntime } from "./src/provider.js";
+export { CursorAuthError, CursorAuthService, CursorToken, createPkcePair, deriveCursorTokenExpiry, fromOAuthCredentials, redactOAuthCredentials, toOAuthCredentials } from "./src/auth.js";
+export { CursorModelDiscoveryError, CursorModelDiscoveryService } from "./src/models.js";
+export { FileCursorCatalogCache, getDefaultCursorCatalogCachePath, parseCursorCatalogCacheRecord, toCursorCatalogCacheRecord, type CursorCatalogCache } from "./src/catalog-cache.js";
+export { createEstimatedCursorCatalog, insertEffortBeforeCursorSuffix, mapCursorCatalogToProviderModels, parseCursorVariant, resolveCursorModelVariant } from "./src/model-mapper.js";
+export { CursorConversationStateStore } from "./src/conversation-state.js";
+export { CursorStreamAdapter, createCursorStreamAdapter } from "./src/stream.js";
+export { Http2CursorAgentTransport } from "./src/transport.js";

package/dist/builtin/cursor/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bastani/cursor",
+  "version": "0.8.29-alpha.2",
+  "private": true,
+  "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
+  "contributors": [
+    "Norin Lavaee",
+    "Alex Lavaee"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "src/**/*.json",
+    "src/proto/README.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@bastani/atomic": "*"
+  },
+  "peerDependenciesMeta": {
+    "@bastani/atomic": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@bastani/atomic-natives": "0.8.29-alpha.2",
+    "@bufbuild/protobuf": "^2.0.0"
+  }
+}

package/dist/builtin/cursor/src/auth.ts

@@ -0,0 +1,352 @@
+import type { OAuthCredentials, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
+import { createHash, randomBytes as nodeRandomBytes, randomUUID } from "node:crypto";
+import {
+	CURSOR_API_BASE_URL,
+	CURSOR_AUTH_POLL_PATH,
+	CURSOR_DEFAULT_TOKEN_TTL_MS,
+	CURSOR_OAUTH_EXPIRY_SKEW_MS,
+	CURSOR_REFRESH_PATH,
+	CURSOR_WEB_BASE_URL,
+	CURSOR_LOGIN_PATH,
+	parseJsonObject,
+	readStringField,
+	readNumberField,
+	sanitizeDiagnosticText,
+} from "./config.js";
+
+export type CursorAuthErrorCode =
+	| "LoginCancelled"
+	| "PollTimedOut"
+	| "PollRejected"
+	| "RefreshTokenExpired"
+	| "CursorApiRejected"
+	| "NetworkError";
+
+export class CursorAuthError extends Error {
+	constructor(
+		readonly code: CursorAuthErrorCode,
+		message: string,
+		readonly status?: number,
+	) {
+		super(message);
+		this.name = "CursorAuthError";
+	}
+}
+
+export class CursorToken {
+	readonly kind: "access" | "refresh";
+	readonly #value: string;
+
+	constructor(kind: "access" | "refresh", value: string) {
+		this.kind = kind;
+		this.#value = value;
+	}
+
+	unwrap(): string {
+		return this.#value;
+	}
+
+	toString(): string {
+		return `[redacted cursor ${this.kind} token]`;
+	}
+
+	toJSON(): string {
+		return this.toString();
+	}
+}
+
+export interface CursorCredentialBundle {
+	readonly access: CursorToken;
+	readonly refresh: CursorToken;
+	readonly expires: number;
+}
+
+export interface CursorPkcePair {
+	readonly verifier: string;
+	readonly challenge: string;
+}
+
+export type CursorFetch = (url: string, init?: RequestInit) => Promise<Response>;
+export type CursorSleep = (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+export type CursorUuid = () => string;
+export type CursorRandomBytes = (length: number) => Uint8Array;
+export type CursorNow = () => number;
+
+export interface CursorAuthServiceOptions {
+	readonly fetch?: CursorFetch;
+	readonly sleep?: CursorSleep;
+	readonly uuid?: CursorUuid;
+	readonly randomBytes?: CursorRandomBytes;
+	readonly now?: CursorNow;
+	readonly maxPollAttempts?: number;
+	readonly initialPollDelayMs?: number;
+	readonly maxPollDelayMs?: number;
+	readonly pollBackoffMultiplier?: number;
+	readonly fetchTimeoutMs?: number;
+	readonly apiBaseUrl?: string;
+	readonly webBaseUrl?: string;
+}
+
+interface CursorTokenResponse {
+	readonly accessToken: string;
+	readonly refreshToken: string;
+}
+
+const DEFAULT_MAX_POLL_ATTEMPTS = 150;
+const DEFAULT_INITIAL_POLL_DELAY_MS = 1000;
+const DEFAULT_MAX_POLL_DELAY_MS = 10000;
+const DEFAULT_POLL_BACKOFF_MULTIPLIER = 1.2;
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
+
+export function base64Url(bytes: Uint8Array): string {
+	return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/u, "");
+}
+
+export function createPkcePair(randomBytes: CursorRandomBytes = defaultRandomBytes): CursorPkcePair {
+	const verifier = base64Url(randomBytes(96));
+	const challenge = createHash("sha256").update(verifier).digest("base64url");
+	return { verifier, challenge };
+}
+
+export function toOAuthCredentials(bundle: CursorCredentialBundle): OAuthCredentials {
+	return {
+		access: bundle.access.unwrap(),
+		refresh: bundle.refresh.unwrap(),
+		expires: bundle.expires,
+	};
+}
+
+export function fromOAuthCredentials(credentials: OAuthCredentials): CursorCredentialBundle {
+	return {
+		access: new CursorToken("access", credentials.access),
+		refresh: new CursorToken("refresh", credentials.refresh),
+		expires: credentials.expires,
+	};
+}
+
+export function redactOAuthCredentials(credentials: OAuthCredentials): OAuthCredentials {
+	return {
+		access: "[redacted]",
+		refresh: "[redacted]",
+		expires: credentials.expires,
+	};
+}
+
+export function deriveCursorTokenExpiry(accessToken: string, now: CursorNow = Date.now): number {
+	const parts = accessToken.split(".");
+	if (parts.length < 2 || !parts[1]) {
+		return now() + CURSOR_DEFAULT_TOKEN_TTL_MS;
+	}
+
+	try {
+		const payload = Buffer.from(parts[1], "base64url").toString("utf8");
+		const parsed = parseJsonObject(payload);
+		if (!parsed) {
+			return now() + CURSOR_DEFAULT_TOKEN_TTL_MS;
+		}
+		const exp = readNumberField(parsed, "exp");
+		return exp ? exp * 1000 - CURSOR_OAUTH_EXPIRY_SKEW_MS : now() + CURSOR_DEFAULT_TOKEN_TTL_MS;
+	} catch {
+		return now() + CURSOR_DEFAULT_TOKEN_TTL_MS;
+	}
+}
+
+export class CursorAuthService {
+	readonly #fetch: CursorFetch;
+	readonly #sleep: CursorSleep;
+	readonly #uuid: CursorUuid;
+	readonly #randomBytes: CursorRandomBytes;
+	readonly #now: CursorNow;
+	readonly #maxPollAttempts: number;
+	readonly #initialPollDelayMs: number;
+	readonly #maxPollDelayMs: number;
+	readonly #pollBackoffMultiplier: number;
+	readonly #fetchTimeoutMs: number;
+	readonly #apiBaseUrl: string;
+	readonly #webBaseUrl: string;
+
+	constructor(options: CursorAuthServiceOptions = {}) {
+		this.#fetch = options.fetch ?? fetch;
+		this.#sleep = options.sleep ?? sleep;
+		this.#uuid = options.uuid ?? randomUUID;
+		this.#randomBytes = options.randomBytes ?? defaultRandomBytes;
+		this.#now = options.now ?? Date.now;
+		this.#maxPollAttempts = options.maxPollAttempts ?? DEFAULT_MAX_POLL_ATTEMPTS;
+		this.#initialPollDelayMs = options.initialPollDelayMs ?? DEFAULT_INITIAL_POLL_DELAY_MS;
+		this.#maxPollDelayMs = options.maxPollDelayMs ?? DEFAULT_MAX_POLL_DELAY_MS;
+		this.#pollBackoffMultiplier = options.pollBackoffMultiplier ?? DEFAULT_POLL_BACKOFF_MULTIPLIER;
+		this.#fetchTimeoutMs = options.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+		this.#apiBaseUrl = options.apiBaseUrl ?? CURSOR_API_BASE_URL;
+		this.#webBaseUrl = options.webBaseUrl ?? CURSOR_WEB_BASE_URL;
+	}
+
+	async login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+		const bundle = await this.loginCursor(callbacks);
+		return toOAuthCredentials(bundle);
+	}
+
+	async loginCursor(callbacks: OAuthLoginCallbacks): Promise<CursorCredentialBundle> {
+		const { verifier, challenge } = createPkcePair(this.#randomBytes);
+		const uuid = this.#uuid();
+		const loginUrl = new URL(CURSOR_LOGIN_PATH, this.#webBaseUrl);
+		loginUrl.searchParams.set("challenge", challenge);
+		loginUrl.searchParams.set("uuid", uuid);
+		loginUrl.searchParams.set("mode", "login");
+		loginUrl.searchParams.set("redirectTarget", "cli");
+		callbacks.onAuth({ url: loginUrl.toString() });
+
+		let delayMs = this.#initialPollDelayMs;
+		let consecutiveErrors = 0;
+		for (let attempt = 0; attempt < this.#maxPollAttempts; attempt += 1) {
+			await this.#sleep(delayMs, callbacks.signal);
+			if (callbacks.signal?.aborted) {
+				throw new CursorAuthError("LoginCancelled", "Cursor login was cancelled.");
+			}
+
+			const pollUrl = new URL(CURSOR_AUTH_POLL_PATH, this.#apiBaseUrl);
+			pollUrl.searchParams.set("uuid", uuid);
+			pollUrl.searchParams.set("verifier", verifier);
+
+			let response: Response;
+			try {
+				response = await this.fetchWithDeadline(pollUrl.toString(), { method: "GET" }, callbacks.signal);
+			} catch {
+				if (callbacks.signal?.aborted) throw new CursorAuthError("LoginCancelled", "Cursor login was cancelled.");
+				consecutiveErrors += 1;
+				if (consecutiveErrors >= 3) {
+					throw new CursorAuthError("NetworkError", "Cursor login polling failed after repeated network errors.");
+				}
+				delayMs = Math.min(this.#maxPollDelayMs, Math.ceil(delayMs * this.#pollBackoffMultiplier));
+				continue;
+			}
+
+			if (response.status === 404) {
+				consecutiveErrors = 0;
+				delayMs = Math.min(this.#maxPollDelayMs, Math.ceil(delayMs * this.#pollBackoffMultiplier));
+				continue;
+			}
+
+			if (!response.ok) {
+				consecutiveErrors += 1;
+				if (consecutiveErrors >= 3) {
+					const responseText = await response.text();
+					throw new CursorAuthError(
+						"PollRejected",
+						`Cursor login polling was rejected (${response.status}): ${sanitizeDiagnosticText(responseText, [verifier, uuid, pollUrl.toString()])}`,
+						response.status,
+					);
+				}
+				delayMs = Math.min(this.#maxPollDelayMs, Math.ceil(delayMs * this.#pollBackoffMultiplier));
+				continue;
+			}
+
+			const tokenResponse = parseTokenResponse(await response.text());
+			if (!tokenResponse || tokenResponse.refreshToken.length === 0) {
+				throw new CursorAuthError("PollRejected", "Cursor login response did not include usable tokens.", response.status);
+			}
+
+			return {
+				access: new CursorToken("access", tokenResponse.accessToken),
+				refresh: new CursorToken("refresh", tokenResponse.refreshToken),
+				expires: deriveCursorTokenExpiry(tokenResponse.accessToken, this.#now),
+			};
+		}
+
+		throw new CursorAuthError("PollTimedOut", "Cursor login timed out before authorization completed.");
+	}
+
+	async refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+		const bundle = await this.refreshCursorCredentials(fromOAuthCredentials(credentials));
+		return toOAuthCredentials(bundle);
+	}
+
+	async refreshCursorCredentials(credentials: CursorCredentialBundle): Promise<CursorCredentialBundle> {
+		const refresh = credentials.refresh.unwrap();
+		let response: Response;
+		try {
+			response = await this.fetchWithDeadline(new URL(CURSOR_REFRESH_PATH, this.#apiBaseUrl).toString(), {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${refresh}`,
+					"Content-Type": "application/json",
+				},
+				body: "{}",
+			});
+		} catch {
+			throw new CursorAuthError("NetworkError", "Cursor token refresh failed because the network request failed.");
+		}
+
+		if (response.status === 401 || response.status === 403) {
+			throw new CursorAuthError("RefreshTokenExpired", "Cursor refresh token expired or was rejected; run /login again.", response.status);
+		}
+		if (!response.ok) {
+			const responseText = await response.text();
+			throw new CursorAuthError(
+				"CursorApiRejected",
+				`Cursor token refresh failed (${response.status}): ${sanitizeDiagnosticText(responseText, [refresh])}`,
+				response.status,
+			);
+		}
+
+		const tokenResponse = parseTokenResponse(await response.text());
+		if (!tokenResponse) {
+			throw new CursorAuthError("CursorApiRejected", "Cursor token refresh response did not include an access token.", response.status);
+		}
+		return {
+			access: new CursorToken("access", tokenResponse.accessToken),
+			refresh: new CursorToken("refresh", tokenResponse.refreshToken || refresh),
+			expires: deriveCursorTokenExpiry(tokenResponse.accessToken, this.#now),
+		};
+	}
+
+	private async fetchWithDeadline(url: string, init: RequestInit, parentSignal?: AbortSignal): Promise<Response> {
+		const controller = new AbortController();
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		const timeoutPromise = new Promise<never>((_, reject) => {
+			timeout = setTimeout(() => {
+				controller.abort();
+				reject(new CursorAuthError("NetworkError", "Cursor authentication request timed out."));
+			}, this.#fetchTimeoutMs);
+			timeout.unref?.();
+		});
+		const onAbort = (): void => controller.abort();
+		parentSignal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await Promise.race([this.#fetch(url, { ...init, signal: controller.signal }), timeoutPromise]);
+		} finally {
+			if (timeout) clearTimeout(timeout);
+			parentSignal?.removeEventListener("abort", onAbort);
+		}
+	}
+}
+
+function parseTokenResponse(text: string): CursorTokenResponse | undefined {
+	const parsed = parseJsonObject(text);
+	if (!parsed) return undefined;
+	const accessToken = readStringField(parsed, "accessToken") ?? readStringField(parsed, "access_token");
+	const refreshToken = readStringField(parsed, "refreshToken") ?? readStringField(parsed, "refresh_token") ?? "";
+	if (!accessToken) return undefined;
+	return { accessToken, refreshToken };
+}
+
+function defaultRandomBytes(length: number): Uint8Array {
+	return nodeRandomBytes(length);
+}
+
+function sleep(milliseconds: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) {
+		return Promise.reject(new CursorAuthError("LoginCancelled", "Cursor login was cancelled."));
+	}
+	return new Promise((resolve, reject) => {
+		const abort = (): void => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			reject(new CursorAuthError("LoginCancelled", "Cursor login was cancelled."));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", abort);
+			resolve();
+		}, milliseconds);
+		signal?.addEventListener("abort", abort, { once: true });
+	});
+}