@llblab/pi-actors 0.13.4 → 0.13.5

package/BACKLOG.md

@@ -6,7 +6,7 @@ Continue progressive component/pipeline expansion in small validated slices; rea
 
 - Plan organic universal communication primitives.
   - Priority: High.
-  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` and `run:<id>` → `session:<id>` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, `inspect target=tool:<name>` exposes registered tool actor contracts, `inspect target=coordinator` exposes current-session run inventory, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`, run termination now uses actor-native `control.stop`/`control.cancel`/`control.kill` without runtime-prefixed control aliases, async command events preserve full argv details while keeping coordinator summaries bounded, async-run operations recommendations now emit structured `message`/`inspect` objects instead of shell-like suggestion strings, `inspect view=messages` exposes run actor messages while retaining `events` as a compatibility alias, async-run operations recipes now expose `message_file`/`messages` terminology instead of public event-file args, and operator-facing docs now describe coordination with actor-message terminology before transport details, async-run docs separate public actor behavior from storage/transport mechanics more clearly, public actor-message/template guidance avoids transport-specific wording, and async-run operations recipes now use only `message_file` for actor-message inputs, and interactive recipe mailboxes now advertise actor-native termination controls where the runtime already supports them. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
+  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` and `run:<id>` → `session:<id>` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, `inspect target=tool:<name>` exposes registered tool actor contracts, `inspect target=coordinator` exposes current-session run inventory, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`, run termination now uses actor-native `control.stop`/`control.cancel`/`control.kill` without runtime-prefixed control aliases, async command events preserve full argv details while keeping coordinator summaries bounded, async-run operations recommendations now emit structured `message`/`inspect` objects instead of shell-like suggestion strings, `inspect view=messages` exposes run actor messages while retaining `events` as a compatibility alias, async-run operations recipes now expose `message_file`/`messages` terminology instead of public event-file args, and operator-facing docs now describe coordination with actor-message terminology before transport details, async-run docs separate public actor behavior from storage/transport mechanics more clearly, public actor-message/template guidance avoids transport-specific wording, and async-run operations recipes now use only `message_file` for actor-message inputs, interactive recipe mailboxes now advertise actor-native termination controls where the runtime already supports them, and task-first/library docs now describe operations snapshots in terms of actor-message tails instead of event tails. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
   - Scope: Design and implement a small semantic layer around addressed messages and actors while preserving low-level primitives as adapters where useful. Candidate top-level concepts are `spawn` for creating an actor/run from a recipe or template, `message` for sending typed messages to any address, and `inspect` for intentional observation/debugging. Candidate addresses include `run:<id>`, `branch:<run>/<branch>`, `coordinator`, `session:<id>`, `tool:<name>`, and future chat/session endpoints. Candidate message fields include `to`, `from`, `type`, `summary`, `body`, `reply_to`, `correlation_id`, and `metadata`.
   - Contract direction: Unify “send down” and “messages up” as one message model. `to: run:<id>` routes to a run mailbox, `to: coordinator` routes to the coordinator attention path, and branch/tool/session addresses can be layered over the same semantic envelope. Recipes should declare mailbox capability (`accepts`, `emits`) without exposing FIFO/outbox mechanics or delivery policy as their public interface.
   - Design gates: Breaking changes are allowed in this phase, so compress concepts instead of preserving accidental surfaces. Consolidate duplicated lifecycle/message/event APIs into a concentrated protocol with the fewest durable nouns and verbs that still explain the system. Duplex communication should be symmetric where the domain is symmetric: the same message envelope should represent run→coordinator, coordinator→run, run→run, branch→parent, and parent→branch traffic, with routing/transport hidden below it. Keep command templates as the portable synchronous execution graph; keep recipe files as semantic definitions; avoid leaking transports into public args; make polling an explicit diagnostic operation, not an example path; replace runtime action names with the actor API rather than preserving parallel concepts.

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.13.5: Actor Message Snapshot Wording
+
+- `[Docs]` Replaced remaining task-first and recipe-library event-tail wording for async-run operations with actor-message tail terminology. Impact: operations guidance now matches the `message_file` recipe surface and `inspect view=messages` actor vocabulary.
+- `[Utilities]` Updated the `recipe-utils.mjs run-ops-snapshot` usage text from `<event-file>` to `<message-file>`. Impact: helper diagnostics no longer teach the old public noun.
+
 ## 0.13.4: Interactive Recipe Termination Contracts
 
 - `[Recipe Library]` Added actor-native `control.stop`, `control.cancel`, and `control.kill` mailbox accepts to interactive artifact/message/fanout recipes and the music player recipe. Impact: `inspect view=mailbox` now advertises the run termination messages that the actor runtime supports for these long-lived recipe actors.

package/docs/recipe-library.md

@@ -71,7 +71,7 @@ Pipeline recipes demonstrate second-order composition:
 - `recipes/subagent-review-coordinator.json`: Lens reviewers → verifier → merger → judge → normalizer.
 - `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → validation → release review → artifact report.
 - `recipes/pipeline-repo-health.json`: Task-first repository-health cell: git status/log → docs index → validation → normalized artifact report.
-- `recipes/pipeline-async-run-ops.json`: Task-first async-run operations cell: run summary → event tail → normalized operations report → artifact report.
+- `recipes/pipeline-async-run-ops.json`: Task-first async-run operations cell: run summary → actor-message tail → normalized operations report → artifact report.
 - `recipes/pipeline-review-readiness.json`: Release/readiness gate over selected lenses.
 - `recipes/pipeline-quorum-review.json`: Quorum vote shape → merge → judge → normalize.
 - `recipes/pipeline-architect-coordinator.json`: Architecture lens fanout → critique → verification → synthesis → next slice.
@@ -91,7 +91,7 @@ These are examples of library composition, not a workflow DSL. Pipeline recipes
 Utility recipes cover local operator workflows that do not need subagents:
 
 - `recipes/utility-markdown-index.json`: List Markdown files in a directory as input for README/docs index maintenance.
-- `recipes/utility-jsonl-tail.json`: Tail a JSONL/event log with a configurable line count.
+- `recipes/utility-jsonl-tail.json`: Tail a JSONL message/log file with a configurable line count.
 - `recipes/utility-validation-wrapper.json`: Run a caller-supplied validation command in a scoped directory with a bounded timeout.
 - `recipes/utility-git-status.json`: Read concise branch/worktree state for a repo.
 - `recipes/utility-git-log.json`: Read recent decorated commit history for a repo.
@@ -99,7 +99,7 @@ Utility recipes cover local operator workflows that do not need subagents:
 - `recipes/utility-changelog-head.json`: Read the top slice of a changelog for release summary prep.
 - `recipes/utility-playlist-scan.json`: List local media files as playlist-building input.
 - `recipes/utility-run-summary.json`: Use `scripts/recipe-utils.mjs` to summarize async run state files as JSON.
-- `recipes/utility-run-ops-snapshot.json`: Combine async run summaries, event-tail JSONL, and stale/terminal recommendations into one structured operations snapshot.
+- `recipes/utility-run-ops-snapshot.json`: Combine async run summaries, actor-message JSONL tails, and stale/terminal recommendations into one structured operations snapshot.
 - `recipes/utility-playlist-build.json`: Use `scripts/recipe-utils.mjs` to build a filtered playlist listing as newline paths, M3U, or inline `|`-separated source.
 - `recipes/utility-changelog-section.json`: Use `scripts/recipe-utils.mjs` to extract one changelog release section.
 - `recipes/utility-artifact-manifest.json`: Use `scripts/recipe-utils.mjs` to emit a machine-readable JSON manifest for an artifact path.

package/docs/task-first-recipes.md

@@ -88,13 +88,13 @@ Purpose: inspect, summarize, and decide actions for local async runs.
 Pipeline:
 
 ```text
-run-state summary → event tail → stale/active classification → recommended action → optional stop/control message
+run-state summary → actor-message tail → stale/active classification → recommended action → optional stop/control message
 ```
 
 Likely needed cells:
 
 - run summary helper
-- JSONL event tailer
+- JSONL actor-message tailer
 - stale-run classifier
 - control-message recommender
 - run report artifact
@@ -108,7 +108,7 @@ Existing seeds:
 
 Implemented seed:
 
-- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines run summary, event tail, and recommended inspect/control messages before the LLM normalization step.
+- `pipeline-async-run-ops`: structured run operations snapshot → normalized operations report → artifact report. The snapshot combines run summary, actor-message tail, and recommended inspect/control messages before the LLM normalization step.
 
 ### Research Brief Cell
 
@@ -197,14 +197,14 @@ Purpose: convert local media directories into controllable playback workflows.
 Pipeline:
 
 ```text
-media scan → playlist build → playback start → event summary → controls
+media scan → playlist build → playback start → message summary → controls
 ```
 
 Likely needed cells:
 
 - playlist builder
 - music player
-- run/event summary
+- run/message summary
 - control recommender
 
 Existing seeds:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.13.4",
+  "version": "0.13.5",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "type": "module",

package/scripts/recipe-utils.mjs

@@ -5,7 +5,7 @@ import { dirname, extname, join, relative, resolve } from "node:path";
 function usage() {
   console.error(`Usage:
   recipe-utils.mjs run-summary <state-root>
-  recipe-utils.mjs run-ops-snapshot <state-root> <event-file> [lines] [stale-minutes]
+  recipe-utils.mjs run-ops-snapshot <state-root> <message-file> [lines] [stale-minutes]
   recipe-utils.mjs playlist <source-dir> [extensions] [max-depth] [paths|m3u|inline]
   recipe-utils.mjs changelog-section <file> <version>
   recipe-utils.mjs artifact-manifest <artifact-path> <title> <status> [summary]