@llblab/pi-actors 0.16.3 → 0.16.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.16.4: Recipe Usage Fingerprints
+
+- `[Recipe Usage]` Added content fingerprints to user recipe usage metadata. Impact: when a recipe file is edited and its authored meaning changes, the next launch resets `usage.calls`, records `usage.reset_at`, and starts counting usage for the current recipe content.
+- `[Docs]` Documented fingerprint-backed usage reset semantics in the template recipe and tool registry docs.
+- `[Package]` Bumped package and packaged skill metadata to `0.16.4` for the hotfix release.
+
 ## 0.16.3: Recipe Import Path Placeholders
 
 - `[Template Recipes]` Added static `{repo}` and `{agent}` expansion for recipe paths, including `imports` and `from` bindings. Impact: recipes can import sibling packaged/user recipes without hard-coded absolute paths while keeping imports load-time deterministic.

package/docs/template-recipes.md

@@ -95,7 +95,7 @@ User-owned recipes may accumulate extension-maintained usage metadata:
 }
 ```
 
-The extension increments `usage.calls` and updates `usage.last_called` when it starts that concrete recipe, either through a recipe-backed tool call or a direct async recipe-file run. Agents should treat these fields as cleanup evidence, not as authored recipe contract. Packaged standard-library recipes are not mutated for usage metadata.
+The extension increments `usage.calls` and updates `usage.last_called` when it starts that concrete recipe, either through a recipe-backed tool call or a direct async recipe-file run. It also stores a content `usage.fingerprint`; if the authored recipe content changes, the next launch resets `usage.calls` before counting the new launch and records `usage.reset_at`. Agents should treat these fields as cleanup evidence, not as authored recipe contract. Packaged standard-library recipes are not mutated for usage metadata.
 
 There is intentionally no failure counter in the recipe contract. A failed launch can reflect caller misuse, missing runtime values, or an environmental problem rather than recipe uselessness. Cleanup decisions should be explicit operator work: keep as a tool, set `tool: false`, merge, delete, or archive.
 

package/docs/tool-registry.md

@@ -17,7 +17,7 @@ The 0.16 registry source is file-discovered recipes, not a live tool-only JSON f
 
 `~/.pi/agent/actors-tools.json` is legacy compatibility input. On startup, pi-actors migrates it into recipe files when possible, writes a migration report, and archives the source only when migration has no conflicts or invalid generated recipes.
 
-Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls` and `usage.last_called` on user-owned recipe files. Use that evidence during focused cleanup passes: keep valuable tools, set `tool: false` for useful components that should leave the active tool surface, merge duplicates, or delete/archive low-value files. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
+Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. Use that evidence during focused cleanup passes: keep valuable tools, set `tool: false` for useful components that should leave the active tool surface, merge duplicates, or delete/archive low-value files. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
 
 `register_tool` is the preferred agent-facing mutation API. It creates, updates, and deletes recipe files in `~/.pi/agent/recipes`; agents do not need to edit the files directly for normal registration. Direct file edits are still valid for operators and advanced agents. Runtime behavior is reactive: file creation, deletion, or edits in the user recipe root trigger validation and tool-set refresh, with invalid recipes surfaced as diagnostics rather than silently ignored.
 

package/lib/recipe-usage.ts

@@ -4,6 +4,7 @@
  * Owns lightweight launch counters for user-owned recipe files
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 
 import { writeJsonAtomic } from "./file-state.ts";
@@ -11,6 +12,8 @@ import { writeJsonAtomic } from "./file-state.ts";
 interface RecipeUsageRecord {
   calls?: number;
   last_called?: string;
+  fingerprint?: string;
+  reset_at?: string;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -23,18 +26,37 @@ function normalizeCalls(value: unknown): number {
     : 0;
 }
 
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (!isRecord(value)) return JSON.stringify(value);
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(",")}}`;
+}
+
+function getRecipeFingerprint(raw: Record<string, unknown>): string {
+  const { usage: _usage, ...content } = raw;
+  return createHash("sha256").update(stableStringify(content)).digest("hex");
+}
+
 export function recordRecipeLaunch(path: string, now = new Date()): boolean {
   if (!existsSync(path)) return false;
   try {
     const raw = JSON.parse(readFileSync(path, "utf8"));
     if (!isRecord(raw)) return false;
     const usage: RecipeUsageRecord = isRecord(raw.usage) ? raw.usage : {};
+    const fingerprint = getRecipeFingerprint(raw);
+    const changed = typeof usage.fingerprint === "string" && usage.fingerprint !== fingerprint;
+    const nowIso = now.toISOString();
     writeJsonAtomic(path, {
       ...raw,
       usage: {
         ...usage,
-        calls: normalizeCalls(usage.calls) + 1,
-        last_called: now.toISOString(),
+        calls: (changed ? 0 : normalizeCalls(usage.calls)) + 1,
+        last_called: nowIso,
+        fingerprint,
+        ...(changed ? { reset_at: nowIso } : {}),
       },
     });
     return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.16.3",
+  "version": "0.16.4",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.16.3
+  version: 0.16.4
 ---
 
 # Actors (pi-actors)

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.16.3
+  version: 0.16.4
 ---
 
 # Swarm