@llblab/pi-actors 0.13.3 → 0.13.4

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. 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, 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.
   - 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,9 @@
 # Changelog
 
+## 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.
+
 ## 0.13.3: Actor Vocabulary Cleanup
 
 - `[Docs]` Removed remaining public FIFO/outbox phrasing from actor-message/template-recipe docs and runtime prompt guidance. Impact: agent and operator guidance now consistently describes `spawn`, `message`, and `inspect` without transport-specific vocabulary.

package/package.json

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

package/recipes/music-player.json

@@ -18,7 +18,7 @@
     "player": "auto"
   },
   "mailbox": {
-    "accepts": ["player.play", "player.pause", "player.resume", "player.toggle", "player.next", "player.previous", "player.stop", "player.status"],
+    "accepts": ["control.stop", "control.cancel", "control.kill", "player.play", "player.pause", "player.resume", "player.toggle", "player.next", "player.previous", "player.stop", "player.status"],
     "emits": ["player.track"]
   },
   "template": "{repo}/scripts/music-player.mjs {command} {source} {loop} {volume} {player} {state_dir}"

package/recipes/pipeline-artifact-report.json

@@ -19,6 +19,7 @@
     "tools": ""
   },
   "mailbox": {
+    "accepts": ["control.stop", "control.cancel", "control.kill"],
     "emits": ["artifact.prepared", "artifact.blocked"]
   },
   "template": [

package/recipes/pipeline-artifact-write.json

@@ -22,6 +22,7 @@
     "tools": ""
   },
   "mailbox": {
+    "accepts": ["control.stop", "control.cancel", "control.kill"],
     "emits": ["artifact.written", "artifact.blocked"]
   },
   "artifacts": {

package/recipes/subagent-artifact.json

@@ -20,6 +20,7 @@
     "tools": ""
   },
   "mailbox": {
+    "accepts": ["control.stop", "control.cancel", "control.kill"],
     "emits": ["artifact.prepared", "artifact.blocked"]
   },
   "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Prepare a durable artifact. Target path: {artifact_path}. Format: {artifact_format}. Write policy: {write_policy}. Validation policy: {validation_policy}. Input: {input}"

package/recipes/subagent-message.json

@@ -23,6 +23,7 @@
     "tools": ""
   },
   "mailbox": {
+    "accepts": ["control.stop", "control.cancel", "control.kill"],
     "emits": ["component.*"]
   },
   "template": "pi -p --model {model} --thinking {thinking} {tools?--tools:--no-tools} {tools} Create an actor-message envelope-shaped record. To: {to}. From: {from}. Type: {type}. Message policy: {message_policy}. Payload/body: {payload}. Output format: {output_format}"

package/recipes/subagents-prompts.json

@@ -26,6 +26,7 @@
     "summary": "{summary_path}"
   },
   "mailbox": {
+    "accepts": ["control.stop", "control.cancel", "control.kill"],
     "emits": ["command.done", "run.done", "run.failed"]
   },
   "repeat": "{prompts.length}",