@llblab/pi-actors 0.12.5 → 0.12.6

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.12.6: Documentation Example Alignment
+
+- `[Docs]` Replaced remaining shader-ring recipe examples in registry and template-recipe docs with the concrete docs-review actor recipe example, aligned test fixtures, and changed async-run outbox docs to show actor message envelopes without public delivery knobs. Impact: public docs now consistently demonstrate useful actor wrapping and keep coordinator attention policy out of recipe-authored message examples.
+
 ## 0.12.5: README Actor Recipe Example
 
 - `[Docs]` Replaced the placeholder shader-ring onboarding recipe with a concrete async docs-review actor recipe that includes typed args, mailbox metadata, and a real launch template. Impact: README onboarding now demonstrates actor wrapping instead of an abstract placeholder.

package/docs/async-runs.md

@@ -188,22 +188,19 @@ Shape:
 
 ```json
 {
-  "event": "player.track",
+  "type": "player.track",
+  "to": "coordinator",
+  "from": "run:music-player",
   "summary": "Now playing: track.flac",
   "level": "info",
-  "delivery": "log",
   "ts": "2026-05-19T00:00:00.000Z",
-  "data": { "track": "/Music/track.flac", "index": 3, "count": 42 }
+  "body": { "track": "/Music/track.flac", "index": 3, "count": 42 }
 }
 ```
 
-`level` is `info`, `warning`, or `error`. `delivery` is `log`, `notify`, or `followup`:
+`level` is `info`, `warning`, or `error`. The public message describes sender, receiver, type, summary, and body; it does not choose notification mechanics. Runtime attention policy infers whether a coordinator-bound message stays available for explicit `inspect`, becomes a UI notification, or re-enters the launching coordinator as compact follow-up context.
 
-- `log`: stored only; read explicitly with `inspect view=events`.
-- `notify`: shown as a UI notification to the launching coordinator session.
-- `followup`: notification plus compact follow-up context to the launching coordinator session.
-
-Use `followup` for completion and decision-point messages that should reach the coordinator, not for every progress tick. Packaged multi-agent branch completion is a completion message and should bubble by default. Follow-up path lists use Markdown hierarchy: a section heading, `- Base: ...`, and `- Files: ...`, so repeated run-state prefixes do not flood agent context.
+Use coordinator-bound messages for completion and decision points, not for every progress tick. Packaged multi-agent branch completion is a completion message and should bubble by default. Follow-up path lists use Markdown hierarchy: a section heading, `- Base: ...`, and `- Files: ...`, so repeated run-state prefixes do not flood agent context.
 
 ## Cancellation And Ownership
 

package/docs/template-recipes.md

@@ -170,15 +170,15 @@ A registered tool can point at an actor recipe by storing the recipe path or nam
 
 ```json
 {
-  "shader_ring": {
-    "description": "Start the shader ring recipe",
-    "args": ["theme", "out_dir"],
-    "template": "shader-ring-8-parallel.json"
+  "docs_review": {
+    "description": "Start an async docs review actor",
+    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "template": "docs-review.json"
   }
 }
 ```
 
-If `shader-ring-8-parallel.json` contains `async: true`, calling `shader_ring` starts a detached run and returns metadata. If `async` is omitted or false, calling `shader_ring` executes the recipe foreground and returns normal tool output.
+If `docs-review.json` contains `async: true`, calling `docs_review` starts a detached actor run and returns metadata. If `async` is omitted or false, calling `docs_review` executes the recipe foreground and returns normal tool output.
 
 A registered tool may also co-locate an actor recipe directly in `actors-tools.json`:
 

package/docs/tool-registry.md

@@ -47,16 +47,16 @@ Use `update=true` to overwrite an existing tool. Omit `template` and co-located
 ]
 ```
 
-For reusable workflows, register a small tool whose `template` points to a template recipe instead of embedding a large parallel template in the tool itself:
+For reusable actor workflows, register a small tool whose `template` points to an actor recipe instead of embedding the launch graph in the tool itself:
 
 ```text
-register_tool name=shader_ring \
-  description="Start the shader ring recipe" \
-  template="shader-ring-8-parallel.json" \
-  args="theme,out_dir"
+register_tool name=docs_review \
+  description="Start an async docs review actor" \
+  template="docs-review.json" \
+  args="scope:path,model:string=openai-codex/gpt-5.5"
 ```
 
-This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/shader-ring-8-parallel.json` contains `async: true`, calling the tool starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/docs-review.json` 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, the registry entry may include recipe fields directly beside tool metadata:
 
@@ -93,10 +93,10 @@ Tool names come from the top-level registry keys. Tool entries define `template`
     "description": "Run pi as a non-interactive sub-agent",
     "template": "pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
   },
-  "shader_ring": {
-    "description": "Start the shader ring recipe",
-    "args": ["theme", "out_dir"],
-    "template": "shader-ring-8-parallel.json"
+  "docs_review": {
+    "description": "Start an async docs review actor",
+    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "template": "docs-review.json"
   }
 }
 ```

package/package.json

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