pi-session-mcp 0.7.0 → 0.8.0

package/docs/pi-extensions-design.md

@@ -3,6 +3,14 @@
 Status: approved by the owner on 2026-10-11 for implementation. Tracking issue:
 [#34](https://github.com/plagor44-ux/pi-session-mcp/issues/34).
 
+> **Amended by [ADR 0007](adr/0007-profile-skill-selection.md).** This design
+> assumed that `noSkills` and the other `no*` options keep skills, prompt
+> templates and themes out of every session. With Pi SDK 1.1.0 that did not hold
+> for resources that an allowlisted extension package ships. An extension
+> allowlist now makes none of them available; a skill reaches a session only
+> through the operator's `skillCatalog` and the profile's `skills`. See
+> [Pi skills](skills.md).
+
 ## Goal
 
 An operator can allowlist Pi extensions per execution profile. A profile that
@@ -53,8 +61,10 @@ Success means:
 `DefaultResourceLoader` with `noExtensions: true`, no skills, templates or
 themes, and a disabled system prompt. `SdkPiSessionAdapter.create` resolves
 provider, model, authentication and availability against one `ModelRuntime`
-shared by all sessions, and only then builds the resource loader and calls
-`createAgentSession`.
+shared by the sessions of profiles without extensions (a profile with
+`extensions` gets a runtime of its own, see *Session creation*), and only then
+builds the resource loader and calls `createAgentSession`. This describes the
+state before this feature; ADR 0007 later added the skill selection.
 
 Facts about Pi SDK 1.1.0 that shape this design, verified against the
 installed package:
@@ -85,8 +95,11 @@ installed package:
    mismatched npm packages, and `getInstalledPath(source, "user")` falls back
    to a synchronous `npm root -g` on a miss and accepts legacy global
    installs; neither is side-effect free.
-9. `pi-cursor-sdk` and `@cursor/sdk` call `console.log`. In a stdio MCP server
-   such output corrupts the protocol stream.
+9. Skills, prompt templates and themes that an allowlisted extension package
+   ships reached the session although `noSkills` was set (ADR 0007).
+   `loadSkills` removes duplicate skill names before `skillsOverride` runs.
+10. `pi-cursor-sdk` and `@cursor/sdk` call `console.log`. In a stdio MCP server
+    such output corrupts the protocol stream.
 
 The relevant SDK functions are root exports of
 `@earendil-works/pi-coding-agent`: `createAgentSessionServices`,
@@ -115,8 +128,12 @@ Rules, enforced by `configSchema`:
 
 - Each entry matches `npm:<name>@<version>`. `<name>` is an npm package name,
   optionally scoped (`@scope/name`), lowercase. `<version>` is an exact semver
-  version with optional prerelease and build metadata. Ranges, tags, `git:`,
-  paths and URLs are rejected.
+  version with an optional prerelease. Build metadata (`+build`) is rejected
+  because npm does not keep it in a published version, so such a pin could
+  never match the installed manifest; the configuration fails with
+  `config_invalid` instead of every session failing with
+  `extension_version_mismatch`. Ranges, tags, `git:`, paths and URLs are
+  rejected.
 - At most 8 entries per profile. A package name appears at most once per
   profile.
 - The field is allowed on `read-only` and `coding` profiles, including the
@@ -210,9 +227,17 @@ and step 6 leaves no session to dispose.
   granted MCP tool or a tool of another extension fails with
   `extension_tool_conflict`. This also stops an extension from replacing a
   built-in tool inside a `read-only` profile.
-  A name must also match `[A-Za-z0-9_.:][A-Za-z0-9_.:-]*`: the SDK reads `*`
-  in an allowlist as a glob and a leading `+` or `-` as a modifier, so any
-  other name fails the same way, in both profiles.
+  A name must also match `[A-Za-z0-9_][A-Za-z0-9_-]{0,63}`: the SDK reads `*`
+  in an allowlist as a glob and a leading `+` or `-` as a modifier, and 64
+  characters of letters, digits, `_` and `-` fit the common provider
+  function-name limit, so any other name fails the same way, in both
+  profiles. Names that Pi SDK 1.1.0 treats as MCP tools fail too: any name
+  starting with `mcp__`, and exactly `list_mcp_resources`,
+  `list_mcp_resource_templates` and `read_mcp_resource`. When the allowlist
+  names no `mcp__` entry, the SDK keeps such tools outside the allowlist for
+  codemode and tool_search, so they could otherwise be active without a grant.
+  This server's own MCP bridge tools use a single underscore (`mcp_<server>_<tool>`)
+  and never collide.
   The check runs after load and again after binding, because a `session_start`
   handler can register a tool during `bindExtensions`. If the registered tool
   set then differs from the one the session was created with, the start fails
@@ -230,7 +255,11 @@ and step 6 leaves no session to dispose.
   `before_provider_request`, `before_provider_headers` and `context`.
 - **Prompts.** Every `session.prompt()` call, for every profile, passes
   `expandPromptTemplates: false`. Client prompt text never dispatches an
-  extension command, a skill command or a prompt template.
+  extension command, a skill command or a prompt template. The call also
+  passes `source: "rpc"`, which is what Pi's own RPC mode uses for input from
+  a program over stdio and so matches an MCP client. The SDK default,
+  `interactive`, means a human at the terminal or the CLI's print mode, which
+  a client prompt is not. Extension `input` hooks therefore see `rpc`.
 - **UI and flags.** No UI context is bound; extension UI calls return the
   SDK's no-op results. `extensionFlagValues` is empty, so extension flags keep
   their defaults.
@@ -311,7 +340,7 @@ admitted:
 | `extension_not_installed` | Configured Pi extension is not installed | Pi has no user install of the package. |
 | `extension_version_mismatch` | Configured Pi extension version is not installed | The installed version differs from the pinned version. |
 | `extension_load_failed` | Configured Pi extension could not be loaded | Invalid manifest, entry outside the package, load or bind error, services diagnostic of type `error`. |
-| `extension_tool_conflict` | Configured Pi extension tools conflict | An extension tool name collides with a built-in, MCP or other extension tool. |
+| `extension_tool_conflict` | Configured Pi extension tools conflict | An extension tool name collides with a built-in, MCP or other extension tool, or is unsafe (see *Name conflicts*). |
 
 Existing codes keep their meaning. An extension provider that is unknown after
 loading is `unknown_provider`.
@@ -358,7 +387,7 @@ Automated tests use no credentials and no network.
   - `session_shutdown` on close, on a failure after services, and on a late
     start after the deadline;
   - tool lists for read-only and coding, and `extension_tool_conflict`;
-  - `expandPromptTemplates: false` on every prompt;
+  - `expandPromptTemplates: false` and `source: "rpc"` on every prompt;
   - profiles without extensions taking the unchanged path.
 - **stdout guard** (`test/stdout-guard.test.ts`): foreign `write` and
   `console.*` output does not reach stdout, transport writes do, and the

package/docs/releasing.md

@@ -20,7 +20,8 @@ error codes, as defined in the [tool contracts](tool-contracts.md).
 
 A release is distributed twice: as the GitHub release with its source archive,
 and as the npm package `pi-session-mcp`. The npm package contains the built
-files, the executables, the documentation and the example configuration, but
+files, the executables, the operator documentation and the example
+configuration. It contains no implementation plans (`docs/superpowers/`), and
 no lockfile, because npm does not ship lockfiles inside packages.
 
 ## Update the Pi SDK
@@ -47,7 +48,10 @@ update is possible. It is not an update and not an acceptance.
    ships in the package as
    `node_modules/@earendil-works/pi-coding-agent/CHANGELOG.md`. Look for changes
    to stop reasons, prompt acceptance, the tools declared to the model,
-   provider keys, MCP naming and packaging.
+   provider keys, MCP naming and packaging. For MCP naming, compare the SDK's
+   `isMcpToolName` (`dist/core/mcp-servers.js`) with the reserved names in
+   `src/session-tools.ts`. That function is not a root export, so no test
+   notices when the SDK reserves another name.
 
 3. Move the pin:
 
@@ -100,7 +104,8 @@ release, record the contract again:
 5. Update the versions named in [Installation](installation.md).
 6. Run the working-tree
    [Level 2 lifecycle](acceptance.md#level-2-setup-acceptance) with the real
-   client for every scope.
+   client for every scope (`scripts/setup-acceptance.mjs`, see
+   [Tooling](acceptance.md#tooling)).
 
 ## Patch audit advisories
 
@@ -151,7 +156,10 @@ Steps:
    `## Unreleased`, so that the unreleased entries become the release entries.
 4. Run the Level 1 checks. `npm run --silent doctor -- --json` must report the
    new `packageVersion`.
-5. Open one pull request named `chore: prepare v<x.y.z> release`.
+5. Run the working-tree
+   [Level 2 acceptance](acceptance.md#tooling) on the release candidate with
+   `scripts/setup-acceptance.mjs`, unless the release notes state its absence.
+6. Open one pull request named `chore: prepare v<x.y.z> release`.
 
 ## Publish a release
 
@@ -171,7 +179,7 @@ package contains exactly the tagged sources:
 git clone --branch v<x.y.z> --depth 1 https://github.com/plagor44-ux/pi-session-mcp.git /tmp/pi-session-mcp-release
 cd /tmp/pi-session-mcp-release
 npm ci
-npm publish --dry-run     # review the file list: dist/, .pi-session-mcp-cli/, scripts/doctor.mjs, docs/
+npm publish --dry-run     # review the file list: dist/, .pi-session-mcp-cli/, scripts/doctor.mjs, docs/ without docs/superpowers/
 npm stage publish         # the prepack script builds the server, setup and Doctor
 ```
 
@@ -210,7 +218,8 @@ After publishing:
 1. Run the published-release
    [Level 2 acceptance](acceptance.md#working-tree-and-published-release-variants)
    from a fresh clone of the tag and from the published npm package, and
-   record it.
+   record it. `scripts/setup-acceptance.mjs` runs both
+   ([Tooling](acceptance.md#tooling)).
 2. Upgrade the installation as described in
    [Installation](installation.md#upgrade).
 3. Update the status section in [Acceptance](acceptance.md).

package/docs/session-mcp.md

@@ -7,8 +7,13 @@ the Pi session, supplies their definitions as `customTools`, and includes the
 names in Pi's explicit active `tools` list. The selected tools are verified again
 before the session is returned.
 
-Global/project extensions remain disabled (`noExtensions: true`). Installing
-`pi-mcp-adapter` globally is neither required nor sufficient for this integration.
+Global and project extensions are never auto-discovered; only the extensions
+that a profile allowlists load (see [Pi extensions](installation.md#pi-extensions)).
+Installing `pi-mcp-adapter` globally is neither required nor sufficient for this
+integration. Skills are likewise never auto-discovered; a profile gets only the
+skills it selects from the operator's catalog (see [Pi skills](skills.md)).
+Granting an external MCP tool through `mcpServers` and selecting a skill are
+independent: a skill grants no tool.
 There is no automatic import of global MCP configuration or ambient credentials.
 Profiles without `mcpServers` keep their existing built-in tool sets and launch
 no MCP child process. The public `pi_session_start` input remains unchanged: callers