@llblab/pi-actors 0.15.0 → 0.16.1

package/lib/runtime.ts

@@ -6,6 +6,9 @@
 
 import * as Config from "./config.ts";
 import type { RegisteredToolExec } from "./execution.ts";
+import * as Paths from "./paths.ts";
+import * as RecipeDiscovery from "./recipe-discovery.ts";
+import * as RecipeMigration from "./recipe-migration.ts";
 import * as Tools from "./tools.ts";
 
 export interface RuntimeContext {
@@ -22,11 +25,15 @@ export interface ToolInfoLike {
 export interface ToolRegistryRuntimeDeps {
   configPath: string;
   exec: RegisteredToolExec;
+  packagedRecipeRoot?: string;
+  recipeRoot?: string;
+  getActiveTools?: () => string[];
   getAllTools: () => ToolInfoLike[];
   registerTool: (
     definition: ReturnType<typeof Tools.createRuntimeToolDefinition>,
   ) => void;
   reservedToolNames: Set<string>;
+  setActiveTools?: (toolNames: string[]) => void;
 }
 
 export interface ToolRegistryRuntime {
@@ -45,6 +52,7 @@ export function createAutoToolsRuntime(
   deps: ToolRegistryRuntimeDeps,
 ): ToolRegistryRuntime {
   const tools = new Map<string, Config.RegisteredTool>();
+  const runtimeToolFingerprints = new Map<string, string>();
   const runtimeTools = new Set<string>();
   function notify(
     ctx: RuntimeContext,
@@ -60,35 +68,77 @@ export function createAutoToolsRuntime(
       ? `Tool "${name}" is already registered outside pi-actors.`
       : undefined;
   }
+  function getToolFingerprint(cfg: Config.RegisteredTool): string {
+    return JSON.stringify({
+      args: cfg.args,
+      argTypes: cfg.argTypes,
+      defaults: cfg.defaults,
+      description: cfg.description,
+      recipe: cfg.recipe,
+      template: cfg.template,
+    });
+  }
+  function deactivateMissingRuntimeTools(activeNames: Set<string>): void {
+    const stale = [...runtimeTools].filter((name) => !activeNames.has(name));
+    if (stale.length === 0) return;
+    for (const name of stale) {
+      runtimeTools.delete(name);
+      runtimeToolFingerprints.delete(name);
+    }
+    if (!deps.getActiveTools || !deps.setActiveTools) return;
+    const staleSet = new Set(stale);
+    deps.setActiveTools(
+      deps.getActiveTools().filter((name) => !staleSet.has(name)),
+    );
+  }
   function registerRuntimeTool(cfg: Config.RegisteredTool) {
+    const fingerprint = getToolFingerprint(cfg);
+    if (runtimeToolFingerprints.get(cfg.name) === fingerprint) return;
     deps.registerTool(Tools.createRuntimeToolDefinition(cfg, deps.exec));
     runtimeTools.add(cfg.name);
+    runtimeToolFingerprints.set(cfg.name, fingerprint);
   }
   function loadTools(ctx: RuntimeContext) {
-    const loaded = Config.loadToolConfig(
-      deps.configPath,
-      deps.reservedToolNames,
-    );
+    const warnings: string[] = [];
+    const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
+    const packagedRecipeRoot = deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot();
+    const migration = RecipeMigration.migrateLegacyToolRegistry({
+      configPath: deps.configPath,
+      recipeRoot,
+      reservedToolNames: deps.reservedToolNames,
+    });
+    warnings.push(...migration.warnings);
+    if (migration.conflicts.length > 0)
+      warnings.push(`Recipe migration conflicts: ${migration.conflicts.join(", ")}`);
+    if (migration.invalid.length > 0)
+      warnings.push(`Recipe migration invalid entries: ${migration.invalid.join(", ")}`);
+    const discovered = RecipeDiscovery.discoverRecipeSources([
+      { root: recipeRoot, defaultTool: true, mutableUsage: true },
+      { root: packagedRecipeRoot },
+    ]);
+    warnings.push(...discovered.diagnostics);
     tools.clear();
-    for (const [name, cfg] of loaded.tools) tools.set(name, cfg);
-    if (loaded.changed) {
-      const saveError = Config.saveTools(deps.configPath, tools);
-      if (saveError) {
-        loaded.warnings.push(
-          `Failed to normalize ${deps.configPath}: ${saveError}`,
+    for (const entry of discovered.active.values()) {
+      try {
+        const cfg = RecipeDiscovery.toRegisteredTool(entry);
+        if (cfg) tools.set(cfg.name, cfg);
+      } catch (error) {
+        warnings.push(
+          `Recipe ${entry.id} could not be exposed as a tool: ${error instanceof Error ? error.message : String(error)}`,
         );
       }
     }
+    deactivateMissingRuntimeTools(new Set(tools.keys()));
     for (const cfg of tools.values()) {
       const conflict = getExternalToolConflict(cfg.name);
       if (conflict) {
-        loaded.warnings.push(conflict);
+        warnings.push(conflict);
         continue;
       }
       registerRuntimeTool(cfg);
     }
-    if (loaded.warnings.length > 0) {
-      notify(ctx, `Auto-tools: ${loaded.warnings.join("; ")}`, "warning");
+    if (warnings.length > 0) {
+      notify(ctx, `Recipe tools: ${warnings.join("; ")}`, "warning");
     }
   }
   return {

package/lib/tools.ts

@@ -9,8 +9,11 @@ import * as AsyncRuns from "./async-runs.ts";
 import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import * as Execution from "./execution.ts";
+import * as Paths from "./paths.ts";
 import * as Prompts from "./prompts.ts";
+import * as RecipeDiscovery from "./recipe-discovery.ts";
 import * as RecipeReferences from "./recipe-references.ts";
+import * as RecipeUsage from "./recipe-usage.ts";
 import * as Registry from "./registry.ts";
 import * as Schema from "./schema.ts";
 
@@ -229,6 +232,17 @@ function compactToolActor(name: string, tool: Record<string, unknown>): string {
   return `\ntool=${name} description=${String(tool.description ?? "").replaceAll(/\s+/g, "_")} args=${Object.keys(properties).join(",")} required=${required}`;
 }
 
+function compactRecipeRegistry(summary: Record<string, unknown>): string {
+  const active = Array.isArray(summary.active) ? summary.active.length : 0;
+  const shadowed = Array.isArray(summary.shadowed) ? summary.shadowed.length : 0;
+  const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
+  const disabled = Array.isArray(summary.disabled) ? summary.disabled.length : 0;
+  const diagnostics = Array.isArray(summary.diagnostics)
+    ? summary.diagnostics.length
+    : 0;
+  return `\nrecipes active=${active} shadowed=${shadowed} invalid=${invalid} disabled=${disabled} diagnostics=${diagnostics}`;
+}
+
 function compactActorMessageResult(
   message: ActorMessages.ActorMessage,
   result: Record<string, unknown>,
@@ -427,6 +441,8 @@ export function createSpawnToolDefinition<
 
 export interface InspectToolDeps<TContext = unknown> {
   getTool?: (name: string) => any | undefined;
+  packagedRecipeRoot?: string;
+  recipeRoot?: string;
 }
 
 function getContextSessionId(ctx: unknown): string | undefined {
@@ -494,8 +510,31 @@ export function createInspectToolDefinition<TContext = unknown>(
     ) {
       const input = asRecord(params);
       const target = String(input.target ?? "");
-      const address = ActorMessages.parseActorAddress(target);
       const view = String(input.view ?? "");
+      if (target === "recipes" || target === "recipe-registry") {
+        if (view !== "status" && view !== "summary") {
+          throw new Error("inspect recipes supports view=status or view=summary.");
+        }
+        const discovered = RecipeDiscovery.discoverRecipeSources([
+          { root: deps.recipeRoot ?? Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+          { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
+        ]);
+        const summary = RecipeDiscovery.summarizeDiscovery(discovered);
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: maybeJsonText(
+                summary,
+                input.verbose === true,
+                compactRecipeRegistry(summary),
+              ),
+            },
+          ],
+          details: summary,
+        };
+      }
+      const address = ActorMessages.parseActorAddress(target);
       if (address.kind === "coordinator") {
         if (view !== "status" && view !== "runs") {
           throw new Error(
@@ -881,6 +920,7 @@ export function createRuntimeToolDefinition(
       ctx: AsyncRunToolContext,
     ) {
       try {
+        if (cfg.sourcePath) RecipeUsage.recordRecipeLaunch(cfg.sourcePath);
         if (isAsyncRecipe) {
           const input = params as Record<string, unknown>;
           const { run_id, ...values } = input;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [
@@ -40,7 +40,8 @@
     "AGENTS.md",
     "BACKLOG.md",
     "CHANGELOG.md",
-    "docs"
+    "docs",
+    "banner.jpg"
   ],
   "pi": {
     "extensions": [
@@ -49,7 +50,8 @@
     "skills": [
       "./skills/actors/SKILL.md",
       "./skills/swarm/SKILL.md"
-    ]
+    ],
+    "image": "https://github.com/llblab/pi-actors/raw/main/banner.jpg"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

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.15.0
+  version: 0.16.1
 ---
 
 # Actors (pi-actors)
@@ -93,6 +93,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "messages" }
 { "target": "run:repo-health", "view": "artifacts" }
 { "target": "tool:music_player", "view": "status" }
+{ "target": "recipes", "view": "status" }
 { "target": "coordinator", "view": "status" }
 ```
 
@@ -104,6 +105,7 @@ Views:
 - `mailbox`: declared accepts/emits contract.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
+- `recipes` target: registry summary for active, shadowed, invalid, disabled, and diagnostic recipe entries.
 
 Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
 
@@ -165,22 +167,38 @@ Rules:
 4. Use `imports` to compose recipes; imported recipes are definitions, not nested async runs.
 5. Declare `mailbox` for actors that accept or emit meaningful messages.
 6. Declare `artifacts` for durable outputs the coordinator should inspect.
-7. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
-8. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+7. Recipe identity comes from the filename basename when `name` is omitted.
+8. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
+9. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+
+Priority for same-name recipes:
+
+1. No recipe: no capability.
+2. Packaged pi-actors recipe: standard-library declarative actor component.
+3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
+4. User recipe in `~/.pi/agent/recipes/*.json`: highest-priority operator tool surface.
+
+Only matching filename ids compete. Higher priority shadows lower priority. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+
+Muscle-memory lens: every recipe in `~/.pi/agent/recipes/*.json` becomes an easy-to-call tool by default. This is intentionally sticky: successful local patterns can quickly become durable agent muscle memory. The tradeoff is tool-surface clutter; accidental or one-off tools behave like persistent intrusive thoughts until an agent/operator focuses on cleanup.
+
+Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup or `tool: false` candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
+
+Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, set `tool: false` to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer demotion over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 
 ## Registered Tools
 
-`register_tool` persists trusted local capabilities in `~/.pi/agent/actors-tools.json`.
+`register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`.
 
-Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion.
+Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete recipe files in the user recipe root; direct file editing is allowed but is the lower-level path.
 
 Tool templates may be:
 
 - A foreground command template.
 - A file-backed recipe name/path.
-- A co-located recipe, optionally `async: true`.
+- A complete recipe body, optionally `async: true`.
 
-Registered tools are convenient buttons; recipes are the reusable semantic definitions behind them.
+The user recipe root is the default tool set; packaged recipes are the lower-priority standard library and opt into tool exposure with `tool: true`. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
 
 ## Recipe Navigator
 

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.15.0
+  version: 0.16.1
 ---
 
 # Swarm