@llblab/pi-actors 0.22.5 → 0.23.0

package/scripts/async-runner.mjs

@@ -64,22 +64,27 @@ function event(name, data = {}) {
     `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
   );
 }
+
 function quoteCommandDetailPart(value) {
   if (value === "") return "''";
   if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
+
 function formatCommandDetail(command, args) {
   return [command, ...args].map(quoteCommandDetailPart).join(" ");
 }
+
 function summarizeCommandDetail(commandDetail) {
   return commandDetail.length > 160
     ? `${commandDetail.slice(0, 157)}...`
     : commandDetail;
 }
+
 function getCommandDoneDelivery(result) {
   return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
 }
+
 function outbox(name, summary, data = {}, delivery = "log", level = "info") {
   appendFileSync(
     outboxPath,
@@ -102,6 +107,7 @@ function progress(phase, extra = {}) {
 let activeSubagents = 0;
 let completedSubagents = 0;
 const subagentFailures = [];
+
 function progressRunning() {
   progress("running", {
     activeSubagents,

package/scripts/conformance.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+/**
+ * Internal conformance runner.
+ *
+ * This script runs the protocol-facing regression suites that exercise recipe
+ * discovery, registry mutation, spawn lifecycle, message routing, room/branch
+ * state, ownership checks, artifacts, and attention semantics without requiring
+ * the Pi UI.
+ *
+ * Keep output compact for CI and release preflight use; detailed failures are
+ * printed only when the underlying Node test run fails.
+ */
+
+import { spawnSync } from "node:child_process";
+
+const suites = [
+  "tests/protocol-examples.test.ts",
+  "tests/recipe-discovery.test.ts",
+  "tests/registry.test.ts",
+  "tests/runtime-registry.test.ts",
+  "tests/async-runs.test.ts",
+  "tests/actor-rooms.test.ts",
+  "tests/tools.test.ts",
+];
+
+const result = spawnSync(
+  process.execPath,
+  ["--experimental-strip-types", "--test", ...suites],
+  { cwd: new URL("..", import.meta.url), encoding: "utf8", stdio: "pipe" },
+);
+
+const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+const summary = output
+  .split("\n")
+  .filter((line) =>
+    /^ℹ (tests|pass|fail|cancelled|skipped|todo|duration_ms) /.test(line),
+  )
+  .join("\n");
+
+console.log("pi-actors conformance");
+console.log(`suites ${suites.length}`);
+if (summary) console.log(summary);
+if (result.status !== 0) {
+  console.error(output.trimEnd());
+  process.exit(result.status ?? 1);
+}

package/scripts/coordinator.mjs

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
+
+/**
+ * Multi-actor coordinator helper.
+ *
+ * This script is the local orchestration process behind packaged swarm and
+ * worker-pool recipes. It starts child actors, assigns work through room and
+ * branch mailboxes, records progress artifacts, and coordinates optional locker
+ * state without owning project-specific policy.
+ *
+ * Keep reusable coordination mechanics here; keep caller goals, prompts, model
+ * choices, and release/project policy in recipes or invocation arguments.
+ */
+
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";

package/scripts/locker.mjs

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
+
+/**
+ * Local coordination locker service.
+ *
+ * This script owns a small file-backed lock/task state directory and exposes a
+ * Unix-socket command surface for coordinators. It can serve live lock requests,
+ * queue work items, hand out task leases, renew/release resource locks, and emit
+ * compact snapshots for inspection.
+ *
+ * Keep it generic: no project policy, no recipe-specific prompts, and no actor
+ * orchestration decisions belong in this layer.
+ */
+
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import {

package/scripts/music-player.mjs

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
+
+/**
+ * Packaged local music-player actor helper.
+ *
+ * This script backs the standard music-player recipe. It scans local music
+ * sources, builds playback queues, launches an available backend player, and
+ * consumes run-mailbox control messages such as play, pause, next, previous,
+ * stop, and status.
+ *
+ * Keep the helper focused on one maintained player actor implementation; recipe
+ * metadata and invocation arguments choose source paths and backend behavior.
+ */
+
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import {
@@ -156,7 +169,9 @@ function windowsMediaPlayerExecutable() {
   const roots = [
     process.env.ProgramFiles,
     process.env["ProgramFiles(x86)"],
-    process.env.SystemDrive ? join(process.env.SystemDrive, "Program Files") : undefined,
+    process.env.SystemDrive
+      ? join(process.env.SystemDrive, "Program Files")
+      : undefined,
     process.env.SystemDrive
       ? join(process.env.SystemDrive, "Program Files (x86)")
       : undefined,
@@ -728,7 +743,11 @@ function startControlLoop(ctx) {
   try {
     watcher = watch(ctx.stateDir, { persistent: false }, (_eventType, file) => {
       const name = file ? String(file) : "";
-      if (!name || name === basename(ctx.inboxFile) || name === basename(runtimeWakeFile(ctx))) {
+      if (
+        !name ||
+        name === basename(ctx.inboxFile) ||
+        name === basename(runtimeWakeFile(ctx))
+      ) {
         dirty = true;
       }
     });

package/scripts/recipe-utils.mjs

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
+
+/**
+ * Recipe utility command bundle.
+ *
+ * This script provides small, deterministic helper subcommands used by packaged
+ * recipes: run summaries, operational snapshots, playlist generation, changelog
+ * extraction, artifact manifests/writes, actor-message envelopes, package
+ * summaries, and skill summaries.
+ *
+ * Keep outputs compact and machine-readable where possible because recipe-utils
+ * often feeds command-template pipelines and actor context directly.
+ */
+
 import {
   appendFileSync,
   existsSync,

package/scripts/validate-recipe.mjs

@@ -1,4 +1,17 @@
 #!/usr/bin/env -S node --experimental-strip-types
+
+/**
+ * Template recipe validator CLI.
+ *
+ * This script validates one recipe file or a recipe directory using the same
+ * recipe-reference parser and import resolver that the extension runtime uses.
+ * It supports source-tree TypeScript during development and compiled dist
+ * modules when installed from npm.
+ *
+ * Keep it read-only: validation should report parse/import/schema problems
+ * without registering tools, launching runs, or mutating user recipes.
+ */
+
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";

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.22.5
+  version: 0.23.0
 ---
 
 # Actors (pi-actors)
@@ -84,7 +84,7 @@ Envelope fields:
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
 - Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
 - Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
-- Standard termination messages: `control.stop`, `control.cancel`, `control.kill`.
+- Standard termination messages: `control.stop`, `control.cancel`, `control.kill`; terminal retention messages: `control.archive`, `control.prune`.
 
 Check `inspect view=mailbox` before domain-specific messages.
 
@@ -125,7 +125,7 @@ Actor inspector commands:
 - `/actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|current-branch <name>|mention <text>`: narrow table previews without changing room/run state.
 - `/actors-inspect <number>`: open one visible row as a full-message view.
 
-The table is compact and optimistic by default: bounded body previews, capped noisy room rows, branch-local inbox previews, and an inline roster summary in the form `name/role` that wraps only when needed. Use `unread` for queued branch inbox work and `branch <name>` / `current-branch <name>` for one branch's room/direct/inbox traffic. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
+The table is compact and optimistic by default: bounded body previews, capped noisy room rows, branch-local inbox previews, stable event ids in selected-message details, and an inline roster summary in the form `name/role` that wraps only when needed. Use `unread` for queued branch inbox work and `branch <name>` / `current-branch <name>` for one branch's room/direct/inbox traffic. Rows with `metadata.requires_response=true` show a `!` attention marker. `/actors-inspect <number>` marks that row read for the current session filter. Active roster members use the target color; members that sent `actor.leave` stay visible as inactive/muted participants from the current run. Actor display names come from `actor.join` bodies (`display`) or branch addresses, keeping debugger output plain and name-driven.
 
 Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
 

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.22.5
+  version: 0.23.0
 ---
 
 # Swarm