@llblab/pi-actors 0.19.10 → 0.19.11

package/AGENTS.md

@@ -43,7 +43,7 @@
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
 - `Template recipe graph`: The valid execution chain is `tool → template → recipe → run → template`; file-backed and co-located recipes are storage variants of that chain | Trigger: Adding registry bindings, recipes, docs, or runtime shortcuts | Action: Keep command templates synchronous and portable, use `async: true` as the detached run switch, require every recipe to own `template` directly, and reject cyclic shortcuts such as recipe-owned `tool`
 - `Layer boundary discipline`: Command-template evolution must be separated from template-recipe configuration and async-run lifecycle configuration | Trigger: Adding syntax, placeholders, imports, async controls, or docs | Action: Put portable execution graph semantics in `docs/command-templates.md`, recipe storage/import/default/reference behavior in `docs/template-recipes.md`, and detached lifecycle/state/IPC behavior in `docs/async-runs.md`; type imported recipes as command-template-shaped recipe definitions, not async-run instances
-- `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, and keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason
+- `Executable script recipes`: Recipe templates may point directly at executable helper scripts, including JavaScript `.mjs` files with shebangs; do not prefix such recipes with `node` unless the script is intentionally not executable | Trigger: Adding or editing script-backed recipes and docs | Action: Keep the script executable bit, call `{repo}/scripts/name.mjs ...` directly, keep the standard library on one maintained wrapper per capability unless a second wrapper has a concrete platform reason, and ensure installed npm script entrypoints do not import `.ts` files from under `node_modules` through Node native type stripping
 - `Registry safety boundaries`: Tool definitions use `template`, not `script`, and built-in/core tool names must not be shadowed | Trigger: Loading/editing persisted config or registration logic | Action: Reject legacy `script` entries explicitly, avoid silent user-config rewrites outside the repo, and keep conflict checks before persistence/runtime registration
 - `Async run observability`: Ambient triangles count active async work units across the visible run tree: each running async run contributes at least one triangle, reported active parallel command/subagent branches contribute the visible branch count when greater than one, and descendant `pi -p` subagent processes are folded in so coordinator-plus-workers scenarios expand beyond a single coordinator marker. Event-driven terminal/outbox watchers should initiate follow-up for unhandled terminal completion/failure states, failed or in-flight `command.done` branch completions, and coordinator-bound script-authored messages with bounded body previews; actor `message` is the explicit coordinator-to-run command channel paired with these upward events. Do not restore busy-polling loops, sleep-then-status smoke examples, duplicate follow-ups for final successful leaf commands, or duplicate follow-ups for `cancel`, `kill`, or control-stop actions already handled by synchronous tool results. | Trigger: Changing async run UI, notifications, actor-message routing, or smoke-test interpretation | Action: Preserve branch-aware triangles from `progress.activeSubagents`, runtime-inferred branch bubbling for packaged fanout completion, process-tree expansion for coordinator-launched workers, terminal notifications as event-driven behavior, and docs/examples that teach reactive run→coordinator→message loops before sleep-polling patterns.
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.

package/BACKLOG.md

@@ -8,10 +8,13 @@
 - Goal: Continue evolving actor communication without adding a second public messaging model.
 - Direction:
   - Evaluate whether room storage/routing should remain built into the tool adapter or move behind a dedicated non-LLM communication actor recipe/script, possibly singleton-scoped. Preserve the same public `room:<run>` address and envelope either way.
+  - Treat the next backend decision as an evidence-backed experiment, not a rewrite: stress a real room/direct-message workload, compare the current file-backed adapter with a thin communication actor/helper, and record the decision.
   - Consider reducing direct file-backed state where it improves coherence: model room/roster state as actor-owned data structures served by helper scripts/actors, with files retained only for durable snapshots, recovery, artifacts, or audit logs.
-  - Further storage changes should preserve the current burst/read/concurrency safeguards: branch communication snapshot writes are debounced, root snapshots stay current, roster files are not rewritten during bursts when only `last_seen` changes, room status inspection does not parse full timelines, and branch-local inbox append/status rewrites are lock-guarded.
+  - Further storage changes should preserve the current burst/read/concurrency safeguards: branch communication snapshot writes are debounced, root snapshots stay current, roster files are not rewritten during bursts when only `last_seen` changes, room status inspection does not parse full timelines, branch-local inbox append/status rewrites are lock-guarded, and legacy no-ID branch inbox records can be claimed exactly once.
+  - Prevent monolith drift: `actor-rooms.ts` may remain a thin adapter, but growing routing policy, subscription loops, fanout policy, or long-lived state ownership should move behind a focused communication helper/actor rather than accumulating in the tool adapter.
 - Exit:
   - Any backend/storage change preserves existing `spawn` / `message` / `inspect` semantics and room address compatibility.
+  - A short decision note or changelog entry explains why the room backend stayed file-backed or moved behind a communication actor/helper.
 
 ### Graceful Actor Retirement
 
@@ -27,6 +30,18 @@
   - A packaged coordinator recipe can launch worker actors, complete its coordination duties, and shut itself down automatically after the worker tree reaches terminal state.
   - Persistent services and implementer actors remain alive unless their recipe explicitly opts into retirement.
 
+### Coordinator Strategy Boundary
+
+- Priority: Medium.
+- Goal: Keep the generic coordinator from becoming a second overloaded monolith as room/direct-message workflows mature.
+- Direction:
+  - Split only at real pressure points: branch inbox claim/finalize helpers, participant execution, room transcript synthesis, and mode strategies are likely seams, but avoid cosmetic module churn.
+  - Preserve the current principle that the locker stays generic/thin and all orchestration policy stays in coordinator strategy code or recipe composition.
+  - Prefer reusable helper modules or small scripts only when at least two packaged workflows need the same behavior.
+- Exit:
+  - Adding a new coordinator mode or packaged multi-agent workflow does not require editing unrelated mode logic.
+  - Existing room-swarm, locker, and direct-branch-message tests still cover the extracted seams.
+
 ### Consensus-First Build Recipe
 
 - Priority: Medium.
@@ -42,6 +57,18 @@
   - A packaged recipe can reproduce the interactive-music-instrument workflow shape for another single-artifact task without copying the demo script.
   - Docs and skills point agents to the packaged recipe and explain when to choose it over a free-form room swarm.
 
+### Actor OS Scenario Smoke Matrix
+
+- Priority: Medium.
+- Goal: Convert the 0.19.x actor-communication hardening into repeatable end-to-end scenario checks instead of relying on ad hoc demos.
+- Direction:
+  - Cover one scenario each for shared room coordination, direct branch work delivery, branch inbox claim/handle/fail transitions, inspector navigation, recipe context injection, recipe persistence suggestion, and opt-in retirement candidate detection.
+  - Keep scenarios local-first and bounded: fake `pi`/models where possible, no external services, no long sleeps, no broad golden transcripts.
+  - Prefer packaged recipes and public `spawn` / `message` / `inspect` calls so the smoke matrix exercises the same surface agents use.
+- Exit:
+  - A single validation command or documented test group verifies the actor OS behaviors that made 0.19.x production-useful.
+  - The smoke matrix catches regressions in actor communication, recipe memory, and observability without requiring a manual swarm demo.
+
 ### Persistent Backlog Implementer Workflow
 
 - Priority: Medium.
@@ -84,10 +111,22 @@
   - Add nested recipe directories only after flat `recipes/*.json` discovery semantics are stable.
   - Keep same-id priority and invalid-blocking behavior explicit if nested ids are introduced.
 
+### Actor Recipe Feedback Loop
+
+- Priority: Low.
+- Goal: Turn actor recipe-context awareness into a practical improvement loop for packaged recipes and operator-owned recipe memory.
+- Direction:
+  - After real multi-agent runs, capture whether child actors report that recipe/import/mailbox/role boundaries fit the task.
+  - Keep the loop advisory and operator-gated: feedback may suggest recipe edits or copying into `~/.pi/agent/recipes`, but must not auto-save or rewrite durable recipes without confirmation.
+  - Prefer small recipe/readme/skill refinements over adding scenario catalogs; recurring patterns should become packaged recipes only after repeated use.
+- Exit:
+  - At least one real run produces recipe-boundary feedback that is either applied to a recipe/docs change or explicitly rejected with rationale.
+
 ### Recipe Usage Telemetry Evolution
 
 - Priority: Low.
 - Goal: Improve long-term operator insight into recipe usefulness without making telemetry noisy.
 - Direction:
   - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
+  - Consider an operator-approved recipe promotion workflow that turns successful package/ad hoc/direct spawn suggestions into a reviewed `~/.pi/agent/recipes` entry with provenance and diff, without auto-saving.
   - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.19.11: Installed Async Runner Hotfix
+
+- `[Async Runs]` Fixed installed npm package async recipe launches on Node 22 by avoiding direct runtime imports of raw `.ts` files from under `node_modules` in `scripts/async-runner.mjs`. Installed runners now copy the package `lib` sources into the run state before importing them, keeping Node native type stripping outside the blocked `node_modules` path.
+- `[Scripts]` Applied the same installed-package import guard to `scripts/validate-recipe.mjs`, so the packaged recipe validator works when invoked from an installed `@llblab/pi-actors` package.
+- `[Tests]` Added installed-package script smoke coverage that copies `lib`/`scripts` under a temporary `node_modules/@llblab/pi-actors` path and verifies both async runner execution and recipe validation avoid `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`.
+- `[Package]` Bumped package metadata, lockfile metadata, and packaged skill metadata to `0.19.11` for the hotfix release.
+
 ## 0.19.10: Legacy Branch Message Claim IDs
 
 - `[Branch Messages]` Coordinator claim handling now assigns IDs to older/manual queued branch inbox entries that lack `id`, so injected direct messages can still transition to `handled` or `failed` and do not repeat forever.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.19.10",
+  "version": "0.19.11",
   "private": false,
-  "description": "Actor runtime and orchestrator for agent-managed local processes",
+  "description": "Local Actor Kernel for Pi",
   "keywords": [
     "pi-package",
     "pi-extension",

package/scripts/async-runner.mjs

@@ -11,18 +11,42 @@
  * Keep orchestration policy out of this file.
  */
 
-import { appendFileSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, cpSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 const stateDir = process.argv[2];
 if (!stateDir) {
   console.error("missing state dir");
   process.exit(1);
 }
-const { executeRegisteredTool } = await import("../lib/execution.ts");
-const { execCommandTemplate } = await import("../lib/command-templates.ts");
-const { appendRecipeContextToPiArgs } = await import("../lib/actor-recipe-context.ts");
-const { writeJsonAtomic } = await import("../lib/file-state.ts");
+
+function scriptFile() {
+  return fileURLToPath(import.meta.url);
+}
+
+function isUnderNodeModules(file) {
+  return /[/\\]node_modules[/\\]/.test(file);
+}
+
+function prepareTypeStripImportRoot() {
+  const packageRoot = dirname(dirname(scriptFile()));
+  const sourceLib = join(packageRoot, "lib");
+  if (!isUnderNodeModules(packageRoot)) return sourceLib;
+  const copiedLib = join(stateDir, ".type-strip-lib");
+  if (!existsSync(copiedLib)) cpSync(sourceLib, copiedLib, { recursive: true });
+  return copiedLib;
+}
+
+const typeStripImportRoot = prepareTypeStripImportRoot();
+async function importLib(name) {
+  return import(pathToFileURL(join(typeStripImportRoot, `${name}.ts`)).href);
+}
+
+const { executeRegisteredTool } = await importLib("execution");
+const { execCommandTemplate } = await importLib("command-templates");
+const { appendRecipeContextToPiArgs } = await importLib("actor-recipe-context");
+const { writeJsonAtomic } = await importLib("file-state");
 const runPath = join(stateDir, "run.json");
 const progressPath = join(stateDir, "progress.json");
 const resultPath = join(stateDir, "result.json");

package/scripts/validate-recipe.mjs

@@ -1,9 +1,30 @@
 #!/usr/bin/env -S node --experimental-strip-types
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { cpSync, existsSync, mkdtempSync, readdirSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { readResolvedRecipeConfig } from "../lib/recipe-references.ts";
+function scriptFile() {
+  return fileURLToPath(import.meta.url);
+}
+
+function isUnderNodeModules(file) {
+  return /[/\\]node_modules[/\\]/.test(file);
+}
+
+function prepareTypeStripImportRoot() {
+  const packageRoot = dirname(dirname(scriptFile()));
+  const sourceLib = join(packageRoot, "lib");
+  if (!isUnderNodeModules(packageRoot)) return sourceLib;
+  const copiedLib = join(mkdtempSync(join(tmpdir(), "pi-actors-validate-lib-")), "lib");
+  cpSync(sourceLib, copiedLib, { recursive: true });
+  return copiedLib;
+}
+
+const typeStripImportRoot = prepareTypeStripImportRoot();
+const { readResolvedRecipeConfig } = await import(
+  pathToFileURL(join(typeStripImportRoot, "recipe-references.ts")).href
+);
 
 function usage() {
   console.error(`Usage:

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.19.10
+  version: 0.19.11
 ---
 
 # Actors (pi-actors)

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.19.10
+  version: 0.19.11
 ---
 
 # Swarm