@llblab/pi-actors 0.15.0 → 0.16.1

package/lib/prompts.ts

@@ -6,7 +6,7 @@
 
 export const REGISTER_TOOL_DESCRIPTION =
   "Register a persistent custom tool from a command template, template recipe path, or co-located template recipe. " +
-  "Definitions are stored in actors-tools.json across reloads. " +
+  "Definitions are stored as recipe files under ~/.pi/agent/recipes across reloads. " +
   "Use update=true to overwrite an existing tool, template=null/empty to delete.";
 
 export const REGISTER_TOOL_PROMPT_SNIPPET =
@@ -28,7 +28,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
-- Register_tool makes persistent tools from command templates, recipe names/paths, or co-located recipes; args may be typed or placeholder-derived.
+- Register_tool writes user recipe files in ~/.pi/agent/recipes; that root is the default tool set, while packaged recipes are the lower-priority standard library.
 - Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages.
 - For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;

package/lib/recipe-discovery.ts

@@ -0,0 +1,231 @@
+/**
+ * File-discovered recipe registry helpers
+ * Zones: recipe discovery, tool exposure, migration diagnostics
+ * Owns filename identity discovery across prioritized recipe roots
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { RegisteredTool } from "./config.ts";
+import type { TemplateRecipeConfig } from "./recipe-references.ts";
+import * as RecipeReferences from "./recipe-references.ts";
+import * as Schema from "./schema.ts";
+
+export interface DiscoveredRecipe {
+  id: string;
+  path: string;
+  root: string;
+  priority: number;
+  config?: TemplateRecipeConfig;
+  active: boolean;
+  shadowed: boolean;
+  invalid: boolean;
+  disabled: boolean;
+  tool: boolean;
+  mutableUsage: boolean;
+  diagnostics: string[];
+  shadows: string[];
+}
+
+export interface RecipeDiscoveryResult {
+  active: Map<string, DiscoveredRecipe>;
+  entries: DiscoveredRecipe[];
+  diagnostics: string[];
+}
+
+export interface RecipeDiscoverySource {
+  root?: string;
+  file?: string;
+  defaultTool?: boolean;
+  mutableUsage?: boolean;
+}
+
+function listRecipeFiles(root: string): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith(".json") &&
+        entry.name !== "actors-tools-migration-report.json",
+    )
+    .map((entry) => join(root, entry.name))
+    .sort();
+}
+
+function readDiscoveredRecipe(
+  root: string,
+  file: string,
+  priority: number,
+  defaultTool = false,
+  mutableUsage = false,
+): DiscoveredRecipe {
+  const id = RecipeReferences.getRecipeIdFromPath(file);
+  try {
+    const config = RecipeReferences.readResolvedRecipeConfig(file);
+    const invalid = !config;
+    const disabled = config?.disabled === true;
+    return {
+      id,
+      path: file,
+      root,
+      priority,
+      config,
+      active: false,
+      shadowed: false,
+      invalid,
+      disabled,
+      tool: (config?.tool ?? defaultTool) === true && !disabled && !invalid,
+      mutableUsage,
+      diagnostics: invalid ? [`Invalid recipe: ${file}`] : [],
+      shadows: [],
+    };
+  } catch (error) {
+    return {
+      id,
+      path: file,
+      root,
+      priority,
+      active: false,
+      shadowed: false,
+      invalid: true,
+      disabled: false,
+      tool: false,
+      mutableUsage,
+      diagnostics: [
+        `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
+      ],
+      shadows: [],
+    };
+  }
+}
+
+function filesForSource(
+  source: RecipeDiscoverySource,
+): Array<{ root: string; file: string; defaultTool: boolean; mutableUsage: boolean }> {
+  const defaultTool = source.defaultTool === true;
+  const mutableUsage = source.mutableUsage === true;
+  if (source.file)
+    return [{ root: source.root ?? source.file, file: source.file, defaultTool, mutableUsage }];
+  return source.root
+    ? listRecipeFiles(source.root).map((file) => ({
+        root: source.root!,
+        file,
+        defaultTool,
+        mutableUsage,
+      }))
+    : [];
+}
+
+export function discoverRecipeSources(
+  sources: RecipeDiscoverySource[],
+): RecipeDiscoveryResult {
+  const entries = sources.flatMap((source, priority) =>
+    filesForSource(source).map(({ root, file, defaultTool, mutableUsage }) =>
+      readDiscoveredRecipe(root, file, priority, defaultTool, mutableUsage),
+    ),
+  );
+  const byId = new Map<string, DiscoveredRecipe[]>();
+  for (const entry of entries) {
+    const bucket = byId.get(entry.id) ?? [];
+    bucket.push(entry);
+    byId.set(entry.id, bucket);
+  }
+
+  const active = new Map<string, DiscoveredRecipe>();
+  const diagnostics: string[] = [];
+  for (const [id, bucket] of byId) {
+    bucket.sort(
+      (a, b) => a.priority - b.priority || a.path.localeCompare(b.path),
+    );
+    const winner = bucket[0];
+    winner.active = true;
+    winner.shadows = bucket.slice(1).map((entry) => entry.path);
+    active.set(id, winner);
+    for (const shadow of bucket.slice(1)) shadow.shadowed = true;
+    if (winner.invalid)
+      diagnostics.push(
+        `Recipe ${id} is invalid and blocks lower-priority recipes`,
+      );
+    if (winner.disabled)
+      diagnostics.push(
+        `Recipe ${id} is disabled and blocks lower-priority recipes`,
+      );
+    if (winner.shadows.length > 0)
+      diagnostics.push(
+        `Recipe ${id} shadows ${winner.shadows.length} lower-priority recipe(s)`,
+      );
+    diagnostics.push(...winner.diagnostics);
+  }
+
+  return { active, entries, diagnostics };
+}
+
+export function discoverRecipes(roots: string[]): RecipeDiscoveryResult {
+  return discoverRecipeSources(roots.map((root) => ({ root })));
+}
+
+export function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown> {
+  return {
+    active: [...result.active.values()].map((entry) => ({
+      id: entry.id,
+      path: entry.path,
+      description: entry.config?.description,
+      tool: entry.tool,
+      disabled: entry.disabled,
+      invalid: entry.invalid,
+      shadows: entry.shadows,
+    })).sort((a, b) => a.id.localeCompare(b.id)),
+    shadowed: result.entries
+      .filter((entry) => entry.shadowed)
+      .map((entry) => ({ id: entry.id, path: entry.path, shadowedBy: result.active.get(entry.id)?.path }))
+      .sort((a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path)),
+    invalid: result.entries
+      .filter((entry) => entry.invalid)
+      .map((entry) => ({ id: entry.id, path: entry.path, diagnostics: entry.diagnostics }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+    disabled: result.entries
+      .filter((entry) => entry.disabled)
+      .map((entry) => ({ id: entry.id, path: entry.path }))
+      .sort((a, b) => a.id.localeCompare(b.id)),
+    diagnostics: result.diagnostics,
+  };
+}
+
+export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined {
+  if (!entry.tool || entry.invalid || entry.disabled || !entry.config) return undefined;
+  const cfg = entry.config;
+  const template = entry.path;
+  const description = cfg.description ?? `Execute template recipe: ${entry.id}`;
+  const argTemplate = cfg.template;
+  const argTemplateConfig =
+    typeof argTemplate === "object" && !Array.isArray(argTemplate)
+      ? {
+          ...argTemplate,
+          ...(cfg.args !== undefined ? { args: cfg.args } : {}),
+          defaults: { ...(argTemplate.defaults ?? {}), ...(cfg.defaults ?? {}) },
+        }
+      : { args: cfg.args, defaults: cfg.defaults ?? {}, template: argTemplate };
+  const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+  return {
+    name: entry.id,
+    description,
+    template,
+    recipe: cfg,
+    args: Schema.getToolArgNames(argTemplateConfig),
+    defaults: Object.fromEntries(
+      Object.entries(cfg.defaults ?? {}).map(([key, value]) => [key, String(value)]),
+    ),
+    ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
+    ...(entry.mutableUsage ? { sourcePath: entry.path } : {}),
+    ...(cfg.args ? { storedArgs: cfg.args } : {}),
+    ...(cfg.defaults
+      ? {
+          storedDefaults: Object.fromEntries(
+            Object.entries(cfg.defaults).map(([key, value]) => [key, String(value)]),
+          ),
+        }
+      : {}),
+  };
+}

package/lib/recipe-migration.ts

@@ -0,0 +1,123 @@
+/**
+ * Legacy actors-tools.json to recipe-file migration helpers
+ * Zones: registry migration, recipe persistence, compatibility diagnostics
+ * Owns one-way migration from legacy tool registry entries into user recipe files
+ */
+
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import * as Config from "./config.ts";
+import { writeJsonAtomic } from "./file-state.ts";
+import type { TemplateRecipeConfig } from "./recipe-references.ts";
+import * as RecipeReferences from "./recipe-references.ts";
+
+export interface LegacyRegistryMigrationResult {
+  migrated: string[];
+  skipped: string[];
+  conflicts: string[];
+  invalid: string[];
+  archive?: string;
+  report?: string;
+  warnings: string[];
+}
+
+export interface LegacyRegistryMigrationOptions {
+  configPath: string;
+  recipeRoot: string;
+  reservedToolNames: Set<string>;
+  archive?: boolean;
+}
+
+function recipePathForTool(recipeRoot: string, name: string): string {
+  return join(recipeRoot, `${name}.json`);
+}
+
+function toRecipeConfig(tool: Config.RegisteredTool): TemplateRecipeConfig {
+  return {
+    name: tool.name,
+    description: tool.description,
+    tool: true,
+    ...(tool.recipe?.async !== undefined ? { async: tool.recipe.async } : {}),
+    ...(tool.recipe?.state_dir ? { state_dir: tool.recipe.state_dir } : {}),
+    ...(tool.storedArgs ? { args: tool.storedArgs } : {}),
+    ...(tool.storedDefaults ? { defaults: tool.storedDefaults } : {}),
+    template: tool.template!,
+    ...(tool.recipe?.values ? { values: tool.recipe.values } : {}),
+  };
+}
+
+function nextArchivePath(configPath: string): string {
+  const base = `${configPath}.migrated`;
+  if (!existsSync(base)) return base;
+  for (let index = 1; index < 1000; index += 1) {
+    const path = `${base}.${index}`;
+    if (!existsSync(path)) return path;
+  }
+  return `${base}.${Date.now()}`;
+}
+
+export function migrateLegacyToolRegistry(
+  options: LegacyRegistryMigrationOptions,
+): LegacyRegistryMigrationResult {
+  const { configPath, recipeRoot, reservedToolNames } = options;
+  const result: LegacyRegistryMigrationResult = {
+    migrated: [],
+    skipped: [],
+    conflicts: [],
+    invalid: [],
+    warnings: [],
+  };
+  if (!existsSync(configPath)) return result;
+
+  const loaded = Config.loadToolConfig(configPath, reservedToolNames);
+  result.warnings.push(...loaded.warnings);
+  mkdirSync(recipeRoot, { recursive: true });
+
+  for (const [name, tool] of loaded.tools) {
+    const path = recipePathForTool(recipeRoot, name);
+    if (existsSync(path)) {
+      result.conflicts.push(name);
+      continue;
+    }
+    const recipe = toRecipeConfig(tool);
+    try {
+      writeJsonAtomic(path, recipe);
+      const parsed = RecipeReferences.readResolvedRecipeConfig(path);
+      if (!parsed) {
+        result.invalid.push(name);
+        continue;
+      }
+      result.migrated.push(name);
+    } catch (error) {
+      result.invalid.push(
+        `${name}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  if (loaded.tools.size === 0) result.skipped.push(basename(configPath));
+
+  const reportPath = join(recipeRoot, "actors-tools-migration-report.json");
+  writeJsonAtomic(reportPath, {
+    source: configPath,
+    migrated: result.migrated,
+    skipped: result.skipped,
+    conflicts: result.conflicts,
+    invalid: result.invalid,
+    warnings: result.warnings,
+  });
+  result.report = reportPath;
+
+  if (
+    options.archive !== false &&
+    result.conflicts.length === 0 &&
+    result.invalid.length === 0
+  ) {
+    const archive = nextArchivePath(configPath);
+    renameSync(configPath, archive);
+    result.archive = archive;
+  }
+
+  return result;
+}

package/lib/recipe-references.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 
 import type {
   CommandTemplateConfig,
@@ -30,6 +30,9 @@ export interface TemplateRecipeMailbox {
 
 export interface TemplateRecipeDefinition {
   name?: string;
+  description?: string;
+  tool?: boolean;
+  disabled?: boolean;
   imports?: Record<string, TemplateRecipeImport>;
   template: CommandTemplateValue;
   args?: string[];
@@ -194,14 +197,16 @@ function readRawRecipeConfig(
       string,
       unknown
     >;
-    return raw && typeof raw === "object" && !Object.hasOwn(raw, "tool")
-      ? raw
-      : undefined;
+    return raw && typeof raw === "object" ? raw : undefined;
   } catch {
     return undefined;
   }
 }
 
+export function getRecipeIdFromPath(file: string): string {
+  return basename(file, ".json");
+}
+
 function readRecipeConfig(value: unknown): TemplateRecipeConfig | undefined {
   const path = getRecipePath(value);
   return path ? readResolvedRecipeConfig(path) : undefined;
@@ -489,7 +494,20 @@ export function readResolvedRecipeConfig(
   if (!template) return undefined;
   const expandedTemplate = expandImportNodes(template, imports);
   return {
-    ...(typeof substituted.name === "string" ? { name: substituted.name } : {}),
+    name:
+      typeof substituted.name === "string"
+        ? substituted.name
+        : getRecipeIdFromPath(path),
+    ...(typeof substituted.description === "string" &&
+    substituted.description.trim()
+      ? { description: substituted.description.trim() }
+      : {}),
+    ...(typeof substituted.tool === "boolean"
+      ? { tool: substituted.tool }
+      : {}),
+    ...(typeof substituted.disabled === "boolean"
+      ? { disabled: substituted.disabled }
+      : {}),
     ...(substituted.async === true
       ? { async: true }
       : substituted.async === false
@@ -514,13 +532,16 @@ export function readResolvedRecipeConfig(
     ...(typeof substituted.label === "string"
       ? { label: substituted.label }
       : {}),
-    ...(typeof substituted.when === "string" || typeof substituted.when === "boolean"
+    ...(typeof substituted.when === "string" ||
+    typeof substituted.when === "boolean"
       ? { when: substituted.when }
       : {}),
-    ...(typeof substituted.timeout === "number" || typeof substituted.timeout === "string"
+    ...(typeof substituted.timeout === "number" ||
+    typeof substituted.timeout === "string"
       ? { timeout: substituted.timeout }
       : {}),
-    ...(typeof substituted.delay === "number" || typeof substituted.delay === "string"
+    ...(typeof substituted.delay === "number" ||
+    typeof substituted.delay === "string"
       ? { delay: substituted.delay }
       : {}),
     ...(typeof substituted.output === "string"
@@ -529,8 +550,10 @@ export function readResolvedRecipeConfig(
     ...(isRecord(substituted.artifacts)
       ? {
           artifacts: Object.fromEntries(
-            Object.entries(substituted.artifacts)
-              .filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+            Object.entries(substituted.artifacts).filter(
+              (entry): entry is [string, string] =>
+                typeof entry[1] === "string",
+            ),
           ),
         }
       : {}),
@@ -538,15 +561,24 @@ export function readResolvedRecipeConfig(
       ? {
           mailbox: {
             ...(Array.isArray(substituted.mailbox.accepts)
-              ? { accepts: substituted.mailbox.accepts.filter((value): value is string => typeof value === "string") }
+              ? {
+                  accepts: substituted.mailbox.accepts.filter(
+                    (value): value is string => typeof value === "string",
+                  ),
+                }
               : {}),
             ...(Array.isArray(substituted.mailbox.emits)
-              ? { emits: substituted.mailbox.emits.filter((value): value is string => typeof value === "string") }
+              ? {
+                  emits: substituted.mailbox.emits.filter(
+                    (value): value is string => typeof value === "string",
+                  ),
+                }
               : {}),
           },
         }
       : {}),
-    ...(typeof substituted.retry === "number" || typeof substituted.retry === "string"
+    ...(typeof substituted.retry === "number" ||
+    typeof substituted.retry === "string"
       ? { retry: substituted.retry }
       : {}),
     ...(substituted.failure === "continue" ||

package/lib/recipe-usage.ts

@@ -0,0 +1,44 @@
+/**
+ * Recipe usage metadata helpers
+ * Zones: recipe telemetry, muscle-memory cleanup evidence
+ * Owns lightweight launch counters for user-owned recipe files
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { writeJsonAtomic } from "./file-state.ts";
+
+interface RecipeUsageRecord {
+  calls?: number;
+  last_called?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeCalls(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : 0;
+}
+
+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 : {};
+    writeJsonAtomic(path, {
+      ...raw,
+      usage: {
+        ...usage,
+        calls: normalizeCalls(usage.calls) + 1,
+        last_called: now.toISOString(),
+      },
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/registry.ts

@@ -4,10 +4,15 @@
  * Owns register/update/delete validation, persistence, runtime side effects, and result payloads
  */
 
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+
 import * as Config from "./config.ts";
 import * as Identity from "./identity.ts";
 import * as Output from "./output.ts";
 import * as CommandTemplates from "./command-templates.ts";
+import { writeJsonAtomic } from "./file-state.ts";
+import * as Paths from "./paths.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as Schema from "./schema.ts";
 
@@ -41,6 +46,7 @@ export interface RegisterToolResult {
 
 export interface RegisterToolRuntimeDeps<TContext> {
   configPath: string;
+  recipeRoot?: string;
   getExternalToolConflict: (name: string) => string | undefined;
   getTools: () => Map<string, Config.RegisteredTool>;
   getActiveTools: () => string[];
@@ -76,6 +82,38 @@ function listTools<TContext>(
   };
 }
 
+function getRecipeRoot<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+): string {
+  return deps.recipeRoot ?? Paths.getRecipeRoot(dirname(deps.configPath));
+}
+
+function getToolRecipePath<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+  name: string,
+): string {
+  return join(getRecipeRoot(deps), `${name}.json`);
+}
+
+function persistToolRecipe<TContext>(
+  deps: RegisterToolRuntimeDeps<TContext>,
+  cfg: Config.RegisteredTool,
+): string {
+  const path = getToolRecipePath(deps, cfg.name);
+  mkdirSync(dirname(path), { recursive: true });
+  writeJsonAtomic(path, {
+    description: cfg.description,
+    tool: true,
+    ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
+    ...(cfg.recipe?.state_dir ? { state_dir: cfg.recipe.state_dir } : {}),
+    ...(cfg.storedArgs ? { args: cfg.storedArgs } : {}),
+    ...(cfg.storedDefaults ? { defaults: cfg.storedDefaults } : {}),
+    ...(cfg.recipe?.values ? { values: cfg.recipe.values } : {}),
+    template: cfg.template,
+  });
+  return path;
+}
+
 function deleteTool<TContext>(
   name: string,
   ctx: TContext,
@@ -90,14 +128,8 @@ function deleteTool<TContext>(
       details: { tool: name },
     };
   }
-  const nextTools = new Map(tools);
-  nextTools.delete(name);
-  const saveError = Config.saveTools(deps.configPath, nextTools);
-  if (saveError) {
-    throw new Error(
-      Output.formatToolText(`Failed to persist tool deletion: ${saveError}`),
-    );
-  }
+  const recipePath = getToolRecipePath(deps, name);
+  if (existsSync(recipePath)) unlinkSync(recipePath);
   tools.delete(name);
   deps.setActiveTools(
     deps.getActiveTools().filter((toolName) => toolName !== name),
@@ -111,7 +143,7 @@ function deleteTool<TContext>(
         ),
       ),
     ],
-    details: { config: deps.configPath, tool: name },
+    details: { config: recipePath, tool: name },
   };
 }
 
@@ -257,16 +289,17 @@ export async function executeRegisterTool<TContext>(
     );
   }
   const cfg = buildConfig(name, input, existing);
-  const nextTools = new Map(tools);
-  nextTools.set(name, cfg);
-  const saveError = Config.saveTools(deps.configPath, nextTools);
-  if (saveError) {
+  let recipePath: string;
+  try {
+    recipePath = persistToolRecipe(deps, cfg);
+  } catch (error) {
     throw new Error(
       Output.formatToolText(
-        `Failed to persist tool registration: ${saveError}`,
+        `Failed to persist tool recipe: ${error instanceof Error ? error.message : String(error)}`,
       ),
     );
   }
+  cfg.sourcePath = recipePath;
   tools.set(name, cfg);
   deps.registerRuntimeTool(cfg);
   deps.notify(ctx, `Tool persisted: ${name}`, "info");
@@ -289,7 +322,7 @@ export async function executeRegisterTool<TContext>(
     ],
     details: {
       args: cfg.args,
-      config: deps.configPath,
+      config: recipePath,
       defaults: cfg.defaults,
       ...(cfg.recipe?.async !== undefined ? { async: cfg.recipe.async } : {}),
       ...(cfg.recipe?.name ? { recipeName: cfg.recipe.name } : {}),