@llblab/pi-actors 0.20.2 → 0.21.0

package/docs/template-recipes.md

@@ -1,10 +1,10 @@
 # Template Recipe Standard
 
-Template recipes are saved JSON definitions around the synchronous [Command Template Standard](./command-templates.md).
+Template recipes are saved definitions around the synchronous [Command Template Standard](./command-templates.md). JSON remains the canonical precise format; Markdown is a literate authoring format that compiles into the same recipe model.
 
 **Meta-contract:** a recipe stores a command-template graph plus defaults and run mode. It does not create a second execution language.
 
-**Scope:** reusable JSON shape, recipe naming, file-backed recipes, co-located recipes, recipe-layer imports/references, call-time values, foreground execution, and the `async: true` handoff to the [Async Run Standard](./async-runs.md).
+**Scope:** reusable JSON/Markdown shape, recipe naming, file-backed recipes, co-located recipes, recipe-layer imports/references, call-time values, foreground execution, and the `async: true` handoff to the [Async Run Standard](./async-runs.md).
 
 ---
 
@@ -27,7 +27,7 @@ Packaged recipes are the pi-actors recipe standard library: declarative actor co
 
 Template-recipe standard owns:
 
-- Saved JSON definitions around one command-template graph.
+- Saved JSON definitions around one command-template graph, plus Markdown-authored recipes that compile to that shape.
 - File-backed and co-located recipe shapes.
 - Recipe identity through file-backed filename or co-located tool id.
 - Recipe defaults, values, imports, import references, and import-node expansion.
@@ -67,6 +67,33 @@ Async recipe:
 
 A file-backed recipe's id comes from its filename, not a JSON `name` field. Legacy files may still contain `name`, but loaders ignore it for identity. `template` is the command-template tree. `async: true` selects detached run mode when the recipe is invoked through a registered tool.
 
+## Markdown Authoring
+
+Markdown recipes use `.md` files with YAML-like frontmatter for recipe metadata and one fenced executable block for the recipe/template body. Runtime behavior comes only from frontmatter plus the fenced block; surrounding prose is advisory for humans and future recipe-context use.
+
+````markdown
+---
+description: Literate docs check
+args:
+  - scope:path
+defaults:
+  scope: docs
+mailbox:
+  accepts:
+    - control.stop
+---
+
+Human notes can explain intent, examples, or review guidance.
+
+```template
+npm run check -- {scope}
+```
+````
+
+Fenced blocks marked `template`, `command-template`, `json`, or `recipe` are executable. A `template` fence stores its text as the command-template string. A JSON fence can contain either a full recipe object with `template` or a raw command-template value. Frontmatter supports the recipe metadata used by JSON recipes, including `args`, `defaults`, `imports`, `mailbox`, `artifacts`, `async`, and command-template flags.
+
+JSON remains the source-of-truth format for precise machine editing. If `<id>.json` and `<id>.md` exist in the same discovery priority layer, `<id>.json` wins and the Markdown recipe is reported as shadowed.
+
 ## Discovery Priority
 
 Recipe priority only matters when two discovered recipes have the same filename id. The conceptual ladder from lowest to highest priority is:
@@ -74,11 +101,11 @@ Recipe priority only matters when two discovered recipes have the same filename
 1. No recipe for that id.
 2. Packaged pi-actors recipe components, acting as the standard library.
 3. Explicitly referenced ad hoc user recipe files located outside `~/.pi/agent/recipes`.
-4. User recipe files under `~/.pi/agent/recipes/*.json`.
+4. User recipe files under `~/.pi/agent/recipes/*.json` or `*.md`.
 
 The high-priority user recipe directory is also the default tool set: recipes placed there are agent tools by location. This preserves the old advantage of a tool-only registry because listing `~/.pi/agent/recipes` shows the operator-managed tool surface. Packaged and ad hoc recipes are recipe components by default; they become tools only when copied or registered into the agent recipe root.
 
-Higher-priority files shadow lower-priority files with the same basename. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
+Higher-priority files shadow lower-priority files with the same basename. Within one priority layer, same-id JSON shadows Markdown because JSON is the canonical precise format. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
 
 ## Usage Metadata
 
@@ -203,19 +230,22 @@ Reusable local recipes live in:
 
 ```text
 ~/.pi/agent/recipes/*.json
+~/.pi/agent/recipes/*.md
 ```
 
 Bare recipe names resolve under that directory, so `file: "review-docs"` loads:
 
 ```text
 ~/.pi/agent/recipes/review-docs.json
+# or, when no same-id JSON file exists:
+~/.pi/agent/recipes/review-docs.md
 ```
 
 Call-time params override file params. `values` are merged with file values; call-time values win. If a run id is omitted for an explicit async start, the file basename becomes the default run id.
 
 ## Registered Recipe Tools
 
-A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` are tools by location; packaged/ad hoc recipes are components unless copied or registered into that user recipe root:
+A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` or `*.md` are tools by location; packaged/ad hoc recipes are components unless copied or registered into that user recipe root:
 
 ```json
 {
@@ -312,6 +342,6 @@ Nested object keys are dot-separated. Import references are resolved before norm
 
 ## Recipe Shape
 
-Use the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` before relying on recipe launchers.
+Use the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` or `*.md` before relying on recipe launchers.
 
 If a proposed recipe needs a scheduler, queue daemon, `goto`, or custom workflow syntax, stop. Keep the recipe as saved command-template JSON and put policy in the registered tool, script, or caller.

package/docs/tool-registry.md

@@ -1,6 +1,6 @@
 # Tool Registry
 
-`pi-actors` stores persistent agent tools as recipe files under `~/.pi/agent/recipes/*.json` and registers the active tool set automatically on session start.
+`pi-actors` stores persistent agent tools as recipe files under `~/.pi/agent/recipes/*.json` or `*.md` and registers the active tool set automatically on session start.
 
 This document is the local adaptation of the portable [Command Template Standard](./command-templates.md) and the recipe-file runtime described in [Template Recipe Standard](./template-recipes.md).
 
@@ -8,11 +8,12 @@ This document is the local adaptation of the portable [Command Template Standard
 
 The registry source is location-discovered recipes, not a live tool-only JSON file and not a recipe-owned boolean:
 
-- `~/.pi/agent/recipes/*.json` is the highest-priority user recipe root and the operator-managed tool set.
+- `~/.pi/agent/recipes/*.json` and `*.md` are the highest-priority user recipe root and the operator-managed tool set.
 - Recipes in that root are tools by location.
 - Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
 - Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
-- Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` has id/tool name `docs_review`.
+- Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` and `docs_review.md` both have id/tool name `docs_review`.
+- Same-id JSON shadows Markdown in the same priority layer.
 
 
 Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. `inspect target=recipes view=summary verbose=true` includes usage metadata and operator-gated cleanup recommendations for invalid, shadowed, disabled, component-only, unused, or overriding recipes. Recommended actions stay explicit: keep as a tool/component, enable, merge, fix, delete, or archive. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.

package/index.ts

@@ -13,6 +13,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import * as ActorInspectorTui from "./lib/actor-inspector-tui.ts";
+import * as AsyncRuns from "./lib/async-runs.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Observability from "./lib/observability.ts";
 import * as Paths from "./lib/paths.ts";
@@ -47,6 +48,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   const runDirWatchers = new Map<string, FSWatcher>();
   const observedRuns = new Map<string, Observability.RunObservedStatus>();
   const observedRunEventLines = new Map<string, number>();
+  const retirementAttempts = new Set<string>();
   let runStatusFrame = 0;
   let communicationWidgetVisible = false;
   let actorInspectorRows = 12;
@@ -61,6 +63,17 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   let recipeWatcherFailureNotified = false;
   const getRunOwnerId = (ctx: ExtensionContext): string =>
     ctx.sessionManager.getSessionId();
+  const retireCandidateRuns = (
+    ctx: ExtensionContext,
+    summary: Observability.RunSummary,
+  ): void => {
+    void Observability.executeRunRetirements(summary, {
+      attempted: retirementAttempts,
+      cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
+      notify: (message, level) => ctx.ui.notify(message, level),
+      sendStop: (candidate) => AsyncRuns.sendRunMessage(candidate.stateDir, "stop"),
+    });
+  };
   const updateRunUi = (ctx: ExtensionContext, notify = false): void => {
     const ownerId = getRunOwnerId(ctx);
     const summary = Observability.summarizeRuns(undefined, ownerId);
@@ -139,6 +152,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       summary,
     );
     if (!notify) return;
+    retireCandidateRuns(ctx, summary);
     for (const transition of transitions) {
       if (!Observability.shouldNotifyRunTransition(transition)) continue;
       const text = Observability.formatRunTransitionMessage(transition);

package/lib/actor-rooms.ts

@@ -13,6 +13,7 @@ import type { ActorMessage } from "./actor-messages.ts";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
+const DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED = 2000;
 const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
 
 export interface RoomMember {
@@ -386,6 +387,26 @@ export function readBranchInboxMessages(
   }
 }
 
+export function getBranchInboxTerminalRetainLimit(): number {
+  const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
+  return Number.isInteger(value) && value >= 0
+    ? value
+    : DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED;
+}
+
+function compactBranchInboxMessages<T extends { status?: string }>(
+  messages: T[],
+): T[] {
+  const retainTerminal = getBranchInboxTerminalRetainLimit();
+  const active = messages.filter(
+    (message) => message.status !== "handled" && message.status !== "failed",
+  );
+  const terminal = messages.filter(
+    (message) => message.status === "handled" || message.status === "failed",
+  );
+  return [...terminal.slice(-retainTerminal), ...active];
+}
+
 export function appendBranchInboxMessage(
   stateDir: string,
   run: string,
@@ -428,7 +449,8 @@ export function updateBranchInboxMessageStatus(
       return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
     });
     if (!changed) return false;
-    fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+    const compacted = compactBranchInboxMessages(updated);
+    fs.writeFileSync(file, `${compacted.map((message) => JSON.stringify(message)).join("\n")}\n`);
     return true;
   } finally {
     releaseLock();

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 {