@llblab/pi-kit 0.1.0

package/AGENTS.md

@@ -0,0 +1,35 @@
+# Project Context
+
+## Product Contract
+
+- `@llblab/pi-kit` is a Pi package distribution, not a Pi extension.
+- It bundles independently released LLBLAB extensions behind one installable package.
+- Every included package version is exact. Ranges, floating tags, local paths, and unpublished refs are forbidden in release state.
+- The kit owns composition and version selection only. Runtime behavior, Skills, documentation, and implementation remain owned by the included packages.
+- Loading order is explicit in `package.json`; do not rely on recursive package discovery.
+
+## Context Ownership
+
+- `README.md` owns public purpose, contents, installation, and update instructions.
+- `package.json` owns the canonical package set, exact versions, bundled resources, and load order.
+- `BACKLOG.md` owns open work only.
+- `CHANGELOG.md` owns completed delivery history, with at most eight outcome bullets of at most 512 characters per release.
+- Tests own executable package-coherence evidence.
+
+## Engineering Rules
+
+- Start work from `BACKLOG.md` and inspect the included package manifests before changing pins or resource paths.
+- Keep `dependencies`, `bundledDependencies`, Pi resource paths, README inventory, tests, and lockfile synchronized.
+- Bundle every included Pi package so npm installation is self-contained under this package's module root.
+- Expose only resources declared by each included package. Prefer published distribution entrypoints over source entrypoints when both exist.
+- Do not copy extension source, Skills, or documentation into this repository.
+- Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.
+- Use English for public and repository-facing text.
+- Do not commit, publish, tag, create a remote repository, or mutate Pi settings without explicit authorization.
+
+## Validation
+
+- Run `npm test` after manifest or inventory changes.
+- Run `npm run pack:check` before declaring package readiness.
+- Inspect the dry-run tarball inventory to confirm all four bundled packages and their declared resources are present.
+- Run `npm run validate` at completion.

package/BACKLOG.md

@@ -0,0 +1,3 @@
+# Backlog
+
+- [ ] `Release`: Configure npm Trusted Publishing and publish the first validated package release after explicit authorization.

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to `@llblab/pi-kit` are documented here.
+
+## 0.1.0 - 2026-08-18
+
+- `Package`: Established a version-pinned Pi distribution bundling Actors, Codex usage, Grow Loop, and Telegram extensions with their declared Skills behind one installable package.
+- `Validation`: Added executable coherence checks for exact versions, bundled dependencies, resource paths, installed manifests, and public inventory synchronization; verified the packed distribution through Pi in an isolated agent home.
+- `Pinned Releases`: Advances Actors to `0.49.1` for maintained Music Player Generative App routing and Telegram to `0.36.1` for adaptive JSON/CML controls, hybrid surface guidance, consistent denials, destructive Skip state, and Trusted Publisher release automation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llblab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @llblab/pi-kit
+
+`@llblab/pi-kit` is the version-pinned LLBLAB extension distribution for [Pi](https://github.com/badlogic/pi-mono). It provides one installable package while each included extension keeps its own repository, release line, and development lifecycle.
+
+## Included packages
+
+| Package | Version | Resources |
+| --- | ---: | --- |
+| `@llblab/pi-actors` | `0.49.1` | Extension and Skills |
+| `@llblab/pi-codex-usage` | `0.9.2` | Extension |
+| `@llblab/pi-grow-loop` | `0.7.1` | Extension and Skills |
+| `@llblab/pi-telegram` | `0.36.1` | Extension and Skills |
+
+Versions are exact by design. Updating an extension does not change an installed kit until this repository explicitly advances that dependency and publishes a new kit version.
+
+## Install
+
+From npm after publication:
+
+```bash
+pi install npm:@llblab/pi-kit@0.1.0
+```
+
+For local development:
+
+```bash
+pi install ./pi-kit
+```
+
+Pi loads the bundled extension entrypoints and Skills declared by this package. The kit itself does not register an extension or introduce runtime behavior.
+
+## Development
+
+```bash
+npm install
+npm run validate
+```
+
+To advance one included package, update its exact version in `dependencies`, run `npm install`, update the package table and changelog, then validate the packed artifact. Do not use version ranges.
+
+## Security
+
+Pi extensions execute with the user's system permissions. Review every included package and its release before advancing the pinned version.

package/node_modules/@llblab/pi-actors/AGENTS.md

@@ -0,0 +1,150 @@
+# Project Context
+
+## Meta-Protocol Principles
+
+- `README.md` and `docs/`: human-facing product entrypoint, concepts, and reference.
+- `skills/`: agent-facing operating protocols and Skill-local operational references.
+- injected system prompt: routing-only meta-protocol that selects the owning Skill.
+- `AGENTS.md`, source, and tests: implementation protocol and executable evidence.
+- `BACKLOG.md`: canonical future-only work.
+- `CHANGELOG.md`: completed delivery history.
+
+Do not make normal-use Skills depend on README/docs, do not copy Skill operating manuals into the system prompt, and do not present implementation evidence as the agent operating path. Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
+
+## Concept
+
+`pi-actors` is a local Run kernel and persistent capability registry for Pi:
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+An actor is any runnable local capability, including a script, tool, service, pipeline, or subagent. Recipes define actors' reusable execution. Runs are concrete actor instances and own one generation of execution and evidence. Trace owns observations. Control owns actor-local inputs for services that actually consume them. `register_tool` persists capabilities separately.
+
+Public Run verbs remain `spawn`, `message`, and `inspect`.
+
+## Core Structure
+
+```text
+Pi host
+  -> index.ts                         composition root
+     -> lib/tools*.ts                 public tool adapters
+     -> lib/runtime.ts / registry.ts  active user Recipe tools
+     -> lib/recipes-*.ts              Recipe resolution/evolution
+     -> lib/async-runs.ts             Run lifecycle facade
+     -> lib/runs-*.ts                 focused lifecycle/evidence domains
+     -> lib/observability.ts          terminal + Trace-attention observation
+     -> lib/inspector*.ts             owner-filtered actor-instance inspection
+     -> scripts/*.mjs                 process/service entrypoints
+     -> skills/*/recipes/*            Skill-owned Recipe components
+     -> skills/*                      agent operating protocols
+     -> README.md / docs/*            human product guidance
+```
+
+`index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic. For architecture-affecting work, load and follow `.agents/skills/domain-dag/SKILL.md`; its validator is local agent tooling, not an npm, CI, or release gate.
+
+## Key Domains
+
+- `extension-runtime.ts`: low-level Pi session lifecycle, tool adaptation, and runtime service composition behind the thin `index.ts` event-registration root.
+- `command-templates.ts`: portable synchronous execution graph.
+- `recipes-references.ts`, `recipes-discovery.ts`, `recipe-control.ts`: Recipe resolution, imports, shadowing, and Control declarations.
+- `async-runs.ts`: lifecycle facade.
+- `runs-start.ts`, `runs-status.ts`, `runs-control.ts`, `runs-control-delivery.ts`, `runs-controls.ts`, `runs-trace.ts`, `runs-process.ts`, `runs-retention.ts`, `runs-parent-teardown.ts`: focused Run internals.
+- `execution-sessions.ts`, `trace-projection.ts`, `control-projection.ts`, `session-evidence.ts`: bounded/redacted execution and inspection evidence.
+- `tools-message.ts`: exact Control facade.
+- `tools-inspect.ts`: exact `run:<id>`, `runtime`, `recipes`, and `tool:<name>` inspection.
+- `runtime-identity.ts`, `runtime-triage.ts`: immutable package/schema identity and pure pending/stale Control classification.
+- `tools-spawn.ts`, `tools-register.ts`, `tools-local.ts`, `tools-response.ts`: Run creation, persistent capabilities, Recipe-backed tools, and compact results.
+- `inspector.ts`, `inspector-overlay.ts`, `inspector-command.ts`, `inspector-actions.ts`: actor-instance Recipe/Trace/Control projection, navigation, command wiring, and fenced actions. **Actor Inspector** remains the product and command name, not a separate domain.
+- `observability.ts`, `run-ui-runtime.ts`: Trace attention, terminal reconciliation, and Pi follow-up delivery.
+- automatic draft/tool review domains: structurally redacted model review, journaled mutation, lineage, recovery, and explicit retry/reset safety.
+
+The bundled Skill Recipe dependency DAG is `artifacts → actors, swarm` and `project-work → actors, artifacts, swarm`; `actors`, `music-player`, `swarm`, and `recipe-memory` have no cross-Skill Recipe dependencies.
+
+Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed Skill Recipes self-locate through runtime-owned `{skill_dir}`. Recipes stay optional, composable, policy-light, and caller-configurable.
+
+## Operating Principles
+
+### Recipe
+
+- Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching the Skill directory, not a second pi-actors identity field.
+- Recipe files may define args/defaults, imports, artifacts, command-template flags, and `control`.
+- Declare actor-local actions only when a long-lived process implements them.
+- Actions are lowercase, unique, and cannot use runtime-reserved lifecycle names.
+- Removed communication-plane metadata fails explicitly; never translate it.
+- User Recipes are discovered only from the persistent user registry; Skill Recipes are exact components outside tool discovery. Explicit entry paths resolve from invocation `cwd`; relative imports resolve from their importing file.
+- Files over 1 MiB, import depth over 32, and import cycles fail closed.
+
+### Trace
+
+Canonical event:
+
+```json
+{"id":"…","ts":"…","kind":"…","summary":"…","data":{},"level":"info","attention":"notify"}
+```
+
+Trace is a bounded retained suffix, not an audit archive. Every first-party writer must call `appendRunTraceEvent`; under the canonical token-owned lock it appends within both fixed bounds or atomically retains the newest suffix plus one cumulative warning-only `runtime.trace_compacted` marker. The marker means older history was discarded; terminal/result/execution/artifact files remain authoritative independently. Reads are newline-safe and order equal timestamps by same-source ordinal, fixed source rank, then stable id without exposing ordering metadata. Never write `trace.jsonl` directly. Persist durable state or an artifact before attention; `attention: "followup"` remains rare.
+
+### Control
+
+Public shape:
+
+```json
+{"target":"run:<id>","action":"…","input":{},"verbose":false}
+```
+
+Admit only lowercase ASCII actions of at most 64 characters, serialized JSON input of at most 380 bytes, and complete newline-terminated wire records of at most 512 bytes on both FIFO and named pipe. Invalid envelopes remain outside the journal; persist every admitted Control before transport. Put larger data in a declared artifact/path and send only a bounded reference or instruction through Control. Fence every record and endpoint with immutable `run_instance_id`; controlled services capture that generation at startup. Serialize admission and every compacted atomic journal replacement through token-owned dead-process-reclaiming locks. Reject malformed, oversized, stale-generation, or 64-pending journals before admission with bounded backpressure/integrity details; bound persisted errors to 4 KiB inside the string and retain at most 128 terminal records. First-party services must exact-id claim and finalize through `runs-controls.ts`; admitted nonterminal Controls never expire automatically. Keep transitions expected-state-fenced and monotonic when consumers complete before producer delivery evidence. FIFO and named pipe are transport details, not public concepts; reject partial writes and keep FIFO readers gap-free across writers. Revalidate owner, generation, state, and process identity under the lifecycle lock immediately before delivery.
+
+Keep `controls.jsonl` raw and local for execution fidelity. Every model-facing and Actor Inspector Control surface must use the shared bounded `control-projection.ts` redaction before exposure; never attach a second raw copy in tool details.
+
+Runtime lifecycle and review actions remain runtime-owned. Runtime kill is the recovery path for a stuck saturated Run; it never consumes actor-local Control capacity or appends a synthetic Control record. Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state.
+
+### Inspect
+
+Run views are exactly `recipe`, `trace`, and `control`. Trace reports retained-history completeness; Control reports capacity, saturation, stale pending work, journal bytes, and bounded diagnostics. Runtime triage aggregates backpressured Runs and incomplete Trace. Non-Run management targets remain `runtime`, `recipes`, and `tool:<name>`. Apply owner filtering and redaction before projecting evidence.
+
+## Retained Safety Invariants
+
+Never weaken:
+
+- owner filtering;
+- immutable generation fencing;
+- cross-platform process identity checks;
+- canonical lifecycle locks and same-directory restart serialization;
+- shutdown and parent-teardown kill;
+- terminal notification reconciliation and handled/failure evidence;
+- bounded logs, complete captures, and tool output;
+- owned Pi session provenance;
+- path containment, canonical ownership markers, and symlink rejection;
+- redaction of secrets and machine-local paths;
+- automatic review admission, CAS, journaling, quarantine, lineage, retry, and reset safety.
+
+Lifecycle operations fail closed when identity, ownership, or generation cannot be proven. Do not directly signal processes from UI code or edit active Run state to force outcomes.
+
+## Registry and Evolution
+
+`~/.pi/agent/recipes/*.json` is executable capability memory. Preserve filename identity, atomic writes, canonical per-path locks with atomic owner publication and non-blocking abandoned staging, explicit operator-gated changes, and transportability.
+
+Automatic review receives value-free structural projections, not executable content, paths, prose, canonical names, or secrets. Deterministic executors derive unchanged Recipes from trusted captures. Approved mutation must journal intent before mutation and roll forward safely after crashes.
+
+`PI_ACTORS_AUTOMATIC_REVIEW=off` disables scheduling and safe-boundary activation while remaining visible in runtime status.
+
+## Output and Observability
+
+Tool result/error text contributes exactly one leading line break. Keep model-facing responses compact and state-backed. Preserve complete byte-exact command streams in bounded spill files while returning bounded tails; never feed truncated tails into pipeline stdin.
+
+File watchers accelerate reconciliation; a bounded interval recovers missed terminal and retained-attention events. Canonical attention observation uses stable retained ids, primes them at startup without replay, and bounds seen memory to the current suffix across compaction; only allowlisted legacy outbox fallback uses line offsets. Attention is a wake hint, so persist durable recovery state before emitting it. Terminal follow-ups contain only Run id, status, one base path, and relative artifact names in visible content; semantic details remain structured. Delivery remains honestly at-least-once across the send/handled-marker crash window.
+
+When a deferred Run result gates the next step, wait for its terminal follow-up. Inspect early only for operator request, meaningful attention, or diagnosis of an overdue Run.
+
+## Documentation and Release Discipline
+
+- Keep published text portable: use `~`, `<repo>`, or relative paths.
+- Update `skills/actors/SKILL.md` when durable operating mechanics change.
+- Keep `skills/swarm/SKILL.md` focused on multi-agent methodology rather than kernel internals.
+- Recipe `description` is optional. Skill Recipe QA recursively validates direct filesystem-owned components and capability semantics with zero diagnostics or warnings; it does not enforce aesthetics or architecture policy.
+- Before release run the normal product validation and dependency audit. Use the project-local Domain DAG Skill during architecture-affecting development, not as publication automation.
+- `.github/workflows/release.yml` owns the immutable sequence reusable validation → npm Trusted Publisher publication/verification → GitHub Release convergence; follow [docs/releasing.md](docs/releasing.md).
+- Keep npm publication tokenless: use the exact npm Trusted Publisher binding and job-scoped OIDC permission, never a long-lived npm token or token fallback.
+- Until a stable version beyond `1.x`, prefer clean breaking simplification over compatibility aliases or renamed legacy abstractions.

package/node_modules/@llblab/pi-actors/BACKLOG.md

@@ -0,0 +1,6 @@
+# Project Backlog
+
+- [ ] `Linux MPRIS media integration`: Expose the active `music-player/playback` singleton as one optional generation-fenced MPRIS2 player so GNOME and compatible desktop shells can show current media and native controls without making D-Bus a second playback authority.
+  - [ ] Publish `PlaybackStatus`, track metadata, duration, read-time position, volume, and supported capabilities under one stable session-scoped bus identity; disappear cleanly when the Run stops or its generation is replaced, and fail soft when the user D-Bus session is unavailable.
+  - [ ] Map `Play`, `Pause`, `PlayPause`, `Next`, `Previous`, `Stop`, `Seek`, `SetPosition`, and `Volume` back into the existing generation-fenced music-player Control/helper contract rather than signaling the backend or editing Run state directly.
+  - [ ] Validate deterministic D-Bus contract behavior plus a live GNOME smoke showing the media surface, metadata, progress, volume, and controls while preserving backend independence and exact Actor ownership.