pi-session-mcp 0.6.4 → 0.7.0

package/docs/threat-model.md

@@ -30,23 +30,36 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
   equality with a bounded direct MCP initialize, `tools/list`, and
   `pi_capabilities_get({})` call. It never starts a session or invokes
   a provider; the verifier cleans up its process.
-- **Concurrent setup corruption:** On an explicitly supported local Linux
-  filesystem (ext2/3/4, XFS, Btrfs, tmpfs, overlayfs, ZFS, F2FS, UBIFS, or
-  bcachefs), durable
-  ownership transactions hold a stable, never-renamed regular file through a
-  kernel `flock`. There is no clock-based stale recovery. A transaction guardian
-  inherits that locked file description, launches each mutating client command
-  in its own process group, and retains the fence across parent death until
-  `/proc` confirms that no non-zombie group member remains. Indeterminate cleanup
-  retains the fence and fails closed; missing or untrusted `flock`, unsupported
-  filesystems, symlinks, inode mismatch, and raw lock errors are reduced to
-  stable codes. Directory creation and atomic state replacement are fsynced
-  through their parent directory before success. A mutation already accepted
-  by an external CLI or configuration backend cannot be rolled back
-  automatically and remains `pending` for reconciliation.
-- **Unsupported process-group guarantees:** Setup is accepted on Linux only.
-  Every non-Linux platform fails closed before client spawn because the tested
-  kernel-fence and `/proc` process-group proof are unavailable.
+- **Concurrent setup corruption:** Durable ownership transactions hold a
+  stable, never-renamed regular file through a kernel lock on an explicitly
+  supported local filesystem:
+  - on Linux, through the trusted util-linux `flock`, on ext2/3/4, XFS, Btrfs,
+    tmpfs, overlayfs, ZFS, F2FS, UBIFS, or bcachefs;
+  - on macOS, through `O_EXLOCK` at open, on the APFS volume type of `/`.
+
+  There is no clock-based stale recovery. A transaction guardian inherits that
+  locked file description, launches each mutating client command in its own
+  process group, and retains the fence across parent death until a determinate
+  process-table scan confirms that no non-zombie group member remains. The
+  scan reads `/proc` on Linux and the trusted system `/bin/ps` on macOS; a
+  `ps` sample that fails, has an unexpected line or does not list the scanning
+  process is indeterminate. On macOS the proof rests on `/bin/ps` on the
+  sealed, SIP-protected system volume, together with the uid and mode check
+  that also guards `flock`. The macOS lock relies on the documented `O_EXLOCK`
+  behavior of open(2): flock(2) semantics on the open file description, and
+  `EOPNOTSUPP` on a filesystem without locking, which fails closed.
+  Indeterminate cleanup retains the fence and fails closed. A missing or
+  untrusted `flock` or `ps`, unsupported filesystems, symlinks, inode
+  mismatch, and raw lock errors are reduced to stable codes. Directory
+  creation and atomic state replacement are fsynced through their parent
+  directory before success. A mutation already accepted by an external CLI or
+  configuration backend cannot be rolled back automatically and remains
+  `pending` for reconciliation.
+- **Unsupported process-group guarantees:** Setup runs on Linux and macOS
+  only. Every other platform fails closed before client spawn because no
+  tested kernel fence and process-group proof exist for it. On both supported
+  platforms, the fence does not cover descendants that leave the process
+  group, and it does not promise PID reaping.
 
 - **Workspace escape:** callers can request configured workspace aliases only; validated configuration maps aliases to resolved paths. There is no arbitrary `cwd` input.
 - **Execution-selection escalation:** callers cannot supply raw provider, model, thinking level, permission profile, or credentials. A configured execution-profile alias binds all of those values; exactly one configured default is `read-only`. The legacy `profile` input is rejected rather than silently reinterpreted.
@@ -55,12 +68,19 @@ Pi Session MCP trusts the local process that launches and speaks MCP over inheri
 - **Thinking-level clamping:** SDK capability handling can alter a requested level. The adapter compares the effective `session.thinkingLevel` after creation and disposes on a mismatch.
 - **Orphaned SDK session:** a post-creation mismatch or later registry failure could otherwise leave a live Pi handle. The adapter holds it locally until all postconditions pass, best-effort disposes on each later failure, and the registry admits only verified handles.
 - **Excess capability:** the execution profile selects a permission-derived tool allowlist. Read-only permits only `read`, `grep`, `find`, and `ls`; coding remains high impact.
-- **Project resource code execution:** Pi resource loading disables extensions, skills, prompts, and themes. Non-executable `AGENTS.md` context remains untrusted instruction content, never authorization.
+- **Project resource code execution:** Pi resource loading disables extension discovery, skills, prompts, and themes; only a profile's allowlisted extensions load (see below). Non-executable `AGENTS.md` context remains untrusted instruction content, never authorization.
 - **Concurrent state corruption:** a per-session queue serializes prompt admission and close; concurrent abort callers share one attempt for the active turn. Closing is terminal, settles an active turn, and disposes once.
 - **Secret/prompt disclosure:** stdout is protocol-only. Stderr diagnostics use stable code and safe context only. Public metadata is whitelisted and omits auth objects/sources, credential paths, headers, base URLs, complete model objects, SDK IDs, raw provider errors, prompts, transcripts, and tool data. Completed `assistantText` can still repeat model-visible data and is potentially sensitive.
 - **Capability-enumeration disclosure:** the trusted local MCP peer can read configured workspace aliases and execution-profile provider/model intent. Discovery omits workspace paths, authentication state, SDK state, sessions, turns, prompts, transcripts, and tool data. Operators must choose aliases that are suitable for this trusted-peer boundary.
 - **Stale capability assumptions:** discovery reads configuration only. It makes no provider, authentication, filesystem, or network probe and cannot prove that a configured provider/model is available. Session creation keeps the existing exact runtime checks.
 - **Availability:** input length is bounded; profile-specific authentication/catalog work and session creation have 5,000 ms and 10,000 ms deadlines. Preflight, abort, close cleanup, registry shutdown, and process shutdown (signal or stdin EOF) have 5,000 ms, 5,000 ms, 5,000 ms, 12,000 ms, and 15,000 ms server-side deadlines. Active sessions retain 20 turns and 64 KiB UTF-8 of final text per turn. The registry rejects starts after shutdown begins and disposes a late-created handle. The process shutdown path explicitly exits the process after its cleanup deadline, but cannot prove graceful termination of a blocked provider operation.
+- **Allowlisted Pi extensions:** a profile's `extensions` load operator-trusted code into the server process with the user's full rights; it may start processes, use the network and write files (for example `pi-cursor-sdk` below `~/.pi/agent`, `~/.cursor/projects/` and `<workspace>/.pi/`). Mitigations:
+  - Only exact `npm:<name>@<version>` specs from the operator's configuration load; the MCP client cannot name an extension.
+  - Resolution never installs, and a different installed version fails closed. Only Pi's own user install (`<Pi agent dir>/npm/node_modules/<name>`, normally below `~/.pi/agent`) counts; a package installed elsewhere, for example with `npm i -g`, is reported as not installed.
+  - `read-only` profiles never activate extension tools. At session start, after load and again after binding, no extension tool may shadow a built-in or granted tool; later registrations are covered in the residual risks.
+  - Client prompts never dispatch extension commands, but extension input hooks can still see, rewrite or consume a prompt.
+  - Each extension session gets its own model runtime, and close emits `session_shutdown`.
+- **stdout corruption:** every write through `process.stdout` or `console.log`, `console.info` and `console.debug` other than the MCP transport's is dropped. The stdout guard intercepts `process.stdout.write`, `process.stdout.end` and `console.log`, `console.info` and `console.debug`, which covers output from extensions and the SDK in the server process. stderr gets only `foreign_stdout_suppressed` with byte and write counts, never the content. Anything that writes file descriptor 1 directly is not covered; see the residual risks.
 - **Misleading annotations:** annotations are client hints only and never grant access.
 - **Shutdown orphaning:** `SIGINT`, `SIGTERM`, and stdin EOF invoke the same bounded registry cleanup and transport close, so a client that only closes stdin does not leave sessions or their MCP children running. Handles are disposed at most once; late promises are ignored after removal. Explicit process exit prevents local shutdown from hanging indefinitely, but SDK limitations can leave external work unconfirmed or abruptly cut off.
 
@@ -87,3 +107,19 @@ change public terminal errors; cancellation and close still take precedence.
 Aliases and profile definitions are trusted administrator configuration, not a filesystem or provider-security sandbox. A locally available model may later be unreachable; no live provider request is made during selection. Symlinks and Pi tools can reach resources permitted to the OS identity. `AGENTS.md` can influence model behavior. The number of active sessions and the duration of an already accepted turn remain unbounded. Stdio peer authentication, quotas, persistent recovery, provider hard-kill capability, dependency integrity policy, and OS/filesystem isolation remain outside the verified boundary. Coding-profile acceptance checks behavior in a selected fixture; it does not prove OS-level isolation.
 The trusted same-UID operator can unlink or replace the setup lock path between
 checks and must not mutate the ownership directory during a transaction.
+
+An allowlisted extension is trusted code; pinning its version does not detect
+modification of the installed package directory. `read-only` limits the
+model's tools, not extension code or hooks. Anything that writes file
+descriptor 1 directly reaches the MCP stream, because Node.js cannot intercept
+it: in-process writes such as `fs.writeSync(1, …)` or native code, and child
+processes that an extension starts with inherited stdio. The Cursor runtime
+behind `pi-cursor-sdk` starts processes of its own during turns (observed with
+`pi-cursor-sdk@0.5.3`: `git`, `ssh`, `gh` and the MCP servers configured for
+Cursor, in a `read-only` profile too); none inherited the server's stdout in
+that run. Extensions may persist their own state outside Pi
+Session MCP's in-memory boundary. Extension tool names are checked for
+conflicts after loading and again after binding; a tool that an extension
+registers later, during a turn, is not re-checked and may replace a built-in
+tool, `read` included, because allowlisted extensions are trusted code. An extension may deactivate built-in or granted
+tools for its own session.

package/docs/tool-contracts.md

@@ -22,7 +22,7 @@ There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inv
 ```json
 {
   "ok": true,
-  "server": { "name": "pi-session-mcp", "version": "0.6.4" },
+  "server": { "name": "pi-session-mcp", "version": "0.7.0" },
   "configuration": {
     "fingerprint": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
     "reloadPolicy": "restart-required"
@@ -34,12 +34,13 @@ There are exactly eight tools. No `pi_turn_wait` tool or live provider/model inv
     "permissionProfile": "read-only",
     "provider": "configured-provider",
     "model": "configured-model",
-    "thinkingLevel": "medium"
+    "thinkingLevel": "medium",
+    "extensions": []
   }]
 }
 ```
 
-The server sorts both arrays by alias with a deterministic code-point comparison. It copies only loaded configuration fingerprint/reload policy, configured aliases, and the six documented profile fields. It never copies the configuration path or contents, workspace paths, authentication state, SDK data, session/turn data, prompts, transcripts, or tool arguments/results. The handler reads the in-memory loaded snapshot only and does not call the registry, Pi adapter, provider, filesystem, or network. The fingerprint identifies the exact loaded bytes, not current-file freshness; provider/model fields describe configured intent and make no availability claim.
+The server sorts both arrays by alias with a deterministic code-point comparison. It copies only loaded configuration fingerprint/reload policy, configured aliases, and the seven documented profile fields. `extensions` lists the configured extension specs (`npm:<name>@<version>`), empty when a profile loads none; it makes no claim that the package is installed. It never copies the configuration path or contents, workspace paths, authentication state, SDK data, session/turn data, prompts, transcripts, or tool arguments/results. The handler reads the in-memory loaded snapshot only and does not call the registry, Pi adapter, provider, filesystem, or network. The fingerprint identifies the exact loaded bytes, not current-file freshness; provider/model fields describe configured intent and make no availability claim.
 
 Annotations are `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, and `openWorldHint: false`. Clients may use them for presentation, but the strict input schema and server-owned projection enforce the contract.
 
@@ -67,6 +68,10 @@ Public MCP errors are stable and sanitized. Their messages do not include inputs
 | `external_mcp_no_tools` | Complete valid discovery returned no tools while explicit grants were required. |
 | `external_mcp_grant_tool_missing` | Complete valid nonempty discovery omitted an explicitly granted remote tool. |
 | `external_mcp_activation_mismatch` | Pi did not activate exactly the expected post-discovery tool set. |
+| `extension_not_installed` | Pi has no installed package for a configured extension. |
+| `extension_version_mismatch` | Pi's installed extension package has another version than the configured one. |
+| `extension_load_failed` | A configured extension has an invalid manifest, failed to load or failed to bind. |
+| `extension_tool_conflict` | An extension tool name collides with a built-in, MCP or other extension tool. |
 | `pi_session_creation_failed` | Pi session construction failed without a more specific safe classification. |
 | `server_stopping` | Shutdown has begun, so a new session cannot be admitted. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-mcp",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Local stdio MCP server for controlled Pi coding-agent sessions",
   "license": "MIT",
   "keywords": [