pi-cursor-sdk

When using the Cursor SDK, you must map Pi's native thinking levels to the specific values expected by the Cursor models.

Pi Thinking Levels: off, minimal, low, medium, high, xhigh, max.

Mapping Rules:

• off $\rightarrow$ none (if supported), else off, else false.
• minimal $\rightarrow$ minimal.
• low $\rightarrow$ low.
• medium $\rightarrow$ medium.
• high $\rightarrow$ high (or true for boolean-only thinking models).
• xhigh $\rightarrow$ xhigh (or extra-high).
• max $\rightarrow$ max.

Important Implementation Details:

• Use null for unsupported Pi levels so the system can skip or clamp them natively.
• For models that only support boolean thinking (true/false), use an explicit mapping where unsupported levels are null to avoid accidental enablement.
• The thinkingLevelMap only controls Pi-native behavior; the actual ModelSelection.params for Agent.create() must be constructed using the active Pi level and discovered Cursor metadata.

// Example shape for boolean-only thinking models
{
  off: "false",
  minimal: null,
  low: null,
  medium: null,
  high: "true",
  xhigh: null,
  max: null,
}

There are several integration boundaries in the pi-cursor-sdk that affect how tools are displayed:

Tool Visibility Limits

• Live Web-Search Ordering: Local Cursor WebSearch might not appear in live streaming events (onDelta, onStep, run.stream()). The web search card may only appear after run.wait() finishes to avoid buffering the entire assistant response.
• WebFetch Availability: The SDK can only display a Cursor web fetch if the SDK reports a webFetchToolCall, a web-fetch-shaped MCP completion, or a web-fetch host alias. It cannot force Cursor to expose WebFetch if it isn't in the tool set.
• Future SDK Tools: If Cursor introduces new tools with unknown names or payloads, the SDK falls back to neutral Cursor activity cards with scrubbed text.

Error Handling

• Process-level Exceptions: Raw AbortError DOMExceptions and certain WriteIterableClosedError events are suppressed during active provider turns to maintain a stable session lifecycle. However, fatal errors like write EPIPE (in specific multi-frame synchronous write paths) remain fatal.

The platform smoke suite executes across three distinct target environments to ensure cross-platform stability. Each target uses a specific Crabbox provider and follows a specific execution contract.

Key Architectural Concepts:

• Host-side Rendering: To avoid browser dependency drift inside test targets, targets capture the raw ANSI stream, and the host machine performs the rendering (e.g., via xterm/Playwright) to generate visual evidence.
• Fail-Fast Logic: The gate runs targets sequentially. If one target fails, the suite stops immediately to prevent wasting Cursor API tokens and resources.

Native replay is display-only. It is a mechanism to show what happened in Cursor, not to execute actions in pi.

What replay does NOT do:

• No Execution: It does not re-run Cursor-side commands, apply edits/deletes, or call Cursor-side MCP servers.
• No State Updates: Replay-only cards do not update pi state, generate images, or drive pi workflow controls (like SwitchMode, plan mode, or todo state).
• No Tool Exposure: Replay does not expose pi tool schemas to Cursor. The local pi MCP bridge is the correct path for exposing active pi tools.
• No Web Tools: Cursor web search and Cursor web fetch cards are mirrors of SDK-reported activity; pi does not expose executable web search/fetch tools through replay.

Handling Incomplete Tasks:

• Started tool calls that never complete are surfaced as neutral Cursor [tool name] did not complete activity cards.
• Reasons for incompletion include missing completion, aborted, or SDK run failed.

When running pi-cursor-sdk locally, there are two distinct tool surfaces interacting with Cursor:

1. Cursor-native surface: Includes Cursor local-agent tools, settings, plugins, and configured Cursor MCP servers. This surface is owned by the Cursor SDK local agent path and is not affected by Pi CLI tool toggles like --no-tools or --exclude-tools.
2. pi bridge surface: Exposes active pi tools through a local loopback MCP bridge. This surface is affected by Pi CLI tool toggles because they change the active pi tool registry.

Key Bridge Behaviors:

• Naming: Bridged tools are exposed to Cursor with collision-safe names using the pi__ prefix (e.g., pi__sem_reindex).
• Tool Preference: When the bridge is active, Cursor is instructed to prefer pi__mcp for MCP work and pi__subagent for delegation. Cursor-configured MCP and native subagents act as fallbacks.
• Execution: The bridge queues Cursor's MCP calls, emits a toolCall in pi, waits for the toolResult, and resolves it back to the Cursor SDK run without creating a new Agent.
• Built-in Tools: Overlapping tools like read, bash, write, edit, grep, find, and ls are hidden by default to avoid conflict with Cursor's native capabilities. Use PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 to expose them.