@llblab/pi-kit 0.21.2 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.22.0 - 2026-09-23
+
+- `Named npm Extensions`: Advances the exact Clean Room pin to `0.2.0`. `/clean-room <package-name>` now loads installed npm Pi extensions by name, including scoped packages, while preserving explicit resource isolation and project-local precedence.
+- `Model Selection`: Starting an empty clean room from a model registered by an excluded extension no longer fails. When built-in models remain in scope, the child receives only valid entries instead of warnings for stale or excluded-provider patterns; other model providers remain selectable through `/model` when loaded explicitly.
+- `Package Cohort`: Keeps every other bundled package at its current exact version. Package membership, entrypoint order, Skill ownership, and the Pi minimum remain unchanged.
+
 ## 0.21.2 - 2026-09-23
 
 - `Backup Push Reliability`: Advances the exact State Flow pin to `0.18.1`. Backup replication permits one in-flight push per repository; overlapping attempts are skipped until a later accepted turn, while session shutdown waits for the active process to close. Canonical state acceptance remains independent of Git replication.

package/README.md

@@ -11,7 +11,7 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | Package | Version | Purpose |
 | --- | ---: | --- |
 | [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.53.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
-| [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
+| [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.2.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
 | [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.18.1` | Incremental scoped context/memory compiler with independent scope revisions, canonical file persistence, bounded and diagnosable Git backup replication, native working context within each run, and targeted historical reads |

package/node_modules/@llblab/pi-clean-room/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0: Named npm extensions and isolated model selection
+
+- Launch installed npm extensions by package name, including scoped packages, without exposing their other resources to the clean room.
+- Start clean rooms from extension-backed parent models without failing on excluded providers; when a built-in model scope remains, pass only its valid entries to avoid child startup warnings from stale patterns.
+
 ## 0.1.1: Isolation and terminal recovery fixes
 
 - Keep unselected append-system context excluded when selected global prompt files are missing.

package/node_modules/@llblab/pi-clean-room/README.md

@@ -6,7 +6,7 @@ Launch a fresh, isolated Pi TUI with only the extensions you explicitly select.
 
 ## Installation
 
-Requirements: Pi `0.84.4–0.84.x` and Node.js `22.19.0` or newer.
+Requirements: Pi `0.84.4` or newer and Node.js `22.19.0` or newer.
 
 Install from npm:
 
@@ -32,6 +32,7 @@ Install or load this extension, then run:
 /clean-room skills agents system append-system
 /clean-room skills pi-extension-name pi-actors
 /clean-room skills/brain-storm
+/clean-room pi-awesome-extension
 ```
 
 Arguments may be extension names or resource switches:
@@ -42,9 +43,9 @@ Arguments may be extension names or resource switches:
 - `system` — use `~/.pi/agent/SYSTEM.md`
 - `append-system` — include `~/.pi/agent/APPEND_SYSTEM.md`
 
-Extension names are resolved from the global or project-local extensions directory. Absolute and working-directory-relative extension paths are also accepted. Project-local names take precedence over global names. Source-file names resolve consistently across `.ts`, `.js`, `.mts`, `.mjs`, `.cts`, and `.cjs`.
+Extension names are resolved from project-local extensions first, then global extensions, then locally installed npm Pi packages (project-local before global). For example, `/clean-room pi-awesome-extension` loads that package's declared extension entries without loading its other resources. Absolute and working-directory-relative extension paths are also accepted. Source-file names resolve consistently across `.ts`, `.js`, `.mts`, `.mjs`, `.cts`, and `.cjs`.
 
-The nested Pi starts in the current working directory with the current model and thinking level. All optional resources are disabled unless named explicitly. Pi's built-in system prompt and built-in tools remain available. Missing selected global prompt files contribute no content; unselected prompt files remain excluded.
+The nested Pi starts in the current working directory with the current thinking level. It retains the current model unless that model's provider was registered by a parent extension, which may not be loaded in the clean room; in that case Pi selects an available model. Model-cycling scope is inherited from the parent's resolved available models, excluding providers registered by parent-only extensions. When the filtered scope is nonempty, invalid or excluded-provider patterns are not forwarded to the child. `/model` shows all models available in the child; use it to choose a provider loaded by a named extension even when that provider is not in the inherited scope. Built-in model providers remain available without extensions. All optional resources are disabled unless named explicitly. Pi's built-in system prompt and built-in tools remain available. Missing selected global prompt files contribute no content; unselected prompt files remain excluded.
 
 Exit the nested TUI normally with `Ctrl+D` to return to the parent session. Launch failures and signal termination are reported after restoring the parent TUI.
 

package/node_modules/@llblab/pi-clean-room/index.ts

@@ -12,6 +12,40 @@ import {
 const EMPTY_COMPONENT = { render: () => [], invalidate: () => {} };
 const EXTENSION_SUFFIXES = [".ts", ".js", ".mts", ".mjs", ".cts", ".cjs"];
 
+function npmPackageRoots(cwd: string, agentDir: string): string[] {
+	return [join(cwd, CONFIG_DIR_NAME, "npm", "node_modules"), join(agentDir, "npm", "node_modules")];
+}
+
+function installedExtensionPackage(name: string, root: string): string | undefined {
+	if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(name) || name === "." || name === "..") return undefined;
+	const path = join(root, name);
+	try {
+		const manifest = JSON.parse(readFileSync(join(path, "package.json"), "utf8"));
+		if (manifest.name !== name) return undefined;
+		if (Array.isArray(manifest.pi?.extensions) && manifest.pi.extensions.length > 0) return path;
+		if (!manifest.pi && existsSync(join(path, "extensions"))) return path;
+	} catch {
+		// Missing or invalid npm package manifest.
+	}
+	return undefined;
+}
+
+function discoverInstalledExtensionNames(cwd: string, agentDir: string): string[] {
+	const names = new Set<string>();
+	for (const root of npmPackageRoots(cwd, agentDir)) {
+		if (!existsSync(root)) continue;
+		for (const entry of readdirSync(root, { withFileTypes: true })) {
+			if (entry.name.startsWith("@") && entry.isDirectory()) {
+				for (const child of readdirSync(join(root, entry.name), { withFileTypes: true })) {
+					const name = `${entry.name}/${child.name}`;
+					if (child.isDirectory() && installedExtensionPackage(name, root)) names.add(name);
+				}
+			} else if (entry.isDirectory() && installedExtensionPackage(entry.name, root)) names.add(entry.name);
+		}
+	}
+	return [...names];
+}
+
 export function discoverExtensionNames(cwd: string, agentDir = getAgentDir()): string[] {
 	const roots = [join(agentDir, "extensions"), join(cwd, CONFIG_DIR_NAME, "extensions")];
 	const names = new Set<string>();
@@ -23,6 +57,7 @@ export function discoverExtensionNames(cwd: string, agentDir = getAgentDir()): s
 			if (entry.isFile() && suffix) names.add(entry.name.slice(0, -suffix.length));
 		}
 	}
+	for (const name of discoverInstalledExtensionNames(cwd, agentDir)) names.add(name);
 	return [...names].sort();
 }
 
@@ -36,6 +71,10 @@ export function resolveExtension(source: string, cwd: string, agentDir = getAgen
 			if (existsSync(candidate)) return candidate;
 		}
 	}
+	for (const root of npmPackageRoots(cwd, agentDir)) {
+		const path = installedExtensionPackage(source, root);
+		if (path) return path;
+	}
 	return undefined;
 }
 
@@ -96,7 +135,12 @@ function launchCleanRoom(
 	resources: ReadonlySet<ResourceArgument>,
 	skills: string[],
 ) {
-	const args = buildCleanRoomArgs(extensionPaths, ctx.model, ctx.thinkingLevel, resources, getAgentDir(), skills);
+	// Providers registered by parent extensions may not exist in the isolated child.
+	const extensionProviders = new Set(ctx.modelRegistry.getRegisteredProviderIds());
+	const model = ctx.model && !extensionProviders.has(ctx.model.provider) ? ctx.model : undefined;
+	const scopedModels = ctx.scopedModels?.filter(({ model }) => !extensionProviders.has(model.provider));
+	const args = buildCleanRoomArgs(extensionPaths, model, ctx.thinkingLevel, resources, getAgentDir(), skills);
+	if (scopedModels?.length) args.push("--models", scopedModels.map(({ model }) => `${model.provider}/${model.id}`).join(","));
 	const cliEntry = process.argv[1];
 	const command = cliEntry && existsSync(cliEntry) ? process.execPath : "pi";
 	const commandArgs = cliEntry && existsSync(cliEntry) ? [cliEntry, ...args] : args;

package/node_modules/@llblab/pi-clean-room/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-clean-room",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "Launch an isolated Pi TUI with only explicitly selected extensions",
   "keywords": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "@llblab/pi-actors": "0.53.0",
-    "@llblab/pi-clean-room": "0.1.1",
+    "@llblab/pi-clean-room": "0.2.0",
     "@llblab/pi-codex-usage": "0.10.0",
     "@llblab/pi-grow-loop": "0.8.1",
     "@llblab/pi-state-flow": "0.18.1",