@llblab/pi-actors 0.17.0 → 0.18.0

package/docs/async-runs.md

@@ -22,7 +22,7 @@ Async-run standard owns:
 Async-run standard does not own:
 
 - Command-template syntax, placeholders, graph semantics, or branch policy.
-- Recipe import resolution, recipe names, or recipe storage format.
+- Recipe import resolution, filename-derived recipe identity, or recipe storage format.
 - Domain semantics for subagents, swarms, release readiness, media playback, or project policy.
 - Scheduling, queue daemons, distributed workers, or workflow DSLs.
 
@@ -52,7 +52,6 @@ A recipe with `async: true` starts detached when invoked through its registered
 
 ```json
 {
-  "name": "music-player",
   "async": true,
   "template": "play-audio {source}"
 }
@@ -72,7 +71,7 @@ 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 lifecycle and communication values into template values so scripts can write run-local status files, control endpoints, or room-aware coordination messages:
+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. The recipe filename 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.
@@ -182,7 +181,7 @@ Some recipes expose a run-local control channel. When present, a caller can send
 }
 ```
 
-For `run:<id>`, `message` adapts the body to the recipe's run-local control channel. For `branch:<run>/<branch>`, it sends the full envelope through the parent run mailbox so the run can dispatch branch-local control. For `tool:<name>`, object bodies become the target tool parameters and primitive bodies are passed as `{ "input": body }`. The generic runtime records control messages but does not interpret arbitrary run mailbox content. For example, a music player may accept `play`, `pause`, `next`, and `stop`, while a collaborative agent recipe may accept `continue`, `revise:<note>`, `approve`, or `abort`. Recipes may treat terminal control messages such as `stop` as synchronously handled so the later process exit does not generate a duplicate async follow-up.
+For `run:<id>`, `message` adapts the body to the recipe's run-local control channel. For `branch:<run>/<branch>`, it sends the full envelope through the parent run mailbox and records a queued branch-local inbox entry at `branches/<branch>/inbox.jsonl` so the run can dispatch branch-local control. Current consumers are recipe-specific worker protocols that read the parent run mailbox or branch inbox; independent one-shot prompt processes do not automatically consume branch inbox entries. For `tool:<name>`, object bodies become the target tool parameters and primitive bodies are passed as `{ "input": body }`. The generic runtime records control messages but does not interpret arbitrary run mailbox content. For example, a music player may accept `play`, `pause`, `next`, and `stop`, while a collaborative agent recipe may accept `continue`, `revise:<note>`, `approve`, or `abort`. Recipes may treat terminal control messages such as `stop` as synchronously handled so the later process exit does not generate a duplicate async follow-up.
 
 The standard run-local transport is Unix-oriented. Use WSL/Linux/macOS for packaged message-controlled recipes, or let a Windows-specific recipe expose its own transport such as a Windows named pipe or localhost socket.
 
@@ -294,7 +293,6 @@ Example recipe:
 
 ```json
 {
-  "name": "collab-{run}",
   "async": true,
   "parallel": true,
   "timeout": 1800000,

package/docs/command-templates.md

@@ -159,6 +159,8 @@ template="echo 'literal words' {text}"
 
 ## Composition
 
+Shell syntax warning: command-template placeholder parsing still sees braces inside shell snippets. Avoid inline Bash parameter expansion such as `${file%.md}` or `${name}` in recipe/template strings because `{file...}` can be parsed as a pi-actors placeholder. For non-trivial shell loops or parameter expansion, put the shell logic in a small trusted script and call that script from the template; keep the command template as the launch boundary.
+
 `template: [...]` means sequential composition by default; each leaf is a command template executed with one shared runtime value map:
 
 ```json

package/docs/recipe-library.md

@@ -48,6 +48,8 @@ Core subagent recipes:
 
 Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. Packaged recipes intentionally do not ship concrete model-version defaults: callers must pass current model policy at launch, which keeps reusable recipe components from aging around old provider aliases. The generic prompt launchers, including `subagent-tools` and `subagents-prompts`, expose the same core model/thinking/tool/output knobs so callers do not need separate recipe families for policy tuning. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
 
+For build-oriented swarms, prefer a consensus-first shape over parallel writers: proposer roles coordinate in a room with message/inspect tools, a named implementer owns the first artifact write, a QA reviewer inspects the result, and a finalizer applies review-grounded fixes before `run.done`. This pattern keeps creative/lens diversity while preserving one coherent artifact and gives recipes concrete artifact assertions instead of treating room discussion as success.
+
 Register one atom:
 
 ```text
@@ -82,6 +84,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" }` objects; `name` stays ASCII-safe for `branch:<run>/<name>` addresses and debugger output remains plain and name-driven. 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/task-first-recipes.md

@@ -137,6 +137,35 @@ Existing seeds:
 - `subagent-contradiction-map`
 - `subagent-verify`
 
+### Consensus-First Build Cell
+
+Purpose: turn several expert proposals into one coherent artifact without parallel writers fragmenting the result.
+
+Pipeline:
+
+```text
+mission → lens proposers in room → consensus transcript → named implementer writes artifact → QA reviewer checks artifact + transcript → finalizer applies fixes → artifact assertions
+```
+
+Use this for creative demos, single-file artifacts, specs, docs, prompt packs, and product/UX deliverables where broad input matters but one owner should shape the final file. Proposers should have message/inspect tools only. The implementer should be the first role with write tools. QA should inspect/read but not mutate. The finalizer may write only after reading QA evidence.
+
+Required gates:
+
+- Artifact path, report path, and minimum acceptance checks are explicit inputs.
+- The workflow fails if the requested artifact is missing, too small, or not self-contained enough for the task.
+- `run.done` is emitted only after QA/finalizer passes, not merely after room discussion.
+
+Existing seeds:
+
+- `pipeline-room-swarm` for room-visible discussion and rosters.
+- `subagent-message` for explicit room handoffs.
+- `subagent-review` / `subagent-verify` for QA roles.
+- `pipeline-artifact-write` or a small helper script for deterministic artifact assertion.
+
+Next recipe direction:
+
+- Add a generic packaged consensus-build pipeline once the interface stabilizes around proposer roles, implementer prompt, QA prompt, artifact assertions, and public model/tool knobs.
+
 ### Implementation Tasking Cell
 
 Purpose: prepare bounded work for one or more implementation agents.

package/docs/template-recipes.md

@@ -19,7 +19,7 @@ async: true     = run through detached lifecycle
 
 A recipe wraps one command-template tree. The wrapped `template` keeps the normal command-template semantics: argv splitting, placeholders, defaults, typed args, sequence, `parallel: true`, `when`, delay, retry, failure propagation, recover cleanup, and output selection.
 
-Layer boundary: `imports`, `{ "name": "alias" }` imported-recipe nodes, `{alias.defaults.key}` references, fallback expressions, and recipe-local ternaries are recipe-loading features. They resolve before the command-template graph runs and do not extend the portable Command Template Standard. Typed imports are recipe definitions: they expose the imported recipe's command-template-shaped metadata (`template`, `args`, `defaults`, flags, and `values`), while async-run launch fields such as `async` and `state_dir` remain lifecycle configuration for starting a run, not part of the imported execution graph.
+Layer boundary: `imports`, `{ "name": "alias" }` imported-recipe nodes, `{alias.defaults.key}` references, fallback expressions, and recipe-local ternaries are recipe-loading features. They resolve before the command-template graph runs and do not extend the portable Command Template Standard. Typed imports are recipe definitions: they expose the imported recipe's command-template-shaped metadata (`template`, `args`, `defaults`, flags, and `values`), while async-run launch fields such as `async`, `state_dir`, and `retire_when` remain lifecycle configuration for starting a run, not part of the imported execution graph.
 
 Packaged recipes are the pi-actors recipe standard library: declarative actor config components that can be imported, launched, inspected, overridden, or composed by user recipes. Treat them as stable building blocks rather than user-local policy.
 
@@ -29,7 +29,7 @@ Template-recipe standard owns:
 
 - Saved JSON definitions around one command-template graph.
 - File-backed and co-located recipe shapes.
-- Recipe identity through `name` or filename.
+- Recipe identity through file-backed filename or co-located tool id.
 - Recipe defaults, values, imports, import references, and import-node expansion.
 - Ordered named artifact declarations through `artifacts`.
 - Foreground-vs-detached selection through `async: true` when invoked by a recipe-aware host.
@@ -52,7 +52,6 @@ Synchronous recipe:
 
 ```json
 {
-  "name": "check-docs",
   "template": "npm run check:docs"
 }
 ```
@@ -61,13 +60,12 @@ Async recipe:
 
 ```json
 {
-  "name": "review-docs",
   "async": true,
   "template": "review docs/spec.md"
 }
 ```
 
-`name` names the saved definition when an explicit name is needed. File-backed recipes usually omit it because the filename is the canonical recipe id. `template` is the command-template tree. `async: true` selects detached run mode when the recipe is invoked through a registered tool.
+A file-backed recipe's id comes from its filename, not a JSON `name` field. Legacy files may still contain `name`, but loaders ignore it for identity. `template` is the command-template tree. `async: true` selects detached run mode when the recipe is invoked through a registered tool.
 
 ## Discovery Priority
 
@@ -107,7 +105,6 @@ Use recipe-level `artifacts` to declare stable artifact names and paths for the
 
 ```json
 {
-  "name": "report-task",
   "args": ["report_path:path"],
   "defaults": { "report_path": "artifacts/report.md" },
   "artifacts": {
@@ -156,11 +153,10 @@ Recipes do not declare a second event-delivery policy. A running actor emits add
 
 ## Command-Template Flags At Recipe Top Level
 
-Top-level command-template flags may sit beside `name` and `async`:
+Top-level command-template flags may sit beside recipe metadata such as `async`:
 
 ```json
 {
-  "name": "review-docs",
   "async": true,
   "parallel": true,
   "timeout": 300000,
@@ -199,7 +195,7 @@ Bare recipe names resolve under that directory, so `file: "review-docs"` loads:
 ~/.pi/agent/recipes/review-docs.json
 ```
 
-Call-time params override file params. `values` are merged with file values; call-time values win. If a run id is omitted for an explicit async start, the explicit recipe `name` or file basename becomes the default run id.
+Call-time params override file params. `values` are merged with file values; call-time values win. If a run id is omitted for an explicit async start, the file basename becomes the default run id.
 
 ## Registered Recipe Tools
 
@@ -226,7 +222,7 @@ Example: a recipe may expose a private `repo` default for an example script, whi
 
 ## Recipe Imports
 
-File-backed recipes may import other file-backed recipes at the recipe layer. Imports are resolved before the command-template graph is executed, so command-template core stays registry-free and synchronous.
+File-backed recipes may import other file-backed recipes at the recipe layer. Imports are resolved before the command-template graph is executed, so command-template core stays registry-free and synchronous. Recipe loading is intentionally bounded: a single recipe file larger than 1 MiB is rejected before JSON parsing, and import chains deeper than 32 are rejected before further resolution. Split very large prompts/data into explicit files or artifacts and keep recipe graphs shallow enough for operator review.
 
 ```json
 {
@@ -244,17 +240,16 @@ File-backed recipes may import other file-backed recipes at the recipe layer. Im
 
 An import binding may be either a string recipe path/name or an object with:
 
-- `from`: recipe path or bare name. Import paths support static load-time placeholders: `{repo}` expands to the directory above the active recipe root, and `{agent}` expands to the pi agent directory. For a packaged recipe in `<repo>/recipes/name.json`, `{repo}/recipes/other.json` resolves to a sibling packaged recipe. For a user recipe in `~/.pi/agent/recipes/name.json`, `{repo}` and `{agent}` both resolve to `~/.pi/agent`.
+- `from`: recipe path or bare recipe name. Import paths support static load-time placeholders: `{repo}` expands to the directory above the active recipe root, and `{agent}` expands to the pi agent directory. For a packaged recipe in `<repo>/recipes/name.json`, `{repo}/recipes/other.json` resolves to a sibling packaged recipe. For a user recipe in `~/.pi/agent/recipes/name.json`, `{repo}` and `{agent}` both resolve to `~/.pi/agent`. Bare names such as `utility-package-summary` resolve by recipe priority: first `~/.pi/agent/recipes`, then the importing recipe's directory, then the packaged standard library. This makes packaged recipes easy to reuse while preserving user/ad hoc overrides by filename identity.
 - `defaults`: extra default values exposed through the import.
 - `values`: explicit values for embedding that imported recipe.
 
 A template node of `{ "name": "alias" }` is replaced with the imported recipe's command-template graph. Imported recipe defaults are merged with import `defaults`, import `values`, node `defaults`, and node `values`; later layers win. This lets a parent recipe embed a reusable recipe in a sequence or `parallel: true` branch without inventing a workflow language.
 
-Async composition stays explicit: importing a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
+Async composition stays explicit: importing a recipe reuses its command-template-shaped definition. It does not start a nested async run. Put `async: true` on the parent recipe when the combined imported graph should run detached as one run with one state dir. Ephemeral coordinator recipes may declare `retire_when: "children_terminal"` as an opt-in lifecycle hint for future graceful retirement handling; persistent services and implementer loops should omit it. For agent-callable fanout, prefer public inputs such as `prompts:array` plus `repeat: "{prompts.length}"`, then select each branch value with `{prompts[index]}` instead of baking concrete prompts or file names into the reusable recipe.
 
 ```json
 {
-  "name": "parallel-review",
   "async": true,
   "imports": {
     "review": "review-one.json"
@@ -301,6 +296,6 @@ Nested object keys are dot-separated. Import references are resolved before norm
 
 ## Recipe Shape
 
-Use `name` for an explicit recipe id, rely on the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` before relying on recipe launchers.
+Use the filename for file-backed recipe ids, and use `async: true` for detached runs. Use `parallel: true` for fanout, `when` for node guards, and semantic public args such as `tools`, `all`, or `timeout_ms` instead of leaking CLI fragments or reusing node-control names. Local files belong under `~/.pi/agent/recipes/*.json` before relying on recipe launchers.
 
 If a proposed recipe needs a scheduler, queue daemon, `goto`, or custom workflow syntax, stop. Keep the recipe as saved command-template JSON and put policy in the registered tool, script, or caller.

package/index.ts

@@ -49,7 +49,14 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   const observedRunEventLines = new Map<string, number>();
   let runStatusFrame = 0;
   let communicationWidgetVisible = false;
-  let inspectorVerbosity: ActorInspectorTui.ActorInspectorVerbosity = "verbose";
+  let actorInspectorRows = 12;
+  let actorInspectorChannels:
+    | ActorInspectorTui.ActorInspectorPreview["channel"][]
+    | undefined;
+  let actorInspectorMention: string | undefined;
+  const actorInspectorRoomLimitPerRun = 6;
+  let selectedInspectorSequence: number | undefined;
+  let recipeWatcherFailureNotified = false;
   const getRunOwnerId = (ctx: ExtensionContext): string =>
     ctx.sessionManager.getSessionId();
   const updateRunUi = (ctx: ExtensionContext, notify = false): void => {
@@ -63,31 +70,59 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     ctx.ui.setWidget(
       "zz-pi-actors-comms",
       communicationWidgetVisible
-        ? () => ({
-            invalidate() {},
-            render(width: number) {
-              return (
-                ActorInspectorTui.renderInspectorWidget(
-                  ActorInspectorTui.readActorInspectorPreviews(
-                    RUN_STATE_ROOT,
-                    14,
-                    { ownerId, currentRunOnly: true },
-                  ),
-                  width,
+        ? () => {
+            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 {
+              invalidate() {},
+              render(width: number) {
+                const previews = ActorInspectorTui.readActorInspectorPreviews(
+                  RUN_STATE_ROOT,
+                  actorInspectorRows,
                   {
-                    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),
+                    channels: actorInspectorChannels,
+                    currentRunOnly: true,
+                    mention: actorInspectorMention,
+                    ownerId,
+                    roomLimitPerRun: actorInspectorRoomLimitPerRun,
                   },
-                  { verbosity: inspectorVerbosity },
-                ) ?? []
-              );
-            },
-          })
+                );
+                const rows =
+                  (selectedInspectorSequence !== undefined
+                    ? ActorInspectorTui.renderInspectorItemView(
+                        previews,
+                        width,
+                        style,
+                        { sequence: selectedInspectorSequence },
+                      )
+                    : ActorInspectorTui.renderInspectorWidget(
+                        previews,
+                        width,
+                        style,
+                      )) ?? [];
+                const run = previews[0]?.run;
+                const roster = run
+                  ? ActorInspectorTui.renderInspectorRosterPanel(
+                      ActorInspectorTui.readActorInspectorRoster(
+                        RUN_STATE_ROOT,
+                        run,
+                      ),
+                      width,
+                      style,
+                    )
+                  : undefined;
+                return roster ? [...roster, ...rows] : rows;
+              },
+            };
+          }
         : undefined,
       { placement: "belowEditor" },
     );
@@ -117,6 +152,12 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
         { deliverAs: "followUp", triggerTurn: true },
       );
     }
+    Observability.pruneRunObservationState(
+      observedRuns,
+      observedRunEventLines,
+      summary,
+      transitions.map((transition) => transition.run),
+    );
     for (const event of outboxEvents) {
       if (!Observability.shouldNotifyRunOutboxEvent(event)) continue;
       const text = Observability.formatRunOutboxMessage(event);
@@ -190,7 +231,16 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     if (recipeReloadTimeout) clearTimeout(recipeReloadTimeout);
     recipeReloadTimeout = undefined;
   };
+  const notifyRecipeWatcherFailure = (ctx: ExtensionContext): void => {
+    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: ExtensionContext): void => {
+    recipeWatcherFailureNotified = false;
     if (recipeReloadTimeout) clearTimeout(recipeReloadTimeout);
     recipeReloadTimeout = setTimeout(() => {
       runtime.loadTools(ctx);
@@ -206,9 +256,10 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       recipeRootWatcher.on("error", () => {
         recipeRootWatcher?.close();
         recipeRootWatcher = undefined;
+        notifyRecipeWatcherFailure(ctx);
       });
     } catch {
-      // Watching is best-effort; restarting the session reloads recipe tools.
+      notifyRecipeWatcherFailure(ctx);
     }
   };
   const actorToolDefinitions = new Map<string, any>();
@@ -243,9 +294,38 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     closeRecipeWatcher();
   });
   pi.registerCommand("actors-inspector-toggle", {
-    description: "Toggle actor inspector widget",
-    handler: async (_args, ctx) => {
-      communicationWidgetVisible = !communicationWidgetVisible;
+    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"}`,
@@ -253,13 +333,57 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       );
     },
   });
-  pi.registerCommand("actors-inspector-verbosity", {
-    description: "Toggle actor inspector verbosity",
-    handler: async (_args, ctx) => {
-      inspectorVerbosity =
-        inspectorVerbosity === "verbose" ? "compact" : "verbose";
+  pi.registerCommand("actors-inspector-filter", {
+    description:
+      "Filter actor inspector rows: all, room, direct, broadcast, mention <text>",
+    handler: async (args, ctx) => {
+      const parts = Array.isArray(args)
+        ? args.map(String)
+        : String(args ?? "").split(/\s+/);
+      const mode = (parts[0] ?? "").trim().toLowerCase();
+      if (!mode || mode === "all" || mode === "clear") {
+        actorInspectorChannels = undefined;
+        actorInspectorMention = undefined;
+      } else if (mode === "room" || mode === "direct" || mode === "broadcast") {
+        actorInspectorChannels = [mode];
+        actorInspectorMention = undefined;
+      } 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|mention <text>",
+          "warning",
+        );
+        return;
+      }
+      selectedInspectorSequence = undefined;
+      communicationWidgetVisible = true;
+      updateRunUi(ctx);
+      ctx.ui.notify(`Actor inspector filter ${mode || "all"}`, "info");
+    },
+  });
+  pi.registerCommand("actors-inspect", {
+    description: "Inspect actor message by visible number",
+    handler: async (args, ctx) => {
+      const raw = Array.isArray(args) ? args[0] : String(args ?? "");
+      const sequence = Number.parseInt(String(raw), 10);
+      if (!Number.isFinite(sequence) || sequence <= 0) {
+        ctx.ui.notify("Usage: /actors-inspect <number>", "warning");
+        return;
+      }
+      selectedInspectorSequence = sequence;
+      communicationWidgetVisible = true;
       updateRunUi(ctx);
-      ctx.ui.notify(`Actor inspector ${inspectorVerbosity} mode`, "info");
+      ctx.ui.notify(`Actor inspect item ${sequence}`, "info");
     },
   });
   pi.on("before_agent_start", async (event) => ({