@rahularya01/pi-cursor 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [1.3.1] - 2026-07-25
+
+### Fixed
+
+- **Tool continuation was unrecoverable after the first tool round.** Losing the upstream bridge mid-tool failed with `Cursor tool continuation was lost … skipReason=pending_tool_call_mismatch` on every round after the first. The mid-pause snapshot records only the round that was parked, but the client re-sends every tool result in the in-flight user turn, and recovery demanded the two sets be equal. The parked set must instead be _covered by_ what arrived; the in-flight turn is still matched exactly, which is what pins the replayed transcript to the client's view.
+- **Parallel tool calls beyond the first never reached the client.** Cursor can frame several execs in one chunk, but the response was closed on the first, so the rest were silently dropped and only re-offered if the bridge happened to survive. The pause is now deferred to the end of the chunk. Only execs the client was actually told about are recorded as pending, since recovery can only expect back what the client saw.
+- **Checkpoints delivered during a tool pause were discarded.** The latest checkpoint was held in per-round state while the bridge outlived the round, so anything arriving mid-pause was stranded in the previous round's closure — a recurring cause of `hadStoredCheckpoint=false` diagnostics. It now lives on the bridge.
+- **An oversized or unsupported image broke every later turn.** The whole history is re-parsed on each request and an image failing Cursor's 5 MiB / format check threw, so one bad screenshot — typically from a tool result — permanently failed the conversation. Images already in the transcript are now decoded leniently; the message being sent still errors, since that one the caller can fix.
+- **An undecodable checkpoint was never discarded**, failing every subsequent turn in the conversation. It is now decoded once during staleness validation and dropped on failure, degrading to a rebuild.
+- **The most load-bearing blob was first to be evicted.** `trimBlobStore` drops oldest-first, but merging used `Map.set`, which leaves an existing key at its original position — so the system-prompt blob, written first on every build and referenced by every checkpoint, was permanently the oldest entry. Merging now re-inserts, making eviction genuinely least-recently-referenced.
+- **Tool-result images were dropped on checkpoint recovery**, though the full-history rebuild path preserved them.
+- Tool results with no `tool_call_id` are excluded from recovery's set matching instead of reading as duplicates and failing an otherwise sound recovery.
+- A live bridge is no longer resumed when the request's history does not match the one it was parked on. Without a Pi session id the bridge key is only a hash of the opening user message, so two conversations that start alike shared a key.
+
+## [1.3.0] - 2026-07-24
+
+### Added
+
+- **Wire-drift detection.** Unrecognized `agent.v1` server messages and unknown protobuf fields are no longer skipped silently. They are counted, written to the lifecycle log as `wire_drift`, appended to the failing turn's error message, and listed by `/cursor.doctor` (`lastDriftSignal`, `wireDrift`, `wireDriftStranding` plus a detail block). `wireDriftStranding=yes` distinguishes an unanswered message that could have parked the turn from a merely out-of-date schema — previously both surfaced as a bare idle timeout.
+- **Reproducible protobuf codegen.** `proto/agent.proto` is now vendored as the source of truth for `src/proto/agent_pb.ts`, with `npm run proto:gen` (regenerate), `npm run proto:sync` (recover the `.proto` from an updated generated file — protoc-gen-es embeds the full descriptor), and `npm run proto:check` (fails the build when the two drift apart, and is part of `npm run check`). Uses `buf` + `protoc-gen-es` from devDependencies, so no system `protoc` is required. See [`proto/README.md`](proto/README.md).
+- `npm run smoke:wire` performs the real Connect/HTTP2 handshake against the configured endpoint and reports schema drift without starting a chat turn.
+
+### Changed
+
+- **`src/stream/native-core.ts` split into focused modules** (5,696 → ~1,650 lines): `types`, `tuning`, `debug-log`, `images`, `model-discovery`, `message-parsing`, `pi-adapter`, `request-build`, `bridge-session`, `session-state`, `server-messages`, `thinking-filter`, and `drift`. The public surface of `src/stream/index.ts` is unchanged.
+- `native-core.ts` is now covered by ESLint and Prettier (it was previously exempted for being too large), which removed a large amount of dead code and unused imports.
+- Shared structural types are declared once in `src/stream/types.ts`; `recovery.ts` and `native-core.ts` previously carried duplicate copies of `ParsedTurn`, `StoredConversation`, and friends.
+
+### Removed
+
+- **The quarantined OpenAI-compatible local proxy.** `startProxy`/`stopProxy` and the entire parallel request path (`handleChatCompletion`, `writeSSEStream`, `handleToolResultResume`, `handleNonStreamingResponse`, and helpers) are gone — roughly 1,250 lines that were unreachable from the provider. Native `streamSimple` was already the only chat path; `/cursor.doctor` now reports `proxyPath=removed`.
+
 ## [1.2.3] - 2026-07-24
 
 ### Fixed

package/README.md

@@ -163,23 +163,40 @@ Pi Coding Agent  →  streamSimple (cursor-native)
 
 Stream modules are split under `src/stream/`:
 
-| Module                 | Responsibility                                      |
-| ---------------------- | --------------------------------------------------- |
-| `config.ts`            | Agent URL + client version resolution               |
-| `model-routing.ts`     | Effort suffix / requested model resolution          |
-| `context-normalize.ts` | Context-mode side-channel folding                   |
-| `recovery.ts`          | Tool-continuation recovery planner                  |
-| `protocol.ts`          | Auth/protocol error enhancement                     |
-| `native-core.ts`       | Native streamSimple runtime + (internal) proxy path |
-
-The OpenAI-compatible local proxy remains **internal/quarantined** (not exported from `src/stream/index.ts`). Day-to-day chat uses native `streamSimple` only.
-
-`src/proto/agent_pb.ts` is a large generated Connect/protobuf surface used by the wire layer. Prefer regenerating it from upstream protos when Cursor changes the agent schema rather than hand-editing.
+| Module                 | Responsibility                                                        |
+| ---------------------- | --------------------------------------------------------------------- |
+| `types.ts`             | Shared structural types (no runtime code — safe for anyone to import) |
+| `config.ts`            | Agent URL + client version resolution                                 |
+| `tuning.ts`            | Timeouts, retry budgets, and the stream idle watchdog                 |
+| `debug-log.ts`         | Debug / lifecycle / metric sinks with secret redaction                |
+| `images.ts`            | Image decode + Cursor CLI format and size validation                  |
+| `model-routing.ts`     | Effort suffix / requested model resolution                            |
+| `model-discovery.ts`   | `GetUsableModels` unary RPCs + per-token model cache                  |
+| `context-normalize.ts` | Context-mode side-channel folding                                     |
+| `message-parsing.ts`   | Pi/OpenAI message list → Cursor turn structures                       |
+| `pi-adapter.ts`        | Pi context/model types ↔ OpenAI-shaped request, usage accounting      |
+| `request-build.ts`     | `AgentRunRequest` protobuf construction + blob store                  |
+| `bridge-session.ts`    | Active-bridge registry + h2-bridge lifecycle                          |
+| `session-state.ts`     | Conversation store, checkpoints, key derivation, session locks        |
+| `server-messages.ts`   | Inbound KV / exec / interaction dispatch                              |
+| `thinking-filter.ts`   | Strips inline `<think>`-style tags from the text channel              |
+| `recovery.ts`          | Tool-continuation recovery planner                                    |
+| `protocol.ts`          | Auth/protocol error enhancement                                       |
+| `drift.ts`             | Wire-drift detection (unknown message cases and protobuf fields)      |
+| `native-core.ts`       | Native streamSimple runtime that drives all of the above              |
+
+Native `streamSimple` is the only chat path. The OpenAI-compatible local proxy that
+used to sit alongside it was removed in favour of a single code path.
+
+`src/proto/agent_pb.ts` is a large generated Connect/protobuf surface used by the wire
+layer. Never hand-edit it — regenerate with `npm run proto:gen` (see
+[`proto/README.md`](proto/README.md)) when Cursor changes the agent schema.
 
 ## Troubleshooting
 
 - **Not logged in / 401:** Ensure Cursor CLI or app is logged in, or run `/login cursor` again. Check `/cursor.doctor` to verify your `tokenSource`. Tokens from CLI/IDE are re-resolved when near expiry; idle stream retries also force-refresh credentials.
 - **Empty / hung stream:** Cursor may have updated wire headers; verify network connectivity or bump `PI_CURSOR_CLIENT_VERSION`. `/cursor.doctor` prints the active `clientVersion`.
+- **Wire-protocol drift:** Cursor can change `agent.v1` at any time. Unrecognized server messages and unknown protobuf fields are no longer skipped silently — they are counted, written to the lifecycle log as `wire_drift`, appended to the failing turn's error message, and listed by `/cursor.doctor` under `wireDrift`. `wireDriftStranding=yes` means an unanswered message could have parked the turn, which is the difference between "our schema is a bit behind" and "this is why it hung". Run `CURSOR_ACCESS_TOKEN=... npm run smoke:wire` to check the handshake and schema against the live endpoint without starting a chat turn, then see [`proto/README.md`](proto/README.md) to resync the schema.
 - **Stuck / dies after a few minutes of work:** v1.2.2 answers all Cursor `InteractionQuery` permission prompts (web search / ask-question / etc.) that previously parked the stream. Inspect `$TMPDIR/pi-cursor-lifecycle.jsonl` for `interaction_query` / `bridge_close` events, and `/cursor.doctor` for `lastStreamEvent`. Full debug: `PI_CURSOR_PROVIDER_DEBUG=1`.
 - **Tool continuation lost:** The provider now prefers full-history rebuild when checkpoints are stale/mismatched. If recovery still skips, `/cursor.doctor` shows `lastRecoverySkipReason`. Retry the turn or start a new chat.
 - **WSL credential detection:** Ensure your Windows user profile folder exists under `/mnt/c/Users/` and is readable from WSL. Disable with `PI_CURSOR_SYSTEM_CREDENTIALS=0` if undesired.
@@ -191,7 +208,13 @@ npm install
 npm run check
 ```
 
-`npm run check` runs TypeScript typechecking, ESLint, Prettier format verification, security checks, and unit tests.
+`npm run check` runs TypeScript typechecking, ESLint, Prettier format verification, security checks, the protobuf staleness check, and unit tests.
+
+| Script                | Purpose                                                                           |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `npm run proto:gen`   | Regenerate `src/proto/agent_pb.ts` from `proto/agent.proto`.                      |
+| `npm run proto:sync`  | Rebuild `proto/agent.proto` from an updated generated file obtained upstream.     |
+| `npm run proto:check` | Fail if the generated protobuf is stale or hand-edited (part of `npm run check`). |
 
 ## Attributions