@llblab/pi-actors 0.33.0 → 0.34.0

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

@@ -187,5 +187,5 @@ These are valid ideas but not current focus. Reintroduce only with concrete evid
 ```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.
+Small cleanup lane: continue opportunistic domain polish only when a real ownership boundary appears.
 ```

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## Unreleased
+## 0.34.0: Actor Kernel Domain Compression
+
+- `[Context]` Added a critical tools-domain split track and durable naming guidance: split broad buckets proactively, use `tool-<verb>.ts` for independent public agent-tool domains when deleting `tools.ts`, reserve `tools-<part>.ts` only for a retained `tools.ts` aggregate-root architecture, keep non-tool domains unprefixed, and avoid new `utils` or compatibility barrels when direct owned-domain imports work.
+- `[Domains]` Started the `tools.ts` split by moving JSON schema builders into `schema.ts` and compact response helpers into the tool-family response path, reducing the remaining tool bucket to public tool composition rather than generic schema ownership.
+- `[Domains]` Moved the public `message` actor tool behavior into `tools-message.ts`, including run controls, branch/room delivery, tool actor invocation, and compact delivery next actions.
+- `[Domains]` Moved shared session ownership guards and normalized mismatch diagnostics into `tools-access.ts` so public tools can share one access contract without copying ownership checks.
+- `[Domains]` Moved mailbox contract normalization and accepted/emitted type extraction into `tools-mailbox.ts`, removing duplicated mailbox metadata handling from message and inspect tool paths.
+- `[Domains]` Added `tools-response.ts` for compact public tool responses and next-action rendering shared by spawn, inspect, and registered tool paths; moved recipe registry compact summaries and doctor/import next-action rendering into it.
+- `[Domains]` Moved the public `inspect` actor tool behavior into `tools-inspect.ts`, including recipe registry inspection, room/session/tool/run views, and inspect-specific compact observation formatting.
+- `[Domains]` Moved the public `spawn` actor tool behavior into `tools-spawn.ts`, including actor launch, draft recipe capture, shadowed recipe launch diagnostics, and spawn next-action feedback.
+- `[Domains]` Removed the over-thin `tool-context.ts` extraction and kept tool execution context types local to the domains that use them.
+- `[Domains]` Moved saved local capability execution into `tools-local.ts`, including generated schemas, argument usage hints, runtime value normalization, and async recipe launch behavior.
+- `[Domains]` Moved public `register_tool` behavior into `tools-register.ts`, including the register schema and registry mutation bridge for persisted local capabilities.
+- `[Domains]` Kept `tools.ts` as the public tool-family composition owner, moved decomposed behavior into `tools-*` subdomains, removed the redundant `actor-tools.ts` prefix because this package is already actor-scoped, and documented that any `tools-*` helper reused by non-tools domains must drop the prefix in the same slice.
+- `[Domains]` Removed redundant internal `actor-` prefixes from core library domains: `inspector.ts`, `messages.ts`, `recipes-context.ts`, and `rooms.ts`; public recipe/script/docs names that intentionally expose actor terminology stay unchanged.
+- `[Scripts]` Collapsed the one-off `run-executor.ts`, `worker.ts`, `validate-recipe.ts`, `recipe-utils.ts`, `locker.ts`, and `coordinator.ts` domains into their owning scripts; reusable lifecycle, room, mailbox, and recipe-reference primitives stay in `lib/`, while public scripts own their executable control loops directly.
+- `[Domains]` Started decomposing the oversized `async-runs.ts` lifecycle aggregate into `runs-*` subdomains, moving artifact manifest handling to `runs-artifacts.ts`, durable run inbox locking/claim handling to `runs-mailbox.ts`, process-control signal helpers to `runs-control.ts`, outbox event parsing/payload formatting to `runs-outbox.ts`, run-state index discovery/rebuild logic to `runs-index.ts`, id normalization to `runs-identity.ts`, archive/prune retention behavior to `runs-retention.ts`, process identity/liveness checks to `runs-process.ts`, run message delivery to `runs-messages.ts`, status/log derivation to `runs-status.ts`, and start lock/reuse guards to `runs-start.ts` while preserving the `async-runs.ts` facade.
+- `[Context]` Reversed the thin-script default: `scripts/*.mjs` should own script-only executable behavior, and behavior should move into `lib/` only for real non-script reuse or existing reusable domain ownership; packaging/tests/shim neatness alone no longer justify a lib domain.
+- `[Context]` Polished domain ownership headers after the file moves so command templates, actor messages, rooms, recipe context, inspector previews, and mailbox loops describe their actual reasons to change without generic helper wording.
+- `[Domains]` Renamed generic `output.ts` to `execution-output.ts` so registered-tool stdout/stderr truncation and temp artifact formatting are tied to the execution domain instead of a broad output bucket.
+- `[Domains]` Renamed the recipe domain family from singular `recipe-*` to plural `recipes-*` (`recipes-references.ts`, `recipes-discovery.ts`, `recipes-usage.ts`, `recipes-context.ts`) to match the `tools-*` and `runs-*` family convention.
+- `[Tests]` Extended installed-package contract coverage to assert stale renamed lib domains are absent from `dist/lib`, keeping packaged JS output aligned with the current domain names.
 
 ## 0.33.0: Signal-First Compatibility Pruning
 

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?: {