@llblab/pi-actors 0.16.1 → 0.16.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.16.3: Recipe Import Path Placeholders
+
+- `[Template Recipes]` Added static `{repo}` and `{agent}` expansion for recipe paths, including `imports` and `from` bindings. Impact: recipes can import sibling packaged/user recipes without hard-coded absolute paths while keeping imports load-time deterministic.
+- `[Docs]` Documented `{repo}` and `{agent}` import path placeholders in the template recipe standard.
+- `[Package]` Bumped package and packaged skill metadata to `0.16.3` for the hotfix release.
+
+## 0.16.2: Recipe Registry Diagnostics Hotfix
+
+- `[Schema]` Derived recipe tool arguments without expanding runtime-dependent repeat nodes. Impact: valid recipes using repeat expressions such as `{lenses.length}` can be exposed as tools instead of being skipped during startup schema generation.
+- `[Runtime]` Replaced the dense semicolon warning with grouped recipe registry diagnostics and explicit spacing. Impact: startup diagnostics are easier to scan and do not visually run into adjacent text.
+- `[Recipes]` Added a packaged `lens-swarm` recipe that composes the review coordinator without concrete model-version defaults. Impact: the standard library includes the general multi-lens review launcher instead of relying only on operator-local copies.
+- `[Package]` Bumped package and packaged skill metadata to `0.16.2` for the hotfix release.
+
 ## 0.16.1: Recipe Registry Hotfix
 
 - `[Runtime]` Prevented invalid user recipe files from aborting extension startup when tool-schema generation fails, surfacing a warning and skipping the offending tool instead. Impact: one bad recipe in `~/.pi/agent/recipes` no longer takes down the pi-actors extension.

package/docs/template-recipes.md

@@ -245,7 +245,7 @@ File-backed recipes may import other file-backed recipes at the recipe layer. Im
 
 An import binding may be either a string recipe path/name or an object with:
 
-- `from`: recipe path or bare name.
+- `from`: recipe path or bare name. Import paths support static load-time placeholders: `{repo}` expands to the directory above the active recipe root, and `{agent}` expands to the pi agent directory. For a packaged recipe in `<repo>/recipes/name.json`, `{repo}/recipes/other.json` resolves to a sibling packaged recipe. For a user recipe in `~/.pi/agent/recipes/name.json`, `{repo}` and `{agent}` both resolve to `~/.pi/agent`.
 - `defaults`: extra default values exposed through the import.
 - `values`: explicit values for embedding that imported recipe.
 

package/lib/recipe-discovery.ts

@@ -41,6 +41,32 @@ export interface RecipeDiscoverySource {
   mutableUsage?: boolean;
 }
 
+function assertToolSafeRepeatConfig(
+  config: unknown,
+  argTypes: Record<string, { kind: string }>,
+  defaults: Record<string, unknown>,
+): void {
+  if (typeof config === "string" || config === undefined || config === null) return;
+  if (Array.isArray(config)) {
+    for (const step of config) assertToolSafeRepeatConfig(step, argTypes, defaults);
+    return;
+  }
+  if (typeof config !== "object") return;
+  const node = config as { repeat?: unknown; template?: unknown; recover?: unknown };
+  if (typeof node.repeat === "string") {
+    const trimmed = node.repeat.trim();
+    if (!/^\d+$/.test(trimmed)) {
+      const match = trimmed.match(/^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/);
+      if (!match || (argTypes[match[1]]?.kind !== "array" && !Array.isArray(defaults[match[1]])))
+        throw new Error(
+          "Command template repeat must be a positive integer or {array.length} with an array argument/default.",
+        );
+    }
+  }
+  assertToolSafeRepeatConfig(node.template, argTypes, defaults);
+  assertToolSafeRepeatConfig(node.recover, argTypes, defaults);
+}
+
 function listRecipeFiles(root: string): string[] {
   if (!existsSync(root)) return [];
   return readdirSync(root, { withFileTypes: true })
@@ -207,6 +233,13 @@ export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | unde
           defaults: { ...(argTemplate.defaults ?? {}), ...(cfg.defaults ?? {}) },
         }
       : { args: cfg.args, defaults: cfg.defaults ?? {}, template: argTemplate };
+  const explicitArgTypes = Object.fromEntries(
+    (cfg.args ?? []).map((arg) => {
+      const parsed = Schema.parseToolArgToken(String(arg));
+      return [parsed.arg, parsed.type];
+    }),
+  );
+  assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, cfg.defaults ?? {});
   const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
   return {
     name: entry.id,

package/lib/recipe-references.ts

@@ -75,11 +75,15 @@ export function resolveRecipePath(
   recipeRoot = Paths.getRecipeRoot(),
 ): string {
   const trimmed = value.trim();
-  if (trimmed.startsWith("~/")) return resolve(homedir(), trimmed.slice(2));
-  if (trimmed.includes("/")) return resolve(trimmed);
+  const repoRoot = resolve(recipeRoot, "..");
+  const expanded = trimmed
+    .replaceAll("{repo}", repoRoot)
+    .replaceAll("{agent}", Paths.getAgentDir());
+  if (expanded.startsWith("~/")) return resolve(homedir(), expanded.slice(2));
+  if (expanded.includes("/")) return resolve(expanded);
   return resolve(
     recipeRoot,
-    trimmed.endsWith(".json") ? trimmed : `${trimmed}.json`,
+    expanded.endsWith(".json") ? expanded : `${expanded}.json`,
   );
 }
 

package/lib/runtime.ts

@@ -98,6 +98,27 @@ export function createAutoToolsRuntime(
     runtimeTools.add(cfg.name);
     runtimeToolFingerprints.set(cfg.name, fingerprint);
   }
+  function formatRecipeToolWarnings(warnings: string[]): string {
+    const shadowed = warnings.filter((warning) => warning.includes(" shadows "));
+    const skipped = warnings.filter((warning) => warning.includes(" could not be exposed as a tool:"));
+    const other = warnings.filter(
+      (warning) => !shadowed.includes(warning) && !skipped.includes(warning),
+    );
+    const lines = ["pi-actors recipe registry warning"];
+    if (shadowed.length > 0) {
+      lines.push("User recipes override packaged recipes:");
+      lines.push(...shadowed.map((warning) => `• ${warning}`));
+    }
+    if (skipped.length > 0) {
+      lines.push("Recipes skipped from tool exposure:");
+      lines.push(...skipped.map((warning) => `• ${warning}`));
+    }
+    if (other.length > 0) {
+      lines.push("Other registry diagnostics:");
+      lines.push(...other.map((warning) => `• ${warning}`));
+    }
+    return `${lines.join("\n")}\n`;
+  }
   function loadTools(ctx: RuntimeContext) {
     const warnings: string[] = [];
     const recipeRoot = deps.recipeRoot ?? Paths.getRecipeRoot();
@@ -138,7 +159,7 @@ export function createAutoToolsRuntime(
       registerRuntimeTool(cfg);
     }
     if (warnings.length > 0) {
-      notify(ctx, `Recipe tools: ${warnings.join("; ")}`, "warning");
+      notify(ctx, formatRecipeToolWarnings(warnings), "warning");
     }
   }
   return {

package/lib/schema.ts

@@ -261,19 +261,35 @@ function collectWhenDeclarations(
     declarations.push(parseToolArgToken(`${bareCondition[1]}:bool=false`));
 }
 
+function collectCommandTemplateConfigDeclarations(
+  config: CommandTemplates.CommandTemplateConfig | CommandTemplates.CommandTemplateValue,
+  declarations: ParsedToolArgToken[],
+): void {
+  if (typeof config === "string") {
+    collectTemplatePlaceholderDeclarations(config, declarations);
+    return;
+  }
+  if (Array.isArray(config)) {
+    for (const step of config)
+      collectCommandTemplateConfigDeclarations(step, declarations);
+    return;
+  }
+  if (config.template !== undefined)
+    collectCommandTemplateConfigDeclarations(config.template, declarations);
+  if (config.recover !== undefined)
+    collectCommandTemplateConfigDeclarations(config.recover, declarations);
+  for (const field of [config.timeout, config.delay, config.retry, config.repeat]) {
+    if (typeof field === "string")
+      collectTemplatePlaceholderDeclarations(field, declarations);
+  }
+  if (typeof config.when === "string") collectWhenDeclarations(config.when, declarations);
+}
+
 function getTemplatePlaceholderDeclarations(
   config: CommandTemplates.CommandTemplateConfig,
 ): ParsedToolArgToken[] {
   const declarations: ParsedToolArgToken[] = [];
-  for (const step of CommandTemplates.expandCommandTemplateConfigs(config)) {
-    collectTemplatePlaceholderDeclarations(step.template, declarations);
-    for (const field of [step.timeout, step.delay, step.retry]) {
-      if (typeof field === "string")
-        collectTemplatePlaceholderDeclarations(field, declarations);
-    }
-    if (typeof step.when === "string")
-      collectWhenDeclarations(step.when, declarations);
-  }
+  collectCommandTemplateConfigDeclarations(config, declarations);
   return declarations;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "keywords": [

package/recipes/lens-swarm.json

@@ -0,0 +1,68 @@
+{
+  "name": "lens-swarm",
+  "description": "General-purpose multi-lens review swarm. Launches independent reviewers by lens, then verifies, merges, judges, and normalizes the result.",
+  "tool": true,
+  "async": true,
+  "imports": {
+    "coordinator": "subagent-review-coordinator.json"
+  },
+  "args": [
+    "scope:string",
+    "lenses:array",
+    "model:string",
+    "thinking:string",
+    "tools:string",
+    "claim:string",
+    "evidence_policy:string",
+    "risk_policy:string",
+    "output_format:string"
+  ],
+  "defaults": {
+    "lenses": [
+      "correctness",
+      "architecture",
+      "operator UX"
+    ],
+    "thinking": "off",
+    "tools": "",
+    "claim": "The reviewed scope has clear, evidence-based findings, risks, and recommended next actions.",
+    "evidence_policy": "Cite inspected files, command outputs, or explicit uncertainty for every material claim.",
+    "risk_policy": "Preserve minority high-impact risks and ideas; separate confirmed issues from hypotheses.",
+    "output_format": "Markdown sections: Summary, Consensus Findings, Minority Findings, Verification, Judge Notes, Risks, Next Actions."
+  },
+  "mailbox": {
+    "accepts": [
+      "control.stop",
+      "control.cancel",
+      "control.kill"
+    ],
+    "emits": [
+      "review.completed",
+      "verification.completed",
+      "merge.completed",
+      "judge.completed",
+      "command.done",
+      "run.done",
+      "run.failed"
+    ]
+  },
+  "template": [
+    {
+      "name": "coordinator",
+      "values": {
+        "scope": "{scope}",
+        "lenses": "{lenses}",
+        "claim": "{claim}",
+        "reviewer_model": "{model}",
+        "verifier_model": "{model}",
+        "merger_model": "{model}",
+        "judge_model": "{model}",
+        "thinking": "{thinking}",
+        "tools": "{tools}",
+        "evidence_policy": "{evidence_policy}",
+        "risk_policy": "{risk_policy}",
+        "output_format": "{output_format}"
+      }
+    }
+  ]
+}

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.16.1
+  version: 0.16.3
 ---
 
 # Actors (pi-actors)
@@ -216,7 +216,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - Review chain: [`subagent-review`](../../recipes/subagent-review.json), [`subagent-verify`](../../recipes/subagent-verify.json), [`subagent-merge`](../../recipes/subagent-merge.json), [`subagent-judge`](../../recipes/subagent-judge.json), [`subagent-normalize`](../../recipes/subagent-normalize.json).
 - Planning/evidence: [`subagent-plan`](../../recipes/subagent-plan.json), [`subagent-task-card`](../../recipes/subagent-task-card.json), [`subagent-evidence-map`](../../recipes/subagent-evidence-map.json), [`subagent-contradiction-map`](../../recipes/subagent-contradiction-map.json), [`subagent-critic`](../../recipes/subagent-critic.json).
 - Handoffs: [`subagent-checkpoint`](../../recipes/subagent-checkpoint.json), [`subagent-followup`](../../recipes/subagent-followup.json), [`subagent-message`](../../recipes/subagent-message.json), [`subagent-artifact`](../../recipes/subagent-artifact.json), [`subagent-conflict-report`](../../recipes/subagent-conflict-report.json).
-- Composition: [`subagent-quorum`](../../recipes/subagent-quorum.json), [`subagent-review-coordinator`](../../recipes/subagent-review-coordinator.json).
+- Composition: [`subagent-quorum`](../../recipes/subagent-quorum.json), [`subagent-review-coordinator`](../../recipes/subagent-review-coordinator.json), [`lens-swarm`](../../recipes/lens-swarm.json).
 
 ### Pipelines
 

package/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.16.1
+  version: 0.16.3
 ---
 
 # Swarm