@llblab/pi-actors 0.32.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/candidate 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 executable shims for detached/helper processes.
-- `/lib/*.ts`: Compiled domain and script-entrypoint logic. Keep `scripts/*.mjs` lightweight and move substantive behavior into named domain modules so `dist/lib` is the JS-only runtime surface. This intentionally grows a standard library: script-born behavior should gain a clear domain name when reuse is plausible. Exception: self-contained application/build scripts with no expected second consumer, such as `music-player.mjs` or `build-dist.mjs`, may remain standalone `.mjs` files.
+- `/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,8 @@ 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.
 - Decompose oversized bullets into sublists or hierarchy; long flat list items are a context-smell.

package/BACKLOG.md

@@ -67,20 +67,6 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Stale claims are reproducible and visible in worker status.
   - Tests cover stale-claim counting without adding scheduler/broker policy.
 
-### M-23 Tool Boundary Type Tightening
-
-- Priority: Low.
-- Status: Planned.
-- Goal: Remove avoidable `any` at the Pi/tool boundary where a narrow local type can express the real contract without broad rewiring.
-- Why now: `index.ts` still keeps runtime tool definitions in a `Map<string, any>`; this is small but visible in the composition root.
-- Direction:
-  - Add or reuse a narrow exported tool-definition type from the Pi adapter or tools domain.
-  - Keep SDK details behind `lib/pi.ts`.
-  - Do not introduce a broad type-modeling pass across every schema helper.
-- Acceptance:
-  - `index.ts` no longer uses `Map<string, any>` for actor tool definitions.
-  - TypeScript validation still passes without weakening public tool schemas.
-
 ### M-17 Message Delivery Outcome Contract
 
 - Priority: High.
@@ -103,7 +89,7 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
 - Priority: High.
 - Status: Planned.
 - Goal: Make successful ad hoc actor patterns easy to promote manually from draft memory into active user recipe memory.
-- Why now: Draft recipes under `~/.pi/agent/recipes/candidates` are replayable but intentionally not active tools; the directory name is retained for compatibility, and the two-stage memory model now needs an explicit operator-gated promotion path.
+- Why now: Draft recipes under `~/.pi/agent/recipes/drafts` are replayable but intentionally not active tools, and the two-stage memory model needs an explicit operator-gated promotion path.
 - Direction:
   - List draft recipes with source run, timestamp, fingerprint, description/template preview, and validation status.
   - Promote a selected draft to `~/.pi/agent/recipes/<name>.json` only through an explicit action or explicit tool argument.
@@ -116,20 +102,6 @@ The backlog is intentionally pruned to the 20% of work most likely to deliver 80
   - Tests cover valid promotion, invalid draft, name collision, and packaged-recipe shadowing.
   - Docs explain draft memory vs active tool memory in one compact section.
 
-### M-24 Registry Path Naming Cleanup
-
-- Priority: Low.
-- Status: Planned.
-- Goal: Reduce legacy-storage naming noise without changing the persistent file path.
-- Why now: `legacy-tool-registry.json` is still a compatibility storage path, but helper names and tests should make clear that the stable path is retained intentionally.
-- Direction:
-  - Prefer neutral helper/test wording such as registry path or retained registry storage path.
-  - Keep the on-disk filename unchanged unless a separate migration is justified.
-  - Do not reintroduce legacy migration code.
-- Acceptance:
-  - Path helpers and tests no longer imply an unfinished migration.
-  - Existing registry storage compatibility remains unchanged.
-
 ### M-19 Recipe Doctor Risk Labels v2
 
 - Priority: Medium.
@@ -215,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,35 @@
 # 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
+
+- `[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`.
+- `[Context]` Documented the pre-stable policy that context compression wins over compatibility aliases until after a stable release greater than `1.x.x`; rename slices should remove legacy actor-facing names, fields, env vars, paths, and docs instead of carrying shims.
+- `[Breaking]` Renamed retained registry storage from `legacy-tool-registry.json` to `tool-registry.json`, removing the stale compatibility noun from runtime path helpers and tests.
+- `[Types]` Added a narrow actor tool-definition type and removed the remaining `Map<string, any>` from the composition root without expanding SDK type exposure.
+- `[Scripts]` Collapsed the conformance runner back into a standalone script and removed its one-off lib domain, documenting that script-only glue should stay self-contained unless reuse or packaged runtime constraints justify a domain.
 
 ## 0.32.0: Actor Surface Minimization
 

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