@llblab/pi-actors 0.46.1 → 0.48.0

package/dist/skills/actors/references/persistent-tools.md

@@ -0,0 +1,74 @@
+# Persistent Tools
+
+Use a persistent tool when the agent should call a trusted capability by name across turns or sessions. Use `spawn` instead for one-off Recipe execution.
+
+## Choose one source mode
+
+```text
+Maintained or explicit-file Recipe
+→ register_tool from=<skill>/<recipe|path.json|path.md>
+
+Trusted command template
+→ register_tool template="..."
+
+Reviewed captured draft
+→ register_tool draft=<draft-path>
+```
+
+Do not mix source modes.
+
+## Specialize a maintained Recipe
+
+```text
+register_tool
+  name=music_player
+  from=media/player
+  defaults={"source":"~/Music/1MIX"}
+```
+
+`from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
+
+Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
+
+## Prove registration
+
+Read registration as a state transition, not one success word:
+
+```text
+resolved
+→ validated
+→ persisted
+→ registry_active
+→ host_registered
+→ active_tool
+→ callable_now
+```
+
+When `callable_now` is true, call the actual generated tool and verify `launch_kind: "tool"` when provenance matters. When false, stop at the reported activation boundary and use tool/Recipe diagnosis. A Recipe spawn is not an activation test or tool invocation substitute.
+
+Use:
+
+```text
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+inspect target=recipes view=doctor
+```
+
+## Command templates
+
+Use `template` only for a trusted command definition, not to make the agent guess whether a string is command text or Recipe delegation. Give raw command tools an agent-facing description and declare or infer only caller-owned args. Use a Recipe file when reusable composition or lifecycle policy is needed.
+
+## Updates and deletion
+
+Use `update=true` only for an intentional replacement. Preserve the existing capability when candidate resolution, validation, persistence, or activation fails. Use the compact deletion form documented by the live `register_tool` schema; do not create a second deletion mechanism.
+
+## Stop rules
+
+Stop rather than:
+
+- copying source Recipe args, defaults, artifacts, Control, or helper command;
+- invoking a Skill helper by installation path;
+- using `spawn` and claiming the tool was called;
+- treating persistence as callability;
+- adding shell evaluation or backgrounding to bypass registration;
+- editing an unrelated rejected Skill component unless that repair is explicitly requested.

package/dist/skills/actors/references/recipes.md

@@ -0,0 +1,51 @@
+# Recipes
+
+A Recipe is a reusable executable definition. Address a maintained component as `<active-skill>/<direct-filename-stem>` or use an explicit `.json` / `.md` path. Recipe files do not declare their own top-level `name`.
+
+## Direct delegation
+
+Use direct delegation when the root remains fundamentally the same capability under a different persistent name, description, or caller default:
+
+```text
+media/player
+→ music_player with a default source
+```
+
+For agent-facing persistent specialization, use:
+
+```text
+register_tool from=media/player defaults={"source":"~/Music/1MIX"}
+```
+
+The delegated root inherits async behavior, args and types, defaults, artifacts, Control, and runtime-owned origins. Do not copy those fields into the wrapper.
+
+## Named import composition
+
+Use imports when authoring a graph with reusable named nodes:
+
+```json
+{
+  "imports": {
+    "review": "swarm/quorum-review",
+    "report": "artifacts/report"
+  },
+  "template": [
+    { "name": "review" },
+    { "name": "report" }
+  ]
+}
+```
+
+Imports are local definitions inside one execution graph. An imported child does not automatically make its Control contract the root Run's Control contract. Do not use imports merely to wrap one Recipe with defaults.
+
+## Caller and runtime ownership
+
+Callers provide only the effective public args. The runtime owns Recipe/Skill location, Run state, Trace, generation, owner/session, and related execution origins. Never declare, default, or override runtime-owned inputs.
+
+Keep selected model, thinking, mission, concurrency, quorum, and timeout caller-owned unless the capability Skill documents stable policy.
+
+## Resolution behavior
+
+Exact resolution uses the current immutable session Skill context. An invalid unrelated component may make catalog inventory partial, but it must not block an unrelated exact valid identity. A disabled, missing, ambiguous, or changed target fails closed without ambient fallback.
+
+If direct spawn and persistent admission disagree for the same identity, stop and diagnose. Do not switch to an absolute helper path, copy the source contract, or execute the helper directly.

package/dist/skills/actors/references/runs.md

@@ -0,0 +1,39 @@
+# Runs
+
+Use a Run when execution may outlive the current turn, needs declared Control, produces retained artifacts/evidence, fans out, or must remain inspectable.
+
+## Launch
+
+```text
+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.
+
+## Observe
+
+Normally wait for terminal 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
+```
+
+Trace is bounded retained observation, so read its completeness summary. Prove final outcomes with terminal status, result, declared artifacts, and execution evidence rather than assuming retained Trace is exhaustive.
+
+## Control
+
+Send an actor-local action only when the root Recipe declares and implements it:
+
+```text
+message 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.
+
+Control is not actor chat, peer routing, or a task inbox. A Recipe import does not create a peer actor. Several actors/subagents require the `swarm` methodology in addition to these Run mechanics.
+
+## Safety
+
+Operate only on owned Runs and their active generation. Never edit Run state to force an outcome, bypass process identity checks, or signal processes directly from UI/instruction code. Restart creates new generation-local evidence; inspect the exact generation before destructive lifecycle action.

package/dist/skills/artifacts/SKILL.md

@@ -1,16 +1,33 @@
 ---
 name: artifacts
-description: Deterministic artifact writing, reporting, manifests, and bundles for reusable actor workflows.
+description: Use when an actor workflow must write reusable files, reports, manifests, or bundles with deterministic paths and declared outputs.
 ---
 
 # Artifacts
 
-Own reusable capabilities that turn bounded input or prior command output into declared files, reports, manifests, and artifact bundles.
+Use this Skill after the desired durable-output outcome is known. For generic Recipe execution, Runs, persistence, or diagnosis, follow `actors`; this Skill only selects artifact behavior.
 
-## Scope
+## Choose the outcome
 
-- Write or assemble caller-declared artifacts with explicit paths and overwrite policy.
-- Produce bounded human-readable reports and machine-readable manifests.
-- Compose validation evidence into artifact outputs without owning the validation policy.
+| Desired outcome | Recipe | Result |
+| --- | --- | --- |
+| Write one generated artifact and a machine-readable manifest, with optional validation first | `artifacts/bundle` | Primary artifact plus manifest |
+| Generate bounded normalized report content without committing a filesystem write | `artifacts/report` | Report content for review or later composition |
+| Generate and write one artifact | `artifacts/write` | Declared artifact path written with explicit mode |
+| Describe one existing or intended artifact | `artifacts/manifest` | Manifest JSON on stdout; no write |
+| Write prior pipeline output exactly | `artifacts/file-write` | Supporting stdin-to-file write; normally use inside composition |
 
-This Skill does not own repository workflow, multi-agent review methodology, Run lifecycle, retention policy, or transport delivery. Its Recipe identity is `artifacts/<filename stem>`; Recipe files have no top-level `name`. Cross-capability composition uses exact `<skill>/<recipe>` references; helper-backed Recipes use only this Skill's `scripts/` through `{skill_dir}`.
+Prefer `bundle` when both durable content and inventory evidence are required. Prefer `write` for one accepted file. Use `report` while content still needs review. Do not use `file-write` as a content generator. If one selected outcome should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its graph.
+
+## Inputs and boundaries
+
+- Keep `input` bounded and evidence-based; choose the current model explicitly where the Recipe requires `model`.
+- Supply caller-owned `artifact_path` and, for `bundle`, a distinct `manifest_path`.
+- `write_mode=create` is the safe default and stops if the target exists. Use `overwrite` or `append` only when the requested mutation is explicit.
+- Parent directories are created by the writer. `~` is resolved for artifact paths.
+- `manifest` reports existence, size, and modification evidence; it does not validate artifact meaning.
+- Validation in `bundle` runs only when `run_validation=true` and uses the caller-supplied trusted command and scope.
+
+## Stop rules
+
+Stop rather than guessing when the target path, overwrite policy, accepted content, model, or validation command is unclear. Do not claim a durable artifact from `report` or `manifest` alone. After a Run starts, use the `actors` evidence and lifecycle protocol; this Skill does not redefine it.

package/dist/skills/media/SKILL.md

@@ -1,16 +1,44 @@
 ---
 name: media
-description: Local media discovery, playlist construction, and controllable playback capabilities.
+description: Use for local media discovery, filtering, library summaries, playlist construction, or controllable playback.
 ---
 
 # Media
 
-Own reusable local media workflows and services.
+Use this Skill for caller-selected local media. For generic Recipe execution, persistent-tool setup, Run lifecycle, or diagnosis, follow `actors`; this Skill only selects media behavior.
 
-## Scope
+## Choose the operation
 
-- Scan caller-selected media sources and build bounded playlists.
-- Run controllable playback when the local player implements declared actions.
-- Emit canonical Trace and consume canonical Control without inventing media-specific runtime nouns.
+| Intent | Recipe | Use when |
+| --- | --- | --- |
+| Start or control playback | `media/player` | A local file, directory, or playlist should become a controlled service |
+| Build a library summary | `media/library` | A filtered playlist should feed bounded report content |
+| Build a filtered playlist | `media/playlist-build` | Extension filtering and `paths`, `m3u`, or `inline` output are required |
+| Scan a directory for raw file paths | `media/playlist-scan` | A shallow unfiltered inventory is intentionally sufficient |
 
-This Skill does not own the Run kernel, user media, transport delivery, or general artifact policy. Its Recipe identity is `media/<filename stem>`; Recipe files have no top-level `name`. Helper-backed Recipes locate only co-located scripts through `{skill_dir}`, and cross-capability composition uses exact `<skill>/<recipe>` references.
+Use `playlist-build` rather than `playlist-scan` for normal media selection. `library` composes playlist output into report content; its `artifact_path` identifies the intended report target but does not by itself prove a durable write.
+
+## Controlled playback
+
+`media/player` is an async controlled service. Start one owned Run, then use only its declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previous`, `stop`, and `status`.
+
+```text
+spawn recipe=media/player as=run:music values={"source":"~/Music","player":"auto"}
+message target=run:music action=pause
+inspect target=run:music view=control
+```
+
+For recurring playback as a persistent callable tool, use the persistent-capability workflow in `actors` with `from=media/player`; do not copy the player contract.
+
+## Paths and selection
+
+- `source` for playback must name caller-approved local media; do not broaden it to unrelated directories.
+- `source_dir` must be an intended readable directory. `~` is accepted by maintained media helpers.
+- Keep `max_depth` bounded. Use explicit comma-separated extensions for `playlist-build` and `library`.
+- Choose `output_mode=m3u` only when playlist text is wanted; it does not create a playlist file.
+- Choose an explicit `artifact_path` and model for `library` report generation.
+- `player=auto` selects an available supported backend; do not install or substitute a player silently.
+
+## Stop rules
+
+Stop if the source is missing, unreadable, contains no selected media, or no supported player is available. Do not claim playback from process start alone; confirm through Run evidence or `status`. Prefer the declared `stop` action for a responsive player. If the service is unresponsive, return to `actors` for bounded Run recovery rather than shell process control.

package/dist/skills/project-work/SKILL.md

@@ -1,16 +1,37 @@
 ---
 name: project-work
-description: Repository inspection, documentation maintenance, release preparation, and project health workflows.
+description: Use for repository health inspection, project summaries, documentation maintenance, release-readiness evidence, or bounded run-operation reports.
 ---
 
 # Project Work
 
-Own reusable workflows for inspecting and maintaining software projects.
+Use this Skill to produce bounded project evidence and plans. For generic Recipe execution, Run lifecycle, persistence, or multi-actor methodology, follow `actors` and, when applicable, `swarm`; this Skill only selects project workflows.
 
-## Scope
+## Choose the primary workflow
 
-- Summarize Git, package, Skill, changelog, and documentation state.
-- Compose repository health, documentation maintenance, and release-readiness evidence.
-- Keep project-level orchestration separate from lower-level artifact and actor utilities.
+| Intended result | Recipe | Boundary |
+| --- | --- | --- |
+| Repository status, recent history, docs surface, validation, and risks | `project-work/repo-health` | Runs the caller-supplied trusted validation command |
+| Documentation consistency review and maintenance plan | `project-work/docs-maintenance` | Evidence and plan only; does not edit documentation |
+| Multi-lens release verdict with blockers and degraded-confidence evidence | `project-work/release-readiness` | Readiness only; does not publish |
+| Evidence-only release summary and PR-body draft | `project-work/release-summary` | No commit, PR, merge, tag, publish, or external release action |
+| Bounded report over existing actor Run state | `project-work/run-ops` | Read-only report; does not send Control or mutate Runs |
 
-This Skill does not own the Run kernel, publication authority, multi-agent methodology, or artifact-writing mechanics. Its Recipe identity is `project-work/<filename stem>`; Recipe files have no top-level `name`. It composes other capabilities only through exact `<skill>/<recipe>` references and keeps project-specific helper behavior under its own `scripts/` directory.
+Choose `release-readiness` when independent review and a release verdict are needed. Choose `release-summary` when the evidence is already sufficient and only a concise operator-gated summary is wanted. If one primary workflow should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its composition.
+
+## Inputs and evidence
+
+- Scope every workflow to the caller-selected repository, docs directory, or Run state.
+- Treat `validation_command` as trusted executable input. Do not invent or broaden it.
+- Select current model policy explicitly for workflows that request a model; release-readiness reviewer roles inherit only the values supplied by the caller.
+- Artifact paths identify intended report targets. Confirm actual declared artifact evidence before claiming a durable file.
+- Preserve degraded or insufficient review status. Never turn partial reviewer output into consensus.
+- Release outputs are evidence, not publication authority.
+
+## Supporting Recipes
+
+`git-status`, `git-log`, `changelog-head`, `changelog-section`, `markdown-index`, `package-summary`, and `skill-summary` support the primary workflows. Use one directly only when its narrow deterministic output is the requested result; otherwise start from a primary workflow and avoid rebuilding its composition manually.
+
+## Stop rules
+
+Stop when repository scope, version, validation command, model policy, or write target is ambiguous. Do not edit docs from a `docs-maintenance` plan, publish from release evidence, or send Run Controls from `run-ops`. Hand those operations to their owning protocol after explicit authorization.

package/dist/skills/recipe-memory/SKILL.md

@@ -1,16 +1,36 @@
 ---
 name: recipe-memory
-description: Package-owned structural review components for safe persistent Recipe capability memory.
+description: Use only for internal automatic Recipe-memory review, diagnosis, or recovery; do not use for normal Recipe creation, registration, or invocation.
 ---
 
 # Recipe Memory
 
-Own the executable reviewer components used by automatic draft and active-tool Recipe evolution.
+Use this Skill only when automatic draft-memory or active-tool review needs diagnosis or bounded recovery. Normal agents must not spawn, register, specialize, or invoke `recipe-memory/draft-review` or `recipe-memory/tool-review`; they are package-owned internal reviewer components.
 
-## Scope
+## Diagnose first
 
-- Review value-free structural projections rather than executable content or machine-local paths.
-- Return bounded decisions for deterministic package-owned executors.
-- Remain package-owned so user Recipes cannot shadow or redirect automatic review.
+```text
+inspect target=recipes view=reviews
+inspect target=runtime view=triage
+```
 
-This Skill does not own registry mutation, CAS, journaling, quarantine, lineage, retry, reset, or safe-boundary activation. Those remain Run-kernel and registry responsibilities. Its direct Recipe identities are `recipe-memory/<filename stem>`; Recipe files have no top-level `name`. They are internal components, never automatic user tools.
+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.
+
+## Recovery Controls
+
+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"}
+```
+
+- `review.retry` resumes the selected failed review scope while preserving authenticated transaction recovery.
+- `review.reset` clears disposable failure state only. It must reject evidence that requires roll-forward recovery.
+- Re-inspect `view=reviews` after one recovery Control; do not loop retries or resets without changed evidence.
+
+## Stop rules
+
+Stop when the phase is healthy or idle, the requested scope does not match the failure, recovery evidence requires deterministic roll-forward, or the reported next action is not retry/reset. Never edit review state, lineage, journals, quarantine, drafts, or persisted Recipes directly. Never bypass automatic review by running its internal Recipes as ordinary capabilities.