@llblab/pi-actors 0.20.0 → 0.20.2

package/BACKLOG.md

@@ -2,6 +2,39 @@
 
 ## Open Work
 
+### Branch Inbox Retention and Transition Scaling
+
+- Priority: Medium.
+- Goal: Keep direct branch message queues reliable for long-lived interactive branch runners without unbounded rewrite amplification.
+- Direction:
+  - Evaluate current whole-file branch inbox status rewrites under realistic long-lived direct-message workloads.
+  - Consider bounded retention, compaction, or append-only transition logs for `queued` / `claimed` / `handled` / `failed` state changes while preserving stable message IDs and exact-once claim semantics.
+  - Keep branch-local inbox append/status mutations lock-guarded and preserve inspector visibility for unread/current-branch filters.
+- Exit:
+  - A documented decision or implementation explains how branch inboxes scale for persistent runners and proves existing direct-message semantics remain compatible.
+
+### Installed Recipe Trust Boundary Hardening
+
+- Priority: Medium.
+- Goal: Keep recipe-library growth local-first without letting operator muscle memory become an accidental sandbox bypass.
+- Direction:
+  - Review packaged recipes, examples, and docs for destructive or external side effects and ensure they require explicit paths, typed args, narrow helper scripts, and clear operator gates.
+  - Keep warnings framed as diagnostics, not a security boundary.
+  - Prefer small audited helper scripts over broad shell templates when recipes touch files, processes, networks, or external services.
+- Exit:
+  - A trust-boundary review confirms packaged recipes and docs preserve the current local-first/not-sandbox-first contract, with any needed hardening captured in tests or docs.
+
+### Direct Branch Message Consumption Semantics
+
+- Priority: Medium.
+- Goal: Make it impossible to misunderstand branch inbox delivery as universal active delivery without a consuming coordinator or runner protocol.
+- Direction:
+  - Audit README, actor-message docs, async-run docs, actors skill, and recipe guidance for branch inbox wording.
+  - Clarify that direct branch messages are queued and become active work only when the relevant coordinator/runner claims, injects, handles, or fails them.
+  - Add or update a bounded smoke scenario that demonstrates queued direct messages, claim/handle transitions, and inspector visibility.
+- Exit:
+  - Public docs and tests show both halves of direct branch delivery: durable branch-local queueing and explicit worker consumption semantics.
+
 ### Actor Rooms, Roster, and Cross-Branch Messaging
 
 - Priority: High.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- `[Tests]` Added installed-package validation coverage for a user recipe that imports a packaged recipe by bare name, preserving the documented priority order for user, adjacent, and packaged recipes.
+- `[Package]` Bumped package metadata and packaged skill metadata to `0.20.1` for the hotfix release.
+
 ## 0.20.0: Compiled Runtime Entrypoints
 
 - `[Packaging]` Added a build step that emits compiled `dist/lib/*.js` and declaration files from the TypeScript runtime modules, with relative `.ts` imports rewritten to `.js` for installed package execution.

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,374 @@
+/**
+ * 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 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();
+    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 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;
+        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.js

@@ -151,6 +151,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);
@@ -318,7 +328,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 +371,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 +391,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/paths.js

@@ -3,6 +3,7 @@
  * Zones: paths, registry config, temp directory
  * Owns agent directory, tools config, recipe root, and actor run state root resolution
  */
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -24,5 +25,9 @@ export function getRecipeRoot(agentDir = getAgentDir()) {
     return join(agentDir, "recipes");
 }
 export function getPackagedRecipeRoot() {
-    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "recipes");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const compiledRoot = resolve(here, "..", "..", "recipes");
+    if (existsSync(compiledRoot))
+        return compiledRoot;
+    return resolve(here, "..", "recipes");
 }

package/index.js

@@ -0,0 +1,19 @@
+/**
+ * Runtime extension entrypoint wrapper.
+ *
+ * Installed npm packages load compiled JS from dist so Node does not try to strip
+ * TypeScript under node_modules. Source checkouts fall back to index.ts for local
+ * development before dist has been built.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const compiledEntry = resolve(here, "dist", "index.js");
+const sourceEntry = resolve(here, "index.ts");
+const entry = existsSync(compiledEntry) ? compiledEntry : sourceEntry;
+const entryModule = await import(pathToFileURL(entry).href);
+
+export default entryModule.default;

package/lib/actor-rooms.ts

@@ -241,6 +241,15 @@ function readJsonlLineCount(file: string): number {
   }
 }
 
+function readRoomMessageCount(stateDir: string, room: string): number {
+  try {
+    return readJsonlLineCount(messagesFile(stateDir, room));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return 0;
+    throw error;
+  }
+}
+
 function readJsonlTailLines(file: string, limit: number): string[] {
   const lineLimit = Math.max(1, limit);
   const stat = fs.statSync(file);
@@ -446,7 +455,7 @@ export function appendRoomMessage(
       }
     }
     return {
-      message_count: readRoomMessages(stateDir, room).length,
+      message_count: readRoomMessageCount(stateDir, room),
       room,
       roster_count: Object.keys(roster).length,
       sent: true,
@@ -496,12 +505,7 @@ export function readRoomMessagePreviews(
 }
 
 export function getRoomStatus(stateDir: string, room: string): RoomStatus {
-  let messageCount = 0;
-  try {
-    messageCount = readJsonlLineCount(messagesFile(stateDir, room));
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
+  const messageCount = readRoomMessageCount(stateDir, room);
   const [last] = readRoomMessages(stateDir, room, 1);
   return {
     ...(last
@@ -529,7 +533,7 @@ export function ensureRoomMember(
   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/lib/paths.ts

@@ -4,6 +4,7 @@
  * Owns agent directory, tools config, recipe root, and actor run state root resolution
  */
 
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -36,5 +37,8 @@ export function getRecipeRoot(agentDir = getAgentDir()): string {
 }
 
 export function getPackagedRecipeRoot(): string {
-  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "recipes");
+  const here = dirname(fileURLToPath(import.meta.url));
+  const compiledRoot = resolve(here, "..", "..", "recipes");
+  if (existsSync(compiledRoot)) return compiledRoot;
+  return resolve(here, "..", "recipes");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -33,6 +33,7 @@
     "prepack": "npm run build"
   },
   "files": [
+    "index.js",
     "index.ts",
     "lib",
     "scripts",
@@ -48,7 +49,7 @@
   ],
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./index.js"
     ],
     "skills": [
       "./skills/actors/SKILL.md",
@@ -57,7 +58,8 @@
     "image": "https://github.com/llblab/pi-actors/raw/main/banner.jpg"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
     "@types/node": "latest",

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.0
+  version: 0.20.2
 ---
 
 # Actors (pi-actors)

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.0
+  version: 0.20.2
 ---
 
 # Swarm