pi-cursor-sdk 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Changelog
 
-## Unreleased
+## 0.1.17 - 2026-05-23
+
+### Added
+
+- Surface in-progress Cursor SDK `task` activity in the TUI from SDK-provided `args.description`, with one deduped line such as `Cursor task: Explore AI/automation projects` and no generic heartbeat or per-tool start spam.
+
+### Changed
+
+- Bump pi dev dependency baseline to `0.75.5` for read-tool collapsed-card rendering, package update fixes, and other upstream pi changes. Cursor edit replay remains display-only via `diffString`; pi's new SDK `details.patch` field is not required because Cursor agents do not execute pi's edit tool.
+- Rework live-run internals into dedicated coordination/drain/turn/partial-content modules (`cursor-live-run-coordinator.ts`, `cursor-provider-live-run-drain.ts`, `cursor-provider-turn-coordinator.ts`, `cursor-partial-content-emitter.ts`) while preserving the provider's external contract.
+- Complete phase-2 remediation for #23/#24/#25 by splitting bridge ownership across snapshot/server/run/abort/diagnostics/MCP/types modules, splitting native replay ownership across state/registration/replay/tools modules, and unifying tool completion routing through `resolveToolCompletion`.
+- Replace monolithic provider test coverage with focused stream/bridge/replay/live-run suites plus shared harness helpers.
+- Promote smoke automation into packaged entrypoints (`npm run smoke:live`, `npm run smoke:steering`, `npm run smoke:jsonl`) and make helper retry/polling behavior explicit (TUI answer/footer polling plus deterministic tmux cleanup).
+- Document the hard maintainer rule that Cursor SDK behavior must be verified against the installed `@cursor/sdk` package and/or official TypeScript SDK docs before implementation or release claims.
+- Bump package metadata to `0.1.17` so the dry-run tarball no longer collides with the existing `v0.1.16` tag.
+
+### Fixed
+
+- Resolve startup noise issue #17 by extending Cursor SDK bootstrap filtering to late hook compatibility warnings and ripgrep/ignore-mapping output while preserving non-startup logs.
+- Fix steering/follow-up delivery for active pooled Cursor runs by resuming/waiting on the in-flight run and sending incremental follow-up text after pending tool/result flow completes instead of issuing a second concurrent `Agent.send()`; additional stale tool batches from the old run are cancelled so the new user input is not lost.
+- Resolve issue #19 with a canonical edit-diff fallback resolver (`diffString → diff → unifiedDiff → patch`) shared by replay and transcript formatting paths.
+- Resolve issue #20 by updating the token-tracking investigation note to mark the `0.75.3` observation as point-in-time and call out the current `0.75.5` development baseline.
+- Resolve issue #21 by decomposing prior 1k+ provider/transcript/bridge/test monoliths into ownership-scoped modules.
+- Harden bridge diagnostics and secret scrubbing so debug JSONL stays run-safe and allowlisted without endpoint path material, raw args/results, or credential payloads.
+- Make Cursor SDK output filtering safe for overlapping provider streams by restoring the global stdout/stderr/console patch only after the last active install.
+- Reject bridge MCP calls cleanly when tool-dispatch handlers throw, and avoid suppressing unrelated MCP replay solely because an external payload reuses a known bridge request ID.
+- Bound native replay diff/write previews by both lines and characters, summarize non-text MCP content without dumping raw payload JSON, and make expanded-diff truncation copy truthful.
+- Change smoke forbidden-material scans to report only matching file names, not secret-bearing matched lines.
+- Harden live-smoke direct-output checks so a step logs `PASS` only after both command exit and expected stdout assertion succeed, with the basic prompt retrying once on empty output even when the first command exits zero.
 
 ## 0.1.16 - 2026-05-22
 

package/README.md

@@ -248,7 +248,7 @@ Actual Cursor runs still need a key from `/login`, `CURSOR_API_KEY`, or `--api-k
 - **The pi tool bridge is local and MCP-backed.** Bridgeable active pi tools are exposed to local Cursor agents through a tokenized `127.0.0.1` MCP endpoint; internal Cursor replay activity names are excluded, and overlapping built-in pi tools are hidden by default. Set `PI_CURSOR_PI_TOOL_BRIDGE=0` to disable it or `PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1` to expose overlapping built-ins too.
 - **Cursor native tool replay is display-only.** Replay renders recorded Cursor SDK activity and never re-runs Cursor-side commands, reapplies Cursor edits, calls MCP servers, or mutates pi state. Workflow tools such as Cursor `SwitchMode` and Cursor todo state are not pi workflow controls. See [Cursor native tool replay](docs/cursor-native-tool-replay.md) for supported replay cards, ordering, conflict handling, and opt-out flags.
 - **Cursor run state can span tool-use turns.** Within a pi session, the extension reuses one Cursor SDK agent across compatible follow-up turns and sends incremental prompts when context still matches. It recreates the agent when context diverges, after compaction or `/tree` navigation, on API key changes, after send errors, or on session shutdown. For bridged pi tools, the matching pi `toolResult` resolves into the same live Cursor SDK run without creating a new `Agent`, unless the run was disposed, aborted, or cancelled. Replay can also split one live Cursor SDK run across pi `toolUse` turns for display.
-- **Cursor setting sources default to all.** The extension passes `local.settingSources: ["all"]` by default so configured Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available like they are in Cursor. To narrow loading, set a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`. To disable ambient setting sources, set `PI_CURSOR_SETTING_SOURCES=none`. Direct Cursor SDK startup logs are suppressed so setting/skill loading messages do not pollute the TUI.
+- **Cursor setting sources default to all.** The extension passes `local.settingSources: ["all"]` by default so configured Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available like they are in Cursor. To narrow loading, set a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`. To disable ambient setting sources, set `PI_CURSOR_SETTING_SOURCES=none`. Direct Cursor SDK bootstrap logs (settings, skills, hook-load compatibility warnings, and similar) are suppressed so they do not pollute the TUI.
 - **Max Mode is not a manual pi variant.** Cursor's SDK may enable Max Mode automatically for models that require it. This extension only advertises exact context-window variants that the SDK catalog exposes and otherwise uses conservative SDK-derived default/non-Max context windows.
 - **Output token limits are conservative.** Cursor SDK model metadata does not currently expose output token limits directly.
 - **Token usage is approximate in pi.** Cursor SDK usage events include cumulative internal agent/tool/cache work, so raw Cursor SDK counters are not copied into pi usage. The extension reports approximate pi session activity in `input`/`output`, including split-run tool calls and consumed tool results, while `totalTokens` tracks the replayable Cursor prompt/context estimate used for context display and compaction.

package/docs/cursor-live-smoke-checklist.md

@@ -22,6 +22,14 @@ mkdir -p "$SMOKE_DIR"
 pi -e . --list-models cursor
 ```
 
+The repo also ships partial automation for the prerequisite/basic/default-settings/non-interactive math/TUI output polling/steering/diagnostic/JSONL subset:
+
+```bash
+npm run smoke:live
+```
+
+The script is a helper only; it polls the section 3 TUI for answer/footer evidence and then cleans up the tmux session, but it does not replace manual visual review of the full TUI checklist. Release readiness still requires the manual checks below for detailed TUI behavior, bridge, standalone native replay, abort/cancel, packaging, cleanup, and any touched runtime surface not covered by the helper.
+
 Pass criteria:
 
 - `cursor/composer-2.5` appears in the model list.
@@ -155,13 +163,25 @@ Forbidden fields:
 Run a forbidden-material scan over smoke stderr/captures:
 
 ```bash
-find "$SMOKE_DIR" -type f \( -name '*stderr.txt' -o -name 'capture*.txt' \) -print0 |
-  xargs -0 grep -E 'CURSOR_API_KEY|Bearer [A-Za-z0-9._-]+|/cursor-pi-tool-bridge/[^ ]+/mcp|127\.0\.0\.1:[0-9]+/cursor-pi-tool-bridge|apiKey|cookie|session-cookie|secret-token'
+forbidden_files="$(find "$SMOKE_DIR" -type f \( -name '*stderr.txt' -o -name '*capture*.txt' \) -print0 |
+  xargs -0 grep -IlE 'CURSOR_API_KEY|Bearer [A-Za-z0-9._-]+|/cursor-pi-tool-bridge/[^ ]+/mcp|127\.0\.0\.1:[0-9]+/cursor-pi-tool-bridge|apiKey|cookie|session-cookie|secret-token' || true)"
+if [[ -n "$forbidden_files" ]]; then
+  printf 'Forbidden material matched in smoke files; inspect locally without pasting matched lines.\n' >&2
+  while IFS= read -r file; do
+    [[ -z "$file" ]] && continue
+    if [[ "$file" == "$SMOKE_DIR/"* ]]; then
+      printf '  %s\n' "${file#"$SMOKE_DIR/"}" >&2
+    else
+      printf '  %s\n' "$file" >&2
+    fi
+  done <<<"$forbidden_files"
+  exit 1
+fi
 ```
 
 Pass criteria:
 
-- The grep returns no matches except deliberately planted test strings that are asserted not to appear in serialized diagnostics.
+- The scan returns no matching files except deliberately planted test strings that are asserted not to appear in serialized diagnostics, and it does not print matched secret-bearing lines.
 - If tool names themselves are considered sensitive for a release target, do not enable `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` for shared logs. The diagnostics contract intentionally allows tool names.
 
 ## 7. Long-running bridge and abort/cancel
@@ -190,45 +210,21 @@ Pass criteria:
 After all live runs, scan JSONL structurally instead of reading raw content into a report:
 
 ```bash
-node <<'NODE'
-const fs = require('fs');
-const path = require('path');
-const root = process.env.SMOKE_DIR;
-const files = [];
-function walk(dir) {
-  for (const name of fs.readdirSync(dir)) {
-    const p = path.join(dir, name);
-    const st = fs.statSync(p);
-    if (st.isDirectory()) walk(p);
-    else if (p.endsWith('.jsonl')) files.push(p);
-  }
-}
-walk(root);
-let failures = 0;
-for (const file of files.sort()) {
-  const records = fs.readFileSync(file, 'utf8').trim().split(/\n+/).filter(Boolean).map(JSON.parse);
-  const messages = records.filter((record) => record.type === 'message').map((record) => record.message);
-  const assistants = messages.filter((message) => message.role === 'assistant');
-  const usage = assistants.map((message) => message.usage).filter(Boolean);
-  const badUsage = usage.filter((u) =>
-    typeof u.input !== 'number' || u.input < 0 ||
-    typeof u.output !== 'number' || u.output < 0 ||
-    typeof u.totalTokens !== 'number' || u.totalTokens < 0 ||
-    u.cacheRead !== 0 || u.cacheWrite !== 0
-  );
-  if (usage.length !== assistants.length || badUsage.length > 0) failures += 1;
-  console.log(JSON.stringify({ file: path.relative(root, file), assistantCount: assistants.length, usageCount: usage.length, badUsageCount: badUsage.length }));
-}
-process.exit(failures === 0 ? 0 : 1);
-NODE
+node scripts/validate-smoke-jsonl.mjs "$SMOKE_DIR"
 ```
 
-Pass criteria:
+Script-enforced pass criteria:
+
+- Every scanned JSONL file is parseable and non-empty.
+- Every scanned JSONL file contains at least one assistant message.
+- Every assistant message has usage metadata.
+- Assistant usage `input`, `output`, and `totalTokens` are non-negative numbers.
+- Assistant usage `cacheRead` and `cacheWrite` are exactly `0`.
+
+Additional manual usage checks for provider/accounting changes:
 
-- Every assistant message has valid usage.
-- Cache fields remain `0`.
-- Tool-heavy runs show nonzero output for visible assistant/tool-call activity.
-- Split runs count consumed tool-result input once on the following assistant turn.
+- Tool-heavy runs should show nonzero output for visible assistant/tool-call activity.
+- Split runs should count consumed tool-result input once on the following assistant turn.
 
 ## 9. Standard local gates
 

package/docs/cursor-model-ux-spec.md

@@ -16,7 +16,7 @@ Current implementation notes:
 - Image payload forwarding sends images only from the latest user message. If the latest user turn is plain text after an earlier image turn, the transcript keeps an `[image omitted from transcript]` placeholder but no image bytes are sent to Cursor. The prompt explicitly tells Cursor that prior image bytes are unavailable and to ask the user to reattach or describe a prior image when needed. Carrying images forward across turns remains a future product decision because it affects token cost, privacy, stale visual context, and expected multimodal follow-up behavior.
 - `@cursor/sdk` is a package dependency of this extension; users should not need a global SDK install.
 - Cursor auth uses pi-native API-key resolution for provider `cursor`: CLI `--api-key`, stored `~/.pi/agent/auth.json` API key from `/login`, then `CURSOR_API_KEY`. The extension config file stores only non-secret Cursor-only state such as fast defaults.
-- Local agents pass `settingSources: ["all"]` by default so Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available. Users can narrow loading with a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`, or disable ambient setting sources with `PI_CURSOR_SETTING_SOURCES=none`. The provider suppresses direct Cursor SDK startup writes around agent creation so setting/skill loading logs do not pollute pi's TUI.
+- Local agents pass `settingSources: ["all"]` by default so Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available. Users can narrow loading with a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`, or disable ambient setting sources with `PI_CURSOR_SETTING_SOURCES=none`. The provider suppresses direct Cursor SDK bootstrap stdout/stderr/console noise (including late first-send workspace loading such as hook compatibility warnings) so it does not pollute pi's TUI.
 - Cursor SDK models are treated as thinking-capable even when pi reports `thinking=no`; that pi column only means the SDK did not expose a pi-controllable thinking parameter for that model.
 - Cursor-side thinking remains visible through pi's native thinking rendering when the Cursor SDK emits thinking or summary deltas.
 - Local Cursor agents get two tool surfaces. First, Cursor keeps the Cursor SDK local-agent tool surface plus configured Cursor settings, plugins, and Cursor MCP servers. Second, pi-cursor-sdk exposes active pi tools through a default-on, tokenized loopback MCP bridge when bridgeable tools exist.
@@ -27,7 +27,7 @@ Current implementation notes:
 - Cursor SDK MCP tool calls use a guarded timeout override because installed `@cursor/sdk` 1.0.13 has a 60-second MCP request default with no public per-server timeout option. The extension extends that Cursor SDK MCP `callTool` timeout path to 3600 seconds by default. Users can override it with `PI_CURSOR_MCP_TOOL_TIMEOUT_MS` or `PI_CURSOR_MCP_TOOL_TIMEOUT_SECONDS`.
 - Bridge diagnostics are opt-in only: `PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1` writes typed, allowlisted, scrubbed single-line JSONL records to `process.stderr` with prefix `[pi-cursor-sdk:bridge]`. Diagnostics are scrubbed operational logs, not anonymous telemetry. They intentionally include tool names, safe correlation IDs, run lifecycle, exposed pi↔MCP name pairs, queued requests, result resolution, rejection, cancellation, and pending counts. Correlation IDs are generated independently from the tokenized endpoint path, and Cursor MCP call IDs are hashed before serialization. Diagnostics must not include endpoint paths/URLs/path components/tokens, API keys, bearer tokens, cookies, session credentials, raw args/results, stdout/stderr payloads, file contents, Cursor settings output, or local private session paths in tracked docs, and they must not call pi UI status, notification, or footer APIs. If tool names themselves are unacceptable for a release target, bridge debug diagnostics are not safe for shared logs under the current contract.
 - This repo does not provide a generic desktop-automation, browser-driver, or CDP recipe. Provider docs should describe pi-cursor-sdk's Cursor provider/bridge contract only.
-- Cursor internal tool activity is recorded from SDK events and scrubbed. In interactive TTY sessions, supported completed `read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`, diagnostics, delete, todo/plan, task, image generation, and MCP activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so the TUI can show native-looking cards without rerunning Cursor's reads/shell commands/file edits. Cursor `glob` activity is replayed through native `find` cards. Cursor write activity is replayed through native-looking `write` cards, and Cursor StrReplace/edit activity uses native-looking `edit` only when recorded arguments truthfully satisfy pi's `edit` schema; path-only Cursor edit and notebook edit replay falls back to neutral Cursor activity before pi validation. Diagnostics, delete, todos/plans, task, image, and MCP activity use neutral Cursor activity cards with pi's default success/error shell. Neutral Cursor activity calls include `activityTitle` and, when available, `activitySummary` so partial/collapsed cards preserve identity such as `Cursor plan`, `Cursor todos`, `Cursor MCP`, or `Cursor edit`. Replay-only tools display recorded Cursor results, normalize workspace-local paths/diff headers for display, use pi diff colors for edit previews and path-inferred syntax highlighting for write previews, and fail closed if called without a recorded result. Native replay wrappers are registered only for tool names not already owned by another extension; conflicting tools use the bounded scrubbed transcript fallback. Cursor workflow tools such as `SwitchMode` and Cursor todo state are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards can be followed by Cursor's final plan text, selected from `run.wait().result` when Cursor provides one and trimmed against already-emitted text. Started Cursor SDK tool calls that never receive a completion event are discarded without synthetic replay errors; explicit failures remain visible when Cursor reports them through completed tool calls or step results. `PI_CURSOR_NATIVE_TOOL_DISPLAY=0` disables native replay, and `PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is a registration-only opt-out that keeps the transcript fallback without shadowing pi tool names. When bridge or native replay cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK activity arrives: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later tool batches as further `toolUse` turns, then Cursor's final assistant answer. For shell replay, completed `stdout` / `stderr` are primary; unambiguous `shell-output-delta` data is used only as display-only fallback for empty successful shell completions, and overlapping shell calls drop ambiguous deltas instead of guessing. Non-interactive runs keep bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when no live-run turn split is active.
+- Cursor internal tool activity is recorded from SDK events and scrubbed. In interactive TTY sessions, supported completed `read`, `bash`, `grep`, `find`, `ls`, `edit`, `write`, diagnostics, delete, todo/plan, task, image generation, and MCP activity is replayed through pi's native tool-call rendering path with recorded Cursor results, so the TUI can show native-looking cards without rerunning Cursor's reads/shell commands/file edits. Cursor `glob` activity is replayed through native `find` cards. Cursor write activity is replayed through native-looking `write` cards, and Cursor StrReplace/edit activity uses native-looking `edit` only when recorded arguments truthfully satisfy pi's `edit` schema; path-only Cursor edit and notebook edit replay falls back to neutral Cursor activity before pi validation. Diagnostics, delete, todos/plans, task, image, and MCP activity use neutral Cursor activity cards with pi's default success/error shell. Neutral Cursor activity calls include `activityTitle` and, when available, `activitySummary` so partial/collapsed cards preserve identity such as `Cursor plan`, `Cursor todos`, `Cursor MCP`, or `Cursor edit`. When the Cursor SDK emits a running `task` tool call with a description, the provider surfaces one low-noise in-progress line such as `Cursor task: Explore AI/automation projects` from SDK args only; it does not emit generic heartbeat text or per-tool start cards for ordinary `read`, `bash`, or `grep` activity. Replay-only tools display recorded Cursor results, normalize workspace-local paths/diff headers for display, use pi diff colors for edit previews and path-inferred syntax highlighting for write previews, and fail closed if called without a recorded result. Native replay wrappers are registered only for tool names not already owned by another extension; conflicting tools use the bounded scrubbed transcript fallback. Cursor workflow tools such as `SwitchMode` and Cursor todo state are not pi workflow controls; reported todo/plan events are displayed as Cursor activity only. Plan/todo replay cards can be followed by Cursor's final plan text, selected from `run.wait().result` when Cursor provides one and trimmed against already-emitted text. Started Cursor SDK tool calls that never receive a completion event are discarded without synthetic replay errors; explicit failures remain visible when Cursor reports them through completed tool calls or step results. `PI_CURSOR_NATIVE_TOOL_DISPLAY=0` disables native replay, and `PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is a registration-only opt-out that keeps the transcript fallback without shadowing pi tool names. When bridge or native replay cards are emitted, the provider mirrors Codex's turn shape as Cursor SDK activity arrives: assistant `toolUse`, pi `toolResult`s, live post-tool Cursor thinking/text, any later tool batches as further `toolUse` turns, then Cursor's final assistant answer. For shell replay, completed `stdout` / `stderr` are primary; unambiguous `shell-output-delta` data is used only as display-only fallback for empty successful shell completions, and overlapping shell calls drop ambiguous deltas instead of guessing. Non-interactive runs keep bounded scrubbed transcript output instead, preserving `pi -p` assistant text output. Cursor text deltas stream live when no live-run turn split is active.
 - Synthetic replay names are internal compatibility details. New model-facing prompt text and user-visible cards use native tool names when renderer-compatible, or neutral Cursor activity labels when not. Legacy sessions containing old internal replay names are sanitized before prompt/display. Bridge MCP names such as `pi__sem_reindex` are MCP-only; pi session output uses real pi tool names.
 - Cursor SDK usage events report cumulative internal agent/tool/cache work, not the replayable pi prompt context. The extension does not copy raw Cursor SDK usage into pi usage or compaction. For Cursor assistant messages, `usage.input`/`usage.output` are approximate pi session activity components: initial Cursor prompt input is counted once, consumed split-run tool results are counted as deduped input on the following assistant turn, and assistant output includes visible text/thinking/tool-call content. `usage.totalTokens` is the replayable Cursor prompt/context estimate derived from the same `buildCursorPrompt()` path used for `Agent.send`; it may differ from `input + output` and is the context-safe value for display/compaction. `src/cursor-usage-accounting.ts` owns this usage policy, and `src/cursor-live-run-accounting.ts` owns prompt-once and consumed-tool-result accounting so provider usage and bridge result resolution share the same matched tool-result boundary.
 - Audit observation, 2026-05-19, superseded by the 2026-05-21 replay pass: a missing-file read with Composer 2.5 emitted `tool-call-started` for Cursor `read`, then streamed final text `Error: File not found`, but did not emit `tool-call-completed` or an `onStep` `toolCall` error result. Leftover started calls are now discarded at run completion instead of becoming synthetic replay errors. Cursor-reported completed/step errors remain visible.
@@ -37,6 +37,7 @@ Current implementation notes:
 - Max Mode context windows are distinct from default/non-Max context windows. `@cursor/sdk` 1.0.13 documentation says the SDK may enable Max Mode automatically when a selected model requires it, but the public local-agent `ModelSelection` path still does not expose a manual Max Mode selector. Do not advertise Max Mode context windows unless the SDK catalog exposes an exact parameter/variant or the SDK public API adds a Max Mode selector that the extension actually sends.
 - `@cursor/sdk` 1.0.13 adds latest-style `ModelListItem.aliases`. The extension registers only unambiguous aliases as pi model IDs (with the same context suffixes when applicable) and sends the alias back in `ModelSelection.id`, while sharing Cursor-only state such as fast defaults with the underlying catalog `id`. Aliases shared by multiple base models, such as generic family aliases, are skipped because the pi row metadata would otherwise imply one base model while Cursor may resolve the alias to another.
 - Session-scoped Cursor SDK agent pooling reuses one live `@cursor/sdk` agent across compatible follow-up turns within the same pi session scope. `computeCursorContextFingerprint()` and `shouldBootstrapCursorSend()` decide whether the next turn sends a full bootstrap prompt or an incremental follow-up. The pool recreates the agent when context diverges, when branch or compaction summaries appear after `/tree` navigation or compaction, when the API key identity changes, after send errors, on `session_shutdown`, and when `session_before_tree` / `session_tree` invalidate the active branch. Incremental sends omit the full Cursor SDK tool boundary block because the session agent retains prior bootstrap context.
+- Pi steering/follow-up delivery can arrive while a split live Cursor SDK run is still active. The provider resolves pending live runs by scanning trailing `toolResult` messages while skipping trailing `user` messages, tracks the active live run per session scope, and resumes the in-flight run instead of calling `Agent.send()` again. When the context ends with steering user text after tool results, the provider releases the prior live run and chains an incremental `Agent.send()` for the latest user message in the same provider turn; if the prior run emits more text or tool requests after steering arrives, that stale activity is cancelled instead of surfacing another old-run tool turn and losing the new user input. A pre-send guard waits for or resumes any still-active scoped live run before starting a fresh send so `@cursor/sdk` `AgentBusyError` (`already has active run`) does not surface to pi users.
 
 ## Goal
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.16",
+	"version": "0.1.17",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -24,6 +24,9 @@
 	"files": [
 		"src",
 		"scripts/refresh-cursor-model-snapshots.mjs",
+		"scripts/steering-rpc-smoke.mjs",
+		"scripts/tmux-live-smoke.sh",
+		"scripts/validate-smoke-jsonl.mjs",
 		"README.md",
 		"docs/cursor-model-ux-spec.md",
 		"docs/cursor-live-smoke-checklist.md",
@@ -40,7 +43,10 @@
 		"typecheck": "tsc --noEmit",
 		"test": "vitest run",
 		"test:watch": "vitest",
-		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs"
+		"refresh:cursor-snapshots": "node scripts/refresh-cursor-model-snapshots.mjs",
+		"smoke:live": "scripts/tmux-live-smoke.sh",
+		"smoke:steering": "node scripts/steering-rpc-smoke.mjs",
+		"smoke:jsonl": "node scripts/validate-smoke-jsonl.mjs"
 	},
 	"dependencies": {
 		"@cursor/sdk": "^1.0.13",
@@ -53,9 +59,9 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "^0.75.3",
-		"@earendil-works/pi-coding-agent": "^0.75.3",
-		"@earendil-works/pi-tui": "^0.75.3",
+		"@earendil-works/pi-ai": "^0.75.5",
+		"@earendil-works/pi-coding-agent": "^0.75.5",
+		"@earendil-works/pi-tui": "^0.75.5",
 		"typebox": "^1.1.38",
 		"typescript": "^6.0.3",
 		"vitest": "^4.1.6"

package/scripts/steering-rpc-smoke.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * RPC steering smoke: queue steer after a native-replay tool-use turn completes execution.
+ */
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const CHILD_SHUTDOWN_GRACE_MS = 2_000;
+
+function printHelp() {
+	console.log(`RPC steering smoke for pi-cursor-sdk live runs.
+
+Usage:
+  node scripts/steering-rpc-smoke.mjs
+
+Environment:
+  SMOKE_SESSION_DIR            Session directory for the RPC pi run. Defaults to /tmp/pi-cursor-steer-smoke-<timestamp>.
+  CURSOR_API_KEY               Required Cursor API key for live pi runs.
+
+Options:
+  -h, --help                   Show this help.
+
+Exit codes:
+  0  steering scenario completed without AgentBusyError; STEER_OK and STEER_CHAIN present
+  1  validation failure, timeout, AgentBusyError, or non-zero pi exit
+
+Notes:
+  - Runs pi in RPC mode with native tool replay enabled and the pi bridge disabled.
+  - Sends steer after the replayed bash tool finishes execution (post toolResult boundary).
+  - Prints a single JSON result line on success; errors go to stderr.`);
+}
+
+function fail(message) {
+	throw new Error(message);
+}
+
+function parseEvents(stdout) {
+	const events = [];
+	for (const line of stdout.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			events.push(JSON.parse(line));
+		} catch {
+			// ignore partial lines
+		}
+	}
+	return events;
+}
+
+function assistantText(events) {
+	return events
+		.filter((event) => event.type === "message_end" && event.message?.role === "assistant")
+		.map((event) =>
+			(event.message.content ?? [])
+				.filter((block) => block.type === "text")
+				.map((block) => block.text)
+				.join("\n"),
+		)
+		.join("\n");
+}
+
+function hasToolUseTurn(events) {
+	return events.some(
+		(event) =>
+			event.type === "message_end" &&
+			event.message?.role === "assistant" &&
+			event.message?.stopReason === "toolUse",
+	);
+}
+
+function hasToolExecutionEnd(events) {
+	return events.some((event) => event.type === "tool_execution_end");
+}
+
+function waitFor(getStdout, predicate, timeoutMs = 300_000) {
+	const start = Date.now();
+	return new Promise((resolve, reject) => {
+		const tick = () => {
+			const events = parseEvents(getStdout());
+			if (predicate(events)) {
+				resolve(events);
+				return;
+			}
+			if (Date.now() - start > timeoutMs) {
+				reject(
+					new Error(
+						`timeout after ${timeoutMs}ms\nassistantText=${assistantText(events)}\nstdoutTail=${getStdout().slice(-4000)}`,
+					),
+				);
+				return;
+			}
+			setTimeout(tick, 500);
+		};
+		tick();
+	});
+}
+
+function waitForChildClose(child) {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(child.exitCode ?? 1);
+	return new Promise((resolve) => {
+		child.once("close", (code) => resolve(code ?? 1));
+	});
+}
+
+function signalChild(child, signal) {
+	if (!child.pid) return;
+	try {
+		if (process.platform === "win32") {
+			child.kill(signal);
+		} else {
+			process.kill(-child.pid, signal);
+		}
+	} catch {
+		try {
+			child.kill(signal);
+		} catch {
+			// child already exited
+		}
+	}
+}
+
+async function terminateChild(child) {
+	child.stdin.destroy();
+	if (child.exitCode !== null || child.signalCode !== null) return;
+	signalChild(child, "SIGTERM");
+	const killTimer = setTimeout(() => signalChild(child, "SIGKILL"), CHILD_SHUTDOWN_GRACE_MS);
+	try {
+		await waitForChildClose(child);
+	} finally {
+		clearTimeout(killTimer);
+	}
+}
+
+async function runPiRpcSmoke(sessionDir) {
+	const args = ["-e", root, "--cursor-no-fast", "--model", "cursor/composer-2.5", "--mode", "rpc", "--session-dir", sessionDir];
+	const env = {
+		...process.env,
+		PI_CURSOR_SETTING_SOURCES: "none",
+		PI_CURSOR_NATIVE_TOOL_DISPLAY: "1",
+		PI_CURSOR_PI_TOOL_BRIDGE: "0",
+	};
+
+	const child = spawn("pi", args, { cwd: root, env, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
+	let closed = false;
+	let stdout = "";
+	let stderr = "";
+	child.stdout.on("data", (chunk) => {
+		stdout += chunk.toString();
+	});
+	child.stderr.on("data", (chunk) => {
+		stderr += chunk.toString();
+	});
+
+	const send = (obj) => {
+		if (!child.stdin.writable) fail("pi stdin closed before smoke command could be sent");
+		child.stdin.write(`${JSON.stringify(obj)}\n`);
+	};
+
+	try {
+		send({
+			type: "prompt",
+			message:
+				"Steering smoke. Use bash once to run: git status --short. Do not answer until after the tool completes. Final answer must include STEER_OK=yes.",
+		});
+
+		await waitFor(
+			() => stdout,
+			(events) => hasToolUseTurn(events),
+		);
+
+		await waitFor(
+			() => stdout,
+			(events) => hasToolExecutionEnd(events),
+		);
+
+		send({ type: "steer", message: "and also include STEER_CHAIN=ok in the final answer" });
+
+		await waitFor(
+			() => stdout,
+			(events) => {
+				const text = assistantText(events);
+				return text.includes("STEER_OK=yes") && text.includes("STEER_CHAIN=ok") && events.some((event) => event.type === "agent_end");
+			},
+		);
+
+		const combined = stdout + stderr;
+		if (/already has active run|AgentBusyError/i.test(combined)) {
+			fail("AgentBusyError detected in smoke output");
+		}
+
+		const text = assistantText(parseEvents(stdout));
+		if (!text.includes("STEER_OK=yes")) {
+			fail(`missing STEER_OK=yes in assistant output: ${text.slice(0, 500)}`);
+		}
+		if (!text.includes("STEER_CHAIN=ok")) {
+			fail(`missing STEER_CHAIN=ok in assistant output: ${text.slice(0, 500)}`);
+		}
+
+		child.stdin.end();
+		const exitCode = await waitForChildClose(child);
+		closed = true;
+		if (exitCode !== 0) {
+			fail(`pi exited ${exitCode}\nstderr=${stderr.slice(-2000)}`);
+		}
+
+		return {
+			ok: true,
+			sessionDir,
+			steerOk: true,
+			steerChain: true,
+		};
+	} finally {
+		if (!closed) await terminateChild(child);
+	}
+}
+
+async function main() {
+	if (process.argv.includes("-h") || process.argv.includes("--help")) {
+		printHelp();
+		return;
+	}
+
+	if (!process.env.CURSOR_API_KEY) {
+		fail("steering-rpc-smoke: CURSOR_API_KEY is required");
+	}
+
+	const sessionDir = process.env.SMOKE_SESSION_DIR ?? join("/tmp", `pi-cursor-steer-smoke-${Date.now()}`);
+	mkdirSync(sessionDir, { recursive: true });
+	console.log(JSON.stringify(await runPiRpcSmoke(sessionDir)));
+}
+
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});