@llblab/pi-actors 0.20.1 → 0.21.0

package/dist/lib/async-runs.js

@@ -3,8 +3,9 @@
  * Zones: async runtime, lifecycle, state files
  * 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, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, 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";
@@ -89,7 +90,8 @@ function assertNoActiveRunState(stateDir) {
     throw new Error(`Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`);
 }
 function resolveRecipeFile(file) {
-    return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
+    return (RecipeReferences.getRecipePath(file, DEFAULT_RECIPE_ROOT) ??
+        RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT));
 }
 function isMutableUsageRecipeFile(file) {
     const userRoot = resolve(DEFAULT_RECIPE_ROOT);
@@ -300,6 +302,7 @@ export function startRun(params, cwd) {
             template: resolved.template,
             values,
             ...(artifacts ? { artifacts } : {}),
+            ...(startParams.control ? { control: startParams.control } : {}),
             ...(startParams.mailbox ? { mailbox: startParams.mailbox } : {}),
             ...(recipeContextRecords && recipeContextRecords.length > 0
                 ? { recipe_context_records: recipeContextRecords }
@@ -507,10 +510,84 @@ export function appendRunOutboxEvent(runOrDir, event) {
         state_dir: stateDir,
     };
 }
-export function sendRunMessage(runOrDir, message) {
-    if (process.platform === "win32") {
-        throw new Error("run actor messages require Unix FIFO support; use WSL/Linux/macOS or a recipe-specific Windows transport.");
+function getRunControlEndpoint(status, stateDir) {
+    const control = status.control;
+    if (control && typeof control === "object" && !Array.isArray(control)) {
+        const record = control;
+        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, message, bytes) {
+    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);
+        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, payload) {
+    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;
+    try {
+        fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+        return writeSync(fd, payload);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function sendRunMessageToNamedPipe(endpoint, payload, send) {
+    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) => {
+            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, message, options = {}) {
     const status = getRunStatus(runOrDir);
     const stateDir = String(status.state_dir);
     const run = String(status.run ?? runOrDir);
@@ -521,52 +598,66 @@ export function sendRunMessage(runOrDir, message) {
         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;
+    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);
-            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)}`);
+        throw new Error(`Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(error)}`);
     }
-    finally {
-        if (fd !== undefined)
-            closeSync(fd);
+}
+export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.platform) {
+    if (runtimePlatform === "win32") {
+        return {
+            args: [
+                "/PID",
+                String(pid),
+                "/T",
+                ...(signal === "SIGKILL" ? ["/F"] : []),
+            ],
+            command: "taskkill",
+            signalTarget: "processTree",
+        };
     }
+    return { signalTarget: "processGroup" };
 }
 function signalOwnedRunProcess(pid, signal) {
+    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/dist/lib/command-templates.js

@@ -74,8 +74,15 @@ function getExecutableName(command) {
         return "";
     return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
 }
+function matchesFlag(arg, flag) {
+    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, flags) {
-    return args.some((arg) => flags.includes(arg));
+    return args.some((arg) => flags.some((flag) => matchesFlag(arg, flag)));
 }
 function hasRiskyPathArg(args) {
     return args.some((arg) => arg === "/" ||

package/dist/lib/observability.d.ts

@@ -37,9 +37,23 @@ 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 {
     from: RunObservedStatus;
@@ -72,6 +86,7 @@ export declare function countRunningSubagents(stateRoot?: string, ownerId?: stri
 export declare function renderSubagentStatus(count: number, frame?: number): string | undefined;
 export declare function renderRunStatus(summary: RunSummary, frame?: number): string | undefined;
 export declare function findRunRetirementCandidates(summary: RunSummary): RunRetirementCandidate[];
+export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
 export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
 export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>): void;
 export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary): RunOutboxEvent[];

package/dist/lib/observability.js

@@ -4,7 +4,7 @@
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
 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.js";
 import * as Paths from "./paths.js";
 const TERMINAL = new Set([
@@ -15,6 +15,7 @@ const TERMINAL = new Set([
     "killed",
 ]);
 const PROC_DESCENDANT_SCAN_TTL_MS = 1000;
+const RUN_STATE_DISCOVERY_MAX_DEPTH = 8;
 const procDescendantScanCache = new Map();
 function toNumber(value) {
     const number = Number(value);
@@ -34,6 +35,29 @@ function getUpdatedAt(status) {
             ? status.createdAt
             : undefined;
 }
+function listRunStateDirs(stateRoot, depth = 0, seen = new Set()) {
+    if (!existsSync(stateRoot) || seen.has(stateRoot))
+        return [];
+    seen.add(stateRoot);
+    let entries;
+    try {
+        entries = readdirSync(stateRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    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) {
     try {
         const status = AsyncRuns.getRunStatus(stateDir);
@@ -90,9 +114,8 @@ export function summarizeRuns(stateRoot = Paths.getRunStateRoot(), ownerId) {
             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) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
         .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -148,7 +171,7 @@ function getRunningRunPidMap(stateRoot, ownerId) {
     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);
@@ -167,9 +190,8 @@ function summarizeRunsWithoutSubagents(stateRoot, ownerId) {
             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) => Boolean(run))
         .filter((run) => ownerId === undefined || run.ownerId === ownerId)
         .sort((a, b) => (b.updatedAt ?? "").localeCompare(a.updatedAt ?? ""));
@@ -260,23 +282,86 @@ export function renderSubagentStatus(count, frame = 0) {
 export function renderRunStatus(summary, frame = 0) {
     return renderSubagentStatus(summary.runningSubagents, frame);
 }
+function isNestedStateDir(parent, child) {
+    const path = relative(parent, child);
+    return Boolean(path) && !path.startsWith("..") && !isAbsolute(path);
+}
 export function findRunRetirementCandidates(summary) {
     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, options) {
+    const results = [];
+    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.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, summary) {
     const transitions = [];
     for (const run of summary.runs) {

package/dist/lib/recipe-discovery.js

@@ -36,15 +36,18 @@ function listRecipeFiles(root) {
         return [];
     return readdirSync(root, { withFileTypes: true })
         .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(file, config) {
     if (!config)
         return [`Invalid recipe: ${file}`];
-    return CommandTemplates.getCommandTemplateWarnings(typeof config.template === "string" ? config.template : { template: config.template }).map((warning) => `Recipe ${file}: ${warning}`);
+    const commandTemplateConfig = typeof config.template === "object" && config.template !== null
+        ? config.template
+        : config;
+    return CommandTemplates.getCommandTemplateWarnings(commandTemplateConfig).map((warning) => `Recipe ${file}: ${warning}`);
 }
 function readDiscoveredRecipe(root, file, priority, defaultTool = false, mutableUsage = false) {
     const id = RecipeReferences.getRecipeIdFromPath(file);
@@ -135,13 +138,18 @@ export function discoverRecipeSources(sources) {
     const active = new Map();
     const diagnostics = getRecipeRootDiagnostics(sources);
     for (const [id, bucket] of byId) {
-        bucket.sort((a, b) => a.priority - b.priority || a.path.localeCompare(b.path));
+        bucket.sort((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))
+        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`);
         if (winner.disabled)