pi-skill-shiori 0.6.12 → 0.6.13

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## [0.6.13] - 2026-10-05
+
+### Added
+
+- Add session-local `/shiori:stats` timing diagnostics for inventory refresh and skill retrieval, with additive JSON counters and no prompt, skill-body, or cross-session analytics storage.
+
 ## [0.6.12] - 2026-09-30
 
 ### Changed

package/Docs/usage.md

@@ -167,6 +167,17 @@ command: offers=1, loaded=2, zeroHits=1
 top skills: auth-helper(1/2), deploy-kit(1/1)
 ```
 
+## Timing diagnostics
+
+Run `/shiori:stats` to see a compact timing line alongside the existing recommendation feedback summary. The line separates inventory refresh cost from retrieval cost; the JSON payload exposes the same machine-readable counters under `timing.inventoryRefresh` and `timing.retrieval`:
+
+- `count` — successful operations recorded in the current session
+- `lastMs` — duration of the most recent successful operation
+- `totalMs` — cumulative duration of successful operations
+- `maxMs` — longest successful operation
+
+Inventory refresh timing covers the successful session-start, manual `/shiori:reload`, and automatic refresh rebuilds. Retrieval timing covers successful auto-injection, `shiori_recommend`, and `/shiori:recommend` retrievals. These are in-memory, session-local diagnostics: Shiori does not store prompt text, full queries, skill bodies, or cross-session analytics.
+
 ## Agent tools
 
 Shiori registers two tools the agent can call after candidates appear:

package/README.md

@@ -19,7 +19,7 @@ For maintenance priorities and the phased plan, see [`ROADMAP.md`](ROADMAP.md).
 
 Pi Skill Shiori is a [Pi](https://pi.dev/) package for vaults or projects with many Agent Skills where the default catalog becomes noisy and expensive. It hides the normal skill catalog when safe, recommends triggerable skills with compact summaries, and loads full `SKILL.md` bodies on demand.
 
-`0.6.12` is the current working release. Prompt-boundary suppression is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
+`0.6.13` is the current working release. Prompt-boundary suppression is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
 
 ## Features
 
@@ -31,13 +31,14 @@ Pi Skill Shiori is a [Pi](https://pi.dev/) package for vaults or projects with m
 - **SQLite FTS retrieval** — indexes skill names, descriptions, and policy triggers with `node:sqlite` + FTS5, with token-match fallback.
 - **Recommendation reason badges** — compact `[trigger]`, `[description]`, and `[low match]` labels on surfaced skills.
 - **Session-local feedback metrics** — `/shiori:stats` tracks offers, loads, and follow-through without storing prompts.
+- **Timing diagnostics** — `/shiori:stats` separates inventory refresh and retrieval cost without storing prompts, skill bodies, or cross-session analytics.
 
 ## Install
 
 ### Global install from npm
 
 ```bash
-pi install npm:pi-skill-shiori@0.6.12
+pi install npm:pi-skill-shiori@0.6.13
 ```
 
 Without a version pin:
@@ -49,7 +50,7 @@ pi install npm:pi-skill-shiori
 ### Project-local install from npm
 
 ```bash
-pi install -l npm:pi-skill-shiori@0.6.12
+pi install -l npm:pi-skill-shiori@0.6.13
 ```
 
 Without a version pin:
@@ -61,7 +62,7 @@ pi install -l npm:pi-skill-shiori
 ### Install from GitHub
 
 ```bash
-pi install git:github.com/eiei114/pi-skill-shiori@v0.6.12
+pi install git:github.com/eiei114/pi-skill-shiori@v0.6.13
 pi install -l git:github.com/eiei114/pi-skill-shiori
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     ]
   },
   "dependencies": {
-    "yaml": "^2.8.1"
+    "yaml": "^2.9.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/index.ts

@@ -7,7 +7,7 @@ import { findDuplicates, formatInventoryRoots, isAutoRefreshEnabled, isInventory
 import type { SkillIndex } from "./indexer.js";
 import { loadRecommendedSkills } from "./load-skills.js";
 import { formatPlanningKickoffMessage, isPlanningIntent } from "./planning-kickoff.js";
-import { createStats } from "./metrics.js";
+import { createStats, formatTimingSummary, measureTiming } from "./metrics.js";
 import { createRecommendationFeedback } from "./recommendation-feedback.js";
 import { getPolicyPath, loadPolicyWithSource, loadedPolicySignature, type LoadedPolicy } from "./policy.js";
 import {
@@ -48,7 +48,10 @@ export default function piSkillShiori(pi: ExtensionAPI) {
   async function reload(cwd: string, currentPolicy?: LoadedPolicy): Promise<SkillIndex> {
     currentPolicy ??= await loadPolicyWithSource(cwd);
     const policy = currentPolicy.policy;
-    const inventory = await refreshSkillInventory(cwd, policy, index);
+    const inventory = await measureTiming(
+      stats.timing.inventoryRefresh,
+      () => refreshSkillInventory(cwd, policy, index),
+    );
     index = inventory.index;
     inventoryFingerprint = inventory.fingerprint;
     inventoryRoots = inventory.roots;
@@ -139,7 +142,10 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       ctx.ui.notify("Pi Skill Shiori: Skill Catalog suppression pattern not found; leaving system prompt unchanged.", "warning");
     }
 
-    const candidates = retrieveCandidatesExpanded(event.prompt, current.skills, current.policy, current);
+    const candidates = await measureTiming(
+      stats.timing.retrieval,
+      () => retrieveCandidatesExpanded(event.prompt, current.skills, current.policy, current),
+    );
     if (candidates.length === 0) {
       stats.zeroCandidateCount += 1;
       recommendationFeedback.recordZeroCandidates("auto-inject");
@@ -174,7 +180,10 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const current = await ensureIndex(ctx.cwd);
       const policy = withRecommendLimits(current);
-      const candidates = retrieveCandidatesExpanded(params.task, current.skills, policy, current);
+      const candidates = await measureTiming(
+        stats.timing.retrieval,
+        () => retrieveCandidatesExpanded(params.task, current.skills, policy, current),
+      );
       const candidateNames = candidates.map((candidate) => candidate.skill.name);
       const loaded = await loadRecommendedSkills(candidates);
       recommendationFeedback.recordRecommendation(
@@ -340,7 +349,10 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       }
 
       const policy = withRecommendLimits(current);
-      const candidates = retrieveCandidatesExpanded(query, current.skills, policy, current);
+      const candidates = await measureTiming(
+        stats.timing.retrieval,
+        () => retrieveCandidatesExpanded(query, current.skills, policy, current),
+      );
       const candidateNames = candidates.map((candidate) => candidate.skill.name);
       const planning = isPlanningIntent(query);
       const reviewOnly = action === RECOMMEND_REVIEW_ONLY;
@@ -417,11 +429,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     handler: async (_args, ctx) => {
       const payload = {
         ...stats,
+        timing: {
+          inventoryRefresh: { ...stats.timing.inventoryRefresh },
+          retrieval: { ...stats.timing.retrieval },
+        },
         recommendationFeedback: recommendationFeedback.summarize(),
       };
       ctx.ui.notify(
         [
           recommendationFeedback.formatSummary(),
+          formatTimingSummary(stats.timing),
           "",
           JSON.stringify(payload, null, 2),
         ].join("\n"),

package/src/metrics.ts

@@ -1,4 +1,26 @@
-import type { ShioriStats } from "./types.js";
+import { performance } from "node:perf_hooks";
+import type { ShioriStats, ShioriTiming, TimingCounter } from "./types.js";
+
+const TIMING_DECIMAL_PLACES = 2;
+const TIMING_SCALE = 10 ** TIMING_DECIMAL_PLACES;
+
+type MonotonicClock = () => number;
+
+export function createTimingCounter(): TimingCounter {
+  return {
+    lastMs: 0,
+    totalMs: 0,
+    maxMs: 0,
+    count: 0,
+  };
+}
+
+export function createTiming(): ShioriTiming {
+  return {
+    inventoryRefresh: createTimingCounter(),
+    retrieval: createTimingCounter(),
+  };
+}
 
 export function createStats(): ShioriStats {
   return {
@@ -12,5 +34,47 @@ export function createStats(): ShioriStats {
     suppressionStatus: "disabled",
     inventoryRefreshCount: 0,
     inventoryAutoRefreshCount: 0,
+    timing: createTiming(),
   };
 }
+
+export function recordTiming(counter: TimingCounter, elapsedMs: number): void {
+  const duration = roundMilliseconds(elapsedMs);
+  counter.lastMs = duration;
+  counter.totalMs = roundMilliseconds(counter.totalMs + duration);
+  counter.maxMs = Math.max(counter.maxMs, duration);
+  counter.count += 1;
+}
+
+export async function measureTiming<T>(
+  counter: TimingCounter,
+  operation: () => T | PromiseLike<T>,
+  now: MonotonicClock = () => performance.now(),
+): Promise<T> {
+  const startedAt = now();
+  const result = await operation();
+  recordTiming(counter, now() - startedAt);
+  return result;
+}
+
+export function formatTimingSummary(timing: ShioriTiming): string {
+  return [
+    "Timing (session-local)",
+    `inventory refresh: ${formatTimingCounter(timing.inventoryRefresh)}`,
+    `retrieval: ${formatTimingCounter(timing.retrieval)}`,
+  ].join(" | ");
+}
+
+function formatTimingCounter(counter: TimingCounter): string {
+  const count = Number.isFinite(counter.count) && counter.count > 0 ? Math.trunc(counter.count) : 0;
+  return `count=${count} last=${formatMilliseconds(counter.lastMs)} total=${formatMilliseconds(counter.totalMs)} max=${formatMilliseconds(counter.maxMs)}`;
+}
+
+function formatMilliseconds(value: number): string {
+  return `${roundMilliseconds(value).toFixed(TIMING_DECIMAL_PLACES)}ms`;
+}
+
+function roundMilliseconds(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) return 0;
+  return Math.round((value + Number.EPSILON) * TIMING_SCALE) / TIMING_SCALE;
+}

package/src/types.ts

@@ -48,6 +48,18 @@ export interface SkillCandidate {
   reason: RecommendationReasonKind | null;
 }
 
+export interface TimingCounter {
+  lastMs: number;
+  totalMs: number;
+  maxMs: number;
+  count: number;
+}
+
+export interface ShioriTiming {
+  inventoryRefresh: TimingCounter;
+  retrieval: TimingCounter;
+}
+
 export interface ShioriStats {
   inventoryCount: number;
   duplicateCount: number;
@@ -60,4 +72,5 @@ export interface ShioriStats {
   lastReloadAt?: string;
   inventoryRefreshCount: number;
   inventoryAutoRefreshCount: number;
+  timing: ShioriTiming;
 }