@llblab/pi-actors 0.16.2 → 0.16.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.
+- `[Docs]` Documented `{repo}` and `{agent}` import path placeholders in the template recipe standard.
+- `[Package]` Bumped package and packaged skill metadata to `0.16.3` for the hotfix release.
+
 ## 0.16.2: Recipe Registry Diagnostics Hotfix
 
 - `[Schema]` Derived recipe tool arguments without expanding runtime-dependent repeat nodes. Impact: valid recipes using repeat expressions such as `{lenses.length}` can be exposed as tools instead of being skipped during startup schema generation.

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.
 
@@ -245,7 +245,7 @@ File-backed recipes may import other file-backed recipes at the recipe layer. Im
 
 An import binding may be either a string recipe path/name or an object with:
 
-- `from`: recipe path or bare name.
+- `from`: recipe path or bare name. Import paths support static load-time placeholders: `{repo}` expands to the directory above the active recipe root, and `{agent}` expands to the pi agent directory. For a packaged recipe in `<repo>/recipes/name.json`, `{repo}/recipes/other.json` resolves to a sibling packaged recipe. For a user recipe in `~/.pi/agent/recipes/name.json`, `{repo}` and `{agent}` both resolve to `~/.pi/agent`.
 - `defaults`: extra default values exposed through the import.
 - `values`: explicit values for embedding that imported recipe.
 

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-references.ts

@@ -75,11 +75,15 @@ export function resolveRecipePath(
   recipeRoot = Paths.getRecipeRoot(),
 ): string {
   const trimmed = value.trim();
-  if (trimmed.startsWith("~/")) return resolve(homedir(), trimmed.slice(2));
-  if (trimmed.includes("/")) return resolve(trimmed);
+  const repoRoot = resolve(recipeRoot, "..");
+  const expanded = trimmed
+    .replaceAll("{repo}", repoRoot)
+    .replaceAll("{agent}", Paths.getAgentDir());
+  if (expanded.startsWith("~/")) return resolve(homedir(), expanded.slice(2));
+  if (expanded.includes("/")) return resolve(expanded);
   return resolve(
     recipeRoot,
-    trimmed.endsWith(".json") ? trimmed : `${trimmed}.json`,
+    expanded.endsWith(".json") ? expanded : `${expanded}.json`,
   );
 }
 

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.2",
+  "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.2
+  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.2
+  version: 0.16.4
 ---
 
 # Swarm