@llblab/pi-actors 0.17.0 → 0.17.1

package/AGENTS.md

@@ -14,7 +14,7 @@
 ## Topology
 
 - `/index.ts`: Minimal extension coordinator/composition root; it wires live pi ports and should avoid owning domain behavior
-- `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior; `command-templates.ts` mirrors the shared portable command-template standard, `schema.ts` owns tool arg declarations and placeholder-derived tool schemas, `identity.ts` owns names, `config.ts` owns config persistence, `registry.ts` owns registry register/update/delete use-cases, `output.ts` owns result formatting/truncation, `execution.ts` owns registered-tool execution, `recipe-references.ts` owns template recipe reference detection and path resolution, `async-runs.ts` owns async run state, `actor-rooms.ts` owns room timelines/rosters/communication snapshots, `actor-communication-tui.ts` owns compact terminal previews for actor communications, `observability.ts` owns ambient run summaries, `temp.ts` owns pi-agent temp cleanup, `prompts.ts` owns LLM-facing copy, `tools.ts` owns pi-facing tool definitions for both `register_tool`, async run primitives, and generated runtime tools, `runtime.ts` owns load/conflict/registration coordination, and `paths.ts` owns config/tmp path resolution
+- `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior; `command-templates.ts` mirrors the shared portable command-template standard, `schema.ts` owns tool arg declarations and placeholder-derived tool schemas, `identity.ts` owns names, `config.ts` owns config persistence, `registry.ts` owns registry register/update/delete use-cases, `output.ts` owns result formatting/truncation, `execution.ts` owns registered-tool execution, `recipe-references.ts` owns template recipe reference detection and path resolution, `async-runs.ts` owns async run state, `actor-rooms.ts` owns room timelines/rosters/communication snapshots, `actor-inspector-tui.ts` owns compact terminal previews and selected-message inspection for actor communications, `observability.ts` owns ambient run summaries, `temp.ts` owns pi-agent temp cleanup, `prompts.ts` owns LLM-facing copy, `tools.ts` owns pi-facing tool definitions for both `register_tool`, async run primitives, and generated runtime tools, `runtime.ts` owns load/conflict/registration coordination, and `paths.ts` owns config/tmp path resolution
 - `index.ts` should import local domains as namespaces (`import * as CommandTemplates from "./lib/command-templates.ts"`) so orchestration reads through domain names instead of flat helper imports
 - `/scripts/*.mjs`: Thin helper processes for detached async run execution; keep policy in registered tool config and reusable logic in `/lib`
 - `/recipes/*.json`: Packaged standard recipe library; keep recipes optional, composable, and policy-light; prefer public args for operator/agent decisions instead of baking project-specific prompts, file names, or concrete model-version defaults into reusable recipes
@@ -48,7 +48,7 @@
 - `Async run observability`: Ambient triangles count active async work units: each running async run contributes at least one triangle, and its reported active parallel command/subagent branches contribute the visible branch count when greater than one. Event-driven terminal/outbox watchers should initiate follow-up for unhandled terminal completion/failure states, failed or in-flight `command.done` branch completions, and coordinator-bound script-authored messages with bounded body previews; actor `message` is the explicit coordinator-to-run command channel paired with these upward events. Do not restore busy-polling loops, sleep-then-status smoke examples, duplicate follow-ups for final successful leaf commands, or duplicate follow-ups for `cancel`, `kill`, or control-stop actions already handled by synchronous tool results. | Trigger: Changing async run UI, notifications, actor-message routing, or smoke-test interpretation | Action: Preserve branch-aware triangles from `progress.activeSubagents`, runtime-inferred branch bubbling for packaged fanout completion, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.
 - `Runtime IO discipline`: Tool stdout and temp state must stay bounded and local | Trigger: Changing execution, formatting, temp files, run state, logs, or artifacts | Action: Keep tail truncation/full-output temp files/failure formatting intact; keep extension-owned temp state under `~/.pi/agent/tmp/pi-actors` unless explicitly overridden
-- `Backlog is planning, not history`: `BACKLOG.md` should contain current/future work, blockers, gates, and next leverage points; completed delivery history belongs in `CHANGELOG.md`, and durable behavior belongs in README/docs | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, keep current task/scope/exit criteria, and prefer an 80/20 focus list when many remaining tasks compete for attention
+- `Backlog is planning, not history`: `BACKLOG.md` should contain only future open work, blockers, gates, and next leverage points in priority order; completed delivery history belongs in `CHANGELOG.md`, and durable behavior belongs in README/docs | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, avoid version-scoped backlog headings, keep current task/scope/exit criteria, and prefer an 80/20 focus list when many remaining tasks compete for attention
 - `Release artifact hygiene`: PR/release summaries become stale during active branch work and do not belong in the repository documentation tree | Trigger: Preparing release notes or PR bodies | Action: Create temporary/operator-facing artifacts outside the repo only during explicit release finalization; keep durable release evidence in `CHANGELOG.md` and open gates in `BACKLOG.md`
 - `Persistent implementer workflows are recipe composition`: Backlog implementer scenarios should be launched through reusable component recipes, not one-off scripts or ad hoc shell orchestration | Trigger: Designing implementer swarms, backlog workers, coordinator-assigned task loops, or related recipes | Action: Compose cells such as `coordinator-locker`, subagent launchers, and actor-message utilities; preserve JSON envelope object shape across handoffs; add missing reusable component recipes only when needed; update the actors skill launcher map with supported scenarios
 - `Context sync`: Meaningful implementation or docs changes must reconcile `BACKLOG.md`, `CHANGELOG.md`, README, and docs navigation | Trigger: Closing, narrowing, or discovering work | Action: Run the context validator before final status when practical

package/BACKLOG.md

@@ -10,13 +10,14 @@
   - Evaluate whether room storage/routing should remain built into the tool adapter or move behind a dedicated non-LLM communication actor recipe/script, possibly singleton-scoped. Preserve the same public `room:<run>` address and envelope either way.
   - Consider reducing direct file-backed state where it improves coherence: model room/roster state as actor-owned data structures served by helper scripts/actors, with files retained only for durable snapshots, recovery, artifacts, or audit logs.
   - Add selected-recipient multicast for a subset of actors without creating subrooms.
+  - Clarify which worker protocols consume direct `branch:<run>/<branch>` envelopes and which swarm scenarios should stay room-visible.
 - Exit:
   - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
   - Selected-recipient multicast remains route-based and does not introduce named subrooms.
 
 ### Actor Communication TUI Preview
 
-- Priority: Medium.
+- Priority: High.
 - Goal: Make actor-to-actor communication more navigable in the terminal UI without exposing large payloads by default.
 - Direction:
   - Add explicit filters for current branch, room, direct messages, unread messages, and mentions.
@@ -50,6 +51,14 @@
 - Exit:
   - Docs, validators, packaged recipes, discovery, and migration behavior all agree on filename-derived identity and location-derived tool exposure.
 
+### Branch-Local Checkpoint Semantics
+
+- Priority: Low.
+- Blocked by: At least one real collaborative branch-runner async-run experiment.
+- Goal: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
+- Exit:
+  - Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.
+
 ### Host-Level Tool Unregistration
 
 - Priority: Low.
@@ -65,6 +74,7 @@
 ### Recipe Discovery Expansion
 
 - Priority: Low.
+- Goal: Support larger recipe libraries without confusing recipe identity or priority.
 - Direction:
   - Add nested recipe directories only after flat `recipes/*.json` discovery semantics are stable.
   - Keep same-id priority and invalid-blocking behavior explicit if nested ids are introduced.
@@ -72,6 +82,7 @@
 ### Recipe Usage Telemetry Evolution
 
 - Priority: Low.
+- Goal: Improve long-term operator insight into recipe usefulness without making telemetry noisy.
 - Direction:
   - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
   - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.
@@ -79,14 +90,7 @@
 ### Opportunistic Recipe Library Growth
 
 - Priority: Low.
+- Goal: Expand packaged recipes only when concrete repeated task patterns justify them.
 - Direction:
-  - Add new utilities or pipelines only when a concrete repeated task pattern justifies them.
-
-## Blocked Work
-
-### Branch-Local Checkpoint Semantics
-
-- Priority: Low.
-- Blocked by: At least one real collaborative branch-runner async-run experiment.
-- Scope: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
-- Exit: Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.
+  - Add new utilities or pipelines when they can be expressed as reusable recipe composition.
+  - Avoid scenario-specific scripts when existing component recipes can be composed.

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## Unreleased
+## 0.17.1: Inspector Hotfix And Room Swarm Hardening
+
+- `[TUI]` Fixed actor inspector line bounding to use `visibleWidth()` for direction/type/summary/body width math, replaced the verbose two-line preview with a hidden-by-default numbered table, made bare `/actors-inspector-toggle` open 12 rows from closed state, removed the verbosity toggle, made `/actors-inspector-toggle <rows>` update the live row count, upgraded `/actors-inspect <number>` to show a separated two-column header plus all preview-object properties as aligned two-space key/value columns, and added a styled emoji regression. Impact: room previews with wide glyphs no longer crash Pi, actor logs stay dense while preserving message type visibility, operators can tune visible row count without persistent inspector settings, and they can drill into one visible row then toggle back to the table.
+- `[Recipe Library]` Added `pipeline-room-swarm` backed by `scripts/room-swarm.mjs`: repeated room-aware participants join `room:<run>`, coordinate over multiple room-visible rounds, leave cleanly, and synthesize the room transcript into a Markdown artifact. Roles can be supplied via `roles_path` to avoid raw JSON placeholders, default roles include display glyphs while keeping branch addresses ASCII-safe, room rosters preserve display/glyph metadata, the inspector table renders glyph display names, and `locker=true` composes a local coordinator-locker cell for artifact locks and decision journaling with regression coverage. Direct branch delivery remains available for worker protocols that consume parent-run branch envelopes, but the packaged swarm no longer relies on it for peer coordination. Impact: the DeepSeek room-swarm experiment is now represented as a policy-light packaged scenario while concrete model choice remains caller/operator policy.
+- `[Docs]` Reconciled `BACKLOG.md` back to future-only open work, removing completed hotfix implementation notes and version-scoped backlog language now captured in this changelog. Refreshed README and project context around the packaged room-swarm/coordinator-locker library surface and actor-inspector TUI ownership.
+- `[Package]` Bumped package and packaged skill metadata to `0.17.1` for the hotfix release.
 
 ## 0.17.0: Actor Rooms And Inspector