@llblab/pi-actors 0.41.0 → 0.41.1

package/AGENTS.md

@@ -70,7 +70,7 @@ Pi host
 
 - Prefer explicit operator action over silent user-config rewrites.
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
-- Preserve runtime output discipline because tool output flows directly into agent context.
+- Preserve runtime output discipline because tool output flows directly into agent context. Tool result/error text contributes exactly one leading line break; Pi's renderer contributes the other break after the call header, producing one empty separator row without doubled gaps.
 - Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
 - Split broad domains proactively when the current name becomes a generic bucket. Prefer concise domain names that match actual ownership. `tools.ts` is the public tool family owner; decomposed tool subdomains use `tools-<part>.ts` (`tools-message.ts`, `tools-inspect.ts`, `tools-spawn.ts`) under that family. Keep only genuinely cross-family domains unprefixed (`schema.ts`); tool-only helpers stay under `tools-*`. If a `tools-*` helper becomes reused by non-tools domains, remove the `tools-` prefix in the same slice and update ownership comments/imports so the name matches its broader responsibility. Avoid redundant internal `actor-` file prefixes in this actor-scoped package unless the file is deliberately tied to a public actor-named recipe/script/docs surface.
 - Until a stable release greater than `1.x.x`, favor context compression over compatibility shims: do not preserve legacy actor-facing names, aliases, fields, env vars, paths, or docs solely for backward compatibility when a clearer current term exists. Remove compatibility layers in the same slice that renames a concept, and record the break in `CHANGELOG.md`.
@@ -107,7 +107,7 @@ Pi host
 - Preserve node controls: `when`, positive `timeout`, `delay`, bounded `retry`, `failure`, and `recover` cleanup.
 - Persist every async command's complete byte-exact stdout/stderr under command- and retry-specific run-state paths while keeping returned tails bounded and pipeline stdin complete.
 - Keep async run state under `~/.pi/agent/tmp/pi-actors/runs` with injected `{run_id}` and `{state_dir}` values.
-- Preserve event-driven observability: durable retrying terminal follow-up notifications, coordinator-bound outbox messages, branch-aware triangles, process-tree expansion, and bounded body previews. Queue coordinator context through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window.
+- Preserve event-driven observability with bounded reconciliation: file watchers accelerate durable retrying terminal follow-up notifications, while a conservative terminal-only interval recovers missed watcher activity, rearms degraded watchers, and never replays outbox traffic. Queue coordinator context through Pi follow-up delivery rather than steering so current work finishes before async results arrive and host follow-up batching policy can combine concurrent completions. Terminal delivery is at-least-once across the unavoidable send/handled-marker crash window; watch-triggered and periodic delivery share one live-runtime in-flight guard.
 - When a deferred actor result gates the next step, wait for its terminal follow-up. Do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs; inspect early only on operator request, meaningful actor event, or diagnosis of an overdue/stuck run.
 - Do not restore busy-polling examples, duplicate terminal notifications, or duplicate notifications for handled `cancel`, `kill`, or control-stop actions.
 

package/BACKLOG.md

@@ -43,25 +43,6 @@ Non-goals:
 
 - [ ] Add a manually invoked command that launches an agent-led consolidation cycle over `~/.pi/agent/recipes/drafts`. The cycle must inventory and classify every draft, propose a complete `promote`, `merge`, or `discard` plan, require explicit operator confirmation before mutations, normalize approved reusable capabilities into active recipe-backed tools under `~/.pi/agent/recipes`, and remove every handled source so the drafts directory finishes empty. It must never run automatically or promote tools silently; preserve evidence for each decision and add regressions for plan-only, confirmation, promotion, merge, discard, failure recovery, and empty-directory completion.
 
-### Overlay actor inspector
-
-- [ ] Replace the command-driven inspector workflow with one large keyboard-driven overlay while preserving the compact striped information design. Stop conditions: `/actors-inspector-toggle` only toggles the overlay; an operator can select an owned run and subagent, switch `Messages` / `Turns` tabs, navigate rows, open/close detail, scroll bounded content, and understand keys/current scope without entering subcommands.
-  - [x] Close the dogfood security prerequisites: reset selection across Pi sessions, revalidate ownership before every selected-run read, contain session evidence beneath the owned run state, broaden structured/text redaction, and add regressions.
-  - [x] Build the centered responsive overlay shell with bordered header/footer, tabs, owned-run/subagent selector, active-scope summary, empty/loading/error states, and Escape close.
-  - [x] Move compact striped Messages rows, filters, unread filtering/attention markers, roster context, and row detail into keyboard navigation.
-  - [x] Move Turns rows and full bounded provenance/tool detail into keyboard navigation with scrolling and explicit persisted/unavailable reasoning labels.
-  - [x] Remove the subcommand grammar and below-editor widget lifecycle, retain only the toggle command, and document discoverable key hints plus responsive behavior.
-  - [ ] Run full package, conformance, and context validation, then close this item. Component input/render/width/scroll/tab/ownership/live-refresh regressions and iterative manual TUI dogfood now cover the accepted visual interaction contract.
-
-### Inspector execution observability
-
-- [x] Consolidate the actor inspector into one manually opened, navigable operator surface for communication and execution evidence. Stop conditions: an operator can choose an owned run/subagent, switch between communication and turn timelines, open one bounded detail view, and inspect every persisted user/assistant/tool-result turn in source order without exposing another session or claiming unavailable hidden reasoning.
-  - [x] Persist deterministic Pi session provenance for each child `pi -p` command under its owned run state, without overriding an explicitly supplied session policy; record the session path in command evidence and tolerate commands that never create a session.
-  - [x] Add a resilient, bounded session-evidence reader that follows the active JSONL entry branch, groups assistant responses with correlated tool calls/results into turns, preserves model/usage/error metadata, redacts sensitive argument/content fields, and reports malformed or incomplete evidence honestly.
-  - [x] Replace communication-specific inspector controller state with a shared navigation model: run selector → `communication` or `turns` timeline → numbered detail, with stable back/toggle/filter behavior and useful empty states for actors that never send messages.
-  - [x] Render compact turn rows and bounded manual detail views for effective prompt/context references, assistant text, host-exposed thinking blocks, tool arguments/results, model/usage, and source-file provenance; label missing reasoning as unavailable rather than inferred.
-  - [x] Add ownership, truncation, redaction, malformed JSONL, active-branch ordering, tool correlation, parallel tool completion, terminal run, coordinator-launched subagent, and communication-navigation regressions; update the Actors skill and inspector documentation after the interaction contract stabilizes.
-
 ## Backlog Curation Rules
 
 - Completed work belongs in `CHANGELOG.md`, not in `BACKLOG.md`.

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.41.1: Actor Inspector and Delivery Hotfix
+
+- `Terminal Delivery`: Added bounded ten-second terminal reconciliation and watcher rearm so owned terminal follow-ups converge without reload when file watching misses or fails. Delivery still uses Pi follow-ups with owner filtering, `triggerTurn`, no historical outbox replay, and the existing at-least-once handled-marker contract; routine run-directory removal stays quiet while real watcher degradation remains diagnostic.
+- `Actor Inspector`: Finished the 0.41 overlay line around a compact meaning-first workflow. `/actors-inspector` now opens the latest numbered Run; Run, Message, and Turn lists show newest evidence first; bounded menus remain usable on short terminals; and humanized Turn rows lead into wrapped Evidence and a metadata-free readable transcript. Turn content now prioritizes User, Thinking, Assistant, and tool actions before Execution and Provenance, strips prompt transport wrappers in readable mode, keeps logical sections on one stripe, and removes false wraps, clipped values, redundant labels/separators, and blank rows.
+- `Tool Output`: Normalized successful results and errors to contribute exactly one leading line break, preserving one empty separator row beneath Pi's rendered tool-call header without occasional double gaps.
+- `Agent Guidance`: Kept Inspector behavior in user documentation and removed it from the bundled Actors skill, leaving that skill focused on agent-operational `spawn`, `message`, `inspect`, recipes, and lifecycle guidance.
+
 ## 0.41.0: Actor Inspector Overlay and Execution Observability
 
 - `[Inspector Menu Alignment]` Shifted value submenus one cell left so adjacent levels share a border, aligned Run and tab labels to one vertical grid, and made the Run dropdown begin immediately below Run by overlaying the tab row. Impact: nested menus read as one connected hierarchy and every top-level control follows the same anchored dropdown rhythm.

package/dist/index.js

@@ -19,8 +19,10 @@ export default function toolRegistryExtension(pi) {
     let runsAnimationInterval;
     let runsNotifyTimeout;
     let activeRunContext;
+    let lastRunWatcherDiagnosticId = 0;
     const runUi = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
+    const terminalNotificationsInFlight = new Set();
     const getRunOwnerId = Pi.getSessionId;
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
@@ -38,7 +40,7 @@ export default function toolRegistryExtension(pi) {
             return;
         const notificationSink = Pi.createNotificationSink(pi, ctx);
         retireCandidateRuns(ctx, snapshot.summary);
-        Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink);
+        Observability.deliverRunTransitionNotifications(snapshot.transitions, notificationSink, terminalNotificationsInFlight);
         Observability.pruneRunUiObservationState(runUi, snapshot);
         if (!terminalOnly) {
             Observability.deliverRunOutboxNotifications(snapshot.outboxEvents, notificationSink);
@@ -46,22 +48,57 @@ export default function toolRegistryExtension(pi) {
     };
     const closeRunWatchers = () => {
         runWatcher.close();
+        terminalReconciliation.close();
         if (runsNotifyTimeout)
             clearTimeout(runsNotifyTimeout);
         runsNotifyTimeout = undefined;
     };
-    const scheduleRunEventUpdate = (ctx) => {
+    const reportRunWatcherDiagnostics = (ctx) => {
+        for (const diagnostic of runWatcher.getDiagnostics()) {
+            if (diagnostic.id <= lastRunWatcherDiagnosticId)
+                continue;
+            lastRunWatcherDiagnosticId = diagnostic.id;
+            ctx.ui.notify(diagnostic.message, diagnostic.code === "rearmed" ? "info" : "warning");
+        }
+    };
+    const scheduleRunEventUpdate = () => {
         if (runsNotifyTimeout)
             clearTimeout(runsNotifyTimeout);
         runsNotifyTimeout = setTimeout(() => {
+            const ctx = activeRunContext;
+            if (!ctx)
+                return;
             runWatcher.refresh();
             updateRunUi(ctx, true);
+            reportRunWatcherDiagnostics(ctx);
         }, 50);
         runsNotifyTimeout.unref?.();
     };
     const runWatcher = Observability.createRunStateWatcher({
         stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-        onChange: () => activeRunContext && scheduleRunEventUpdate(activeRunContext),
+        onChange: scheduleRunEventUpdate,
+    });
+    const terminalReconciliation = Observability.createRunTerminalReconciliationLoop({
+        onError: (error) => {
+            const ctx = activeRunContext;
+            if (!ctx)
+                return;
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+        },
+        reconcile: () => {
+            const ctx = activeRunContext;
+            if (!ctx)
+                return;
+            Observability.reconcileRunTerminalNotifications({
+                inFlight: terminalNotificationsInFlight,
+                ownerId: getRunOwnerId(ctx),
+                sink: Pi.createNotificationSink(pi, ctx),
+                state: runUi,
+            });
+            reportRunWatcherDiagnostics(ctx);
+        },
+        refreshWatcher: () => runWatcher.refresh(),
     });
     const actorToolDefinitions = new Map();
     const withCurrentThinkingContext = (definition) => {
@@ -111,16 +148,22 @@ export default function toolRegistryExtension(pi) {
         // Clear the pre-overlay widget after hot reloads from older pi-actors builds.
         ctx.ui.setWidget("zz-pi-actors-comms", undefined);
         activeRunContext = ctx;
+        closeRunWatchers();
+        recipeReload.close();
         await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
+        if (activeRunContext !== ctx)
+            return;
         runtime.loadTools(ctx);
         updateRunUi(ctx, true, true);
-        closeRunWatchers();
-        recipeReload.close();
         runWatcher.refresh();
+        terminalReconciliation.start();
         recipeReload.watch(ctx);
         if (runsAnimationInterval)
             clearInterval(runsAnimationInterval);
-        runsAnimationInterval = setInterval(() => updateRunUi(ctx, false), 1000);
+        runsAnimationInterval = setInterval(() => {
+            if (activeRunContext === ctx)
+                updateRunUi(ctx, false);
+        }, 1000);
         runsAnimationInterval.unref?.();
     });
     pi.on("session_shutdown", async () => {
@@ -131,8 +174,8 @@ export default function toolRegistryExtension(pi) {
         closeRunWatchers();
         recipeReload.close();
     });
-    pi.registerCommand("actors-inspector-toggle", {
-        description: "Toggle the keyboard-driven actor inspector overlay",
+    pi.registerCommand("actors-inspector", {
+        description: "Open the keyboard-driven actor inspector overlay",
         handler: async (_args, ctx) => {
             ctx.ui.setWidget("zz-pi-actors-comms", undefined);
             await ctx.ui.custom((tui, theme, _keybindings, done) => new InspectorOverlay.ActorInspectorOverlay({

package/dist/lib/inspector-overlay.d.ts

@@ -29,6 +29,7 @@ export declare class ActorInspectorOverlay {
     private detailOpen;
     private detailScroll;
     private detailTurn?;
+    private detailView;
     private readonly readKeys;
     private focus;
     private filterControlIndex;
@@ -45,6 +46,9 @@ export declare class ActorInspectorOverlay {
     dispose(): void;
     private runs;
     private ensureSelectedRun;
+    private contentViewportRows;
+    private selectRun;
+    private cycleRun;
     private listItemCount;
     private selectorAnchor;
     private renderKeyHints;
@@ -58,6 +62,12 @@ export declare class ActorInspectorOverlay {
     private communicationFromOptions;
     private communicationRows;
     private renderDetail;
+    private wrapDetailLines;
+    private detailSection;
+    private readableValueLines;
+    private turnEvidenceLines;
+    private readablePromptText;
+    private turnTranscriptLines;
     private turnItems;
     private turnRows;
     private subagents;
@@ -73,6 +83,7 @@ export declare class ActorInspectorOverlay {
     private renderMenuBox;
     private renderFilterMenus;
     private openDetail;
+    private backDetail;
     private closeDetail;
     private border;
     private stripeBackground;