@llblab/pi-actors 0.16.4 → 0.17.1

package/scripts/room-swarm.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+function arg(name, fallback = "") {
+  const prefix = `--${name}=`;
+  const value = process.argv.find((item) => item.startsWith(prefix));
+  return value ? value.slice(prefix.length) : fallback;
+}
+
+function numberArg(name, fallback) {
+  const value = Number(arg(name, String(fallback)));
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+function boolArg(name, fallback = false) {
+  const value = arg(name, String(fallback)).trim().toLowerCase();
+  return ["1", "true", "yes", "on"].includes(value);
+}
+
+function normalizeRoles(value) {
+  if (!Array.isArray(value)) throw new Error("roles must be an array");
+  return value.map((role, index) => ({
+    name: String(role.name ?? `actor-${index + 1}`),
+    persona: String(role.persona ?? role.role ?? "room participant"),
+    ...(role.glyph ? { glyph: String(role.glyph) } : {}),
+  }));
+}
+
+function parseRoles(raw) {
+  if (!raw.trim()) return defaultRoles;
+  try {
+    return normalizeRoles(JSON.parse(raw));
+  } catch {
+    return raw.split(",").map((item, index) => ({
+      name: item.trim() || `actor-${index + 1}`,
+      persona: "room participant",
+    }));
+  }
+}
+
+async function loadRoles(raw, path) {
+  if (path.trim()) return normalizeRoles(JSON.parse(await readFile(path, "utf8")));
+  return parseRoles(raw);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function agentDir() {
+  return process.env.PI_CODING_AGENT_DIR || `${process.env.HOME}/.pi/agent`;
+}
+
+function runStateDir(runId) {
+  return `${agentDir()}/tmp/pi-actors/runs/${runId}`;
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForPath(path, timeoutMs = 5000) {
+  const started = Date.now();
+  while (!existsSync(path)) {
+    if (Date.now() - started > timeoutMs) throw new Error(`timed out waiting for ${path}`);
+    await sleep(50);
+  }
+}
+
+async function writeLockerMessage(locker, message) {
+  if (!locker) return;
+  await waitForPath(locker.controlPath);
+  await writeFile(locker.controlPath, `${JSON.stringify(message)}\n`, { flag: "a" });
+  await sleep(50);
+}
+
+async function startLocker(config) {
+  if (!config.locker) return undefined;
+  const lockerStateDir = `${runStateDir(config.runId)}/locker`;
+  await mkdir(lockerStateDir, { recursive: true });
+  const child = spawn(new URL("./coordinator-locker.mjs", import.meta.url).pathname, [
+    "serve",
+    "--state-dir",
+    lockerStateDir,
+    "--lease-ms",
+    String(config.lockerLeaseMs),
+  ], {
+    env: { ...process.env, run_id: config.runId },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  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);
+  await writeLockerMessage(locker, {
+    type: "coord.enqueue",
+    body: { id: "room-swarm-artifact", task: "Own final room-swarm artifact synthesis", resources: [config.artifactPath || "artifact"] },
+  });
+  return locker;
+}
+
+async function stopLocker(locker) {
+  if (!locker) return;
+  try {
+    await writeLockerMessage(locker, { type: "control.stop", body: {} });
+    await sleep(100);
+  } finally {
+    if (!locker.child.killed) locker.child.kill("SIGTERM");
+  }
+}
+
+function runPi(prompt, model, thinking) {
+  return new Promise((resolve) => {
+    const child = spawn("pi", [
+      "--model", model,
+      "--thinking", thinking,
+      "--tools", "inspect,message",
+      "--no-context-files",
+      "--no-skills",
+      "--no-session",
+      "-p",
+      prompt,
+    ], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.on("error", (error) => resolve({ code: 1, stdout, stderr: String(error) }));
+  });
+}
+
+async function participant(role, config) {
+  const displayName = role.glyph ? `${role.glyph} ${role.name}` : role.name;
+  const address = `branch:${config.runId}/${role.name}`;
+  const joinPrompt = `You are ${displayName}, ${role.persona}. Mission: ${config.mission}. Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.join', summary='${displayName} joined', body JSON {"role":${JSON.stringify(role.persona)},"display":${JSON.stringify(displayName)},"glyph":${JSON.stringify(role.glyph ?? "")},"caps":["coordination","synthesis"],"claim":"coordinate on mission"}. Then print one short line.`;
+  await runPi(joinPrompt, config.model, config.thinking);
+  for (let round = 1; round <= config.rounds; round += 1) {
+    const prompt = `You are ${displayName} (${address}), ${role.persona}. Mission: ${config.mission}. Round ${round}/${config.rounds}. First call inspect target=${config.room} view=previews lines=30 and inspect target=${config.room} view=contacts. Then call message once to ${config.room} from ${address} type=chat.message. Body: 2-4 sentences that react to a named participant, propose the next coordination step, and refine the shared artifact. Use contacts for peer names and addresses, but keep this packaged swarm's coordination room-visible; do not send direct branch messages unless a caller-specific worker protocol says recipients consume them. End stdout with summary <=160 chars.`;
+    const result = await runPi(prompt, config.model, config.thinking);
+    process.stdout.write(`[${role.name} round ${round}] code=${result.code}\n${result.stdout}\n`);
+    if (result.stderr.trim()) process.stderr.write(`[${role.name} round ${round}] ${result.stderr}\n`);
+    if (round < config.rounds && config.delay > 0) await new Promise((resolve) => setTimeout(resolve, config.delay * 1000));
+  }
+  const leavePrompt = `Call tool message exactly once with to=${shellQuote(config.room)}, from=${shellQuote(address)}, type='actor.leave', summary='${displayName} left', body='finished coordinated work'. Then print goodbye.`;
+  await runPi(leavePrompt, config.model, config.thinking);
+}
+
+async function readRoomTranscript(config) {
+  const messagesPath = `${agentDir()}/tmp/pi-actors/runs/${config.runId}/rooms/main/messages.jsonl`;
+  try {
+    const raw = await readFile(messagesPath, "utf8");
+    return raw
+      .split("\n")
+      .filter(Boolean)
+      .slice(-160)
+      .map((line) => {
+        try {
+          const message = JSON.parse(line);
+          const from = String(message.from || "unknown").replace(/^branch:[^/]+\//, "");
+          const type = String(message.type || "message");
+          const body = typeof message.body === "string" ? message.body : JSON.stringify(message.body ?? "");
+          return `${from} [${type}]: ${body}`;
+        } catch {
+          return line;
+        }
+      })
+      .join("\n");
+  } catch {
+    return "";
+  }
+}
+
+async function synthesize(config, locker) {
+  if (!config.artifactPath) return;
+  await writeLockerMessage(locker, {
+    type: "coord.claim",
+    body: { owner: "room-swarm:synthesizer" },
+  });
+  const transcript = await readRoomTranscript(config);
+  const prompt = `Synthesize this room-swarm transcript into a concise Markdown artifact. Mission: ${config.mission}. Include: Title, Consensus, Roles, Protocol, Final Artifact Shape, Next Actions, Open Questions. Use only the transcript evidence below.\n\nTRANSCRIPT:\n${transcript.slice(-24000)}`;
+  const result = await runPi(prompt, config.model, config.thinking);
+  await writeFile(config.artifactPath, result.stdout.trim() ? result.stdout : "# Room Swarm Artifact\n\nNo synthesis output.\n", "utf8");
+  await writeLockerMessage(locker, {
+    type: "coord.complete",
+    body: { id: "room-swarm-artifact", artifact: config.artifactPath },
+  });
+  await writeLockerMessage(locker, {
+    type: "lock.release",
+    body: { resource: config.artifactPath },
+  });
+  process.stdout.write(`artifact=${config.artifactPath}\n`);
+}
+
+const defaultRoles = [
+  { name: "mapper", glyph: "🗺️", persona: "systems mapper; tracks shared structure and dependencies" },
+  { name: "memory", glyph: "🌿", persona: "memory keeper; preserves decisions and unresolved questions" },
+  { name: "risk", glyph: "🧨", persona: "risk scout; challenges weak coordination and missing owners" },
+  { name: "flow", glyph: "🌊", persona: "flow designer; turns scattered ideas into process rhythm" },
+  { name: "operator", glyph: "🔥", persona: "operator; converts ideas into concrete next actions" },
+  { name: "narrative", glyph: "📖", persona: "narrative synthesizer; keeps the artifact coherent" },
+  { name: "interface", glyph: "✨", persona: "interface designer; makes outputs visible and usable" },
+  { name: "facilitator", glyph: "🤫", persona: "facilitator; asks for consensus and convergence" },
+];
+
+const config = {
+  runId: arg("run-id", process.env.run_id || process.env.RUN_ID || "room-swarm"),
+  mission: arg("mission", "Coordinate a shared artifact and converge on next actions"),
+  model: arg("model", ""),
+  thinking: arg("thinking", "off"),
+  roles: await loadRoles(arg("roles", ""), arg("roles-path", "")),
+  rounds: numberArg("rounds", 4),
+  delay: numberArg("delay", 10),
+  artifactPath: arg("artifact-path", ""),
+  locker: boolArg("locker", false),
+  lockerLeaseMs: numberArg("locker-lease-ms", 600000),
+};
+
+if (!config.model) {
+  console.error("--model is required");
+  process.exit(2);
+}
+config.room = `room:${config.runId}`;
+
+const failures = [];
+const locker = await startLocker(config);
+try {
+  await Promise.all(config.roles.map(async (role) => {
+    try {
+      await participant(role, config);
+    } catch (error) {
+      failures.push(`${role.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }));
+  await synthesize(config, locker);
+} finally {
+  await stopLocker(locker);
+}
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}

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.16.4
+  version: 0.17.1
 ---
 
 # Actors (pi-actors)
@@ -37,7 +37,8 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
+- **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
 - **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`.
 - **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
 - **Mailbox**: public interaction contract: message types the actor accepts/emits.
@@ -80,7 +81,8 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `tool:<name>`, `coordinator`, `session:<id>`.
+- 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`.
 
 Check `inspect view=mailbox` before domain-specific messages.
@@ -91,7 +93,12 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
+{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
+{ "target": "room:repo-health", "view": "status" }
+{ "target": "room:repo-health", "view": "roster" }
+{ "target": "room:repo-health", "view": "contacts" }
+{ "target": "room:repo-health", "view": "previews" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
 { "target": "coordinator", "view": "status" }
@@ -101,7 +108,11 @@ Views:
 
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
-- `messages`: actor messages emitted by the run.
+- `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
+- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
+- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- `contacts`: roster-derived direct-message targets without full roster metadata.
+- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -109,6 +120,38 @@ Views:
 
 Let terminal notifications arrive; avoid sleep-poll loops except during diagnosis.
 
+## Stable Multi-Actor Review Rules
+
+- Prefer independent read-only reviewers for review swarms. Use shared room messages for coordination signals and observability, not for letting reviewers converge early, unless the task explicitly asks for collaborative discussion.
+- Treat inspector-visible communication logs as recipe-quality evidence. Verbose room/direct timelines show whether recipes coordinate clearly, emit useful summaries, over-chat, miss handoffs, choose poor message types, or need better mailbox/artifact conventions. Use `inspect room:<run> view=messages|previews`, `inspect run:<id> view=communication`, and the actor inspector compact/verbose modes to improve recipes after real runs.
+- Smoke-test provider/model availability before launching expensive fanout, or choose a provider known to be configured in this environment. A failed provider fanout creates noisy run transitions without useful review signal.
+- Keep one public communication model: `spawn` creates actors, `message` sends typed envelopes, and `inspect` observes. Avoid adding public side channels or storage nouns when a normal actor address/view can express the operation.
+- Keep route and semantic type separate. Direct, room, coordinator, and session messages may share `type`; delivery behavior comes from `to`.
+- Any UI, summary, or aggregate view that scans run directories must apply coordinator/session ownership filters before exposing summaries or body previews.
+- Treat `communication.json` as visible actor context, not a global mutable truth table. Run-level snapshots should identify the run actor; branch-local snapshots should identify the branch actor.
+- Prefer same-run provenance checks on lateral actor routes. If `from` is accepted for room or branch routes, validate that it belongs to the addressed run.
+
+## Persistent Backlog Implementers
+
+When using actors as backlog implementers, avoid one-shot subagents that exit after one task. Use long-lived branch actors and keep task selection with the coordinator:
+
+1. Coordinator assigns a concrete backlog slice with `task.assign`.
+2. Actor posts `task.claim` to `room:<run>` before editing.
+3. Actor executes and validates the slice.
+4. Actor posts `task.result` and `awaiting_assignment`.
+5. Actor stays alive until the coordinator sends another `task.assign` or an explicit `control.stop`.
+
+Use `front`/`back` actors for opposite backlog ends when reducing overlap. Implementer workflows should be packaged as reusable recipe composition, not bespoke scripts: use `coordinator-locker` for queue/assignment/locking, subagent launcher recipes for execution cells, and actor-message utility recipes for structured handoffs. If the existing recipe library cannot express the scenario, add missing reusable component recipes first, then compose the higher-level workflow from them. Supervisors should route coordinator assignments by `body.actor`, preserve the assignment as an object rather than a JSON string, and keep stopped-worker summaries tied to the original actor list.
+
+Current packaged building blocks:
+
+- `coordinator-locker`: long-lived queue/lock coordinator for assignment and resource ownership.
+- `subagent-prompt`, `subagent-tools`, `subagents-prompts`: execution launchers for one or many agent prompts.
+- `utility-actor-message`: deterministic actor-message envelope construction for handoffs/results.
+- `utility-run-ops-snapshot` and `pipeline-async-run-ops`: inspect live runs/messages before deciding the next assignment.
+
+The missing higher-level persistent backlog-implementer workflow is intentionally future work until it can be expressed from reusable recipe cells.
+
 ## Command Template Standard
 
 Forms:
@@ -180,11 +223,11 @@ Priority for same-name recipes:
 
 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.
 
-Muscle-memory lens: every recipe in `~/.pi/agent/recipes/*.json` becomes an easy-to-call tool by default. This is intentionally sticky: successful local patterns can quickly become durable agent muscle memory. The tradeoff is tool-surface clutter; accidental or one-off tools behave like persistent intrusive thoughts until an agent/operator focuses on cleanup.
+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.
 
-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 or `tool: false` 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.
+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.
 
-Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, set `tool: false` to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer demotion over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
+Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 
 ## Registered Tools
 
@@ -198,7 +241,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; packaged recipes are the lower-priority standard library and opt into tool exposure with `tool: true`. 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; 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
 
@@ -227,7 +270,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).
+- 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; keep role `name` ASCII-safe for branch addresses and use optional `glyph` only as display identity. Use `locker=true` when the swarm needs a coordinator-locker-backed artifact lock and journal.
 
 ### Utilities
 

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.16.4
+  version: 0.17.1
 ---
 
 # Swarm