@llblab/pi-actors 0.20.2 → 0.21.0

package/scripts/coordinator.mjs

@@ -2,6 +2,7 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { createConnection } from "node:net";
 
 function arg(name, fallback = "") {
   const prefix = `--${name}=`;
@@ -102,10 +103,34 @@ async function acquireBranchInboxLock(runId, branchName) {
   return acquireStateLock(`${runStateDir(runId)}/branches/${branchName}`, ".inbox.lock", `Branch inbox ${branchName}`);
 }
 
+async function readLockerControl(locker) {
+  const controlJson = `${locker.stateDir}/control.json`;
+  await waitForPath(controlJson);
+  return JSON.parse(await readFile(controlJson, "utf8"));
+}
+
+function writeNamedPipeLine(path, line) {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(path);
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      if (error) reject(error);
+      else resolve();
+    };
+    socket.on("error", finish);
+    socket.on("connect", () => socket.end(line, () => finish()));
+  });
+}
+
 async function writeLockerMessage(locker, message) {
   if (!locker) return;
-  await waitForPath(locker.controlPath);
-  await writeFile(locker.controlPath, `${JSON.stringify(message)}\n`, { flag: "a" });
+  const control = locker.control ?? await readLockerControl(locker);
+  locker.control = control;
+  const line = `${JSON.stringify(message)}\n`;
+  if (control.type === "named-pipe") await writeNamedPipeLine(control.path, line);
+  else await writeFile(control.path, line, { flag: "a" });
   await sleep(50);
 }
 
@@ -125,8 +150,8 @@ async function startLocker(config) {
   });
   child.stdout.on("data", (chunk) => process.stdout.write(`[locker] ${chunk}`));
   child.stderr.on("data", (chunk) => process.stderr.write(`[locker] ${chunk}`));
-  const locker = { child, controlPath: `${lockerStateDir}/control.fifo`, stateDir: lockerStateDir };
-  await waitForPath(locker.controlPath);
+  const locker = { child, stateDir: lockerStateDir };
+  locker.control = await readLockerControl(locker);
   await writeLockerMessage(locker, {
     type: "lock.enqueue",
     body: { id: "coordinator-artifact", task: "Own final artifact synthesis", resources: [config.artifactPath || "artifact"] },
@@ -230,11 +255,23 @@ async function writeInboxMessages(inboxPath, messages) {
   await writeFile(inboxPath, messages.map((message) => JSON.stringify(message)).join("\n") + "\n", "utf8");
 }
 
-async function claimQueuedInboxMessages(runId, branchName) {
+async function mutateBranchInbox(runId, branchName, mutate, fallback) {
   const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
   const releaseLock = await acquireBranchInboxLock(runId, branchName);
   try {
     const messages = await readInboxLines(inboxPath);
+    const result = mutate(messages);
+    if (result.messages) await writeInboxMessages(inboxPath, result.messages);
+    return result.value;
+  } catch {
+    return fallback;
+  } finally {
+    await releaseLock();
+  }
+}
+
+async function claimQueuedInboxMessages(runId, branchName) {
+  return mutateBranchInbox(runId, branchName, (messages) => {
     const claimedAt = new Date().toISOString();
     const queuedMessages = [];
     const updated = messages.map((msg, index) => {
@@ -248,31 +285,22 @@ async function claimQueuedInboxMessages(runId, branchName) {
       queuedMessages.push(claimed);
       return claimed;
     });
-    if (queuedMessages.length > 0) await writeInboxMessages(inboxPath, updated);
-    return queuedMessages;
-  } catch {
-    return [];
-  } finally {
-    await releaseLock();
-  }
+    return {
+      messages: queuedMessages.length > 0 ? updated : undefined,
+      value: queuedMessages,
+    };
+  }, []);
 }
 
 async function updateInboxMessagesStatus(runId, branchName, ids, status) {
-  const inboxPath = `${runStateDir(runId)}/branches/${branchName}/inbox.jsonl`;
-  const releaseLock = await acquireBranchInboxLock(runId, branchName);
-  try {
-    const messages = await readInboxLines(inboxPath);
+  await mutateBranchInbox(runId, branchName, (messages) => {
     const idSet = new Set(ids);
     const updated = messages.map((msg) => {
       if (!msg.id || !idSet.has(msg.id)) return msg;
       return { ...msg, [`${status}_at`]: new Date().toISOString(), status };
     });
-    await writeInboxMessages(inboxPath, updated);
-  } catch {
-    // Best-effort write
-  } finally {
-    await releaseLock();
-  }
+    return { messages: updated, value: undefined };
+  });
 }
 
 async function executeParticipantPrompt(role, basePrompt, config) {
@@ -421,6 +449,13 @@ async function runPool(config, locker) {
   }));
 }
 
+const coordinatorModes = {
+  consensus: runConsensus,
+  fanout: runFanout,
+  pipeline: runPipeline,
+  pool: runPool,
+};
+
 async function readJsonFile(path) {
   try {
     return JSON.parse(await readFile(path, "utf8"));
@@ -464,16 +499,9 @@ const failures = [];
 const locker = await startLocker(config);
 
 try {
-  if (config.mode === "pipeline") {
-    await runPipeline(config, locker);
-  } else if (config.mode === "fanout") {
-    await runFanout(config, locker);
-  } else if (config.mode === "pool") {
-    await runPool(config, locker);
-  } else {
-    // default: consensus / swarm
-    await runConsensus(config, locker);
-  }
+  const runMode = coordinatorModes[config.mode];
+  if (!runMode) throw new Error(`Unknown coordinator mode: ${config.mode}`);
+  await runMode(config, locker);
   await synthesize(config, locker);
 } catch (globalError) {
   failures.push(`Global coordinator error: ${globalError.message}`);

package/scripts/locker.mjs

@@ -8,7 +8,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
+import { createServer } from "node:net";
 import readline from "node:readline";
 
 function parseArgs(argv) {
@@ -49,6 +51,17 @@ function writeJson(path, value) {
   mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
+function getControlEndpoint() {
+  if (process.platform !== "win32") return { path: controlPath, type: "fifo" };
+  const hash = createHash("sha256").update(resolve(stateDir)).digest("hex").slice(0, 20);
+  return { path: `\\\\.\\pipe\\pi-actors-locker-${hash}`, type: "named-pipe" };
+}
+function writeControlEndpoint(endpoint) {
+  writeJson(join(stateDir, "control.json"), endpoint);
+  const runPath = join(stateDir, "run.json");
+  const run = readJson(runPath, undefined);
+  if (run && typeof run === "object") writeJson(runPath, { ...run, control: endpoint });
+}
 function journal(event, data = {}) {
   appendFileSync(
     journalPath,
@@ -244,30 +257,55 @@ if (mode === "snapshot") {
   process.exit(0);
 }
 
-if (!existsSync(controlPath)) {
-  const result = spawnSync("mkfifo", [controlPath]);
-  if (result.status !== 0)
-    throw new Error(`mkfifo failed: ${result.stderr?.toString?.() ?? ""}`);
+function handleLine(line) {
+  const message = normalizeMessage(line);
+  if (!message) return;
+  try {
+    handle(message);
+  } catch (error) {
+    const text = error instanceof Error ? error.message : String(error);
+    journal("lock.error", { error: text });
+    outbox("lock.error", text, { error: text }, "error");
+  }
 }
-writeJson(queuePath, readJson(queuePath, { items: [] }));
-writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
-journal("lock.started", { leaseMs });
-outbox("lock.started", "Locker ready", { leaseMs });
 
-while (true) {
-  const stream = await import("node:fs").then((fs) =>
-    fs.createReadStream(controlPath, { encoding: "utf8" }),
-  );
-  const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-  for await (const line of rl) {
-    const message = normalizeMessage(line);
-    if (!message) continue;
-    try {
-      handle(message);
-    } catch (error) {
-      const text = error instanceof Error ? error.message : String(error);
-      journal("lock.error", { error: text });
-      outbox("lock.error", text, { error: text }, "error");
-    }
+async function serveFifo(endpoint) {
+  if (!existsSync(endpoint.path)) {
+    const result = spawnSync("mkfifo", [endpoint.path]);
+    if (result.status !== 0)
+      throw new Error(`mkfifo failed: ${result.stderr?.toString?.() ?? ""}`);
+  }
+  writeControlEndpoint(endpoint);
+  while (true) {
+    const stream = await import("node:fs").then((fs) =>
+      fs.createReadStream(endpoint.path, { encoding: "utf8" }),
+    );
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) handleLine(line);
   }
 }
+
+async function serveNamedPipe(endpoint) {
+  rmSync(endpoint.path, { force: true });
+  const server = createServer((socket) => {
+    const rl = readline.createInterface({ input: socket, crlfDelay: Infinity });
+    rl.on("line", handleLine);
+  });
+  await new Promise((resolveReady, rejectReady) => {
+    server.once("error", rejectReady);
+    server.listen(endpoint.path, () => {
+      server.off("error", rejectReady);
+      writeControlEndpoint(endpoint);
+      resolveReady();
+    });
+  });
+  await new Promise(() => {});
+}
+
+const endpoint = getControlEndpoint();
+writeJson(queuePath, readJson(queuePath, { items: [] }));
+writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
+journal("lock.started", { leaseMs, control: endpoint.type });
+outbox("lock.started", "Locker ready", { leaseMs, control: endpoint.type });
+if (endpoint.type === "named-pipe") await serveNamedPipe(endpoint);
+else await serveFifo(endpoint);

package/scripts/validate-recipe.mjs

@@ -26,7 +26,7 @@ function usage() {
   console.error(`Usage:
   validate-recipe.mjs <recipe-file-or-dir> [--all]
 
-Validates one template recipe file, or all *.json files in a directory when --all is set.`);
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set.`);
 }
 
 function expandPath(value) {
@@ -56,7 +56,7 @@ function recipeFiles(target, all) {
     throw new Error(`Recipe path is not a file or directory: ${target}`);
   if (!all) throw new Error("Directory validation requires --all.");
   return readdirSync(target)
-    .filter((file) => file.endsWith(".json"))
+    .filter((file) => file.endsWith(".json") || file.endsWith(".md"))
     .sort((a, b) => a.localeCompare(b))
     .map((file) => resolve(target, file));
 }

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.20.2
+  version: 0.21.0
 ---
 
 # Actors (pi-actors)
@@ -228,11 +228,11 @@ Priority for same-id recipes:
 1. No recipe: no capability.
 2. Packaged pi-actors recipe: standard-library declarative actor component.
 3. Explicit ad hoc user recipe file outside `~/.pi/agent/recipes`.
-4. User recipe in `~/.pi/agent/recipes/*.json`: highest-priority operator tool surface.
+4. User recipe in `~/.pi/agent/recipes/*.json` or `*.md`: highest-priority operator tool surface.
 
-Only matching filename ids compete. Higher priority shadows lower priority. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
+Only matching filename ids compete. Higher priority shadows lower priority; within one priority layer, same-id JSON shadows Markdown. An invalid or `disabled: true` higher-priority recipe blocks fallback so the agent does not silently run standard-library behavior when a user override is broken or intentionally disabled.
 
-Muscle-memory lens: `~/.pi/agent/recipes/*.json` is the agent's capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Agents grow this memory either by calling `register_tool`, which writes recipe files there under the hood, or by deliberately editing those recipe files. Treat this directory like `MEMORY.md` for executable habits: useful local patterns belong there; packaged recipes elsewhere are reusable components, not tools.
+Muscle-memory lens: `~/.pi/agent/recipes/*.json` and `*.md` are the agent's capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Agents grow this memory either by calling `register_tool`, which writes recipe files there under the hood, or by deliberately editing those recipe files. Treat this directory like `MEMORY.md` for executable habits: useful local patterns belong there; packaged recipes elsewhere are reusable components, not tools.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
@@ -240,7 +240,7 @@ Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memo
 
 ## Registered Tools
 
-`register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`.
+`register_tool` persists trusted local capabilities as recipe files in `~/.pi/agent/recipes/*.json`; hand-authored Markdown recipes in the same directory are also discovered as tools.
 
 Use it when a command/template/recipe should become durable agent muscle memory. Prefer typed args or placeholder-derived args; use `update=true` for replacement and `template=null` or `template=""` for deletion. `register_tool` should create/update/delete recipe files in the user recipe root; direct file editing is allowed but is the lower-level path.
 
@@ -250,7 +250,7 @@ Tool templates may be:
 - A file-backed recipe name/path.
 - A complete recipe body, optionally `async: true`.
 
-The user recipe root is the default tool set by location; packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
+The user recipe root is the default tool set by location. It accepts canonical JSON recipes and literate Markdown recipes with frontmatter plus fenced `template`/`json recipe` blocks; same-id JSON shadows Markdown in the same priority layer. Packaged recipes are lower-priority standard-library components and are not tools unless copied or registered into the agent recipe root. Ideal runtime behavior is reactive: create/edit/delete recipe files, validate them, then connect valid tools or surface diagnostics without requiring agents to hand-maintain a separate registry.
 
 ## Recipe Navigator
 
@@ -258,8 +258,8 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 
 ### Coordination and Services
 
-- [`coordinator-locker`](../../recipes/coordinator-locker.json): queue + acquire/renew/release lease locks + journaled coordinator messages.
-- [`locker`](../../recipes/locker.json): modular queue + acquire/renew/release lease locks + journaled locker messages.
+- [`coordinator-locker`](../../recipes/coordinator-locker.json): queue + acquire/renew/release lease locks + journaled coordinator messages + platform-adapted control metadata.
+- [`locker`](../../recipes/locker.json): modular queue + acquire/renew/release lease locks + journaled locker messages + platform-adapted control metadata.
 - [`utility-coordinator-lock-snapshot`](../../recipes/utility-coordinator-lock-snapshot.json): one-shot JSON snapshot of a coordinator-locker state directory.
 - [`music-player`](../../recipes/music-player.json): background local/URL/directory/playlist playback actor controlled by messages.
 
@@ -280,7 +280,7 @@ Use packaged recipes by name with `spawn file=<name>` for async actors, or regis
 - [`pipeline-docs-maintenance`](../../recipes/pipeline-docs-maintenance.json): docs index/review/planning → maintenance artifact.
 - Artifacts: [`pipeline-artifact-report`](../../recipes/pipeline-artifact-report.json), [`pipeline-artifact-write`](../../recipes/pipeline-artifact-write.json), [`pipeline-artifact-bundle`](../../recipes/pipeline-artifact-bundle.json).
 - Review gates: [`pipeline-quorum-review`](../../recipes/pipeline-quorum-review.json), [`pipeline-review-readiness`](../../recipes/pipeline-review-readiness.json).
-- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
+- Task-first workflows: [`pipeline-architect-coordinator`](../../recipes/pipeline-architect-coordinator.json), [`pipeline-research-synthesis`](../../recipes/pipeline-research-synthesis.json), [`pipeline-development-tasking`](../../recipes/pipeline-development-tasking.json), [`pipeline-checkpoint-continuation`](../../recipes/pipeline-checkpoint-continuation.json), [`pipeline-media-library`](../../recipes/pipeline-media-library.json), [`pipeline-room-swarm`](../../recipes/pipeline-room-swarm.json). For room swarms, choose `mode` from `consensus`, `pipeline`, `fanout`, or `pool`; prefer `roles_path` for custom role JSON and keep role `name` ASCII-safe for branch addresses. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 
@@ -339,6 +339,7 @@ Keep the split clean: methodology chooses coordination shape; pi-actors supplies
 - Sending domain messages without checking `mailbox`.
 - Expecting current room messages to wake prompt-only subagents; use direct branch messages or a runner protocol for initiating work.
 - Reading only stdout and missing actor messages/artifacts.
+- Assuming every packaged message-controlled script is native-Windows-ready; core run control is platform-adapted, but Unix-tool scripts must be migrated recipe by recipe.
 - Baking local absolute paths into published docs or reusable recipes.
 - Creating recipes that perform external side effects without explicit operator gates.
 - Letting project insights live only in chat instead of updating BACKLOG/CHANGELOG/docs and, when agent behavior changes, the packaged skill or prompt guidance.

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.20.2
+  version: 0.21.0
 ---
 
 # Swarm