@llblab/pi-actors 0.45.0 → 0.46.0

package/lib/runtime.ts

@@ -23,7 +23,6 @@ export interface RuntimeContext {
 export interface ToolRegistryRuntimeDeps {
   configPath: string;
   exec: RegisteredToolExec;
-  packagedRecipeRoot?: string;
   recipeRoot?: string;
   getActiveTools?: () => string[];
   registerTool: (
@@ -125,7 +124,7 @@ export function createAutoToolsRuntime(
     );
     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) {
@@ -141,11 +140,8 @@ export function createAutoToolsRuntime(
   function loadTools(ctx: RuntimeContext) {
     const warnings: string[] = [];
     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/lib/tools-inspect.ts

@@ -33,7 +33,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;
 }
 
@@ -195,6 +194,7 @@ function inspectRuntime(
 function inspectRecipes(
   view: string,
   deps: InspectToolDeps,
+  context: unknown,
 ): Record<string, unknown> {
   if (
     view !== "status" &&
@@ -213,18 +213,51 @@ function inspectRecipes(
   }
   const discovered = RecipesDiscovery.discoverRecipeSources([
     { root: recipeRoot, defaultTool: true, mutableUsage: true },
-    { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
   ]);
-  const skillRecipeNamespaces =
-    RecipesReferences.getActiveSkillRecipeNamespaces();
+  const skillContext =
+    context && typeof context === "object" && "activeSkillRecipeContext" in context
+      ? (context as {
+          activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
+        }).activeSkillRecipeContext
+      : undefined;
+  const activeSkillContext =
+    skillContext ?? RecipesReferences.EMPTY_ACTIVE_SKILL_RECIPE_CONTEXT;
+  const skillRecipeNamespaces = RecipesReferences.getActiveSkillRecipeNamespaces(
+    activeSkillContext,
+  );
+  let skillRecipeComponents: Array<Record<string, unknown>> = [];
+  const skillRecipeComponentDiagnostics: Array<Record<string, unknown>> = [];
+  try {
+    skillRecipeComponents = RecipesReferences.listActiveSkillRecipeComponents(
+      activeSkillContext,
+    ).map((component) => ({
+      identity: component.identity,
+      source_kind: "active_skill_component",
+      skill: component.skill,
+      stem: component.stem,
+      imports: component.imports,
+    }));
+  } catch (error) {
+    skillRecipeComponentDiagnostics.push({
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+  const discoverySummary = RecipesDiscovery.summarizeDiscovery(discovered);
   const summary = {
-    ...RecipesDiscovery.summarizeDiscovery(discovered),
-    skill_recipe_namespaces: skillRecipeNamespaces,
+    ...discoverySummary,
+    active: Array.isArray(discoverySummary.active)
+      ? discoverySummary.active.map((entry) => ({
+          ...(entry as Record<string, unknown>),
+          source_kind: "user_registry_capability",
+        }))
+      : discoverySummary.active,
+    skill_recipe_components: skillRecipeComponents,
+    skill_recipe_component_diagnostics: skillRecipeComponentDiagnostics,
+    active_skill_recipe_identities: Object.keys(skillRecipeNamespaces).sort(),
     skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
       .filter(([, roots]) => roots.length > 1)
-      .map(([name, roots]) => ({
+      .map(([name]) => ({
         name,
-        roots,
         error: `Ambiguous active Skill Recipe namespace ${name}`,
       })),
     drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
@@ -386,7 +419,7 @@ export function createInspectToolDefinition<TContext = unknown>(
       if (target === "runtime") {
         details = inspectRuntime(view, input, ctx, deps);
       } else if (target === "recipes") {
-        details = inspectRecipes(view, deps);
+        details = inspectRecipes(view, deps, ctx);
       } else {
         const run = parseRunTarget(target);
         if (run) details = inspectRun(run, view, input, ctx, deps);

package/lib/tools-local.ts

@@ -18,6 +18,7 @@ import * as ToolsResponse from "./tools-response.ts";
 type JsonSchema = Schema.JsonSchema;
 
 export interface RuntimeToolContext extends ModelContext.CurrentModelContext {
+  activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
   cwd: string;
   sessionManager?: { getSessionId?: () => string };
 }
@@ -243,6 +244,7 @@ export function createRuntimeToolDefinition(
               values: resolveRecipeToolValues(cfg, values, ctx),
             },
             ctx.cwd,
+            { skillContext: ctx.activeSkillRecipeContext },
           );
           return {
             content: [

package/lib/tools-spawn.ts

@@ -11,12 +11,13 @@ import * as AsyncRuns from "./async-runs.ts";
 import { withFileMutationLock } from "./file-state.ts";
 import * as ModelContext from "./model-context.ts";
 import * as Paths from "./paths.ts";
-import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import * as RecipesUsage from "./recipes-usage.ts";
 import * as Schema from "./schema.ts";
 import * as ToolsResponse from "./tools-response.ts";
 
 export interface SpawnToolContext extends ModelContext.CurrentModelContext {
+  activeSkillRecipeContext?: RecipesReferences.ActiveSkillRecipeContext;
   cwd: string;
   sessionManager?: { getSessionId?: () => string };
 }
@@ -28,22 +29,6 @@ function getRunOwnerId(ctx: SpawnToolContext): string | undefined {
   return ctx.sessionManager?.getSessionId?.();
 }
 
-function shadowedRecipeLaunchDiagnostic(
-  recipe: unknown,
-): Record<string, unknown> | undefined {
-  if (
-    typeof recipe !== "string" ||
-    recipe.includes("/") ||
-    recipe.includes("~")
-  )
-    return undefined;
-  const discovery = RecipesDiscovery.discoverRecipeSources([
-    { root: Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
-    { root: Paths.getPackagedRecipeRoot(), defaultTool: false },
-  ]);
-  return RecipesDiscovery.getShadowedLaunchDiagnostic(discovery, recipe);
-}
-
 function draftRecipeName(run: string): string {
   return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
 }
@@ -93,22 +78,6 @@ function writeSpawnDraftRecipe(
   return path;
 }
 
-function enhanceSpawnRecipeError(error: unknown, recipe: unknown): Error {
-  const diagnostic = shadowedRecipeLaunchDiagnostic(recipe);
-  if (!diagnostic)
-    return error instanceof Error ? error : new Error(String(error));
-  const original = error instanceof Error ? error.message : String(error);
-  return Object.assign(
-    new Error(
-      `${original} reason=${diagnostic.reason} active_path=${diagnostic.active_path} blocked_fallback=${diagnostic.blocked_fallback} hint=${diagnostic.hint}`,
-    ),
-    {
-      ...diagnostic,
-      original_error: original,
-    },
-  );
-}
-
 function runIdFromTarget(target: string | undefined): string | undefined {
   if (!target) return undefined;
   if (!target.startsWith("run:")) {
@@ -138,11 +107,9 @@ export function createSpawnToolDefinition<
           "Optional Run identity in exact run:<id> form.",
         ),
         file: Schema.stringSchema(
-          "Optional template Recipe reference. Supports paths, bare user/adjacent/std names, std:<name>, and skill:<skill>/<recipe>.",
-        ),
-        recipe: Schema.stringSchema(
-          "Alias for file; qualified Skill/std or ordinary Recipe reference to spawn.",
+          "Optional Recipe reference as <skill>/<recipe> or an explicit .json/.md file path.",
         ),
+        recipe: Schema.stringSchema("Alias for file."),
         template: Schema.unionSchema([
           Schema.stringSchema("Inline command template string"),
           Schema.arraySchema(
@@ -186,43 +153,39 @@ export function createSpawnToolDefinition<
           : typeof input.recipe === "string"
             ? input.recipe
             : undefined;
-      let meta: AsyncRuns.AsyncRunMeta;
-      try {
-        meta = AsyncRuns.startRun(
-          {
-            file: recipe,
-            launch_source: "spawn",
-            launch_correlation: { tool_call_id: toolCallId },
-            ownerId: getRunOwnerId(ctx),
-            ...(input.transport_context
-              ? { transport_context: asRecord(input.transport_context) } : {}),
-            run_id: runId,
-            ...(input.template !== undefined
-              ? {
-                  template:
-                    input.template as AsyncRuns.AsyncRunStartParams["template"],
-                }
-              : {}),
-            values: ModelContext.withCurrentModelValues(
-              asRecord(input.values),
-              ctx,
-            ),
-            ...(input.artifacts &&
-            typeof input.artifacts === "object" &&
-            !Array.isArray(input.artifacts)
-              ? {
-                  artifacts: input.artifacts as Record<
-                    string,
-                    AsyncRuns.RunArtifactDeclaration
-                  >,
-                }
-              : {}),
-          },
-          ctx.cwd,
-        );
-      } catch (error) {
-        throw enhanceSpawnRecipeError(error, recipe);
-      }
+      const meta = AsyncRuns.startRun(
+        {
+          file: recipe,
+          launch_source: "spawn",
+          launch_correlation: { tool_call_id: toolCallId },
+          ownerId: getRunOwnerId(ctx),
+          ...(input.transport_context
+            ? { transport_context: asRecord(input.transport_context) } : {}),
+          run_id: runId,
+          ...(input.template !== undefined
+            ? {
+                template:
+                  input.template as AsyncRuns.AsyncRunStartParams["template"],
+              }
+            : {}),
+          values: ModelContext.withCurrentModelValues(
+            asRecord(input.values),
+            ctx,
+          ),
+          ...(input.artifacts &&
+          typeof input.artifacts === "object" &&
+          !Array.isArray(input.artifacts)
+            ? {
+                artifacts: input.artifacts as Record<
+                  string,
+                  AsyncRuns.RunArtifactDeclaration
+                >,
+              }
+            : {}),
+        },
+        ctx.cwd,
+        { skillContext: ctx.activeSkillRecipeContext },
+      );
       const draftRecipe = writeSpawnDraftRecipe(input, meta);
       const nextActions = ToolsResponse.runNextActions(meta.run);
       const details = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -30,8 +30,7 @@
     "test": "node --experimental-strip-types --test --test-concurrency=1 tests/*.test.ts",
     "test:preservation": "node --experimental-strip-types --test --test-concurrency=1 tests/async-runs.test.ts tests/observability.test.ts tests/session-evidence.test.ts tests/inspector-security.test.ts tests/inspector-overlay.test.ts tests/review-control.test.ts",
     "pack:dry": "npm pack --dry-run",
-    "recipes:qa": "node scripts/validate-recipe.mjs recipes --all --qa --summary",
-    "release:validate": "npm run validate && node scripts/release-gates.mjs",
+    "recipes:qa": "node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary",
     "validate": "npx tsc --noEmit && npm run recipes:qa && npm run build && npm run check && npm test && npm run conformance && npm run pack:dry",
     "audit:dependencies": "npm audit --audit-level=high --omit=peer",
     "build": "node scripts/build-dist.mjs",
@@ -42,7 +41,6 @@
     "dist",
     "lib",
     "scripts",
-    "recipes",
     "skills",
     "README.md",
     "AGENTS.md",
@@ -65,7 +63,7 @@
     "sourceSkills": [
       "./skills"
     ],
-    "image": "https://github.com/llblab/pi-actors/raw/main/banner.jpg"
+    "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/scripts/async-runner.mjs

@@ -74,7 +74,6 @@ function summarizeCommandDetail(commandDetail) {
 
 export async function runAsyncRunner(stateDir = process.argv[2]) {
   if (!stateDir) throw new Error("missing state dir");
-
   const runPath = join(stateDir, "run.json");
   const progressPath = join(stateDir, "progress.json");
   const resultPath = join(stateDir, "result.json");
@@ -83,11 +82,9 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   const stderrPath = join(stateDir, "stderr.log");
   const executionPath = join(stateDir, "execution.json");
   const meta = JSON.parse(readFileSync(runPath, "utf8"));
-
   function event(kind, data = {}) {
     appendRunTraceEvent(stateDir, { kind, data });
   }
-
   function observation(kind, summary, data = {}, delivery = "log", level = "info") {
     appendRunTraceEvent(stateDir, {
       kind,
@@ -97,7 +94,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(level === "error" ? { level: "error" } : {}),
     });
   }
-
   function progress(phase, extra = {}) {
     writeJsonAtomic(progressPath, {
       ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
@@ -106,7 +102,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...extra,
     });
   }
-
   let activeSubagents = 0;
   let completedSubagents = 0;
   let promptCounter = 0;
@@ -115,7 +110,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   const evidenceRecords = [];
   const stageOccurrences = new Map();
   let reportEvidence;
-
   function writeExecutionManifest(status) {
     writeJsonAtomic(executionPath, {
       version: 1,
@@ -129,7 +123,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       updated_at: new Date().toISOString(),
     });
   }
-
   function commandSessionFiles(sessionDir) {
     if (!sessionDir) return [];
     try {
@@ -141,7 +134,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       return [];
     }
   }
-
   function commandEvidenceStartRecord({
     commandDetail,
     commandId,
@@ -181,7 +173,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
           : "not_required",
     };
   }
-
   function commandEvidenceRecord({
     captureDir,
     commandDetail,
@@ -273,7 +264,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
             : "rejected",
     };
   }
-
   function auditReviewReport(text) {
     const required = evidenceRecords
       .filter((record) =>
@@ -294,11 +284,9 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       complete_allowed: missing.length === 0,
     };
   }
-
   function getCommandDoneDelivery(result) {
     return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
   }
-
   function progressRunning() {
     progress("running", {
       activeSubagents,
@@ -306,14 +294,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       failures: subagentFailures,
     });
   }
-
   function promptFilePath() {
     promptCounter += 1;
     const dir = join(stateDir, "prompts");
     mkdirSync(dir, { recursive: true });
     return join(dir, `command-${String(promptCounter).padStart(3, "0")}.md`);
   }
-
   function readPromptText(promptFile) {
     if (!promptFile) return undefined;
     try {
@@ -322,7 +308,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       return undefined;
     }
   }
-
   async function observedExec(command, args, options) {
     captureCounter += 1;
     const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
@@ -485,7 +470,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     progressRunning();
     return result;
   }
-
   try {
     event("run.runner.start", { pid: process.pid });
     progressRunning();

package/scripts/build-dist.mjs

@@ -40,12 +40,21 @@ writeFileSync(
   "utf8",
 );
 
-for (const dir of ["scripts", "recipes", "fixtures", "skills"]) {
+for (const dir of ["scripts", "fixtures", "skills"]) {
   cpSync(dir, join("dist", dir), { recursive: true });
 }
 
-const builtScripts = readdirSync(join("dist", "scripts"))
-  .filter((name) => name.endsWith(".mjs"))
-  .map((name) => join("dist", "scripts", name));
+function listModuleScripts(root) {
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return listModuleScripts(path);
+    return entry.isFile() && entry.name.endsWith(".mjs") ? [path] : [];
+  });
+}
+
+const builtScripts = [
+  ...listModuleScripts(join("dist", "scripts")),
+  ...listModuleScripts(join("dist", "skills")),
+];
 
 run(process.execPath, ["--check", ...builtScripts]);

package/skills/actors/SKILL.md

@@ -29,7 +29,7 @@ A Recipe defines execution. It may declare named typed args, inline fallbacks, c
 
 Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Prefer maintained packaged Recipes over ad hoc wrappers. Use `std:<recipe>` for exact packaged lookup and `skill:<skill>/<recipe-path>` for a component bundled with a Pi-active Skill. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Prefer maintained Skill-owned Recipes over ad hoc wrappers. 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 its directory, not an additional pi-actors identity field. Use `<skill>/<recipe>` for an exact direct component or an explicit `.json` / `.md` path. Entry paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe directory. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
 ## Trace
 
@@ -90,11 +90,11 @@ If work may outlive the current turn, needs steering, produces artifacts, fans o
 
 ## Top Recipes
 
-- [Repository health](../../recipes/pipeline-repo-health.json)
-- [Quorum review](../../recipes/pipeline-quorum-review.json)
-- [Artifact bundle](../../recipes/pipeline-artifact-bundle.json)
-- [Music player service](../../recipes/music-player.json)
-- [Resource locker service](../../recipes/resource-locker.json)
+- [Repository health](../project-work/recipes/repo-health.json)
+- [Quorum review](../swarm/recipes/quorum-review.json)
+- [Artifact bundle](../artifacts/recipes/bundle.json)
+- [Music player service](../media/recipes/player.json)
+- [Resource locker service](./recipes/resource-locker.json)
 
 ## Deep References
 

package/skills/actors/recipes/recipe-validate.json

@@ -0,0 +1,11 @@
+{
+  "args": [
+    "target:path",
+    "all:bool"
+  ],
+  "defaults": {
+    "target": "recipes",
+    "all": "true"
+  },
+  "template": "{skill_dir}/scripts/validate-recipe.mjs {target} {all?--all:}"
+}

package/{dist/recipes/utility-coordinator-lock-snapshot.json → skills/actors/recipes/resource-locker-snapshot.json}

@@ -1,13 +1,11 @@
 {
   "args": [
-    "repo:path",
     "state_dir:path",
     "lines:int"
   ],
   "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
     "state_dir": "~/.pi/agent/tmp/pi-actors/runs/coordinator-locker",
     "lines": "20"
   },
-  "template": "{repo}/scripts/locker.mjs snapshot --state-dir {state_dir} --lines {lines}"
+  "template": "{skill_dir}/scripts/resource-locker.mjs snapshot --state-dir {state_dir} --lines {lines}"
 }

package/{recipes → skills/actors/recipes}/resource-locker.json

@@ -1,11 +1,9 @@
 {
   "async": true,
   "args": [
-    "repo:path",
     "lease_ms:int"
   ],
   "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
     "lease_ms": "600000"
   },
   "control": [
@@ -23,5 +21,5 @@
     "locks": "{state_dir}/locks.json",
     "journal": "{state_dir}/journal.jsonl"
   },
-  "template": "{repo}/scripts/locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
+  "template": "{skill_dir}/scripts/resource-locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
 }

package/{recipes/utility-run-ops-snapshot.json → skills/actors/recipes/run-ops-snapshot.json}

@@ -1,17 +1,15 @@
 {
   "args": [
-    "repo:path",
     "state_root:path",
     "run_id:string",
     "lines:int",
     "stale_minutes:int"
   ],
   "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
     "state_root": "~/.pi/agent/tmp/pi-actors/runs",
     "run_id": "music",
     "lines": "80",
     "stale_minutes": "60"
   },
-  "template": "{repo}/scripts/recipe-utils.mjs run-ops-snapshot {state_root} {run_id} {lines} {stale_minutes}"
+  "template": "{skill_dir}/scripts/run-utils.mjs run-ops-snapshot {state_root} {run_id} {lines} {stale_minutes}"
 }

package/skills/actors/recipes/run-summary.json

@@ -0,0 +1,9 @@
+{
+  "args": [
+    "state_root:path"
+  ],
+  "defaults": {
+    "state_root": "~/.pi/agent/tmp/pi-actors/runs"
+  },
+  "template": "{skill_dir}/scripts/run-utils.mjs run-summary {state_root}"
+}