@llblab/pi-actors 0.12.4 → 0.12.6

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## 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.
+
 ## 0.12.4: Actor Runtime Positioning
 
 - `[Docs]` Reframed README and package metadata around `pi-actors` as an actor runtime and orchestrator for agent-managed local processes, while preserving the persistent actor-tool registry as one capability. Impact: new readers see how templates, recipes, mailboxes, messages, artifacts, and run state turn any trusted local process into an agent-controllable actor.

package/README.md

@@ -126,17 +126,24 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
 
 ```json
 {
-  "name": "shader-ring-8-parallel",
+  "name": "docs-review",
   "async": true,
-  "parallel": true,
-  "template": ["..."]
+  "args": ["scope:path", "model:string"],
+  "defaults": {
+    "model": "openai-codex/gpt-5.5"
+  },
+  "mailbox": {
+    "accepts": ["control.stop"],
+    "emits": ["review.completed", "run.failed"]
+  },
+  "template": "pi -p --model {model} --no-tools \"Review {scope} for unclear actor-runtime onboarding. Return concise findings.\""
 }
 ```
 
 Expose a reusable actor recipe as a normal capability:
 
 ```text
-register_tool name=shader_ring description="Start shader ring" 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"
 ```
 
 `Task` is the user's work item. `Template` is the execution graph. `Actor recipe` is saved JSON. `Run` is one actor instance with status, logs, messages, cancellation, artifacts, and ambient triangles.
@@ -203,13 +210,13 @@ register_tool name=transcribe \
 For reusable actor workflows, keep the large template and mailbox contract in a recipe file and register a small tool:
 
 ```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"
 ```
 
-If the recipe file contains `async: true`, calling `shader_ring` starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+If the recipe file contains `async: true`, calling `docs_review` starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
 A recipe can also be co-located in `actors-tools.json` when keeping metadata and the recipe body together is clearer:
 
@@ -262,10 +269,10 @@ The commands above persist entries like this in `~/.pi/agent/actors-tools.json`;
     "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/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.4",
+  "version": "0.12.6",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "type": "module",