@llblab/pi-actors 0.16.4 → 0.17.1

package/docs/actor-messages.md

@@ -32,7 +32,19 @@ session:<id>
 tool:<name>
 ```
 
-Future forms may include `chat:<id>` or package-specific endpoints, but the envelope stays the same.
+Cross-branch communication adds one organic endpoint kind:
+
+```text
+room:<run>
+```
+
+A room is the task's single shared discussion channel: an addressable mailbox with an append-only message log and a compact member roster stored under the owning run state. It is not a broker or coordinator: it accepts normal actor-message envelopes, records shared timeline entries, tracks join/leave presence, and lets actors discover peers for direct messages. `room:<run>` is the public address; named subrooms are intentionally not exposed in 0.17.
+
+An alternate implementation shape is a dedicated non-LLM communication actor: a small script-backed service recipe, possibly singleton-scoped, that owns room timelines, rosters, subscriptions, and fanout. This is attractive when communication needs outgrow simple file-backed room state, but it should remain an implementation adapter behind the same `room:<run>` address and message envelope. The public model should not fork into a separate chat API.
+
+That actor-backed shape can also reduce direct file storage. Instead of every protocol feature owning JSON files as primary state, a helper actor can keep live room/roster structures in memory or another local structure and write files only as snapshots, audit logs, artifacts, or recovery checkpoints. The decision boundary is practical: keep files when durability and inspectability are the main value; prefer actor-owned structures when live coordination, subscriptions, fanout, unread state, or mutation consistency becomes the main value.
+
+Package-specific endpoints may still exist, but the envelope stays the same.
 
 ## Message Envelope
 
@@ -73,6 +85,8 @@ run -> coordinator
 run -> run
 parent -> branch
 branch -> parent
+branch -> room
+room -> branch notification
 coordinator -> tool
 ```
 
@@ -80,11 +94,59 @@ Transports differ, but the public contract does not:
 
 - `to: run:<id>` routes through the run-local control channel selected by that recipe or runtime adapter.
 - `to: coordinator` routes to the runtime attention path when `from` names a run actor. `to: session:<id>` uses the same actor-message path only when the sender run is owned by that session, making explicit session-directed checkpoints possible without exposing runtime delivery knobs. Generic async-runner `command.done` messages and explicit coordinator/session-bound messages include the actor envelope fields alongside runtime metadata.
-- `to: branch:<run>/<branch>` routes through the parent run mailbox with the full envelope preserved so the run can dispatch branch-local control.
+- `to: branch:<run>/<branch>` routes through the parent run mailbox with the full envelope preserved so the run or recipe-specific worker protocol can dispatch branch-local control. It is not a broadcast room and it does not make an arbitrary prompt process consume the message automatically.
+- `to: room:<run>` appends the full envelope to the room timeline and updates room state for room-control types such as `actor.join` and `actor.leave`.
 - `to: tool:<name>` invokes an executable pi tool by name. Object bodies become tool parameters; primitive bodies are passed as `{ "input": body }`.
 
 Transport is not public API unless a recipe explicitly documents a custom endpoint.
 
+## Rooms and Rosters
+
+The task room is the discovery and shared-context layer for actors whose spawn-tree positions do not give them each other's addresses. The spawn tree remains the lifecycle/provenance structure; the task room describes the group communication graph. Direct messages and room messages can share the same semantic `type` such as `chat.message`; the route (`to: branch:*` versus `to: room:*`) determines whether delivery is private or group-wide.
+
+Use direct branch messages only when the receiving branch is backed by a worker or recipe that reads the parent run mailbox and dispatches branch-targeted envelopes. Room roster contacts are discovery hints, not a guarantee that an independent prompt process is subscribed to its branch address. For ad hoc or transcript-driven swarms, prefer room-visible replies and mentions so every participant can inspect the shared timeline.
+
+A minimal join message:
+
+```json
+{
+  "to": "room:review",
+  "from": "branch:review/security",
+  "type": "actor.join",
+  "summary": "Security reviewer joined",
+  "body": {
+    "role": "reviewer",
+    "caps": ["security-review", "risk-analysis"],
+    "claim": "Review auth boundary risks"
+  }
+}
+```
+
+A leave message removes that actor from the roster while preserving the timeline entry:
+
+```json
+{
+  "to": "room:review",
+  "from": "branch:review/security",
+  "type": "actor.leave"
+}
+```
+
+Room messages require `from` so roster presence and provenance stay explicit. The sender must belong to the room's run (`run:<run>` or `branch:<run>/<branch>`), which prevents accidental cross-run roster pollution. Other room posts also refresh sender presence, defaulting the role hint to `actor` when no richer role is known.
+
+Roster entries should keep identity axes separate:
+
+- `address`: Stable route for direct messages.
+- `parent`: Spawn-tree parent for provenance and ownership checks.
+- `role`: Current task function; dynamic and prompt-dependent.
+- `caps`: Capabilities the actor can offer.
+- `claim`: Current work claim or focus.
+- `status` / `last_seen`: Presence and staleness hints.
+
+Compact roster inspection includes these hints when present so agents can discover direct-message targets without verbose JSON.
+
+Actors should receive a compact visible communication snapshot rather than a full global tree: self, parent/root, joined rooms, relevant sibling/member addresses, and role/capability hints. Current run actors get `communication.json` in their state dir, and async templates receive `{communication_file}`, `{actor_address}`, and `{default_room}` values. The snapshot includes `self`, `root`, optional `parent`, the default room, current default-room members, direct-message `contacts` derived from the room roster, and `updated_at`. Branch-local snapshots are refreshed when a branch joins or posts in the default room, so actors can discover peers without reading full timelines. Full timelines and rosters remain intentional inspection surfaces. For TUI and compact operator display, `view=previews` returns bounded message preview records with `timestamp`, `from`, `to`, `type`, optional `summary`, and optional `body_preview`.
+
 ## Mailbox Declaration
 
 Recipes can declare their conversational surface:
@@ -131,7 +193,7 @@ Recipes can declare their conversational surface:
 }
 ```
 
-The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, and `mailbox` for `run:<id>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
+The implementation supports `status`, `tail`, `messages`, `artifacts`, `files`, `mailbox`, and `communication` for `run:<id>` actors, `status`, `messages`, `previews`, `roster`, and `contacts` for `room:<run>` actors, `status`/`runs` for `coordinator`, `session:<id>`, and `session:all` actors with optional status filtering, and `status`/`schema` for registered `tool:<name>` actors. Room `status` returns compact message/roster counts plus `last_message_at`, `last_message_from`, `last_message_type`, and `last_message_summary` when available. Use `messages` for actor-envelope inspection. `inspect target=coordinator` requires a current coordinator session; use `session:<id>` or `session:all` when the session is intentionally explicit. Direct `run:<id>` and `room:<run>` inspection respects coordinator-session ownership when the current session is known. `inspect` is for decision points and diagnosis only; examples must not teach sleep-then-inspect polling.
 
 ## Runtime Direction
 
@@ -152,4 +214,5 @@ intentional observe  -> inspect
 - No public transport-path vocabulary in recipe args.
 - No polling-first examples.
 - No separate upward and downward message schemas.
+- No heavyweight chat/broker subsystem when an addressable room mailbox is enough.
 - No broad facade that hides artifacts, logs, or ownership checks.

package/docs/async-runs.md

@@ -72,13 +72,20 @@ A caller can also start any recipe or inline template explicitly through `spawn`
 
 `spawn` always starts a detached run actor. Registered recipe tools follow the recipe's `async` flag.
 
-Use `run_id` on async recipe tools or `as: "run:<id>"` on `spawn` when the caller wants a stable id for later inspection or control. Recipe `name` identifies the saved definition; the run id identifies one execution instance of that recipe. Async runs inject `{run_id}` and `{state_dir}` into template values so scripts can write run-local status files or control endpoints.
+Use `run_id` on async recipe tools or `as: "run:<id>"` on `spawn` when the caller wants a stable id for later inspection or control. Recipe `name` identifies the saved definition; the run id identifies one execution instance of that recipe. Async runs inject lifecycle and communication values into template values so scripts can write run-local status files, control endpoints, or room-aware coordination messages:
+
+- `{run_id}`: stable run id.
+- `{state_dir}`: run-local state directory.
+- `{actor_address}`: run actor address, e.g. `run:review`.
+- `{default_room}`: default room address, e.g. `room:review`.
+- `{communication_file}`: compact communication snapshot path.
 
 ## State Files
 
 Use ordinary files under the extension temp directory so status tools stay simple and inspectable:
 
 - `run.json`: pid, optional source metadata (`tool`, `recipe`, `recipe_file`), command-template config, cwd, coordinator owner id, values, named `artifacts`, mailbox metadata, created time, and state dir.
+- `communication.json`: compact actor communication snapshot with self/root/parent, default-room, member, and contact hints for room-aware scripts and agents.
 - `progress.json`: phase, active command count, completed count, failures, and updated time.
 - `events.jsonl`: append-only implementation lifecycle log.
 - `outbox.jsonl`: implementation storage for actor-message envelopes used by `inspect view=messages`, coordinator notifications, or follow-up context. Coordinator follow-ups preserve bounded `body` previews plus message metadata for decision points.
@@ -95,6 +102,7 @@ State files use this shape:
 
 ```text
 ~/.pi/agent/tmp/pi-actors/runs/<run>/run.json
+~/.pi/agent/tmp/pi-actors/runs/<run>/communication.json
 ~/.pi/agent/tmp/pi-actors/runs/<run>/progress.json
 ~/.pi/agent/tmp/pi-actors/runs/<run>/events.jsonl
 ~/.pi/agent/tmp/pi-actors/runs/<run>/outbox.jsonl
@@ -129,13 +137,27 @@ The core loop is:
 
 Addressed `message` calls and coordinator follow-ups are the paired control plane: run-to-coordinator actor messages flow upward, while coordinator-to-run actor messages flow downward. Recipe scripts own the message vocabulary (`next`, `pause`, `approve`, `revise`, `continue`, and so on); pi-actors owns the safe run-local transport, coordinator-session ownership checks, and coordinator attention policy.
 
+### Persistent backlog implementers
+
+Backlog implementer actors should be long-lived workers, not one-shot prompts, when the coordinator wants continuous branch work. A typical run starts two actors, such as `branch:<run>/front` and `branch:<run>/back`, that claim from opposite ends of the canonical backlog and share `room:<run>` for visibility.
+
+The stable loop is:
+
+1. Coordinator sends `task.assign` to an idle branch actor with the exact backlog slice and validation boundary.
+2. Actor posts `task.claim` to `room:<run>` before editing.
+3. Actor completes the slice, validates, and posts `task.result` plus `awaiting_assignment`.
+4. Actor remains alive and waits for the next coordinator message.
+5. Coordinator either sends another `task.assign` or sends `control.stop` after confirming no actionable work remains.
+
+Implementer recipes should declare this contract in `mailbox.accepts` and `mailbox.emits`. They should not self-terminate after a successful slice, and they should not silently self-select a new task unless the coordinator deliberately configured that policy for the run. This keeps task choice centralized while preserving actor-local execution autonomy.
+
 ## Tool Surface
 
 The actor-level surface is:
 
 - `spawn`: start a detached `run:<id>` actor from `file`, `recipe`, or inline `template`.
-- `message`: send one typed envelope to `run:<id>`, `branch:<run>/<branch>`, `tool:<name>`, `coordinator`, or `session:<id>`.
-- `inspect`: intentionally read owned `run:<id>` status, tail, messages, artifacts, files, or mailbox metadata; read current `coordinator` run inventory only when a coordinator session is known; read `session:<id>` or `session:all` run inventory with optional status filtering when the session is explicit; read `tool:<name>` status or schema for registered tool actors.
+- `message`: send one typed envelope to `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, or `session:<id>`.
+- `inspect`: intentionally read owned `run:<id>` status, tail, messages, artifacts, files, mailbox metadata, or communication snapshot; read `room:<run>` status, messages, previews, roster, or contacts; read current `coordinator` run inventory only when a coordinator session is known; read `session:<id>` or `session:all` run inventory with optional status filtering when the session is explicit; read `tool:<name>` status or schema for registered tool actors.
 
 Low-level async actions map into the actor surface instead of forming a second public model:
 

package/docs/recipe-library.md

@@ -59,9 +59,9 @@ register_tool name=subagent_prompt \
 Start it:
 
 ```text
-subagent_prompt prompt="Review docs/async-runs.md for unclear wording." run_id=docs-review
-inspect target=run:docs-review view=status
-inspect target=run:docs-review view=tail
+subagent_prompt prompt="Review docs/async-runs.md for unclear wording." run_id=docs_review
+inspect target=run:docs_review view=status
+inspect target=run:docs_review view=tail
 ```
 
 ## Composed Pipelines
@@ -82,6 +82,7 @@ Pipeline recipes demonstrate second-order composition:
 - `recipes/pipeline-development-tasking.json`: Plan → task card → critique → integrator handoff.
 - `recipes/pipeline-docs-maintenance.json`: Docs index → documentation review → maintenance plan → artifact report.
 - `recipes/pipeline-media-library.json`: Playlist build → media-library artifact report.
+- `recipes/pipeline-room-swarm.json`: Room participants join `room:<run>`, coordinate over repeated room-visible rounds, leave cleanly, and synthesize the room transcript into a caller-provided artifact path. Keep model/thinking/mission policy caller-owned. Custom roles can be supplied with `roles_path` as a JSON array of `{ "name", "persona", "glyph" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses, while optional `glyph` is display-only for room summaries and operator scanning. The packaged swarm uses contacts for peer awareness but does not rely on direct branch delivery unless a caller-specific worker protocol consumes branch envelopes. Set `locker=true` to compose a local `coordinator-locker` cell under `{state_dir}/locker` for artifact ownership, resource lease locks, and a decision journal without merging locker policy into the room-participant script.
 - `recipes/pipeline-artifact-report.json`: Normalize → artifact-shaped output → actor-message-shaped record. This pipeline prepares a candidate artifact and emits `artifact.prepared`/`artifact.blocked`; the `artifact_path` is a target path, not a guarantee that the file was written.
 - `recipes/pipeline-artifact-write.json`: Normalize → artifact-shaped output → deterministic artifact write → actor-message-shaped record. Use only when the caller explicitly wants filesystem writes; `write_mode` is `create`, `overwrite`, or `append`.
 - `recipes/pipeline-artifact-bundle.json`: Optional validation → deterministic artifact write → machine-readable manifest generation → deterministic manifest write → actor-message-shaped record. Use when the caller explicitly wants a filesystem handoff bundle with both artifact and manifest paths.

package/docs/template-recipes.md

@@ -78,7 +78,7 @@ Recipe priority only matters when two discovered recipes have the same filename
 3. Explicitly referenced ad hoc user recipe files located outside `~/.pi/agent/recipes`.
 4. User recipe files under `~/.pi/agent/recipes/*.json`.
 
-The high-priority user recipe directory is also the default tool set: recipes placed there are agent tools unless they explicitly set `tool: false`. This preserves the old advantage of a tool-only registry because listing `~/.pi/agent/recipes` shows the operator-managed tool surface. Packaged and ad hoc recipes are recipe components by default; they opt into agent-tool exposure with `tool: true`.
+The high-priority user recipe directory is also the default tool set: recipes placed there are agent tools by location. This preserves the old advantage of a tool-only registry because listing `~/.pi/agent/recipes` shows the operator-managed tool surface. Packaged and ad hoc recipes are recipe components by default; they become tools only when copied or registered into the agent recipe root.
 
 Higher-priority files shadow lower-priority files with the same basename. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
 
@@ -97,7 +97,7 @@ User-owned recipes may accumulate extension-maintained usage metadata:
 
 The extension increments `usage.calls` and updates `usage.last_called` when it starts that concrete recipe, either through a recipe-backed tool call or a direct async recipe-file run. It also stores a content `usage.fingerprint`; if the authored recipe content changes, the next launch resets `usage.calls` before counting the new launch and records `usage.reset_at`. Agents should treat these fields as cleanup evidence, not as authored recipe contract. Packaged standard-library recipes are not mutated for usage metadata.
 
-There is intentionally no failure counter in the recipe contract. A failed launch can reflect caller misuse, missing runtime values, or an environmental problem rather than recipe uselessness. Cleanup decisions should be explicit operator work: keep as a tool, set `tool: false`, merge, delete, or archive.
+There is intentionally no failure counter in the recipe contract. A failed launch can reflect caller misuse, missing runtime values, or an environmental problem rather than recipe uselessness. Cleanup decisions should be explicit operator work: keep as a tool, move out of the agent recipe root to retain recipe-only memory, merge, delete, or archive.
 
 For object form, keep `template` last. Recipe metadata comes first; executable content stays last.
 
@@ -203,12 +203,11 @@ Call-time params override file params. `values` are merged with file values; cal
 
 ## Registered Recipe Tools
 
-A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` are tools by default; packaged/ad hoc recipes opt in with `tool: true`:
+A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` are tools by location; packaged/ad hoc recipes are components unless copied or registered into that user recipe root:
 
 ```json
 {
   "description": "Start an async docs review actor",
-  "tool": true,
   "async": true,
   "args": ["scope:path", "model:string"],
   "template": "review {scope} --model {model}"

package/docs/tool-registry.md

@@ -6,18 +6,16 @@ This document is the local adaptation of the portable [Command Template Standard
 
 ## Registry Model
 
-The 0.16 registry source is file-discovered recipes, not a live tool-only JSON file:
+The registry source is location-discovered recipes, not a live tool-only JSON file and not a recipe-owned boolean:
 
 - `~/.pi/agent/recipes/*.json` is the highest-priority user recipe root and the operator-managed tool set.
-- Recipes in that root are tools by default.
-- `tool: false` keeps a user recipe file recipe-only.
-- Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components.
-- Packaged or ad hoc recipes opt into tool exposure with `tool: true`.
+- Recipes in that root are tools by location.
+- Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components, not automatically registered tools.
+- Ad hoc recipe files outside the user recipe root are components unless explicitly registered/copied into `~/.pi/agent/recipes`.
 - Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` has id/tool name `docs_review`.
 
-`~/.pi/agent/actors-tools.json` is legacy compatibility input. On startup, pi-actors migrates it into recipe files when possible, writes a migration report, and archives the source only when migration has no conflicts or invalid generated recipes.
 
-Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. Use that evidence during focused cleanup passes: keep valuable tools, set `tool: false` for useful components that should leave the active tool surface, merge duplicates, or delete/archive low-value files. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
+Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls`, `usage.last_called`, and a content `usage.fingerprint` on user-owned recipe files. If authored recipe content changes, the next launch resets `usage.calls` and records `usage.reset_at` before counting the launch, so usage evidence follows the current recipe meaning rather than an older file history. `inspect target=recipes view=summary verbose=true` includes usage metadata and operator-gated cleanup recommendations for invalid, shadowed, disabled, component-only, unused, or overriding recipes. Recommended actions stay explicit: keep as a tool/component, enable, merge, fix, delete, or archive. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
 
 `register_tool` is the preferred agent-facing mutation API. It creates, updates, and deletes recipe files in `~/.pi/agent/recipes`; agents do not need to edit the files directly for normal registration. Direct file edits are still valid for operators and advanced agents. Runtime behavior is reactive: file creation, deletion, or edits in the user recipe root trigger validation and tool-set refresh, with invalid recipes surfaced as diagnostics rather than silently ignored.
 
@@ -62,18 +60,17 @@ For reusable actor workflows, register a small tool whose `template` points to a
 ```text
 register_tool name=docs_review \
   description="Start an async docs review actor" \
-  template="docs-review" \
+  template="docs_review" \
   args="scope:path,model:string"
 ```
 
-This writes or updates `~/.pi/agent/recipes/docs_review.json` with `tool: true` and a recipe-reference template. If the referenced recipe contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+This writes or updates `~/.pi/agent/recipes/docs_review.json` with a recipe-reference template. Its location in the user recipe root makes it a tool. If the referenced recipe contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
 When co-location is clearer than a separate file, `register_tool` writes the recipe fields directly into the user recipe file:
 
 ```json
 {
   "description": "Start an async docs review",
-  "tool": true,
   "async": true,
   "args": ["scope:path", "model:string"],
   "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
@@ -95,7 +92,6 @@ Tool names come from recipe filenames in `~/.pi/agent/recipes`. Recipe files def
 ```json
 {
   "description": "Transcribe an audio file",
-  "tool": true,
   "template": "~/bin/transcribe {file:path} {lang=ru} {model:string}"
 }
 ```
@@ -103,7 +99,6 @@ Tool names come from recipe filenames in `~/.pi/agent/recipes`. Recipe files def
 ```json
 {
   "description": "Run pi as a non-interactive sub-agent",
-  "tool": true,
   "args": ["prompt:string", "model:string"],
   "template": "pi -p --model {model} --no-tools {prompt}"
 }

package/index.ts

@@ -2,7 +2,7 @@
  * 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 their definitions in actors-tools.json, and exposes actor orchestration across reloads and sessions.
+ * 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, type FSWatcher } from "node:fs";
@@ -12,6 +12,7 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 
+import * as ActorInspectorTui from "./lib/actor-inspector-tui.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Observability from "./lib/observability.ts";
 import * as Paths from "./lib/paths.ts";
@@ -47,6 +48,9 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   const observedRuns = new Map<string, Observability.RunObservedStatus>();
   const observedRunEventLines = new Map<string, number>();
   let runStatusFrame = 0;
+  let communicationWidgetVisible = false;
+  let actorInspectorRows = 12;
+  let selectedInspectorSequence: number | undefined;
   const getRunOwnerId = (ctx: ExtensionContext): string =>
     ctx.sessionManager.getSessionId();
   const updateRunUi = (ctx: ExtensionContext, notify = false): void => {
@@ -57,7 +61,46 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       "zz-pi-actors-runs",
       status ? ctx.ui.theme.fg("dim", status) : undefined,
     );
-    ctx.ui.setWidget("zz-pi-actors-runs", undefined);
+    ctx.ui.setWidget(
+      "zz-pi-actors-comms",
+      communicationWidgetVisible
+        ? () => ({
+            invalidate() {},
+            render(width: number) {
+              const previews = ActorInspectorTui.readActorInspectorPreviews(
+                RUN_STATE_ROOT,
+                actorInspectorRows,
+                { ownerId, currentRunOnly: true },
+              );
+              const 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),
+              };
+              return (
+                (selectedInspectorSequence !== undefined
+                  ? ActorInspectorTui.renderInspectorItemView(
+                      previews,
+                      width,
+                      style,
+                      { sequence: selectedInspectorSequence },
+                    )
+                  : ActorInspectorTui.renderInspectorWidget(
+                      previews,
+                      width,
+                      style,
+                    )) ?? []
+              );
+            },
+          })
+        : undefined,
+      { placement: "belowEditor" },
+    );
     const transitions = Observability.detectRunTransitions(
       observedRuns,
       summary,
@@ -135,7 +178,9 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     if (!existsSync(RUN_STATE_ROOT)) return;
     if (!stateRootWatcher) {
       try {
-        stateRootWatcher = watch(RUN_STATE_ROOT, () => scheduleRunEventUpdate(ctx));
+        stateRootWatcher = watch(RUN_STATE_ROOT, () =>
+          scheduleRunEventUpdate(ctx),
+        );
         stateRootWatcher.on("error", () => {
           stateRootWatcher?.close();
           stateRootWatcher = undefined;
@@ -207,6 +252,61 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     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;
+        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;
+        communicationWidgetVisible = true;
+      }
+      updateRunUi(ctx);
+      ctx.ui.notify(
+        `Actor inspector ${communicationWidgetVisible ? "shown" : "hidden"}`,
+        "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}`,
   }));