@aeondave/pi-skill-optimizer 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes are documented here.
 
+## 3.0.1 - 2026-09-30
+
+### Fixed
+
+- Keep Pi 0.99's initially inactive `deferred` and `codemode` tools discoverable through the optimizer's `tool_search`. Activate only matching search results, retain them across later replanning, and leave initially unavailable direct or hidden tools outside the catalog.
+- Reject blank tool searches without activating fallback results. Document how to disable Pi's replaceable built-in `tool-search` at the same scope as the optimizer, avoiding its startup conflict warning.
+
 ## 3.0.0 - 2026-09-28
 
 ### Scoped distribution - 2026-09-29

package/README.md

@@ -26,12 +26,19 @@ Restart Pi, then check that it loaded:
 /skill-optimizer
 ```
 
+Pi 0.99.0+ also includes a built-in `tool-search` extension. This optimizer provides
+its own `tool_search`, so disable the built-in under **Built-in extensions** in
+`pi config` to avoid the startup conflict warning. Use the global setting for a
+personal install, or `pi config -l` for a project-only install. The optimizer
+continues to find registered `deferred` and `codemode` tools. See the
+[tool-search configuration](docs/CONFIGURATION.md#replacing-the-built-in-tool-search).
+
 That's enough to start. Optionally run `/skill-optimizer init` to generate routing hints for your library. **Init uses your current Pi model and may incur cost**; normal discovery does not.
 
 | Need | Command |
 | --- | --- |
 | Install only in this project | `pi install -l npm:@aeondave/pi-skill-optimizer` |
-| Pin the current release | `pi install npm:@aeondave/pi-skill-optimizer@3.0.0` |
+| Pin the current release | `pi install npm:@aeondave/pi-skill-optimizer@3.0.1` |
 | Update an unpinned install | `pi update npm:@aeondave/pi-skill-optimizer` |
 
 Restart after updating. Pinned installs stay pinned until you explicitly install another version.

package/docs/CONFIGURATION.md

@@ -14,6 +14,12 @@ Exact skill loading accepts only registered names. Resource and location resolut
 
 `excludeSkills` removes names from discovery and search, not from explicit exact loading. It is a routing preference, not an access-control boundary. The three resolver tools return their content without another output-reduction pass, so full skill instructions and recovered originals remain readable.
 
+### Replacing the built-in tool search
+
+The extension registers `tool_search` itself, so it replaces Pi's built-in `builtin:tool-search` extension (the built-in is marked replaceable and the tool name decides). While both are in the load set, Pi prints a startup warning that the built-in was not loaded. The optimizer indexes eligible registered tools, including ones it deferred from Pi's active set and Pi-registered `deferred` or `codemode` tools. Matching inactive results activate additively; unrelated fallback results remain inactive. Pi's built-in MCP extension can still activate `tool_search` by name when a deferred server connects.
+
+To silence the warning, disable the built-in where the optimizer runs: toggle `tool-search` off under Built-in extensions in `pi config`, or set `"extensions": ["-builtin:tool-search"]` in the applicable `settings.json`. A personal install needs the global setting in `~/.pi/agent/settings.json`; a project-only install can use `.pi/settings.json`. For development with `pi -e ./src/index.ts`, set the toggle locally or globally. Re-enable the built-in if you remove the optimizer.
+
 ## Commands
 
 | Command | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeondave/pi-skill-optimizer",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "private": false,
   "type": "module",
   "description": "Less repeated context for Pi: local skill routing, on-demand tools, and recoverable output reduction.",
@@ -80,6 +80,6 @@
     "extensions": [
       "./src/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-skill-optimizer/v3.0.0/assets/banner.png"
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-skill-optimizer/v3.0.1/assets/banner.png"
   }
 }

package/src/index.ts

@@ -112,6 +112,14 @@ const MAX_SEEN_EVIDENCE = 4_096;
 const MAX_HISTORY_ARTIFACTS = 128;
 const PROTECTED_RUNTIME_TOOLS = ["skill_search", "tool_search", "retrieve_output"] as const;
 
+function isHostSearchableTool(tool: object): boolean {
+	return "exposure" in tool && (tool.exposure === "deferred" || tool.exposure === "codemode");
+}
+
+function isHostHiddenTool(tool: object): boolean {
+	return "exposure" in tool && tool.exposure === "hidden";
+}
+
 type ConfigRecord = ReturnType<typeof getConfig>;
 
 const EMPTY_STORED_PROFILE: StoredProfile = {
@@ -565,12 +573,20 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 	};
 
 	const rebuildToolCatalog = (state: RuntimeSnapshot): ToolDiscoveryCatalog => {
+		const allTools = pi.getAllTools();
 		permittedToolNames ??= new Set([
 			...pi.getActiveTools().map((name) => name.toLowerCase()),
 			...PROTECTED_RUNTIME_TOOLS,
 		]);
-		const discoverable = pi.getAllTools().filter((tool) =>
-			permittedToolNames?.has(tool.name.toLowerCase()),
+		for (const tool of allTools) {
+			if (!isHostHiddenTool(tool)) continue;
+			const name = tool.name.toLowerCase();
+			permittedToolNames.delete(name);
+			retainedToolNames.delete(name);
+			deactivatedToolNames.delete(name);
+		}
+		const discoverable = allTools.filter((tool) =>
+			!isHostHiddenTool(tool) && permittedToolNames?.has(tool.name.toLowerCase()),
 		);
 		toolCatalog = buildToolDiscoveryCatalog(discoverable, {
 			protect: [...PROTECTED_RUNTIME_TOOLS, ...state.config.alwaysTools],
@@ -578,13 +594,25 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 		return toolCatalog;
 	};
 
+	const buildToolSearchCatalog = (state: RuntimeSnapshot): ToolDiscoveryCatalog => {
+		rebuildToolCatalog(state);
+		return buildToolDiscoveryCatalog(pi.getAllTools().filter((tool) =>
+			!isHostHiddenTool(tool)
+				&& (permittedToolNames?.has(tool.name.toLowerCase()) || isHostSearchableTool(tool)),
+		), {
+			protect: [...PROTECTED_RUNTIME_TOOLS, ...state.config.alwaysTools],
+		});
+	};
+
 	const activateAdditively = (names: readonly string[]): string[] => {
 		const requested = new Set(names.map((name) => name.toLowerCase()));
 		const current = new Set(pi.getActiveTools().map((name) => name.toLowerCase()));
 		const added: string[] = [];
 		for (const tool of pi.getAllTools()) {
-			if (!permittedToolNames?.has(tool.name.toLowerCase())) continue;
+			if (isHostHiddenTool(tool)) continue;
+			if (!permittedToolNames?.has(tool.name.toLowerCase()) && !isHostSearchableTool(tool)) continue;
 			if (!requested.has(tool.name.toLowerCase())) continue;
+			permittedToolNames?.add(tool.name.toLowerCase());
 			retainedToolNames.add(tool.name.toLowerCase());
 			if (current.has(tool.name.toLowerCase())) continue;
 			current.add(tool.name.toLowerCase());
@@ -592,8 +620,8 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 			added.push(tool.name);
 		}
 		const ordered = pi.getAllTools()
-			.map((tool) => tool.name)
-			.filter((name) => permittedToolNames?.has(name.toLowerCase()) && current.has(name.toLowerCase()));
+			.filter((tool) => !isHostHiddenTool(tool) && current.has(tool.name.toLowerCase()))
+			.map((tool) => tool.name);
 		pi.setActiveTools(ordered);
 		return added;
 	};
@@ -607,8 +635,8 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 		for (const name of deactivatedToolNames) active.add(name);
 		pi.setActiveTools(
 			pi.getAllTools()
-				.map((tool) => tool.name)
-				.filter((name) => active.has(name.toLowerCase())),
+				.filter((tool) => !isHostHiddenTool(tool) && active.has(tool.name.toLowerCase()))
+				.map((tool) => tool.name),
 		);
 		deactivatedToolNames.clear();
 		toolCatalog = undefined;
@@ -658,12 +686,13 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "tool_search",
 		label: "Tool Search",
-		description: "Search inactive tools locally. Returned tools are activated additively without disabling current tools.",
+		description: "Search local tool definitions and activate matching inactive tools without disabling current tools.",
 		promptSnippet: "Search and activate additional tools on demand",
 		parameters: TOOL_SEARCH_PARAMS,
 		async execute(_id, params, _signal, _update, ctx) {
+			if (!params.query.trim()) throw new TypeError("query must not be empty");
 			const state = ensureSnapshot(ctx);
-			const catalog = toolCatalog ?? rebuildToolCatalog(state);
+			const catalog = buildToolSearchCatalog(state);
 			const page = searchToolDiscoveryCatalog(catalog, params.query, {
 				cursor: params.cursor,
 				pageSize: Math.min(
@@ -671,7 +700,9 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 					state.config.toolSearchPageSize,
 				),
 			});
-			const activated = activateAdditively(page.results.map((result) => result.name));
+			const activated = activateAdditively(page.results
+				.filter((result) => result.matchedTerms.length > 0)
+				.map((result) => result.name));
 			return {
 				content: [{ type: "text", text: JSON.stringify({ ...page, activated }) }],
 				details: { activated, confidence: page.confidence, failOpen: page.failOpen },