pi-cursor-sdk: Instructions file for Codex

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-local-run-terminal-error.ts owns cancelling a failed LOCAL run from its SDK terminal error run-row write (before the SDK changes run.status, so native tool processes stop) and restoring the SDK error from the resulting cancelled wait result; session stores are wrapped at open.
• 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 SessionManager-bound runtime scope keys/generations separately from stable persistent session identity, cwd/name/trust, process-wide started-session liveness and stale-extension detection, and lifecycle registration for pools, cloud names and debug grouping.
• src/cursor-provider-binding.ts owns public native Cursor auth/catalog publication, per-ExtensionAPI provider closures, and one-shot process-wide native header receipts capturing scope, usage origin, canonical projection, operation purpose and owning session state (an unstarted registrant delegates the turn to the receipt owner's module, which follows the native provider's catalog issue and model metadata); src/cursor-request-provenance.ts resolves actual-request-equivalent source-ordered occupancy floors and operation-signal summary purpose without text/clocks or sibling scans.
• src/cursor-session-settings.ts owns branch-scoped runtime/cloud acknowledgement, mode, fast, and HTTP preferences plus owner-scoped CLI snapshots/one-shot consumption across reload; SDK transport configuration and environment/user defaults remain process-global.
• src/cursor-custom-store-path.ts owns native custom-root validation, trusted-system alias/private directory preparation, fixed SQLite leaf and before/after-open identity guards (pathname/Windows ACL ceilings are explicit).
• src/cursor-session-store.ts owns captured default/custom-domain leases, exact custom-session and current/legacy default cwd/session-derived SQLite identity admission, contract-verified pre-migration layout safety, exact identity admission before bounded path walks, atomic derived cwd ownership through admission/open/disposal, temporary stores, and owned-prefix/removal guards (default-domain higher user-managed links allowed; persistent opens retain an active matching lease).
• src/cursor-http1.ts owns branch-scoped local HTTP/1.1 session state, global-preference override tracking, and the process-wide configured SDK handle/null reset.
• src/cursor-ripgrep-path.ts owns shared SDK-relative platform package resolution and local-agent ripgrep initialization; src/cursor-sdk-runtime.ts initializes the native parser vendor path before shared SDK imports.
• src/cursor-session-agent.ts owns runtime-scoped SDK agent pooling, durable transport-aware compatibility identity, send-state commits, busy tracking for in-flight SDK run.wait() work, and scoped acquire/dispose state; src/cursor-local-agent-ownership.ts owns atomic process-wide exact store/agent claims shared across extension copies and resume cleanup (release only on proven SDK disposal).
• 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 when no started live session remains across module copies.
• src/cursor-session-compaction-prep.ts owns prepareCursorSessionForCompaction() (release scoped live runs and reset the conversation pool) wired from session_before_compact in src/index.ts; isolated summary agents never commit ordinary resume handles.
• 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 exposes the shared exact-frame SDK output filter. Extension initialization installs one process-lifetime lease, including detached rules/skills work and asynchronous reload gaps; the versioned process singleton shares sink ownership and async attribution across reevaluation, with canonical test-only reset.
• 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 coherent native current-context mapping from LOCAL turn-ended usage or estimates; cumulative bills never enter native usage.
• src/cursor-sdk-billed-usage.ts owns bounded public Agent.getUsage() observation and disjoint aggregate-safe validation; no UUID watermarks or guessed client-run billing joins.
• src/cursor-usage-ledger.ts owns unique public native origin claims, validated fsynced session-ID journals, raw/reported/terminal/billed facts and canonical branch views; src/cursor-usage-command.ts owns truthful /cursor-usage view/refresh/export/help with the default footer unchanged.
• src/cursor-provider-turn-summary.ts owns fresh text-only LOCAL compaction/tree agents, ephemeral stores and disposal before terminal emission, independent of ordinary conversation tools/mode/resume.
• 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/release-review.mjs and scripts/lib/release-review-*.mjs own exact-diff review, catalog, registry, package, and PR/issue evidence receipts; their commands are in docs/development.md.
• 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; TOOL_DISPLAY_IMPLEMENTATIONS is a typed Record<CursorNormalizedToolName, ToolDisplaySpec> that requires every normalized tool key and rejects extra 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 stable MCP v2 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 Hono HTTP routing, Host/Origin validation, 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-pi-context.ts owns the stock/transcript Pi context boundary; it uses Pi's required public replay helpers, not a local replay implementation.
• src/cursor-context-tools.ts owns request tool snapshots at provider stream start (tools replayed from transcript declarations or shorthand systemPrompt/tools contexts), distinct from the registry-owned bridge snapshot.
• 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-custom-subagent-definitions.ts maps validated named config to public SDK agents with independent catalog selection; SDK 1.0.37 LOCAL conversion is ID/inherit-only, while Cloud retains params. Ordinary turn acquisition hashes nonempty resolved definitions; summaries remain definition-free.
• 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 no-follow regular-file opens, exclusive private creation, fsync, and bounded validated frame IO shared by usage journals, Cloud lifecycle and local cleanup; preserve descriptor/path identity guards.
• src/cursor-state.ts owns Cursor fast/mode controls, /cursor-http session/user persistence, /cursor-tools, and local config refresh/cleanup wiring.
• 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 naming, the model-facing bridge preference text, and concise MCP descriptions that point to the bootstrap tool-surface rules.
• 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/native-cursor-ownership.test.mjs owns native concurrent and same-file-manager lifecycle/resume/bridge ownership contracts, using the shared native harness and explicit compatibility CI routes.
• 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.
• test/helpers/cursor-provider-ownership.ts supplies explicit direct-provider fixtures with real public SessionManager/captured accounting; binding/native tests own actual header-receipt proof.
• 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).