@llblab/pi-actors 0.31.0 → 0.33.0

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Required practical guide for non-trivial pi-actors use. Read before using or changing spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.31.0
+  version: 0.33.0
 ---
 
 # Actors (pi-actors)
@@ -39,12 +39,11 @@ Trusted local capability
 
 - **Command template**: portable execution graph. String leaf, sequence array, or object node with controls.
 - **Recipe**: saved JSON definition wrapping a template with args, defaults, imports, mailbox, artifacts, metadata, and optional `async: true`.
-- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, communication snapshot, and artifacts.
-- **Room actor**: shared timeline + roster endpoint addressable as `room:<run>`; every spawned run gets `room:<run>`.
+- **Run actor**: one detached execution instance addressable as `run:<id>` with status, logs, messages, mailbox metadata, files, and artifacts.
 - **Tool actor**: registered persistent capability addressable as `tool:<name>` and callable through the generated tool or `message`. `tool:pi-actors` is reserved for runtime/status inspection.
-- **Coordinator/session**: the current pi session endpoint that receives bounded actor follow-ups.
-- **Mailbox**: public interaction contract: message types the actor accepts/emits.
 - **Artifact**: named durable output path declared by a recipe/run.
+- **Mailbox**: interaction contract: message types the actor accepts/emits.
+- **Advanced group/coordination surfaces**: `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:<id>`, and communication snapshots exist for multi-actor workflows and diagnostics; do not make them the default mental model.
 
 ## Three Verbs
 
@@ -86,8 +85,9 @@ Envelope fields:
 
 - Required: `to`, `type`.
 - Useful: `summary`, `body`, `from`, `reply_to`, `correlation_id`, `metadata`.
-- Addresses: `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `tool:<name>`, `coordinator`, `session:<id>`.
-- Room posts require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
+- Core addresses: `run:<id>`, `tool:<name>`.
+- Advanced addresses: `branch:<run>/<branch>`, `room:<run>` for group timeline/roster, `coordinator`, `session:<id>`.
+- Group posts to `room:<run>` require `from` from the same run (`run:<run>` or `branch:<run>/<branch>`).
 - Runtime termination message: `control.kill` is the only documented actor message that kills a run. `control.stop` and `control.cancel` are actor-local mailbox vocabulary only when a recipe declares and handles them. Terminal retention messages: `control.archive`, `control.prune`.
 - Long-lived child processes should remain in the run-owned process group unless the recipe implements an explicit daemon termination bridge; do not leave unowned detached services behind `control.kill`.
 
@@ -99,12 +99,7 @@ Check `inspect view=mailbox` before domain-specific messages.
 { "target": "run:repo-health", "view": "status" }
 { "target": "run:repo-health", "view": "tail", "lines": "80" }
 { "target": "run:repo-health", "view": "messages" }
-{ "target": "run:repo-health", "view": "communication" }
 { "target": "run:repo-health", "view": "artifacts" }
-{ "target": "room:repo-health", "view": "status" }
-{ "target": "room:repo-health", "view": "roster" }
-{ "target": "room:repo-health", "view": "contacts" }
-{ "target": "room:repo-health", "view": "previews" }
 { "target": "tool:pi-actors", "view": "status" }
 { "target": "tool:music_player", "view": "status" }
 { "target": "recipes", "view": "status" }
@@ -116,10 +111,10 @@ Views:
 - `status`: lifecycle, pid, values, progress, result, compact summary.
 - `tail`: recent stdout/stderr/log tail.
 - `messages`: actor messages emitted by the run, or room timeline entries for `room:*`.
-- `communication`: run/branch communication snapshot with self/root/default-room/member/contact hints.
-- `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
-- `contacts`: roster-derived direct-message targets without full roster metadata.
-- `previews`: TUI-ready bounded room message previews with timestamp/from/to/type/summary/body_preview.
+- Advanced `communication`: run/branch group-coordination snapshot with self/root/default-room/member/contact hints.
+- Advanced `roster`: room member list with address, role, parent, caps, claim, status, and last seen.
+- Advanced `contacts`: roster-derived direct-message targets without full roster metadata.
+- Advanced `previews`: TUI-ready bounded group-message previews with timestamp/from/to/type/summary/body_preview.
 - `mailbox`: declared accepts/emits contract for runs; queued direct branch inbox messages for `branch:<run>/<branch>` with `id`, status, route/type, and queue/handling timestamps.
 - `files`: run state directory file list.
 - `artifacts`: declared artifact paths/status.
@@ -218,13 +213,13 @@ Only matching filename ids compete. Higher priority shadows lower priority; with
 Muscle-memory lens: pi-actors has two durable executable-memory layers.
 
 1. `~/.pi/agent/recipes/*.json` and `*.md` are the agent's active capability memory. Every recipe in that directory becomes an easy-to-call tool automatically and survives into later sessions. Descriptions matter here because they become the tool's operator-facing title/context.
-2. `~/.pi/agent/recipes/candidates/*.json` is candidate memory captured from successful inline `spawn template=...` runs. Candidates are not registered tools and do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/candidates/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
+2. `~/.pi/agent/recipes/drafts/*.json` is draft memory captured from successful inline `spawn template=...` runs. Drafts do not enter the injected tool surface. They remain reusable by explicit path, e.g. `spawn file="~/.pi/agent/recipes/drafts/<name>.json"`, and can be promoted by moving or copying one level up into `~/.pi/agent/recipes`.
 
-Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow candidate memory by trying ad hoc actors successfully. Treat both as executable habits: candidates are the workbench/proving ground; root recipes are promoted muscle memory.
+Agents grow active memory by calling `register_tool` or by deliberate recipe-file edits. They grow draft memory by trying ad hoc actors successfully. Treat both as executable habits: drafts are the workbench/proving ground; root recipes are promoted muscle memory.
 
 Usage lens: user recipes may carry extension-maintained launch metadata such as `usage.calls` and `usage.last_called`. The extension increments the counter when it starts that concrete recipe; agents should not hand-edit counters as part of normal recipe maintenance. Treat usage as evidence for usefulness analysis: heavily used recipes are good candidates for promotion, documentation, or stronger tests; unused recipes are cleanup candidates. Do not use failure counts as a primary usefulness signal because failures may reflect bad caller judgment rather than bad recipes. Do not delete or demote solely from counters without operator approval.
 
-Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave candidate recipes as replayable evidence, not active tools. If a candidate is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
+Promotion lens: successful transient/ad hoc actor runs are evidence, not commands. Inline spawns leave draft recipes as replayable evidence, not active tools. If a draft is repeatable, parameterized, safe enough, and likely useful later, the agent may promote it by moving/copying it into `~/.pi/agent/recipes` or by calling `register_tool` with a concise name, typed args/defaults, and a reviewed template or recipe path. Do not auto-register every success; do not promote temp paths, secrets, one-off prompts, or project-private assumptions without normalization and approval.
 
 Cleanup rule: periodically inspect `~/.pi/agent/recipes` as the live muscle-memory set. For each stale, duplicate, too-specific, or low-value recipe, choose one explicit action: keep as a tool, move it out of the agent recipe root to retain recipe-only memory, merge into a better recipe, or delete/archive the file. Prefer moving over deletion when the recipe may still be useful as a component. Never silently remove tools during unrelated work.
 

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.31.0
+  version: 0.33.0
 ---
 
 # Swarm
@@ -30,8 +30,8 @@ Maintain this skill as a living orchestration standard. When real swarm work exp
 - `Async Run`: A local lifecycle envelope around a command-template swarm composer or utility. It owns state, logs, status, cancellation, and observability, not swarm semantics.
 - `Lens`: A deliberately narrow cognitive role assigned to one subagent, such as security, tests, architecture, economics, or operator UX.
 - `Task Card`: A bounded implementation assignment with goal, allowed files, avoided files, expected output, and validation gates.
-- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, candidate recipes, command templates, async runs, or services.
-- `Candidate Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
+- `Component Capability`: An abstract adapter operation such as launcher, reviewer, verifier, merger, quorum, checkpoint, follow-up, judge, or normalizer. Swarm may target these capabilities, but local adapters bind them to concrete tools, recipes, draft recipes, command templates, async runs, or services.
+- `Draft Recipe`: A reusable but non-registered recipe captured from a successful inline actor spawn under `~/.pi/agent/recipes/drafts`. It can be replayed by explicit file path and later promoted into the active tool recipe root after enough dogfood.
 - `Coordinator Checkpoint`: A deliberate subagent pause where the subagent preserves its working context, sends a bounded question or status to the orchestrator, receives a coordinator reply, and continues in the same subagent context.
 - `Evidence Checkpoint`: A deliberate stop where a subagent records sources, assumptions, confidence, contradictions, or blocking evidence gaps before synthesis.
 - `Integrator`: The human or agent that merges isolated branches/worktrees into the shared target and owns conflict resolution.

package/dist/lib/conformance.d.ts

@@ -1,12 +0,0 @@
-/**
- * Internal conformance runner logic.
- * Zones: CI/release validation, protocol regression suite selection
- */
-export declare const conformanceSuites: string[];
-export interface ConformanceReport {
-    code: number;
-    output: string;
-    summary: string;
-    suites: number;
-}
-export declare function runConformance(cwd?: URL): ConformanceReport;

package/dist/lib/conformance.js

@@ -1,28 +0,0 @@
-/**
- * Internal conformance runner logic.
- * Zones: CI/release validation, protocol regression suite selection
- */
-import { spawnSync } from "node:child_process";
-export const conformanceSuites = [
-    "tests/protocol-examples.test.ts",
-    "tests/recipe-discovery.test.ts",
-    "tests/registry.test.ts",
-    "tests/runtime-registry.test.ts",
-    "tests/async-runs.test.ts",
-    "tests/actor-rooms.test.ts",
-    "tests/tools.test.ts",
-];
-export function runConformance(cwd = new URL("..", import.meta.url)) {
-    const result = spawnSync(process.execPath, ["--experimental-strip-types", "--test", ...conformanceSuites], { cwd, encoding: "utf8", stdio: "pipe" });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    const summary = output
-        .split("\n")
-        .filter((line) => /^ℹ (tests|pass|fail|cancelled|skipped|todo|duration_ms) /.test(line))
-        .join("\n");
-    return {
-        code: result.status ?? 1,
-        output,
-        summary,
-        suites: conformanceSuites.length,
-    };
-}

package/lib/conformance.ts

@@ -1,46 +0,0 @@
-/**
- * Internal conformance runner logic.
- * Zones: CI/release validation, protocol regression suite selection
- */
-
-import { spawnSync } from "node:child_process";
-
-export const conformanceSuites = [
-  "tests/protocol-examples.test.ts",
-  "tests/recipe-discovery.test.ts",
-  "tests/registry.test.ts",
-  "tests/runtime-registry.test.ts",
-  "tests/async-runs.test.ts",
-  "tests/actor-rooms.test.ts",
-  "tests/tools.test.ts",
-];
-
-export interface ConformanceReport {
-  code: number;
-  output: string;
-  summary: string;
-  suites: number;
-}
-
-export function runConformance(cwd = new URL("..", import.meta.url)): ConformanceReport {
-  const result = spawnSync(
-    process.execPath,
-    ["--experimental-strip-types", "--test", ...conformanceSuites],
-    { cwd, encoding: "utf8", stdio: "pipe" },
-  );
-
-  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-  const summary = output
-    .split("\n")
-    .filter((line) =>
-      /^ℹ (tests|pass|fail|cancelled|skipped|todo|duration_ms) /.test(line),
-    )
-    .join("\n");
-
-  return {
-    code: result.status ?? 1,
-    output,
-    summary,
-    suites: conformanceSuites.length,
-  };
-}