@llblab/pi-actors 0.36.0 → 0.37.1

package/dist/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.36.0
+  version: 0.37.1
 ---
 
 # Actors (pi-actors)
@@ -194,13 +194,14 @@ Rules:
 2. `async: true` makes spawned work a detached actor run.
 3. Public knobs belong in `args`/`defaults`; hidden launch mechanics stay inside `template`.
 4. Use `imports` to compose recipes; imported recipes are definitions, not nested async runs.
-5. When exposing an already-authored recipe as a user tool, make a small wrapper recipe in `~/.pi/agent/recipes` that imports the source recipe and uses a `{ "name": "alias" }` node. Do not copy the ready recipe's script command, defaults, mailbox, or artifacts into a second template.
-6. Declare `mailbox` for actors that accept or emit meaningful messages.
-7. Declare `artifacts` for durable outputs the coordinator should inspect.
-8. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
-9. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
-10. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
-11. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
+5. Direct recipe delegation is the thin-wrapper case: when a `template` value is just a ready recipe name/path, the intended behavior is to delegate to that recipe rather than execute the recipe file as a program. Use this for simple handoffs and wrapper tools; use `imports` + `{ "name": "alias" }` when you need rich composition, multiple nodes, or import-specific values/defaults.
+6. When exposing an already-authored recipe as a user tool before direct delegation is available or when composition is needed, make a small wrapper recipe in `~/.pi/agent/recipes` that imports the source recipe and uses a `{ "name": "alias" }` node. Do not copy the ready recipe's script command, defaults, mailbox, or artifacts into a second template.
+7. Declare `mailbox` for actors that accept or emit meaningful messages.
+8. Declare `artifacts` for durable outputs the coordinator should inspect.
+9. File-backed recipe identity comes from the filename basename; legacy top-level `name` fields are ignored by loaders.
+10. File-backed async recipes pass child `pi -p` actors a bounded JSONL recipe context bundle by default: raw entry/import recipe records, derived `name`, import path/alias, and `"you_are_here": true` on the launching recipe node. Set `"actor_context": false` or `"off"` to suppress it for minimal prompts.
+11. Keep packaged recipes generic: no machine-local paths, no private companion identities, no project-specific defaults unless the recipe is explicitly project-specific.
+12. Do not ship concrete model-version defaults in packaged recipes; expose `model`, `models`, and stage-specific model args so the caller must choose current policy at launch.
 
 Priority for same-id recipes:
 
@@ -209,7 +210,7 @@ Priority for same-id recipes:
 3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
 4. User recipe in `~/.pi/agent/recipes/*.json` or `*.md`: highest-priority operator tool surface.
 
-Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. Same-id overrides are normal composition/delegation behavior, not startup-warning material. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
@@ -230,7 +231,21 @@ Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memo
 
 Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete simple recipe files in the user recipe root; direct recipe-file editing is the right path when the wrapper needs `imports` or other top-level recipe metadata not exposed by the interactive mutation API.
 
-Ready-recipe registration pattern:
+Ready-recipe registration patterns:
+
+Thin delegation target shape:
+
+```json
+{
+  "description": "Run a ready recipe through a local tool name.",
+  "args": ["source:path", "volume:int=70"],
+  "template": "/path/to/ready-recipe.json"
+}
+```
+
+Delegation is for one-to-one handoff: expose or call a maintained recipe directly, preserving that recipe as the source of truth. If the runtime does not yet support direct recipe references in `template`, or if you need composition, use the import-node wrapper below.
+
+Composition/import wrapper:
 
 ```json
 {
@@ -243,16 +258,16 @@ Ready-recipe registration pattern:
 }
 ```
 
-Use this pattern whenever a reusable recipe already exists: packaged pi-actors components, project-local recipes, ad hoc reviewed recipe files, and especially skill-owned recipes that wrap skill scripts. The wrapper owns only the public tool name, description, optional narrowed args/defaults, and local usage metadata. The imported recipe remains the source of truth for the script path, default values, mailbox contract, artifacts, and future fixes.
+Use delegation or this import pattern whenever a reusable recipe already exists: packaged pi-actors components, project-local recipes, ad hoc reviewed recipe files, and especially skill-owned recipes that wrap skill scripts. The wrapper owns only the public tool name, description, optional narrowed args/defaults, and local usage metadata. The delegated/imported recipe remains the source of truth for the script path, default values, mailbox contract, artifacts, and future fixes.
 
 Tool-registration lenses are open-ended prompts for deciding what deserves durable tool status:
 
 1. **Reliability lens**: register wrappers for operations where agents commonly omit checks, run steps out of order, pass ambiguous inputs, or recover poorly from partial failure.
 2. **Safety lens**: prefer read-only diagnostics, dry-runs, preflights, confirmations, or bounded adapters around high-impact operations before registering direct action tools.
 3. **Context-affordance lens**: register tools whose mere presence in the injected capability list should steer agents toward the right operational habit.
-4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are the first candidates to import from a user-root wrapper when they match a recurring local workflow.
-5. **Skill-recipe lens**: when a skill ships a recipe for its script, local tools must import that recipe instead of calling the skill script directly. This preserves the skill's maintained interface and keeps future script/default changes centralized.
-6. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool.
+4. **Existing-recipe lens**: scan already-authored recipes before inventing a new tool. Packaged recipes, ad hoc project recipes, and recipes co-located under skill directories are the first candidates to delegate to or import from a user-root wrapper when they match a recurring local workflow.
+5. **Skill-recipe lens**: when a skill ships a recipe for its script, local tools must delegate to or import that recipe instead of calling the skill script directly. This preserves the skill's maintained interface and keeps future script/default changes centralized.
+6. **Composition lens**: register small semantic entrypoints over reusable recipe components instead of baking one large scenario-specific shell command into a tool; prefer direct delegation for one recipe, imports for composed graphs.
 7. **Portability lens**: keep recipe files transportable; make tool exposure a consequence of placement in `~/.pi/agent/recipes`, not recipe-owned markers or machine-local assumptions.
 
 Default bias: register diagnostic/preflight tools before action tools, and promote existing recipes before writing new orchestration. A good persistent tool shrinks the chance of a subtle operational mistake, not just the number of keystrokes.
@@ -260,7 +275,7 @@ Default bias: register diagnostic/preflight tools before action tools, and promo
 Tool templates may be:
 
 - A foreground command template.
-- A file-backed recipe name/path.
+- A file-backed recipe name/path for thin delegation.
 - A complete recipe body, optionally `async: true`.
 
 The user recipe root is the default tool set by location. It accepts canonical JSON recipes and literate Markdown recipes with frontmatter plus fenced `template`/`json recipe` blocks; same-id JSON shadows Markdown in the same priority layer. Packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
@@ -269,6 +284,8 @@ The user recipe root is the default tool set by location. It accepts canonical J
 
 Use packaged recipes by name with `spawn file=<name>` for async actors, or register/call them as tools when repeated use deserves a stable shortcut.
 
+Packaged review recipes are directly spawnable. Use `spawn file="pipeline-review-readiness" values={...}` for readiness review or `spawn file="subagent-review" values={...}` for one reviewer; pass model/thinking/tool policy through values, then inspect the run. Do not recreate their script commands, call packaged scripts directly, or create wrapper recipes just to launch the maintained recipe.
+
 - [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json): room-visible swarm coordination with roles, rounds, optional locker, artifact synthesis, and `subagent_ttl_ms` for hard participant budgets.
 - [`pipeline-repo-health`](../../recipes/pipeline-repo-health.json): git/doc/validation evidence → normalized repository health report.
 - [`pipeline-release-readiness`](../../recipes/pipeline-release-readiness.json): changelog/package/skill/validation evidence → release review → artifact report.

package/dist/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.36.0
+  version: 0.37.1
 ---
 
 # Swarm

package/docs/recipe-library.md

@@ -48,6 +48,8 @@ Core subagent recipes:
 
 Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. Packaged recipes intentionally do not ship concrete model-version defaults: callers must pass current model policy at launch, which keeps reusable recipe components from aging around old provider aliases. The generic prompt launchers, including `subagent-tools` and `subagents-prompts`, expose the same core model/thinking/tool/output knobs so callers do not need separate recipe families for policy tuning. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
 
+For one-off packaged subagent reviews, launch the recipe directly with `spawn file="subagent-review" values={...}` or `spawn file="pipeline-review-readiness" values={...}`. Do not copy the underlying `pi -p` command or wrap the recipe unless you are creating a durable operator tool with a narrower interface.
+
 For build-oriented swarms, prefer a consensus-first shape over parallel writers: proposer roles coordinate in a room with message/inspect tools, a named implementer owns the first artifact write, a QA reviewer inspects the result, and a finalizer applies review-grounded fixes before `run.done`. This pattern keeps creative/lens diversity while preserving one coherent artifact and gives recipes concrete artifact assertions instead of treating room discussion as success.
 
 Register one atom:

package/docs/template-recipes.md

@@ -292,9 +292,26 @@ An import binding may be either a string recipe path/name or an object with:
 
 A template node of `{ "name": "alias" }` is replaced with the imported recipe's command-template graph. Imported recipe defaults are merged with import `defaults`, import `values`, node `defaults`, and node `values`; later layers win. This lets a parent recipe embed a reusable recipe in a sequence or `parallel: true` branch without inventing a workflow language.
 
-Use imports as the default adapter for exposing ready recipes as local tools. A user-root recipe such as `~/.pi/agent/recipes/repo_context_check.json` should import the maintained source recipe and call `{ "name": "alias" }`, not duplicate the source recipe's script command. Skill scripts are the strongest version of this rule: when a skill provides `recipes/<name>.json` for its `scripts/*` entrypoint, local tools must import the skill recipe via `{agent}/skills/<skill>/recipes/<name>.json` instead of invoking the script path directly.
+Use imports as the default adapter for composed ready recipes. A user-root recipe such as `~/.pi/agent/recipes/repo_context_check.json` can import the maintained source recipe and call `{ "name": "alias" }` instead of duplicating the source recipe's script command. Skill scripts are the strongest version of this rule: when a skill provides `recipes/<name>.json` for its `scripts/*` entrypoint, local tools should delegate to or import the skill recipe instead of invoking the script path directly.
 
-Async composition stays explicit: importing a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
+## Direct Recipe Delegation
+
+A `template` string that resolves to a recipe name or recipe file path delegates to that recipe instead of executing the recipe file as a binary:
+
+```json
+{
+  "description": "Play music through the packaged player recipe.",
+  "async": true,
+  "defaults": { "source": "~/Music", "volume": "70" },
+  "template": "music-player"
+}
+```
+
+Delegation is a one-to-one handoff for thin wrappers and simple reuse. It uses the same bare-name priority as imports: user-root recipes under `~/.pi/agent/recipes`, then the importing recipe's directory, then packaged standard-library recipes. A higher-priority invalid or disabled recipe still blocks lower-priority fallback so operator overrides fail closed.
+
+Delegated recipes remain the source of truth for their command template, async setting, args/defaults, mailbox, artifacts, and future fixes. Wrapper recipe fields may narrow args/defaults or override lifecycle metadata. Use imports plus `{ "name": "alias" }` when you need rich composition, multiple recipe nodes, import-specific values/defaults, or a pipeline where the reusable recipe is only one step.
+
+Async composition stays explicit: importing or delegating to a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir; thin delegation may inherit `async: true` from the delegated recipe. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
 
 ```json
 {

package/index.ts

@@ -106,7 +106,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
     exec: CommandTemplates.execCommandTemplate,
     getActiveTools: () => pi.getActiveTools(),
-    getAllTools: () => pi.getAllTools(),
     registerTool: (definition) => {
       actorToolDefinitions.set(definition.name, definition);
       pi.registerTool(definition);

package/lib/async-runs.ts

@@ -67,11 +67,7 @@ import {
   deliverRunMessage,
   type SendRunMessageOptions,
 } from "./runs-messages.ts";
-import {
-  buildRunStatus,
-  tailFile,
-  tailLines,
-} from "./runs-status.ts";
+import { buildRunStatus, tailFile, tailLines } from "./runs-status.ts";
 import { readJsonFileResilient } from "./state-readers.ts";
 
 const RUNNER_IDENTITY_GRACE_MS = 5000;
@@ -213,8 +209,9 @@ function assertNoActiveRunState(stateDir: string): void {
 
 function resolveRecipeFile(file: string): string {
   return (
-    RecipesReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
-    RecipesReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT)
+    RecipesReferences.resolveRecipeReferencePath(file, Paths.getRecipeRoot()) ??
+    RecipesReferences.getRecipePath(file, Paths.getRecipeRoot()) ??
+    RecipesReferences.resolveRecipePath(file, Paths.getRecipeRoot())
   );
 }
 

package/lib/command-templates.ts

@@ -134,18 +134,33 @@ export function resolveInheritedDefaultReferences(
   inheritedDefaults: Record<string, unknown> | undefined,
   runtimeValues: Record<string, unknown> = {},
 ): Record<string, unknown> | undefined {
-  if (!ownDefaults || !inheritedDefaults) return ownDefaults;
+  if (!ownDefaults) return ownDefaults;
   const resolved = { ...ownDefaults };
+  const values = { ...(inheritedDefaults ?? {}), ...runtimeValues };
   for (const [key, value] of Object.entries(ownDefaults)) {
     if (typeof value !== "string") continue;
     const exact = /^\{([A-Za-z_][A-Za-z0-9_-]*)\}$/.exec(value);
-    if (
-      !exact ||
-      Object.hasOwn(runtimeValues, exact[1]) ||
-      !Object.hasOwn(inheritedDefaults, exact[1])
-    )
+    if (exact && Object.hasOwn(values, exact[1])) {
+      resolved[key] = values[exact[1]];
       continue;
-    resolved[key] = inheritedDefaults[exact[1]];
+    }
+    const indexed = value.match(
+      /^\{([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]\}$/,
+    );
+    if (!indexed) continue;
+    const source = values[indexed[1]];
+    const indexValue = /^\d+$/.test(indexed[2])
+      ? indexed[2]
+      : values[indexed[2]];
+    const index = Number(indexValue);
+    if (
+      Array.isArray(source) &&
+      Number.isInteger(index) &&
+      index >= 0 &&
+      index < source.length
+    ) {
+      resolved[key] = source[index] ?? "";
+    }
   }
   return resolved;
 }

package/lib/prompts.ts

@@ -31,7 +31,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
 - 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.
-- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
+- Prefer maintained packaged recipes/pipelines with spawn file=<recipe> before ad hoc scripts/wrappers; long fanout = parent async recipe wrapping template(parallel:true) and imports.
 - For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {

package/lib/recipes-context.ts

@@ -22,14 +22,68 @@ function isPiCommand(command: string): boolean {
   return commandName(command) === "pi";
 }
 
+const PI_PRINT_FLAGS = new Set(["-p", "--print"]);
+const PI_VALUE_OPTIONS = new Set([
+  "--api-key",
+  "--append-system-prompt",
+  "--exclude-tools",
+  "--extension",
+  "--fork",
+  "--mode",
+  "--model",
+  "--models",
+  "--name",
+  "--prompt-template",
+  "--provider",
+  "--session",
+  "--session-dir",
+  "--skill",
+  "--system-prompt",
+  "--theme",
+  "--thinking",
+  "--tools",
+]);
+const PI_SHORT_VALUE_OPTIONS = new Set(["-e", "-n", "-t", "-xt"]);
+
+function isPiPrintFlag(arg: string): boolean {
+  return PI_PRINT_FLAGS.has(arg);
+}
+
+function isPiOption(arg: string): boolean {
+  return arg.startsWith("-") && arg !== "-";
+}
+
+function piOptionConsumesNextArg(arg: string): boolean {
+  if (arg.includes("=")) return false;
+  return PI_VALUE_OPTIONS.has(arg) || PI_SHORT_VALUE_OPTIONS.has(arg);
+}
+
+function isPiFileArgument(arg: string): boolean {
+  return arg.startsWith("@") && arg.length > 1;
+}
+
 function findPrintPromptIndex(args: string[]): number | undefined {
+  let printMode = false;
+  let positionalOnly = false;
+  let promptIndex: number | undefined;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
-    if ((arg === "-p" || arg === "--print") && index + 1 < args.length) {
-      return index + 1;
+    if (!positionalOnly && arg === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (!positionalOnly && isPiPrintFlag(arg)) {
+      printMode = true;
+      continue;
+    }
+    if (!positionalOnly && isPiOption(arg)) {
+      if (piOptionConsumesNextArg(arg)) index += 1;
+      continue;
     }
+    if (!printMode || isPiFileArgument(arg)) continue;
+    promptIndex = index;
   }
-  return undefined;
+  return promptIndex;
 }
 
 function matchesActorContext(