@llblab/pi-actors 0.20.1 → 0.21.0

package/lib/async-runs.ts

@@ -4,7 +4,7 @@
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
 
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import {
   closeSync,
   constants,
@@ -19,6 +19,7 @@ import {
   writeFileSync,
   writeSync,
 } from "node:fs";
+import { createConnection } from "node:net";
 import { platform } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -37,8 +38,14 @@ const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 
 export type AsyncRunLaunchSource = "spawn" | "tool";
 
+export interface AsyncRunControlEndpoint {
+  path: string;
+  type: "fifo" | "named-pipe";
+}
+
 export interface AsyncRunStartParams {
   async?: boolean;
+  control?: AsyncRunControlEndpoint;
   file?: string;
   launch_source?: AsyncRunLaunchSource;
   name?: string;
@@ -112,6 +119,7 @@ export interface AsyncRunMeta {
   template: CommandTemplateValue;
   values: Record<string, unknown>;
   artifacts?: Record<string, string>;
+  control?: AsyncRunControlEndpoint;
   mailbox?: RecipeReferences.TemplateRecipeMailbox;
   recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
   retire_when?: "children_terminal";
@@ -207,7 +215,10 @@ function assertNoActiveRunState(stateDir: string): void {
 }
 
 function resolveRecipeFile(file: string): string {
-  return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
+  return (
+    RecipeReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
+    RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT)
+  );
 }
 
 function isMutableUsageRecipeFile(file: string): boolean {
@@ -446,6 +457,7 @@ export function startRun(
     template: resolved.template,
     values,
     ...(artifacts ? { artifacts } : {}),
+    ...(startParams.control ? { control: startParams.control } : {}),
     ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
     ...(recipeContextRecords && recipeContextRecords.length > 0
       ? { recipe_context_records: recipeContextRecords }
@@ -700,15 +712,115 @@ export function appendRunOutboxEvent(
   };
 }
 
-export function sendRunMessage(
-  runOrDir: string,
+export interface SendRunMessageOptions {
+  namedPipeSend?: (path: string, payload: string) => Promise<number>;
+  platform?: NodeJS.Platform;
+}
+
+function getRunControlEndpoint(
+  status: Record<string, unknown>,
+  stateDir: string,
+): AsyncRunControlEndpoint {
+  const control = status.control;
+  if (control && typeof control === "object" && !Array.isArray(control)) {
+    const record = control as Record<string, unknown>;
+    if (
+      (record.type === "fifo" || record.type === "named-pipe") &&
+      typeof record.path === "string" &&
+      record.path.trim()
+    ) {
+      return { path: record.path, type: record.type };
+    }
+  }
+  return { path: join(stateDir, "control.fifo"), type: "fifo" };
+}
+
+function writeRunMessageReceipt(
+  stateDir: string,
   message: string,
-): Record<string, unknown> {
-  if (process.platform === "win32") {
-    throw new Error(
-      "run actor messages require Unix FIFO support; use WSL/Linux/macOS or a recipe-specific Windows transport.",
+  bytes: number,
+): void {
+  const trimmedMessage = message.trim().toLowerCase();
+  const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
+    trimmedMessage,
+  );
+  const ts = new Date().toISOString();
+  writeFileSync(
+    join(stateDir, "events.jsonl"),
+    `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`,
+    { flag: "a" },
+  );
+  try {
+    const envelope = JSON.parse(message) as Record<string, unknown>;
+    writeFileSync(
+      join(stateDir, "inbox.jsonl"),
+      `${JSON.stringify({ ...envelope, received_at: ts })}\n`,
+      { flag: "a" },
     );
+  } catch {
+    // Plain control lines are already represented in events.jsonl.
+  }
+  if (terminalMessage) {
+    markTerminalHandled(stateDir, {
+      event: "run.message",
+      message: trimmedMessage,
+    });
+  }
+}
+
+function sendRunMessageToFifo(
+  endpoint: AsyncRunControlEndpoint,
+  payload: string,
+): number {
+  if (!existsSync(endpoint.path))
+    throw new Error(`Run control FIFO not found: ${endpoint.path}`);
+  const stat = statSync(endpoint.path);
+  if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+    throw new Error(`Run control endpoint is not a FIFO: ${endpoint.path}`);
   }
+  let fd: number | undefined;
+  try {
+    fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+    return writeSync(fd, payload);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function sendRunMessageToNamedPipe(
+  endpoint: AsyncRunControlEndpoint,
+  payload: string,
+  send?: (path: string, payload: string) => Promise<number>,
+): Promise<number> {
+  if (send) return send(endpoint.path, payload);
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(endpoint.path);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(new Error("named pipe connection timed out"));
+    }, 5000);
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve(Buffer.byteLength(payload));
+    };
+    socket.on("error", finish);
+    socket.on("connect", () => {
+      socket.end(payload, () => finish());
+    });
+  });
+}
+
+export async function sendRunMessage(
+  runOrDir: string,
+  message: string,
+  options: SendRunMessageOptions = {},
+): Promise<Record<string, unknown>> {
   const status = getRunStatus(runOrDir);
   const stateDir = String(status.state_dir);
   const run = String(status.run ?? runOrDir);
@@ -718,64 +830,90 @@ export function sendRunMessage(
   if (!pid || !isAlive(pid)) throw new Error(`Run pid is not alive: ${run}`);
   if (!pidMatchesRun(pid, String(status.cwd), stateDir))
     throw new Error(`Run pid owner mismatch: ${run}`);
-  const controlPath = join(stateDir, "control.fifo");
-  if (!existsSync(controlPath))
-    throw new Error(`Run control FIFO not found: ${controlPath}`);
-  const stat = statSync(controlPath);
-  if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
-    throw new Error(`Run control endpoint is not a FIFO: ${controlPath}`);
-  }
+  const endpoint = getRunControlEndpoint(status, stateDir);
   const payload = message.endsWith("\n") ? message : `${message}\n`;
-  let fd: number | undefined;
+  const runtimePlatform = options.platform ?? process.platform;
   try {
-    fd = openSync(controlPath, constants.O_WRONLY | constants.O_NONBLOCK);
-    const bytes = writeSync(fd, payload);
-    const trimmedMessage = message.trim().toLowerCase();
-    const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
-      trimmedMessage,
-    );
-    const ts = new Date().toISOString();
-    writeFileSync(
-      join(stateDir, "events.jsonl"),
-      `${JSON.stringify({ bytes, event: "run.message", terminal: terminalMessage || undefined, ts })}\n`,
-      { flag: "a" },
-    );
-    try {
-      const envelope = JSON.parse(message) as Record<string, unknown>;
-      writeFileSync(
-        join(stateDir, "inbox.jsonl"),
-        `${JSON.stringify({ ...envelope, received_at: ts })}\n`,
-        { flag: "a" },
-      );
-    } catch {
-      // Plain control lines are already represented in events.jsonl.
-    }
-    if (terminalMessage) {
-      markTerminalHandled(stateDir, {
-        event: "run.message",
-        message: trimmedMessage,
-      });
+    if (endpoint.type === "fifo") {
+      if (runtimePlatform === "win32") {
+        throw new Error(
+          "run actor messages on native Windows require a named-pipe control endpoint; this recipe still exposes Unix FIFO control.",
+        );
+      }
+      const bytes = sendRunMessageToFifo(endpoint, payload);
+      writeRunMessageReceipt(stateDir, message, bytes);
+      return {
+        bytes,
+        control: "control.fifo",
+        control_path: endpoint.path,
+        control_type: endpoint.type,
+        run,
+        sent: true,
+        state_dir: stateDir,
+      };
     }
+    const bytes = await sendRunMessageToNamedPipe(
+      endpoint,
+      payload,
+      options.namedPipeSend,
+    );
+    writeRunMessageReceipt(stateDir, message, bytes);
     return {
       bytes,
-      control: "control.fifo",
+      control: endpoint.path,
+      control_path: endpoint.path,
+      control_type: endpoint.type,
       run,
       sent: true,
       state_dir: stateDir,
     };
   } catch (error) {
     throw new Error(
-      `Run control FIFO is not ready: ${controlPath}: ${error instanceof Error ? error.message : String(error)}`,
+      `Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(error)}`,
     );
-  } finally {
-    if (fd !== undefined) closeSync(fd);
   }
 }
 
+export interface RunProcessSignalPlan {
+  args?: string[];
+  command?: string;
+  signalTarget: "processGroup" | "process" | "processTree";
+}
+
+export function getRunProcessSignalPlan(
+  pid: number,
+  signal: NodeJS.Signals,
+  runtimePlatform: NodeJS.Platform = process.platform,
+): RunProcessSignalPlan {
+  if (runtimePlatform === "win32") {
+    return {
+      args: [
+        "/PID",
+        String(pid),
+        "/T",
+        ...(signal === "SIGKILL" ? ["/F"] : []),
+      ],
+      command: "taskkill",
+      signalTarget: "processTree",
+    };
+  }
+  return { signalTarget: "processGroup" };
+}
+
 function signalOwnedRunProcess(
   pid: number,
   signal: NodeJS.Signals,
-): { signalTarget: "processGroup" | "process" } {
+): RunProcessSignalPlan {
+  const plan = getRunProcessSignalPlan(pid, signal);
+  if (plan.command && plan.args) {
+    const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
+    if (result.status !== 0) {
+      throw new Error(
+        result.stderr?.trim() || result.stdout?.trim() || `${plan.command} failed`,
+      );
+    }
+    return plan;
+  }
   try {
     process.kill(-pid, signal);
     return { signalTarget: "processGroup" };

package/lib/command-templates.ts

@@ -157,8 +157,15 @@ function getExecutableName(command: string | undefined): string {
   return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
 }
 
+function matchesFlag(arg: string, flag: string): boolean {
+  if (arg === flag) return true;
+  if (/^-[A-Za-z]$/.test(flag) && /^-[A-Za-z]+$/.test(arg))
+    return arg.slice(1).includes(flag.slice(1));
+  return false;
+}
+
 function hasAnyFlag(args: string[], flags: string[]): boolean {
-  return args.some((arg) => flags.includes(arg));
+  return args.some((arg) => flags.some((flag) => matchesFlag(arg, flag)));
 }
 
 function hasRiskyPathArg(args: string[]): boolean {

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`,