@llblab/pi-actors 0.14.3 → 0.16.0

package/lib/async-runs.ts

@@ -19,8 +19,8 @@ import {
   writeFileSync,
   writeSync,
 } from "node:fs";
-import { basename, extname, join, resolve } from "node:path";
 import { platform } from "node:os";
+import { basename, extname, join, resolve } from "node:path";
 
 import type {
   CommandTemplateFailureScope,
@@ -28,8 +28,9 @@ import type {
 } from "./command-templates.ts";
 import { substituteCommandTemplateToken } from "./command-templates.ts";
 import { writeJsonAtomic } from "./file-state.ts";
-import * as RecipeReferences from "./recipe-references.ts";
 import * as Paths from "./paths.ts";
+import * as RecipeReferences from "./recipe-references.ts";
+import * as RecipeUsage from "./recipe-usage.ts";
 
 export interface AsyncRunStartParams {
   async?: boolean;
@@ -139,8 +140,7 @@ function resolveArtifactPaths(
 function resolveRunTemplate(params: AsyncRunStartParams): {
   template: CommandTemplateValue;
 } {
-  if (!params.template)
-    throw new Error("spawn requires file or template.");
+  if (!params.template) throw new Error("spawn requires file or template.");
   const envelope: Record<string, unknown> = {};
   for (const key of [
     "args",
@@ -173,6 +173,12 @@ function resolveRecipeFile(file: string): string {
   return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
 }
 
+function isMutableUsageRecipeFile(file: string): boolean {
+  const userRoot = resolve(DEFAULT_RECIPE_ROOT);
+  const resolved = resolve(file);
+  return resolved.startsWith(`${userRoot}/`);
+}
+
 function readRecipeFile(file: string): AsyncRunStartParams {
   const path = resolveRecipeFile(file);
   const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
@@ -227,7 +233,8 @@ function isAlive(pid: number): boolean {
 }
 
 function pidMatchesRun(pid: number, cwd: string, stateDir: string): boolean {
-  if (platform() !== "linux" || !existsSync(`/proc/${pid}`)) return isAlive(pid);
+  if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
+    return isAlive(pid);
   try {
     const procCwd = readlinkSync(`/proc/${pid}/cwd`);
     const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
@@ -316,6 +323,9 @@ export function startRun(
     ? resolveRecipeFile(startParams.file)
     : undefined;
   const recipe = startParams.name || getRunIdFromFile(recipeFile);
+  if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
+    RecipeUsage.recordRecipeLaunch(recipeFile);
+  }
   const outFd = openSync(stdout, "a");
   const errFd = openSync(stderr, "a");
   const argv = ["--experimental-strip-types", RUNNER_PATH, stateDir];
@@ -405,15 +415,23 @@ function normalizeRunOutboxEvent(
       : `${run}:${index}`;
   return {
     ...(record.body !== undefined ? { body: record.body } : {}),
-    ...(typeof record.correlation_id === "string" ? { correlation_id: record.correlation_id } : {}),
+    ...(typeof record.correlation_id === "string"
+      ? { correlation_id: record.correlation_id }
+      : {}),
     ...(record.data !== undefined ? { data: record.data } : {}),
     delivery: normalizeRunOutboxDelivery(record.delivery),
-    ...(record.metadata && typeof record.metadata === "object" && !Array.isArray(record.metadata) ? { metadata: record.metadata as Record<string, unknown> } : {}),
+    ...(record.metadata &&
+    typeof record.metadata === "object" &&
+    !Array.isArray(record.metadata)
+      ? { metadata: record.metadata as Record<string, unknown> }
+      : {}),
     event,
     ...(typeof record.from === "string" ? { from: record.from } : {}),
     id,
     level: normalizeRunOutboxLevel(record.level),
-    ...(typeof record.reply_to === "string" ? { reply_to: record.reply_to } : {}),
+    ...(typeof record.reply_to === "string"
+      ? { reply_to: record.reply_to }
+      : {}),
     run,
     state_dir: stateDir,
     summary,
@@ -448,8 +466,9 @@ export function getRunStatus(runOrDir: string): Record<string, unknown> {
   const pid = Number(meta.pid || 0);
   const aliveOwnedRunner = Boolean(
     pid &&
-      isAlive(pid) &&
-      (!Array.isArray(meta.argv) || pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir)),
+    isAlive(pid) &&
+    (!Array.isArray(meta.argv) ||
+      pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir)),
   );
   const status: AsyncRunStatus = result
     ? Number(result.code ?? 0) === 0
@@ -555,7 +574,9 @@ export function appendRunOutboxEvent(
     ...(event.body !== undefined ? { body: event.body } : {}),
     ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
     ...(event.data !== undefined ? { data: event.data } : {}),
-    delivery: normalizeRunOutboxDelivery(event.delivery ?? (to === "coordinator" ? "followup" : "log")),
+    delivery: normalizeRunOutboxDelivery(
+      event.delivery ?? (to === "coordinator" ? "followup" : "log"),
+    ),
     event: type,
     from: event.from || `run:${run}`,
     level: normalizeRunOutboxLevel(event.level),
@@ -608,7 +629,9 @@ export function sendRunMessage(
     fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
     const bytes = writeSync(fd, payload);
     const trimmedMessage = message.trim().toLowerCase();
-    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(trimmedMessage);
+    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
+      trimmedMessage,
+    );
     writeFileSync(
       join(stateDir, "events.jsonl"),
       `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts: new Date().toISOString() })}\n`,

package/lib/command-templates.ts

@@ -541,7 +541,12 @@ function shouldResolveEmbeddedCommandTemplateToken(
 function isFalsyCommandTemplateValue(value: unknown): boolean {
   if (value === undefined || value === null || value === false) return true;
   const normalized = String(value).trim().toLowerCase();
-  return normalized === "" || normalized === "0" || normalized === "false" || normalized === "no";
+  return (
+    normalized === "" ||
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no"
+  );
 }
 
 function resolveCommandTemplateCondition(

package/lib/config.ts

@@ -6,12 +6,12 @@
 
 import { existsSync, readFileSync } from "node:fs";
 
+import type { CommandTemplateValue } from "./command-templates.ts";
+import * as CommandTemplates from "./command-templates.ts";
 import { writeJsonAtomic } from "./file-state.ts";
 import { normalizeToolName } from "./identity.ts";
-import * as CommandTemplates from "./command-templates.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as Schema from "./schema.ts";
-import type { CommandTemplateValue } from "./command-templates.ts";
 
 export interface RegisteredTool {
   name: string;
@@ -23,6 +23,7 @@ export interface RegisteredTool {
   template?: CommandTemplateValue;
   storedArgs?: string[];
   storedDefaults?: Record<string, string>;
+  sourcePath?: string;
 }
 
 export interface LoadConfigResult {

package/lib/execution.ts

@@ -4,9 +4,9 @@
  * Owns command-template invocation execution and pi tool-result payload formatting
  */
 
+import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import { formatFailureOutput, formatOutput, formatToolText } from "./output.ts";
-import * as CommandTemplates from "./command-templates.ts";
 import * as Schema from "./schema.ts";
 
 export interface ToolExecOptions {
@@ -268,9 +268,10 @@ function resolveNumericControlField(
   label: string,
 ): number | undefined {
   if (value === undefined) return undefined;
-  const resolved = typeof value === "string"
-    ? CommandTemplates.substituteCommandTemplateToken(value, values, label)
-    : value;
+  const resolved =
+    typeof value === "string"
+      ? CommandTemplates.substituteCommandTemplateToken(value, values, label)
+      : value;
   if (resolved === "") return undefined;
   const numeric = Number(resolved);
   if (!Number.isFinite(numeric) || numeric < 0)
@@ -407,7 +408,10 @@ async function executeTemplateConfig(
   const controlValues = { ...(context.defaults ?? {}), ...params };
   await applyDelay(normalized.delay, controlValues, signal);
   if (
-    !CommandTemplates.shouldRunCommandTemplateNode(normalized.when, controlValues)
+    !CommandTemplates.shouldRunCommandTemplateNode(
+      normalized.when,
+      controlValues,
+    )
   ) {
     return {
       branches: [],

package/lib/observability.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, relative, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
@@ -114,7 +114,9 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(typeof status.ownerId === "string"
         ? { ownerId: status.ownerId }
         : {}),
-      ...(status.artifacts && typeof status.artifacts === "object" && !Array.isArray(status.artifacts)
+      ...(status.artifacts &&
+      typeof status.artifacts === "object" &&
+      !Array.isArray(status.artifacts)
         ? { artifacts: status.artifacts as Record<string, string> }
         : {}),
       ...(status.terminal_handled ? { terminalHandled: true } : {}),
@@ -359,7 +361,11 @@ function parseOutboxLine(
       event,
       id,
       level: normalizeOutboxLevel(raw.level),
-      ...(raw.metadata && typeof raw.metadata === "object" && !Array.isArray(raw.metadata) ? { metadata: raw.metadata as Record<string, unknown> } : {}),
+      ...(raw.metadata &&
+      typeof raw.metadata === "object" &&
+      !Array.isArray(raw.metadata)
+        ? { metadata: raw.metadata as Record<string, unknown> }
+        : {}),
       run: run.run,
       stateDir: run.stateDir,
       summary,
@@ -413,7 +419,8 @@ export function shouldSendRunOutboxFollowUp(event: RunOutboxEvent): boolean {
 
 function commonDirectory(paths: string[]): string | undefined {
   if (paths.length === 0) return undefined;
-  const split = (path: string): string[] => dirname(path).split("/").filter(Boolean);
+  const split = (path: string): string[] =>
+    dirname(path).split("/").filter(Boolean);
   const first = split(paths[0]);
   let length = first.length;
   for (const path of paths.slice(1)) {
@@ -440,7 +447,9 @@ function formatPathGroup(label: string, paths: string[]): string {
   const unique = [...new Set(paths.filter(Boolean))].slice(0, 8);
   if (unique.length === 0) return "";
   const base = commonDirectory(unique);
-  const names = unique.map((path) => `\`${relativeName(base, path)}\``).join(", ");
+  const names = unique
+    .map((path) => `\`${relativeName(base, path)}\``)
+    .join(", ");
   return `\n${label}:\n- Base: ${base ? `\`${base}\`` : "current run"}\n- Files: ${names}`;
 }
 
@@ -464,7 +473,9 @@ function formatNamedArtifacts(artifacts: unknown): string {
 }
 
 function getOutboxField(event: RunOutboxEvent, key: string): unknown {
-  return event.data && typeof event.data === "object" && !Array.isArray(event.data)
+  return event.data &&
+    typeof event.data === "object" &&
+    !Array.isArray(event.data)
     ? (event.data as Record<string, unknown>)[key]
     : undefined;
 }
@@ -478,7 +489,8 @@ function formatBodyPreview(body: unknown): string {
 }
 
 export function formatRunOutboxMessage(event: RunOutboxEvent): string {
-  if (event.event === "command.done") return `Run ${event.run}: ${event.summary}`;
+  if (event.event === "command.done")
+    return `Run ${event.run}: ${event.summary}`;
   return `Run ${event.run}: ${event.summary}${formatBodyPreview(event.body)}${formatNamedArtifacts(getOutboxField(event, "artifacts"))}${formatRunFileList(getOutboxField(event, "run_files"))}`;
 }
 
@@ -491,9 +503,7 @@ export function getRunTransitionNotificationType(
   return "error";
 }
 
-export function shouldNotifyRunTransition(
-  transition: RunTransition,
-): boolean {
+export function shouldNotifyRunTransition(transition: RunTransition): boolean {
   if (transition.terminalHandled) return false;
   return (
     transition.to === "done" ||

package/lib/paths.ts

@@ -5,7 +5,8 @@
  */
 
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 export function getAgentDir(
   env: Record<string, string | undefined> = process.env,
@@ -33,3 +34,7 @@ export function getRunStateRoot(agentDir = getAgentDir()): string {
 export function getRecipeRoot(agentDir = getAgentDir()): string {
   return join(agentDir, "recipes");
 }
+
+export function getPackagedRecipeRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "recipes");
+}

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 =
@@ -20,25 +20,18 @@ export const REGISTER_TOOL_GUIDELINES = [
 ];
 
 export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
-- Local-first cybernetic tool memory: agents persist trusted local capabilities instead of repeating shell recipes.
-- Task = user work; template = execution graph; recipe = saved JSON; run = execution instance.
-- Command templates stay sync: string leaf, array sequence, object flags, parallel: true fanout.
-- Template flags: args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output; placeholders support {value??fallback} and {flag?yes:no}.
-- Recipes live in ~/.pi/agent/recipes/*.json and wrap templates with metadata/defaults/imports/artifacts.
-- Recipe imports are local variables: imports.alias -> {"name":"alias"} nodes and {alias.defaults.key} refs.
-- Imported recipes are definitions, not nested async runs; parent async:true creates one run.
-- async:true = detached lifecycle; spawn creates run actors from recipes/templates.
-- Actor run state lives under ~/.pi/agent/tmp/pi-actors/runs.
-- Use spawn/message/inspect for actor-level start/send/observe; runtime action internals are absorbed into the actor API.
-- Run lifecycle = state files, logs, actor messages, mailbox send, cancel/kill, compact status; do not busy-poll runs, rely on message/follow-up notifications and use message for explicit run-local commands.
-- Tool template may be a command template, recipe path/name, or co-located recipe.
-- register_tool makes compact persistent buttons; args may be typed or derived from placeholders.
-- For single calls or short pipelines, use foreground templates/tools.
-- For subagents, swarms, background music, or long fanout, prefer async recipes/runs.
-- Long async fanout = parent async recipe wrapping template(parallel: true) and imports; packaged fanout recipes bubble branch completion follow-ups by default.
-- If asked to explore pi-actors, read README.md, docs/README.md, docs/template-recipes.md, docs/async-runs.md, and recipes/.
-- Ambient triangles show active async commands/subagents for the launching coordinator.
-- After async run finish, inspect status/tail/messages before final artifacts.`;
+- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.
+- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
+- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.
+- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.
+- Recipes live in ~/.pi/agent/recipes/*.json, own template directly, and may declare metadata/defaults/imports/mailbox/artifacts.
+- 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 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.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   name: "Tool name in snake_case (e.g., 'transcribe')",
@@ -53,7 +46,7 @@ export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
   templateArray:
     "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.",
   templateNull: "Delete the tool when template is null.",
-  args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,model=openai-codex/gpt-5.5",
+  args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast",
   update: "Set to true to overwrite an existing tool registration.",
   values:
     "Optional default runtime placeholder values for a co-located template recipe.",

package/lib/recipe-discovery.ts

@@ -0,0 +1,226 @@
+/**
+ * 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"))
+    .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)]),
+          ),
+        }
+      : {}),
+  };
+}