@llblab/pi-actors 0.29.2 → 0.30.0

package/dist/index.js

@@ -4,59 +4,24 @@
  *
  * 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 { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 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 Pi from "./lib/pi.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 EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
-const EXTENSION_SKILLS_DIR = join(EXTENSION_DIR, "skills");
-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 observedRunOutboxEventIds = new Map();
+    let activeRunContext;
+    const runUi = Observability.createRunUiObservationState();
     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;
-    const actorInspectorReadKeys = new Set();
-    let recipeWatcherFailureNotified = false;
-    const getRunOwnerId = (ctx) => ctx.sessionManager.getSessionId();
+    const actorInspector = ActorInspectorTui.createActorInspectorControllerState();
+    const getRunOwnerId = Pi.getSessionId;
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
             attempted: retirementAttempts,
@@ -67,88 +32,40 @@ export default function toolRegistryExtension(pi) {
     };
     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,
-                            readKeys: actorInspectorReadKeys,
-                            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 = selectedInspectorSequence === undefined && run
-                            ? ActorInspectorTui.renderInspectorRosterPanel(ActorInspectorTui.readActorInspectorRoster(RUN_STATE_ROOT, run), width, style)
-                            : undefined;
-                        return roster ? [...roster, ...rows] : rows;
-                    },
-                };
-            }
+        const snapshot = Observability.readRunUiSnapshot(runUi, ownerId);
+        ctx.ui.setStatus("zz-pi-actors-runs", snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined);
+        ctx.ui.setWidget("zz-pi-actors-comms", actorInspector.visible
+            ? () => ({
+                invalidate() { },
+                render(width) {
+                    return ActorInspectorTui.renderActorInspectorPanel({
+                        stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+                        state: actorInspector,
+                        ownerId,
+                        width,
+                        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),
+                        },
+                    });
+                },
+            })
             : undefined, { placement: "belowEditor" });
-        const transitions = Observability.detectRunTransitions(observedRuns, summary);
-        const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary, observedRunOutboxEventIds);
         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.stateDir ?? transition.run), observedRunOutboxEventIds);
-        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 notificationSink = Pi.createNotificationSink(pi, ctx);
+        retireCandidateRuns(ctx, snapshot.summary);
+        Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink);
+        Observability.pruneRunUiObservationState(runUi, snapshot);
+        Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
     };
     const closeRunWatchers = () => {
-        stateRootWatcher?.close();
-        stateRootWatcher = undefined;
-        for (const watcher of runDirWatchers.values())
-            watcher.close();
-        runDirWatchers.clear();
+        runWatcher.close();
         if (runsNotifyTimeout)
             clearTimeout(runsNotifyTimeout);
         runsNotifyTimeout = undefined;
@@ -157,89 +74,18 @@ export default function toolRegistryExtension(pi) {
         if (runsNotifyTimeout)
             clearTimeout(runsNotifyTimeout);
         runsNotifyTimeout = setTimeout(() => {
-            refreshRunWatchers(ctx);
+            runWatcher.refresh();
             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 runWatcher = Observability.createRunStateWatcher({
+        stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+        onChange: () => activeRunContext && scheduleRunEventUpdate(activeRunContext),
+    });
     const actorToolDefinitions = new Map();
     const runtime = Runtime.createAutoToolsRuntime({
-        configPath: CONFIG_PATH,
+        configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         exec: CommandTemplates.execCommandTemplate,
         getActiveTools: () => pi.getActiveTools(),
         getAllTools: () => pi.getAllTools(),
@@ -247,22 +93,25 @@ export default function toolRegistryExtension(pi) {
             actorToolDefinitions.set(definition.name, definition);
             pi.registerTool(definition);
         },
-        reservedToolNames: RESERVED_TOOL_NAMES,
+        reservedToolNames: Tools.RESERVED_TOOL_NAMES,
         setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
     });
+    const recipeReload = Runtime.createRecipeToolReloadWatcher(runtime);
     pi.on("resources_discover", async () => {
-        if (!existsSync(EXTENSION_SKILLS_DIR))
+        const skillPaths = Paths.getExistingExtensionSkillPaths(import.meta.url);
+        if (skillPaths.length === 0)
             return;
-        return { skillPaths: [EXTENSION_SKILLS_DIR] };
+        return { skillPaths };
     });
     pi.on("session_start", async (_event, ctx) => {
-        await Temp.prepareExtensionTempDir(TEMP_DIR);
+        activeRunContext = ctx;
+        await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
         runtime.loadTools(ctx);
         updateRunUi(ctx);
         closeRunWatchers();
-        closeRecipeWatcher();
-        refreshRunWatchers(ctx);
-        watchRecipeRoot(ctx);
+        recipeReload.close();
+        runWatcher.refresh();
+        recipeReload.watch(ctx);
         if (runsAnimationInterval)
             clearInterval(runsAnimationInterval);
         runsAnimationInterval = setInterval(() => updateRunUi(ctx, false), 1000);
@@ -272,139 +121,46 @@ export default function toolRegistryExtension(pi) {
         if (runsAnimationInterval)
             clearInterval(runsAnimationInterval);
         runsAnimationInterval = undefined;
+        activeRunContext = undefined;
         closeRunWatchers();
-        closeRecipeWatcher();
+        recipeReload.close();
     });
     pi.registerCommand("actors-inspector-toggle", {
-        description: "Toggle actor inspector widget; optional row count",
+        description: ActorInspectorTui.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.toggle,
         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;
+            const result = ActorInspectorTui.handleActorInspectorToggle(actorInspector, args);
+            if (result.update)
                 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");
+            ctx.ui.notify(result.notify, result.type);
         },
     });
     pi.registerCommand("actors-inspector-filter", {
-        description: "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
+        description: ActorInspectorTui.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.filter,
         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");
+            const result = ActorInspectorTui.handleActorInspectorFilter(actorInspector, args);
+            if (result.update)
+                updateRunUi(ctx);
+            ctx.ui.notify(result.notify, result.type);
         },
     });
     pi.registerCommand("actors-inspect", {
-        description: "Inspect actor message by visible number",
+        description: ActorInspectorTui.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.inspect,
         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;
-            }
-            const previews = ActorInspectorTui.readActorInspectorPreviews(RUN_STATE_ROOT, actorInspectorRows, {
-                channels: actorInspectorChannels,
-                currentRunOnly: true,
-                branch: actorInspectorBranch,
-                mention: actorInspectorMention,
-                ownerId: getRunOwnerId(ctx),
-                readKeys: actorInspectorReadKeys,
-                roomLimitPerRun: actorInspectorRoomLimitPerRun,
-                unreadOnly: actorInspectorUnreadOnly,
-            });
-            const preview = previews.find((item) => item.sequence === sequence);
-            if (preview)
-                actorInspectorReadKeys.add(ActorInspectorTui.inspectorPreviewReadKey(preview));
-            selectedInspectorSequence = sequence;
-            communicationWidgetVisible = true;
-            updateRunUi(ctx);
-            ctx.ui.notify(`Actor inspect item ${sequence}`, "info");
+            const previews = ActorInspectorTui.readActorInspectorPreviews(Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, actorInspector.rows, ActorInspectorTui.getActorInspectorPreviewOptions(actorInspector, getRunOwnerId(ctx)));
+            const result = ActorInspectorTui.handleActorInspectorInspect(actorInspector, args, previews);
+            if (result.update)
+                updateRunUi(ctx);
+            ctx.ui.notify(result.notify, result.type);
         },
     });
     pi.on("before_agent_start", async (event) => ({
         systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,
     }));
-    pi.registerTool(Tools.createRegisterToolDefinition({
-        configPath: CONFIG_PATH,
+    Pi.registerToolDefinitions(pi, Tools.createCoreActorToolDefinitions({
+        configPath: Paths.EXTENSION_RUNTIME_PATHS.configPath,
         getActiveTools: () => pi.getActiveTools(),
-        getExternalToolConflict: runtime.getExternalToolConflict,
-        getTools: runtime.getTools,
-        notify: runtime.notify,
-        registerRuntimeTool: runtime.registerRuntimeTool,
-        reservedToolNames: RESERVED_TOOL_NAMES,
+        getRuntimeTool: (name) => actorToolDefinitions.get(name),
+        registryRuntime: runtime,
         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-inspector-tui.d.ts

@@ -50,6 +50,41 @@ export interface ActorInspectorPreviewReadOptions {
     roomLimitPerRun?: number;
     unreadOnly?: boolean;
 }
+export interface ActorInspectorControllerState {
+    branch?: string;
+    channels?: ActorInspectorPreview["channel"][];
+    mention?: string;
+    readKeys: Set<string>;
+    roomLimitPerRun: number;
+    rows: number;
+    selectedSequence?: number;
+    unreadOnly: boolean;
+    visible: boolean;
+}
+export interface ActorInspectorCommandResult {
+    notify: string;
+    type: "info" | "warning";
+    update: boolean;
+}
+export declare const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
+export declare const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS: {
+    filter: string;
+    inspect: string;
+    toggle: string;
+};
+export declare function createActorInspectorControllerState(): ActorInspectorControllerState;
+export declare function getActorInspectorPreviewOptions(state: ActorInspectorControllerState, ownerId: string): ActorInspectorPreviewReadOptions;
+export declare function handleActorInspectorToggle(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
+export declare function handleActorInspectorFilter(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
+export declare function handleActorInspectorInspect(state: ActorInspectorControllerState, args: unknown, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
+export declare function selectActorInspectorSequence(state: ActorInspectorControllerState, sequence: number, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
+export declare function renderActorInspectorPanel(input: {
+    stateRoot: string;
+    state: ActorInspectorControllerState;
+    ownerId: string;
+    width: number;
+    style: ActorInspectorWidgetStyle;
+}): string[];
 export declare function inspectorPreviewReadKey(preview: ActorInspectorPreview): string;
 export declare function readActorInspectorPreviews(stateRoot?: string, limit?: number, options?: ActorInspectorPreviewReadOptions): ActorInspectorPreview[];
 export declare function readActorInspectorRoster(stateRoot: string | undefined, run: string, room?: string): ActorInspectorRosterMember[];