@aeondave/pi-skill-optimizer 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes are documented here.
 
+## Unreleased
+
+## 3.1.1 - 2026-10-08
+
+### Fixed
+
+- Optimize the native Pi transcript before provider conversion, keeping worker notifications, shell
+  output and summaries out of human-intent routing and prefetch insertion.
+- Preserve structured system sections and tool declarations; respect provider scoping when the
+  request has no selected model.
+- Label prefetch as catalog metadata, not loaded instructions or usage evidence. Emit its actual
+  catalog fingerprint and report selected skills only when an overlay was inserted.
+- Recognize native Pi skill-activation calls without double-counting `skill_search` usage.
+
 ## 3.1.0 - 2026-10-03
 
 ### Breaking

package/README.md

@@ -37,7 +37,7 @@ That's enough to start. Optionally run `/skill-optimizer init` to generate routi
 | 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.1.0` |
+| Pin the current release | `pi install npm:@aeondave/pi-skill-optimizer@3.1.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.
@@ -61,6 +61,10 @@ Say you have hundreds of skills, but you're asking Pi to fix a database migratio
 
 AUTO keeps a compact, stable index of **all eligible names**, adds relevant descriptions beside your latest request, and exposes `skill_search` for loading complete instructions. The stable index does not change when your question changes.
 
+Prefetch is a catalog, not loaded instructions or evidence that a skill was used. Worker updates,
+extension notifications and summaries do not replace your request as the routing signal or receive
+its overlay; there is no need to acknowledge the catalog.
+
 | Area | What AUTO does | What stays available |
 | --- | --- | --- |
 | Skills | Shortens catalog descriptions; prefetches relevant ones | Every eligible name and exact full-instruction loading |

package/docs/ARCHITECTURE.md

@@ -20,8 +20,19 @@ The index contains no filesystem paths. With the same catalog, profile, and conf
 
 AUTO extracts intent only from genuine human text in Anthropic, OpenAI Chat and Responses, Gemini, Mistral, and Pi's structured `pi-messages` request shapes. A catalog may live in a system or developer block, but neither is treated as human intent. Assistant text, tool or function results, injected context, image metadata, and empty input cannot create a ranking signal.
 
+At runtime, catalog optimization and usage extraction run in Pi's `context_with_system` hook,
+before provider conversion erases custom-message provenance. Native `custom`, `bashExecution`,
+`branchSummary`, `compactionSummary` and `toolResult` messages remain intact and cannot become
+the query or overlay target. Structured system sections and tool declarations are preserved;
+request-local clones do not modify persisted conversation entries.
+
 Ranking uses exact matching, BM25F, bounded name and alias typo recovery, reciprocal-rank fusion, diversity, profile evidence, and decayed usage evidence. It scores full source descriptions, then appends a bounded set of verbatim skill names and descriptions (not the full `SKILL.md` instructions) to the latest human block. The overlay is separate from the stable prefix, fingerprinted, idempotent, and omitted when there is no valid target.
 
+The resolver labels prefetch as discovery metadata, not loaded instructions or usage evidence.
+Diagnostics count only overlays actually inserted. Usage follows explicit human mentions and skill
+activations; the `skill_search` executor records its own loads/resources, so transcript scanning
+does not count those calls twice. Catalog selections and assistant acknowledgments are not usage.
+
 Optional init-generated activation tags distinguish specialists, workflow methods
 and behavioral discipline. An admitted specialist can bring one activity-matched
 supporting skill into the ordinary prefetch budget; this does not recursively

package/package.json

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

package/src/index.ts

@@ -1084,13 +1084,14 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("before_provider_request", (event, ctx) => {
+	pi.on("context_with_system", (event, ctx) => {
 		if (isDisabled(ctx.cwd)) return;
 		const config = getRuntimeConfig(ctx);
 		const providers = config.providers.length > 0 ? config.providers : undefined;
-		if (providers && ctx.model && !providers.includes(ctx.model.provider)) return;
+		if (providers && (!ctx.model || !providers.includes(ctx.model.provider))) return;
 		const state = ensureSnapshot(ctx);
-		const transformed = optimizePayload(event.payload, {
+		const payload = { messages: event.messages };
+		const transformed = optimizePayload(payload, {
 			...state.config,
 			profile: state.profile,
 			usagePrior: buildUsagePrior(state.usage, {
@@ -1109,7 +1110,7 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 			addPending(getStatsFilePath(ctx.cwd), { skills: transformed.removedChars, tools: 0, output: 0 });
 		}
 		if (registry) {
-			const evidence = collectSkillUsageEvidence(event.payload, registry.skills.map((skill) => skill.name)).slice(-MAX_SEEN_EVIDENCE);
+			const evidence = collectSkillUsageEvidence(payload, registry.skills.map((skill) => skill.name)).slice(-MAX_SEEN_EVIDENCE);
 			const names: string[] = [];
 			for (const item of evidence) {
 				if (seenEvidence.has(item.key)) continue;
@@ -1124,7 +1125,9 @@ export default function skillOptimizer(pi: ExtensionAPI) {
 		}
 		maybeFlush(ctx);
 		updateStatus(ctx);
-		return transformed.next === event.payload ? undefined : transformed.next;
+		return transformed.next === payload
+			? undefined
+			: { messages: (transformed.next as typeof payload).messages };
 	});
 
 	pi.on("context", (event, ctx) => {

package/src/optimize.ts

@@ -361,25 +361,24 @@ export function optimizePayload<T>(
   }
 
   let addedPrefetchChars = 0;
-  const selectedSkills =
-    planSkillPrefetch(catalogSkills, query, {
-      profile: config.profile,
-      usagePrior: config.usagePrior,
-      always: uniqueInOrder([
-        ...(config.profile?.critical ?? []),
-        ...(config.alwaysSkills ?? []),
-      ]),
-      never: config.excludeSkills,
-      targetTopK: config.prefetchTarget,
-      minTopK: config.prefetchMin,
-      maxTopK: config.prefetchMax,
-      fullRenderBudgetChars: config.prefetchBudgetChars,
-      fuzzyCandidateLimit: config.fuzzyCandidateLimit,
-    }).selected;
+  let injectedSkills: string[] = [];
+  const prefetchPlan = planSkillPrefetch(catalogSkills, query, {
+    profile: config.profile,
+    usagePrior: config.usagePrior,
+    always: uniqueInOrder([
+      ...(config.profile?.critical ?? []),
+      ...(config.alwaysSkills ?? []),
+    ]),
+    never: config.excludeSkills,
+    targetTopK: config.prefetchTarget,
+    minTopK: config.prefetchMin,
+    maxTopK: config.prefetchMax,
+    fullRenderBudgetChars: config.prefetchBudgetChars,
+    fuzzyCandidateLimit: config.fuzzyCandidateLimit,
+  });
+  const selectedSkills = prefetchPlan.selected;
   if (selectedSkills.length > 0) {
-    const appendix = renderSkillPrefetch({
-      selected: selectedSkills,
-    } as Parameters<typeof renderSkillPrefetch>[0]);
+    const appendix = renderSkillPrefetch(prefetchPlan);
     if (appendix) {
       const withPrefetch = appendToLatestHumanInput(
         next,
@@ -389,6 +388,7 @@ export function optimizePayload<T>(
       if (withPrefetch !== next) {
         addedPrefetchChars = serializedLength(withPrefetch) - serializedLength(next);
         next = withPrefetch;
+        injectedSkills = selectedSkills.map((skill) => skill.name);
       }
     }
   }
@@ -416,7 +416,7 @@ export function optimizePayload<T>(
     removedChars: originalLength - finalLength,
     baseRemovedChars,
     addedPrefetchChars: Math.max(0, addedPrefetchChars),
-    selected: selectedSkills.map((skill) => skill.name),
+    selected: injectedSkills,
     catalogNames: uniqueInOrder(catalogNames),
     fingerprints: uniqueInOrder(fingerprints),
     budget,

package/src/skills.ts

@@ -1058,7 +1058,7 @@ export function renderSkillPrefetch(plan: SkillPrefetchPlan): string {
 	if (plan.selected.length === 0) return "";
 	return [
 		`<skill_prefetch catalog_sha256="${plan.fingerprint}">`,
-		"  <skill_resolver>Use skill_search(name) to load the full skill resource.</skill_resolver>",
+		"  <skill_resolver>Catalog metadata only, not loaded instructions or usage evidence. Load a relevant full skill with skill_search(action=load, name); no acknowledgment is needed.</skill_resolver>",
 		...plan.selected.map(renderFullSkill),
 		"</skill_prefetch>",
 	].join("\n");

package/src/usage.ts

@@ -91,16 +91,18 @@ export function collectSkillUsageEvidence(payload: unknown, selectedSkills: read
 		const rawMessage = rawMessages[messageIndex];
 		if (!rawMessage || typeof rawMessage !== "object") continue;
 		const message = rawMessage as Record<string, unknown>;
+		if (message.role !== "assistant") continue;
 		if (!Array.isArray(message.content)) continue;
 		for (let blockIndex = 0; blockIndex < message.content.length; blockIndex++) {
 			const rawBlock = message.content[blockIndex];
 			if (!rawBlock || typeof rawBlock !== "object") continue;
 			const block = rawBlock as Record<string, unknown>;
-			if (block.type !== "tool_use" || typeof block.name !== "string") continue;
+			if ((block.type !== "tool_use" && block.type !== "toolCall") || typeof block.name !== "string") continue;
 			const toolName = block.name.toLowerCase();
 			if (toolName !== "skill" && toolName !== "activate_skill") continue;
-			if (!block.input || typeof block.input !== "object") continue;
-			const input = block.input as Record<string, unknown>;
+			const rawInput = block.type === "toolCall" ? block.arguments : block.input;
+			if (!rawInput || typeof rawInput !== "object") continue;
+			const input = rawInput as Record<string, unknown>;
 			let serialized = "";
 			try { serialized = JSON.stringify(input); } catch { serialized = String(input); }
 			const sourceId = objectId(block);