@llblab/pi-actors 0.45.1 → 0.46.1

package/dist/lib/tools-local.js

@@ -44,7 +44,8 @@ function shouldAddRuntimeToolUsageHint(error) {
     return (/^Argument \S+ must /.test(message) || /^Missing .* value: /.test(message));
 }
 function formatRuntimeToolUsageHint(cfg, required, includeRunId) {
-    const optional = cfg.args.filter((arg) => !required.includes(arg));
+    const optional = cfg.args.filter((arg) => !RecipesReferences.isRuntimeOwnedRecipeInput(arg) &&
+        !required.includes(arg));
     const exampleDefaults = {
         ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
         ...cfg.defaults,
@@ -115,6 +116,8 @@ export function createRuntimeToolDefinition(cfg, exec) {
             ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
             : Schema.getRequiredToolArgNames(requiredTemplateConfig);
     for (const arg of cfg.args) {
+        if (RecipesReferences.isRuntimeOwnedRecipeInput(arg))
+            continue;
         paramSchema[arg] = typedArgSchema(arg, cfg.argTypes?.[arg]);
         if (requiredArgs.has(arg))
             required.push(arg);
@@ -160,7 +163,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
                         tool: cfg.name,
                         policy_values: ModelContext.withCurrentModelValues({ ...(cfg.recipe?.values ?? {}), ...values }, ctx),
                         values: resolveRecipeToolValues(cfg, values, ctx),
-                    }, ctx.cwd);
+                    }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
                     return {
                         content: [
                             {

package/dist/lib/tools-response.js

@@ -91,6 +91,8 @@ export function compactAsyncRunStatus(value) {
     const result = asRecord(status.result);
     const run = String(status.run ?? "<unknown>");
     const tokens = [`run=${run}`, `status=${String(status.status ?? "unknown")}`];
+    if (status.launch_kind)
+        tokens.push(`launch_kind=${String(status.launch_kind)}`);
     tokens.push(...compactModelPolicy(status.model_policy ?? progress.model_policy));
     if (status.tool)
         tokens.push(`tool=${String(status.tool)}`);

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

@@ -4,7 +4,9 @@
  * Owns the public spawn execution path for run-backed actors
  */
 import * as ModelContext from "./model-context.ts";
+import type * as RecipeResolution from "./recipes-context.ts";
 export interface SpawnToolContext extends ModelContext.CurrentModelContext {
+    recipeResolutionContext?: RecipeResolution.RecipeResolutionContext;
     cwd: string;
     sessionManager?: {
         getSessionId?: () => string;

package/dist/lib/tools-spawn.js

@@ -9,7 +9,6 @@ import * as AsyncRuns from "./async-runs.js";
 import { withFileMutationLock } from "./file-state.js";
 import * as ModelContext from "./model-context.js";
 import * as Paths from "./paths.js";
-import * as RecipesDiscovery from "./recipes-discovery.js";
 import * as RecipesUsage from "./recipes-usage.js";
 import * as Schema from "./schema.js";
 import * as ToolsResponse from "./tools-response.js";
@@ -18,17 +17,6 @@ const maybeJsonText = ToolsResponse.maybeJsonText;
 function getRunOwnerId(ctx) {
     return ctx.sessionManager?.getSessionId?.();
 }
-function shadowedRecipeLaunchDiagnostic(recipe) {
-    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) {
     return `${run.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "spawn"}.json`;
 }
@@ -60,16 +48,6 @@ function writeSpawnDraftRecipe(input, meta) {
     RecipesUsage.recordRecipeLaunch(path, new Date(), "spawn", Paths.getRecipeRoot());
     return path;
 }
-function enhanceSpawnRecipeError(error, recipe) {
-    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) {
     if (!target)
         return undefined;
@@ -90,8 +68,8 @@ export function createSpawnToolDefinition() {
         parameters: Schema.objectSchema({
             artifacts: Schema.looseObjectSchema("Optional named artifact paths for the spawned Run."),
             as: Schema.stringSchema("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."),
+            file: Schema.stringSchema("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("Inline command-template sequence or parallel tree"),
@@ -112,34 +90,28 @@ export function createSpawnToolDefinition() {
                 : typeof input.recipe === "string"
                     ? input.recipe
                     : undefined;
-            let meta;
-            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,
-                        }
-                        : {}),
-                    values: ModelContext.withCurrentModelValues(asRecord(input.values), ctx),
-                    ...(input.artifacts &&
-                        typeof input.artifacts === "object" &&
-                        !Array.isArray(input.artifacts)
-                        ? {
-                            artifacts: input.artifacts,
-                        }
-                        : {}),
-                }, 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,
+                    }
+                    : {}),
+                values: ModelContext.withCurrentModelValues(asRecord(input.values), ctx),
+                ...(input.artifacts &&
+                    typeof input.artifacts === "object" &&
+                    !Array.isArray(input.artifacts)
+                    ? {
+                        artifacts: input.artifacts,
+                    }
+                    : {}),
+            }, ctx.cwd, { skillContext: ctx.recipeResolutionContext?.activeSkills });
             const draftRecipe = writeSpawnDraftRecipe(input, meta);
             const nextActions = ToolsResponse.runNextActions(meta.run);
             const details = {

package/dist/lib/tools.d.ts

@@ -15,8 +15,11 @@ export interface CoreActorToolDefinitionDeps<TContext extends RuntimeToolContext
     configPath: string;
     getActiveTools: () => string[];
     getRuntimeTool: (name: string) => unknown;
+    getRuntimeToolStatus: (name: string) => Record<string, unknown> | undefined;
     handleRuntimeControl?: (action: string, input: unknown) => Record<string, unknown>;
-    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool">;
+    registryRuntime: Pick<RegisterToolRuntimeDeps<TContext>, "getToolNameBlocker" | "getTools" | "notify" | "registerRuntimeTool"> & {
+        getStatus(): import("./runtime.ts").RecipeRegistryStatus;
+    };
     setActiveTools: (toolNames: string[]) => void;
 }
 export declare function resolveActiveRuntimeTool(name: string, activeTools: Pick<Map<string, unknown>, "has">, getDefinition: (name: string) => unknown): unknown;

package/dist/lib/tools.js

@@ -41,6 +41,8 @@ export function createCoreActorToolDefinitions(deps) {
         }),
         ToolsInspect.createInspectToolDefinition({
             getTool: (name) => deps.getRuntimeTool(name),
+            getToolStatus: deps.getRuntimeToolStatus,
+            registryStatus: deps.registryRuntime.getStatus,
         }),
     ];
 }

package/dist/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/dist/skills/actors/SKILL.md

@@ -19,9 +19,9 @@ Use the swarm skill separately for decomposition, quorum design, reviewer lenses
 - `spawn`: create one Run from a Recipe or inline command template.
 - `message`: send one actor-local Control to `run:<id>`, or the reserved review actions to `runtime`.
 - `inspect`: inspect `run:<id>`, `runtime`, `recipes`, or `tool:<name>`.
-- `register_tool`: persist a trusted capability; it does not address a running actor.
+- `register_tool`: persist a trusted capability; it does not address a running actor. Trust current-session callability only when its result says `callable_now: true`.
 
-A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`.
+A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`. Spawning a user Recipe is still a Recipe launch (`launch_kind: "spawn"`), not evidence that its registered tool was exposed or invoked; registered-tool execution reports `launch_kind: "tool"`, and `inspect target=tool:<name> view=status` separates both usage counts.
 
 ## Recipe
 
@@ -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. A rejected component makes catalog inspection partial without blocking exact resolution of unrelated valid components in the same live session context. 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/dist/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/{recipes/utility-coordinator-lock-snapshot.json → dist/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/dist/{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/dist/{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/dist/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}"
+}

package/dist/{scripts/locker.mjs → skills/actors/scripts/resource-locker.mjs}

@@ -21,12 +21,12 @@ import readline from "node:readline";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 function packageRoot() {
-  return dirname(dirname(fileURLToPath(import.meta.url)));
+  return dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
 }
 
 async function importRuntimeModule(name) {
   const root = packageRoot();
-  const compiled = join(root, "dist", "lib", `${name}.js`);
+  const compiled = join(root, "lib", `${name}.js`);
   const source = join(root, "lib", `${name}.ts`);
   return await import(pathToFileURL(existsSync(compiled) ? compiled : source).href);
 }

package/dist/skills/actors/scripts/run-utils.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+/** Actor-owned Run summary utilities. */
+
+// @ts-nocheck
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function usage() {
+  console.error(`Usage:
+  run-utils.mjs run-summary <state-root>
+  run-utils.mjs run-ops-snapshot <state-root> <run-id> [lines] [stale-minutes]`);
+}
+
+function walkFiles(dir, maxDepth = 2, depth = 0, out = []) {
+  if (depth > maxDepth || !existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) walkFiles(path, maxDepth, depth + 1, out);
+    else if (stat.isFile()) out.push(path);
+  }
+  return out;
+}
+
+function readJson(file) {
+  if (!existsSync(file)) return undefined;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function getRunStatus(run, progress, result) {
+  if (progress?.phase) return progress.phase;
+  if (result?.code !== undefined) return result.code === 0 ? "done" : "failed";
+  return run.status ?? "unknown";
+}
+
+function collectRunSummary(rootValue) {
+  const root = resolve(rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  const files = walkFiles(root, 2).filter((file) => basename(file) === "run.json");
+  const rows = [];
+  for (const file of files) {
+    const run = readJson(file);
+    if (!run) {
+      rows.push({ run: relative(root, file), status: "invalid-json", recipe: "", updated: "" });
+      continue;
+    }
+    const runDir = dirname(file);
+    const progress = readJson(join(runDir, "progress.json"));
+    const result = readJson(join(runDir, "result.json"));
+    rows.push({
+      run: run.run_id ?? run.run ?? relative(root, file).split(sep)[0],
+      status: getRunStatus(run, progress, result),
+      recipe: run.recipe ?? run.recipe_file ?? "",
+      updated:
+        progress?.updatedAt ??
+        result?.completedAt ??
+        run.updated_at ??
+        run.completed_at ??
+        run.started_at ??
+        "",
+    });
+  }
+  rows.sort((a, b) => `${a.status}:${a.run}`.localeCompare(`${b.status}:${b.run}`));
+  return rows;
+}
+
+function tailJsonl(fileValue, linesValue = "80") {
+  const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  if (!existsSync(file)) return [];
+  const lines = Number.parseInt(linesValue, 10);
+  const count = Number.isFinite(lines) && lines > 0 ? lines : 80;
+  return readFileSync(file, "utf8")
+    .trimEnd()
+    .split("\n")
+    .filter(Boolean)
+    .slice(-count)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return { raw: line };
+      }
+    });
+}
+
+function runOpsSnapshot(
+  rootValue,
+  runIdValue = "music",
+  linesValue = "80",
+  staleMinutesValue = "60",
+) {
+  const runs = collectRunSummary(rootValue);
+  const root = resolve(rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+  const inspectedRun = String(runIdValue || "music");
+  const staleMs = Number(staleMinutesValue) * 60 * 1000;
+  const now = Date.now();
+  const recommendations = runs.flatMap((run) => {
+    const updatedMs = Date.parse(run.updated || "");
+    const stale =
+      Number.isFinite(updatedMs) &&
+      Number.isFinite(staleMs) &&
+      now - updatedMs > staleMs;
+    if (run.status === "running" && stale) {
+      return [{
+        run: run.run,
+        reason: "running-stale",
+        suggested_inspect: { target: `run:${run.run}`, view: "control" },
+      }];
+    }
+    if (["failed", "exited", "killed"].includes(run.status)) {
+      return [{
+        run: run.run,
+        reason: `terminal-${run.status}`,
+        suggested_inspect: { target: `run:${run.run}`, view: "trace" },
+      }];
+    }
+    return [];
+  });
+  console.log(JSON.stringify({
+    runs,
+    inspectedRun,
+    trace: tailJsonl(join(root, inspectedRun, "trace.jsonl"), linesValue),
+    recommendations,
+  }, null, 2));
+}
+
+function runSummary(rootValue) {
+  console.log(JSON.stringify(collectRunSummary(rootValue), null, 2));
+}
+
+function run(argv = process.argv.slice(2)) {
+  const [command, ...args] = argv;
+  if (command === "run-summary") {
+    runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+    return;
+  }
+  if (command === "run-ops-snapshot") {
+    runOpsSnapshot(
+      args[0] ?? "~/.pi/agent/tmp/pi-actors/runs",
+      args[1] ?? "music",
+      args[2],
+      args[3],
+    );
+    return;
+  }
+  usage();
+  fail(`Unknown command: ${command ?? ""}`);
+}
+
+try {
+  run();
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}