@llblab/pi-actors 0.45.1 → 0.46.0

package/AGENTS.md

@@ -36,11 +36,11 @@ Pi host
      -> lib/observability.ts          terminal + Trace-attention observation
      -> lib/inspector*.ts             owner-filtered actor-instance inspection
      -> scripts/*.mjs                 process/service entrypoints
-     -> recipes/*.json                packaged Recipe library
+     -> skills/*/recipes/*            Skill-owned Recipe components
      -> skills/* + docs/*             agent and human guidance
 ```
 
-`index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic.
+`index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic. For architecture-affecting work, load and follow `.agents/skills/domain-dag/SKILL.md`; its validator is local agent tooling, not an npm, CI, or release gate.
 
 ## Key Domains
 
@@ -58,17 +58,20 @@ Pi host
 - `observability.ts`, `run-ui-runtime.ts`: Trace attention, terminal reconciliation, and Pi follow-up delivery.
 - automatic draft/tool review domains: structurally redacted model review, journaled mutation, lineage, recovery, and explicit retry/reset safety.
 
-Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed packaged Recipes self-locate their installed package root while explicit caller values remain authoritative. Recipes stay optional, composable, policy-light, and caller-configurable.
+The bundled Skill Recipe dependency DAG is `artifacts → actors, swarm`, `media → artifacts`, and `project-work → actors, artifacts, swarm`; `actors`, `swarm`, and `recipe-memory` have no cross-Skill Recipe dependencies.
+
+Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`. Recipes stay optional, composable, policy-light, and caller-configurable.
 
 ## Operating Principles
 
 ### Recipe
 
+- Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching the Skill directory, not a second pi-actors identity field.
 - Recipe files may define args/defaults, imports, artifacts, command-template flags, and `control`.
 - Declare actor-local actions only when a long-lived process implements them.
 - Actions are lowercase, unique, and cannot use runtime-reserved lifecycle names.
 - Removed communication-plane metadata fails explicitly; never translate it.
-- User Recipes shadow packaged definitions; invalid shadowing blocks fallback.
+- User Recipes are discovered only from the persistent user registry; Skill Recipes are exact components outside tool discovery. Explicit entry paths resolve from invocation `cwd`; relative imports resolve from their importing file.
 - Files over 1 MiB, import depth over 32, and import cycles fail closed.
 
 ### Trace
@@ -136,11 +139,10 @@ When a deferred Run result gates the next step, wait for its terminal follow-up.
 ## Documentation and Release Discipline
 
 - Keep published text portable: use `~`, `<repo>`, or relative paths.
-- Keep executable JavaScript and TypeScript blocks compact: no blank lines inside function bodies or control-flow blocks. Structural object, type, interface, class, and module bodies are exempt.
 - Update `skills/actors/SKILL.md` when durable operating mechanics change.
 - Keep `skills/swarm/SKILL.md` focused on multi-agent methodology rather than kernel internals.
-- Recipe `description` is optional because discovery supplies stable fallback tool copy; packaged Recipe QA must report zero diagnostics and zero release-blocking warnings without component boilerplate.
-- Before release run build, full tests, preservation tests, Recipe QA, Domain DAG validation, ABCd context validation, line-count gates, and release gates.
+- Recipe `description` is optional. Skill Recipe QA recursively validates direct filesystem-owned components and capability semantics with zero diagnostics or warnings; it does not enforce aesthetics or architecture policy.
+- Before release run the normal product validation and dependency audit. Use the project-local Domain DAG Skill during architecture-affecting development, not as publication automation.
 - `.github/workflows/release.yml` owns the immutable sequence reusable validation → npm Trusted Publisher publication/verification → GitHub Release convergence; follow [docs/releasing.md](docs/releasing.md).
 - Keep npm publication tokenless: use the exact npm Trusted Publisher binding and job-scoped OIDC permission, never a long-lived npm token or token fallback.
 - Until a stable version beyond `1.x`, prefer clean breaking simplification over compatibility aliases or renamed legacy abstractions.

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-> Each release keeps at most 8 outcome records of at most 512 characters.
+## 0.46.0: Skill-Owned Capability Packs
+
+- `Breaking Recipe Grammar`: File-backed identity now comes only from the filename; top-level Recipe `name`, nested Skill identities, JSON/Markdown stem collisions, bare references, and the old `std:` / `skill:` prefixes fail with migration guidance. Composition accepts exact `<active-skill>/<stem>` references or explicit `.json` / `.md` paths, with entry paths based at invocation cwd and relative imports based at their owning Recipe.
+- `Skill-Owned Distribution`: All 58 bundled components move from the root Recipe library into six flat Pi Skills—Actors, Artifacts, Media, Project Work, Recipe Memory, and Swarm—with 67 explicit imports and an acyclic cross-Skill graph. Root and `dist` Recipe libraries, package-root discovery, fallback/shadowing, wrapper installation, and obsolete root capability helpers are removed; Skill components never auto-register as tools.
+- `Scoped Resolution and Provenance`: Immutable active-Skill contexts are session-scoped and captured per Run. Recipe inspection distinguishes user registry capabilities, active Skill components, and explicit files while recording entry/import roles, filename stems, logical identities, Skill ownership, and alias ancestry without exposing private `source_file`, `{skill_dir}`, or `{recipe_dir}` values to model/Inspector surfaces.
+- `Capability Safety`: Automatic review resolves exact package-owned `recipe-memory/*` components so user files cannot redirect reviewers. Helpers self-locate through runtime-owned `{skill_dir}`; Control, Trace, lifecycle fencing, review transactions, and the public `spawn`, `message`, `inspect`, `register_tool` plus Recipe/Trace/Control view contracts remain unchanged.
+- `Validation and Architecture`: Recursive Skill QA validates direct identity, parse/import semantics, origins, Control, portable paths, and helper targets in source and installed packages. The custom release-gate and executable-style policy scanners are removed; CI runs product validation plus dependency audit, while a non-packaged project-local Domain DAG Skill supports architecture work without becoming a release gate.
+- `Dogfood and Migration`: Source and installed tests execute repository health, release readiness, quorum review, artifact bundle, media player, and package-owned draft review through qualified Skill references, plus relative/absolute file imports and all breaking failures. Migrate `std:foo` to `owning-skill/foo`, `skill:foo/bar` to `foo/bar`, root Recipes to their owning Skill filename, and delete Recipe `name` fields.
 
 ## 0.45.1: Entrypoint and Release Policy
 

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
 ```
 
@@ -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

@@ -98,7 +98,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) &&

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/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

@@ -16,7 +16,10 @@ import * as Tools from "./tools.js";
 import * as ToolsResponse from "./tools-response.js";
 export function createActorExtensionRuntime(pi) {
     let activeRunContext;
+    const skillContextsBySession = new Map();
     const getRunOwnerId = Pi.getSessionId;
+    const getSkillContext = (ctx) => skillContextsBySession.get(getRunOwnerId(ctx)) ??
+        RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
     const automaticReview = AutomaticReviewRuntime.createAutomaticReviewRuntime({
         getActiveContext: () => activeRunContext,
         getRunOwnerId,
@@ -41,6 +44,7 @@ export function createActorExtensionRuntime(pi) {
                 if (ctx && typeof ctx === "object") {
                     nextArgs[4] = {
                         ...ctx,
+                        activeSkillRecipeContext: getSkillContext(ctx),
                         getThinkingLevel: () => pi.getThinkingLevel(),
                     };
                 }
@@ -67,8 +71,8 @@ export function createActorExtensionRuntime(pi) {
     });
     const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
     return {
-        beforeAgentStart(systemPrompt, skills) {
-            RecipesReferences.setActiveSkillRecipeSources(skills);
+        beforeAgentStart(systemPrompt, skills, ctx) {
+            skillContextsBySession.set(getRunOwnerId(ctx), RecipesReferences.createActiveSkillRecipeContext(skills));
             return {
                 systemPrompt: `${systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
             };
@@ -83,12 +87,14 @@ export function createActorExtensionRuntime(pi) {
                 automaticReview.schedule();
         },
         onSessionShutdown(reason, ctx) {
+            skillContextsBySession.delete(getRunOwnerId(ctx));
             activeRunContext = undefined;
             automaticReview.close();
             recipeReload.close();
             runUiRuntime.shutdown(reason, ctx);
         },
         async onSessionStart(ctx) {
+            skillContextsBySession.set(getRunOwnerId(ctx), RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT);
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             activeRunContext = ctx;
             runUiRuntime.close();

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) {