@llblab/pi-actors 0.35.0 → 0.37.0

package/lib/recipes-discovery.ts

@@ -27,6 +27,7 @@ export interface DiscoveredRecipe {
   tool: boolean;
   mutableUsage: boolean;
   diagnostics: string[];
+  riskLabels: CommandTemplates.CommandTemplateRiskLabel[];
   shadows: string[];
 }
 
@@ -110,6 +111,14 @@ function listRecipeFiles(root: string): string[] {
     );
 }
 
+function getRecipeCommandTemplateConfig(
+  config: TemplateRecipeConfig,
+): CommandTemplates.CommandTemplateConfig {
+  return (typeof config.template === "object" && config.template !== null
+    ? config.template
+    : config) as CommandTemplates.CommandTemplateConfig;
+}
+
 function getRecipeConfigDiagnostics(
   file: string,
   config: TemplateRecipeConfig | undefined,
@@ -118,15 +127,36 @@ function getRecipeConfigDiagnostics(
     const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
     return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
   }
-  const commandTemplateConfig =
-    typeof config.template === "object" && config.template !== null
-      ? config.template
-      : config;
   return CommandTemplates.getCommandTemplateWarnings(
-    commandTemplateConfig as CommandTemplates.CommandTemplateConfig,
+    getRecipeCommandTemplateConfig(config),
   ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
+function getRecipeRiskLabels(
+  config: TemplateRecipeConfig | undefined,
+): CommandTemplates.CommandTemplateRiskLabel[] {
+  if (!config) return [];
+  const labels = new Set(
+    CommandTemplates.getCommandTemplateRiskLabels(
+      getRecipeCommandTemplateConfig(config),
+    ),
+  );
+  if (config.async === true) labels.add("risk.long_running");
+  return [
+    "risk.shell",
+    "risk.eval",
+    "risk.destructive_fs",
+    "risk.broad_fs_write",
+    "risk.external_side_effect",
+    "risk.secret_touching",
+    "risk.network",
+    "risk.long_running",
+    "risk.platform_specific",
+  ].filter((label): label is CommandTemplates.CommandTemplateRiskLabel =>
+    labels.has(label as CommandTemplates.CommandTemplateRiskLabel),
+  );
+}
+
 function readDiscoveredRecipe(
   root: string,
   file: string,
@@ -152,6 +182,7 @@ function readDiscoveredRecipe(
       tool: defaultTool && !disabled && !invalid,
       mutableUsage,
       diagnostics: getRecipeConfigDiagnostics(file, config),
+      riskLabels: getRecipeRiskLabels(config),
       shadows: [],
     };
   } catch (error) {
@@ -169,6 +200,7 @@ function readDiscoveredRecipe(
       diagnostics: [
         `Failed to load recipe ${file}: ${error instanceof Error ? error.message : String(error)}`,
       ],
+      riskLabels: [],
       shadows: [],
     };
   }
@@ -392,7 +424,7 @@ function diagnosticSeverity(message: string): "info" | "warning" | "error" {
     return "error";
   }
   if (
-    /world-writable|group-writable|invokes bash|eval|destructive|unsafe/i.test(
+    /world-writable|group-writable|invokes bash|eval|destructive|broad filesystem|unsafe/i.test(
       message,
     )
   ) {
@@ -435,6 +467,7 @@ function diagnosticDetails(
     seen.add(key);
     details.push({
       ...(entry ? { id: entry.id, path: entry.path } : {}),
+      ...(entry?.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
       action: diagnosticSuggestedAction(message),
       message,
       severity: diagnosticSeverity(message),
@@ -496,6 +529,7 @@ function remediationForEntry(
       kind: "risky_shell_boundary",
       severity: "warning",
       path: entry.path,
+      ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
       reason: riskyDiagnostics[0],
       action:
         "audit trusted command boundary; keep only if the recipe is local and intentional",
@@ -544,6 +578,31 @@ function discoveryRemediations(
     );
 }
 
+function summarizeRiskLabels(
+  entries: DiscoveredRecipe[],
+): Array<Record<string, unknown>> {
+  const counts = new Map<string, { count: number; ids: Set<string> }>();
+  for (const entry of entries) {
+    for (const label of entry.riskLabels) {
+      const current = counts.get(label) ?? { count: 0, ids: new Set<string>() };
+      current.count += 1;
+      current.ids.add(entry.id);
+      counts.set(label, current);
+    }
+  }
+  return [...counts.entries()]
+    .map(([label, value]) => ({
+      label,
+      count: value.count,
+      recipes: [...value.ids].sort(),
+    }))
+    .sort(
+      (a, b) =>
+        Number(b.count) - Number(a.count) ||
+        String(a.label).localeCompare(String(b.label)),
+    );
+}
+
 function recommendationForEntry(
   entry: DiscoveredRecipe,
   activePath: string | undefined,
@@ -598,6 +657,7 @@ export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
       /spawn run ([^\s]+)/,
     )?.[1];
     const preview = templatePreview(config?.template);
+    const riskLabels = getRecipeRiskLabels(resolved);
     return {
       id,
       path,
@@ -607,6 +667,7 @@ export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
       modified_at: stat.mtime.toISOString(),
       valid: Boolean(resolved),
       diagnostics,
+      ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
       ...(config?.description ? { description: config.description } : {}),
       ...(sourceRun ? { source_run: sourceRun } : {}),
       ...(config?.async !== undefined ? { async: config.async } : {}),
@@ -639,6 +700,7 @@ export function summarizeDiscovery(
         disabled: entry.disabled,
         invalid: entry.invalid,
         shadows: entry.shadows,
+        ...(entry.riskLabels.length ? { risk_labels: entry.riskLabels } : {}),
         ...(entry.config?.imports ? { imports: entry.config.imports } : {}),
         ...(recipeUsage(entry.config)
           ? { usage: recipeUsage(entry.config) }
@@ -665,6 +727,7 @@ export function summarizeDiscovery(
       .filter((entry) => entry.disabled)
       .map((entry) => ({ id: entry.id, path: entry.path }))
       .sort((a, b) => a.id.localeCompare(b.id)),
+    risk_summary: summarizeRiskLabels(result.entries),
     recommendations,
     remediations,
     top_action: remediations[0],

package/lib/recipes-references.ts

@@ -135,27 +135,55 @@ function recipeNameFiles(value: string): string[] {
   return [`${trimmed}.json`, `${trimmed}.md`];
 }
 
-function resolveRecipeImportPath(
+function recipeCandidatePaths(
   value: string,
   currentRecipeRoot: string,
-): string {
+): string[] {
   if (!isBareRecipeName(value))
-    return resolveRecipePath(value, currentRecipeRoot);
+    return [resolveRecipePath(value, currentRecipeRoot)];
   const roots = [
     Paths.getRecipeRoot(),
     currentRecipeRoot,
     Paths.getPackagedRecipeRoot(),
   ];
-  const candidates = [
+  return [
     ...new Set(
       roots.flatMap((root) =>
         recipeNameFiles(value).map((file) => resolve(root, file)),
       ),
     ),
   ];
+}
+
+function resolveRecipeImportPath(
+  value: string,
+  currentRecipeRoot: string,
+): string {
+  const candidates = recipeCandidatePaths(value, currentRecipeRoot);
   return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 
+export function resolveRecipeReferencePath(
+  value: unknown,
+  currentRecipeRoot = Paths.getRecipeRoot(),
+): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed || hasWhitespace(trimmed)) return undefined;
+  for (const path of recipeCandidatePaths(trimmed, currentRecipeRoot)) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = readRawRecipeConfig(path);
+      if (raw && typeof raw === "object" && Object.hasOwn(raw, "template"))
+        return path;
+      return path;
+    } catch {
+      return path;
+    }
+  }
+  return undefined;
+}
+
 export function getRecipePath(
   value: unknown,
   recipeRoot = Paths.getRecipeRoot(),
@@ -165,18 +193,7 @@ export function getRecipePath(
   if (!trimmed || hasWhitespace(trimmed)) return undefined;
   if (trimmed.endsWith(".json") || trimmed.endsWith(".md"))
     return resolveRecipePath(trimmed, recipeRoot);
-  const jsonPath = resolveRecipePath(trimmed, recipeRoot);
-  const mdPath = resolveRecipePath(`${trimmed}.md`, recipeRoot);
-  const path = existsSync(jsonPath) ? jsonPath : mdPath;
-  if (!existsSync(path)) return undefined;
-  try {
-    const raw = readRawRecipeConfig(path);
-    return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
-      ? path
-      : undefined;
-  } catch {
-    return undefined;
-  }
+  return resolveRecipeReferencePath(trimmed, recipeRoot);
 }
 
 function isImportNode(value: unknown): boolean {
@@ -483,7 +500,7 @@ export function getRecipeIdFromPath(file: string): string {
 }
 
 function readRecipeConfig(value: unknown): TemplateRecipeConfig | undefined {
-  const path = getRecipePath(value);
+  const path = resolveRecipeReferencePath(value);
   return path ? readResolvedRecipeConfig(path) : undefined;
 }
 
@@ -647,6 +664,7 @@ function applyDefaultsToTemplate(
 ): CommandTemplateValue {
   const cleanOverrides = { ...overrides };
   delete cleanOverrides.name;
+  delete cleanOverrides.template;
   delete cleanOverrides.values;
   if (typeof template === "object" && !Array.isArray(template)) {
     return {
@@ -686,6 +704,119 @@ function withActorRecipeContext(
   return { actorRecipeContext: context, template: value };
 }
 
+function loadDelegatedRecipe(
+  value: unknown,
+  currentRecipeFile: string,
+  stack: string[],
+  options: ReadResolvedRecipeConfigOptions,
+): TemplateRecipeConfig | undefined {
+  const path = resolveRecipeReferencePath(value, dirname(currentRecipeFile));
+  if (!path) return undefined;
+  const config = readResolvedRecipeConfig(
+    path,
+    [...stack, currentRecipeFile],
+    options,
+  );
+  if (!config) throw new Error(`Template recipe must define template: ${path}`);
+  if (config.disabled === true)
+    throw new Error(`Template recipe is disabled: ${path}`);
+  return config;
+}
+
+function applyDelegatedRecipeToNode(
+  delegated: TemplateRecipeConfig,
+  overrides: Record<string, unknown> = {},
+): CommandTemplateValue {
+  return applyDefaultsToTemplate(
+    delegated.template,
+    delegated.values,
+    overrides,
+  );
+}
+
+function expandRecipeDelegations(
+  value: CommandTemplateValue,
+  currentRecipeFile: string,
+  stack: string[],
+  options: ReadResolvedRecipeConfigOptions = {},
+): CommandTemplateValue {
+  if (typeof value === "string") {
+    const delegated = loadDelegatedRecipe(
+      value,
+      currentRecipeFile,
+      stack,
+      options,
+    );
+    return delegated ? applyDelegatedRecipeToNode(delegated) : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(
+      (item) =>
+        expandRecipeDelegations(
+          item as CommandTemplateValue,
+          currentRecipeFile,
+          stack,
+          options,
+        ) as CommandTemplateConfig,
+    );
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.template === "string") {
+    const delegated = loadDelegatedRecipe(
+      record.template,
+      currentRecipeFile,
+      stack,
+      options,
+    );
+    if (delegated) return applyDelegatedRecipeToNode(delegated, record);
+  }
+  if (Array.isArray(record.template)) {
+    return {
+      ...record,
+      template: record.template.map(
+        (item) =>
+          expandRecipeDelegations(
+            item as CommandTemplateValue,
+            currentRecipeFile,
+            stack,
+            options,
+          ) as CommandTemplateConfig,
+      ),
+    } as CommandTemplates.CommandTemplateObjectConfig;
+  }
+  if (record.template && typeof record.template === "object") {
+    return {
+      ...record,
+      template: expandRecipeDelegations(
+        record.template as CommandTemplateValue,
+        currentRecipeFile,
+        stack,
+        options,
+      ),
+    } as CommandTemplates.CommandTemplateObjectConfig;
+  }
+  return value;
+}
+
+function getDirectDelegatedRecipe(
+  value: CommandTemplateValue,
+  currentRecipeFile: string,
+  stack: string[],
+  options: ReadResolvedRecipeConfigOptions = {},
+): TemplateRecipeConfig | undefined {
+  if (typeof value === "string")
+    return loadDelegatedRecipe(value, currentRecipeFile, stack, options);
+  if (!Array.isArray(value) && typeof value.template === "string") {
+    return loadDelegatedRecipe(
+      value.template,
+      currentRecipeFile,
+      stack,
+      options,
+    );
+  }
+  return undefined;
+}
+
 function expandImportNodes(
   value: CommandTemplateValue,
   imports: Record<string, ImportedRecipe>,
@@ -807,7 +938,22 @@ export function readResolvedRecipeConfig(
   >;
   const template = getRecipeCommandTemplate(substituted);
   if (!template) return undefined;
-  const expandedTemplate = expandImportNodes(template, imports, options);
+  const expandedImportsTemplate = expandImportNodes(template, imports, options);
+  const delegated = getDirectDelegatedRecipe(
+    expandedImportsTemplate,
+    path,
+    stack,
+    options,
+  );
+  const expandedTemplate = delegated
+    ? applyDelegatedRecipeToNode(
+        delegated,
+        typeof expandedImportsTemplate === "object" &&
+          !Array.isArray(expandedImportsTemplate)
+          ? (expandedImportsTemplate as Record<string, unknown>)
+          : {},
+      )
+    : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
   const recipeName = getRecipeIdFromPath(path);
   const templateWithContext = options.includeActorRecipeContext
     ? withActorRecipeContext(expandedTemplate, {
@@ -817,33 +963,53 @@ export function readResolvedRecipeConfig(
         role: stack.length > 0 ? "import" : "entry",
       })
     : expandedTemplate;
+  const mergedDefaults = mergeDefaults(
+    delegated?.defaults,
+    isRecord(substituted.defaults) ? substituted.defaults : undefined,
+  );
+  const artifactSource = isRecord(substituted.artifacts)
+    ? substituted.artifacts
+    : delegated?.artifacts;
+  const mailboxSource = isRecord(substituted.mailbox)
+    ? substituted.mailbox
+    : delegated?.mailbox;
   return {
     name: recipeName,
     ...(typeof substituted.description === "string" &&
     substituted.description.trim()
       ? { description: substituted.description.trim() }
-      : {}),
+      : typeof delegated?.description === "string"
+        ? { description: delegated.description }
+        : {}),
     ...(typeof substituted.disabled === "boolean"
       ? { disabled: substituted.disabled }
-      : {}),
+      : typeof delegated?.disabled === "boolean"
+        ? { disabled: delegated.disabled }
+        : {}),
     ...(substituted.async === true
       ? { async: true }
       : substituted.async === false
         ? { async: false }
-        : {}),
+        : delegated?.async === true
+          ? { async: true }
+          : delegated?.async === false
+            ? { async: false }
+            : {}),
     ...(typeof substituted.state_dir === "string"
       ? { state_dir: substituted.state_dir }
-      : {}),
+      : typeof delegated?.state_dir === "string"
+        ? { state_dir: delegated.state_dir }
+        : {}),
     ...(Object.keys(imports).length > 0
       ? { imports: getRecipeImports(raw) }
       : {}),
     template: templateWithContext,
     ...(Array.isArray(substituted.args)
       ? { args: substituted.args as string[] }
-      : {}),
-    ...(isRecord(substituted.defaults)
-      ? { defaults: substituted.defaults }
-      : {}),
+      : Array.isArray(delegated?.args)
+        ? { args: delegated.args }
+        : {}),
+    ...(mergedDefaults ? { defaults: mergedDefaults } : {}),
     ...(typeof substituted.parallel === "boolean"
       ? { parallel: substituted.parallel }
       : {}),
@@ -865,31 +1031,31 @@ export function readResolvedRecipeConfig(
     ...(typeof substituted.output === "string"
       ? { output: substituted.output }
       : {}),
-    ...(isRecord(substituted.artifacts)
+    ...(isRecord(artifactSource)
       ? {
           artifacts: Object.fromEntries(
-            Object.entries(substituted.artifacts).filter(
+            Object.entries(artifactSource).filter(
               (entry): entry is [string, string] =>
                 typeof entry[1] === "string",
             ),
           ),
         }
       : {}),
-    ...(isRecord(substituted.mailbox)
+    ...(isRecord(mailboxSource)
       ? {
           mailbox: {
-            ...(Array.isArray(substituted.mailbox.accepts)
+            ...(Array.isArray(mailboxSource.accepts)
               ? {
-                  accepts: substituted.mailbox.accepts.filter(
+                  accepts: mailboxSource.accepts.filter(
                     (value): value is TemplateRecipeMailboxEntry =>
                       typeof value === "string" ||
                       (isRecord(value) && typeof value.type === "string"),
                   ),
                 }
               : {}),
-            ...(Array.isArray(substituted.mailbox.emits)
+            ...(Array.isArray(mailboxSource.emits)
               ? {
-                  emits: substituted.mailbox.emits.filter(
+                  emits: mailboxSource.emits.filter(
                     (value): value is TemplateRecipeMailboxEntry =>
                       typeof value === "string" ||
                       (isRecord(value) && typeof value.type === "string"),
@@ -899,7 +1065,8 @@ export function readResolvedRecipeConfig(
           },
         }
       : {}),
-    ...(substituted.retire_when === "children_terminal"
+    ...(substituted.retire_when === "children_terminal" ||
+    delegated?.retire_when === "children_terminal"
       ? { retire_when: "children_terminal" as const }
       : {}),
     ...(typeof substituted.retry === "number" ||

package/lib/registry.ts

@@ -50,7 +50,7 @@ export interface RegisterToolResult {
 export interface RegisterToolRuntimeDeps<TContext> {
   configPath: string;
   recipeRoot?: string;
-  getExternalToolConflict: (name: string) => string | undefined;
+  getToolNameBlocker: (name: string) => string | undefined;
   getTools: () => Map<string, Config.RegisteredTool>;
   getActiveTools: () => string[];
   notify: (
@@ -132,8 +132,8 @@ function promoteDraftRecipe<TContext>(
   const targetPath = getToolRecipePath(deps, name);
   const tools = deps.getTools();
   const existing = tools.get(name);
-  const conflict = deps.getExternalToolConflict(name);
-  if (conflict) throw new Error(ExecutionOutput.formatToolText(conflict));
+  const blocker = deps.getToolNameBlocker(name);
+  if (blocker) throw new Error(ExecutionOutput.formatToolText(blocker));
   if ((existing || existsSync(targetPath)) && !input.update) {
     throw new Error(
       ExecutionOutput.formatToolText(
@@ -383,8 +383,8 @@ export async function executeRegisterTool<TContext>(
     return deleteTool(name, ctx, deps);
   const tools = deps.getTools();
   const existing = tools.get(name);
-  const conflict = deps.getExternalToolConflict(name);
-  if (conflict) throw new Error(ExecutionOutput.formatToolText(conflict));
+  const blocker = deps.getToolNameBlocker(name);
+  if (blocker) throw new Error(ExecutionOutput.formatToolText(blocker));
   if (existing && !input.update) {
     throw new Error(
       ExecutionOutput.formatToolText(

package/lib/runtime-notifier.ts

@@ -147,6 +147,7 @@ export function createFileRuntimeNotifier(
       mkdirSync(dirname(file), { recursive: true });
       let position =
         options.replay || !existsSync(file) ? 0 : statSync(file).size;
+      let pending = "";
       let closed = false;
       const reconcile = (reason: RuntimeReconcileReason): void => {
         if (closed) return;
@@ -160,10 +161,15 @@ export function createFileRuntimeNotifier(
       const drain = (): void => {
         if (closed || !existsSync(file)) return;
         const buffer = readFileSync(file);
-        if (position > buffer.length) position = 0;
-        const chunk = buffer.subarray(position).toString("utf8");
+        if (position > buffer.length) {
+          position = 0;
+          pending = "";
+        }
+        const chunk = pending + buffer.subarray(position).toString("utf8");
         position = buffer.length;
-        for (const line of chunk.split("\n")) {
+        const lines = chunk.split("\n");
+        pending = chunk.endsWith("\n") ? "" : (lines.pop() ?? "");
+        for (const line of lines) {
           if (!line.trim()) continue;
           const event = parseRuntimeWakeEventLine(line);
           if (event && event.actor === actor) {

package/lib/runtime.ts

@@ -1,7 +1,7 @@
 /**
  * Tool registry runtime coordinator
  * Zones: runtime coordination, registry loading, pi tools
- * Owns persisted tool loading, conflict detection, runtime registration, and warning notification
+ * Owns persisted tool loading, reserved-name guards, runtime registration, and warning notification
  */
 
 import { existsSync, watch, type FSWatcher } from "node:fs";
@@ -19,17 +19,12 @@ export interface RuntimeContext {
   };
 }
 
-export interface ToolInfoLike {
-  name: string;
-}
-
 export interface ToolRegistryRuntimeDeps {
   configPath: string;
   exec: RegisteredToolExec;
   packagedRecipeRoot?: string;
   recipeRoot?: string;
   getActiveTools?: () => string[];
-  getAllTools: () => ToolInfoLike[];
   registerTool: (
     definition: ReturnType<typeof ToolsLocal.createRuntimeToolDefinition>,
   ) => void;
@@ -38,7 +33,7 @@ export interface ToolRegistryRuntimeDeps {
 }
 
 export interface ToolRegistryRuntime {
-  getExternalToolConflict(name: string): string | undefined;
+  getToolNameBlocker(name: string): string | undefined;
   getTools(): Map<string, Config.RegisteredTool>;
   loadTools(ctx: RuntimeContext): void;
   notify(
@@ -67,11 +62,9 @@ export function createAutoToolsRuntime(
   ) {
     if (ctx.hasUI) ctx.ui.notify(message, type);
   }
-  function getExternalToolConflict(name: string): string | undefined {
-    if (runtimeTools.has(name)) return undefined;
-    const existing = deps.getAllTools().find((tool) => tool.name === name);
-    return existing
-      ? `Tool "${name}" is already registered outside pi-actors.`
+  function getToolNameBlocker(name: string): string | undefined {
+    return deps.reservedToolNames.has(name)
+      ? `Reserved tool name: ${name}`
       : undefined;
   }
   function getToolFingerprint(cfg: Config.RegisteredTool): string {
@@ -105,6 +98,7 @@ export function createAutoToolsRuntime(
     runtimeToolFingerprints.set(cfg.name, fingerprint);
   }
   function isStartupActionableRegistryWarning(warning: string): boolean {
+    if (warning.includes(" shadows ")) return false;
     if (
       warning.includes("invokes bash;") &&
       warning.includes("trusted executable content")
@@ -166,9 +160,9 @@ export function createAutoToolsRuntime(
     }
     deactivateMissingRuntimeTools(new Set(tools.keys()));
     for (const cfg of tools.values()) {
-      const conflict = getExternalToolConflict(cfg.name);
-      if (conflict) {
-        warnings.push(conflict);
+      const blocker = getToolNameBlocker(cfg.name);
+      if (blocker) {
+        warnings.push(blocker);
         continue;
       }
       registerRuntimeTool(cfg);
@@ -179,7 +173,7 @@ export function createAutoToolsRuntime(
     }
   }
   return {
-    getExternalToolConflict,
+    getToolNameBlocker,
     getTools: () => tools,
     loadTools,
     notify,