pi-cursor-sdk AGENTS.md

AGENTS.md

Purpose

This repository is a pi provider extension that registers Cursor SDK-backed models under the cursor provider. Agent work is successful when changes preserve pi-native model/thinking/session behavior, keep Cursor API keys out of repo state and logs, and pass the local validation commands below.

Repository map

• src/index.ts registers the pi extension, provider, fallback warnings, Cursor runtime controls, native replay wrappers, question tool, and pi tool bridge hooks.
• src/model-discovery.ts discovers Cursor models, builds pi model metadata, stores per-model metadata, and defines fallback models.
• shared/cursor-model-selection-identities.mjs owns canonical selectable model/context/fast identities and context-window key normalization shared by runtime discovery and the snapshot generator; its .d.mts file owns the TypeScript contract.
• src/cursor-provider.ts is a thin streamCursor() wrapper that delegates turn execution to the turn runner.
• src/cursor-provider-turn-runner.ts orchestrates provider turns (pre-send drain, prepare, send, finalize, emit, cleanup).
• src/cursor-provider-turn-prepare.ts owns turn prepare (auth, MCP timeout install, effective local HTTP transport configuration, session agent, live-run setup, coordinator).
• src/cursor-provider-turn-send.ts owns SDK agent.send() wiring and abort listener registration.
• src/cursor-provider-turn-finalize.ts owns unified awaitFinalizeCursorRunOutcome() (wait, transcript replay, incomplete tools, artifacts, context cache).
• src/cursor-provider-turn-emit.ts owns live vs direct emission from finalized outcomes.
• src/cursor-provider-turn-types.ts owns immutable turn phase data and explicit phase result types; phase-local cleanup stays inside the owning phase.
• src/cursor-provider-run-outcome.ts owns the discriminated CursorRunOutcome model and terminal emission classification.
• src/cursor-provider-run-finalizer.ts owns live-run wait completion, outcome application, debug finalization, and SDK abort-suppression disposal.
• src/cursor-run-final-text.ts owns final assistant text selection for run outcomes and live-run drain.
• src/cursor-provider-errors.ts owns scrubbed Cursor SDK run failure detail, abort reason formatting, and provider error sanitization.
• src/cursor-provider-lazy.ts owns the streamSimple wrapper that defers Cursor provider execution to invocation and converts provider runtime failures into stream errors; the provider module stays in Pi's static extension graph so host peers resolve through Pi's loader.
• src/cursor-session-scope.ts owns pi session cwd, session file/id/name/generation scope keys, and session_start / session_info_changed registration for session-agent pooling, cloud agent names, and debug grouping.
• src/cursor-session-store.ts owns per-session Cursor SDK SQLite store identity derivation, open/disposal, temporary fileless stores, and guarded removal.
• src/cursor-http1.ts owns branch-scoped local HTTP/1.1 session state, global-preference override tracking, and extension-owned SDK configuration/null reset.
• src/cursor-ripgrep-path.ts owns bundled Cursor SDK platform ripgrep resolution and local-agent environment initialization.
• src/cursor-session-agent.ts owns session-scoped SDK agent pooling, transport-aware pool identity, send-state commits, busy tracking for in-flight SDK run.wait() work, and scoped acquire/dispose state.
• src/cursor-session-agent-lineage.ts owns non-resumable per-session local agent lineage custom entries independent of local resume.
• src/cursor-session-agent-lifecycle.ts owns lazy session-agent lifecycle invalidation on model select, compaction, tree navigation, shutdown, and scope changes, including shutdown-time HTTP transport reset before module reload.
• src/cursor-session-compaction-prep.ts owns prepareCursorSessionForCompaction() (release scoped live runs, reset pooled agent, suppress summarizer resume-handle persist) wired from session_before_compact in src/index.ts.
• src/cursor-session-send-policy.ts owns session send planning (bootstrap vs incremental), periodic agent rebootstrap threshold, and prompt mode selection.
• src/cursor-provider-live-run-drain.ts owns live-run drain/replay mirroring, pre-send continuation, and native replay turn emission.
• src/cursor-provider-turn-coordinator.ts orchestrates SDK delta/step handling during a turn over focused collaborators.
• src/cursor-provider-turn-shell-output.ts owns shell-output-delta tracking and merging into completed shell tool calls.
• src/cursor-provider-turn-tool-ledger.ts owns started/completed tool identities, fingerprints, and duplicate suppression.
• src/cursor-provider-turn-sdk-normalizer.ts normalizes SDK delta/step completions via the ledger and shell tracker.
• src/cursor-provider-turn-display-router.ts owns trace vs native-replay display routing during a turn.
• src/cursor-provider-turn-lifecycle-emitter.ts owns deferred in-progress lifecycle labels during a turn.
• src/cursor-tool-lifecycle.ts owns low-noise deferred in-progress lifecycle labels for long-running Cursor tools (coalesced with completed replay cards; bridge excluded).
• src/cursor-tool-visibility.ts owns canonical Cursor tool visibility classification for lifecycle, incomplete-tool, and replay activity titles.
• src/cursor-incomplete-tool-visibility.ts owns bounded user-visible labels/traces for started Cursor SDK tool calls discarded without completion.
• src/cursor-sdk-event-debug.ts owns opt-in provider event artifact capture for Cursor SDK callbacks, stream events, replay/drain/bridge decisions, final partials, and summaries under .debug/cursor-sdk-events/, including discarded incomplete started tool calls when PI_CURSOR_SDK_EVENT_DEBUG=1.
• shared/cursor-sdk-event-debug-env.mjs owns canonical Cursor SDK event-debug env names; src/cursor-sdk-event-debug-constants.ts re-exports them and owns debug artifact base-dir resolution.
• src/cursor-sdk-event-debug-session.ts owns debug session grouping, turn artifact directory allocation, and session manifest updates.
• src/cursor-agents-context.ts owns Cursor-model suppression of pi <project_context> / AGENTS.md duplication and PI_CURSOR_PRESERVE_PI_AGENTS_MD; src/cursor-agents-context-registration.ts owns the static lifecycle registration for that suppression.
• src/cursor-sdk-output-filter.ts suppresses Cursor SDK integrator bootstrap noise from pi's TUI.
• src/cursor-edit-diff.ts owns canonical edit diff fallback resolution for replay/display paths.
• src/cursor-record-utils.ts owns shared record/string-key parsing and neutral unknown-value stringification helpers used across bridge and transcript layers.
• src/cursor-partial-content-emitter.ts owns shared thinking/text block emission for live-run drain and turn coordinator paths.
• shared/cursor-cloud-lifecycle-constants.mjs owns the canonical Cursor Cloud agent ID pattern, lifecycle entry type, and journal prefix; src/cursor-cloud-lifecycle.ts and scripts/cloud-runtime-smoke.mjs consume it for provider runtime and maintainer scripts.
• shared/cursor-sensitive-text.mjs owns canonical secret scrubbing; src/cursor-sensitive-text.ts and maintainer scripts import it directly.
• shared/cursor-setting-sources.mjs owns canonical PI_CURSOR_SETTING_SOURCES parsing/serialization; src/cursor-setting-sources.ts and maintainer scripts import it directly.
• src/cursor-usage-accounting.ts owns pi usage mapping from local turn-ended and billed Agent.getUsage() spend, plus post-compaction occupancy floors.
• src/cursor-sdk-billed-usage.ts owns Agent.getUsage() fetch, local usage-UUID watermarks, and billed turn selection.
• scripts/lib/cursor-smoke-env.mjs, scripts/lib/cursor-smoke-shell.sh, and scripts/lib/cursor-visual-render.mjs own maintainer smoke PATH/env isolation and browser-rendered visual artifacts; smoke runners should consume these helpers instead of duplicating debug env names, sealed Node PATH logic, or xterm/Playwright rendering.
• scripts/lib/cloud-smoke-github.mjs owns throwaway GitHub repository identity, provisioning, and deletion proof; scripts/lib/cloud-smoke-cleanup-evidence.mjs owns Cloud agent cleanup, retained evidence/provenance, and release-gate resource coordination; scripts/lib/cloud-smoke-shutdown.mjs owns signal-safe detached-child shutdown; scripts/lib/cloud-smoke-pi-runner.mjs owns print/RPC child transport; scripts/lib/cloud-smoke-artifacts.mjs owns metadata and lifecycle artifact readers. scripts/cloud-runtime-smoke.mjs keeps concrete lane orchestration.
• scripts/platform-smoke/artifact-bundle-contract.mjs owns the canonical platform artifact bundle path/size/shape contract; scripts/platform-smoke/artifact-fs-safety.mjs owns no-follow traversal, bounded reads, extraction preflight, and spill writes; scripts/platform-smoke/artifact-anchored-extract.mjs plus artifact-openat-extract.c own descriptor-relative POSIX extraction/rollback and fail-closed Windows-controller handling; scripts/platform-smoke/artifact-secrets.mjs owns bundle secret-scan/redaction; scripts/platform-smoke/wrapped-line-match.mjs owns terminal-wrap-aware line matching. Platform smoke scripts should consume these instead of duplicating fs-safety or redaction logic.
• src/cursor-tool-presentation-registry.ts is the canonical typed registry for Cursor tool names, labels, visibility, lifecycle, replay metadata (legacy wrapper names, wrapper labels, side-effect policy, call-summary policy), web remapping, alias normalization, and bridge exclusions for internal replay wrappers only (cursor, cursor_*); sibling modules derive from it.
• src/cursor-transcript-tool-specs.ts owns per-tool transcript formatters and pi display builders keyed by normalized tool name; its display implementation keys must match registry entries exactly (CURSOR_TOOL_DISPLAY_SPEC_KEYS).
• src/cursor-pi-tool-bridge-types.ts owns shared bridge/MCP type contracts.
• src/cursor-env-boolean.ts owns canonical env boolean parsing (default and tri-state optional) for bridge diagnostics, flags, and native replay gating.
• src/cursor-live-run-coordinator.ts owns live Cursor run registry/scope matching, queued events, drain leases, idle disposal timers, and release cleanup.
• src/cursor-pi-tool-bridge.ts re-exports bridge registration and snapshot helpers; exposes active pi tools to local Cursor agents through a per-run loopback MCP bridge.
• src/cursor-pi-tool-bridge-snapshot.ts owns bridge snapshot building, env gating, and surface signatures.
• src/cursor-pi-tool-bridge-server.ts owns loopback HTTP routing and run endpoint registry for bridge runs.
• src/cursor-pi-tool-bridge-run.ts owns MCP transport setup, pending bridge calls, pi tool dispatch, cancellation, and run lifecycle.
• src/cursor-pi-tool-bridge-abort.ts owns bridge pi tool execution abort tracking and process signal handling.
• src/cursor-pi-tool-bridge-diagnostics.ts owns bridge debug diagnostics serialization and stderr logging.
• src/cursor-pi-tool-bridge-mcp.ts owns MCP name/schema conversion and pi-to-MCP content helpers for the bridge.
• src/cursor-model-lifecycle.ts owns the canonical effective Cursor model lifecycle/sync helper for session_start, before_agent_start, model_select with event-model override, and turn_start; callers keep Cursor-only filtering explicit.
• src/cursor-fallback-warning.ts owns per-session Cursor fallback catalog warning activation.
• src/cursor-question-tool.ts owns the bridge-exposed cursor_ask_question pi UI tool and the pi-cursor-sdk:ask-question:blocked wait-state event.
• src/cursor-native-tool-display-registration.ts owns native replay tool registration and model-scoped activation.
• src/cursor-native-replay-routing.ts owns canonical native replay disposition (queue_replay / inactive_trace / transcript_trace) and context-tool partitioning for drain.
• src/cursor-native-replay-trace.ts owns inactive native replay trace formatting (title: summary).
• src/cursor-context-tools.ts owns context.tools snapshot helpers at provider stream start.
• src/cursor-display-text.ts owns shared single-line sanitization and 240-char truncation for replay/trace display.
• src/cursor-native-tool-display-replay.ts owns replay card rendering and diff/preview formatting.
• src/cursor-native-tool-display-tools.ts owns native/replay tool definition factories and replay execute wrappers.
• src/cursor-native-tool-display-state.ts owns native replay display state, env gating, and record/consume helpers.
• src/cursor-tool-result-display-readers.ts owns canonical result readers shared by transcript/replay paths, including MCP-like content display normalization.
• src/cursor-tool-transcript.ts owns the raw unknown toolCall -> transcript/display façade; src/cursor-transcript-tool-specs.ts, src/cursor-transcript-utils.ts, and src/cursor-transcript-tool-formatters.ts implement spec dispatch and formatting.
• src/cursor-mcp-timeout-override.ts owns Cursor SDK MCP timeout overrides: 3600s default for callTool, 10s default for verified initialize/listTools paths on first send, and SDK-default behavior for unknown MCP protocol stacks.
• src/cursor-config.ts owns Cursor SDK config loading, parsing, source precedence, safety-cap resolution, cloud environment selection, and legacy fast-default config persistence.
• src/cursor-cloud-options.ts owns cloud SDK option mapping and fail-closed preflight.
• src/cursor-cloud-local-state.ts owns canonical cloud starting-ref normalization, hermetic Git probes, remote identity/refspec validation, and reasoned local-state inspection.
• src/cursor-cloud-lifecycle.ts owns session-branch cloud lifecycle ledger entries and explicit /cursor-cloud list/archive/delete command behavior.
• src/cursor-durable-fs.ts owns the canonical no-follow regular-file open (openExistingRegularFileNoFollow) and read-write fsync (fsyncExistingRegularFile) helpers used to durably fsync session/journal files without following an attacker-replaced symlink; src/cursor-cloud-lifecycle.ts and src/cursor-session-agent-cleanup.ts consume it instead of duplicating the identity-check logic.
• src/cursor-state.ts owns Cursor fast/mode controls, /cursor-http session/user persistence, /cursor-tools, local config refresh/cleanup wiring, and stable state re-exports.
• src/cursor-runtime-state.ts owns effective Cursor config/runtime resolution, cloud/local runtime flags, runtime status helpers, cloud acknowledgement, and /cursor-runtime / /cursor-cloud wiring.
• src/context.ts, src/context-window-cache.ts, and src/bundled-context-windows.ts handle prompt conversion and context-window caches.
• src/cursor-bridge-contract.ts owns pi bridge MCP description helpers and the exported full bridge contract text (bootstrap/manifest carry the user-facing contract; MCP descriptions use a one-line pointer).
• src/cursor-tool-manifest.ts owns bootstrap callable-surface manifest text (PI_CURSOR_TOOL_MANIFEST, default on).
• test/**/*.test.ts contains Vitest coverage for provider registration, discovery, state, context, bridge, replay, and streaming behavior.
• test/helpers/pi-harness.ts is the canonical fake pi/extension harness (createPiHarness, shared model/context/event runners, tool factories).
• test/helpers/cursor-provider-harness.ts owns Cursor SDK provider mocks/stream helpers and re-exports pi-harness fixtures for provider tests.
• docs/cursor-model-ux-spec.md is the maintainer design source of truth for Cursor model UX. Keep it aligned with behavior changes.
• docs/cursor-testing-lessons.md is the maintainer source of truth for regression testing lessons (auth.json, isolated smoke harnesses, JSONL replay scans, plan-mode replay traps).
• docs/cursor-dogfood-checklist.md is the minimal one-session dogfood checklist (baseline env, JSONL ID patterns, bootstrap manifest, edit diff card).