@llblab/pi-kit 0.1.0

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

@@ -0,0 +1,231 @@
+# pi-actors
+
+![pi-actors banner](https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg)
+
+Local Run kernel and persistent tool registry for [Pi](https://github.com/earendil-works/pi).
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+An **actor** is any runnable local capability: a script, tool, service, pipeline, or subagent. A **Recipe** is its reusable executable definition. `spawn` creates a **Run**—one concrete actor instance—which captures its Recipe, appends observable **Trace**, and may consume actor-local **Control**.
+
+## Local Coordinator Model
+
+Multi-instance systems commonly put instance creation and routing in an external gateway. pi-actors supports a different topology: the current Pi instance remains the coordinator, companion extensions such as Telegram provide presence, and explicit Runs perform bounded delegated work. The coordinator receives high-level outcomes, decomposes them, stays available for decisions, and owns integration plus final validation instead of becoming another undifferentiated worker.
+
+This topology does not require every task to become a subagent. Short work with one natural validation boundary stays inline; delegation pays when clean context, asynchronous execution, independent judgement, parallel ownership, or coordinator availability exceeds its coordination cost. Bounded implementation can run with reasoning off while the coordinator selectively launches clean-context reasoning-enabled reviewers; several independent reviews can provide broader evidence than one author self-review. Terminal follow-ups, durable Trace, and declared artifacts replace tight polling loops.
+
+## Install
+
+```bash
+pi install npm:@llblab/pi-actors
+```
+
+For local development:
+
+```bash
+pi install /path/to/pi-actors
+```
+
+The package contributes the extension and six capability-owning Skills for actors, artifacts, music playback, project work, Recipe memory, and swarm orchestration.
+
+## Public Tools
+
+### `spawn`
+
+Create a Run from an active-Skill Recipe, an explicit Recipe file, or an inline command template:
+
+```text
+spawn template="sleep 30" as=run:demo
+spawn recipe=project-work/repo-health values={"repo":"/work/project","model":"provider/model"}
+spawn recipe=music-player/playback values={"source":"/music"}
+spawn template="make test" as=run:test
+```
+
+Use a Run when work may outlive the current turn, needs steering, fans out, produces artifacts, or must remain inspectable. Short foreground commands can remain ordinary tools.
+
+### `message`
+
+Send one exact Control:
+
+```json
+{
+  "target": "run:player",
+  "action": "pause",
+  "input": { "reason": "operator" },
+  "verbose": false
+}
+```
+
+Run targets accept only actions declared by the captured Recipe. Runtime targets accept only reserved review actions:
+
+```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"}
+```
+
+Lifecycle `kill` remains runtime-owned rather than Recipe-declared.
+
+### `inspect`
+
+Inspect one exact management target:
+
+```text
+inspect target=run:test view=recipe
+inspect target=run:test view=trace source=lifecycle lines=40
+inspect target=run:test view=control
+inspect target=runtime view=status
+inspect target=recipes view=status
+inspect target=recipes view=doctor identity=music-player/playback
+inspect target=tool:my_tool view=status
+```
+
+A Run exposes exactly `recipe`, `trace`, and `control` views.
+
+### `register_tool`
+
+Persist a maintained Recipe with `register_tool name=<tool> from=<skill>/<recipe> defaults={...}`, or register a trusted command through the separate `template` mode. Definitions live under `~/.pi/agent/recipes`. Treat a tool as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
+
+## Recipe
+
+Recipes can declare:
+
+- named typed args, inline fallbacks, configuration `defaults`, and composition `values`;
+- imports and command-template composition;
+- retry, failure, recovery, repeat, concurrency, and timeout policy;
+- artifact paths;
+- `control: ["action"]` only for inputs a service actually consumes.
+
+Example controlled Recipe:
+
+```json
+{
+  "async": true,
+  "control": ["pause", "resume", "stop"],
+  "artifacts": { "state": "{state_dir}/player-state.json" },
+  "template": "{skill_dir}/scripts/player.mjs --state-dir {state_dir}"
+}
+```
+
+Ordinary one-shot Recipes should omit `control`. Recipe imports compose definitions inside one Run; they do not create peer actors.
+
+```json
+{
+  "imports": {
+    "report": "artifacts/report",
+    "review": "swarm/quorum-review"
+  },
+  "template": [{ "name": "report" }, { "name": "review" }]
+}
+```
+
+Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; the filename is identity. `SKILL.md` `name` remains Pi host metadata and matches the Skill directory—pi-actors adds no second Skill identity field.
+
+References have two classes: exact active-Skill identities such as `project-work/repo-health`, and explicit `.json` / `.md` paths. Entry file paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe's directory; absolute paths remain exact. File-backed Recipes receive immutable `{recipe_dir}` and Skill Recipes also receive `{skill_dir}`. Skill components never become tools automatically.
+
+String command-template leaves execute directly without shell interpretation. Use template arrays for sequencing or an explicit trusted shell/script when shell semantics matter.
+
+## Trace
+
+`trace.jsonl` contains bounded structured observations:
+
+```json
+{
+  "id": "cfd0…",
+  "ts": "2026-01-01T00:00:00.000Z",
+  "kind": "progress.update",
+  "summary": "Indexed 40 files",
+  "data": { "files": 40 },
+  "level": "info",
+  "attention": "notify"
+}
+```
+
+Trace fields are exact: `id`, `ts`, `kind`, and optional `summary`, `data`, `level`, `attention`. Address, sender, recipient, reply, and routing fields fail validation. Trace is a bounded retained suffix, not an audit archive: the canonical authority appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; `result.json`, `execution.json`, terminal state, and declared artifacts retain their own authority. `inspect view=trace` reports whether retained history is complete. Reads are newline-safe and deterministic; first-party scripts never write this file directly.
+
+Attention is a live wake hint, not a durable queue: persist recovery state or an artifact first. Use `attention: "notify"` for visible status and `attention: "followup"` only when the coordinator needs semantic follow-up context; compaction may discard older hints. Store large evidence in artifacts or bounded execution captures.
+
+## Control
+
+Controls persist to `controls.jsonl` before transport. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one record. Canonical transitions retain a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. Every record carries immutable `run_instance_id`. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and bounded diagnostics. If a stuck Run is saturated, use runtime-owned `kill`; it bypasses actor-local capacity and creates no synthetic Control.
+
+Long-lived services publish `control-endpoint.json` only when ready:
+
+```json
+{
+  "path": "/path/to/control.fifo",
+  "type": "fifo",
+  "ready_at": "2026-01-01T00:00:00.000Z",
+  "run_instance_id": "generation-id"
+}
+```
+
+Supported transports are Unix FIFO and Windows named pipe. Every actor-local Control uses the same portable envelope: action is at most 64 lowercase ASCII characters, serialized JSON input is at most 380 bytes, and the newline-terminated wire record is at most 512 bytes. Put larger data in a declared artifact/path and send only its bounded reference or instruction through Control. Delivery revalidates owner, generation, state, and process identity under the canonical lifecycle lock.
+
+## Run State
+
+Owned state lives under:
+
+```text
+~/.pi/agent/tmp/pi-actors/runs/<run>/
+```
+
+Core files:
+
+- `run.json` — identity, owner, generation, captured Recipe, policy, process identity;
+- `trace.jsonl` — structured observations;
+- `controls.jsonl` — durable Controls and outcomes;
+- `control-endpoint.json` — generation-fenced service readiness;
+- `execution.json` — command/session provenance and complete-capture references;
+- `result.json`, command logs, progress, and declared artifacts.
+
+The runtime preserves owner filtering, process-identity verification, lifecycle locking, shutdown kill independent of actor-local Control capacity, terminal reconciliation, bounded captures, owned Pi sessions, path containment, and redaction. Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state. Restart clears generation-local Trace, Control, endpoint, execution, and terminal evidence; archive preserves the bounded tree, while prune preserves only requested artifacts.
+
+## Actor Inspector
+
+Open the owner-filtered TUI:
+
+```text
+/actor-inspector
+```
+
+It presents actor instances through Recipe, Trace, and Control tabs, with source filtering, detail navigation, refresh, and generation-fenced Run kill.
+
+## Skill Recipes
+
+Useful entry points include:
+
+- `project-work/repo-health`
+- `project-work/release-readiness`
+- `swarm/quorum-review`
+- `artifacts/bundle`
+- `music-player/playback` — singleton controlled playback service
+- `actors/resource-locker` — optional controlled resource-lock service
+
+Validate Recipes with:
+
+```bash
+npm run recipes:qa
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run validate
+npm run test:preservation
+```
+
+See the [documentation index](./docs/README.md), [Run lifecycle](./docs/async-runs.md), and [Recipe library](./docs/recipe-library.md).
+
+Project context: [AGENTS.md](./AGENTS.md) · [BACKLOG.md](./BACKLOG.md) · [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+MIT

package/node_modules/@llblab/pi-actors/dist/fixtures/protocol/artifact-manifest.json

@@ -0,0 +1,9 @@
+{
+  "report": {
+    "path": "{state_dir}/report.md",
+    "kind": "markdown",
+    "media_type": "text/markdown",
+    "required": true
+  },
+  "journal": "{state_dir}/journal.jsonl"
+}

package/node_modules/@llblab/pi-actors/dist/fixtures/protocol/control-endpoint.json

@@ -0,0 +1,6 @@
+{
+  "path": "named-pipe-example",
+  "type": "named-pipe",
+  "ready_at": "2026-01-01T00:00:00.000Z",
+  "run_instance_id": "generation-1"
+}

package/node_modules/@llblab/pi-actors/dist/fixtures/protocol/control-record.json

@@ -0,0 +1,9 @@
+{
+  "id": "control-1",
+  "run_instance_id": "generation-1",
+  "action": "pause",
+  "input": { "reason": "operator" },
+  "status": "handled",
+  "queued_at": "2026-01-01T00:00:00.000Z",
+  "handled_at": "2026-01-01T00:00:01.000Z"
+}

package/node_modules/@llblab/pi-actors/dist/fixtures/protocol/recipe-summary.json

@@ -0,0 +1,8 @@
+{
+  "id": "music-player",
+  "path": "skills/media/recipes/player.json",
+  "location": "packaged",
+  "active": true,
+  "args": ["repo", "command", "source", "loop", "volume", "player", "state_dir"],
+  "control": ["play", "pause", "resume", "toggle", "next", "previous", "stop", "status"]
+}

package/node_modules/@llblab/pi-actors/dist/fixtures/protocol/run-state.json

@@ -0,0 +1,10 @@
+{
+  "run": "demo",
+  "state_dir": "{state_dir}",
+  "status": "running",
+  "template": "echo demo",
+  "values": {
+    "run_id": "demo",
+    "state_dir": "{state_dir}"
+  }
+}

package/node_modules/@llblab/pi-actors/dist/fixtures/protocol/trace-event.json

@@ -0,0 +1,9 @@
+{
+  "id": "trace-1",
+  "ts": "2026-01-01T00:00:00.000Z",
+  "kind": "progress.update",
+  "summary": "Work progressed",
+  "data": { "completed": 1 },
+  "level": "info",
+  "attention": "notify"
+}

package/node_modules/@llblab/pi-actors/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * pi-actors — actor runtime and persistent local tool registry for pi.
+ * Zones: composition root, pi agent, actor runtime
+ * Owns extension composition and Pi event registration, not domain behavior.
+ */
+import * as Pi from "./lib/pi.ts";
+export default function toolRegistryExtension(pi: Pi.ExtensionAPI): void;

package/node_modules/@llblab/pi-actors/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * pi-actors — actor runtime and persistent local tool registry for pi.
+ * Zones: composition root, pi agent, actor runtime
+ * Owns extension composition and Pi event registration, not domain behavior.
+ */
+import * as ExtensionRuntime from "./lib/extension-runtime.js";
+import * as InspectorCommand from "./lib/inspector-command.js";
+export default function toolRegistryExtension(pi) {
+    const runtime = ExtensionRuntime.createActorExtensionRuntime(pi);
+    pi.on("resources_discover", async () => runtime.discoverResources(import.meta.url));
+    pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
+    pi.on("agent_end", async (_event, ctx) => runtime.onAgentEnd(ctx));
+    pi.on("session_shutdown", async (event, ctx) => runtime.onSessionShutdown(event.reason, ctx));
+    pi.on("before_agent_start", async (event, ctx) => runtime.beforeAgentStart(event.systemPrompt, event.systemPromptOptions.skills ?? [], ctx));
+    InspectorCommand.registerActorInspectorCommand(pi, runtime.getRunOwnerId);
+    runtime.registerCoreTools();
+}

package/node_modules/@llblab/pi-actors/dist/lib/async-runs.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Command-template async run lifecycle facade.
+ * Owns: launch, state observation, listing, message/control facade methods, and retention while runs-* subdomains own narrower run internals.
+ */
+import type { CommandTemplateFailureScope, CommandTemplateValue } from "./command-templates.ts";
+import { type CurrentPolicyProvenance } from "./model-context.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
+import { type RunProcessIdentity } from "./runs-process.ts";
+import * as RuntimeIdentity from "./runtime-identity.ts";
+import * as RunsIndex from "./runs-index.ts";
+import * as RunsParentTeardown from "./runs-parent-teardown.ts";
+import { type DeliverRunControlOptions, type DeliverRunControlRequest } from "./runs-control-delivery.ts";
+import { type AsyncRunStatus } from "./runs-status.ts";
+export type AsyncRunLaunchSource = "spawn" | "tool";
+export interface AsyncRunControlEndpoint {
+    path: string;
+    type: "fifo" | "named-pipe";
+}
+export declare function normalizeRunTransportContext(value: unknown): Record<string, string | number | boolean> | undefined;
+export interface AsyncRunStartParams {
+    async?: boolean;
+    control_endpoint?: AsyncRunControlEndpoint;
+    file?: string;
+    launch_source?: AsyncRunLaunchSource;
+    lifecycleHooks?: {
+        onLockContention?(): void;
+    };
+    launch_correlation?: {
+        correlation_id?: string;
+        tool_call_id?: string;
+    };
+    name?: string;
+    ownerId?: string;
+    run_id?: string;
+    singleton?: boolean;
+    singleton_run_id?: string;
+    singleton_recipe_id?: string;
+    state_dir?: string;
+    tool?: string;
+    template?: CommandTemplateValue;
+    args?: string[];
+    defaults?: Record<string, unknown>;
+    recipe_dir?: string;
+    skill_dir?: string;
+    parallel?: boolean;
+    concurrency?: number | string;
+    min_successful?: number | string;
+    label?: string;
+    when?: boolean | string;
+    timeout?: number | string;
+    delay?: number | string;
+    accept_output?: "review_evidence";
+    output?: string;
+    artifacts?: Record<string, RunArtifactDeclaration>;
+    control?: string[];
+    notification_policy?: "normal" | "silent";
+    retire_when?: "children_terminal";
+    retry?: number | string;
+    failure?: CommandTemplateFailureScope;
+    recover?: CommandTemplateValue;
+    transport_context?: Record<string, unknown>;
+    repeat?: number;
+    values?: Record<string, unknown>;
+    policy_values?: Record<string, unknown>;
+    actor_context?: boolean | string;
+    cwd?: string;
+}
+export type { AsyncRunStatus } from "./runs-status.ts";
+export interface AsyncRunMeta {
+    argv: string[];
+    createdAt: string;
+    cwd: string;
+    launch_kind?: AsyncRunLaunchSource;
+    launch_source?: AsyncRunLaunchSource;
+    launch_correlation?: {
+        correlation_id?: string;
+        tool_call_id?: string;
+    };
+    ownerId?: string;
+    pid: number;
+    recipe?: string;
+    recipe_file?: string;
+    run: string;
+    run_instance_id: string;
+    state_dir: string;
+    state_schema: typeof RuntimeIdentity.RUN_STATE_SCHEMA;
+    status: AsyncRunStatus;
+    tool?: string;
+    template: CommandTemplateValue;
+    values: Record<string, unknown>;
+    artifacts?: Record<string, RunArtifactDeclaration>;
+    control?: string[];
+    control_endpoint?: AsyncRunControlEndpoint;
+    model_policy?: CurrentPolicyProvenance;
+    notification_policy?: "normal" | "silent";
+    process_identity?: RunProcessIdentity;
+    recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
+    retire_when?: "children_terminal";
+    reused?: boolean;
+    singleton?: boolean;
+    singleton_recipe_id?: string;
+    singleton_values?: Record<string, unknown>;
+    transport_context?: Record<string, unknown>;
+}
+export { safeRunId } from "./runs-identity.ts";
+export { resolveArtifactManifest } from "./runs-artifacts.ts";
+export type { RunArtifactDeclaration, RunArtifactManifestEntry, } from "./runs-artifacts.ts";
+export interface AsyncRunStartOptions {
+    skillContext?: RecipesReferences.ActiveSkillRecipeContext;
+}
+export declare function startRun(params: AsyncRunStartParams, cwd: string, options?: AsyncRunStartOptions): AsyncRunMeta;
+export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
+export type { RunStateIndexEntry } from "./runs-index.ts";
+export declare function listRunStateDirs(stateRoot?: string): string[];
+export declare function rebuildRunStateIndex(stateRoot?: string): RunsIndex.RunStateIndexEntry[];
+export declare function readRunStateIndex(stateRoot?: string): RunsIndex.RunStateIndexEntry[] | undefined;
+export declare function listRuns(stateRoot?: string, statusFilter?: string): Array<Record<string, unknown>>;
+export type { ParentRunTeardownAttempt, ParentRunTeardownDiscoveryFailure, ParentRunTeardownResult, } from "./runs-parent-teardown.ts";
+export interface ParentRunsTeardownSummaryResult extends RunsParentTeardown.ParentRunTeardownResult {
+    summaryPath?: string;
+}
+export declare function teardownRunsOwnedByParent(ownerId: string | undefined, stateRoot?: string, options?: {
+    trigger?: string;
+}): ParentRunsTeardownSummaryResult;
+export declare function tailRun(runOrDir: string, lines?: number): string;
+export type { DeliverRunControlOptions, DeliverRunControlRequest, } from "./runs-control-delivery.ts";
+export interface SendRunControlOptions extends DeliverRunControlOptions {
+    ownerId?: string;
+}
+export declare function sendRunControl(runOrDir: string, request: DeliverRunControlRequest, options?: SendRunControlOptions): Promise<Record<string, unknown>>;
+export { getRunProcessSignalPlan } from "./runs-control.ts";
+export type { RunProcessSignalPlan } from "./runs-control.ts";
+export interface RunControlExpectation {
+    onLocked?(): void;
+    ownerId?: string;
+    runInstanceId?: string;
+}
+export declare function markRunTerminalNotificationHandled(stateDir: string, status: string): void;
+export declare function recordRunTerminalDeliveryFailure(stateDir: string, status: string, error: unknown): void;
+export declare function cancelRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
+export declare function archiveRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;
+export declare function pruneRun(runOrDir: string, options?: {
+    preserveArtifacts?: boolean;
+}, expected?: RunControlExpectation): Record<string, unknown>;
+export declare function killRun(runOrDir: string, expected?: RunControlExpectation): Record<string, unknown>;