@llblab/pi-actors 0.30.2 → 0.32.0

package/AGENTS.md

@@ -61,6 +61,7 @@ Pi host
 - Prefer explicit operator action over silent user-config rewrites.
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
 - Preserve runtime output discipline because tool output flows directly into agent context.
+- Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
 - Keep the project lens local-first and cybernetic: agents wrap durable local capabilities as actors, then use semantic tools and messages instead of repeatedly reconstructing shell commands.
 - Design recipes as agent-callable tools: make prompts, scopes, paths, models, and policy knobs public args/defaults when the caller should decide them at invocation time.
 - Decompose oversized bullets into sublists or hierarchy; long flat list items are a context-smell.
@@ -80,6 +81,7 @@ Pi host
 ## Public Actor Model
 
 - Preserve the public verbs: `spawn`, `message`, `inspect`.
+- Keep the model-facing concept ladder minimal: core is run actors, typed messages, intentional inspection, artifacts, and recipe/tool memory; group messaging, roster, branches, sessions, and diagnostics are advanced surfaces.
 - Prefer one typed actor-message envelope for upward, downward, lateral, parent/branch, and branch/parent messages.
 - Prefer actor addresses and inspect views over exposing FIFO, outbox, or status mechanics as public concepts.
 - Keep route and semantic type separate: delivery behavior comes from `to`, while `type` describes intent.
@@ -116,6 +118,7 @@ Pi host
 ## State, IO, And Safety
 
 - Tool stdout and temp state must stay bounded and local.
+- Feedback hints must be evidence-backed, bounded, and action-shaped; prefer `next_actions` pointing to existing verbs over prose, and avoid hints when no concrete next step is justified.
 - Keep tail truncation, full-output temp files, failure formatting, and centralized limits intact.
 - Published docs must not include machine-local absolute paths.
 - Any view scanning run directories must apply coordinator/session ownership filters before exposing summaries or previews.

package/BACKLOG.md

@@ -47,25 +47,12 @@ No open hotfix items.
 - File length alone is not a domain-split trigger: ~1000-line cohesive domain files are acceptable when ownership is clear.
 - Consider splitting only when a file crosses roughly 2000 lines, mixes real ownership zones, or hides a clearer domain boundary.
 - Prefer semantic compression before file splitting: fewer public nouns, consistent outcomes, compact diagnostics, and domain-owned constants/helpers.
+- Preserve signal/noise balance: feedback should be state-backed, compact, and action-shaped; do not add advisory prose just because a surface exists.
 
 ## Minor Backlog
 
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
-### M-14 Session Mismatch Follow-through
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Extend 0.27 structured session diagnostics consistently across room, branch, run, coordinator, and session workflows.
-- Why now: M-12 established the shape; dogfood should now make every ownership denial equally actionable without relaxing ownership gates.
-- Direction:
-  - Audit all session mismatch errors for consistent `reason`, owner/current session fields, and inspect-session hints.
-  - Keep read/write ownership policy unchanged.
-  - Update docs with session mismatch examples and recovery inspection paths.
-- Acceptance:
-  - Room, branch, run, coordinator, and session denials share the same compact/verbose shape.
-  - Tests cover representative inspect and message paths.
-
 ### M-15 Worker Stale-Claim Dogfood
 
 - Priority: Medium.
@@ -111,23 +98,23 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Room messages distinguish timeline append success from forwarded branch-targeted copies.
   - Tests cover at least run, branch, room, coordinator, and ownership-denied outcomes.
 
-### M-18 Candidate Recipe Promotion UX
+### M-18 Draft Recipe Promotion UX
 
 - Priority: High.
 - Status: Planned.
-- Goal: Make successful ad hoc actor patterns easy to promote manually from candidate memory into active user recipe memory.
-- Why now: Candidate recipes under `~/.pi/agent/recipes/candidates` are replayable but intentionally not active tools; the two-stage memory model now needs an explicit operator-gated promotion path.
+- Goal: Make successful ad hoc actor patterns easy to promote manually from draft memory into active user recipe memory.
+- Why now: Draft recipes under `~/.pi/agent/recipes/candidates` are replayable but intentionally not active tools; the directory name is retained for compatibility, and the two-stage memory model now needs an explicit operator-gated promotion path.
 - Direction:
-  - List candidate recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
-  - Promote a selected candidate to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
+  - List draft recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
+  - Promote a selected draft to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
   - Run recipe validation/doctor before writing and expose collision/shadowing diagnostics.
-  - Preserve candidate files unless deletion is explicitly requested.
+  - Preserve draft files unless deletion is explicitly requested.
   - Prefer extending existing registry/tool surfaces over adding a new public noun.
 - Acceptance:
-  - Candidate recipes remain non-tools until promotion.
+  - Draft recipes remain non-tools until promotion.
   - Promotion writes atomically and never auto-promotes.
-  - Tests cover valid promotion, invalid candidate, name collision, and packaged-recipe shadowing.
-  - Docs explain candidate memory vs active tool memory in one compact section.
+  - Tests cover valid promotion, invalid draft, name collision, and packaged-recipe shadowing.
+  - Docs explain draft memory vs active tool memory in one compact section.
 
 ### M-24 Registry Path Naming Cleanup
 
@@ -166,10 +153,10 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 - Priority: Medium.
 - Status: Planned.
 - Goal: Add one compact operator triage view that answers what needs attention right now without performing repairs.
-- Why now: Runtime status, recipe doctor, candidates, stale claims, session mismatches, failed runs, and other-session counts are currently separate bounded surfaces.
+- Why now: Runtime status, recipe doctor, drafts, stale claims, session mismatches, failed runs, and other-session counts are currently separate bounded surfaces.
 - Direction:
   - Add `inspect target=tool:pi-actors view=triage` or an equivalent existing inspect surface.
-  - Summarize runtime version/mode, active runs, other-session runs, invalid or blocking recipes, high-risk recipes, candidate recipes, stale worker claims, recent failed runs, attention messages, and suggested next inspect actions.
+  - Summarize runtime version/mode, active runs, other-session runs, invalid or blocking recipes, high-risk recipes, draft recipes, stale worker claims, recent failed runs, attention messages, and suggested next inspect actions.
   - Keep every warning tied to a next inspect/action hint.
   - Do not auto-repair, auto-prune, relax ownership, or hide detailed source-of-truth views.
 - Acceptance:
@@ -226,7 +213,7 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: M-14 Session Mismatch Follow-through.
-Then: M-15 Worker Stale-Claim Dogfood → M-17 Message Delivery Outcome Contract → M-18 Candidate Recipe Promotion UX.
+Next milestone: M-15 Worker Stale-Claim Dogfood.
+Then: M-17 Message Delivery Outcome Contract → M-18 Draft Recipe Promotion UX.
 Small cleanup lane: M-23 Tool Boundary Type Tightening → M-24 Registry Path Naming Cleanup.
 ```

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.32.0: Actor Surface Minimization
+
+- `[Context]` Added durable signal/noise guidance for actor-facing surfaces: keep the model-facing concept ladder minimal, make feedback hints state-backed and action-shaped, and avoid speculative advisory prose.
+- `[Backlog]` Added critical concept-surface compression and actor feedback-loop strengthening tracks to guide the next minimization-focused development cycle.
+- `[Concepts]` Compressed model-facing language by presenting captured inline-spawn recipes as drafts, treating `room:<run>` as advanced group messaging plus roster, demoting coordinator/session/debug views from golden-path guidance, and keeping compatibility names/paths as storage details rather than core onboarding nouns.
+- `[Feedback]` Added bounded next-action hints to recipe registry/doctor inspection, artifact inspection, delivery-fallback message results, and terminal run follow-ups so state-backed surfaces point back to `inspect`, `message`, `spawn`, or draft promotion without polling or auto-repair.
+- `[Sessions]` Normalized session-directed message ownership failures onto the same structured `reason=session_mismatch`, owner/current session, and inspect-session hint shape used by run, branch, room, and coordinator ownership denials.
+
+## 0.31.0: Agent Adoption Ergonomics
+
+- `[Adoption]` Added a compact actor-mode trigger rule to the injected prompt, actors skill, README, and async-run docs so models prefer `spawn → message → inspect` for long-lived, stateful, follow-up, artifact, service, fanout, and resumable work while keeping short foreground checks as ordinary tools.
+- `[Skills]` Reframed the bundled actors skill as required practical guidance for non-trivial actor use or pi-actors changes, and made the injected prompt route agents to it before improvising actor workflows.
+- `[Tools]` Strengthened `spawn`, `message`, and `inspect` descriptions with adoption cues that steer models away from ad hoc shell backgrounding, actor restarts, and polling loops.
+- `[Spawn]` Added explicit next-action feedback to spawn results so newly created actors immediately suggest inspect/message chains instead of leaving agents to infer the next step.
+- `[Docs]` Added a task-first “when to use actors” golden path to the README without adding public verbs or scheduler/service-manager concepts.
+
 ## 0.30.2: Music Player Kill Hotfix
 
 - `[Music Player]` Kept backend player processes inside the async run process group so `control.kill` can terminate an active music-player run without leaving detached `cvlc`/player children alive.

package/README.md

@@ -29,7 +29,26 @@ inspect  intentionally read state, logs, messages, contracts, or artifacts
 
 Everything else is an adapter until proven otherwise.
 
-Use `spawn` when work may outlive the current turn. Use `message` when the actor should be steered rather than restarted. Use `inspect` at decision points, after actor follow-ups, or during diagnosis. Do not build polling loops as the default coordination pattern.
+Use `spawn` when work may outlive the current turn. Use `message` when the actor should be steered rather than restarted. Use `inspect` at decision points, after actor follow-ups, or during diagnosis. For non-trivial actor use, load the bundled `actors` skill before improvising. Do not build polling loops as the default coordination pattern.
+
+## When To Use Actors
+
+Use actor-mode instead of ad hoc shell backgrounding when work is:
+
+- Long-running or likely to outlive this agent turn.
+- Stateful, resumable, or something you will need to inspect later.
+- Expected to produce named artifacts or follow-up messages.
+- A service, worker, media process, fanout, subagent, or pipeline.
+- A repeatable local capability worth promoting into recipe memory.
+
+Keep ordinary foreground tools for short checks such as `rg`, `ls`, quick tests, and one-shot transforms. The golden path is:
+
+```text
+create actor        -> spawn
+steer actor         -> message
+read state/results  -> inspect
+repeatable pattern  -> promote to recipe/tool memory
+```
 
 ## Install
 
@@ -47,16 +66,21 @@ The npm package is dist-first for JavaScript-only runtimes: default Pi metadata
 
 ## Address Surface
 
-Actors and coordination endpoints are addressed with compact route strings:
+Core actor addresses stay small:
+
+```text
+run:<id>      one detached actor run
+tool:<name>   executable registered tool actor
+```
+
+Advanced coordination/debug addresses are available when a recipe or workflow needs them:
 
 ```text
-run:<id>               one detached actor run
-branch:<run>/<branch>  branch-local actor endpoint
-room:<run>             shared run-local task room
-coordinator            launching coordinator attention path
+branch:<run>/<branch>  branch-local worker endpoint
+room:<run>             group-message timeline plus roster for one run
+coordinator            compatibility alias for the current session coordination path
 session:               current session actor surface
-session:all            cross-session inventory surface
-tool:<name>            executable registered tool
+session:all            cross-session inventory surface for diagnostics
 ```
 
 Actor messages use one envelope shape:
@@ -121,9 +145,9 @@ message to=run:docs_review type=control.continue body=continue
 message to=run:docs_review type=control.kill body=stop
 ```
 
-## Actor Rooms
+## Group Messaging And Roster
 
-Every spawned run can have a shared room at `room:<run>`. A room is not a broker and not a chat app. It is a run-local coordination surface: append-only timeline, compact roster, member discovery, and previews.
+Every spawned run can have advanced group messaging at `room:<run>`. Treat this as a run-local timeline plus roster for coordinated actors, not as a core chat/broker concept.
 
 Actors can join, post, leave, and discover peers:
 
@@ -136,7 +160,7 @@ message \
   body='{"role":"reviewer","caps":["security-review"],"claim":"Review auth boundary risks"}'
 ```
 
-Inspect the room intentionally:
+Inspect group messages and roster intentionally:
 
 ```text
 inspect target=room:review view=status
@@ -146,7 +170,7 @@ inspect target=room:review view=contacts
 inspect target=room:review view=messages
 ```
 
-Room posts require a same-run sender, so unrelated runs do not pollute the roster. Direct messages and room messages use the same envelope; only the address changes. Direct `branch:<run>/<branch>` messages are private: they are forwarded through the parent run mailbox and recorded in the recipient branch inbox for worker protocols that consume queued branch work. For selected-recipient multicast, send to `room:<run>` with `metadata.recipients` set to same-run `branch:<run>/<branch>` addresses; this keeps one room transcript entry while forwarding branch-targeted copies.
+Group posts require a same-run sender, so unrelated runs do not pollute the roster. Direct messages and group messages use the same envelope; only the address changes. Direct `branch:<run>/<branch>` messages are private: they are forwarded through the parent run mailbox and recorded in the recipient branch inbox for worker protocols that consume queued branch work. For selected-recipient multicast, send to `room:<run>` with `metadata.recipients` set to same-run `branch:<run>/<branch>` addresses; this keeps one visible transcript entry while forwarding branch-targeted copies.
 
 ## Actor Inspector
 

package/dist/lib/observability.js

@@ -721,19 +721,30 @@ function formatRecipePersistenceSuggestion(transition) {
     }
     return `\nAgent note: this actor was spawned directly and completed successfully. If this pattern fits this machine's recurring workflow, ask the operator whether to save it as a durable recipe/tool under ~/.pi/agent/recipes with register_tool. Do not auto-save without confirmation.`;
 }
+function formatTransitionNextActions(transition) {
+    const actions = [
+        `inspect target=run:${transition.run} view=status`,
+        transition.to === "done" && Object.keys(transition.artifacts ?? {}).length > 0
+            ? `inspect target=run:${transition.run} view=artifacts`
+            : `inspect target=run:${transition.run} view=tail`,
+        `inspect target=run:${transition.run} view=messages`,
+    ].filter(Boolean);
+    return `\nNext actions: ${actions.join(" | ")}`;
+}
 export function formatRunTransitionMessage(transition) {
     const artifacts = formatNamedArtifacts(transition.artifacts);
     const runFiles = formatRunFileList(getRunArtifacts(transition));
     const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
+    const nextActions = formatTransitionNextActions(transition);
     if (transition.to === "done")
-        return `Run ${transition.run} completed successfully.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail if the result needs inspection.${persistenceSuggestion}`;
+        return `Run ${transition.run} completed successfully.${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
     if (transition.to === "failed")
-        return `Run ${transition.run} failed.${artifacts}${runFiles}\nUse inspect target=run:${transition.run} view=status or view=tail for details.`;
+        return `Run ${transition.run} failed.${artifacts}${runFiles}${nextActions}`;
     if (transition.to === "cancelled")
-        return `Run ${transition.run} was cancelled. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+        return `Run ${transition.run} was cancelled.${nextActions}`;
     if (transition.to === "killed")
-        return `Run ${transition.run} was force-killed. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+        return `Run ${transition.run} was force-killed.${nextActions}`;
     if (transition.to === "exited")
-        return `Run ${transition.run} exited before writing a result. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
-    return `Run ${transition.run} finished with status ${transition.to}. Use inspect target=run:${transition.run} view=status or view=tail if analysis is needed.`;
+        return `Run ${transition.run} exited before writing a result.${nextActions}`;
+    return `Run ${transition.run} finished with status ${transition.to}.${nextActions}`;
 }

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.\n- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.\n- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -21,12 +21,12 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.
 - Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
-- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
+- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.
+- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
 - Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
-- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
-- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;
+- For any non-trivial actor use or pi-actors change, read the bundled actors skill first; for deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.`;
 export const REGISTER_TOOL_PARAM_DESCRIPTIONS = {
     name: "Tool name in snake_case (e.g., 'transcribe')",
     description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.",