@llblab/pi-actors 0.58.1 → 0.58.3

package/skills/actors/references/runs.md

@@ -5,26 +5,26 @@ Use a Run when execution may outlive the current turn, needs declared Control, p
 ## Launch
 
 ```text
-spawn recipe=<skill>/<recipe> values={...} as=run:<id>
+actors_run_spawn recipe=<skill>/<recipe> values={...} as=run:<id>
 ```
 
 Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
 
 A rare Skill Recipe may declare `singleton: true`. Do not pass `as`: the runtime derives `run:<skill>` plus the canonical `<skill>/<recipe>` identity, allows at most one singleton Recipe per Skill, and returns the same compatible healthy active Run instead of launching a duplicate. Contradictory Recipe identity, startup values, Control, or ownership fails closed. Delegation inherits both singleton identities instead of retargeting them. Runtime tool failures after executor entry or async launcher handoff retain their original error/cause/details instead of guessed argument-repair guidance. A later missing-value failure can follow partial work; inspect the existing evidence rather than blindly replaying the invocation. Pre-dispatch argument guidance is not proof that no preparation effect occurred, and dispatch is not actuation or closure. Configured retry policies remain unchanged.
 
-Compact spawn/async-tool receipts use flat Markdown-list fields: run, state, launch_kind and admitted optional facts; model/thinking policy source-value relationships may nest. The displayed Run key has no duplicated namespace. Multiline values preserve their Markdown content, and structured/verbose data remains unchanged. A compact attachment receipt explicitly says existing Run reused; that reports the backend's reuse fact, not another generation, readiness promise or scope proof. A terminal result is never reused; after its runner exits, restart keeps the logical Run id but creates a new fenced generation. Continuity still depends on actor-owned validated state, not the Run id alone.
+Compact spawn/async-tool receipts use bare block-YAML fields: run, state, launch_kind and admitted optional facts; model/thinking policy source-value relationships may nest. The displayed Run key has no duplicated namespace. Multiline values preserve their Markdown content, and structured/verbose data remains unchanged. A compact attachment receipt explicitly says existing Run reused; that reports the backend's reuse fact, not another generation, readiness promise or scope proof. A terminal result is never reused; after its runner exits, restart keeps the logical Run id but creates a new fenced generation. Continuity still depends on actor-owned validated state, not the Run id alone.
 
 ## Observe
 
 Normally wait for the completion batch: ready trees reach an active root coordinator at the next safe model-step boundary after the full tool batch, or wake an already-idle coordinator through a debounced follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
 
 ```text
-inspect target=run:<id> view=recipe
-inspect target=run:<id> view=trace
-inspect target=run:<id> view=control
+actors_inspect target=run:<id> view=recipe
+actors_inspect target=run:<id> view=trace
+actors_inspect target=run:<id> view=control
 ```
 
-Fresh root completions use YAML frontmatter (run, state, admitted kind), followed by raw left-edge Markdown. Prepend the packet-local index only when two or more results are shown. Exactly one shown result omits its index even with omitted results; preserve omission/inventory metadata, internal member/generation/correlation and every saved message. This rule does not apply to numbered streams. New source captures put all runtime metadata above that body, with no service/file footer. files.groups gives one literal root plus relative entry paths; files.read_first names zero-based group/entry indices for the first useful source, not an automatic read. role/purpose guidance is English; Actor Markdown and path/name bytes are unchanged. External paths use separate roots; unknown bases remain explicit rather than guessed from cwd or Run id. Known cut counts alone may follow the cut body; unknown-loss warnings and packet omission/inventory facts stay in the header. Retained captures preserve their old bytes and presentation. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact source/generation/parent/location references remain in complete model content, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
+Fresh root completions use YAML frontmatter (run, state, admitted kind), followed by raw left-edge Markdown. Prepend the packet-local index only when two or more results are shown. Exactly one shown result omits its index even with omitted results; preserve omission/inventory metadata, internal member/generation/correlation and every saved message. This rule does not apply to numbered streams. New source captures put all runtime metadata above that body, with no service/file footer. files.groups gives one literal root plus relative entry paths; files.read_first names zero-based group/entry indices for the first useful source, not an automatic read. Role/name and concise admitted status replace repeated per-file purposes/format/size/mutable/generation dumps; full bindings remain in saved snapshots. Status keeps admission privacy, Actor-response/exported-text, metadata-only diagnostics and unverified declarations distinct. Unavailable locations and missing terminal-result locations stay explicit; Actor Markdown and path/name bytes are unchanged. External paths use separate roots; unknown bases remain explicit rather than guessed from cwd or Run id. Known cut counts alone may follow the cut body; unknown-loss warnings and packet omission/inventory facts stay in the header. Retained captures preserve their old bytes and presentation. No external #N heading, result:/preview: wrapper, list nesting, whole-body fence, Batch caption, members wrapper or routine outer counter is added. Primary/final Actor response uses kind:primary; explicit error/failure diagnostic text uses kind:diagnostic, never a launch command. Untracked fallback has no kind and keeps unknown original completeness/privacy explicit outside YAML. Known cut loss is [N characters omitted] at the cut, with no extra ellipsis or body clipping counters/flags in metadata. Unknown upstream loss remains separately unknown and does not assert a known positive omission. Exact useful source/location paths remain in complete model content, while generation/hash/parent bindings stay in the frozen snapshot, with whole references or explicit omission, captured inventory recovery and non-done omitted states. The compact TUI independently renders literal headers/markers and native Markdown bodies from validated content-bound blocks; only whole header reference/location rows and framing are hidden. Expansion and invalid/missing hints reveal original text. Hashes/layout/markers establish consistency/correlation only, never authentication, read/action permission, acceptance or native truth. Authored YAML/next/tool/batch/omission lookalikes stay body content. Fresh packets share48KiB UTF-8 including service data, equally between up to64candidate rows, with256captured members and no redistribution of unused shares or fixed16KiB/2KiB text cap. Full admitted text fitting its share without upstream uncertainty has no cut marker; otherwise use the scalar/CRLF-safe prefix and exact retained-source loss. Allocation/text is frozen at admission; rendering/recovery does not reread sources or reallocate. Unsupported Pi event/control output is withheld. Source basis stays in reference metadata; retained structured coverage facts are not exposed as YAML clipping fields. Pending/queued/presented older formats—including #N records and the first frontmatter draft—keep exact bytes, hints and budgets. Encoding names are storage replay data, not public product choices, source permissions or work authority. No standing full-map instruction or automatic research/read follows; use selective same-session investigation when needed.
 
 Current completion index values restart within each packet; they are not session-wide historical references. Completion streams are adopted but not enabled, and no start-stream command is available yet. Do not infer an active stream or reset a counter from missing metadata or a pending target, and never relabel older saved packets. The kernel-only allocator now commits fixed scope/order/indices, the counter and first-packet target activation together, and an internal fresh-session bridge can use it after current manager/generation admission. The default runtime does not opt in; no public action exposes it. Event reason or a matching ID alone is insufficient. Old callbacks/wrappers cannot act after replacement; fresh wrappers must belong to the current original manager. Startup/reload/resume and ambiguous imports remain closed to stream capture/ACK, without changing saved packets or inferring a counter from history. Its whole-range exhaustion or admitted counter unavailability yields a frozen unknown index (quoted "?" in fresh YAML; #? in older saved layouts), never partial indices or an automatic fresh stream. Old packets retain their original scope while a pending switch waits; uncertainty does not permit reallocation. Stream state outlives packet cleanup/receipt rotation. Malformed/missing state remains refused, not a zero counter or proof of non-connection.
 
@@ -44,17 +44,17 @@ Ordinary notify/followup selects this AX layout only for new sink delivery. Noti
 
 ## Investigate Known Files
 
-Compact spawn/async-tool receipts now carry `file_navigation`: observed canonical starting locations for that exact generation, admitted against the current session before and after observation. It needs no catalog/body read or original producer key; missing/stale/foreign locations stay unavailable, and oversize rows are omitted whole within the compact card budget. Locations are mutable research data, not body/privacy/terminal/native proof. The compact run_files value keeps the whole selected observed location data in nested block YAML or reports a whole Run-row omission with shown/omitted/total counts, within the shared16KiB bound including response spacing. JSON-compatible details and saved terminal-packet encodings are unchanged. The optional current-session full-map command remains available but is not repeated when a complete direct location row is actually shown; absent/unavailable/omitted rows retain one next node naming tool=inspect, target=runtime, view=runs, verbose=true rather than disguising a command as observed data. It never executes automatically. New completion packets also capture bounded member location rows once, in root-first order with observed failed subtrees before peer children. They use only the remaining shared model budget after outcomes, with separate honest Run-row counts. Reload/render never reads sources or refreshes that data. Old absent/request-only packet formats keep their earlier text; source/npm SDK verifies an explicitly requested result read from a terminal row, without routine polling or original producer keys. Inherited locations/hints never transfer ownership.
+Compact spawn/async-tool receipts now carry `file_navigation`: observed canonical starting locations for that exact generation, admitted against the current session before and after observation. It needs no catalog/body read or original producer key; missing/stale/foreign locations stay unavailable, and oversize rows are omitted whole within the compact card budget. Locations are mutable research data, not body/privacy/terminal/native proof. The compact run_files value selects exact useful context-index/result/execution/metadata paths plus unavailable-location status in nested block YAML, or reports a whole Run-row omission with shown/omitted/total counts within16KiB including response spacing. It does not enumerate absent optional technical files or repeat format/size/mutable/generation facts. Full JSON-compatible details retain every admitted observation; this is a read-free projection, not a complete inventory, body certificate or new status engine. JSON-compatible details and saved terminal-packet encodings are unchanged. The optional current-session full-map command remains available but is not repeated when a complete direct location row is actually shown; absent/unavailable/omitted rows retain one next node naming tool=inspect, target=runtime, view=runs, verbose=true rather than disguising a command as observed data. It never executes automatically. New completion packets also capture bounded member location rows once, in root-first order with observed failed subtrees before peer children. They use only the remaining shared model budget after outcomes, with separate honest Run-row counts. Reload/render never reads sources or refreshes that data. Old absent/request-only packet formats keep their earlier text; source/npm SDK verifies an explicitly requested result read from a terminal row, without routine polling or original producer keys. Inherited locations/hints never transfer ownership.
 
 For an explicit file investigation, request the existing management route:
 
 ```text
-inspect target=runtime view=runs verbose=true
+actors_inspect target=runtime view=runs verbose=true
 ```
 
 Its `navigation` selects only the actual current logical session's already cataloged, generation-checked directories. Start at the root's context index/result, then follow selected locations with ordinary file tools; no original producer key is needed. Resuming the same saved session after restart retains this research scope; a new/forked/cloned session does not inherit it through copied history or paths.
 
-The ordinary map keeps independent roots latest-registration-first and puts known failed child subtrees before other siblings without moving a descendant ahead of its ancestors. For an explicit failed investigation use inspect target=runtime view=runs status=failed verbose=true. This filters inventory, not navigation: the full owned map then puts observed failed root subtrees first, with recency as the stable peer tie-break. Its priority.root_order is latest_registration or failed_subtrees_first and priority.basis=observed_failed_rows; missing/unmatched observations remain unranked, not proof of success. Ordering grants no ownership/terminal/native authority and does not read extra evidence or rewrite the catalog.
+The ordinary map keeps independent roots latest-registration-first and puts known failed child subtrees before other siblings without moving a descendant ahead of its ancestors. For an explicit failed investigation use actors_inspect target=runtime view=runs status=failed verbose=true. This filters inventory, not navigation: the full owned map then puts observed failed root subtrees first, with recency as the stable peer tie-break. Its priority.root_order is latest_registration or failed_subtrees_first and priority.basis=observed_failed_rows; missing/unmatched observations remain unranked, not proof of success. Ordering grants no ownership/terminal/native authority and does not read extra evidence or rewrite the catalog.
 
 This bounded map marks file_inventory_scope=canonical_starting_locations and reports file locations, observed sizes and format_hint (json/jsonl/text). Hints describe the expected layout, not validated syntax/UTF-8 or complete output; it is not a full file inventory, body, original privacy, terminal/clock/native truth or authority to change state. Missing/nonregular/stale locations stay unavailable, whole-row omission counts are explicit, and corrupt/missing catalogs report `catalog_unavailable` without repair or turning healthy Runs into failures. New launches and explicit compatible singleton attachments register their exact existing generation; reads never scan/backfill missing entries. A `catalog: unavailable` launch warning means that separate registration attempt did not complete, not that the work failed. Do not relaunch merely to repair the map; even failed publication can leave committed catalog bytes. Current ordering covers directly owned rows and their exact same-session parent links, not a complete cross-session descendant tree. Compact/default inspection still does not build a map. Launch text offers that request as a fallback when no complete direct row is shown; existing new-outcome formats retain their optional request. Neither embeds a session-wide map or file bodies.
 
@@ -73,7 +73,7 @@ Do not infer successful native closure from a teardown count, signal attempt or
 Send an actor-local action only when the root Recipe declares and implements it:
 
 ```text
-message target=run:<id> action=<declared-action> input={...}
+actors_control_apply target=run:<id> action=<declared-action> input={...}
 ```
 
 Inspect Control when readiness, capacity, stale work, or saturation matters. Put large data in an artifact and send only a bounded reference or instruction. Use runtime-owned termination for a stuck Run rather than inventing undeclared service actions.

package/skills/music-player/SKILL.md

@@ -16,10 +16,10 @@ When a Telegram-originated turn or explicit Telegram-control question makes repe
 `music-player/playback` is a singleton async controlled service with the canonical address `run:music-player`. The Recipe is the sole lifecycle owner: it starts the service, supervises it, and stops playback when the Run closes. The service owns queue, backend, checkpoint, and playback state. `scripts/playback.mjs` owns both foreground playback and the bounded control CLI. Its `control <state-dir> <action> [percent]` entrypoint observes or controls an existing owner without starting, adopting, or supervising it. Explicit foreground `serve` supports a caller-owned standalone host without importing the Actor runtime; Actor and standalone ownership of one state directory are mutually exclusive.
 
 ```text
-spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
-message target=run:music-player action=pause
-message target=run:music-player action=next
-inspect target=run:music-player view=control
+actors_run_spawn recipe=music-player/playback values={"source":"~/Music","player":"auto"}
+actors_control_apply target=run:music-player action=pause
+actors_control_apply target=run:music-player action=next
+actors_inspect target=run:music-player view=control
 ```
 
 A repeated compatible spawn returns the healthy active singleton instead of launching a second player. A terminal or dead singleton restarts under the same Run id with a fresh fenced generation and restores its validated playback checkpoint when the source and configuration still match.

package/skills/music-player/scripts/playback.mjs

@@ -112,7 +112,7 @@ function usage() {
 Runs a foreground music player so pi-actors can own it as a controlled Run.
 Actor-owned controls use canonical records in <state-dir>/controls.jsonl.
 Standalone controls use the generation-fenced playback service endpoint.
-Prefer message target=run:<run> action=<command> for Actors; external adapters use control <state-dir> <action>.
+Prefer actors_control_apply target=run:<run> action=<command> for Actors; external adapters use control <state-dir> <action>.
 Supported players: auto, mpv, afplay, ffplay, cvlc, play, wmp.
 `);
 }

package/skills/recipe-memory/SKILL.md

@@ -11,13 +11,13 @@ Use this Skill only when automatic draft-memory or active-tool review needs diag
 
 Automatic reviewers receive value-free contract shape, risk labels, usage counts, and batch-local equality groups, not executable content, descriptions, paths, or canonical names. Structural evidence and launch counts alone do not establish semantic purpose, good tool names, successful reuse, or accepted outcomes. Promotion preserves unchanged captured executable content; it does not generalize a one-off mission.
 
-Explicit create-only retention is owned by `actors` through `register_tool expose=false`, not by these internal reviewers. Automatic retained lifecycle is not implemented. Current draft promote/discard and tool-review behavior are unchanged. Missing evidence is unknown; this guidance adds no retain/defer action, retry permission, automatic rewrite, or live migration. Do not bypass confidentiality or edit review state to simulate the future policy.
+Explicit create-only retention is owned by `actors` through `actors_tool_register expose=false`, not by these internal reviewers. Automatic retained lifecycle is not implemented. Current draft promote/discard and tool-review behavior are unchanged. Missing evidence is unknown; this guidance adds no retain/defer action, retry permission, automatic rewrite, or live migration. Do not bypass confidentiality or edit review state to simulate the future policy.
 
 ## Diagnose first
 
 ```text
-inspect target=recipes view=reviews
-inspect target=runtime view=triage
+actors_inspect target=recipes view=reviews
+actors_inspect target=runtime view=triage
 ```
 
 Use the review view to distinguish `draft` and `tool` scope, current phase, failed stage, bounded error, preserved transaction evidence, and the recorded next action. Use runtime triage only when the reviewer Run itself needs Run-level diagnosis. Follow `actors` for generic Inspect, Run, and Control semantics.
@@ -27,10 +27,10 @@ Use the review view to distinguish `draft` and `tool` scope, current phase, fail
 Use runtime Controls only when the review evidence names the matching recovery action:
 
 ```text
-message target=runtime action=review.retry input={"scope":"draft"}
-message target=runtime action=review.retry input={"scope":"tool"}
-message target=runtime action=review.reset input={"scope":"draft"}
-message target=runtime action=review.reset input={"scope":"tool"}
+actors_control_apply target=runtime action=review.retry input={"scope":"draft"}
+actors_control_apply target=runtime action=review.retry input={"scope":"tool"}
+actors_control_apply target=runtime action=review.reset input={"scope":"draft"}
+actors_control_apply target=runtime action=review.reset input={"scope":"tool"}
 ```
 
 - `review.retry` resumes the selected failed review scope while preserving authenticated transaction recovery.