@llblab/pi-actors 0.40.0 → 0.41.0

package/docs/actor-inspector.md

@@ -0,0 +1,72 @@
+# Actor Inspector
+
+The actor inspector is a manually opened, read-only TUI navigator for owned actor runs. It keeps communication evidence and persisted subagent execution evidence in one hierarchy without merging their meanings.
+
+```text
+owned run
+  → messages | turns
+    → filtered timeline
+      → bounded detail
+```
+
+## Navigation
+
+`/actors-inspector-toggle` opens one centered overlay and remains the only command to remember. The first run owned by the current Pi session becomes the active run automatically; an empty session still exposes functional tabs and filters.
+
+The overlay exposes an explicit focus hierarchy:
+
+```text
+Run       Enter opens owned runs, ↓ enters tabs
+Tabs      ←/→ chooses Messages or Turns, Enter opens filter parameters
+Filters   ↑/↓ chooses Channel/State or Subagent, Enter opens values to the right
+Values    ↑/↓ hovers, Enter applies, Escape returns one menu level
+List      ↑/↓ chooses, Enter/→ opens detail
+Detail    ↑/↓ scroll, Escape/← returns
+Escape    Close (or cancel the active options popup)
+```
+
+Navigation stays bounded by available actions. `↑` on Run does nothing because no higher control exists. `↓` on Tabs enters the timeline only when it contains rows. Empty timelines therefore never receive focus.
+
+Selection and focus remain separate visual states. Accent-blue text marks the current tab, active filter popup, and applied option. A light neutral background plus `▶` marks every selectable control or timeline row that currently owns keyboard focus. Opening a popup keeps its parent filter blue so the relationship remains visible. The footer uses accent color only for key names and arrows; descriptions remain muted.
+
+The top Run control aligns vertically with the tab labels, names the selected owned run, and colors its textual lifecycle status semantically. Enter opens available owned runs immediately beneath it, overlaying the tab row rather than leaving a detached gap. The timeline no longer renders run metadata as a data row.
+
+Filters live behind their tab rather than occupying a permanent row. Non-default filters remain visible as compact suffixes in the tab label, so hidden state never silently changes the timeline. Enter on Messages opens `Channel: <current>`, `State: <current>`, and `From: <current>`; `From` draws its values from the selected run's roster and limits rows to one actor. Enter on Turns opens `Subagent: <current>`. Enter on a parameter opens its alternative values as a second menu to the right while the parent and current value remain visible. Parent and child share their touching border rather than leaving or doubling a spacer column. Escape returns one level at a time. Moving focus never applies a value.
+
+Nested menus overlay rather than replace the timeline. Only rows and columns containing menu borders or values occlude underlying cells. When adjacent menus have different heights, the unused corner remains transparent and preserves the separator, striped background, and timeline data beneath it.
+
+The overlay uses most of the available terminal width and height. The bordered header keeps both tabs visible, while the list body shows the selected run and its current status above the evidence rows. Evidence rows retain stable alternating backgrounds based on their absolute timeline position, including while scrolling: even rows keep the dark overlay background, while odd rows use the neutral `customMessageBg` stripe. The footer exposes the active keys. Messages retain attention markers and unread filtering and open into bounded detail without leaving the overlay. The overlay refreshes while visible and distinguishes true empty timelines from filtered-empty results; filtered-empty copy points back to Enter on the active tab without moving focus.
+
+## Communication Timeline
+
+The communication timeline reads run-local room, direct, branch-inbox, and coordinator/session message evidence. It preserves channel/sender filters, unread state, attention markers, roster-derived sender options, and bounded body previews. Unread remains filterable but does not consume a row column with a separate dot marker.
+
+Communication evidence describes messages between actors. It does not prove model execution.
+
+## Turns Timeline
+
+Detached child `pi -p` commands receive isolated session storage under their owned run state:
+
+```text
+<run-state>/sessions/command-NNN/*.jsonl
+```
+
+The runner records direct command-template session files in `review-evidence.json`. Coordinator-managed room/swarm participants also persist role/phase-scoped directories under the same `sessions/` root; the inspector discovers those owned files even though the coordinator, rather than the command-template runner, launched them. Explicit caller session policy (`--no-session`, `--session`, `--session-id`, `--session-dir`, or `--fork`) remains authoritative and is not replaced. A command may therefore have no inspector-visible session.
+
+The turns timeline follows the latest persisted entry branch in each recorded Pi session and groups:
+
+- User input associated with the response;
+- Assistant text and host-persisted thinking blocks;
+- Provider, model, stop reason, usage, and error metadata;
+- Tool calls in assistant source order;
+- Tool results correlated by `toolCallId`, regardless of completion order.
+
+Enter opens the selected turn inside the overlay. Detail adds command/stage identity, session and prompt paths, recipe-context reference, tool arguments/results, truncation state, unmatched result counts, and parse diagnostics. ↑/↓ scroll long detail while the footer keeps return/close keys visible.
+
+## Evidence And Privacy Boundary
+
+The inspector reads file-backed evidence; it does not reconstruct hidden provider reasoning or claim access to data Pi did not persist. When no explicit thinking block exists, detail shows `reasoning unavailable`.
+
+Session text, communication bodies, and structured values remain bounded. Common secret-bearing keys, camelCase/private-key credentials, serialized JSON credentials, and inline credential patterns are redacted before rendering. Malformed JSONL lines, missing parents, cycles, missing sessions, and incomplete tool correlation remain diagnostic states rather than inferred data.
+
+Ownership filtering happens before run summaries, communication previews, roster data, or session evidence become visible. Selection and read state reset across Pi sessions. Manifest session paths must resolve canonically beneath the selected owned run's `sessions/` directory; absolute paths, traversal, and symlink escapes remain invisible. The inspector never scans another coordinator session's run state into the current view.

package/docs/async-runs.md

@@ -216,9 +216,9 @@ Runtime wake notifications are now modeled separately from durable queues. Messa
 
 ## Coordinator Notifications
 
-The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and steers terminal `done`/`failed`/unhandled `killed`/`exited` transitions back to the owning session with `triggerTurn: true`; a busy coordinator receives completion at the next safe tool boundary, while an idle coordinator starts a normal turn without a racy manual idle check. Script-authored `notify`/`followup` actor messages still follow their declared outbox delivery policy. Terminal notifications include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble according to outbox policy, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Intentional `control.kill` and recipe-local stop commands stay out of coordinator context because the initiating message already returns synchronously or is handled by actor-local policy. If a notification asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered notification requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
+The launching coordinator should not busy-poll long-running async runs. The extension watches run state directories and queues terminal `done`/`failed`/unhandled `killed`/`exited` transitions back to the owning session through Pi's `followUp` delivery mode with `triggerTurn: true`; a busy coordinator finishes its current work before queued actor results arrive, while an idle coordinator starts a normal turn without a racy manual idle check. Pi's configured `followUpMode` determines whether concurrently queued results arrive together or one at a time. Script-authored `notify`/`followup` actor messages still follow their declared outbox delivery policy. Terminal notifications include recipe-level named `artifacts` when declared. The generic runner also emits compact `command.done` actor messages for completed leaf commands; recipe authors declare that capability in `mailbox.emits` rather than configuring a separate delivery policy. Failures and in-flight parallel branch completions can bubble according to outbox policy, while successful final leaf completions stay diagnostic to avoid flooding long sequential pipelines. Intentional `control.kill` and recipe-local stop commands stay out of coordinator context because the initiating message already returns synchronously or is handled by actor-local policy. If a notification asks for direction, answer with `message` rather than starting a polling loop. Use explicit `inspect` only when a delivered notification requests inspection, a real decision depends on state, or a suspected stuck run needs diagnosis — never merely because a timeout elapsed.
 
-Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. An owned terminal run without `terminal-handled.json` remains retry-eligible during same-runtime and extension/session replacement reconciliation; the marker is written only after successful steering delivery, and initial reconciliation does not replay historical outbox traffic. This is an at-least-once contract: a process crash after send but before marker persistence can produce a duplicate notification, while a failed send remains durably retryable. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
+Ambient status indicators may refresh while work is active, but coordinator attention is driven from run-state changes rather than a coordinator agent loop. This lets the coordinator continue other work after `spawn`; the run signals back through lifecycle state, results, and actor messages. An owned terminal run without `terminal-handled.json` remains retry-eligible during same-runtime and extension/session replacement reconciliation; the marker is written only after successful follow-up delivery, and initial reconciliation does not replay historical outbox traffic. This is an at-least-once contract: a process crash after send but before marker persistence can produce a duplicate notification, while a failed send remains durably retryable. The ambient triangle count represents active async work units: each running async run contributes at least one triangle, and a run with multiple active parallel command/subagent branches contributes the reported active branch count. If a coordinator starts one parent run with four active parallel branches, four triangles are shown; if the same coordinator starts five independent single-branch runs, five triangles are shown.
 
 ## Run Actor Messages
 

package/index.ts

@@ -7,7 +7,7 @@
 
 import * as AsyncRuns from "./lib/async-runs.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
-import * as Inspector from "./lib/inspector.ts";
+import * as InspectorOverlay from "./lib/inspector-overlay.ts";
 import * as Observability from "./lib/observability.ts";
 import * as Paths from "./lib/paths.ts";
 import * as Pi from "./lib/pi.ts";
@@ -15,6 +15,7 @@ import * as Prompts from "./lib/prompts.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Temp from "./lib/temp.ts";
 import * as Tools from "./lib/tools.ts";
+import * as ToolsResponse from "./lib/tools-response.ts";
 
 export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   let runsAnimationInterval: NodeJS.Timeout | undefined;
@@ -22,7 +23,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   let activeRunContext: Pi.ExtensionContext | undefined;
   const runUi = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
-  const actorInspector = Inspector.createActorInspectorControllerState();
   const getRunOwnerId = Pi.getSessionId;
   const retireCandidateRuns = (
     ctx: Pi.ExtensionContext,
@@ -47,33 +47,6 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
       "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: number) {
-              return Inspector.renderActorInspectorPanel({
-                stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-                state: actorInspector,
-                ownerId,
-                width,
-                style: {
-                  actor: (text: string) => ctx.ui.theme.fg("accent", text),
-                  muted: (text: string) => ctx.ui.theme.fg("dim", text),
-                  preview: (text: string) => ctx.ui.theme.fg("text", text),
-                  stripe: (text: string) => text,
-                  stripeAlt: (text: string) =>
-                    ctx.ui.theme.bg("customMessageBg", text),
-                  target: (text: string) => ctx.ui.theme.fg("success", text),
-                  type: (text: string) => ctx.ui.theme.fg("warning", text),
-                },
-              });
-            },
-          })
-        : undefined,
-      { placement: "belowEditor" },
-    );
     if (!notify) return;
     const notificationSink = Pi.createNotificationSink(pi, ctx);
     retireCandidateRuns(ctx, snapshot.summary);
@@ -115,7 +88,7 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     const execute = definition.execute as (...args: unknown[]) => unknown;
     return {
       ...definition,
-      execute: (...args: unknown[]) => {
+      execute: async (...args: unknown[]) => {
         const nextArgs = [...args];
         const ctx = nextArgs[4];
         if (ctx && typeof ctx === "object") {
@@ -124,7 +97,11 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
             getThinkingLevel: () => pi.getThinkingLevel(),
           };
         }
-        return execute(...nextArgs);
+        try {
+          return ToolsResponse.spaceToolResult(await execute(...nextArgs));
+        } catch (error) {
+          throw ToolsResponse.spaceToolError(error);
+        }
       },
     } as T;
   };
@@ -147,6 +124,8 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     return { skillPaths };
   });
   pi.on("session_start", async (_event, ctx) => {
+    // Clear the pre-overlay widget after hot reloads from older pi-actors builds.
+    ctx.ui.setWidget("zz-pi-actors-comms", undefined);
     activeRunContext = ctx;
     await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
     runtime.loadTools(ctx);
@@ -167,39 +146,29 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
     recipeReload.close();
   });
   pi.registerCommand("actors-inspector-toggle", {
-    description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.toggle,
-    handler: async (args, ctx) => {
-      const result = Inspector.handleActorInspectorToggle(actorInspector, args);
-      if (result.update) updateRunUi(ctx);
-      ctx.ui.notify(result.notify, result.type);
-    },
-  });
-  pi.registerCommand("actors-inspector-filter", {
-    description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.filter,
-    handler: async (args, ctx) => {
-      const result = Inspector.handleActorInspectorFilter(actorInspector, args);
-      if (result.update) updateRunUi(ctx);
-      ctx.ui.notify(result.notify, result.type);
-    },
-  });
-  pi.registerCommand("actors-inspect", {
-    description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.inspect,
-    handler: async (args, ctx) => {
-      const previews = Inspector.readActorInspectorPreviews(
-        Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
-        actorInspector.rows,
-        Inspector.getActorInspectorPreviewOptions(
-          actorInspector,
-          getRunOwnerId(ctx),
-        ),
-      );
-      const result = Inspector.handleActorInspectorInspect(
-        actorInspector,
-        args,
-        previews,
+    description: "Toggle the keyboard-driven actor inspector overlay",
+    handler: async (_args, ctx) => {
+      ctx.ui.setWidget("zz-pi-actors-comms", undefined);
+      await ctx.ui.custom<void>(
+        (tui, theme, _keybindings, done) =>
+          new InspectorOverlay.ActorInspectorOverlay({
+            done,
+            ownerId: getRunOwnerId(ctx),
+            stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
+            theme,
+            tui,
+          }),
+        {
+          overlay: true,
+          overlayOptions: {
+            anchor: "center",
+            width: "94%",
+            minWidth: 72,
+            maxHeight: "94%",
+            margin: 1,
+          },
+        },
       );
-      if (result.update) updateRunUi(ctx);
-      ctx.ui.notify(result.notify, result.type);
     },
   });
   pi.on("before_agent_start", async (event) => ({