@llblab/pi-actors 0.45.1 → 0.46.1

package/README.md

@@ -2,7 +2,7 @@
 
 ![pi-actors banner](https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg)
 
-Local Run kernel and persistent tool registry for [Pi](https://github.com/badlogic/pi-mono).
+Local Run kernel and persistent tool registry for [Pi](https://github.com/earendil-works/pi).
 
 ```text
 Recipe --spawn--> Run
@@ -23,17 +23,18 @@ For local development:
 pi install /path/to/pi-actors
 ```
 
-The package contributes the extension, packaged Recipes, and the `actors` and `swarm` skills.
+The package contributes the extension and six capability-owning Skills for actors, artifacts, media, project work, Recipe memory, and swarm orchestration.
 
 ## Public Tools
 
 ### `spawn`
 
-Create a Run from a packaged/local Recipe or an inline command template:
+Create a Run from an active-Skill Recipe, an explicit Recipe file, or an inline command template:
 
 ```text
 spawn template="sleep 30" as=run:demo
-spawn recipe=pipeline-repo-health values={"repo":"/work/project","model":"provider/model"}
+spawn recipe=project-work/repo-health values={"repo":"/work/project","model":"provider/model"}
+spawn recipe=media/player values={"source":"/music"} as=run:player
 spawn template="make test" as=run:test
 ```
 
@@ -80,7 +81,7 @@ A Run exposes exactly `recipe`, `trace`, and `control` views.
 
 ### `register_tool`
 
-Persist a trusted command template or Recipe-backed capability under `~/.pi/agent/recipes`. Registration remains separate from running Control.
+Persist a trusted command template or Recipe-backed capability under `~/.pi/agent/recipes`. Registration remains separate from running Control. Treat it as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
 
 ## Recipe
 
@@ -99,13 +100,25 @@ Example controlled Recipe:
   "async": true,
   "control": ["pause", "resume", "stop"],
   "artifacts": { "state": "{state_dir}/player-state.json" },
-  "template": "{repo}/scripts/player.mjs --state-dir {state_dir}"
+  "template": "{skill_dir}/scripts/player.mjs --state-dir {state_dir}"
 }
 ```
 
 Ordinary one-shot Recipes should omit `control`. Recipe imports compose definitions inside one Run; they do not create peer actors.
 
-File-backed Recipes receive immutable `{recipe_dir}`; Recipes under a Pi-active Skill also receive `{skill_dir}`. Use `std:<recipe>` for an exact packaged component and `skill:<skill>/<recipe-path>` for an exact active-Skill component. Skill Recipes are namespaced reusable components and do not become tools automatically.
+```json
+{
+  "imports": {
+    "report": "artifacts/report",
+    "review": "swarm/quorum-review"
+  },
+  "template": [{ "name": "report" }, { "name": "review" }]
+}
+```
+
+Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; the filename is identity. `SKILL.md` `name` remains Pi host metadata and matches the Skill directory—pi-actors adds no second Skill identity field.
+
+References have two classes: exact active-Skill identities such as `project-work/repo-health`, and explicit `.json` / `.md` paths. Entry file paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe's directory; absolute paths remain exact. File-backed Recipes receive immutable `{recipe_dir}` and Skill Recipes also receive `{skill_dir}`. Skill components never become tools automatically.
 
 String command-template leaves execute directly without shell interpretation. Use template arrays for sequencing or an explicit trusted shell/script when shell semantics matter.
 
@@ -175,15 +188,16 @@ Open the owner-filtered TUI:
 
 It presents actor instances through Recipe, Trace, and Control tabs, with source filtering, detail navigation, refresh, and generation-fenced Run kill.
 
-## Packaged Recipes
+## Skill Recipes
 
 Useful entry points include:
 
-- `pipeline-repo-health`
-- `pipeline-quorum-review`
-- `pipeline-artifact-bundle`
-- `music-player` — controlled playback service
-- `resource-locker` — optional controlled resource-lock service
+- `project-work/repo-health`
+- `project-work/release-readiness`
+- `swarm/quorum-review`
+- `artifacts/bundle`
+- `media/player` — controlled playback service
+- `actors/resource-locker` — optional controlled resource-lock service
 
 Validate Recipes with:
 

package/dist/fixtures/protocol/recipe-summary.json

@@ -1,6 +1,6 @@
 {
   "id": "music-player",
-  "path": "recipes/music-player.json",
+  "path": "skills/media/recipes/player.json",
   "location": "packaged",
   "active": true,
   "args": ["repo", "command", "source", "loop", "volume", "player", "state_dir"],

package/dist/index.js

@@ -11,7 +11,7 @@ export default function toolRegistryExtension(pi) {
     pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
     pi.on("agent_end", async (_event, ctx) => runtime.onAgentEnd(ctx));
     pi.on("session_shutdown", async (event, ctx) => runtime.onSessionShutdown(event.reason, ctx));
-    pi.on("before_agent_start", async (event) => runtime.beforeAgentStart(event.systemPrompt, event.systemPromptOptions.skills ?? []));
+    pi.on("before_agent_start", async (event, ctx) => runtime.beforeAgentStart(event.systemPrompt, event.systemPromptOptions.skills ?? [], ctx));
     InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);
     runtime.registerCoreTools();
 }

package/dist/lib/async-runs.d.ts

@@ -68,6 +68,7 @@ export interface AsyncRunMeta {
     argv: string[];
     createdAt: string;
     cwd: string;
+    launch_kind?: AsyncRunLaunchSource;
     launch_source?: AsyncRunLaunchSource;
     launch_correlation?: {
         correlation_id?: string;
@@ -98,7 +99,10 @@ export interface AsyncRunMeta {
 export { safeRunId } from "./runs-identity.ts";
 export { resolveArtifactManifest } from "./runs-artifacts.ts";
 export type { RunArtifactDeclaration, RunArtifactManifestEntry, } from "./runs-artifacts.ts";
-export declare function startRun(params: AsyncRunStartParams, cwd: string): AsyncRunMeta;
+export interface AsyncRunStartOptions {
+    skillContext?: RecipesReferences.ActiveSkillRecipeContext;
+}
+export declare function startRun(params: AsyncRunStartParams, cwd: string, options?: AsyncRunStartOptions): AsyncRunMeta;
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
 export type { RunStateIndexEntry } from "./runs-index.ts";
 export declare function listRunStateDirs(stateRoot?: string): string[];

package/dist/lib/async-runs.js

@@ -105,10 +105,11 @@ function resolveStateDir(params, run) {
 function assertNoActiveRunState(stateDir) {
     RunsStart.assertNoActiveRunState(stateDir, readJson, RUNNER_PATH);
 }
-function resolveRecipeFile(file) {
-    return (RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
-        RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
-        RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot()));
+function resolveRecipeFile(file, cwd, options) {
+    const path = RecipesReferences.resolveRecipeReferencePath(file, cwd, options.skillContext);
+    if (path)
+        return path;
+    throw new Error(`Recipe reference not found. Use <skill>/<recipe> or an explicit .json/.md file path: ${file}`);
 }
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
@@ -116,12 +117,13 @@ function isMutableUsageRecipeFile(file) {
     const relation = relative(userRoot, resolved);
     return relation !== "" && !relation.startsWith("..") && !isAbsolute(relation);
 }
-function readRecipeFile(file) {
-    const path = resolveRecipeFile(file);
+function readRecipeFile(file, cwd, options) {
+    const path = resolveRecipeFile(file, cwd, options);
     const raw = RecipesReferences.readRawRecipeConfig(path);
     const includeActorRecipeContext = raw?.actor_context !== false && raw?.actor_context !== "off";
     const config = RecipesReferences.readResolvedRecipeConfig(path, [], {
         includeActorRecipeContext,
+        skillContext: options.skillContext,
     });
     if (!config) {
         throw new Error(`Template recipe must define template: ${path}`);
@@ -141,10 +143,10 @@ function getRunIdFromFile(file) {
     const name = basename(file, extname(file));
     return name || undefined;
 }
-function resolveStartParams(params) {
+function resolveStartParams(params, cwd, options) {
     if (!params.file)
         return params;
-    const fileParams = readRecipeFile(params.file);
+    const fileParams = readRecipeFile(params.file, cwd, options);
     return {
         ...fileParams,
         ...params,
@@ -239,23 +241,13 @@ function acquireStateStartLock(stateDir, options = {}) {
 function prepareStateDirForStart(stateDir) {
     RunsStart.prepareStateDirForStart(stateDir, readJson, RUNNER_PATH);
 }
-export function startRun(params, cwd) {
-    const startParams = resolveStartParams(params);
+export function startRun(params, cwd, options = {}) {
+    const startParams = resolveStartParams(params, cwd, options);
     const resolved = resolveRunTemplate(startParams);
     const run = safeRunId(startParams.run_id);
     const stateDir = resolveStateDir(startParams, run);
     const recipeFile = startParams.file
-        ? resolveRecipeFile(startParams.file)
-        : undefined;
-    const packagedRecipeRoot = resolve(Paths.getPackagedRecipeRoot());
-    const recipeRelation = recipeFile
-        ? relative(packagedRecipeRoot, recipeFile)
-        : undefined;
-    const packagedRepo = startParams.defaults?.repo === "~/.pi/agent/extensions/pi-actors" &&
-        recipeRelation &&
-        !recipeRelation.startsWith("..") &&
-        !isAbsolute(recipeRelation)
-        ? dirname(packagedRecipeRoot)
+        ? resolveRecipeFile(startParams.file, cwd, options)
         : undefined;
     const argSpec = Schema.parseToolArgDeclarationList(startParams.args ?? []);
     if (argSpec.error)
@@ -268,7 +260,6 @@ export function startRun(params, cwd) {
     const values = Schema.normalizeRuntimeValues({
         ...argSpec.defaults,
         ...(startParams.defaults || {}),
-        ...(packagedRepo ? { repo: packagedRepo } : {}),
         ...(startParams.values || {}),
         run_id: run,
         state_dir: stateDir,
@@ -306,7 +297,15 @@ export function startRun(params, cwd) {
         const includeActorRecipeContext = startParams.actor_context !== false &&
             startParams.actor_context !== "off";
         const recipeContextRecords = recipeFile && includeActorRecipeContext
-            ? RecipesReferences.buildRecipeContextRecords(recipeFile)
+            ? RecipesReferences.buildRecipeContextRecords(recipeFile, options.skillContext).map((record, index) => index === 0 &&
+                startParams.launch_source === "tool" &&
+                record.source_kind === "explicit_file_recipe"
+                ? {
+                    ...record,
+                    logical_reference: record.name,
+                    source_kind: "user_registry_capability",
+                }
+                : record)
             : undefined;
         if (recipeFile &&
             isMutableUsageRecipeFile(recipeFile) &&
@@ -327,7 +326,10 @@ export function startRun(params, cwd) {
             createdAt: new Date().toISOString(),
             cwd,
             ...(startParams.launch_source
-                ? { launch_source: startParams.launch_source }
+                ? {
+                    launch_kind: startParams.launch_source,
+                    launch_source: startParams.launch_source,
+                }
                 : {}),
             ...(startParams.launch_correlation
                 ? { launch_correlation: startParams.launch_correlation } : {}),

package/dist/lib/automatic-review-runtime.d.ts

@@ -4,6 +4,7 @@
  * Owns automatic-review lifecycle wiring without owning review decisions or filesystem transactions.
  */
 import type * as Pi from "./pi.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 export interface AutomaticReviewRuntime {
     close(): void;
     handleControl(action: string, input: unknown): Record<string, unknown>;
@@ -15,4 +16,5 @@ export interface AutomaticReviewRuntimeDeps {
     getRunOwnerId(ctx: Pi.ExtensionContext): string;
     getThinkingLevel(): unknown;
 }
+export declare const PACKAGE_RECIPE_MEMORY_CONTEXT: RecipesReferences.ActiveSkillRecipeContext;
 export declare function createAutomaticReviewRuntime(deps: AutomaticReviewRuntimeDeps): AutomaticReviewRuntime;

package/dist/lib/automatic-review-runtime.js

@@ -3,13 +3,20 @@
  * Zones: session-bound review schedulers, silent reviewer launch adapters, review controls
  * Owns automatic-review lifecycle wiring without owning review decisions or filesystem transactions.
  */
-import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import * as AsyncRuns from "./async-runs.js";
 import * as DraftSleep from "./draft-sleep.js";
 import * as ModelContext from "./model-context.js";
 import * as Paths from "./paths.js";
+import * as RecipesReferences from "./recipes-references.js";
 import * as ReviewControl from "./review-control.js";
 import * as ToolReviewScheduler from "./tool-review-scheduler.js";
+export const PACKAGE_RECIPE_MEMORY_CONTEXT = RecipesReferences.createActiveSkillRecipeContext([
+    {
+        name: "recipe-memory",
+        filePath: fileURLToPath(new URL("../skills/recipe-memory/SKILL.md", import.meta.url)),
+    },
+]);
 export function createAutomaticReviewRuntime(deps) {
     let draftScheduler;
     let toolScheduler;
@@ -56,14 +63,14 @@ export function createAutomaticReviewRuntime(deps) {
                         throw new Error("Draft review session changed before launch.");
                     }
                     return AsyncRuns.startRun({
-                        file: join(Paths.getPackagedRecipeRoot(), "draft-review.json"),
+                        file: "recipe-memory/draft-review",
                         launch_source: "tool",
                         notification_policy: "silent",
                         ownerId: deps.getRunOwnerId(ctx),
                         policy_values: policyValues(ctx),
                         run_id: DraftSleep.draftSleepRunId(batch.batchId),
                         values: { input_path: batch.reviewerInputPath },
-                    }, ctx.cwd);
+                    }, ctx.cwd, { skillContext: PACKAGE_RECIPE_MEMORY_CONTEXT });
                 },
                 process: (state) => DraftSleep.processDraftSleepReview(state, {
                     getRunStatus: AsyncRuns.getRunStatus,
@@ -77,14 +84,14 @@ export function createAutomaticReviewRuntime(deps) {
                         throw new Error("Tool review session changed before launch.");
                     }
                     return AsyncRuns.startRun({
-                        file: join(Paths.getPackagedRecipeRoot(), "tool-review.json"),
+                        file: "recipe-memory/tool-review",
                         launch_source: "tool",
                         notification_policy: "silent",
                         ownerId: deps.getRunOwnerId(ctx),
                         policy_values: policyValues(ctx),
                         run_id: ToolReviewScheduler.toolReviewRunId(batch.reviewId),
                         values: { input_path: batch.reviewerInputPath },
-                    }, ctx.cwd);
+                    }, ctx.cwd, { skillContext: PACKAGE_RECIPE_MEMORY_CONTEXT });
                 },
                 process: (state) => ToolReviewScheduler.processToolReviewResult(state, {
                     getRunStatus: AsyncRuns.getRunStatus,

package/dist/lib/draft-sleep.js

@@ -31,7 +31,6 @@ function readState(path) {
 function defaultActiveTools(recipeRoot) {
     const discovered = RecipesDiscovery.discoverRecipeSources([
         { root: recipeRoot, defaultTool: true, mutableUsage: true },
-        { root: Paths.getPackagedRecipeRoot() },
     ]);
     return [...discovered.active.values()]
         .filter((entry) => existsSync(entry.path))

package/dist/lib/execution.d.ts

@@ -72,6 +72,7 @@ export interface RegisteredToolExecutionResult {
         command: string;
         fullOutputPath?: string;
         killed: boolean;
+        launch_kind: "tool";
         stderrBytes?: number;
         stderrCapturedBytes?: number;
         stderrFile?: string;

package/dist/lib/execution.js

@@ -709,6 +709,7 @@ export async function executeRegisteredTool(cfg, params, exec, cwd, signal) {
             command,
             fullOutputPath: result.stdoutFile ?? formatted.fullOutputPath,
             killed: result.killed,
+            launch_kind: "tool",
             ...getCaptureDetails(result),
             ...(executed.branches.length > 0 ? { branches: executed.branches } : {}),
             ...(executed.failures.length > 0

package/dist/lib/extension-runtime.d.ts

@@ -6,7 +6,7 @@
 import * as Pi from "./pi.ts";
 import * as RecipesReferences from "./recipes-references.ts";
 export interface ActorExtensionRuntime {
-    beforeAgentStart(systemPrompt: string, skills: RecipesReferences.ActiveSkillRecipeSource[]): {
+    beforeAgentStart(systemPrompt: string, skills: RecipesReferences.ActiveSkillRecipeSource[], ctx: Pi.ExtensionContext): {
         systemPrompt: string;
     };
     discoverResources(metaUrl: string): {

package/dist/lib/extension-runtime.js

@@ -8,6 +8,7 @@ import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 import * as Pi from "./pi.js";
 import * as Prompts from "./prompts.js";
+import * as RecipeResolution from "./recipes-context.js";
 import * as RecipesReferences from "./recipes-references.js";
 import * as RunUiRuntime from "./run-ui-runtime.js";
 import * as Runtime from "./runtime.js";
@@ -16,7 +17,16 @@ import * as Tools from "./tools.js";
 import * as ToolsResponse from "./tools-response.js";
 export function createActorExtensionRuntime(pi) {
     let activeRunContext;
+    const recipeResolutionContextsBySession = new Map();
     const getRunOwnerId = Pi.getSessionId;
+    const getRecipeResolutionContext = (ctx) => {
+        const sessionId = getRunOwnerId(ctx);
+        const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
+        if (!resolutionContext) {
+            throw new Error(`Recipe resolution context is unavailable for session ${sessionId}.`);
+        }
+        return resolutionContext;
+    };
     const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
         getActiveContext: () => activeRunContext,
         getRunOwnerId,
@@ -41,6 +51,7 @@ export function createActorExtensionRuntime(pi) {
                 if (ctx && typeof ctx === "object") {
                     nextArgs[4] = {
                         ...ctx,
+                        recipeResolutionContext: getRecipeResolutionContext(ctx),
                         getThinkingLevel: () => pi.getThinkingLevel(),
                     };
                 }
@@ -57,6 +68,7 @@ export function createActorExtensionRuntime(pi) {
         configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         exec: CommandTemplates.execCommandTemplate,
         getActiveTools: () => pi.getActiveTools(),
+        getAllTools: () => pi.getAllTools(),
         registerTool: (definition) => {
             const wrapped = withCurrentThinkingContext(definition);
             actorToolDefinitions.set(wrapped.name, wrapped);
@@ -65,10 +77,17 @@ export function createActorExtensionRuntime(pi) {
         reservedToolNames: Tools.RESERVED_TOOL_NAMES,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     });
-    const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
+    const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime, {
+        getResolutionContext: () => activeRunContext
+            ? getRecipeResolutionContext(activeRunContext)
+            : undefined,
+    });
     return {
-        beforeAgentStart(systemPrompt, skills) {
-            RecipesReferences.setActiveSkillRecipeSources(skills);
+        beforeAgentStart(systemPrompt, skills, ctx) {
+            const sessionId = getRunOwnerId(ctx);
+            const resolutionContext = RecipeResolution.createRecipeResolutionContext(sessionId, ctx.cwd, RecipesReferences.createActiveSkillRecipeContext(skills));
+            recipeResolutionContextsBySession.set(sessionId, resolutionContext);
+            runtime.loadTools(ctx, resolutionContext);
             return {
                 systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
             };
@@ -83,12 +102,15 @@ export function createActorExtensionRuntime(pi) {
                 automaticReview.schedule();
         },
         onSessionShutdown(reason, ctx) {
+            recipeResolutionContextsBySession.delete(getRunOwnerId(ctx));
             activeRunContext = undefined;
             automaticReview.close();
             recipeReload.close();
             runUiRuntime.shutdown(reason, ctx);
         },
         async onSessionStart(ctx) {
+            const sessionId = getRunOwnerId(ctx);
+            recipeResolutionContextsBySession.set(sessionId, RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd));
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             activeRunContext = ctx;
             runUiRuntime.close();
@@ -98,7 +120,6 @@ export function createActorExtensionRuntime(pi) {
             if (activeRunContext !== ctx)
                 return;
             automaticReview.start(ctx);
-            runtime.loadTools(ctx);
             runUiRuntime.start(ctx);
             recipeReload.watch(ctx);
         },
@@ -107,6 +128,7 @@ export function createActorExtensionRuntime(pi) {
                 configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
                 getActiveTools: () => pi.getActiveTools(),
                 getRuntimeTool: (name) => Tools.resolveActiveRuntimeTool(name, runtime.getTools(), (activeName) => actorToolDefinitions.get(activeName)),
+                getRuntimeToolStatus: runtime.getToolStatus,
                 handleRuntimeControl: automaticReview.handleControl,
                 registryRuntime: runtime,
                 setActiveTools: (toolNames) => pi.setActiveTools(toolNames),

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,28 @@ 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_kind: meta.launch_kind ?? meta.launch_source,
             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: valid admitted recipes are reconciled as tools across sessions; register_tool writes there and reports current activation truth.\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

@@ -9,7 +9,7 @@ export const REGISTER_TOOL_DESCRIPTION = "Register a persistent custom tool from
 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.",
+    "After register_tool succeeds, trust its callable_now and activation result; persisted definitions remain available for admission 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.",
 ];
@@ -18,14 +18,14 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.
 - Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node→bun→deno 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.
 - 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.
+- ~/.pi/agent/recipes/*.json is actor muscle memory: valid admitted recipes are reconciled as tools across sessions; register_tool writes there and reports current activation truth.
 - Recipes own template directly and may declare metadata/defaults/imports/control/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.
 - 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.d.ts

@@ -1,10 +1,19 @@
 /**
- * Recipe context prompt assembly.
- * Zones: async runner prompt context, recipe provenance, LLM child launches
- * Owns compact actor recipe context records appended to child-agent prompts.
+ * Recipe context contracts and prompt assembly.
+ * Zones: live session resolution, async runner prompt context, recipe provenance, LLM child launches
+ * Owns the immutable live Recipe environment and compact actor context appended to child-agent prompts.
  */
 import type { CommandTemplateActorRecipeContext } from "./command-templates.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import type { TemplateRecipeContextRecord } from "./recipes-references.ts";
+export interface RecipeResolutionContext {
+    readonly activeSkills: RecipesReferences.ActiveSkillRecipeContext;
+    readonly cwd: string;
+    readonly generation: string;
+    readonly sessionId: string;
+}
+export declare function createRecipeResolutionContext(sessionId: string, cwd: string, activeSkills: RecipesReferences.ActiveSkillRecipeContext): RecipeResolutionContext;
+export declare function createEmptyRecipeResolutionContext(sessionId: string, cwd: string): RecipeResolutionContext;
 export interface MarkedRecipeContextRecord extends TemplateRecipeContextRecord {
     you_are_here?: true;
     you_are_here_path?: string;