@llblab/pi-actors 0.45.0 → 0.46.0

package/dist/lib/inspector.js

@@ -56,9 +56,37 @@ export function readActorInspectorRecipe(stateDir) {
         !Array.isArray(primary.recipe)
         ? primary.recipe
         : undefined;
-    const redactedRecord = (value) => SessionEvidence.redactSessionEvidenceValue(Object.fromEntries(Object.entries(value).filter(([key, entry]) => entry !== undefined &&
-        key !== "recipe_dir" &&
-        key !== "skill_dir")));
+    const stripPrivateOrigins = (value) => {
+        if (Array.isArray(value))
+            return value.map(stripPrivateOrigins);
+        if (!value || typeof value !== "object")
+            return value;
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key, entry]) => entry !== undefined &&
+            key !== "recipe_dir" &&
+            key !== "skill_dir" &&
+            key !== "source_file")
+            .map(([key, entry]) => [
+            key,
+            key === "actorRecipeContext" && entry && typeof entry === "object"
+                ? stripPrivateOrigins(Object.fromEntries(Object.entries(entry).filter(([contextKey]) => contextKey !== "file")))
+                : stripPrivateOrigins(entry),
+        ]));
+    };
+    const redactedRecord = (value) => SessionEvidence.redactSessionEvidenceValue(stripPrivateOrigins(value));
+    const primarySourceKind = primary?.source_kind === "active_skill_component"
+        ? "active_skill_component"
+        : primary?.source_kind === "user_registry_capability" ||
+            meta.launch_source === "tool"
+            ? "user_registry_capability"
+            : "explicit_file_recipe";
+    const primaryLogicalReference = typeof primary?.logical_reference === "string"
+        ? primary.logical_reference
+        : typeof primary?.name === "string"
+            ? primary.name
+            : typeof meta.recipe === "string"
+                ? meta.recipe
+                : "unknown";
     const launchValues = meta.values && typeof meta.values === "object" && !Array.isArray(meta.values)
         ? Object.fromEntries(Object.entries(meta.values).filter(([key]) => key !== "recipe_dir" && key !== "skill_dir"))
         : meta.values;
@@ -66,17 +94,27 @@ export function readActorInspectorRecipe(stateDir) {
         composition: contexts.map((entry) => redactedRecord({
             ...(typeof entry.alias === "string" ? { alias: entry.alias } : {}),
             depth: entry.depth,
-            file: entry.file,
             import_path: entry.import_path,
-            name: entry.name,
-            qualified_name: entry.qualified_name,
+            logical_reference: entry.logical_reference ?? entry.name,
+            recipe_stem: entry.name,
+            role: entry.role,
+            ...(typeof entry.skill === "string" ? { skill: entry.skill } : {}),
+            source_kind: entry.source_kind === "active_skill_component"
+                ? "active_skill_component"
+                : entry.source_kind === "user_registry_capability" ||
+                    (entry.depth === 0 && meta.launch_source === "tool")
+                    ? "user_registry_capability"
+                    : "explicit_file_recipe",
         })),
         ...(definition ? { definition: redactedRecord(definition) } : {}),
         diagnostics: result.diagnostics.map((diagnostic) => diagnostic.message),
         identity: redactedRecord({
             run: meta.run,
             recipe: meta.recipe,
-            recipe_file: meta.recipe_file,
+            recipe_stem: primary?.name ?? meta.recipe,
+            logical_reference: primaryLogicalReference,
+            ...(typeof primary?.skill === "string" ? { skill: primary.skill } : {}),
+            source_kind: primarySourceKind,
             launch_source: meta.launch_source,
         }),
         launch: redactedRecord({

package/dist/lib/paths.d.ts

@@ -25,4 +25,3 @@ export declare function getExtensionSkillsDir(extensionUrl: string): string;
 export declare function getExistingExtensionSkillPaths(extensionUrl: string): string[];
 export declare function getRecipeRoot(agentDir?: string): string;
 export declare function getRecipeDraftRoot(agentDir?: string): string;
-export declare function getPackagedRecipeRoot(): string;

package/dist/lib/paths.js

@@ -70,10 +70,3 @@ export function getRecipeRoot(agentDir = getAgentDir()) {
 export function getRecipeDraftRoot(agentDir = getAgentDir()) {
     return join(getRecipeRoot(agentDir), "drafts");
 }
-export function getPackagedRecipeRoot() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const compiledRoot = resolve(here, "..", "..", "recipes");
-    if (existsSync(compiledRoot))
-        return compiledRoot;
-    return resolve(here, "..", "recipes");
-}

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 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 and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, 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/control/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- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+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 and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, 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/control/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- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/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.";

package/dist/lib/prompts.js

@@ -24,8 +24,8 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
-- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.
+- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",

package/dist/lib/recipes-context.js

@@ -78,7 +78,7 @@ export function findPiPrintPromptIndex(args) {
 function matchesActorContext(record, context) {
     if (!context)
         return record.role === "entry";
-    if (context.file && context.file === record.file)
+    if (context.file && context.file === record.source_file)
         return true;
     if (context.name && context.name === record.name)
         return true;
@@ -105,7 +105,7 @@ export function markRecipeContextRecords(records, context) {
 }
 export function formatRecipeContextJsonl(records, context) {
     return markRecipeContextRecords(records, context)
-        .map((record) => JSON.stringify(record))
+        .map(({ source_file: _sourceFile, ...record }) => JSON.stringify(record))
         .join("\n");
 }
 export function buildRecipeContextPromptBlock(records, context) {

package/dist/lib/recipes-references.d.ts

@@ -12,7 +12,6 @@ export interface TemplateRecipeImportBinding {
 }
 export type TemplateRecipeImport = string | TemplateRecipeImportBinding;
 export interface TemplateRecipeDefinition {
-    name?: string;
     description?: string;
     disabled?: boolean;
     imports?: Record<string, TemplateRecipeImport>;
@@ -39,6 +38,7 @@ export interface TemplateRecipeDefinition {
     usage?: Record<string, unknown>;
 }
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
+    name?: string;
     async?: boolean;
     recipe_dir?: string;
     skill_dir?: string;
@@ -46,31 +46,46 @@ export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
 export interface TemplateRecipeContextRecord {
     alias?: string;
     depth: number;
-    file: string;
     import_path: string[];
+    logical_reference: string;
     name: string;
-    qualified_name?: string;
     recipe: Record<string, unknown>;
     role: "entry" | "import";
+    skill?: string;
+    source_file: string;
+    source_kind: "active_skill_component" | "explicit_file_recipe" | "user_registry_capability";
 }
 export interface ReadResolvedRecipeConfigOptions {
     includeActorRecipeContext?: boolean;
+    skillContext?: ActiveSkillRecipeContext;
 }
 export interface ActiveSkillRecipeSource {
     name: string;
     filePath?: string;
     baseDir?: string;
 }
-export declare function setActiveSkillRecipeSources(skills: ActiveSkillRecipeSource[]): void;
-export declare function getActiveSkillRecipeNamespaces(): Record<string, string[]>;
-export declare function resolveRecipePath(value: string, recipeRoot?: string): string;
-export declare function resolveRecipeReferencePath(value: unknown, currentRecipeRoot?: string): string | undefined;
-export declare function getRecipePath(value: unknown, recipeRoot?: string): string | undefined;
+export interface ActiveSkillRecipeContext {
+    readonly namespaces: Readonly<Record<string, readonly string[]>>;
+}
+export declare function createActiveSkillRecipeContext(skills: ActiveSkillRecipeSource[]): ActiveSkillRecipeContext;
+export declare const EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT: ActiveSkillRecipeContext;
+export declare function getActiveSkillRecipeNamespaces(context: ActiveSkillRecipeContext): Record<string, string[]>;
+export interface ActiveSkillRecipeComponent {
+    file: string;
+    identity: string;
+    imports: Record<string, string>;
+    skill: string;
+    stem: string;
+}
+export declare function listActiveSkillRecipeComponents(context: ActiveSkillRecipeContext): ActiveSkillRecipeComponent[];
+export declare function resolveRecipePath(value: string, baseDir?: string): string;
+export declare function resolveRecipeReferencePath(value: unknown, baseDir?: string, context?: ActiveSkillRecipeContext): string | undefined;
+export declare function getRecipePath(value: unknown, baseDir?: string, context?: ActiveSkillRecipeContext): string | undefined;
 export declare function diagnoseRawRecipeConfigFailure(path: 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 buildRecipeContextRecords(file: string, context?: ActiveSkillRecipeContext): TemplateRecipeContextRecord[];
 export declare function getRecipeTemplate(value: unknown): CommandTemplateValue | undefined;
 export declare function isRecipeReference(value: unknown): boolean;
 export declare function isAsyncRecipeReference(value: unknown): boolean;

package/dist/lib/recipes-references.js

@@ -3,9 +3,8 @@
  * Zones: registry config, async runs, path resolution
  * Owns detection, loading, and recipe-layer expansion for template recipe files
  */
-import { existsSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 import * as RecipeControl from "./recipe-control.js";
@@ -13,9 +12,8 @@ import * as Schema from "./schema.js";
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
 const RUNTIME_RECIPE_VALUE_NAMES = new Set(["recipe_dir", "skill_dir"]);
-const activeSkillRecipeRoots = new Map();
-export function setActiveSkillRecipeSources(skills) {
-    activeSkillRecipeRoots.clear();
+export function createActiveSkillRecipeContext(skills) {
+    const rootsByName = new Map();
     for (const skill of skills) {
         const name = skill.name.trim();
         const skillDir = skill.baseDir
@@ -25,62 +23,132 @@ export function setActiveSkillRecipeSources(skills) {
                 : undefined;
         if (!name || !skillDir)
             continue;
-        const roots = activeSkillRecipeRoots.get(name) ?? new Set();
+        const roots = rootsByName.get(name) ?? new Set();
         roots.add(resolve(skillDir, "recipes"));
-        activeSkillRecipeRoots.set(name, roots);
+        rootsByName.set(name, roots);
     }
-}
-export function getActiveSkillRecipeNamespaces() {
-    return Object.fromEntries([...activeSkillRecipeRoots.entries()]
+    const namespaces = Object.fromEntries([...rootsByName.entries()]
         .sort(([left], [right]) => left.localeCompare(right))
-        .map(([name, roots]) => [name, [...roots].sort()]));
+        .map(([name, roots]) => [name, Object.freeze([...roots].sort())]));
+    return Object.freeze({ namespaces: Object.freeze(namespaces) });
+}
+export const EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT = createActiveSkillRecipeContext([]);
+export function getActiveSkillRecipeNamespaces(context) {
+    return Object.fromEntries(Object.entries(context.namespaces).map(([name, roots]) => [
+        name,
+        [...roots],
+    ]));
+}
+function nestedRecipeFiles(root) {
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            return nestedRecipeFiles(path);
+        return entry.isFile() && /\.(?:json|md)$/u.test(entry.name) ? [path] : [];
+    });
+}
+export function listActiveSkillRecipeComponents(context) {
+    const components = [];
+    for (const [skill, roots] of Object.entries(context.namespaces)) {
+        if (roots.length > 1)
+            throw new Error(`Duplicate active Skill identity ${skill}: ${roots.join(", ")}`);
+        const root = roots[0];
+        if (!root || !existsSync(root))
+            continue;
+        const direct = readdirSync(root, { withFileTypes: true });
+        for (const entry of direct.filter((candidate) => candidate.isDirectory())) {
+            const nested = nestedRecipeFiles(join(root, entry.name));
+            if (nested.length > 0)
+                throw new Error(`Nested Skill Recipe file is not addressable: ${nested[0]}`);
+        }
+        const files = direct
+            .filter((entry) => entry.isFile() && /\.(?:json|md)$/u.test(entry.name))
+            .map((entry) => join(root, entry.name));
+        const byStem = new Map();
+        for (const file of files) {
+            const stem = getRecipeIdFromPath(file);
+            const matches = byStem.get(stem) ?? [];
+            matches.push(file);
+            byStem.set(stem, matches);
+        }
+        for (const [stem, matches] of [...byStem].sort(([a], [b]) => a.localeCompare(b))) {
+            if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(stem))
+                throw new Error(`Invalid Skill Recipe filename stem: ${stem}`);
+            if (matches.length > 1)
+                throw new Error(`Skill Recipe stem collision: ${skill}/${stem} has both .json and .md files`);
+            const file = matches[0];
+            const raw = readRawRecipeConfig(file);
+            if (!raw || !Object.hasOwn(raw, "template"))
+                throw new Error(`Invalid Skill Recipe component: ${skill}/${stem}`);
+            assertRecipeHasNoDeclaredName(raw);
+            components.push({
+                file,
+                identity: `${skill}/${stem}`,
+                imports: Object.fromEntries(Object.entries(getRecipeImports(raw)).map(([alias, value]) => [
+                    alias,
+                    getImportFrom(value),
+                ])),
+                skill,
+                stem,
+            });
+        }
+    }
+    return components;
 }
-function qualifiedRecipeNameForFile(file) {
+const SKILL_RECIPE_REFERENCE = /^([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\/([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/;
+function qualifiedRecipeNameForFile(file, context) {
     const path = resolve(file);
-    const stdRelation = relative(Paths.getPackagedRecipeRoot(), path);
-    if (stdRelation &&
-        !stdRelation.startsWith("..") &&
-        !isAbsolute(stdRelation)) {
-        return `std:${stdRelation.replace(/\.(?:json|md)$/u, "")}`;
-    }
-    for (const [skillName, roots] of activeSkillRecipeRoots) {
-        if (roots.size !== 1)
+    for (const [skillName, roots] of Object.entries(context.namespaces)) {
+        if (roots.length !== 1)
             continue;
-        const root = [...roots][0];
+        const root = roots[0];
         const relation = relative(root, path);
-        if (relation && !relation.startsWith("..") && !isAbsolute(relation))
-            return `skill:${skillName}/${relation.replaceAll("\\", "/").replace(/\.(?:json|md)$/u, "")}`;
+        if (relation &&
+            dirname(relation) === "." &&
+            !relation.startsWith("..") &&
+            !isAbsolute(relation)) {
+            return `${skillName}/${basename(relation, extname(relation))}`;
+        }
     }
     return undefined;
 }
-function qualifiedRecipeCandidates(value) {
+function assertRecipeReferencePrefixWasNotRemoved(value) {
     if (value.startsWith("std:")) {
-        return recipeNameFiles(value.slice(4)).map((file) => resolve(Paths.getPackagedRecipeRoot(), file));
+        throw new Error("std: Recipe references were removed in pi-actors 0.46.\nUse <skill>/<recipe> or an explicit .json/.md file path.");
     }
-    if (!value.startsWith("skill:"))
+    if (value.startsWith("skill:")) {
+        throw new Error("skill: Recipe references were removed in pi-actors 0.46.\nUse <skill>/<recipe> without a prefix.");
+    }
+}
+function skillRecipeCandidates(value, context) {
+    const match = SKILL_RECIPE_REFERENCE.exec(value);
+    if (!match)
         return undefined;
-    const qualified = value.slice(6);
-    const separator = qualified.indexOf("/");
-    if (separator <= 0 || separator === qualified.length - 1)
-        throw new Error(`Invalid Skill Recipe reference: ${value}`);
-    const skillName = qualified.slice(0, separator);
-    const recipeName = qualified.slice(separator + 1);
-    const roots = [...(activeSkillRecipeRoots.get(skillName) ?? [])];
+    const [, skillName, recipeName] = match;
+    const roots = [...(context.namespaces[skillName] ?? [])];
     if (roots.length === 0)
-        throw new Error(`Active Skill Recipe namespace not found: ${skillName}`);
+        throw new Error(`Active Skill Recipe not found: ${skillName}/${recipeName}`);
     if (roots.length > 1)
-        throw new Error(`Ambiguous active Skill Recipe namespace ${skillName}: ${roots.join(", ")}`);
+        throw new Error(`Duplicate active Skill identity ${skillName}: ${roots.join(", ")}`);
     const root = roots[0];
-    return recipeNameFiles(recipeName).map((file) => {
-        const candidate = resolve(root, file);
-        const relation = relative(root, candidate);
-        if (!relation || relation.startsWith("..") || isAbsolute(relation))
-            throw new Error(`Skill Recipe reference escapes its recipes root: ${value}`);
-        return candidate;
-    });
+    const candidates = ["json", "md"].map((extension) => resolve(root, `${recipeName}.${extension}`));
+    const existing = candidates.filter((candidate) => existsSync(candidate));
+    if (existing.length > 1) {
+        throw new Error(`Skill Recipe stem collision: ${skillName}/${recipeName} has both .json and .md files`);
+    }
+    return candidates;
 }
-function hasWhitespace(value) {
-    return /\s/.test(value);
+function recipeReferenceCandidates(value, baseDir, context) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    assertRecipeReferencePrefixWasNotRemoved(trimmed);
+    if (trimmed.endsWith(".json") || trimmed.endsWith(".md")) {
+        return [resolve(baseDir, trimmed)];
+    }
+    return skillRecipeCandidates(trimmed, context);
 }
 function findOwningSkillDir(recipeFile) {
     let current = dirname(recipeFile);
@@ -93,6 +161,11 @@ function findOwningSkillDir(recipeFile) {
         current = parent;
     }
 }
+function assertRecipeHasNoDeclaredName(raw) {
+    if (!Object.hasOwn(raw, "name"))
+        return;
+    throw new Error("Recipe.name was removed in pi-actors 0.46.\nFile-backed Recipe identity is derived from its file name.");
+}
 function assertRuntimeRecipeValuesNotDeclared(raw) {
     const args = Array.isArray(raw.args)
         ? Schema.getExplicitToolArgNames(raw.args.map(String))
@@ -105,82 +178,28 @@ function assertRuntimeRecipeValuesNotDeclared(raw) {
         }
     }
 }
-export function resolveRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
-    const trimmed = value.trim();
-    const repoRoot = resolve(recipeRoot, "..");
-    const expanded = trimmed
-        .replaceAll("{repo}", repoRoot)
-        .replaceAll("{agent}", Paths.getAgentDir());
-    if (expanded.startsWith("~/"))
-        return resolve(homedir(), expanded.slice(2));
-    if (expanded.includes("/"))
-        return resolve(expanded);
-    return resolve(recipeRoot, expanded.endsWith(".json") || expanded.endsWith(".md")
-        ? expanded
-        : `${expanded}.json`);
-}
-function isBareRecipeName(value) {
-    const trimmed = value.trim();
-    return (Boolean(trimmed) &&
-        !trimmed.includes("/") &&
-        !trimmed.startsWith("~") &&
-        !trimmed.includes("{"));
+export function resolveRecipePath(value, baseDir = Paths.getRecipeRoot()) {
+    const candidates = recipeReferenceCandidates(value, baseDir, EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT);
+    if (!candidates || candidates.length !== 1) {
+        throw new Error(`Recipe file reference must be an explicit .json or .md path: ${value}`);
+    }
+    return candidates[0];
 }
-function recipeNameFiles(value) {
-    const trimmed = value.trim();
-    if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
-        return [trimmed];
-    return [`${trimmed}.json`, `${trimmed}.md`];
-}
-function recipeCandidatePaths(value, currentRecipeRoot) {
-    const qualified = qualifiedRecipeCandidates(value.trim());
-    if (qualified)
-        return qualified;
-    if (!isBareRecipeName(value))
-        return [resolveRecipePath(value, currentRecipeRoot)];
-    const roots = [
-        Paths.getRecipeRoot(),
-        currentRecipeRoot,
-        Paths.getPackagedRecipeRoot(),
-    ];
-    return [
-        ...new Set(roots.flatMap((root) => recipeNameFiles(value).map((file) => resolve(root, file)))),
-    ];
-}
-function resolveRecipeImportPath(value, currentRecipeRoot) {
-    const candidates = recipeCandidatePaths(value, currentRecipeRoot);
+function resolveRecipeImportPath(value, recipeDir, context) {
+    const candidates = recipeReferenceCandidates(value, recipeDir, context);
+    if (!candidates) {
+        throw new Error(`Recipe import must use <skill>/<recipe> or an explicit .json/.md file path: ${value}`);
+    }
     return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
-export function resolveRecipeReferencePath(value, currentRecipeRoot = Paths.getRecipeRoot()) {
+export function resolveRecipeReferencePath(value, baseDir = Paths.getRecipeRoot(), context = EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT) {
     if (typeof value !== "string")
         return undefined;
-    const trimmed = value.trim();
-    if (!trimmed || hasWhitespace(trimmed))
-        return undefined;
-    for (const path of recipeCandidatePaths(trimmed, currentRecipeRoot)) {
-        if (!existsSync(path))
-            continue;
-        try {
-            const raw = readRawRecipeConfig(path);
-            if (raw && typeof raw === "object" && Object.hasOwn(raw, "template"))
-                return path;
-            return path;
-        }
-        catch {
-            return path;
-        }
-    }
-    return undefined;
+    const candidates = recipeReferenceCandidates(value, baseDir, context);
+    return candidates?.find((candidate) => existsSync(candidate));
 }
-export function getRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    if (!trimmed || hasWhitespace(trimmed))
-        return undefined;
-    if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
-        return resolveRecipePath(trimmed, recipeRoot);
-    return resolveRecipeReferencePath(trimmed, recipeRoot);
+export function getRecipePath(value, baseDir = Paths.getRecipeRoot(), context = EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT) {
+    return resolveRecipeReferencePath(value, baseDir, context);
 }
 function isImportNode(value) {
     if (!isRecord(value) || Object.hasOwn(value, "template"))
@@ -655,7 +674,7 @@ function withActorRecipeContext(value, context) {
     return { actorRecipeContext: context, template: value };
 }
 function loadDelegatedRecipe(value, currentRecipeFile, stack, options) {
-    const path = resolveRecipeReferencePath(value, dirname(currentRecipeFile));
+    const path = resolveRecipeReferencePath(value, dirname(currentRecipeFile), options.skillContext);
     if (!path)
         return undefined;
     const config = readResolvedRecipeConfig(path, [...stack, currentRecipeFile], options);
@@ -767,12 +786,13 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
     const raw = readRawRecipeConfig(path);
     if (!raw || !Object.hasOwn(raw, "template"))
         return undefined;
+    assertRecipeHasNoDeclaredName(raw);
     RecipeControl.assertRecipeHasNoMailbox(raw);
     assertRuntimeRecipeValuesNotDeclared(raw);
     assertRecipeArgumentContract(raw);
     const imports = {};
     for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
-        const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
+        const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path), options.skillContext ?? EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT);
         const config = readResolvedRecipeConfig(importPath, [...stack, path], options);
         if (!config)
             throw new Error(`Recipe import not found: ${alias}`);
@@ -782,7 +802,7 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         imports[alias] = {
             alias,
             file: importPath,
-            name: config.name ?? alias,
+            name: getRecipeIdFromPath(importPath),
             config,
             defaults: { ...(config.defaults ?? {}), ...(bindingDefaults ?? {}) },
             values: {
@@ -930,7 +950,7 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
     };
 }
-function collectRecipeContextRecords(file, stack, importPath, alias) {
+function collectRecipeContextRecords(file, stack, importPath, context, alias) {
     const path = resolveRecipePath(file, stack.length > 0 ? dirname(stack.at(-1)) : Paths.getRecipeRoot());
     if (stack.includes(path)) {
         throw new Error(`Cyclic recipe import: ${[...stack, path].join(" -> ")}`);
@@ -941,26 +961,32 @@ function collectRecipeContextRecords(file, stack, importPath, alias) {
     const raw = readRawRecipeConfig(path);
     if (!raw || !Object.hasOwn(raw, "template"))
         return [];
-    const qualifiedName = qualifiedRecipeNameForFile(path);
+    assertRecipeHasNoDeclaredName(raw);
+    const qualifiedName = qualifiedRecipeNameForFile(path, context);
+    const skill = qualifiedName?.split("/", 1)[0];
     const record = {
         ...(alias ? { alias } : {}),
         depth: stack.length,
-        file: path,
         import_path: importPath,
+        logical_reference: qualifiedName ?? basename(path),
         name: getRecipeIdFromPath(path),
-        ...(qualifiedName ? { qualified_name: qualifiedName } : {}),
         recipe: raw,
         role: stack.length === 0 ? "entry" : "import",
+        ...(skill ? { skill } : {}),
+        source_file: path,
+        source_kind: qualifiedName
+            ? "active_skill_component"
+            : "explicit_file_recipe",
     };
     const imports = getRecipeImports(raw);
     const children = Object.entries(imports).flatMap(([childAlias, binding]) => {
-        const importFile = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
-        return collectRecipeContextRecords(importFile, [...stack, path], [...importPath, childAlias], childAlias);
+        const importFile = resolveRecipeImportPath(getImportFrom(binding), dirname(path), context);
+        return collectRecipeContextRecords(importFile, [...stack, path], [...importPath, childAlias], context, childAlias);
     });
     return [record, ...children];
 }
-export function buildRecipeContextRecords(file) {
-    return collectRecipeContextRecords(file, [], []);
+export function buildRecipeContextRecords(file, context = EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT) {
+    return collectRecipeContextRecords(file, [], [], context);
 }
 export function getRecipeTemplate(value) {
     return readRecipeConfig(value)?.template;

package/dist/lib/runtime.d.ts

@@ -16,7 +16,6 @@ export interface RuntimeContext {
 export interface ToolRegistryRuntimeDeps {
     configPath: string;
     exec: RegisteredToolExec;
-    packagedRecipeRoot?: string;
     recipeRoot?: string;
     getActiveTools?: () => string[];
     registerTool: (definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>) => void;

package/dist/lib/runtime.js

@@ -69,7 +69,7 @@ export function createAutoToolsRuntime(deps) {
         const other = warnings.filter((warning) => !shadowed.includes(warning) && !skipped.includes(warning));
         const lines = ["pi-actors recipe registry warning"];
         if (shadowed.length > 0) {
-            lines.push("User recipes override packaged recipes:");
+            lines.push("User recipes shadow lower-priority user sources:");
             lines.push(...shadowed.map((warning) => `• ${warning}`));
         }
         if (skipped.length > 0) {
@@ -85,10 +85,8 @@ export function createAutoToolsRuntime(deps) {
     function loadTools(ctx) {
         const warnings = [];
         const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
-        const packagedRecipeRoot = deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot();
         const discovered = RecipesDiscovery.discoverRecipeSources([
             { root: recipeRoot, defaultTool: true, mutableUsage: true },
-            { root: packagedRecipeRoot },
         ]);
         warnings.push(...discovered.diagnostics);
         tools.clear();

package/dist/lib/tools-inspect.d.ts

@@ -7,7 +7,6 @@ export interface InspectToolDeps<TContext = unknown> {
     getRunStatus?: (runOrDir: string) => Record<string, any>;
     getTool?: (name: string) => any | undefined;
     listRuns?: () => Array<Record<string, any>>;
-    packagedRecipeRoot?: string;
     recipeRoot?: string;
 }
 export declare function createInspectToolDefinition<TContext = unknown>(deps?: InspectToolDeps<TContext>): any;