pi-session-mcp 0.0.0-stage → 0.6.2

package/.pi-session-mcp-cli/config.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+import { isMcpServers, snapshotMcpServers } from "./mcp-config.js";
+import { ALIAS_PATTERN, ImmutableMap, } from "./execution-profile.js";
+const alias = z.string().regex(ALIAS_PATTERN);
+const permissionProfile = z.enum(["read-only", "coding"]);
+const thinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+const profileSchema = z.object({
+    default: z.boolean(), permissionProfile, provider: z.string().trim().min(1).max(256),
+    model: z.string().trim().min(1).max(256), thinkingLevel,
+    mcpServers: z.custom((value) => isMcpServers(value)).optional(),
+}).strict().superRefine((profile, context) => {
+    if (profile.mcpServers !== undefined && !isMcpServers(profile.mcpServers, profile.permissionProfile)) {
+        context.addIssue({ code: "custom", path: ["mcpServers"], message: "MCP tool grants do not match the permission profile" });
+    }
+});
+const CONFIG_ERROR_MESSAGES = {
+    config_path_required: "Configuration path is required",
+    invalid_execution_profile_config: "Execution profile configuration is invalid",
+    invalid_thinking_level: "Execution profile thinking level is invalid",
+};
+export class ConfigError extends Error {
+    code;
+    constructor(code) {
+        super(CONFIG_ERROR_MESSAGES[code]);
+        this.name = "ConfigError";
+        this.code = code;
+    }
+}
+export const configSchema = z.object({
+    workspaces: z.record(alias, z.string().min(1)),
+    executionProfiles: z.record(alias, profileSchema).superRefine((profiles, context) => {
+        const entries = Object.entries(profiles);
+        if (entries.length === 0)
+            context.addIssue({ code: "custom", message: "At least one execution profile is required" });
+        const defaults = entries.filter(([, profile]) => profile.default);
+        if (defaults.length !== 1)
+            context.addIssue({ code: "custom", message: "Exactly one execution profile must be the default" });
+        if (defaults.length === 1 && defaults[0][1].permissionProfile !== "read-only")
+            context.addIssue({ code: "custom", message: "The default execution profile must be read-only" });
+    }),
+}).strict();
+/** The only supported reload behavior: a running controller keeps the snapshot it loaded at startup. */
+export const RELOAD_POLICY = "restart-required";
+export const CONFIGURATION_FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+function configurationFingerprint(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * The configuration path comes only from the caller or from `PI_SESSION_MCP_CONFIG`.
+ * There is no default file: a server's working directory is the client's project,
+ * which may be untrusted, so a file found there must never become the policy.
+ */
+export async function loadConfig(path = process.env.PI_SESSION_MCP_CONFIG) {
+    if (!path)
+        throw new ConfigError("config_path_required");
+    const absoluteConfig = resolve(path);
+    // One read: the same bytes feed both the fingerprint and the parse.
+    const bytes = await readFile(absoluteConfig);
+    const configuration = Object.freeze({
+        fingerprint: configurationFingerprint(bytes),
+        reloadPolicy: RELOAD_POLICY,
+    });
+    const input = JSON.parse(bytes.toString("utf8"));
+    let parsed;
+    try {
+        parsed = configSchema.parse(input);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const thinkingLevelIssue = error.issues.some((issue) => issue.path.at(-1) === "thinkingLevel");
+            throw new ConfigError(thinkingLevelIssue ? "invalid_thinking_level" : "invalid_execution_profile_config");
+        }
+        throw error;
+    }
+    const base = dirname(absoluteConfig);
+    const workspaces = new ImmutableMap(Object.entries(parsed.workspaces).map(([key, value]) => [key, resolve(base, value)]));
+    const executionProfiles = new ImmutableMap(Object.entries(parsed.executionProfiles).map(([key, { mcpServers, ...value }]) => [key, Object.freeze({
+            alias: key, ...value,
+            ...(mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(mcpServers) }),
+        })]));
+    const defaultEntry = [...executionProfiles].find(([, profile]) => profile.default);
+    if (!defaultEntry)
+        throw new Error("Execution profile configuration is invalid");
+    return { workspaces, executionProfiles, defaultExecutionProfile: defaultEntry[0], configuration };
+}

package/.pi-session-mcp-cli/doctor-cli.js

@@ -0,0 +1,11 @@
+import { parseDoctorArgs, renderDoctorHuman, renderDoctorJson, runDoctor } from "./doctor.js";
+const options = parseDoctorArgs(process.argv.slice(2));
+if (!options) {
+    process.stderr.write("Usage: doctor [--json]\n");
+    process.exitCode = 64;
+}
+else {
+    const result = await runDoctor();
+    process.stdout.write(options.json ? renderDoctorJson(result) : renderDoctorHuman(result));
+    process.exitCode = result.exitCode;
+}

package/.pi-session-mcp-cli/doctor.js

@@ -0,0 +1,178 @@
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { readPackageMetadata } from "./package-metadata.js";
+const defaultFileSystem = { readFile, stat, access };
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable"];
+function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
+function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
+function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
+function isMissing(error) { return typeof error === "object" && error !== null && "code" in error && ["ENOENT", "config_path_required"].includes(String(error.code)); }
+/** The lockfile's modification time, or undefined for an npm installation, which has no lockfile. */
+async function lockfileMtime(fs, root) {
+    try {
+        return (await fs.stat(join(root, "package-lock.json"))).mtimeMs;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+function isUnreadable(error) { return typeof error === "object" && error !== null && "code" in error && ["EACCES", "EPERM"].includes(String(error.code)); }
+function isSemver(value) { return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(value); }
+function satisfiesNode(version, range) {
+    const minimum = range.match(/>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    const actual = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!minimum || !actual)
+        return false;
+    const want = [Number(minimum[1]), Number(minimum[2] ?? 0), Number(minimum[3] ?? 0)];
+    const got = [Number(actual[1]), Number(actual[2]), Number(actual[3])];
+    return got[0] > want[0] || (got[0] === want[0] && (got[1] > want[1] || (got[1] === want[1] && got[2] >= want[2])));
+}
+/** Build inputs beyond the manifests. An installed package has none of them, which is not staleness. */
+async function productionBuildInputMtimes(root) {
+    const mtimes = [];
+    for (const name of ["tsconfig.json", "tsconfig.build.json"]) {
+        try {
+            mtimes.push((await stat(join(root, name))).mtimeMs);
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+    }
+    const visit = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                await visit(path);
+            else if (entry.isFile() && entry.name.endsWith(".ts"))
+                mtimes.push((await stat(path)).mtimeMs);
+        }
+    };
+    try {
+        await visit(join(root, "src"));
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    return mtimes;
+}
+export async function runDoctor(dependencies = {}) {
+    const fs = dependencies.fileSystem ?? defaultFileSystem;
+    const root = dependencies.packageRoot ?? process.cwd();
+    const checks = [];
+    let metadata;
+    try {
+        const injected = dependencies.packageMetadata !== undefined;
+        if (dependencies.packageMetadata)
+            metadata = await dependencies.packageMetadata();
+        else {
+            metadata = await readPackageMetadata(root, fs.readFile);
+        }
+        if (!metadata || !isSemver(metadata.version) || typeof metadata.engines?.node !== "string" || !/>=\s*\d+/.test(metadata.engines.node))
+            throw new Error("invalid package metadata");
+        if (!injected && metadata.lockVersion !== undefined && !isSemver(metadata.lockVersion))
+            throw new Error("invalid lock metadata");
+    }
+    catch {
+        checks.push(failure("package_metadata_unreadable", "package metadata", "repair package metadata"));
+    }
+    const nodeRange = metadata?.engines?.node;
+    if (nodeRange && !satisfiesNode(dependencies.nodeVersion ?? process.versions.node, nodeRange))
+        checks.push(failure("node_version_unsupported", "Node.js", "use a supported Node.js version"));
+    else if (nodeRange)
+        checks.push(ok("node_version_unsupported", "Node.js"));
+    let buildMtime;
+    try {
+        const build = await fs.stat(join(root, "dist", "main.js"));
+        if (build.isFile()) {
+            buildMtime = build.mtimeMs;
+            checks.push(ok("build_missing", "build output"));
+        }
+        else
+            checks.push(failure("build_missing", "build output", "run the production build"));
+    }
+    catch (error) {
+        checks.push(failure("build_missing", "build output", isMissing(error) ? "run the production build" : "check build output access"));
+    }
+    if (buildMtime !== undefined) {
+        try {
+            const packageMtime = (await fs.stat(join(root, "package.json"))).mtimeMs;
+            const lockMtime = await lockfileMtime(fs, root);
+            const inputMtimes = [packageMtime, lockMtime].filter((value) => value !== undefined);
+            if (!dependencies.fileSystem)
+                inputMtimes.push(...await productionBuildInputMtimes(root));
+            if (inputMtimes.some((mtime) => mtime > buildMtime))
+                checks.push(warning("build_stale", "build output", "run the production build"));
+            else
+                checks.push(ok("build_stale", "build output"));
+        }
+        catch {
+            checks.push(warning("build_stale", "build output", "rebuild to establish current build state"));
+        }
+    }
+    if (metadata) {
+        const expectedVersion = metadata.expectedVersion ?? metadata.lockVersion;
+        if (expectedVersion && metadata.version !== expectedVersion)
+            checks.push(warning("version_mismatch", "package version", "reinstall matching build artifacts"));
+        else
+            checks.push(ok("version_mismatch", "package version"));
+    }
+    let config;
+    try {
+        config = await (dependencies.loadConfig ?? (() => loadConfig()))();
+        checks.push(ok("config_invalid", "configuration"));
+    }
+    catch (error) {
+        if (isMissing(error))
+            checks.push(failure("config_missing", "configuration", "create PI_SESSION_MCP_CONFIG configuration"));
+        else if (isUnreadable(error))
+            checks.push(failure("config_unreadable", "configuration", "grant configuration read access"));
+        else
+            checks.push(failure("config_invalid", "configuration", "fix configuration using the documented schema"));
+    }
+    if (config) {
+        for (const [alias, path] of [...config.workspaces].sort(([a], [b]) => a.localeCompare(b))) {
+            try {
+                const info = await fs.stat(path);
+                if (!info.isDirectory())
+                    checks.push(failure("workspace_not_directory", alias, "point the workspace alias to a directory"));
+                else {
+                    checks.push(ok("workspace_not_directory", alias));
+                    try {
+                        await fs.access(path, constants.R_OK);
+                        checks.push(ok("workspace_unreadable", alias));
+                    }
+                    catch {
+                        checks.push(failure("workspace_unreadable", alias, "grant workspace read access"));
+                    }
+                    const canWrite = [...config.executionProfiles.values()].some((profile) => profile.permissionProfile === "coding");
+                    if (canWrite) {
+                        try {
+                            await fs.access(path, constants.W_OK);
+                            checks.push(ok("workspace_not_writable", alias));
+                        }
+                        catch {
+                            checks.push(failure("workspace_not_writable", alias, "grant coding workspace write access"));
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                checks.push(failure(isMissing(error) ? "workspace_missing" : "workspace_unreadable", alias, isMissing(error) ? "fix the workspace alias target" : "grant workspace access"));
+            }
+        }
+    }
+    const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));
+    checks.sort((a, b) => (rank.get(a.id) ?? 999) - (rank.get(b.id) ?? 999) || a.subject.localeCompare(b.subject));
+    const hasError = checks.some((check) => check.severity === "error");
+    const result = { schemaVersion: 1, ok: !hasError, ...(metadata ? { packageVersion: metadata.version } : {}), checks: Object.freeze(checks), exitCode: hasError ? 2 : checks.some((check) => check.severity === "warning") ? 1 : 0 };
+    return Object.freeze(result);
+}
+export function renderDoctorJson(result) { return JSON.stringify(result) + "\n"; }
+export function renderDoctorHuman(result) { return result.checks.map((check) => `${check.severity.toUpperCase()} ${check.id} [${check.subject}]${check.remediation ? `: ${check.remediation}` : ""}`).join("\n") + "\n"; }
+export function parseDoctorArgs(args) { return args.length === 0 ? { json: false } : args.length === 1 && args[0] === "--json" ? { json: true } : undefined; }

package/.pi-session-mcp-cli/execution-profile.js

@@ -0,0 +1,29 @@
+import { snapshotMcpServers } from "./mcp-config.js";
+export const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+export function toResolvedExecutionProfile(profile) {
+    return Object.freeze({
+        alias: profile.alias,
+        permissionProfile: profile.permissionProfile,
+        provider: profile.provider,
+        model: profile.model,
+        thinkingLevel: profile.thinkingLevel,
+        ...(profile.mcpServers === undefined ? {} : { mcpServers: snapshotMcpServers(profile.mcpServers) }),
+    });
+}
+/** A small read-only map implementation which has no mutating methods at runtime. */
+export class ImmutableMap {
+    entriesMap;
+    constructor(entries) {
+        this.entriesMap = new Map(entries);
+    }
+    get size() { return this.entriesMap.size; }
+    get(key) { return this.entriesMap.get(key); }
+    has(key) { return this.entriesMap.has(key); }
+    entries() { return this.entriesMap.entries(); }
+    keys() { return this.entriesMap.keys(); }
+    values() { return this.entriesMap.values(); }
+    forEach(callbackfn, thisArg) {
+        this.entriesMap.forEach((value, key) => callbackfn.call(thisArg, value, key, this));
+    }
+    [Symbol.iterator]() { return this.entriesMap.entries(); }
+}

package/.pi-session-mcp-cli/mcp-config.js

@@ -0,0 +1,70 @@
+import { isAbsolute } from "node:path";
+const aliasPattern = /^[a-z][a-z0-9_-]{0,23}$/;
+const environmentPattern = /^[A-Z_][A-Z0-9_]{0,127}$/;
+export const MAX_MCP_SERVERS = 8;
+export const MAX_MCP_TOOLS = 64;
+export function mcpToolName(server, tool) {
+    return `mcp_${server}_${tool}`;
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function keysAre(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function text(value, maximum) {
+    return typeof value === "string" && value.length > 0 && value.length <= maximum && !value.includes("\0");
+}
+/** Also used at the adapter boundary: a manually constructed profile must not bypass policy. */
+export function isMcpServers(value, permissionProfile = "coding") {
+    if (permissionProfile !== "read-only" && permissionProfile !== "coding")
+        return false;
+    if (!record(value) || Object.keys(value).length > MAX_MCP_SERVERS)
+        return false;
+    const toolNames = new Set();
+    for (const [serverAlias, server] of Object.entries(value)) {
+        if (!aliasPattern.test(serverAlias) || !record(server) || !keysAre(server, ["command", "args", "envFrom", "tools"]))
+            return false;
+        if (!text(server.command, 4096) || !isAbsolute(server.command))
+            return false;
+        if (server.args !== undefined && (!Array.isArray(server.args) || server.args.length > 128
+            || !server.args.every((arg) => typeof arg === "string" && arg.length <= 4096 && !arg.includes("\0"))))
+            return false;
+        if (server.envFrom !== undefined && (!record(server.envFrom) || Object.keys(server.envFrom).length > 64
+            || !Object.entries(server.envFrom).every(([target, source]) => environmentPattern.test(target)
+                && typeof source === "string" && environmentPattern.test(source))))
+            return false;
+        if (!record(server.tools) || Object.keys(server.tools).length === 0)
+            return false;
+        const remoteNames = new Set();
+        for (const [toolAlias, grant] of Object.entries(server.tools)) {
+            if (!aliasPattern.test(toolAlias) || !record(grant) || !keysAre(grant, ["name", "readOnly"])
+                || !text(grant.name, 256) || typeof grant.readOnly !== "boolean")
+                return false;
+            if (permissionProfile === "read-only" && !grant.readOnly)
+                return false;
+            const exposedName = mcpToolName(serverAlias, toolAlias);
+            // Underscore-containing aliases can otherwise create cross-server name collisions.
+            if (toolNames.has(exposedName) || remoteNames.has(grant.name))
+                return false;
+            toolNames.add(exposedName);
+            remoteNames.add(grant.name);
+            if (toolNames.size > MAX_MCP_TOOLS)
+                return false;
+        }
+    }
+    return true;
+}
+export function snapshotMcpServers(servers) {
+    return Object.freeze(Object.fromEntries(Object.entries(servers).map(([alias, server]) => [alias, Object.freeze({
+            command: server.command,
+            args: Object.freeze([...(server.args ?? [])]),
+            envFrom: Object.freeze({ ...server.envFrom }),
+            tools: Object.freeze(Object.fromEntries(Object.entries(server.tools).map(([name, grant]) => [name, Object.freeze({ ...grant })]))),
+        })])));
+}
+/** Safe discovery metadata; never project commands, arguments, paths, or environment references. */
+export function configuredMcpToolNames(servers) {
+    return Object.entries(servers).flatMap(([server, config]) => Object.keys(config.tools).map((tool) => mcpToolName(server, tool))).sort();
+}

package/.pi-session-mcp-cli/package-metadata.js

@@ -0,0 +1,32 @@
+import packageMetadata from "../package.json" with { type: "json" };
+import { join } from "node:path";
+export const PACKAGE_NAME = packageMetadata.name;
+export const PACKAGE_VERSION = packageMetadata.version;
+export const PACKAGE_NODE_ENGINE = packageMetadata.engines.node;
+export function isMissingFile(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+/** The lockfile text of a Git checkout, or undefined for an npm installation. Other read errors propagate. */
+export async function readLockfile(packageRoot, readFile) {
+    try {
+        return await readFile(join(packageRoot, "package-lock.json"), "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Read the package and lock metadata using the same shape as production. */
+export async function readPackageMetadata(packageRoot, readFile) {
+    const packageJson = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+    const lockText = await readLockfile(packageRoot, readFile);
+    const lock = lockText === undefined ? undefined : JSON.parse(lockText);
+    const engines = packageJson.engines?.node;
+    const lockVersion = lock?.packages?.[""]?.version;
+    return {
+        version: packageJson.version,
+        engines: engines === undefined ? {} : { node: engines },
+        ...(lockVersion === undefined ? {} : { lockVersion: lockVersion }),
+    };
+}

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+## Unreleased
+
+## 0.6.2 — 2026-10-09
+
+- The server now shuts down when the MCP client closes its stdin. Previously
+  only `SIGINT` and `SIGTERM` ran the bounded shutdown, so after stdin EOF an
+  idle Pi session and its external MCP server kept running. EOF uses the same
+  15,000 ms shutdown and exits with status `0`; the first of EOF and a signal
+  sets the exit status. Public tools, fields, states and error codes are
+  unchanged.
+- Built on Pi SDK `1.1.0` (was `1.0.4`). Pi now retries `server_busy` provider
+  errors instead of ending the turn. The new `aborted` flag on settled runs is
+  not a closed terminal cause, so failed turns still report `turn_failed`.
+  Public tools, fields, states and error codes are unchanged.
+- Built on the MCP TypeScript SDK `2.3.1` (was `2.2.0`). Its packages are now
+  licensed under Apache-2.0 instead of MIT. The stdio entry point already
+  builds one server per connection, which the SDK now requires.
+- Validates with Zod `4.6.5` (was `4.5.4`), which fixes an out-of-memory
+  regression of Zod 4.5 in recursive schemas.
+- Development: MCP Inspector `2.10.1` (was the deprecated `0.19.0`). `npm run
+  inspect` works as before. Inspector 2.x keeps its catalog in
+  `~/.mcp-inspector/`; see the README for its secret storage. The lockfile
+  loses 216 packages and gains 89, and the earlier lockfile patches for
+  `proxy-addr`, `shell-quote` and `concurrently` leave the tree with the old
+  Inspector.
+- Development: TypeScript `7.0.2` (was `5.9.3`), Vitest `5.0.3` (was
+  `4.1.11`) and `@types/node` `22.20.5` (was `22.19.19`). The emitted
+  JavaScript is byte-identical to the TypeScript 5.9 build.
+- `setup` was re-recorded against Codex CLI `0.162.0` and Claude Code
+  `2.1.295`; their `mcp` command contracts are unchanged.
+
+## 0.6.1 — 2026-10-07
+
+- The stdio fixture tests no longer fail when they read a log line that the
+  fixture is still writing: only newline-terminated lines are parsed. Test-only
+  change.
+- Published as the npm package `pi-session-mcp` with the executables
+  `pi-session-mcp`, `pi-session-mcp-setup` and `pi-session-mcp-doctor`. The
+  package contains the built files, the documentation and the example
+  configuration, but no lockfile, because npm does not ship lockfiles inside
+  packages. Doctor and `setup` therefore accept an installation without a
+  lockfile, and the entry points start through npm's `bin` symlinks. Public
+  tools, fields, states and error codes are unchanged.
+
+## 0.6.0 — 2026-10-06
+
+- First public release, version `0.6.0`. Earlier 0.x versions were developed
+  privately; their history is not part of this repository.
+- Eight MCP tools over stdio for controlled Pi coding-agent sessions:
+  capability discovery, session start, list, get, prompt, abort and close, and
+  turn polling. Results and errors are sanitized and stable.
+- Operator-defined workspace aliases and execution profiles. A profile binds a
+  permission profile, a provider, a model and a thinking level, and can grant
+  individual tools of local stdio MCP servers to its sessions.
+- An offline `doctor` command and a reproducible `setup` command for Codex CLI
+  and Claude Code with plan, apply, verify, rollback and remove operations.
+  `setup` accepts clients by contract, not by version: it checks the client's
+  public `mcp` command output and fails closed on any unexpected output.
+- Built on Pi SDK `1.0.4` and the MCP TypeScript SDK `2.2.0`. A nightly canary
+  checks the sources against the newest published Pi SDK.

package/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Pi Session MCP is in maintenance mode: defects and upstream drift get focused
+fixes, and no new feature phase is planned. The reasons and the conditions for
+revisiting that decision are in
+[ADR 0003](docs/adr/0003-post-mvp-maintenance.md). Please open an issue before
+working on anything.
+
+## Development setup
+
+Linux and Node.js 22.19.0 or newer:
+
+```bash
+npm ci
+npm run typecheck
+npm run build:cli
+npm test
+npm run build
+```
+
+Tests use a fake Pi adapter or a scripted model. They need no provider
+credentials and no network access beyond the npm registry.
+
+## Rules
+
+The binding project rules are in [AGENTS.md](AGENTS.md). The most important
+ones:
+
+- TypeScript strict mode, ESM, and `.js` suffixes in relative imports.
+- Pin every direct dependency exactly. Do not use range prefixes.
+- Stdout carries MCP frames only. Diagnostics go to stderr and contain neither
+  secrets nor complete prompts.
+- Workspaces are reached only through configured aliases. No tool argument may
+  accept an arbitrary working directory.
+- Use only documented exports of the Pi SDK package root.
+- Write documentation in English.
+
+## Pull requests
+
+Pull requests are limited to collaborators. If you are not a collaborator and
+want to contribute a fix, open an issue that describes it.
+
+- Keep a pull request to one focused change, and say which issue it addresses.
+- Run the checks above and `npm audit` before opening it.
+- Describe what you verified and how. State only what was run: provider-free
+  tests do not establish live client or model behavior.
+- Never put credentials, prompts, transcripts, absolute local paths or raw
+  provider errors into issues, pull requests, tests or logs.
+
+Updating the Pi SDK pin, recording a client contract and patching audit
+advisories each have a procedure in [Releasing](docs/releasing.md). The
+acceptance levels are defined in [Acceptance](docs/acceptance.md).
+
+## Security
+
+Do not report vulnerabilities in public issues. See the
+[security policy](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 plagor44-ux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.