@llblab/pi-actors 0.19.11 → 0.20.1

package/dist/lib/prompts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Prompt and schema copy helpers
+ * Zones: prompts, onboarding, tool schema copy
+ * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
+ */
+export declare const REGISTER_TOOL_DESCRIPTION: string;
+export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
+export declare const REGISTER_TOOL_GUIDELINES: string[];
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.\n- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.\n- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.";
+export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
+    readonly name: "Tool name in snake_case (e.g., 'transcribe')";
+    readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";
+    readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
+    readonly state_dir: "Optional async run state directory for a co-located template recipe.";
+    readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";
+    readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";
+    readonly templateNull: "Delete the tool when template is null.";
+    readonly 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";
+    readonly update: "Set to true to overwrite an existing tool registration.";
+    readonly values: "Optional default runtime placeholder values for a co-located template recipe.";
+};
+export declare function formatRegisteredToolPromptSnippet(template: unknown): string;
+export declare function formatRecipeToolPromptSnippet(recipe: string, asyncRecipe: boolean): string;

package/dist/lib/prompts.js

@@ -0,0 +1,50 @@
+/**
+ * Prompt and schema copy helpers
+ * Zones: prompts, onboarding, tool schema copy
+ * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
+ */
+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 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 = "Register persistent command templates as agent-callable tools";
+export const REGISTER_TOOL_GUIDELINES = [
+    "Use register_tool to wrap trusted local commands, scripts, programs, libraries, or template recipes as persistent pi tools.",
+    "After register_tool succeeds, the new tool is immediately callable and remains available after reload.",
+    'Set template=null or template="" in register_tool to delete a persisted tool.',
+    "Set update=true in register_tool to overwrite an existing tool registration.",
+];
+export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
+- 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}.
+- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
+- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
+- 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.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
+- 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; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
+- 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')",
+    description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",
+    async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.",
+    state_dir: "Optional async run state directory for a co-located template recipe.",
+    template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.",
+    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,mode=fast",
+    update: "Set to true to overwrite an existing tool registration.",
+    values: "Optional default runtime placeholder values for a co-located template recipe.",
+};
+export function formatRegisteredToolPromptSnippet(template) {
+    const rendered = typeof template === "string" ? template : JSON.stringify(template);
+    return `Execute command template: ${rendered}`;
+}
+export function formatRecipeToolPromptSnippet(recipe, asyncRecipe) {
+    return asyncRecipe
+        ? `Start async template recipe: ${recipe}`
+        : `Execute template recipe: ${recipe}`;
+}

package/dist/lib/recipe-discovery.d.ts

@@ -0,0 +1,50 @@
+/**
+ * File-discovered recipe registry helpers
+ * Zones: recipe discovery, tool exposure, migration diagnostics
+ * Owns filename identity discovery across prioritized recipe roots
+ */
+import type { RegisteredTool } from "./config.ts";
+import type { TemplateRecipeConfig } from "./recipe-references.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 RecipeIntegrityManifestEntry {
+    id: string;
+    path: string;
+    root: string;
+    sha256: string;
+    size: number;
+    tool: boolean;
+    active: boolean;
+    invalid: boolean;
+    disabled: boolean;
+    shadowed: boolean;
+}
+export interface RecipeDiscoveryResult {
+    active: Map<string, DiscoveredRecipe>;
+    entries: DiscoveredRecipe[];
+    diagnostics: string[];
+}
+export interface RecipeDiscoverySource {
+    root?: string;
+    file?: string;
+    defaultTool?: boolean;
+    mutableUsage?: boolean;
+}
+export declare function discoverRecipeSources(sources: RecipeDiscoverySource[]): RecipeDiscoveryResult;
+export declare function discoverRecipes(roots: string[]): RecipeDiscoveryResult;
+export declare function createRecipeIntegrityManifest(result: RecipeDiscoveryResult): RecipeIntegrityManifestEntry[];
+export declare function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown>;
+export declare function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined;

package/dist/lib/recipe-discovery.js

@@ -0,0 +1,317 @@
+/**
+ * File-discovered recipe registry helpers
+ * Zones: recipe discovery, tool exposure, migration diagnostics
+ * Owns filename identity discovery across prioritized recipe roots
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import * as CommandTemplates from "./command-templates.js";
+import * as RecipeReferences from "./recipe-references.js";
+import * as Schema from "./schema.js";
+function assertToolSafeRepeatConfig(config, argTypes, defaults) {
+    if (typeof config === "string" || config === undefined || config === null)
+        return;
+    if (Array.isArray(config)) {
+        for (const step of config)
+            assertToolSafeRepeatConfig(step, argTypes, defaults);
+        return;
+    }
+    if (typeof config !== "object")
+        return;
+    const node = config;
+    if (typeof node.repeat === "string") {
+        const trimmed = node.repeat.trim();
+        if (!/^\d+$/.test(trimmed)) {
+            const match = trimmed.match(/^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/);
+            if (!match || (argTypes[match[1]]?.kind !== "array" && !Array.isArray(defaults[match[1]])))
+                throw new Error("Command template repeat must be a positive integer or {array.length} with an array argument/default.");
+        }
+    }
+    assertToolSafeRepeatConfig(node.template, argTypes, defaults);
+    assertToolSafeRepeatConfig(node.recover, argTypes, defaults);
+}
+function listRecipeFiles(root) {
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isFile() &&
+        entry.name.endsWith(".json") &&
+        entry.name !== "legacy-tool-registry-migration-report.json")
+        .map((entry) => join(root, entry.name))
+        .sort();
+}
+function getRecipeConfigDiagnostics(file, config) {
+    if (!config)
+        return [`Invalid recipe: ${file}`];
+    return CommandTemplates.getCommandTemplateWarnings(typeof config.template === "string" ? config.template : { template: config.template }).map((warning) => `Recipe ${file}: ${warning}`);
+}
+function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false) {
+    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: defaultTool && !disabled && !invalid,
+            mutableUsage,
+            diagnostics: getRecipeConfigDiagnostics(file, config),
+            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) {
+    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,
+        }))
+        : [];
+}
+function getRecipeRootDiagnostics(sources) {
+    const diagnostics = [];
+    const roots = new Set(sources
+        .map((source) => source.root)
+        .filter((root) => typeof root === "string"));
+    for (const root of roots) {
+        try {
+            if (!existsSync(root))
+                continue;
+            const stat = statSync(root);
+            if ((stat.mode & 0o002) !== 0) {
+                diagnostics.push(`Recipe root is world-writable; review permissions: ${root}`);
+            }
+            if ((stat.mode & 0o020) !== 0) {
+                diagnostics.push(`Recipe root is group-writable; review ownership and permissions: ${root}`);
+            }
+        }
+        catch (error) {
+            diagnostics.push(`Failed to inspect recipe root ${root}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return diagnostics;
+}
+export function discoverRecipeSources(sources) {
+    const entries = sources.flatMap((source, priority) => filesForSource(source).map(({ root, file, defaultTool, mutableUsage }) => readDiscoveredRecipe(root, file, priority, defaultTool, mutableUsage)));
+    const byId = new Map();
+    for (const entry of entries) {
+        const bucket = byId.get(entry.id) ?? [];
+        bucket.push(entry);
+        byId.set(entry.id, bucket);
+    }
+    const active = new Map();
+    const diagnostics = getRecipeRootDiagnostics(sources);
+    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) {
+    return discoverRecipeSources(roots.map((root) => ({ root })));
+}
+function recipeUsage(config) {
+    const usage = config?.usage;
+    return usage && typeof usage === "object" && !Array.isArray(usage)
+        ? usage
+        : undefined;
+}
+function cleanupRecommendation(entry) {
+    if (entry.invalid) {
+        return {
+            id: entry.id,
+            path: entry.path,
+            reason: "invalid recipe blocks lower-priority entries with the same id",
+            actions: ["fix", "delete", "archive"],
+        };
+    }
+    if (entry.shadowed) {
+        return {
+            id: entry.id,
+            path: entry.path,
+            reason: "shadowed by a higher-priority recipe",
+            actions: ["merge", "delete", "archive"],
+        };
+    }
+    if (entry.disabled) {
+        return {
+            id: entry.id,
+            path: entry.path,
+            reason: "disabled recipe is retained but not exposed as a tool",
+            actions: ["keep disabled", "delete", "archive"],
+        };
+    }
+    const usage = recipeUsage(entry.config);
+    const calls = Number(usage?.calls ?? 0);
+    if (entry.mutableUsage && entry.tool && calls === 0) {
+        return {
+            id: entry.id,
+            path: entry.path,
+            reason: "active user tool has no recorded launches",
+            actions: ["keep as tool", "move out of tool root", "delete", "archive"],
+        };
+    }
+    if (entry.mutableUsage && !entry.tool) {
+        return {
+            id: entry.id,
+            path: entry.path,
+            reason: "user recipe is a component, not an active tool",
+            actions: ["keep component", "move into tool root", "merge", "delete", "archive"],
+        };
+    }
+    if (entry.shadows.length > 0) {
+        return {
+            id: entry.id,
+            path: entry.path,
+            reason: `overrides ${entry.shadows.length} lower-priority recipe(s)`,
+            actions: ["keep override", "merge", "delete", "archive"],
+        };
+    }
+    return undefined;
+}
+export function createRecipeIntegrityManifest(result) {
+    return result.entries
+        .map((entry) => {
+        const bytes = readFileSync(entry.path);
+        return {
+            active: entry.active,
+            disabled: entry.disabled,
+            id: entry.id,
+            invalid: entry.invalid,
+            path: entry.path,
+            root: entry.root,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            shadowed: entry.shadowed,
+            size: bytes.byteLength,
+            tool: entry.tool,
+        };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path));
+}
+function recommendationForEntry(entry, activePath) {
+    const recommendation = cleanupRecommendation(entry);
+    if (!recommendation)
+        return undefined;
+    if (entry.shadowed && activePath) {
+        return {
+            ...recommendation,
+            reason: `shadowed by ${activePath}`,
+        };
+    }
+    return recommendation;
+}
+export function summarizeDiscovery(result) {
+    const recommendations = result.entries
+        .map((entry) => recommendationForEntry(entry, result.active.get(entry.id)?.path))
+        .filter((entry) => Boolean(entry))
+        .sort((a, b) => String(a.id).localeCompare(String(b.id)) || String(a.path).localeCompare(String(b.path)));
+    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,
+            ...(recipeUsage(entry.config) ? { usage: recipeUsage(entry.config) } : {}),
+        })).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)),
+        recommendations,
+        diagnostics: result.diagnostics,
+        integrity_manifest: createRecipeIntegrityManifest(result),
+    };
+}
+export function toRegisteredTool(entry) {
+    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 explicitArgTypes = Object.fromEntries((cfg.args ?? []).map((arg) => {
+        const parsed = Schema.parseToolArgToken(String(arg));
+        return [parsed.arg, parsed.type];
+    }));
+    assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, cfg.defaults ?? {});
+    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/dist/lib/recipe-migration.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Legacy tool-registry 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
+ */
+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;
+}
+export declare function migrateLegacyToolRegistry(options: LegacyRegistryMigrationOptions): LegacyRegistryMigrationResult;

package/dist/lib/recipe-migration.js

@@ -0,0 +1,90 @@
+/**
+ * Legacy tool-registry 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.js";
+import { writeJsonAtomic } from "./file-state.js";
+import * as RecipeReferences from "./recipe-references.js";
+function recipePathForTool(recipeRoot, name) {
+    return join(recipeRoot, `${name}.json`);
+}
+function toRecipeConfig(tool) {
+    return {
+        description: tool.description,
+        ...(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) {
+    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) {
+    const { configPath, recipeRoot, reservedToolNames } = options;
+    const result = {
+        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, "legacy-tool-registry-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/dist/lib/recipe-references.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Template recipe reference helpers
+ * Zones: registry config, async runs, path resolution
+ * Owns detection, loading, and recipe-layer expansion for template recipe files
+ */
+import type { CommandTemplateValue } from "./command-templates.ts";
+import * as CommandTemplates from "./command-templates.ts";
+export interface TemplateRecipeImportBinding {
+    from?: string;
+    defaults?: Record<string, unknown>;
+    values?: Record<string, unknown>;
+}
+export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
+export interface TemplateRecipeMailbox {
+    accepts?: string[];
+    emits?: string[];
+}
+export interface TemplateRecipeDefinition {
+    name?: string;
+    description?: string;
+    disabled?: boolean;
+    imports?: Record<string, TemplateRecipeImport>;
+    template: CommandTemplateValue;
+    args?: string[];
+    defaults?: Record<string, unknown>;
+    parallel?: boolean;
+    label?: string;
+    when?: boolean | string;
+    timeout?: number | string;
+    delay?: number | string;
+    output?: string;
+    artifacts?: Record<string, string>;
+    mailbox?: TemplateRecipeMailbox;
+    retire_when?: "children_terminal";
+    retry?: number | string;
+    failure?: CommandTemplates.CommandTemplateFailureScope;
+    recover?: CommandTemplateValue;
+    repeat?: number;
+    values?: Record<string, unknown>;
+    usage?: Record<string, unknown>;
+}
+export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
+    async?: boolean;
+    state_dir?: string;
+}
+export interface TemplateRecipeContextRecord {
+    alias?: string;
+    depth: number;
+    file: string;
+    import_path: string[];
+    name: string;
+    recipe: Record<string, unknown>;
+    role: "entry" | "import";
+}
+export interface ReadResolvedRecipeConfigOptions {
+    includeActorRecipeContext?: boolean;
+}
+export declare function resolveRecipePath(value: string, recipeRoot?: string): string;
+export declare function getRecipePath(value: unknown, recipeRoot?: string): string | undefined;
+export declare function readRawRecipeConfig(path: string): Record<string, unknown> | undefined;
+export declare function getRecipeIdFromPath(file: string): string;
+export declare function readResolvedRecipeConfig(file: string, stack?: string[], options?: ReadResolvedRecipeConfigOptions): TemplateRecipeConfig | undefined;
+export declare function buildRecipeContextRecords(file: string): TemplateRecipeContextRecord[];
+export declare function getRecipeTemplate(value: unknown): CommandTemplateValue | undefined;
+export declare function isRecipeReference(value: unknown): boolean;
+export declare function isAsyncRecipeReference(value: unknown): boolean;
+export declare function isRecipeTool(template: unknown, recipe: TemplateRecipeConfig | undefined): boolean;