@llblab/pi-actors 0.20.1 → 0.21.0

package/BACKLOG.md

@@ -2,46 +2,6 @@
 
 ## Open Work
 
-### Actor Rooms, Roster, and Cross-Branch Messaging
-
-- Priority: High.
-- Goal: Continue evolving actor communication without adding a second public messaging model.
-- Direction:
-  - Evaluate whether room storage/routing should remain built into the tool adapter or move behind a dedicated non-LLM communication actor recipe/script, possibly singleton-scoped. Preserve the same public `room:<run>` address and envelope either way.
-  - Treat the next backend decision as an evidence-backed experiment, not a rewrite: stress a real room/direct-message workload, compare the current file-backed adapter with a thin communication actor/helper, and record the decision.
-  - Consider reducing direct file-backed state where it improves coherence: model room/roster state as actor-owned data structures served by helper scripts/actors, with files retained only for durable snapshots, recovery, artifacts, or audit logs.
-  - Further storage changes should preserve the current burst/read/concurrency safeguards: branch communication snapshot writes are debounced, root snapshots stay current, roster files are not rewritten during bursts when only `last_seen` changes, room status inspection does not parse full timelines, branch-local inbox append/status rewrites are lock-guarded, and legacy no-ID branch inbox records can be claimed exactly once.
-  - Prevent monolith drift: `actor-rooms.ts` may remain a thin adapter, but growing routing policy, subscription loops, fanout policy, or long-lived state ownership should move behind a focused communication helper/actor rather than accumulating in the tool adapter.
-- Exit:
-  - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
-  - A short decision note or changelog entry explains why the room backend stayed file-backed or moved behind a communication actor/helper.
-
-### Graceful Actor Retirement
-
-- Priority: Medium.
-- Goal: Automatically retire coordinator/helper actors that were launched only to supervise a bounded worker tree once their dependent workers have finished.
-- Direction:
-  - Build on the existing `retire_when: "children_terminal"` recipe/run metadata contract and observability retirement-candidate detection for ephemeral supervisors.
-  - Treat auto-retirement as opt-in only; never infer it for arbitrary long-lived services, user tools, or persistent backlog implementers.
-  - Extend candidate detection beyond current active command/proc-descendant gating to full observed child async-run state rather than log text: the supervisor may retire only when all launched child async runs are terminal and required artifacts/outbox events have been flushed.
-  - Prefer graceful stop (`control.stop` / actor message) before process termination; escalate only after a bounded timeout and record the retirement event in run state.
-  - Preserve manual `cancel` / `kill` semantics and make retirement visible through `inspect` / ambient observability.
-- Exit:
-  - A packaged coordinator recipe can launch worker actors, complete its coordination duties, and shut itself down automatically after the worker tree reaches terminal state.
-  - Persistent services and implementer actors remain alive unless their recipe explicitly opts into retirement.
-
-### Coordinator Strategy Boundary
-
-- Priority: Medium.
-- Goal: Keep the generic coordinator from becoming a second overloaded monolith as room/direct-message workflows mature.
-- Direction:
-  - Split only at real pressure points: branch inbox claim/finalize helpers, participant execution, room transcript synthesis, and mode strategies are likely seams, but avoid cosmetic module churn.
-  - Preserve the current principle that the locker stays generic/thin and all orchestration policy stays in coordinator strategy code or recipe composition.
-  - Prefer reusable helper modules or small scripts only when at least two packaged workflows need the same behavior.
-- Exit:
-  - Adding a new coordinator mode or packaged multi-agent workflow does not require editing unrelated mode logic.
-  - Existing room-swarm, locker, and direct-branch-message tests still cover the extracted seams.
-
 ### Consensus-First Build Recipe
 
 - Priority: Medium.
@@ -57,18 +17,6 @@
   - A packaged recipe can reproduce the interactive-music-instrument workflow shape for another single-artifact task without copying the demo script.
   - Docs and skills point agents to the packaged recipe and explain when to choose it over a free-form room swarm.
 
-### Actor OS Scenario Smoke Matrix
-
-- Priority: Medium.
-- Goal: Convert the 0.19.x actor-communication hardening into repeatable end-to-end scenario checks instead of relying on ad hoc demos.
-- Direction:
-  - Cover one scenario each for shared room coordination, direct branch work delivery, branch inbox claim/handle/fail transitions, inspector navigation, recipe context injection, recipe persistence suggestion, and opt-in retirement candidate detection.
-  - Keep scenarios local-first and bounded: fake `pi`/models where possible, no external services, no long sleeps, no broad golden transcripts.
-  - Prefer packaged recipes and public `spawn` / `message` / `inspect` calls so the smoke matrix exercises the same surface agents use.
-- Exit:
-  - A single validation command or documented test group verifies the actor OS behaviors that made 0.19.x production-useful.
-  - The smoke matrix catches regressions in actor communication, recipe memory, and observability without requiring a manual swarm demo.
-
 ### Persistent Backlog Implementer Workflow
 
 - Priority: Medium.

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## Unreleased
+
+## 0.21.0: Native Windows Actor Control and Literate Recipes
+
+- `[Async Runs]` Added a platform-adapted run-control path: Unix FIFO behavior remains backward-compatible, native Windows can target named-pipe run-control endpoints recorded in run state, and run message receipts still update events and inbox state through the same actor-message path.
+- `[Async Runs]` Added Windows process-tree termination planning for cancel/kill through `taskkill`, while preserving Unix process-group signaling semantics.
+- `[Scripts]` Migrated `locker.mjs` and coordinator locker calls to platform-adapted control metadata: Unix still uses `control.fifo`, while native Windows can use a deterministic named-pipe endpoint with the same message protocol.
+- `[Branch Messages]` Added bounded branch-inbox terminal retention during status transitions, preserving active queued/claimed work while compacting older handled/failed records for long-lived branch runners.
+- `[Recipe Discovery]` Tightened trust-boundary diagnostics so combined short shell/eval flags such as `bash -lc` and nested recipe command-template objects are surfaced, including the packaged validation wrapper's trusted shell boundary.
+- `[Rooms]` Recorded the backend decision to keep the current file-backed room adapter until real workflows need live subscriptions/fanout or shared mutable state, backed by a mixed room/direct-branch workload regression.
+- `[Recipes]` Added Markdown-authored recipe loading for `.md` files with frontmatter metadata and fenced executable recipe/template blocks, with same-id JSON shadowing Markdown in the same priority layer.
+- `[Retirement]` Extended run summaries to discover nested child async-run state dirs, blocks opt-in retirement while nested children are still running, surfaces child/terminal child counts on candidates, and has the session watcher retire ready candidates with one graceful stop attempt plus owned cancellation fallback. Added an integration smoke where an idle supervisor stops after its nested child is terminal while a non-opt-in service remains running.
+- `[Coordinator]` Consolidated direct branch inbox claim/finalize rewrites behind one locked mutation helper and moved room-swarm mode dispatch behind an explicit mode registry. Unknown coordinator modes now fail closed, and `pipeline-room-swarm` exposes the supported mode enum.
+- `[Docs]` Documented the local Actor OS smoke matrix covered by `npm test`, spanning room coordination, direct branch delivery, inbox claim/handle transitions, inspector navigation, recipe context injection, persistence suggestions, and opt-in retirement smoke.
+- `[Docs/Tests]` Documented native Windows support scope and added regression coverage for Windows endpoint metadata, mocked named-pipe sends, Windows process-control planning, unchanged Unix FIFO behavior, locker control metadata, branch inbox compaction, mixed room/direct workloads, Markdown recipe loading/discovery/validation, nested child-run retirement gating, and packaged recipe trust diagnostics.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.21.0` for the minor release.
+
+## 0.20.2: Installed Extension Entrypoint Hotfix
+
+- `[Packaging]` Added a JavaScript extension entrypoint wrapper and changed package metadata to load `./index.js`, so npm-installed packages import compiled `dist/index.js` instead of asking Node to strip `index.ts` under `node_modules`. Source checkouts still fall back to `index.ts` before a local build exists.
+- `[Build]` Extended the compiled runtime build to emit `dist/index.js` alongside `dist/lib/*.js`, keeping extension entrypoint imports and script runtime imports on the same installed-package path model.
+- `[Rooms]` Fixed immediate room append results to report the true persisted room message count after long timelines instead of the default 40-message preview length; `appendRoomMessage`, existing-member room joins, and `getRoomStatus()` now share the same line-count helper.
+- `[Tests]` Added installed-package coverage that imports the extension entrypoint from package metadata without TypeScript stripping, plus room-count regression coverage beyond the default preview limit.
+- `[Package]` Bumped package metadata and packaged skill metadata to `0.20.2` for the hotfix release.
+
 ## 0.20.1: Installed Packaged Recipe Root Hotfix
 
 - `[Recipe Imports]` Fixed installed compiled runtime path resolution so bare user recipe imports can fall back to the packaged standard-library `recipes/` directory instead of looking for a non-existent `dist/recipes` directory.

package/README.md

@@ -169,6 +169,7 @@ The persistent tool surface is file-discovered:
 
 ```text
 ~/.pi/agent/recipes/*.json
+~/.pi/agent/recipes/*.md
 ```
 
 That directory is operator-managed executable memory.
@@ -178,6 +179,7 @@ Rules:
 - User recipes in `~/.pi/agent/recipes/` are tools by location;
 - Recipe filenames define tool ids;
 - User recipes override same-name lower-priority recipes;
+- Same-id JSON recipes shadow Markdown recipes in the same priority layer;
 - Packaged recipes are standard-library components, not automatically installed operator policy;
 - `register_tool` creates, updates, lists, or deletes user recipe files through the normal agent interface.
 
@@ -220,7 +222,7 @@ Templates support:
 - Retries, recovery, failure policy, delays, and guarded execution;
 - Async run values such as `{run_id}`, `{state_dir}`, `{actor_address}`, `{default_room}`, and `{communication_file}`.
 
-The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
+The template owns execution shape. The recipe owns saved metadata, defaults, imports, mailbox, and artifacts. JSON is the canonical precise recipe format; Markdown recipes use frontmatter plus fenced `template`/`json recipe` blocks for literate authoring and compile into the same model. The run actor owns detached lifecycle, state, messages, cancellation, and inspection. File-backed async recipes also provide child `pi -p` actors with a bounded JSONL recipe context bundle by default, including raw entry/import recipe records and a `"you_are_here": true` marker for the recipe node that launched the child. Set `"actor_context": false` or `"off"` in a recipe to suppress that context for minimal prompts.
 
 ## Recipe Library
 
@@ -249,6 +251,10 @@ Use artifacts when outputs should survive context compression.
 
 Use mailbox declarations when an actor has a stable conversational surface.
 
+## Platform Support
+
+Core actor state, inspection, foreground tools, and basic async runs are portable Node.js behavior. Run-local messaging and stop/kill use a platform adapter under the same `message` API: Unix-compatible recipes can use their existing local control endpoint, while native Windows recipes can expose a Windows-native endpoint in run state. Some packaged scripts still depend on Unix tools and are WSL/Linux/macOS-only until migrated; their public recipe surface should stay `spawn` / `message` / `inspect` either way.
+
 ## Safety Boundary
 
 `pi-actors` is local-first, not sandbox-first.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * pi-actors — actor runtime and persistent local tool registry for pi.
+ * Zones: composition root, pi agent, actor runtime
+ *
+ * Wraps command templates as callable pi tools, stores durable user tools as recipe files, and exposes actor orchestration across reloads and sessions.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function toolRegistryExtension(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,385 @@
+/**
+ * pi-actors — actor runtime and persistent local tool registry for pi.
+ * Zones: composition root, pi agent, actor runtime
+ *
+ * Wraps command templates as callable pi tools, stores durable user tools as recipe files, and exposes actor orchestration across reloads and sessions.
+ */
+import { existsSync, readdirSync, watch } from "node:fs";
+import * as ActorInspectorTui from "./lib/actor-inspector-tui.js";
+import * as AsyncRuns from "./lib/async-runs.js";
+import * as CommandTemplates from "./lib/command-templates.js";
+import * as Observability from "./lib/observability.js";
+import * as Paths from "./lib/paths.js";
+import * as Prompts from "./lib/prompts.js";
+import * as Runtime from "./lib/runtime.js";
+import * as Temp from "./lib/temp.js";
+import * as Tools from "./lib/tools.js";
+const CONFIG_PATH = Paths.getConfigPath();
+const TEMP_DIR = Paths.getExtensionTmpDir();
+const RUN_STATE_ROOT = Paths.getRunStateRoot();
+const RESERVED_TOOL_NAMES = new Set([
+    "read",
+    "write",
+    "edit",
+    "bash",
+    "find",
+    "grep",
+    "ls",
+    "register_tool",
+    "message",
+    "spawn",
+    "inspect",
+]);
+export default function toolRegistryExtension(pi) {
+    let runsAnimationInterval;
+    let runsNotifyTimeout;
+    let recipeReloadTimeout;
+    let recipeRootWatcher;
+    let stateRootWatcher;
+    const runDirWatchers = new Map();
+    const observedRuns = new Map();
+    const observedRunEventLines = new Map();
+    const retirementAttempts = new Set();
+    let runStatusFrame = 0;
+    let communicationWidgetVisible = false;
+    let actorInspectorRows = 12;
+    let actorInspectorChannels;
+    let actorInspectorMention;
+    let actorInspectorBranch;
+    let actorInspectorUnreadOnly = false;
+    let actorInspectorRoomLimitPerRun = 12;
+    let selectedInspectorSequence;
+    let recipeWatcherFailureNotified = false;
+    const getRunOwnerId = (ctx) => ctx.sessionManager.getSessionId();
+    const retireCandidateRuns = (ctx, summary) => {
+        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, notify = false) => {
+        const ownerId = getRunOwnerId(ctx);
+        const summary = Observability.summarizeRuns(undefined, ownerId);
+        const status = Observability.renderRunStatus(summary, runStatusFrame++);
+        ctx.ui.setStatus("zz-pi-actors-runs", status ? ctx.ui.theme.fg("dim", status) : undefined);
+        ctx.ui.setWidget("zz-pi-actors-comms", communicationWidgetVisible
+            ? () => {
+                const style = {
+                    actor: (text) => ctx.ui.theme.fg("accent", text),
+                    muted: (text) => ctx.ui.theme.fg("dim", text),
+                    preview: (text) => ctx.ui.theme.fg("text", text),
+                    stripe: (text) => text,
+                    stripeAlt: (text) => ctx.ui.theme.bg("customMessageBg", text),
+                    target: (text) => ctx.ui.theme.fg("success", text),
+                    type: (text) => ctx.ui.theme.fg("warning", text),
+                };
+                return {
+                    invalidate() { },
+                    render(width) {
+                        const previews = ActorInspectorTui.readActorInspectorPreviews(RUN_STATE_ROOT, actorInspectorRows, {
+                            channels: actorInspectorChannels,
+                            currentRunOnly: true,
+                            branch: actorInspectorBranch,
+                            mention: actorInspectorMention,
+                            ownerId,
+                            roomLimitPerRun: actorInspectorRoomLimitPerRun,
+                            unreadOnly: actorInspectorUnreadOnly,
+                        });
+                        const rows = (selectedInspectorSequence !== undefined
+                            ? ActorInspectorTui.renderInspectorItemView(previews, width, style, { sequence: selectedInspectorSequence })
+                            : ActorInspectorTui.renderInspectorWidget(previews, width, style)) ?? [];
+                        const run = previews[0]?.run;
+                        const roster = run
+                            ? ActorInspectorTui.renderInspectorRosterPanel(ActorInspectorTui.readActorInspectorRoster(RUN_STATE_ROOT, run), width, style)
+                            : undefined;
+                        return roster ? [...roster, ...rows] : rows;
+                    },
+                };
+            }
+            : undefined, { placement: "belowEditor" });
+        const transitions = Observability.detectRunTransitions(observedRuns, summary);
+        const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary);
+        if (!notify)
+            return;
+        retireCandidateRuns(ctx, summary);
+        for (const transition of transitions) {
+            if (!Observability.shouldNotifyRunTransition(transition))
+                continue;
+            const text = Observability.formatRunTransitionMessage(transition);
+            const notificationType = Observability.getRunTransitionNotificationType(transition);
+            ctx.ui.notify(text, notificationType);
+            if (!Observability.shouldSendRunTransitionFollowUp(transition))
+                continue;
+            pi.sendMessage({
+                customType: "pi-actors-run",
+                content: text,
+                display: true,
+                details: transition,
+            }, { deliverAs: "followUp", triggerTurn: true });
+        }
+        Observability.pruneRunObservationState(observedRuns, observedRunEventLines, summary, transitions.map((transition) => transition.run));
+        for (const event of outboxEvents) {
+            if (!Observability.shouldNotifyRunOutboxEvent(event))
+                continue;
+            const text = Observability.formatRunOutboxMessage(event);
+            const notificationType = Observability.getRunOutboxNotificationType(event);
+            ctx.ui.notify(text, notificationType);
+            if (!Observability.shouldSendRunOutboxFollowUp(event))
+                continue;
+            pi.sendMessage({
+                customType: "pi-actors-run-message",
+                content: text,
+                display: true,
+                details: event,
+            }, { deliverAs: "followUp", triggerTurn: true });
+        }
+    };
+    const closeRunWatchers = () => {
+        stateRootWatcher?.close();
+        stateRootWatcher = undefined;
+        for (const watcher of runDirWatchers.values())
+            watcher.close();
+        runDirWatchers.clear();
+        if (runsNotifyTimeout)
+            clearTimeout(runsNotifyTimeout);
+        runsNotifyTimeout = undefined;
+    };
+    const scheduleRunEventUpdate = (ctx) => {
+        if (runsNotifyTimeout)
+            clearTimeout(runsNotifyTimeout);
+        runsNotifyTimeout = setTimeout(() => {
+            refreshRunWatchers(ctx);
+            updateRunUi(ctx, true);
+        }, 50);
+        runsNotifyTimeout.unref?.();
+    };
+    const watchRunDir = (ctx, stateDir) => {
+        if (runDirWatchers.has(stateDir) || !existsSync(stateDir))
+            return;
+        try {
+            const watcher = watch(stateDir, () => scheduleRunEventUpdate(ctx));
+            watcher.on("error", () => {
+                watcher.close();
+                runDirWatchers.delete(stateDir);
+            });
+            runDirWatchers.set(stateDir, watcher);
+        }
+        catch {
+            // Watching is best-effort; explicit inspect remains available.
+        }
+    };
+    function refreshRunWatchers(ctx) {
+        if (!existsSync(RUN_STATE_ROOT))
+            return;
+        if (!stateRootWatcher) {
+            try {
+                stateRootWatcher = watch(RUN_STATE_ROOT, () => scheduleRunEventUpdate(ctx));
+                stateRootWatcher.on("error", () => {
+                    stateRootWatcher?.close();
+                    stateRootWatcher = undefined;
+                });
+            }
+            catch {
+                // Watching is best-effort; explicit inspect remains available.
+            }
+        }
+        for (const entry of readdirSync(RUN_STATE_ROOT, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            watchRunDir(ctx, `${RUN_STATE_ROOT}/${entry.name}`);
+        }
+    }
+    const closeRecipeWatcher = () => {
+        recipeRootWatcher?.close();
+        recipeRootWatcher = undefined;
+        if (recipeReloadTimeout)
+            clearTimeout(recipeReloadTimeout);
+        recipeReloadTimeout = undefined;
+    };
+    const notifyRecipeWatcherFailure = (ctx) => {
+        if (recipeWatcherFailureNotified)
+            return;
+        recipeWatcherFailureNotified = true;
+        ctx.ui.notify("Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.", "warning");
+    };
+    const scheduleRecipeReload = (ctx) => {
+        recipeWatcherFailureNotified = false;
+        if (recipeReloadTimeout)
+            clearTimeout(recipeReloadTimeout);
+        recipeReloadTimeout = setTimeout(() => {
+            runtime.loadTools(ctx);
+            ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+        }, 150);
+        recipeReloadTimeout.unref?.();
+    };
+    const watchRecipeRoot = (ctx) => {
+        const recipeRoot = Paths.getRecipeRoot();
+        if (recipeRootWatcher || !existsSync(recipeRoot))
+            return;
+        try {
+            recipeRootWatcher = watch(recipeRoot, () => scheduleRecipeReload(ctx));
+            recipeRootWatcher.on("error", () => {
+                recipeRootWatcher?.close();
+                recipeRootWatcher = undefined;
+                notifyRecipeWatcherFailure(ctx);
+            });
+        }
+        catch {
+            notifyRecipeWatcherFailure(ctx);
+        }
+    };
+    const actorToolDefinitions = new Map();
+    const runtime = Runtime.createAutoToolsRuntime({
+        configPath: CONFIG_PATH,
+        exec: CommandTemplates.execCommandTemplate,
+        getActiveTools: () => pi.getActiveTools(),
+        getAllTools: () => pi.getAllTools(),
+        registerTool: (definition) => {
+            actorToolDefinitions.set(definition.name, definition);
+            pi.registerTool(definition);
+        },
+        reservedToolNames: RESERVED_TOOL_NAMES,
+        setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
+    });
+    pi.on("session_start", async (_event, ctx) => {
+        await Temp.prepareExtensionTempDir(TEMP_DIR);
+        runtime.loadTools(ctx);
+        updateRunUi(ctx);
+        closeRunWatchers();
+        closeRecipeWatcher();
+        refreshRunWatchers(ctx);
+        watchRecipeRoot(ctx);
+        if (runsAnimationInterval)
+            clearInterval(runsAnimationInterval);
+        runsAnimationInterval = setInterval(() => updateRunUi(ctx, false), 1000);
+        runsAnimationInterval.unref?.();
+    });
+    pi.on("session_shutdown", async () => {
+        if (runsAnimationInterval)
+            clearInterval(runsAnimationInterval);
+        runsAnimationInterval = undefined;
+        closeRunWatchers();
+        closeRecipeWatcher();
+    });
+    pi.registerCommand("actors-inspector-toggle", {
+        description: "Toggle actor inspector widget; optional row count",
+        handler: async (args, ctx) => {
+            const raw = Array.isArray(args) ? args[0] : String(args ?? "");
+            if (String(raw).trim()) {
+                const rows = Number.parseInt(String(raw), 10);
+                if (!Number.isFinite(rows) || rows <= 0) {
+                    ctx.ui.notify("Usage: /actors-inspector-toggle [rows] where rows > 0", "warning");
+                    return;
+                }
+                actorInspectorRows = rows;
+                actorInspectorRoomLimitPerRun = rows;
+                selectedInspectorSequence = undefined;
+                communicationWidgetVisible = true;
+                updateRunUi(ctx);
+                ctx.ui.notify(`Actor inspector rows ${rows}`, "info");
+                return;
+            }
+            if (selectedInspectorSequence !== undefined) {
+                selectedInspectorSequence = undefined;
+                communicationWidgetVisible = true;
+                updateRunUi(ctx);
+                ctx.ui.notify("Actor inspector table", "info");
+                return;
+            }
+            if (communicationWidgetVisible) {
+                communicationWidgetVisible = false;
+            }
+            else {
+                actorInspectorRows = 12;
+                actorInspectorRoomLimitPerRun = 12;
+                communicationWidgetVisible = true;
+            }
+            updateRunUi(ctx);
+            ctx.ui.notify(`Actor inspector ${communicationWidgetVisible ? "shown" : "hidden"}`, "info");
+        },
+    });
+    pi.registerCommand("actors-inspector-filter", {
+        description: "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
+        handler: async (args, ctx) => {
+            const parts = Array.isArray(args)
+                ? args.map(String)
+                : String(args ?? "").split(/\s+/);
+            const mode = (parts[0] ?? "").trim().toLowerCase();
+            if (!mode || mode === "all" || mode === "clear") {
+                actorInspectorChannels = undefined;
+                actorInspectorMention = undefined;
+                actorInspectorBranch = undefined;
+                actorInspectorUnreadOnly = false;
+            }
+            else if (mode === "room" || mode === "direct" || mode === "broadcast") {
+                actorInspectorChannels = [mode];
+                actorInspectorMention = undefined;
+            }
+            else if (mode === "unread") {
+                actorInspectorUnreadOnly = true;
+            }
+            else if (mode === "branch" || mode === "current-branch") {
+                const branch = parts.slice(1).join(" ").trim();
+                if (!branch) {
+                    ctx.ui.notify(`Usage: /actors-inspector-filter ${mode} <branch-name>`, "warning");
+                    return;
+                }
+                actorInspectorBranch = branch;
+            }
+            else if (mode === "mention") {
+                const mention = parts.slice(1).join(" ").trim();
+                if (!mention) {
+                    ctx.ui.notify("Usage: /actors-inspector-filter mention <text>", "warning");
+                    return;
+                }
+                actorInspectorChannels = undefined;
+                actorInspectorMention = mention;
+            }
+            else {
+                ctx.ui.notify("Usage: /actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|mention <text>", "warning");
+                return;
+            }
+            selectedInspectorSequence = undefined;
+            communicationWidgetVisible = true;
+            updateRunUi(ctx);
+            ctx.ui.notify(`Actor inspector filter ${mode || "all"}`, "info");
+        },
+    });
+    pi.registerCommand("actors-inspect", {
+        description: "Inspect actor message by visible number",
+        handler: async (args, ctx) => {
+            const raw = Array.isArray(args) ? args[0] : String(args ?? "");
+            const sequence = Number.parseInt(String(raw), 10);
+            if (!Number.isFinite(sequence) || sequence <= 0) {
+                ctx.ui.notify("Usage: /actors-inspect <number>", "warning");
+                return;
+            }
+            selectedInspectorSequence = sequence;
+            communicationWidgetVisible = true;
+            updateRunUi(ctx);
+            ctx.ui.notify(`Actor inspect item ${sequence}`, "info");
+        },
+    });
+    pi.on("before_agent_start", async (event) => ({
+        systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
+    }));
+    pi.registerTool(Tools.createRegisterToolDefinition({
+        configPath: CONFIG_PATH,
+        getActiveTools: () => pi.getActiveTools(),
+        getExternalToolConflict: runtime.getExternalToolConflict,
+        getTools: runtime.getTools,
+        notify: runtime.notify,
+        registerRuntimeTool: runtime.registerRuntimeTool,
+        reservedToolNames: RESERVED_TOOL_NAMES,
+        setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
+    }));
+    pi.registerTool(Tools.createSpawnToolDefinition());
+    pi.registerTool(Tools.createActorMessageToolDefinition({
+        getTool: (name) => actorToolDefinitions.get(name),
+    }));
+    pi.registerTool(Tools.createInspectToolDefinition({
+        getTool: (name) => actorToolDefinitions.get(name),
+    }));
+}

package/dist/lib/actor-rooms.d.ts

@@ -67,6 +67,7 @@ export declare function readBranchInboxMessages(stateDir: string, run: string, a
     queued_at?: string;
     status?: string;
 }>;
+export declare function getBranchInboxTerminalRetainLimit(): number;
 export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
 export declare function updateBranchInboxMessageStatus(stateDir: string, run: string, address: string, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
 export declare function appendRoomMessage(stateDir: string, room: string, message: ActorMessage): RoomAppendResult;

package/dist/lib/actor-rooms.js

@@ -9,6 +9,7 @@ import * as path from "node:path";
 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;
 function roomDir(stateDir, room) {
     return path.join(stateDir, "rooms", room);
@@ -151,6 +152,16 @@ function readJsonlLineCount(file) {
         fs.closeSync(fd);
     }
 }
+function readRoomMessageCount(stateDir, room) {
+    try {
+        return readJsonlLineCount(messagesFile(stateDir, room));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+}
 function readJsonlTailLines(file, limit) {
     const lineLimit = Math.max(1, limit);
     const stat = fs.statSync(file);
@@ -265,6 +276,18 @@ export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
         throw error;
     }
 }
+export function getBranchInboxTerminalRetainLimit() {
+    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(messages) {
+    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, run, address, message) {
     const branch = branchIdFromAddress(address, run);
     if (!branch)
@@ -295,7 +318,8 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
         });
         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 {
@@ -318,7 +342,7 @@ export function appendRoomMessage(stateDir, room, message) {
             }
         }
         return {
-            message_count: readRoomMessages(stateDir, room).length,
+            message_count: readRoomMessageCount(stateDir, room),
             room,
             roster_count: Object.keys(roster).length,
             sent: true,
@@ -361,14 +385,7 @@ export function readRoomMessagePreviews(stateDir, room, limit = 40) {
     }));
 }
 export function getRoomStatus(stateDir, room) {
-    let messageCount = 0;
-    try {
-        messageCount = readJsonlLineCount(messagesFile(stateDir, room));
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
+    const messageCount = readRoomMessageCount(stateDir, room);
     const [last] = readRoomMessages(stateDir, room, 1);
     return {
         ...(last
@@ -388,7 +405,7 @@ export function ensureRoomMember(stateDir, run, room, address, body, summary) {
     const roster = readRoomRoster(stateDir, room);
     if (roster[address]) {
         return {
-            message_count: readRoomMessages(stateDir, room).length,
+            message_count: readRoomMessageCount(stateDir, room),
             room,
             roster_count: Object.keys(roster).length,
             sent: true,

package/dist/lib/async-runs.d.ts

@@ -6,8 +6,13 @@
 import type { CommandTemplateFailureScope, CommandTemplateValue } from "./command-templates.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 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;
@@ -72,6 +77,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";
@@ -96,6 +102,16 @@ export declare function appendRunOutboxEvent(runOrDir: string, event: {
     to?: string;
     type?: string;
 }): Record<string, unknown>;
-export declare function sendRunMessage(runOrDir: string, message: string): Record<string, unknown>;
+export interface SendRunMessageOptions {
+    namedPipeSend?: (path: string, payload: string) => Promise<number>;
+    platform?: NodeJS.Platform;
+}
+export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
+export interface RunProcessSignalPlan {
+    args?: string[];
+    command?: string;
+    signalTarget: "processGroup" | "process" | "processTree";
+}
+export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
 export declare function killRun(runOrDir: string): Record<string, unknown>;