@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/skills/actors/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: actors
+description: Use for any non-trivial pi-actors operation, diagnosis, or development involving Recipes, persistent tools, Runs, spawn, message, inspect, Trace, Control, capability specialization, or activation.
+---
+
+# Actors
+
+## Choose the operation
+
+Start from the intended outcome:
+
+```text
+Run a maintained capability once
+→ use spawn recipe=<skill>/<recipe>
+
+Make a maintained capability a persistent agent-callable tool
+→ use register_tool from=<skill>/<recipe>
+
+Keep the same capability but narrow caller defaults
+→ use register_tool from=<skill>/<recipe> defaults={...}
+
+Register a trusted command directly
+→ use register_tool template="..."
+
+Build a reusable multi-node execution graph
+→ author a Recipe with named imports
+
+Run a long-lived controlled process
+→ spawn its async Recipe, then use message and inspect
+
+Coordinate several independent actors or subagents
+→ also read the swarm Skill
+
+Choose capability-specific behavior
+→ read the owning capability Skill
+
+Diagnose resolution, registration, or activation
+→ use Inspect status/doctor flows and stop on contradictory evidence
+```
+
+Use [persistent tools](./references/persistent-tools.md), [Recipes](./references/recipes.md), [Runs](./references/runs.md), or [diagnostics](./references/diagnostics.md) only when the selected operation needs that detail.
+
+## Core distinctions
+
+Keep these boundaries explicit:
+
+```text
+Skill Recipe ≠ registered tool
+spawn ≠ registered-tool invocation
+persisted ≠ callable
+direct delegation ≠ named import composition
+Run Control ≠ actor chat
+```
+
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool from=<skill>/<recipe>` persists compact logical delegation and activates from the resolved effective contract without copying, symlinking, or ambient re-resolution. A tool is callable in the current session only when activation evidence says `callable_now: true`.
+
+`actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
+
+## Persistent capability workflow
+
+To make `music-player/playback` callable as `music_player` with a default source:
+
+```text
+register_tool
+  name=music_player
+  from=music-player/playback
+  defaults={"source":"~/Music/1MIX"}
+```
+
+Then:
+
+1. Require registration to report successful resolution, validation, persistence, registry admission, host registration, activation, and `callable_now: true`.
+2. Call the actual `music_player` tool. Do not call `spawn` and describe that as tool invocation.
+3. Verify agent-facing evidence reports `launch_kind: "tool"`; use `inspect target=tool:music_player view=status` when usage or activation needs confirmation.
+4. If callability is false, stop at the reported activation boundary. Preserve the logical source and diagnose it; do not substitute a Recipe spawn as proof.
+
+Use direct delegation for the same maintained capability under a persistent name or narrower defaults. Use named imports only when one Recipe graph contains reusable child nodes. See [persistent tools](./references/persistent-tools.md) and [Recipes](./references/recipes.md).
+
+## Local coordinator topology
+
+There are two distinct multi-instance shapes:
+
+- A gateway-centric system owns ingress, agent-instance creation, routing, and lifecycle outside the agents.
+- A host-coordinator system keeps the current Pi instance as the control plane; companion extensions such as Telegram provide presence, while pi-actors creates explicit local Runs for delegated work.
+
+In host-coordinator mode, the top-level agent receives declarative outcomes, preserves user authority and global context, delegates bounded concrete execution, and owns integration plus final validation. It is not merely another worker after delegation begins. One bounded implementation worker normally runs with reasoning off; consequential output receives a separate reasoning-enabled review. Several independent participants or reviewers additionally use `swarm`.
+
+Delegation is not mandatory for every prompt. Work inline when one short bounded act has one natural validation boundary and spawning would add more coordination than isolation, latency hiding, clean context, or continued coordinator availability can repay. For admitted delegation, prefer terminal follow-up and durable Trace/artifacts; inspect on meaningful attention, operator request, or an evidence-based overdue timer rather than busy polling.
+
+## Run workflow
+
+A Run is one concrete execution of a Recipe:
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+1. Spawn with the exact logical Recipe identity and caller-owned values.
+2. Retain the returned `run:<id>` and normally wait for terminal follow-up instead of polling.
+3. Inspect `view=trace` when retained observations or attention matter.
+4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
+5. Send `message` only for an action declared and consumed by that controlled Recipe.
+6. Use terminal state, result, declared artifacts, and execution evidence to prove completion.
+
+A Run exposes only `recipe`, `trace`, and `control` views. Control is bounded actor-local input, not peer messaging or chat. See [Runs](./references/runs.md).
+
+## Diagnosis and stop rules
+
+When a pi-actors operation fails:
+
+1. Keep the intended logical Recipe or tool identity.
+2. Inspect the existing `recipes`, `tool:<name>`, `runtime`, or `run:<id>` surface that owns the failure.
+3. Report resolver, registry, activation, Run, Trace, or Control truth exactly.
+4. Retry only after the owning state is healthy.
+
+Stop if spawn and registry resolve the same Recipe differently. Stop if registration persists but is not callable. Stop if an operation cannot be proven through pi-actors surfaces.
+
+Never recover by copying maintained Recipe args, defaults, Control, artifacts, or helper commands. Never hard-code a `{skill_dir}` replacement path. Never introduce `bash -lc`, `eval`, direct bundled-helper execution, or shell backgrounding to bypass resolution. Never call `spawn` and claim a tool call. Use [diagnostics](./references/diagnostics.md) for the safe next action.
+
+## When to read another Skill
+
+- Read the owning capability Skill when choosing or operating that capability pack.
+- Read `swarm` in addition to `actors` for multiple actors/subagents, parallel scopes, reviewer lenses, quorum, conflict handling, or integration.
+- For generic mechanics, this Skill outranks capability Skills and `swarm`. Report a stale Skill if it contradicts Recipe identity, registration, activation, spawn, Inspect, Trace, or Control semantics here.
+- When changing the extension implementation itself, apply project implementation instructions after this operating protocol.

package/node_modules/@llblab/pi-actors/skills/actors/recipes/command-validate.json

@@ -0,0 +1,13 @@
+{
+  "args": [
+    "command:string",
+    "scope:string",
+    "timeout_ms:int"
+  ],
+  "defaults": {
+    "scope": ".",
+    "timeout_ms": "300000"
+  },
+  "timeout": "{timeout_ms}",
+  "template": "bash -lc 'cd {scope} && {command}'"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/jsonl-tail.json

@@ -0,0 +1,10 @@
+{
+  "args": [
+    "file:path",
+    "lines:int"
+  ],
+  "defaults": {
+    "lines": "40"
+  },
+  "template": "tail -n {lines} {file}"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/recipe-validate.json

@@ -0,0 +1,11 @@
+{
+  "args": [
+    "target:path",
+    "all:bool"
+  ],
+  "defaults": {
+    "target": "recipes",
+    "all": "true"
+  },
+  "template": "{skill_dir}/scripts/validate-recipe.mjs {target} {all?--all:}"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/resource-locker-snapshot.json

@@ -0,0 +1,11 @@
+{
+  "args": [
+    "state_dir:path",
+    "lines:int"
+  ],
+  "defaults": {
+    "state_dir": "~/.pi/agent/tmp/pi-actors/runs/coordinator-locker",
+    "lines": "20"
+  },
+  "template": "{skill_dir}/scripts/resource-locker.mjs snapshot --state-dir {state_dir} --lines {lines}"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/resource-locker.json

@@ -0,0 +1,25 @@
+{
+  "async": true,
+  "args": [
+    "lease_ms:int"
+  ],
+  "defaults": {
+    "lease_ms": "600000"
+  },
+  "control": [
+    "enqueue",
+    "claim",
+    "complete",
+    "fail",
+    "acquire",
+    "renew",
+    "release",
+    "stop"
+  ],
+  "artifacts": {
+    "queue": "{state_dir}/queue.json",
+    "locks": "{state_dir}/locks.json",
+    "journal": "{state_dir}/journal.jsonl"
+  },
+  "template": "{skill_dir}/scripts/resource-locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/run-ops-snapshot.json

@@ -0,0 +1,15 @@
+{
+  "args": [
+    "state_root:path",
+    "run_id:string",
+    "lines:int",
+    "stale_minutes:int"
+  ],
+  "defaults": {
+    "state_root": "~/.pi/agent/tmp/pi-actors/runs",
+    "run_id": "music",
+    "lines": "80",
+    "stale_minutes": "60"
+  },
+  "template": "{skill_dir}/scripts/run-utils.mjs run-ops-snapshot {state_root} {run_id} {lines} {stale_minutes}"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/run-state-files.json

@@ -0,0 +1,13 @@
+{
+  "args": [
+    "state_root:path",
+    "file_name:string",
+    "max_depth:int"
+  ],
+  "defaults": {
+    "state_root": "~/.pi/agent/tmp/pi-actors/runs",
+    "file_name": "run.json",
+    "max_depth": "2"
+  },
+  "template": "find {state_root} -maxdepth {max_depth} -name {file_name} -type f -print"
+}

package/node_modules/@llblab/pi-actors/skills/actors/recipes/run-summary.json

@@ -0,0 +1,9 @@
+{
+  "args": [
+    "state_root:path"
+  ],
+  "defaults": {
+    "state_root": "~/.pi/agent/tmp/pi-actors/runs"
+  },
+  "template": "{skill_dir}/scripts/run-utils.mjs run-summary {state_root}"
+}

package/node_modules/@llblab/pi-actors/skills/actors/references/diagnostics.md

@@ -0,0 +1,44 @@
+# Diagnostics
+
+Preserve the intended logical identity and diagnose through public pi-actors surfaces. Do not inspect raw registry files or implementation source as the normal first response.
+
+## Recipe resolution or catalog failure
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=doctor identity=<skill>/<recipe>
+```
+
+Use the focused doctor form for one intended identity. It reports active-Skill ownership, exact resolvability, partial-catalog state, component status, portable source location, resolution generation, any rejection, and bounded next actions. Use the unfiltered doctor only for catalog-wide diagnosis. A partial catalog does not imply every exact component is unavailable. If the owning Skill is inactive, report that blocker rather than locating and running its helper manually.
+
+## Persistent tool failure
+
+```text
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+```
+
+Distinguish persistence, registry admission, host registration, active-tool membership, and `callable_now`. Confirm the source identity, effective caller schema, separate tool/spawn usage, and last launch kind when exposed.
+
+If persistence succeeded but callability is false, do not use `spawn` and claim the tool worked. Follow the reported activation boundary or stop.
+
+## Run failure
+
+```text
+inspect target=run:<id> view=recipe
+inspect target=run:<id> view=trace
+inspect target=run:<id> view=control
+inspect target=runtime view=status
+```
+
+Use Recipe view for captured identity/launch evidence, Trace for bounded observations, Control for readiness/capacity/stale work, and runtime status for kernel-level health. Treat retained-history completeness honestly.
+
+## Safe failure protocol
+
+1. Keep the exact intended Recipe/tool/Run identity.
+2. Identify the owning public surface.
+3. Record exact resolver, registry, activation, or Run truth.
+4. Apply only the bounded next action returned by that owner.
+5. Retry only after the owning state is healthy.
+
+Stop if evidence remains contradictory or the requested operation cannot be proven. Never recover by copying maintained contracts, hard-coding installation paths, directly executing bundled helpers, adding `bash -lc` or `eval`, shell-backgrounding work, editing unrelated Skills, or relabeling a Recipe spawn as a tool call.

package/node_modules/@llblab/pi-actors/skills/actors/references/persistent-tools.md

@@ -0,0 +1,76 @@
+# 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=music-player/playback
+  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.
+
+Resolution uses Pi's authoritative active-session Skill snapshot across every Skill location Pi admits. Registration resolves and validates the maintained source, persists only its logical `<skill>/<recipe>` reference plus caller specialization, and projects the already-resolved effective contract into the runtime tool. Never replace this composition with a copied Recipe, absolute helper path, symlink, or ambient runtime re-resolution.
+
+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/node_modules/@llblab/pi-actors/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
+music-player/playback
+→ music_player with a default source
+```
+
+For agent-facing persistent specialization, use:
+
+```text
+register_tool from=music-player/playback 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/node_modules/@llblab/pi-actors/skills/actors/references/runs.md

@@ -0,0 +1,41 @@
+# 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.
+
+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. 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 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.