@llblab/pi-actors 0.20.2 → 0.21.0

package/lib/observability.ts

@@ -5,7 +5,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
@@ -52,9 +52,25 @@ export interface RunSummary {
 
 export interface RunRetirementCandidate {
   activeSubagents: number;
+  childRuns: number;
   descendantSubagents: number;
   run: string;
   stateDir: string;
+  terminalChildRuns: number;
+}
+
+export interface RunRetirementExecution {
+  action: "stop" | "cancel" | "skip" | "failed";
+  error?: string;
+  run: string;
+  stateDir: string;
+}
+
+export interface RunRetirementExecutorOptions {
+  attempted?: Set<string>;
+  cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;
+  notify?: (message: string, level: "info" | "warning" | "error") => void;
+  sendStop: (candidate: RunRetirementCandidate) => Promise<unknown>;
 }
 
 export interface RunTransition {
@@ -93,6 +109,7 @@ const TERMINAL = new Set<RunObservedStatus>([
   "killed",
 ]);
 const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
+const RUN_STATE_DISCOVERY_MAX_DEPTH = 8;
 
 const procDescendantScanCache = new Map<
   string,
@@ -120,6 +137,30 @@ function getUpdatedAt(status: Record<string, unknown>): string | undefined {
       : undefined;
 }
 
+function listRunStateDirs(
+  stateRoot: string,
+  depth = 0,
+  seen = new Set<string>(),
+): string[] {
+  if (!existsSync(stateRoot) || seen.has(stateRoot)) return [];
+  seen.add(stateRoot);
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(stateRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join(stateRoot, entry.name);
+    if (existsSync(join(child, "run.json"))) result.push(child);
+    if (depth + 1 < RUN_STATE_DISCOVERY_MAX_DEPTH)
+      result.push(...listRunStateDirs(child, depth + 1, seen));
+  }
+  return result;
+}
+
 function observeRun(stateDir: string): RunObservation | undefined {
   try {
     const status = AsyncRuns.getRunStatus(stateDir);
@@ -178,9 +219,8 @@ export function summarizeRuns(
       total: 0,
     };
   }
-  const runs = readdirSync(stateRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => observeRun(join(stateRoot, entry.name)))
+  const runs = listRunStateDirs(stateRoot)
+    .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -242,7 +282,7 @@ function getRunningRunPidMap(stateRoot: string, ownerId?: string): Map<string, s
   const pids = new Map<string, string>();
   for (const run of summarizeRunsWithoutSubagents(stateRoot, ownerId).runs) {
     if (run.status !== "running") continue;
-    const status = AsyncRuns.getRunStatus(join(stateRoot, run.run));
+    const status = AsyncRuns.getRunStatus(run.stateDir ?? join(stateRoot, run.run));
     const pid = Number(status.pid || 0);
     if (pid > 0) pids.set(String(pid), run.run);
   }
@@ -264,9 +304,8 @@ function summarizeRunsWithoutSubagents(
       runs: [],
       total: 0,
     };
-  const runs = readdirSync(stateRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => observeRun(join(stateRoot, entry.name)))
+  const runs = listRunStateDirs(stateRoot)
+    .map((stateDir) => observeRun(stateDir))
     .filter((run): run is RunObservation => Boolean(run))
     .filter((run) => ownerId === undefined || run.ownerId === ownerId)
     .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -370,28 +409,102 @@ export function renderRunStatus(
   return renderSubagentStatus(summary.runningSubagents, frame);
 }
 
+function isNestedStateDir(parent: string, child: string): boolean {
+  const path = relative(parent, child);
+  return Boolean(path) && !path.startsWith("..") && !isAbsolute(path);
+}
+
 export function findRunRetirementCandidates(
   summary: RunSummary,
 ): RunRetirementCandidate[] {
   return summary.runs
-    .filter((run) => {
+    .map((run) => {
       const activeSubagents = Math.max(0, Math.floor(run.activeSubagents ?? 0));
       const descendantSubagents = Math.max(0, Math.floor(run.descendantSubagents ?? 0));
-      return (
-        run.status === "running" &&
-        run.retireWhen === "children_terminal" &&
-        run.stateDir &&
-        activeSubagents + descendantSubagents <= 0
-      );
+      const childRuns = run.stateDir
+        ? summary.runs.filter(
+            (child) =>
+              child.stateDir !== undefined &&
+              child.stateDir !== run.stateDir &&
+              isNestedStateDir(run.stateDir!, child.stateDir),
+          )
+        : [];
+      const runningChildRuns = childRuns.filter((child) => child.status === "running").length;
+      return {
+        activeSubagents,
+        childRuns: childRuns.length,
+        descendantSubagents,
+        ready:
+          run.status === "running" &&
+          run.retireWhen === "children_terminal" &&
+          run.stateDir !== undefined &&
+          !run.terminalHandled &&
+          activeSubagents + descendantSubagents + runningChildRuns <= 0,
+        run,
+        terminalChildRuns: childRuns.filter((child) => TERMINAL.has(child.status)).length,
+      };
     })
-    .map((run) => ({
-      activeSubagents: Math.max(0, Math.floor(run.activeSubagents ?? 0)),
-      descendantSubagents: Math.max(0, Math.floor(run.descendantSubagents ?? 0)),
-      run: run.run,
-      stateDir: run.stateDir!,
+    .filter((item) => item.ready)
+    .map((item) => ({
+      activeSubagents: item.activeSubagents,
+      childRuns: item.childRuns,
+      descendantSubagents: item.descendantSubagents,
+      run: item.run.run,
+      stateDir: item.run.stateDir!,
+      terminalChildRuns: item.terminalChildRuns,
     }));
 }
 
+export async function executeRunRetirements(
+  summary: RunSummary,
+  options: RunRetirementExecutorOptions,
+): Promise<RunRetirementExecution[]> {
+  const results: RunRetirementExecution[] = [];
+  for (const candidate of findRunRetirementCandidates(summary)) {
+    if (options.attempted?.has(candidate.stateDir)) {
+      results.push({ action: "skip", run: candidate.run, stateDir: candidate.stateDir });
+      continue;
+    }
+    options.attempted?.add(candidate.stateDir);
+    try {
+      await options.sendStop(candidate);
+      options.notify?.(
+        `Retiring actor ${candidate.run} after child runs reached terminal state`,
+        "info",
+      );
+      results.push({ action: "stop", run: candidate.run, stateDir: candidate.stateDir });
+      continue;
+    } catch (error) {
+      try {
+        const cancelResult = options.cancelRun(candidate);
+        const cancelled = Boolean((cancelResult as { cancelled?: unknown }).cancelled);
+        options.notify?.(
+          cancelled
+            ? `Retiring actor ${candidate.run} by cancellation after graceful stop failed`
+            : `Actor retirement skipped for ${candidate.run}: ${error instanceof Error ? error.message : String(error)}`,
+          cancelled ? "warning" : "error",
+        );
+        results.push({
+          action: cancelled ? "cancel" : "skip",
+          ...(cancelled ? {} : { error: error instanceof Error ? error.message : String(error) }),
+          run: candidate.run,
+          stateDir: candidate.stateDir,
+        });
+      } catch (cancelError) {
+        const message = cancelError instanceof Error ? cancelError.message : String(cancelError);
+        options.notify?.(`Actor retirement failed for ${candidate.run}: ${message}`, "error");
+        results.push({
+          action: "failed",
+          error: message,
+          run: candidate.run,
+          stateDir: candidate.stateDir,
+        });
+      }
+    }
+  }
+  return results;
+}
+
 export function detectRunTransitions(
   previous: Map<string, RunObservedStatus>,
   summary: RunSummary,

package/lib/recipe-discovery.ts

@@ -88,11 +88,11 @@ function listRecipeFiles(root: string): string[] {
     .filter(
       (entry) =>
         entry.isFile() &&
-        entry.name.endsWith(".json") &&
+        (entry.name.endsWith(".json") || entry.name.endsWith(".md")) &&
         entry.name !== "legacy-tool-registry-migration-report.json",
     )
     .map((entry) => join(root, entry.name))
-    .sort();
+    .sort((a, b) => a.replace(/\.md$/, ".json").localeCompare(b.replace(/\.md$/, ".json")) || (a.endsWith(".json") ? -1 : 1));
 }
 
 function getRecipeConfigDiagnostics(
@@ -100,9 +100,15 @@ function getRecipeConfigDiagnostics(
   config: TemplateRecipeConfig | undefined,
 ): string[] {
   if (!config) return [`Invalid recipe: ${file}`];
+  const commandTemplateConfig =
+    typeof config.template === "object" && config.template !== null
+      ? config.template
+      : config;
   return CommandTemplates.getCommandTemplateWarnings(
-    typeof config.template === "string" ? config.template : { template: config.template },
-  ).map((warning) => `Recipe ${file}: ${warning}`);
+    commandTemplateConfig as CommandTemplates.CommandTemplateConfig,
+  ).map(
+    (warning) => `Recipe ${file}: ${warning}`,
+  );
 }
 
 function readDiscoveredRecipe(
@@ -218,13 +224,22 @@ export function discoverRecipeSources(
   const diagnostics: string[] = getRecipeRootDiagnostics(sources);
   for (const [id, bucket] of byId) {
     bucket.sort(
-      (a, b) => a.priority - b.priority || a.path.localeCompare(b.path),
+      (a, b) =>
+        a.priority - b.priority ||
+        a.path.replace(/\.md$/, ".json").localeCompare(b.path.replace(/\.md$/, ".json")) ||
+        (a.path.endsWith(".json") ? -1 : 1),
     );
     const winner = bucket[0];
     winner.active = true;
     winner.shadows = bucket.slice(1).map((entry) => entry.path);
     active.set(id, winner);
-    for (const shadow of bucket.slice(1)) shadow.shadowed = true;
+    for (const shadow of bucket.slice(1)) {
+      shadow.shadowed = true;
+      if (winner.path.endsWith(".json") && shadow.path.endsWith(".md"))
+        shadow.diagnostics.push(
+          `Markdown recipe ${shadow.path} is shadowed by JSON recipe ${winner.path}`,
+        );
+    }
     if (winner.invalid)
       diagnostics.push(
         `Recipe ${id} is invalid and blocks lower-priority recipes`,

package/lib/recipe-references.ts

@@ -6,7 +6,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, extname, resolve } from "node:path";
 
 import type {
   CommandTemplateConfig,
@@ -101,7 +101,9 @@ export function resolveRecipePath(
   if (expanded.includes("/")) return resolve(expanded);
   return resolve(
     recipeRoot,
-    expanded.endsWith(".json") ? expanded : `${expanded}.json`,
+    expanded.endsWith(".json") || expanded.endsWith(".md")
+      ? expanded
+      : `${expanded}.json`,
   );
 }
 
@@ -110,20 +112,26 @@ function isBareRecipeName(value: string): boolean {
   return Boolean(trimmed) && !trimmed.includes("/") && !trimmed.startsWith("~") && !trimmed.includes("{");
 }
 
-function recipeNameFile(value: string): string {
+function recipeNameFiles(value: string): string[] {
   const trimmed = value.trim();
-  return trimmed.endsWith(".json") ? trimmed : `${trimmed}.json`;
+  if (trimmed.endsWith(".json") || trimmed.endsWith(".md")) return [trimmed];
+  return [`${trimmed}.json`, `${trimmed}.md`];
 }
 
 function resolveRecipeImportPath(value: string, currentRecipeRoot: string): string {
   if (!isBareRecipeName(value)) return resolveRecipePath(value, currentRecipeRoot);
-  const file = recipeNameFile(value);
   const roots = [
     Paths.getRecipeRoot(),
     currentRecipeRoot,
     Paths.getPackagedRecipeRoot(),
   ];
-  const candidates = [...new Set(roots.map((root) => resolve(root, file)))];
+  const candidates = [
+    ...new Set(
+      roots.flatMap((root) =>
+        recipeNameFiles(value).map((file) => resolve(root, file)),
+      ),
+    ),
+  ];
   return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
 }
 
@@ -134,14 +142,14 @@ export function getRecipePath(
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
   if (!trimmed || hasWhitespace(trimmed)) return undefined;
-  if (trimmed.endsWith(".json")) return resolveRecipePath(trimmed, recipeRoot);
-  const path = resolveRecipePath(trimmed, recipeRoot);
+  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 = JSON.parse(readFileSync(path, "utf8")) as Record<
-      string,
-      unknown
-    >;
+    const raw = readRawRecipeConfig(path);
     return raw && typeof raw === "object" && Object.hasOwn(raw, "template")
       ? path
       : undefined;
@@ -232,6 +240,123 @@ function getRecipeCommandTemplate(
   return normalizeRecipeTemplate({ ...envelope, template });
 }
 
+function parseMarkdownScalar(value: string): unknown {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+  if (
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith("[") && trimmed.endsWith("]"))
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed;
+    }
+  }
+  const quoted = trimmed.match(/^(?:"([^"]*)"|'([^']*)')$/);
+  if (quoted) return quoted[1] ?? quoted[2] ?? "";
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  return trimmed;
+}
+
+function parseMarkdownFrontmatterObject(
+  lines: string[],
+): Record<string, unknown> | unknown[] {
+  if (lines.every((line) => /^\s*-\s+/.test(line))) {
+    return lines.map((line) => parseMarkdownScalar(line.replace(/^\s*-\s+/, "")));
+  }
+  const result: Record<string, unknown> = {};
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^\s{2}([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+    if (!match) continue;
+    if (match[2]) {
+      result[match[1]] = parseMarkdownScalar(match[2]);
+      continue;
+    }
+    const nested: string[] = [];
+    while (index + 1 < lines.length && /^\s{4}/.test(lines[index + 1])) {
+      index += 1;
+      nested.push(lines[index].slice(2));
+    }
+    result[match[1]] = parseMarkdownFrontmatterObject(nested);
+  }
+  return result;
+}
+
+function parseMarkdownFrontmatter(value: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = value.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+    if (!match) continue;
+    if (match[2]) {
+      result[match[1]] = parseMarkdownScalar(match[2]);
+      continue;
+    }
+    const nested: string[] = [];
+    while (index + 1 < lines.length && /^\s+/.test(lines[index + 1])) {
+      index += 1;
+      nested.push(lines[index]);
+    }
+    result[match[1]] = parseMarkdownFrontmatterObject(nested);
+  }
+  return result;
+}
+
+function findMarkdownRecipeFence(
+  body: string,
+): { info: string; body: string } | undefined {
+  const pattern = /```([^\n`]*)\n([\s\S]*?)```/g;
+  for (const match of body.matchAll(pattern)) {
+    const info = match[1].trim().toLowerCase();
+    if (
+      info.includes("recipe") ||
+      info.includes("template") ||
+      info.includes("command") ||
+      info.includes("json")
+    ) {
+      return { info, body: match[2].trim() };
+    }
+  }
+  return undefined;
+}
+
+function parseMarkdownRecipeConfig(
+  content: string,
+): Record<string, unknown> | undefined {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end === -1) return undefined;
+  const frontmatter = parseMarkdownFrontmatter(lines.slice(1, end).join("\n"));
+  const fence = findMarkdownRecipeFence(lines.slice(end + 1).join("\n"));
+  if (!fence) return Object.hasOwn(frontmatter, "template") ? frontmatter : undefined;
+  const text = fence.body.trim();
+  if (!text) return undefined;
+  if (
+    fence.info.includes("json") ||
+    fence.info.includes("recipe") ||
+    text.startsWith("{") ||
+    text.startsWith("[") ||
+    text.startsWith('"')
+  ) {
+    try {
+      const parsed = JSON.parse(text) as unknown;
+      if (isRecord(parsed) && Object.hasOwn(parsed, "template"))
+        return { ...frontmatter, ...parsed };
+      return { ...frontmatter, template: parsed };
+    } catch {
+      if (fence.info.includes("json") || fence.info.includes("recipe")) return undefined;
+    }
+  }
+  return { ...frontmatter, template: text };
+}
+
 export function readRawRecipeConfig(
   path: string,
 ): Record<string, unknown> | undefined {
@@ -243,10 +368,9 @@ export function readRawRecipeConfig(
     );
   }
   try {
-    const raw = JSON.parse(readFileSync(path, "utf8")) as Record<
-      string,
-      unknown
-    >;
+    const content = readFileSync(path, "utf8");
+    if (path.endsWith(".md")) return parseMarkdownRecipeConfig(content);
+    const raw = JSON.parse(content) as Record<string, unknown>;
     return raw && typeof raw === "object" ? raw : undefined;
   } catch {
     return undefined;
@@ -254,7 +378,7 @@ export function readRawRecipeConfig(
 }
 
 export function getRecipeIdFromPath(file: string): string {
-  return basename(file, ".json");
+  return basename(file, extname(file));
 }
 
 function readRecipeConfig(value: unknown): TemplateRecipeConfig | undefined {

package/lib/tools.ts

@@ -1089,7 +1089,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         } else if (message.type === "control.kill") {
           result = AsyncRuns.killRun(address.value);
         } else {
-          result = AsyncRuns.sendRunMessage(
+          result = await AsyncRuns.sendRunMessage(
             address.value,
             messageBodyToRunLine(message),
           );
@@ -1131,7 +1131,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
           ActorRooms.writeCommunicationSnapshot(stateDir, runId);
           ActorRooms.appendBranchInboxMessage(stateDir, runId, message.to, message);
         }
-        result = AsyncRuns.sendRunMessage(
+        result = await AsyncRuns.sendRunMessage(
           address.value,
           JSON.stringify(message),
         );
@@ -1143,16 +1143,18 @@ export function createActorMessageToolDefinition<TContext = unknown>(
         if (!stateDir) throw new Error(`${message.to} has no run state directory.`);
         const recipients = getRoomMulticastRecipients(message, runId);
         const roomResult = ActorRooms.appendRoomMessage(stateDir, address.room, message);
-        const multicast = recipients.map((recipient) =>
-          AsyncRuns.sendRunMessage(
-            runId,
-            JSON.stringify({ ...message, to: recipient }),
+        await Promise.all(
+          recipients.map((recipient) =>
+            AsyncRuns.sendRunMessage(
+              runId,
+              JSON.stringify({ ...message, to: recipient }),
+            ),
           ),
         );
         result = {
           ...roomResult,
-          ...(multicast.length > 0
-            ? { multicast: recipients, multicast_count: multicast.length }
+          ...(recipients.length > 0
+            ? { multicast: recipients, multicast_count: recipients.length }
             : {}),
         };
       } else if (address.kind === "tool" && address.value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/recipes/pipeline-room-swarm.json

@@ -1,7 +1,7 @@
 {
   "async": true,
   "args": [
-    "mode:string",
+    "mode:enum(consensus,pipeline,fanout,pool)",
     "mission:string",
     "model:string",
     "thinking:string",