pi-session-mcp 0.0.0-stage → 0.6.2

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# pi-session-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local, stdio-only [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets a coding agent such as Codex or Claude Code delegate work to a [Pi](https://github.com/earendil-works/pi) coding-agent session, under rules that the operator sets.
+
+The client never chooses a directory, a model or a permission level. It selects from workspace and execution-profile aliases that you define in a local configuration file, starts a session, sends prompts, polls the turn and closes the session. Pi Session MCP embeds the Pi SDK, keeps all state in memory and talks only over stdin and stdout.
+
+> Pi Session MCP is an independent project. It is not affiliated with or endorsed by the makers of Pi, OpenAI or Anthropic. Product names are used only to describe compatibility.
+
+## Why use it
+
+Codex and Claude Code are good at driving a task. Pi is a coding agent that runs against many model providers, including local OpenAI-compatible endpoints. Pi Session MCP connects the two: your main agent stays in charge and hands selected work to a Pi session that you configured.
+
+Reasons to do that:
+
+- **A second model without leaving your agent.** A read-only Pi session on another model can review a change, answer a question about a codebase or give a second opinion. The main agent asks, polls and reads the answer.
+- **Bulk reading stays out of the main context.** The Pi session does the exploring. Only its final answer returns to the client, capped at 64 KiB, so the main agent's context stays small.
+- **Delegated work on a model of your choice.** An execution profile binds a provider, a model and a thinking level. Routine work can go to a local or cheaper model while the main agent keeps the hard parts.
+- **Follow-up turns keep their context.** A session stays open across prompts, so a follow-up question does not pay for the same exploration twice.
+- **You set the limits, not the agent.** The client can only pick from the workspaces and profiles in your configuration file. It cannot name a directory, a model, a provider or a permission level, and the default profile is read-only.
+- **Exactly the extra tools a task needs.** A profile can grant individual tools of local stdio MCP servers to its sessions, and nothing else from those servers.
+- **Predictable to automate.** Sessions and turns have a small set of states and stable error codes. Results contain no paths, credentials, prompts or raw provider errors.
+- **Small footprint.** No daemon, no network listener and no stored state. An offline `doctor` checks an installation, and `setup` registers, verifies and removes the server reproducibly.
+
+It is not the right tool when:
+
+- you want to work with Pi yourself. Run Pi directly;
+- you need remote access, several users or sessions that survive a restart. These are out of scope by design;
+- you need to contain untrusted code. A `coding` profile limits Pi's tools, but it is not an operating-system sandbox.
+
+## Status
+
+The package version is **0.6.2**.
+
+- **Pre-1.0.** The public tool contract is stable within a minor line: a change to tools, fields, states or error codes needs a new minor release.
+- **Linux only**, Node.js 22.19.0 or newer.
+- **Clients:** Codex CLI and Claude Code. The `setup` command does not pin client versions: it accepts a client whose public `mcp` command output matches the expected contract and fails closed otherwise.
+- **Out of scope by design:** HTTP, a web UI, persistence, resume, remote access and multi-user behavior. One trusted local MCP peer talks to one server process.
+- **Not a sandbox.** A `coding` profile restricts the Pi tools that a session may use. It does not isolate the process from the operating system.
+- **Acceptance.** Every release passes the provider-free checks. The live two-client acceptance has not yet been repeated on a build with Pi SDK `1.x`; see [Acceptance](docs/acceptance.md).
+
+## How it works
+
+```text
+Codex or Claude Code  ──MCP over stdio──▶  pi-session-mcp  ──embedded Pi SDK──▶  Pi session  ──▶  model provider
+      (client)                           (this server)                      (in memory)
+```
+
+The client starts `node dist/main.js` as a child process. Pi Session MCP reads its configuration once, exposes eight tools, and runs Pi sessions inside that process through the embedded Pi SDK. Pi's existing local authentication is reused and never stored, printed or returned.
+
+| Tool | Purpose |
+| --- | --- |
+| `pi_capabilities_get` | List the configured workspace and execution-profile aliases. |
+| `pi_session_start` | Start a session for one workspace alias and one execution-profile alias. |
+| `pi_session_list` | List the sessions of this server process. |
+| `pi_session_get` | Read one session. |
+| `pi_session_prompt` | Send a prompt and get a running turn back. |
+| `pi_turn_get` | Poll a turn until it is `completed`, `failed` or `aborted`. |
+| `pi_session_abort` | Abort a running turn. |
+| `pi_session_close` | End a session and release its resources. |
+
+The [tool contracts](docs/tool-contracts.md) define every field, state and error code.
+
+## Quick start
+
+```bash
+npm install -g pi-session-mcp@<version>
+
+mkdir -p "$HOME/.config/pi-session-mcp"
+cp "$(npm root -g)/pi-session-mcp/pi-session-mcp.example.json" "$HOME/.config/pi-session-mcp/pi-session-mcp.json"   # then edit it
+chmod 600 "$HOME/.config/pi-session-mcp/pi-session-mcp.json"
+export PI_SESSION_MCP_CONFIG="$HOME/.config/pi-session-mcp/pi-session-mcp.json"
+
+pi-session-mcp-doctor
+pi-session-mcp-setup --dry-run --target claude-code:user:pi-session-mcp
+pi-session-mcp-setup --apply --target claude-code:user:pi-session-mcp
+pi-session-mcp-setup --verify --target claude-code:user:pi-session-mcp
+```
+
+Use `codex:user:pi-session-mcp` for Codex. The example configuration contains placeholders only: replace the workspace, provider and model with real local values, and never add credentials to the file.
+
+`pi-session-mcp-doctor` is an offline health check. `pi-session-mcp-setup` plans by default, changes a client registration only with an explicit operation, and never replaces an existing divergent registration. Neither needs credentials, a provider or a model.
+
+The [installation guide](docs/installation.md) also covers installing from a release tag with the exact locked dependency tree, the configuration rules, existing registrations, configuration changes, upgrades and removal.
+
+## Configuration
+
+```json
+{
+  "workspaces": {
+    "my-project": "/absolute/path/to/my-project"
+  },
+  "executionProfiles": {
+    "safe-readonly": {
+      "default": true,
+      "permissionProfile": "read-only",
+      "provider": "your-configured-provider",
+      "model": "your-configured-model",
+      "thinkingLevel": "medium"
+    }
+  }
+}
+```
+
+- A workspace alias maps to a directory. Clients can select aliases only.
+- An execution profile binds a permission profile (`read-only` or `coding`), a provider, a model and a thinking level. Exactly one profile is the default, and it must be `read-only`.
+- A profile can grant individual tools of local stdio MCP servers to its sessions; see [External MCP tools in embedded sessions](docs/session-mcp.md).
+- The server reads the file once at startup. Start a new client session after changing it.
+
+## Run it by hand
+
+```bash
+pi-session-mcp          # npm installation
+npm start               # release checkout
+```
+
+This starts the server on stdin and stdout. `PI_SESSION_MCP_CONFIG` must name the configuration file; the server never looks for one in its working directory. Do not type ordinary text into the process and do not redirect diagnostics to stdout: stdout carries MCP frames only.
+
+To explore the tools without a coding agent, use the pinned MCP Inspector:
+
+```bash
+npm run build
+npm run inspect
+```
+
+Listing tools and testing input validation needs no provider credentials. An accepted prompt needs existing local Pi authentication and an available provider and model.
+
+Inspector 2.x keeps its server catalog in `~/.mcp-inspector/`. Without an OS keychain it also stores secrets there unencrypted; `MCP_INSPECTOR_SECRET_STORE=memory` keeps them in memory only.
+
+## Security model
+
+- **Local and single-peer.** No network listener, no daemon between client sessions, no persisted session state.
+- **Aliases instead of paths.** No tool accepts a working directory, a model, a provider or a credential.
+- **Explicit policy file.** The configuration path comes only from `PI_SESSION_MCP_CONFIG`. A file in the working directory, which is the client's project, is never read as configuration.
+- **Sanitized results.** Public errors are stable codes. They contain no paths, prompts, provider errors, authentication data or credential locations. `assistantText` can repeat workspace content and must be treated as sensitive.
+- **Fail closed.** Unknown fields, unknown aliases, unexpected client output and divergent registrations are rejected, not repaired.
+- **Bounded waiting.** Session creation, prompt acceptance, abort, close and shutdown have fixed server-side deadlines.
+
+The [threat model](docs/threat-model.md) states the assumptions and the limits, including what a `coding` profile does not protect against.
+
+## Documentation
+
+Operate:
+
+- [Installation](docs/installation.md)
+- [Client setup reference](docs/client-setup.md): manual registration, the tool flow, deadlines and troubleshooting
+- [External MCP tools in embedded sessions](docs/session-mcp.md)
+- [Changelog](CHANGELOG.md)
+
+Contract and design:
+
+- [Tool contracts](docs/tool-contracts.md)
+- [Architecture](docs/architecture.md)
+- [Threat model](docs/threat-model.md)
+- [Setup lifecycle design](docs/client-setup-design.md)
+- [Doctor contract](docs/doctor-design.md)
+- [ADR 0001: stdio first](docs/adr/0001-stdio-first.md)
+- [ADR 0002: embedded Pi SDK](docs/adr/0002-embedded-pi-sdk.md)
+- [ADR 0003: no new feature phase after the MVP](docs/adr/0003-post-mvp-maintenance.md)
+- [ADR 0004: setup accepts clients by contract, not by version](docs/adr/0004-client-contract-not-version.md)
+
+Maintain:
+
+- [Acceptance](docs/acceptance.md)
+- [Releasing](docs/releasing.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Development
+
+```bash
+npm ci
+npm run typecheck
+npm run build:cli
+npm test
+npm run build
+```
+
+These are the checks that CI runs. Tests use a fake Pi adapter or a scripted model and need no provider credentials. Every direct dependency is pinned exactly, and the lockfile is committed. The project rules for contributors and coding agents are in [AGENTS.md](AGENTS.md).
+
+The Pi SDK moves quickly, so a nightly canary checks the unchanged sources against the newest published SDK without touching the pin. [Releasing](docs/releasing.md) describes how to update the pin, record a client contract, patch audit advisories and prepare a release.
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security policy
+
+## Supported versions
+
+Only the latest release receives fixes.
+
+## Reporting a vulnerability
+
+Report vulnerabilities privately through GitHub's private vulnerability
+reporting: open the **Security** tab of this repository and choose **Report a
+vulnerability**. Do not open a public issue for a suspected vulnerability.
+
+Include the Pi Session MCP version, the client and its version, the shape of the
+configuration without any real values, and the steps to reproduce. Never
+include credentials, prompts, transcripts or absolute local paths.
+
+## What counts
+
+Pi Session MCP promises a narrow boundary, described in the
+[threat model](docs/threat-model.md). Reports about a broken promise are in
+scope, for example:
+
+- a path, credential, prompt, provider error or authentication location in a
+  public tool result, a `doctor` report or a `setup` report;
+- a client reaching a directory, model, provider or permission level that the
+  configuration does not offer through an alias;
+- a session receiving a tool that its execution profile does not grant;
+- `setup` changing or removing a registration that it does not own.
+
+## What does not count
+
+- A `coding` profile is an application-level tool allowlist. It is not an
+  operating-system sandbox, and this is a documented limit, not a defect.
+- Vulnerabilities in Pi, in the MCP clients, in model providers or in other
+  dependencies belong to those projects. A dependency advisory that affects Pi
+  Control's own use of the dependency is in scope.
+- The server trusts its one local MCP peer and the operator's configuration.

package/dist/capabilities.d.ts

@@ -0,0 +1,25 @@
+import type { ConfigurationMetadata } from "./config.js";
+import type { ConfiguredExecutionProfile } from "./execution-profile.js";
+/** Pure projection of the snapshot captured at load time; never reads the configuration file. */
+export declare function projectCapabilities(workspaces: ReadonlyMap<string, string>, executionProfiles: ReadonlyMap<string, ConfiguredExecutionProfile>, configuration: ConfigurationMetadata): {
+    ok: true;
+    server: {
+        name: string;
+        version: string;
+    };
+    configuration: {
+        fingerprint: `sha256:${string}`;
+        reloadPolicy: "restart-required";
+    };
+    workspaces: {
+        alias: string;
+    }[];
+    executionProfiles: {
+        alias: string;
+        default: boolean;
+        permissionProfile: import("./execution-profile.js").PermissionProfile;
+        provider: string;
+        model: string;
+        thinkingLevel: import("./execution-profile.js").ThinkingLevel;
+    }[];
+};

package/dist/capabilities.js

@@ -0,0 +1,26 @@
+import packageMetadata from "../package.json" with { type: "json" };
+const compareAliases = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+/** Pure projection of the snapshot captured at load time; never reads the configuration file. */
+export function projectCapabilities(workspaces, executionProfiles, configuration) {
+    return {
+        ok: true,
+        server: { name: packageMetadata.name, version: packageMetadata.version },
+        configuration: {
+            fingerprint: configuration.fingerprint,
+            reloadPolicy: configuration.reloadPolicy,
+        },
+        workspaces: [...workspaces.keys()]
+            .sort(compareAliases)
+            .map((alias) => ({ alias })),
+        executionProfiles: [...executionProfiles.values()]
+            .sort((left, right) => compareAliases(left.alias, right.alias))
+            .map(({ alias, default: isDefault, permissionProfile, provider, model, thinkingLevel }) => ({
+            alias,
+            default: isDefault,
+            permissionProfile,
+            provider,
+            model,
+            thinkingLevel,
+        })),
+    };
+}

package/dist/client-adapters/claude-code.d.ts

@@ -0,0 +1,4 @@
+import type { ClientAdapter, CommandRunner } from "./types.js";
+export declare function createClaudeCodeAdapter(input: {
+    readonly runner: CommandRunner;
+}): ClientAdapter;

package/dist/client-adapters/claude-code.js

@@ -0,0 +1,33 @@
+import { safeRunner, versionFromOutput } from "./command.js";
+const NAME = "pi-session-mcp";
+function scopeArgs(scope) { return ["-s", scope]; }
+function inspectText(text, intent) {
+    const bounded = text.slice(0, 32_768);
+    if (!/(?:^|\n)\s*pi-session-mcp\s*:/i.test(bounded))
+        return { state: "absent", expected: false };
+    const scope = /(?:^|\n)\s*scope\s*:\s*(user|project|local)\s+config\b.*$/im.exec(bounded)?.[1]?.toLowerCase();
+    const type = /(?:^|\n)\s*type\s*:\s*(\S+)\s*$/im.exec(bounded)?.[1];
+    const command = /(?:^|\n)\s*command\s*:\s*(\S+)\s*$/im.exec(bounded)?.[1];
+    const args = /(?:^|\n)\s*args?\s*:\s*(.+)\s*$/im.exec(bounded)?.[1];
+    const environmentBlock = /(?:^|\n)\s*environment\s*:\s*\n((?:\s{4,}[^\n]+\n?)+)/im.exec(bounded)?.[1];
+    const environment = environmentBlock?.split("\n").map((line) => line.trim()).filter(Boolean) ?? [];
+    const configLine = environment[0];
+    const config = configLine?.startsWith("PI_SESSION_MCP_CONFIG=") ? configLine.slice("PI_SESSION_MCP_CONFIG=".length) : undefined;
+    if (!scope || type !== "stdio" || !command || !args || environment.length !== 1 || !config)
+        return { state: "unsupported", expected: false };
+    const expected = scope === intent.scope && command === intent.nodePath && args.trim() === intent.entryPath && config === intent.configPath;
+    return { state: expected ? "equivalent" : "divergent", expected };
+}
+export function createClaudeCodeAdapter(input) {
+    const runner = safeRunner(input.runner.run);
+    return {
+        client: "claude-code",
+        async discover() { const versionResult = await runner.run("claude", ["--version"]); const v = versionResult.exitCode === 0 ? versionFromOutput("claude-code", versionResult.stdout) : undefined; const probe = await runner.run("claude", ["mcp", "--help"]); const supported = probe.exitCode === 0 && ["get", "add", "remove"].every((command) => new RegExp(`\\b${command}\\b`).test(probe.stdout)); return { client: "claude-code", version: v ?? "unknown", supportsJson: false, supportsAdd: supported, supportsRemove: supported, scopes: supported ? ["user", "project", "local"] : [] }; },
+        async inspect(scope, intent) { const r = await runner.run("claude", ["mcp", "get", NAME]); const absent = /^No MCP server named \"pi-session-mcp\"\.(?:(?:\s+Configured servers:.*)|(?:\s+Run `claude mcp add` to add one\.))?\s*$/i.test(r.stderr.trim()); const x = r.exitCode === 0 ? inspectText(r.stdout, intent) : absent ? { state: "absent", expected: false } : { state: "unsupported", expected: false }; return { client: "claude-code", scope, name: NAME, state: x.state, command: x.expected ? "node" : "unknown", hasExpectedConfig: x.expected, supported: x.state !== "unsupported" }; },
+        async plan(intent) { const r = await this.inspect(intent.scope, intent); return { client: "claude-code", scope: intent.scope, state: r.state, operation: r.state === "absent" ? "add" : "none", reason: r.state === "absent" ? "missing" : r.state === "equivalent" ? "already_registered" : r.state }; },
+        async add(intent, execution) { const r = await (execution?.runner ?? runner).run("claude", ["mcp", "add", NAME, "-s", intent.scope, "-e", `PI_SESSION_MCP_CONFIG=${intent.configPath}`, "--", intent.nodePath, intent.entryPath], execution?.signal); if (r.exitCode !== 0)
+            throw new Error("client registration failed"); },
+        async remove(scope, execution) { const r = await (execution?.runner ?? runner).run("claude", ["mcp", "remove", NAME, ...scopeArgs(scope)], execution?.signal); if (r.exitCode !== 0)
+            throw new Error("client removal failed"); },
+    };
+}

package/dist/client-adapters/codex.d.ts

@@ -0,0 +1,4 @@
+import type { ClientAdapter, CommandRunner } from "./types.js";
+export declare function createCodexAdapter(input: {
+    readonly runner: CommandRunner;
+}): ClientAdapter;

package/dist/client-adapters/codex.js

@@ -0,0 +1,73 @@
+import { safeRunner, versionFromOutput } from "./command.js";
+const NAME = "pi-session-mcp";
+function equivalent(value, intent) {
+    if (!value || typeof value !== "object")
+        return false;
+    const root = value;
+    if (root.name !== NAME || root.enabled !== true)
+        return false;
+    const transport = root.transport;
+    if (!transport || typeof transport !== "object")
+        return false;
+    const entry = transport;
+    const args = Array.isArray(entry.args) ? entry.args : [];
+    const env = entry.env;
+    const envRecord = env && typeof env === "object" ? env : undefined;
+    return entry.type === "stdio"
+        && entry.command === intent.nodePath
+        && args.length === 1 && args[0] === intent.entryPath
+        && !!envRecord && Object.keys(envRecord).length === 1 && envRecord.PI_SESSION_MCP_CONFIG === intent.configPath
+        && Array.isArray(entry.env_vars) && entry.env_vars.length === 0
+        && entry.cwd === null;
+}
+export function createCodexAdapter(input) {
+    const runner = safeRunner(input.runner.run);
+    return {
+        client: "codex",
+        async discover() {
+            const versionResult = await runner.run("codex", ["--version"]);
+            const version = versionResult.exitCode === 0 ? versionFromOutput("codex", versionResult.stdout) : undefined;
+            const probe = await runner.run("codex", ["mcp", "--help"]);
+            const supported = probe.exitCode === 0 && ["get", "add", "remove"].every((command) => new RegExp(`\\b${command}\\b`).test(probe.stdout));
+            return { client: "codex", version: version ?? "unknown", supportsJson: supported, supportsAdd: supported, supportsRemove: supported, scopes: supported ? ["user"] : [] };
+        },
+        async inspect(scope, intent) {
+            if (scope !== "user")
+                return { client: "codex", scope, name: NAME, state: "unsupported", command: "unknown", hasExpectedConfig: false, supported: false };
+            const result = await runner.run("codex", ["mcp", "get", NAME, "--json"]);
+            let state = "absent";
+            let supported = true;
+            let hasExpectedConfig = false;
+            let command = "unknown";
+            if (result.exitCode === 0) {
+                try {
+                    const value = JSON.parse(result.stdout);
+                    const transport = value && typeof value === "object" && value.transport;
+                    if (!transport || typeof transport !== "object")
+                        throw new Error("schema");
+                    hasExpectedConfig = equivalent(value, intent);
+                    state = hasExpectedConfig ? "equivalent" : "divergent";
+                    command = hasExpectedConfig ? "node" : "unknown";
+                }
+                catch {
+                    state = "unsupported";
+                    supported = false;
+                }
+            }
+            else if (/^Error: No MCP server named 'pi-session-mcp' found\.\s*$/i.test(result.stderr.trim()))
+                state = "absent";
+            else {
+                state = "unsupported";
+                supported = false;
+            }
+            return { client: "codex", scope, name: NAME, state, command, hasExpectedConfig, supported };
+        },
+        async plan(intent) { const r = await this.inspect(intent.scope, intent); return { client: "codex", scope: intent.scope, state: r.state, operation: r.state === "absent" ? "add" : "none", reason: r.state === "absent" ? "missing" : r.state === "equivalent" ? "already_registered" : r.state }; },
+        async add(intent, execution) { if (intent.scope !== "user")
+            throw new Error("unsupported client scope"); const r = await (execution?.runner ?? runner).run("codex", ["mcp", "add", NAME, "--env", `PI_SESSION_MCP_CONFIG=${intent.configPath}`, "--", intent.nodePath, intent.entryPath], execution?.signal); if (r.exitCode !== 0)
+            throw new Error("client registration failed"); },
+        async remove(scope, execution) { if (scope !== "user")
+            throw new Error("unsupported client scope"); const r = await (execution?.runner ?? runner).run("codex", ["mcp", "remove", NAME], execution?.signal); if (r.exitCode !== 0)
+            throw new Error("client removal failed"); },
+    };
+}

package/dist/client-adapters/command.d.ts

@@ -0,0 +1,12 @@
+import type { CommandResult, CommandRunner } from "./types.js";
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 5000;
+export declare const MAX_OUTPUT_BYTES = 32768;
+/**
+ * Clients are accepted by contract, not by version: an adapter supports a
+ * client whose public `mcp` command output parses as expected and fails closed
+ * on any other output. The version is reported for information only.
+ */
+export type ClientName = "codex" | "claude-code";
+export declare function boundedResult(result: CommandResult): CommandResult;
+export declare function versionFromOutput(client: ClientName, output: string): string | undefined;
+export declare function safeRunner(run: CommandRunner["run"]): CommandRunner;

package/dist/client-adapters/command.js

@@ -0,0 +1,25 @@
+export const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
+export const MAX_OUTPUT_BYTES = 32_768;
+export function boundedResult(result) {
+    const truncate = (value) => {
+        const bytes = Buffer.from(value, "utf8");
+        return bytes.byteLength <= MAX_OUTPUT_BYTES ? value : bytes.subarray(0, MAX_OUTPUT_BYTES).toString("utf8");
+    };
+    return {
+        exitCode: result.exitCode,
+        stdout: truncate(result.stdout),
+        stderr: truncate(result.stderr),
+    };
+}
+export function versionFromOutput(client, output) {
+    // Each CLI has its own complete public line. Keep the boundary narrow: `\\s`
+    // would accept arbitrary additional lines and trailing diagnostic text.
+    const pattern = client === "codex"
+        ? /^[ \t]*codex(?:-cli)?[ \t]+v?(\d+\.\d+\.\d+)[ \t]*(?:\r?\n)?$/
+        : /^[ \t]*(?:(?:claude(?:-code)?)[ \t]+)?v?(\d+\.\d+\.\d+)(?:[ \t]+\(Claude Code\))?[ \t]*(?:\r?\n)?$/;
+    const match = pattern.exec(output);
+    return match?.[1];
+}
+export function safeRunner(run) {
+    return { run: async (command, args, signal) => boundedResult(await run(command, args, signal)) };
+}

package/dist/client-adapters/index.d.ts

@@ -0,0 +1,4 @@
+export type { ClientAdapter, ClientCapabilities, ClientName, ClientRegistration, ClientScope, CommandResult, CommandRunner, RegistrationIntent, RegistrationPlan, RegistrationState } from "./types.js";
+export { createCodexAdapter } from "./codex.js";
+export { createClaudeCodeAdapter } from "./claude-code.js";
+export { verifyMcpCapabilities, type McpVerifierOptions, type McpVerifierResult, type McpStdioProcess } from "./mcp-verifier.js";

package/dist/client-adapters/index.js

@@ -0,0 +1,3 @@
+export { createCodexAdapter } from "./codex.js";
+export { createClaudeCodeAdapter } from "./claude-code.js";
+export { verifyMcpCapabilities } from "./mcp-verifier.js";

package/dist/client-adapters/mcp-verifier.d.ts

@@ -0,0 +1,20 @@
+export declare const MCP_VERIFY_TIMEOUT_MS = 5000;
+export declare const MCP_MAX_FRAME_BYTES = 65536;
+export interface McpStdioProcess {
+    write(frame: string): void | Promise<void>;
+    read(): Promise<string | null>;
+    kill(): void | Promise<void>;
+}
+export interface McpVerifierOptions {
+    readonly launch: (signal: AbortSignal) => Promise<McpStdioProcess>;
+    readonly timeoutMs?: number;
+}
+export interface McpVerifierResult {
+    readonly status: "verified" | "unsupported" | "timeout" | "failed";
+    readonly initialize: boolean;
+    readonly toolsList: boolean;
+    readonly capabilitiesGet: boolean;
+    readonly tools: readonly string[];
+}
+/** Performs only initialize, tools/list, and pi_capabilities_get({}). */
+export declare function verifyMcpCapabilities(options: McpVerifierOptions): Promise<McpVerifierResult>;

package/dist/client-adapters/mcp-verifier.js

@@ -0,0 +1,174 @@
+import { PACKAGE_NAME, PACKAGE_VERSION } from "../package-metadata.js";
+export const MCP_VERIFY_TIMEOUT_MS = 5_000;
+export const MCP_MAX_FRAME_BYTES = 65_536;
+const EXPECTED_TOOLS = ["pi_capabilities_get", "pi_session_start", "pi_session_list", "pi_session_get", "pi_session_prompt", "pi_session_abort", "pi_session_close", "pi_turn_get"];
+const EXPECTED_PROTOCOL = "2025-03-26";
+const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+const FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const RELOAD_POLICY = "restart-required";
+class VerificationTimeoutError extends Error {
+}
+async function beforeDeadline(operation, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new VerificationTimeoutError();
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new VerificationTimeoutError()), remaining);
+    });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function frame(value) {
+    const body = JSON.stringify(value);
+    return `${body}\n`;
+}
+function parseFrame(value) {
+    if (Buffer.byteLength(value, "utf8") > MCP_MAX_FRAME_BYTES)
+        return undefined;
+    const split = value.indexOf("\r\n\r\n");
+    const body = (split >= 0 ? value.slice(split + 4) : value).trim();
+    try {
+        const parsed = JSON.parse(body);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseToolNames(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const names = [];
+    for (const tool of value) {
+        if (!tool || typeof tool !== "object")
+            return undefined;
+        const name = tool.name;
+        if (typeof name !== "string" || name.length === 0 || name.length > 128 || names.includes(name))
+            return undefined;
+        names.push(name);
+    }
+    return names;
+}
+async function readResponse(process, id, deadline) {
+    while (Date.now() < deadline) {
+        const line = await beforeDeadline(process.read(), deadline);
+        if (line === null)
+            return undefined;
+        const response = parseFrame(line);
+        if (response?.id === id)
+            return response;
+    }
+    return undefined;
+}
+function validConfiguration(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return exactKeys(record, ["fingerprint", "reloadPolicy"])
+        && typeof record.fingerprint === "string" && FINGERPRINT_PATTERN.test(record.fingerprint)
+        && record.reloadPolicy === RELOAD_POLICY;
+}
+function validCapabilities(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const x = value;
+    if (x.ok !== true || !exactKeys(x, ["ok", "server", "configuration", "workspaces", "executionProfiles"]) || !x.server || typeof x.server !== "object")
+        return false;
+    const info = x.server;
+    if (!exactKeys(info, ["name", "version"]) || info.name !== PACKAGE_NAME || info.version !== PACKAGE_VERSION || !Array.isArray(x.workspaces) || !Array.isArray(x.executionProfiles))
+        return false;
+    if (!validConfiguration(x.configuration))
+        return false;
+    const workspaces = x.workspaces;
+    const profiles = x.executionProfiles;
+    if (!workspaces.every((workspace) => {
+        if (!workspace || typeof workspace !== "object")
+            return false;
+        const record = workspace;
+        return exactKeys(record, ["alias"]) && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias);
+    }))
+        return false;
+    if (!profiles.every((profile) => {
+        if (!profile || typeof profile !== "object")
+            return false;
+        const record = profile;
+        return exactKeys(record, ["alias", "default", "permissionProfile", "provider", "model", "thinkingLevel"])
+            && typeof record.alias === "string" && ALIAS_PATTERN.test(record.alias)
+            && typeof record.default === "boolean"
+            && (record.permissionProfile === "read-only" || record.permissionProfile === "coding")
+            && typeof record.provider === "string" && record.provider.length > 0 && record.provider.length <= 256
+            && typeof record.model === "string" && record.model.length > 0 && record.model.length <= 256
+            && typeof record.thinkingLevel === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(record.thinkingLevel);
+    }))
+        return false;
+    const defaults = profiles.filter((profile) => profile.default === true);
+    if (defaults.length !== 1 || defaults[0].permissionProfile !== "read-only")
+        return false;
+    return true;
+}
+function exactKeys(value, expected) {
+    const keys = Object.keys(value).sort();
+    return keys.length === expected.length && [...expected].sort().every((key, index) => keys[index] === key);
+}
+async function performVerification(process, deadline) {
+    const result = { status: "failed", initialize: false, toolsList: false, capabilitiesGet: false, tools: [] };
+    await beforeDeadline(Promise.resolve(process.write(frame({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: EXPECTED_PROTOCOL, capabilities: {}, clientInfo: { name: "pi-session-mcp-verifier", version: PACKAGE_VERSION } } }))), deadline);
+    const initialized = await readResponse(process, 1, deadline);
+    const initializedResult = initialized?.result && typeof initialized.result === "object" ? initialized.result : undefined;
+    const serverInfo = initializedResult?.serverInfo;
+    if (!initializedResult || !serverInfo || typeof serverInfo !== "object"
+        || initializedResult.protocolVersion !== EXPECTED_PROTOCOL
+        || serverInfo.name !== PACKAGE_NAME
+        || serverInfo.version !== PACKAGE_VERSION)
+        return { ...result, status: "unsupported" };
+    result.initialize = true;
+    await beforeDeadline(Promise.resolve(process.write(frame({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }))), deadline);
+    await beforeDeadline(Promise.resolve(process.write(frame({ jsonrpc: "2.0", id: 3, method: "tools/list", params: {} }))), deadline);
+    const listed = await readResponse(process, 3, deadline);
+    if (!listed?.result || typeof listed.result !== "object")
+        return { ...result, status: "unsupported" };
+    const tools = parseToolNames(listed.result.tools);
+    result.toolsList = true;
+    if (!tools || tools.length !== EXPECTED_TOOLS.length || EXPECTED_TOOLS.some((name) => !tools.includes(name)))
+        return { ...result, status: "unsupported" };
+    result.tools = [...EXPECTED_TOOLS];
+    await beforeDeadline(Promise.resolve(process.write(frame({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: "pi_capabilities_get", arguments: {} } }))), deadline);
+    const called = await readResponse(process, 4, deadline);
+    const structured = called?.result && typeof called.result === "object" ? called.result.structuredContent : undefined;
+    if (!called?.result || !validCapabilities(structured))
+        return { ...result, status: "failed" };
+    result.capabilitiesGet = true;
+    return { ...result, status: "verified" };
+}
+/** Performs only initialize, tools/list, and pi_capabilities_get({}). */
+export async function verifyMcpCapabilities(options) {
+    const timeout = Math.max(1, options.timeoutMs ?? MCP_VERIFY_TIMEOUT_MS);
+    const deadline = Date.now() + timeout;
+    const empty = { status: "failed", initialize: false, toolsList: false, capabilitiesGet: false, tools: [] };
+    const controller = new AbortController();
+    let process;
+    let outcome = empty;
+    try {
+        process = await beforeDeadline(options.launch(controller.signal), deadline);
+        outcome = await performVerification(process, deadline);
+    }
+    catch (error) {
+        outcome = { ...empty, status: error instanceof VerificationTimeoutError ? "timeout" : "failed" };
+    }
+    controller.abort();
+    if (process) {
+        try {
+            await beforeDeadline(Promise.resolve(process.kill()), Date.now() + Math.min(timeout, 1_000));
+        }
+        catch {
+            return { ...outcome, status: "failed" };
+        }
+    }
+    return outcome;
+}