@llblab/pi-actors 0.33.0 → 0.34.1

package/AGENTS.md

@@ -18,12 +18,12 @@ Treat this extension as an experimental self-evolution membrane for the agent ha
 ```text
 Pi host
   -> index.ts composition root
-     -> lib/tools.ts / prompts.ts        public tool + injected prompt surface
+     -> lib/tools*.ts / prompts.ts      public tool + injected prompt surface
      -> lib/runtime.ts / registry.ts     active user recipe tools
-     -> lib/recipe-*.ts                  packaged/user/draft recipe discovery
+     -> lib/recipes-*.ts                 packaged/user/draft recipe discovery
      -> lib/async-runs.ts                spawn lifecycle and run state
-     -> lib/actor-rooms.ts               room, roster, mailbox, communication log
-     -> scripts/*.mjs                    thin process entrypoints
+     -> lib/rooms.ts               room, roster, mailbox, communication log
+     -> scripts/*.mjs                    self-contained process entrypoints
      -> recipes/*.json                   packaged actor components
      -> skills/* + docs/*                agent guidance and transportable specs
 ```
@@ -34,19 +34,29 @@ Pi host
 
 - `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior.
   - `command-templates.ts`: portable command-template execution graph.
+  - `tools-access.ts`: shared public tool access/session ownership guards and normalized mismatch diagnostics.
+  - `tools-mailbox.ts`: mailbox contract normalization and accepted/emitted message type helpers for public tool responses.
   - `schema.ts`: tool arg declarations and placeholder-derived schemas.
   - `identity.ts`, `paths.ts`, `config.ts`: names, paths, and persistence.
   - `registry.ts`, `runtime.ts`: register/update/delete, load/conflict/registration coordination.
-  - `execution.ts`, `output.ts`, `limits.ts`: registered-tool execution and bounded output.
-  - `recipe-references.ts`, `recipe-discovery.ts`, `recipe-usage.ts`: recipe graph, discovery, and usage metadata.
-  - `async-runs.ts`, `runtime-notifier.ts`, `mailbox-loop.ts`: detached run state, wake notifications, and mailbox worker helpers.
-  - `actor-rooms.ts`, `actor-inspector-tui.ts`, `observability.ts`: rooms, communication previews, and ambient run status.
-  - `prompts.ts`, `tools.ts`, `temp.ts`: LLM-facing copy, pi-facing tool definitions, and temp cleanup.
+  - `execution.ts`, `execution-output.ts`, `limits.ts`: registered-tool execution and bounded output.
+  - `recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`: recipe graph, discovery, and usage metadata.
+  - `async-runs.ts`: detached run lifecycle facade; `runs-*` subdomains own artifacts, start guards, status, indexes, inbox/outbox, delivery, process control, and retention internals.
+  - `runtime-notifier.ts`, `mailbox-loop.ts`: wake notifications and reusable run/branch mailbox worker loops.
+  - `messages.ts`, `rooms.ts`, `recipes-context.ts`, `inspector.ts`, `observability.ts`: addressed message protocol, rooms, recipe prompt context, communication previews, and ambient run status.
+  - `prompts.ts`, `temp.ts`: LLM-facing copy and temp cleanup.
+  - `tools.ts`: public tool family composition and reserved tool names.
+  - `tools-message.ts`: public `message` tool behavior, including run controls, branch/room routing, tool actor invocation, and delivery feedback.
+  - `tools-inspect.ts`: public `inspect` tool behavior, including recipe registry, room/session/tool/run views, and observation formatting.
+  - `tools-spawn.ts`: public `spawn` tool behavior, including actor launch, draft recipe capture, and launch diagnostics.
+  - `tools-local.ts`: saved local capability execution, generated schemas, value normalization, and async recipe launch.
+  - `tools-register.ts`: public `register_tool` behavior and schema for persisted local capability registration.
+  - `tools-response.ts`: compact model-facing responses and next-action rendering shared by public tool execution paths.
 
 ## Repo Surfaces
 
-- `/scripts/*.mjs`: Stable executables for detached/helper processes. Keep script-only release/build/glue behavior standalone when it has no plausible second consumer.
-- `/lib/*.ts`: Compiled domains and shared script-entrypoint logic. Move substantive script behavior into named domain modules only when reuse, tests, packaged JS-only execution, or clear ownership justifies it. Do not create a lib domain solely to keep a tiny script shim thin.
+- `/scripts/*.mjs`: Stable executables for detached/helper processes. Prefer self-contained script ownership; do not preemptively move script logic into `lib/` just to make scripts thin.
+- `/lib/*.ts`: Compiled reusable domains for the extension/runtime. Move script behavior into `lib/` only when it has real non-script consumers or belongs to an existing reusable domain. Packaged JS-only execution, tests, or shim neatness alone do not justify a new `lib/` domain.
 - `/recipes/*.json`: Packaged standard recipe library. Keep recipes optional, composable, policy-light, and caller-configurable.
 - `/skills/actors/SKILL.md`: Dense practical reference for operating pi-actors itself.
 - `/skills/swarm/SKILL.md`: Bundled methodology skill for multi-agent standards, strategies, and portable examples.
@@ -62,6 +72,7 @@ Pi host
 - Keep published documentation portable: use `~`, `<repo>`, or relative paths instead of machine-local absolute paths.
 - Preserve runtime output discipline because tool output flows directly into agent context.
 - Optimize every actor-facing surface for signal over volume: prefer compact state-backed hints and fewer concepts over broad explanatory prose or speculative guidance.
+- Split broad domains proactively when the current name becomes a generic bucket. Prefer concise domain names that match actual ownership. `tools.ts` is the public tool family owner; decomposed tool subdomains use `tools-<part>.ts` (`tools-message.ts`, `tools-inspect.ts`, `tools-spawn.ts`) under that family. Keep only genuinely cross-family domains unprefixed (`schema.ts`); tool-only helpers stay under `tools-*`. If a `tools-*` helper becomes reused by non-tools domains, remove the `tools-` prefix in the same slice and update ownership comments/imports so the name matches its broader responsibility. Avoid redundant internal `actor-` file prefixes in this actor-scoped package unless the file is deliberately tied to a public actor-named recipe/script/docs surface.
 - Until a stable release greater than `1.x.x`, favor context compression over compatibility shims: do not preserve legacy actor-facing names, aliases, fields, env vars, paths, or docs solely for backward compatibility when a clearer current term exists. Remove compatibility layers in the same slice that renames a concept, and record the break in `CHANGELOG.md`.
 - Keep the project lens local-first and cybernetic: agents wrap durable local capabilities as actors, then use semantic tools and messages instead of repeatedly reconstructing shell commands.
 - Design recipes as agent-callable tools: make prompts, scopes, paths, models, and policy knobs public args/defaults when the caller should decide them at invocation time.

package/BACKLOG.md

@@ -53,37 +53,6 @@ No open hotfix items.
 
 The backlog is intentionally pruned to the 20% of work most likely to deliver 80% of value for `pi-actors` as a local actor kernel. Bias toward consolidation, smaller public surface area, and reliability over new feature breadth.
 
-### M-15 Worker Stale-Claim Dogfood
-
-- Priority: Medium.
-- Status: Planned.
-- Goal: Validate and harden actor-worker v2 stale-claim visibility under intentionally stale claimed branch messages.
-- Why now: M-09 exposed `stale_claims`; real dogfood should verify the operator can diagnose stuck claimed work before adding recovery policy.
-- Direction:
-  - Create deterministic stale claimed branch inbox fixtures or smoke tests.
-  - Verify `worker-status.json`, room events, and inspect surfaces make stale claims visible.
-  - Defer auto-recovery unless workflow evidence proves it is safe.
-- Acceptance:
-  - Stale claims are reproducible and visible in worker status.
-  - Tests cover stale-claim counting without adding scheduler/broker policy.
-
-### M-17 Message Delivery Outcome Contract
-
-- Priority: High.
-- Status: Planned.
-- Goal: Normalize `message` results so operators can distinguish delivered, queued, persisted, forwarded, unsupported, and ownership-denied outcomes.
-- Why now: Branch message UX already treats durable branch mailbox persistence as a successful queued outcome when a parent endpoint is unavailable; that local fix should become a consistent message-result membrane.
-- Direction:
-  - Define compact delivery fields: `queued`, `delivered`, `persisted`, `forwarded`, `consumer`, `reason`, and `hint`.
-  - Apply the shape to `run:<id>`, `branch:<run>/<branch>`, `room:<run>`, `coordinator`, `session:`, and `tool:<name>` where meaningful.
-  - Reuse M-14 session mismatch shape for ownership-denied outcomes.
-  - Do not claim guaranteed live consumption unless a known consumer exists.
-  - Do not add a broker, distributed delivery semantics, or a new public noun.
-- Acceptance:
-  - Branch messages clearly report queued/persisted state and known worker-consumer state where available.
-  - Room messages distinguish timeline append success from forwarded branch-targeted copies.
-  - Tests cover at least run, branch, room, coordinator, and ownership-denied outcomes.
-
 ### M-18 Draft Recipe Promotion UX
 
 - Priority: High.
@@ -185,7 +154,7 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ## Suggested Milestone Order
 
 ```text
-Next milestone: M-15 Worker Stale-Claim Dogfood.
-Then: M-17 Message Delivery Outcome Contract → M-18 Draft Recipe Promotion UX.
-Small cleanup lane: M-23 Tool Boundary Type Tightening → M-24 Registry Path Naming Cleanup.
+Next milestone: M-18 Draft Recipe Promotion UX.
+Then: M-19 Recipe Doctor Risk Labels v2.
+Small cleanup lane: continue opportunistic domain polish only when a real ownership boundary appears.
 ```

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.34.1: Message Delivery Outcome Hotfix
+
+- `[Dogfood]` Added a deterministic actor-worker stale-claim smoke covering an intentionally claimed branch inbox record; the worker now reports stale claim counts in both `worker-status.json` and its awaiting-assignment room event without adding auto-recovery or scheduler policy.
+- `[Messages]` Completed the M-17 message delivery outcome contract by normalizing public message results with `delivered`, `persisted`, `queued`, `forwarded`, `consumer`, and `reason` fields across run, branch, room, coordinator, session, and tool destinations; room multicast now also exposes per-recipient branch delivery outcomes.
+- `[Backlog]` Closed M-15 Worker Stale-Claim Dogfood and M-17 Message Delivery Outcome Contract after adding delivery-result coverage for run, branch, room, coordinator, session, tool, and ownership-denied paths.
+
+## 0.34.0: Actor Kernel Domain Compression
+
+- `[Domains]` Compressed the actor kernel into explicit domain families: `tools.ts` remains the public tool-family owner while `tools-*` owns message, inspect, spawn, register, local execution, response, access, and mailbox-contract behavior; `async-runs.ts` remains the lifecycle facade while `runs-*` owns artifacts, mailbox, process control, delivery, outbox, index, retention, status, start guards, and identity internals.
+- `[Domains]` Removed redundant internal `actor-` prefixes and renamed the recipe family to plural `recipes-*`, leaving public actor-named recipe/script/docs surfaces intact while making core library ownership match the `tools-*` and `runs-*` convention.
+- `[Scripts]` Collapsed script-only runner, worker, validator, recipe-utils, locker, and coordinator library shims back into their owning `scripts/*.mjs` entrypoints; reusable lifecycle, room, mailbox-loop, command-template, and recipe-reference primitives remain in `lib/`.
+- `[Context]` Reversed the thin-script default, polished ownership headers, and kept completed script-autonomy/domain-compression work in the changelog instead of the backlog.
+- `[Tests]` Mirrored renamed domains in test filenames and extended installed-package contract coverage to ensure stale renamed lib domains are absent from `dist/lib` while packaged JS-only script execution still works.
+
 ## 0.33.0: Signal-First Compatibility Pruning
 
 - `[Breaking]` Removed pre-1.x compatibility shims for draft recipe terminology: draft captures now live under `~/.pi/agent/recipes/drafts`, recipe inspection no longer emits `candidates`, spawn details no longer emit `candidate_recipe`, and shadow diagnostics use `blocked_fallback` instead of `blocked_candidate`.

package/dist/index.js

@@ -4,9 +4,9 @@
  *
  * Wraps command templates as callable pi tools, stores durable user tools as recipe files, and exposes actor orchestration across reloads and sessions.
  */
-import * as ActorInspectorTui from "./lib/actor-inspector-tui.js";
 import * as AsyncRuns from "./lib/async-runs.js";
 import * as CommandTemplates from "./lib/command-templates.js";
+import * as Inspector from "./lib/inspector.js";
 import * as Observability from "./lib/observability.js";
 import * as Paths from "./lib/paths.js";
 import * as Pi from "./lib/pi.js";
@@ -20,7 +20,7 @@ export default function toolRegistryExtension(pi) {
     let activeRunContext;
     const runUi = Observability.createRunUiObservationState();
     const retirementAttempts = new Set();
-    const actorInspector = ActorInspectorTui.createActorInspectorControllerState();
+    const actorInspector = Inspector.createActorInspectorControllerState();
     const getRunOwnerId = Pi.getSessionId;
     const retireCandidateRuns = (ctx, summary) => {
         void Observability.executeRunRetirements(summary, {
@@ -38,7 +38,7 @@ export default function toolRegistryExtension(pi) {
             ? () => ({
                 invalidate() { },
                 render(width) {
-                    return ActorInspectorTui.renderActorInspectorPanel({
+                    return Inspector.renderActorInspectorPanel({
                         stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
                         state: actorInspector,
                         ownerId,
@@ -126,28 +126,28 @@ export default function toolRegistryExtension(pi) {
         recipeReload.close();
     });
     pi.registerCommand("actors-inspector-toggle", {
-        description: ActorInspectorTui.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.toggle,
+        description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.toggle,
         handler: async (args, ctx) => {
-            const result = ActorInspectorTui.handleActorInspectorToggle(actorInspector, args);
+            const result = Inspector.handleActorInspectorToggle(actorInspector, args);
             if (result.update)
                 updateRunUi(ctx);
             ctx.ui.notify(result.notify, result.type);
         },
     });
     pi.registerCommand("actors-inspector-filter", {
-        description: ActorInspectorTui.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.filter,
+        description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.filter,
         handler: async (args, ctx) => {
-            const result = ActorInspectorTui.handleActorInspectorFilter(actorInspector, args);
+            const result = Inspector.handleActorInspectorFilter(actorInspector, args);
             if (result.update)
                 updateRunUi(ctx);
             ctx.ui.notify(result.notify, result.type);
         },
     });
     pi.registerCommand("actors-inspect", {
-        description: ActorInspectorTui.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.inspect,
+        description: Inspector.ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS.inspect,
         handler: async (args, ctx) => {
-            const previews = ActorInspectorTui.readActorInspectorPreviews(Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, actorInspector.rows, ActorInspectorTui.getActorInspectorPreviewOptions(actorInspector, getRunOwnerId(ctx)));
-            const result = ActorInspectorTui.handleActorInspectorInspect(actorInspector, args, previews);
+            const previews = Inspector.readActorInspectorPreviews(Paths.EXTENSION_RUNTIME_PATHS.runStateRoot, actorInspector.rows, Inspector.getActorInspectorPreviewOptions(actorInspector, getRunOwnerId(ctx)));
+            const result = Inspector.handleActorInspectorInspect(actorInspector, args, previews);
             if (result.update)
                 updateRunUi(ctx);
             ctx.ui.notify(result.notify, result.type);

package/dist/lib/async-runs.d.ts

@@ -1,10 +1,14 @@
 /**
- * Command-template async run primitives
- * Zones: async runtime, lifecycle, state files
- * Owns detached run state, observation, log tailing, listing, and cancellation safety
+ * 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 * as RecipeReferences from "./recipe-references.ts";
+import * as RecipesReferences from "./recipes-references.ts";
+import { type RunArtifactDeclaration } from "./runs-artifacts.ts";
+import { type RunOutboxEvent } from "./runs-outbox.ts";
+import * as RunsIndex from "./runs-index.ts";
+import { type ProcessRunInboxResult, type RunInboxMessage, type RunInboxStatus } from "./runs-mailbox.ts";
+import { type SendRunMessageOptions } from "./runs-messages.ts";
 export type AsyncRunLaunchSource = "spawn" | "tool";
 export interface AsyncRunControlEndpoint {
     path: string;
@@ -30,7 +34,7 @@ export interface AsyncRunStartParams {
     delay?: number | string;
     output?: string;
     artifacts?: Record<string, RunArtifactDeclaration>;
-    mailbox?: RecipeReferences.TemplateRecipeMailbox;
+    mailbox?: RecipesReferences.TemplateRecipeMailbox;
     retire_when?: "children_terminal";
     retry?: number | string;
     failure?: CommandTemplateFailureScope;
@@ -41,26 +45,6 @@ export interface AsyncRunStartParams {
     cwd?: string;
 }
 export type AsyncRunStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
-export type RunOutboxDelivery = "log" | "notify" | "followup";
-export type RunOutboxLevel = "info" | "warning" | "error";
-export interface RunOutboxEvent {
-    body?: unknown;
-    correlation_id?: string;
-    data?: unknown;
-    delivery: RunOutboxDelivery;
-    event: string;
-    from?: string;
-    id: string;
-    level: RunOutboxLevel;
-    metadata?: Record<string, unknown>;
-    reply_to?: string;
-    run: string;
-    state_dir: string;
-    summary: string;
-    to?: string;
-    ts: string;
-    type?: string;
-}
 export interface AsyncRunMeta {
     argv: string[];
     createdAt: string;
@@ -78,54 +62,25 @@ export interface AsyncRunMeta {
     values: Record<string, unknown>;
     artifacts?: Record<string, RunArtifactDeclaration>;
     control?: AsyncRunControlEndpoint;
-    mailbox?: RecipeReferences.TemplateRecipeMailbox;
-    recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
+    mailbox?: RecipesReferences.TemplateRecipeMailbox;
+    recipe_context_records?: RecipesReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
 }
-export type RunArtifactDeclaration = string | {
-    path: string;
-    kind?: string;
-    media_type?: string;
-    required?: boolean;
-};
-export interface RunArtifactManifestEntry {
-    exists: boolean;
-    kind?: string;
-    media_type?: string;
-    path: string;
-    required?: boolean;
-    sha256?: string;
-    size?: number;
-}
-export declare function resolveArtifactManifest(artifacts: Record<string, RunArtifactDeclaration> | undefined): Record<string, RunArtifactManifestEntry> | undefined;
+export { safeRunId } from "./runs-identity.ts";
+export { resolveArtifactManifest } from "./runs-artifacts.ts";
+export type { RunArtifactDeclaration, RunArtifactManifestEntry, } from "./runs-artifacts.ts";
 export declare function startRun(params: AsyncRunStartParams, cwd: string): AsyncRunMeta;
-export declare function parseRunOutboxEventLine(line: string, run: string, stateDir: string, index: number): RunOutboxEvent | undefined;
+export { parseRunOutboxEventLine } from "./runs-outbox.ts";
+export type { RunOutboxDelivery, RunOutboxEvent, RunOutboxLevel, } from "./runs-outbox.ts";
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
-export interface RunStateIndexEntry {
-    ownerId?: string;
-    recipe?: string;
-    run: string;
-    state_dir: string;
-    status: AsyncRunStatus;
-    tool?: string;
-    updated_at?: string;
-}
+export type { RunStateIndexEntry } from "./runs-index.ts";
 export declare function listRunStateDirs(stateRoot?: string, depth?: number, seen?: Set<string>): string[];
-export declare function rebuildRunStateIndex(stateRoot?: string): RunStateIndexEntry[];
-export declare function readRunStateIndex(stateRoot?: string): RunStateIndexEntry[] | undefined;
+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 declare function tailRun(runOrDir: string, lines?: number): string;
 export declare function readRunEvents(runOrDir: string, lines?: number): RunOutboxEvent[];
-export type RunInboxStatus = "queued" | "sent" | "claimed" | "handled" | "failed";
-export type RunInboxMessage = Record<string, unknown> & {
-    id?: string;
-    status?: RunInboxStatus | string;
-};
-export interface ProcessRunInboxResult {
-    claimed: number;
-    failed: number;
-    handled: number;
-}
+export type { ProcessRunInboxResult, RunInboxMessage, RunInboxStatus, } from "./runs-mailbox.ts";
 export declare function readRunInboxMessages(runOrDir: string, lines?: number): RunInboxMessage[];
 export declare function updateRunInboxMessageStatus(runOrDir: string, id: string, nextStatus: RunInboxStatus, metadata?: Record<string, unknown>): boolean;
 export declare function claimRunInboxMessage(runOrDir: string, owner?: string, statuses?: string[]): RunInboxMessage | undefined;
@@ -148,17 +103,10 @@ export declare function appendRunOutboxEvent(runOrDir: string, event: {
     to?: string;
     type?: string;
 }): Record<string, unknown>;
-export interface SendRunMessageOptions {
-    namedPipeSend?: (path: string, payload: string) => Promise<number>;
-    platform?: NodeJS.Platform;
-}
+export type { SendRunMessageOptions } from "./runs-messages.ts";
 export declare function sendRunMessage(runOrDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;
-export interface RunProcessSignalPlan {
-    args?: string[];
-    command?: string;
-    signalTarget: "processGroup" | "process" | "processTree";
-}
-export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
+export { getRunProcessSignalPlan } from "./runs-control.ts";
+export type { RunProcessSignalPlan } from "./runs-control.ts";
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
 export declare function archiveRun(runOrDir: string): Record<string, unknown>;
 export declare function pruneRun(runOrDir: string, options?: {