@herbertgao/pi-extensions 2026.9.2 → 2026.9.4

package/node_modules/@herbertgao/sol-pi/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-Party Notices
+
+SoL-Pi does not vendor third-party source code. Its npm tarball contains only SoL-Pi source, documentation, tests-excluded assets, and project metadata.
+
+## Runtime peer dependencies
+
+The following packages are supplied by the user's Pi installation and retain their own licenses:
+
+| Package | Development-tested version | License | Source |
+| --- | ---: | --- | --- |
+| `@earendil-works/pi-agent-core` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-ai` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-coding-agent` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `@earendil-works/pi-tui` | 0.84.2 | MIT | <https://github.com/earendil-works/pi> |
+| `typebox` | 1.3.7 | MIT | <https://github.com/sinclairzx81/typebox> |
+
+## Development-only dependencies
+
+`@types/node` (MIT), TypeScript (Apache-2.0), and Vitest (MIT) are used to type-check and test the repository. They are not included in the SoL-Pi npm tarball. Exact versions and transitive dependency metadata are recorded in `package-lock.json`.

package/node_modules/@herbertgao/sol-pi/agents-install.md

@@ -0,0 +1,150 @@
+# SoL-Pi Agent Installation and Configuration Protocol
+
+This is the canonical procedure for Codex, Claude Code, and other coding agents that install, configure, or validate SoL-Pi from a full source checkout. Follow the phases in order. Explicit user instructions take precedence. An extracted npm package is not a substitute for the checkout because it does not contain the test suite.
+
+Installation and configuration are complete only when Pi remains unmodified, the repository checks pass, Pi lists the package, all four mechanisms are enabled in one effective `sol-pi.json`, and Pi starts without an extension error.
+
+## Rules
+
+- Do not modify, patch, fork, or vendor upstream Pi. SoL-Pi must load as a standalone extension through Pi's public package interface.
+- Use Node.js 22.19 or newer and the tested Pi release `@earendil-works/pi-coding-agent@0.84.2`. Treat a different Pi version as a compatibility change and rerun the full suite before using it.
+- Do not clean, reset, switch, or overwrite unrelated repository changes.
+- Do not print, log, commit, upload, or include any secret in a command line. Check only whether a credential is present.
+- Keep SoL-Pi settings in `sol-pi.json`. The Evidence-Preserving Reducer provider/model route is a SoL-Pi setting; provider URLs, credentials, the main agent model, and shell behavior remain Pi settings.
+- Keep persistent artifacts under Pi's session-derived `sol-pi/<session-id>/` root; do not configure a separate storage path.
+
+## Inputs
+
+Resolve these values before making changes:
+
+- `sol_pi_root`: absolute path to the intended SoL-Pi checkout;
+- `target_project`: project in which Pi will run;
+- install scope: project-local or user-wide;
+- exact SoL-Pi branch and commit.
+
+Do not guess an ambiguous path or install scope.
+
+## Phase 1: validate the checkout
+
+From `sol_pi_root`, record the repository state without changing it:
+
+```bash
+git status --short --branch
+git rev-parse HEAD
+node --version
+npm --version
+```
+
+Require Node.js 22.19 or newer. Install from the lockfile and run the source checks:
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm audit --audit-level=high
+node scripts/check-pi-compat.mjs
+npx vitest run tests/all-mechanisms.test.ts
+```
+
+`npm run check` covers type checking, the complete test suite, and package inspection. `tests/all-mechanisms.test.ts` confirms that one all-enabled configuration registers all four mechanisms against Pi's public extension API. The tests run without a model provider.
+
+Stop if any command fails. Do not hide a failure with `|| true` or replace `npm ci` with an unlocked install.
+
+## Phase 2: install Pi and SoL-Pi
+
+Install the tested Pi release without changing its source:
+
+```bash
+npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.84.2
+pi --version
+```
+
+Require `pi --version` to report `0.84.2`.
+
+For a project-local registration, run this from `target_project` and substitute the resolved absolute `sol_pi_root`:
+
+```bash
+pi install "/absolute/path/to/SoL-Pi" --local --approve
+pi list --approve
+```
+
+For a user-wide registration, omit `--local`:
+
+```bash
+pi install "/absolute/path/to/SoL-Pi" --approve
+pi list --approve
+```
+
+The `pi list` output must show the exact SoL-Pi source in the selected scope. Do not install the same checkout in both scopes. A project-local registration must run only in a trusted project; use `--approve` for automated invocations unless trust has already been explicitly persisted.
+
+## Phase 3: configure all four mechanisms
+
+SoL-Pi defaults every mechanism to disabled. For this managed installation, create exactly one effective configuration with every mechanism enabled:
+
+```json
+{
+  "version": 1,
+  "actionFusion": true,
+  "observationPack": true,
+  "evidencePreservingReducer": true,
+  "evidencePreservingReducerProvider": "provider-id",
+  "evidencePreservingReducerModel": "model-id",
+  "onlineContextCompact": true,
+  "cacheWriteReadRatio": 12.5
+}
+```
+
+`evidencePreservingReducerProvider` and `evidencePreservingReducerModel` select the nested reducer route that Evidence-Preserving Reducer resolves through Pi's model registry. They default to the built-in reducer route and must be non-empty strings when supplied. Change them only when a different reducer model is intended.
+
+`cacheWriteReadRatio` is the only pricing-related input SoL-Pi reads. It defaults to `12.5`, accepts any finite non-negative number, and treats `0` as an explicit statement that a cache write adds no cost relative to a cache read. SoL-Pi does not inspect Pi model prices. The value controls one compaction decision and is not a bill estimate. The default follows the GPT-5.6 Sol OpenAI Standard cache-write/read ratio checked on 2026-08-21; see [OpenAI API pricing](https://developers.openai.com/api/docs/pricing). Change it when a different policy is required.
+
+Use one location matching the selected scope. Resolve the directory through Pi; the official Pi defaults are shown in parentheses:
+
+- project-local: `<target_project>/<Pi config directory>/sol-pi.json` (`<target_project>/.pi/sol-pi.json`);
+- user-wide: `<Pi agent directory>/sol-pi.json` (`~/.pi/agent/sol-pi.json`).
+
+SoL-Pi uses Pi's public `CONFIG_DIR_NAME` and `getAgentDir()` APIs. Do not assume the defaults when Pi reports different directories.
+
+The project file replaces the user-wide file; the two are not merged. If both exist, inspect them and obtain direction before changing either one. Unknown keys, unsupported versions, malformed JSON, non-boolean feature values, invalid reducer model fields, and invalid ratios must remain fatal.
+
+Do not put provider URL, credentials, shell path, command prefix, storage path, or run ID in `sol-pi.json`. SoL-Pi either reads those values from Pi or derives them from the Pi session.
+
+SoL-Pi reads no dedicated environment variables. Evidence-Preserving Reducer uses the configured reducer provider/model route and Pi-managed authentication. Configure credentials in Pi and do not copy them into `sol-pi.json`.
+
+From `sol_pi_root`, validate the exact effective file:
+
+```bash
+node scripts/check-sol-pi-config.mjs \
+  --config /absolute/path/to/effective/sol-pi.json \
+  --require-all-enabled
+```
+
+Require exit status 0 and retain its JSON output. The check applies SoL-Pi's default values, rejects unknown keys and wrong types, and confirms all four mechanisms are enabled. A partially enabled file can be valid SoL-Pi configuration, but it does not satisfy this all-enabled profile.
+
+## Phase 4: verify the installation
+
+1. Run `pi list --approve` from `target_project` and confirm the expected SoL-Pi source and scope.
+2. Run `check-sol-pi-config.mjs --require-all-enabled` against the effective `sol-pi.json`.
+3. Re-run `npx vitest run tests/all-mechanisms.test.ts` from `sol_pi_root`.
+4. Start Pi with `--offline --approve`, send no prompt, confirm there is no extension load error, and exit.
+5. Confirm that upstream Pi was not patched and that the SoL-Pi checkout contains no vendored Pi monorepo source.
+
+## Completion report
+
+Report:
+
+- SoL-Pi absolute path, branch, and commit;
+- repository state before and after installation;
+- Node, npm, and Pi versions;
+- install scope and the exact entry shown by `pi list`;
+- effective config path, four enabled flags, EPR reducer provider/model, and `cacheWriteReadRatio`, without secrets;
+- every validation command and result;
+- any blocker or deviation.
+
+Do not describe the installation as successful if a required check is missing.
+
+## Agent entry files
+
+`agents-install.md` is the single source of truth, but agents do not universally auto-discover arbitrary filenames. Root `AGENTS.md` tells Codex to read this file, while root `CLAUDE.md` imports it for Claude Code. Keep those entry files short and keep executable installation details here.
+
+- [Codex `AGENTS.md` discovery](https://developers.openai.com/codex/guides/agents-md)
+- [Claude Code project memory and imports](https://docs.anthropic.com/zh-CN/docs/claude-code/memory)

package/node_modules/@herbertgao/sol-pi/docs/compatibility.md

@@ -0,0 +1,69 @@
+# Pi Compatibility
+
+SoL-Pi is developed and tested against `@earendil-works/pi-coding-agent` 0.84.2. Its public API surface is also type-checked and exercised against Pi 0.81.1, the base used by the original Pi fork. The runtime range is deliberately expressed as a peer dependency because Pi owns installation and upgrade of its packages.
+
+SoL-Pi imports only public package exports:
+
+- `createEditToolDefinition`
+- `createWriteToolDefinition`
+- `createBashToolDefinition`
+- extension types and `ExtensionAPI.registerTool`
+- `context`, `before_provider_request`, `tool_result`, `turn_end`, `agent_settled`, and `session_before_tree` extension events
+- native compaction events, `ExtensionContext.getContextUsage()`, and `ExtensionContext.compact()`
+- `ExtensionContext.model` and `ExtensionContext.modelRegistry`
+- the public session-manager methods exposed through `ExtensionContext`
+
+## Action Fusion
+
+The built-in edit/write definitions capture their working directory, so SoL-Pi caches one definition per `ctx.cwd`. Its own per-file queue surrounds the built-in mutation and follow-up command. It does not nest Pi's built-in mutation queue.
+
+Action Fusion decodes `file://` targets with Node's `fileURLToPath()` before resolving the queue and hash-check path. This keeps file URLs, including percent-encoded filenames and Pi's optional `@` prefix, aligned with the file handled by the built-in mutation tool.
+
+The queue covers only fused operations registered by this SoL-Pi instance. External processes, direct built-in-tool calls outside the replacement, and unrelated extensions are not globally locked. SoL-Pi hashes the target immediately before launching `then_run` and skips the command if it observes an intervening content change.
+
+When another extension already owns `write`, Action Fusion leaves that tool in place and only registers its `edit` replacement. When `pi-automode` exposes `automode_inspect`, Action Fusion registers neither mutation replacement: nested `then_run` cannot re-enter Pi's public `tool_call` permission pipeline, so disabling the fusion is the safe fallback.
+
+## ObservationPack
+
+ObservationPack changes only the messages projected through the public `context` event. Stored session history remains intact. Original bytes and the JSONL ledger live under the session-derived SoL-Pi directory.
+
+## Evidence-Preserving Reducer
+
+The reducer handles public `tool_result` events and resolves the configured reducer provider/model through Pi's model registry before calling `ExtensionContext.modelRegistry.complete()` when available. For the Pi 0.81.1 fork, which exposes no registry `complete()` method, it resolves authentication for that reducer model through `getApiKeyAndHeaders()` and calls the shared `@earendil-works/pi-ai/compat` completion API. The reducer preserves the original result whenever the configured reducer model is unavailable or eligibility, model-call, schema, source-hash, exact-quote, size, or likely-secret checks fail.
+
+All persistent paths use `SessionManager.getSessionDir()` and `getSessionId()`, which are present in both the fork and Pi 0.84.2. SoL-Pi creates no configurable storage-path surface.
+
+The unpublished shared artifact layout is not read or migrated. Each session starts from its own `<sessionDir>/sol-pi/<sessionId>/` directory.
+
+## Online Context Compact
+
+Online Context Compact uses ordinary public `context` and `before_provider_request` handlers instead of fork-only post-transform observer methods. Public handlers run in extension load order, so the SoL-Pi entrypoint registers Online Context Compact after its other context transformers. A third-party transformer loaded later is outside the context-growth observation used by its estimate.
+
+Before selecting or executing a boundary compaction, it also checks the optional `Symbol.for("pi-subagents:manager")` registry exposed by `pi-subagents`. A running top-level subagent, or an unreadable registry, suppresses that compaction rather than risking a context rewrite during delegated work. When the registry is absent, the check is a no-op.
+
+Pi does not expose its active retained-tail compaction setting through the public extension context. The standalone extension therefore uses the documented Pi 0.84.2 default of 20,000 tokens for its economic estimate. Its programmatic factory accepts an explicit matching value for a non-default Pi setting.
+
+Pi 0.84.2's `ExtensionContext.compact()` aborts the active agent before it summarizes, and `agent_settled` fires only once a whole run has drained every turn, retry, auto-compaction, and queued continuation. A plan boundary that selects compaction therefore saves its plan and progress state, calls `ExtensionContext.abort()` to stop the run, and runs compaction from the `agent_settled` that stop produces. The handler awaits the compaction's own `onComplete`/`onError` callbacks. On success, the extension sends a hidden reminder through public `ExtensionAPI.sendMessage()` with `triggerTurn: true`, so Pi starts a new turn against the compacted context and rebuilds the plan even when the native summary omits that instruction.
+
+A settlement barrier keeps the original `agent_settled` dispatch open until the triggered continuation settles. Print- and JSON-mode processes therefore complete the compact-and-continue sequence within the same Pi invocation; an outer driver does not need to resume the session or send `Continue working`. This continuation is armed only by a successful boundary compaction. Cancelling or exiting does not schedule one. A Pi build that never emits `agent_settled` starts no boundary compaction.
+
+Pi 0.84.2 does not return a promise from `ExtensionAPI.sendMessage()`. The barrier is therefore verified for standalone SoL-Pi and depends on Pi starting the requested turn synchronously. A later-loaded third-party extension that performs long asynchronous work in its own `agent_settled` handler is outside this guarantee and needs an integration test with that extension set.
+
+Pi reports the session as idle while an extension-requested manual compaction is running. SoL-Pi cancels `session_before_tree` during that interval to prevent tree navigation from moving the active leaf underneath the compaction. Navigation works normally after the compaction callback settles.
+
+Online Context Compact reads `ExtensionContext.getContextUsage()` for both the context window and the provider-counted context size. When Pi reports no size — as it does between a compaction and the next answered request — the boundary falls back to its own estimate.
+
+The standalone entry passes `cacheWriteReadRatio` from `sol-pi.json` directly into Online Context Compact's economic check. It does not inspect model price metadata. Changing models during a session does not change the ratio; users who want a different decision policy update the configuration and start a new session.
+
+## Interactive TUI
+
+The lightning savings treatment uses Pi 0.84.2's public `renderCall`,
+`renderResult`, `ctx.ui.notify()`, and keyed `ctx.ui.setStatus()` APIs. It checks
+`ctx.mode === "tui"` rather than `ctx.hasUI`, because RPC mode also reports UI
+support. The renderer therefore changes only the interactive terminal display;
+it does not change session messages, provider requests, tool results, JSON
+events, print output, or RPC UI requests.
+
+## Test doubles
+
+The test suite drives every extension through the same public `ExtensionAPI` and `ExtensionContext` surface Pi provides, over a real public `SessionManager`, with no provider registered. That keeps the suite zero-spend and independent of the deleted Pi monorepo test harness. Suites that need a genuine session tree — branch order, compaction entries, custom entries, resume — use `SessionManager.inMemory()` or `SessionManager.create()` rather than reimplementing them.

package/node_modules/@herbertgao/sol-pi/docs/configuration.md

@@ -0,0 +1,75 @@
+# Configuration
+
+SoL-Pi reads one effective JSON configuration file at extension startup. It uses Pi's public `CONFIG_DIR_NAME` and `getAgentDir()` APIs rather than assuming fixed directories.
+
+## Search order
+
+1. `<working-directory>/<Pi config directory>/sol-pi.json`, only after Pi marks the project trusted
+2. `<Pi agent directory>/sol-pi.json`
+3. Built-in defaults when neither file exists
+
+For the official Pi distribution, the first two locations normally resolve to `.pi/sol-pi.json` and `~/.pi/agent/sol-pi.json`.
+
+The project file replaces the global file. SoL-Pi does not merge them.
+
+## Schema
+
+```json
+{
+  "version": 1,
+  "actionFusion": false,
+  "observationPack": false,
+  "evidencePreservingReducer": false,
+  "evidencePreservingReducerProvider": "provider-id",
+  "evidencePreservingReducerModel": "model-id",
+  "onlineContextCompact": false,
+  "cacheWriteReadRatio": 12.5
+}
+```
+
+Feature keys may be omitted and then default to `false`. `cacheWriteReadRatio` may be omitted and then defaults to `12.5`; when present it must be a finite non-negative number, and `0` explicitly means that a cache write adds no cost relative to a cache read. `evidencePreservingReducerProvider` and `evidencePreservingReducerModel` may be omitted and then use the built-in reducer route; when present each must be a non-empty string. Unknown keys, unsupported versions, malformed JSON, non-boolean feature values, invalid ratios, and invalid reducer model fields stop extension loading with a direct error.
+
+For the managed all-enabled installation described in the [agent installation and configuration protocol](../agents-install.md), validate the effective file before starting Pi:
+
+```bash
+node scripts/check-sol-pi-config.mjs \
+  --config /absolute/path/to/effective/sol-pi.json \
+  --require-all-enabled
+```
+
+This preflight does not make every valid SoL-Pi configuration all-enabled. Without `--require-all-enabled`, omitted feature keys retain their normal `false` defaults. The managed workflow uses the flag because its acceptance criterion is that all four mechanisms are active.
+
+## Feature behavior
+
+- `actionFusion`: registers SoL-Pi replacements for Pi's `edit` and `write` tools.
+- `observationPack`: registers `obs_recall` and a provider-context projection handler.
+- `evidencePreservingReducer`: registers a `tool_result` handler and delegates long diagnostic-log reduction to the configured reducer provider/model.
+- `evidencePreservingReducerProvider`: provider namespace used to resolve the reducer model through Pi's model registry.
+- `evidencePreservingReducerModel`: model id used for Evidence-Preserving Reducer.
+- `onlineContextCompact`: registers `update_plan` and boundary-driven native compaction after the other SoL-Pi context transformers.
+- `cacheWriteReadRatio`: supplies the single economic decision ratio used by Online Context Compact.
+
+## Evidence-Preserving Reducer runtime inputs
+
+The release entry supplies the run label and session-derived storage. It uses one configurable model route:
+
+- **Reducer provider/model** — from `evidencePreservingReducerProvider` and `evidencePreservingReducerModel` in the effective `sol-pi.json`. If omitted, SoL-Pi uses its built-in reducer route. SoL-Pi resolves that model through Pi's model registry and still relies on Pi-managed authentication; do not put credentials in `sol-pi.json`.
+
+## Online Context Compact runtime inputs
+
+The release entry uses two runtime inputs:
+
+- **Context window** — from `ExtensionContext.getContextUsage()`, used for window-pressure protection.
+- **Cache write/read ratio** — from `cacheWriteReadRatio` in the effective `sol-pi.json`. The value remains fixed for the session and is not recomputed when the model changes. It drives one runtime decision and is not a cost report.
+
+The configured ratio stays fixed for the loaded extension. The mechanism stores its current plan, progress summaries, request horizon, context growth, and compaction debt as versioned custom entries in Pi's session log. After a successful compaction it sends one hidden, generic message with `triggerTurn: true`, which starts a new turn and instructs the assistant to rebuild its plan. A settlement barrier keeps print and JSON modes in the same Pi invocation until that continuation settles, so callers do not need to resume the session or inject `Continue working`. Cancelling or exiting does not schedule an automatic continuation. The mechanism creates no separate Online Context Compact files. The programmatic factory exposes only a matching retained-tail value for installations whose Pi compaction setting differs from the default.
+
+## Pi integration
+
+SoL-Pi reads no dedicated environment variables. Evidence-Preserving Reducer resolves its configured reducer provider/model through `ExtensionContext.modelRegistry` and uses Pi-managed authentication. If the configured reducer model is unavailable or the nested model call fails, the original tool result continues unchanged.
+
+SoL-Pi does not configure shell paths, command prefixes, storage paths, run IDs, provider URLs, reasoning levels, timeouts, or per-mechanism enable flags through environment variables. Apart from the EPR reducer provider/model route in `sol-pi.json`, model selection remains with Pi. Action Fusion uses Pi's default shell behavior. Persistent artifacts are derived from Pi's session directory and session ID.
+
+## Trust
+
+A project-local config can enable file mutation, shell execution, local archival, and remote diagnostic-log reduction. SoL-Pi waits for Pi's `session_start` context and ignores the project file unless `ctx.isProjectTrusted()` is true. Prefer the global file when you want one personal configuration across trusted projects.

package/node_modules/@herbertgao/sol-pi/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@herbertgao/sol-pi",
+  "version": "0.2.0",
+  "description": "Token-efficient context and tool extensions for Pi, maintained from NVlabs/SoL-Pi.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "context-management",
+    "token-efficiency"
+  ],
+  "homepage": "https://github.com/HerbertGao/pi-extensions/tree/master/packages/sol-pi#readme",
+  "bugs": {
+    "url": "https://github.com/HerbertGao/pi-extensions/issues"
+  },
+  "license": "MIT",
+  "author": "Herbert Gao",
+  "contributors": [
+    "NVIDIA Corporation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HerbertGao/pi-extensions.git",
+    "directory": "packages/sol-pi"
+  },
+  "files": [
+    "src/sol-pi",
+    "assets",
+    "docs/compatibility.md",
+    "docs/configuration.md",
+    "scripts/check-pi-compat.mjs",
+    "scripts/check-sol-pi-config.mjs",
+    "agents-install.md",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "THIRD_PARTY_NOTICES.md",
+    "sol-pi.example.json"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test && npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.84.2",
+    "@earendil-works/pi-ai": ">=0.84.2",
+    "@earendil-works/pi-coding-agent": ">=0.84.2",
+    "@earendil-works/pi-tui": ">=0.84.2",
+    "typebox": ">=1.3.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/sol-pi/index.ts"
+    ]
+  },
+  "x-upstream": {
+    "package": "sol-pi",
+    "version": "0.1.0",
+    "reviewedVersion": "0.1.0",
+    "repository": "https://github.com/NVlabs/SoL-Pi",
+    "commit": "22277b7e0c3c46ba1259a6687f31fe39ade421a5"
+  }
+}

package/node_modules/@herbertgao/sol-pi/scripts/check-pi-compat.mjs

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+	CONFIG_DIR_NAME,
+	ModelRegistry,
+	SessionManager,
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createWriteToolDefinition,
+	getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import { complete as completeCompat } from "@earendil-works/pi-ai/compat";
+
+for (const [name, value] of Object.entries({
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createWriteToolDefinition,
+	getApiKeyAndHeaders: ModelRegistry.prototype.getApiKeyAndHeaders,
+	getAgentDir,
+	piAiCompatComplete: completeCompat,
+	sessionManagerGetSessionDir: SessionManager.prototype.getSessionDir,
+	sessionManagerGetSessionId: SessionManager.prototype.getSessionId,
+})) {
+	if (typeof value !== "function") throw new Error(`Missing public Pi API: ${name}`);
+}
+
+if (typeof CONFIG_DIR_NAME !== "string" || CONFIG_DIR_NAME.length === 0) {
+	throw new Error("Missing public Pi API: CONFIG_DIR_NAME");
+}

package/node_modules/@herbertgao/sol-pi/scripts/check-sol-pi-config.mjs

@@ -0,0 +1,120 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const FEATURE_KEYS = [
+	"actionFusion",
+	"observationPack",
+	"evidencePreservingReducer",
+	"onlineContextCompact",
+];
+const DEFAULT_CACHE_WRITE_READ_RATIO = 12.5;
+const DEFAULT_EPR_REDUCER_PROVIDER = ["openai", "codex"].join("-");
+const DEFAULT_EPR_REDUCER_MODEL = ["gpt-5.6", "luna"].join("-");
+const STRING_KEYS = ["evidencePreservingReducerModel", "evidencePreservingReducerProvider"];
+const CONFIG_KEYS = new Set(["version", ...FEATURE_KEYS, ...STRING_KEYS, "cacheWriteReadRatio"]);
+
+function fail(message) {
+	throw new Error(message);
+}
+
+function parseArguments(argv) {
+	const options = { config: undefined, requireAllEnabled: false };
+	const seen = new Set();
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		if (seen.has(argument)) fail(`duplicate option: ${argument}`);
+		if (argument === "--require-all-enabled") {
+			seen.add(argument);
+			options.requireAllEnabled = true;
+			continue;
+		}
+		if (argument !== "--config") fail(`unknown option: ${argument}`);
+		seen.add(argument);
+		const value = argv[index + 1];
+		if (!value || value.startsWith("--")) fail("missing value for --config");
+		options.config = value;
+		index += 1;
+	}
+	if (!options.config) fail("--config is required");
+	return options;
+}
+
+function readConfig(path) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch (error) {
+		fail(`unable to read config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		fail(`invalid JSON in config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+function validateConfig(value, requireAllEnabled) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		fail("config must be a JSON object");
+	}
+	for (const key of Object.keys(value)) {
+		if (!CONFIG_KEYS.has(key)) fail(`unknown key: ${key}`);
+	}
+	if (value.version !== 1) fail("version must be 1");
+
+	const effective = { version: 1 };
+	for (const key of FEATURE_KEYS) {
+		const configured = value[key];
+		if (configured !== undefined && typeof configured !== "boolean") fail(`${key} must be boolean`);
+		effective[key] = configured ?? false;
+		if (requireAllEnabled && effective[key] !== true) fail(`${key} must be true`);
+	}
+	const cacheWriteReadRatio = Object.hasOwn(value, "cacheWriteReadRatio")
+		? value.cacheWriteReadRatio
+		: DEFAULT_CACHE_WRITE_READ_RATIO;
+	if (
+		typeof cacheWriteReadRatio !== "number" ||
+		!Number.isFinite(cacheWriteReadRatio) ||
+		cacheWriteReadRatio < 0
+	) {
+		fail("cacheWriteReadRatio must be a finite non-negative number");
+	}
+	effective.cacheWriteReadRatio = cacheWriteReadRatio;
+	effective.evidencePreservingReducerModel = stringConfigValue(
+		value,
+		"evidencePreservingReducerModel",
+		DEFAULT_EPR_REDUCER_MODEL,
+	);
+	effective.evidencePreservingReducerProvider = stringConfigValue(
+		value,
+		"evidencePreservingReducerProvider",
+		DEFAULT_EPR_REDUCER_PROVIDER,
+	);
+
+	return {
+		ok: true,
+		all_enabled: FEATURE_KEYS.every((key) => effective[key] === true),
+		effective_config: effective,
+	};
+}
+
+function stringConfigValue(value, key, defaultValue) {
+	const configured = Object.hasOwn(value, key) ? value[key] : defaultValue;
+	if (typeof configured !== "string" || configured.trim().length === 0) fail(`${key} must be a non-empty string`);
+	return configured;
+}
+
+try {
+	const options = parseArguments(process.argv.slice(2));
+	const configPath = resolve(options.config);
+	const result = validateConfig(readConfig(configPath), options.requireAllEnabled);
+	console.log(JSON.stringify({ ...result, config: configPath }, null, 2));
+} catch (error) {
+	console.error(`SoL-Pi configuration preflight failed: ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+}

package/node_modules/@herbertgao/sol-pi/sol-pi.example.json

@@ -0,0 +1,10 @@
+{
+	"version": 1,
+	"actionFusion": false,
+	"observationPack": false,
+	"evidencePreservingReducer": false,
+	"evidencePreservingReducerProvider": "provider-id",
+	"evidencePreservingReducerModel": "model-id",
+	"onlineContextCompact": false,
+	"cacheWriteReadRatio": 12.5
+}