@llblab/pi-actors 0.23.0 → 0.24.1

package/fixtures/protocol/room-message.json

@@ -0,0 +1,11 @@
+{
+  "to": "room:demo",
+  "from": "branch:demo/worker",
+  "type": "task.result",
+  "summary": "Worker completed task",
+  "body": {
+    "id": "inbox-001",
+    "result": "ok"
+  },
+  "received_at": "2026-05-26T00:00:00.000Z"
+}

package/fixtures/protocol/room-roster.json

@@ -0,0 +1,11 @@
+{
+  "room": "main",
+  "members": {
+    "branch:demo/worker": {
+      "display": "worker",
+      "role": "worker",
+      "status": "present",
+      "last_seen": "2026-05-26T00:00:00.000Z"
+    }
+  }
+}

package/fixtures/protocol/run-inbox-message.json

@@ -0,0 +1,9 @@
+{
+  "id": "inbox-001",
+  "status": "queued",
+  "queued_at": "2026-05-26T00:00:00.000Z",
+  "to": "run:demo",
+  "from": "coordinator",
+  "type": "control.continue",
+  "body": "continue"
+}

package/fixtures/protocol/run-outbox-event.json

@@ -0,0 +1,9 @@
+{
+  "id": "event-001",
+  "type": "task.result",
+  "summary": "Worker completed task",
+  "body": {
+    "result": "ok"
+  },
+  "created_at": "2026-05-26T00:00:00.000Z"
+}

package/fixtures/protocol/run-state.json

@@ -0,0 +1,10 @@
+{
+  "run": "demo",
+  "state_dir": "{state_dir}",
+  "status": "running",
+  "template": "echo demo",
+  "values": {
+    "run_id": "demo",
+    "state_dir": "{state_dir}"
+  }
+}

package/index.ts

@@ -48,6 +48,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
   const runDirWatchers = new Map<string, FSWatcher>();
   const observedRuns = new Map<string, Observability.RunObservedStatus>();
   const observedRunEventLines = new Map<string, number>();
+  const observedRunOutboxEventIds = new Map<string, Set<string>>();
   const retirementAttempts = new Set<string>();
   let runStatusFrame = 0;
   let communicationWidgetVisible = false;
@@ -152,6 +153,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     const outboxEvents = Observability.detectRunOutboxEvents(
       observedRunEventLines,
       summary,
+      observedRunOutboxEventIds,
     );
     if (!notify) return;
     retireCandidateRuns(ctx, summary);
@@ -177,6 +179,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       observedRunEventLines,
       summary,
       transitions.map((transition) => transition.stateDir ?? transition.run),
+      observedRunOutboxEventIds,
     );
     for (const event of outboxEvents) {
       if (!Observability.shouldNotifyRunOutboxEvent(event)) continue;

package/lib/actor-inspector-tui.ts

@@ -11,6 +11,7 @@ import { visibleWidth } from "@earendil-works/pi-tui";
 import type { ActorMessage } from "./actor-messages.ts";
 import * as Limits from "./limits.ts";
 import * as Paths from "./paths.ts";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.ts";
 
 export interface ActorInspectorPreview {
   body_preview?: string;
@@ -72,22 +73,7 @@ function asRecord(value: unknown): Record<string, unknown> {
 }
 
 function readJsonLines(file: string): Record<string, unknown>[] {
-  try {
-    return fs
-      .readFileSync(file, "utf8")
-      .split("\n")
-      .filter(Boolean)
-      .flatMap((line) => {
-        try {
-          return [JSON.parse(line) as Record<string, unknown>];
-        } catch {
-          return [];
-        }
-      });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-    return [];
-  }
+  return readJsonlFileResilient<Record<string, unknown>>(file).records;
 }
 
 function previewValue(
@@ -156,16 +142,10 @@ function readRoomRosterRecords(
   stateDir: string,
   room: string,
 ): Record<string, Record<string, unknown>> {
-  try {
-    return JSON.parse(
-      fs.readFileSync(
-        path.join(stateDir, "rooms", room, "roster.json"),
-        "utf8",
-      ),
-    ) as Record<string, Record<string, unknown>>;
-  } catch {
-    return {};
-  }
+  return readJsonFileResilient<Record<string, Record<string, unknown>>>(
+    path.join(stateDir, "rooms", room, "roster.json"),
+    {},
+  ).value;
 }
 
 function memberDisplay(
@@ -297,14 +277,11 @@ function readOutboxPreviews(
 }
 
 function getRunOwnerId(stateDir: string): string | undefined {
-  try {
-    const meta = JSON.parse(
-      fs.readFileSync(path.join(stateDir, "run.json"), "utf8"),
-    ) as Record<string, unknown>;
-    return typeof meta.ownerId === "string" ? meta.ownerId : undefined;
-  } catch {
-    return undefined;
-  }
+  const meta = readJsonFileResilient<Record<string, unknown> | undefined>(
+    path.join(stateDir, "run.json"),
+    undefined,
+  ).value;
+  return typeof meta?.ownerId === "string" ? meta.ownerId : undefined;
 }
 
 function matchesOwner(stateDir: string, ownerId: string | undefined): boolean {

package/lib/actor-rooms.ts

@@ -11,6 +11,11 @@ import * as path from "node:path";
 import type { ActorMessage } from "./actor-messages.ts";
 import * as Limits from "./limits.ts";
 import { notifyRuntimeWake } from "./runtime-notifier.ts";
+import {
+  formatStateReadDiagnostics,
+  readJsonFileResilient,
+  readJsonlFileResilient,
+} from "./state-readers.ts";
 
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
@@ -63,6 +68,8 @@ export interface RoomStatus {
   message_count: number;
   roster_count: number;
   compaction?: RoomCompactionInfo;
+  diagnostics?: string[];
+  diagnostics_count?: number;
   last_message_at?: string;
   last_message_from?: string;
   last_message_summary?: string;
@@ -194,12 +201,7 @@ function runFromRoomAddress(address: string): string | undefined {
 }
 
 function readJsonFile<T>(file: string, fallback: T): T {
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return fallback;
-    throw error;
-  }
+  return readJsonFileResilient<T>(file, fallback).value;
 }
 
 function writeJsonFile(file: string, value: unknown): void {
@@ -460,6 +462,11 @@ function updateRosterForMessage(
 }
 
 export interface BranchInboxRecord extends ActorMessage {
+  claimed_at?: string;
+  claimed_by?: string;
+  error?: string;
+  failed_at?: string;
+  handled_at?: string;
   id?: string;
   queued_at?: string;
   status?: string;
@@ -589,6 +596,49 @@ export function appendBranchInboxMessage(
   }
 }
 
+export function claimBranchInboxMessage(
+  stateDir: string,
+  run: string,
+  address: string,
+  owner = "runtime",
+  statuses: string[] = ["queued"],
+): BranchInboxRecord | undefined {
+  const branch = branchIdFromAddress(address, run);
+  if (!branch)
+    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  const releaseLock = acquireBranchInboxLock(stateDir, branch);
+  try {
+    const file = branchInboxFile(stateDir, branch);
+    const records = readAllBranchInboxLines(stateDir, run, address);
+    let claimed: BranchInboxRecord | undefined;
+    const now = new Date().toISOString();
+    const updated = records.map((record) => {
+      if (claimed || !("message" in record)) return record;
+      const status = record.message.status ?? "queued";
+      if (!statuses.includes(status)) return record;
+      claimed = {
+        ...record.message,
+        claimed_at: now,
+        claimed_by: owner,
+        status: "claimed",
+      };
+      return { message: claimed };
+    });
+    if (!claimed) return undefined;
+    fs.writeFileSync(
+      file,
+      `${updated.map((record) => ("raw" in record ? record.raw : JSON.stringify(record.message))).join("\n")}\n`,
+    );
+    notifyActorWake(stateDir, address, "branch.inbox.claim", {
+      id: claimed.id,
+      owner,
+    });
+    return claimed;
+  } finally {
+    releaseLock();
+  }
+}
+
 export function updateBranchInboxMessageStatus(
   stateDir: string,
   run: string,
@@ -682,7 +732,13 @@ export function readRoomMessages(
 ): RoomTimelineEntry[] {
   try {
     const lines = readJsonlTailLines(messagesFile(stateDir, room), limit);
-    return lines.map((line) => JSON.parse(line));
+    return lines.flatMap((line) => {
+      try {
+        return [JSON.parse(line) as RoomTimelineEntry];
+      } catch {
+        return [];
+      }
+    });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
     throw error;
@@ -722,10 +778,22 @@ export function readRoomMessagePreviews(
 export function getRoomStatus(stateDir: string, room: string): RoomStatus {
   const messageCount = readRoomMessageCount(stateDir, room);
   const [last] = readRoomMessages(stateDir, room, 1);
-  const compaction = readJsonFile<RoomCompactionInfo | undefined>(
+  const compactionRead = readJsonFileResilient<RoomCompactionInfo | undefined>(
     path.join(roomDir(stateDir, room), "compaction.json"),
     undefined,
   );
+  const rosterRead = readJsonFileResilient<Record<string, RoomMember>>(
+    rosterFile(stateDir, room),
+    {},
+  );
+  const messageRead = readJsonlFileResilient<RoomTimelineEntry>(
+    messagesFile(stateDir, room),
+  );
+  const diagnostics = [
+    ...messageRead.diagnostics,
+    ...rosterRead.diagnostics,
+    ...compactionRead.diagnostics,
+  ];
   return {
     ...(last
       ? {
@@ -735,10 +803,16 @@ export function getRoomStatus(stateDir: string, room: string): RoomStatus {
           last_message_type: last.type,
         }
       : {}),
-    ...(compaction ? { compaction } : {}),
+    ...(compactionRead.value ? { compaction: compactionRead.value } : {}),
+    ...(diagnostics.length
+      ? {
+          diagnostics: formatStateReadDiagnostics(diagnostics),
+          diagnostics_count: diagnostics.length,
+        }
+      : {}),
     message_count: messageCount,
     room,
-    roster_count: Object.keys(readRoomRoster(stateDir, room)).length,
+    roster_count: Object.keys(rosterRead.value).length,
   };
 }
 
@@ -785,14 +859,10 @@ export function ensureDefaultRoom(
 export function readCommunicationSnapshot(
   stateDir: string,
 ): ActorCommunicationSnapshot | undefined {
-  try {
-    return JSON.parse(
-      fs.readFileSync(snapshotFile(stateDir), "utf8"),
-    ) as ActorCommunicationSnapshot;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-    throw error;
-  }
+  return readJsonFileResilient<ActorCommunicationSnapshot | undefined>(
+    snapshotFile(stateDir),
+    undefined,
+  ).value;
 }
 
 export function readRoomContacts(

package/lib/actor-worker.ts

@@ -0,0 +1,118 @@
+/**
+ * Canonical mailbox-backed actor worker entrypoint logic.
+ * Zones: worker demo, mailbox loop recipe runtime
+ */
+
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { appendRoomMessage, ensureRoomMember } from "./actor-rooms.ts";
+import { handleMailboxLoopOnce, isMailboxLoopStopMessage } from "./mailbox-loop.ts";
+
+interface ActorWorkerArgs {
+  branch?: string;
+  poll_ms?: string | number;
+  run?: string;
+  state_dir?: string;
+}
+
+export function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs {
+  const args: Record<string, string | true> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2).replaceAll("-", "_");
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    index += 1;
+  }
+  return args as ActorWorkerArgs;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+export async function runActorWorker(argv = process.argv.slice(2)): Promise<void> {
+  const args = parseActorWorkerArgs(argv);
+  const stateDir = String(args.state_dir ?? "");
+  const run = String(args.run ?? "");
+  const branch = String(args.branch ?? "worker");
+  const pollMs = Math.max(50, Number(args.poll_ms ?? 1000));
+
+  if (!stateDir || !run) {
+    throw new Error("usage: actor-worker.mjs --state-dir <dir> --run <id> [--branch worker] [--poll-ms 1000]");
+  }
+
+  const branchAddress = `branch:${run}/${branch}`;
+  const roomAddress = `room:${run}`;
+  const journalPath = join(stateDir, "worker-events.jsonl");
+
+  function journal(event: string, data: Record<string, unknown> = {}): void {
+    appendFileSync(
+      journalPath,
+      `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`,
+    );
+  }
+
+  function room(type: string, summary: string, body: Record<string, unknown> = {}): void {
+    appendRoomMessage(stateDir, "main", {
+      body,
+      from: branchAddress,
+      summary,
+      to: roomAddress,
+      type,
+    });
+  }
+
+  ensureRoomMember(
+    stateDir,
+    run,
+    "main",
+    branchAddress,
+    { display: branch, role: "worker", status: "present" },
+    `${branch} joined as mailbox worker`,
+  );
+  room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+  journal("worker.started", { branch, run });
+
+  let stopping = false;
+  while (!stopping) {
+    const result = await handleMailboxLoopOnce(
+      { address: branchAddress, kind: "branch", run, stateDir },
+      (message) => {
+        if (isMailboxLoopStopMessage(message)) {
+          stopping = true;
+          room("actor.leave", `${branch} stopping`, { branch, reason: message.type });
+          journal("worker.stopping", { id: message.id, type: message.type });
+          return;
+        }
+        room("task.claim", `${branch} claimed ${message.type}`, {
+          branch,
+          id: message.id,
+          type: message.type,
+        });
+        room("task.result", `${branch} handled ${message.type}`, {
+          branch,
+          id: message.id,
+          result: text(message.body),
+          type: message.type,
+        });
+        room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+        journal("task.handled", { id: message.id, type: message.type });
+      },
+      { owner: branchAddress },
+    );
+    if (!result.handled) await sleep(pollMs);
+  }
+
+  journal("worker.done", { branch, run });
+}

package/lib/async-runner.ts

@@ -0,0 +1,173 @@
+/**
+ * Detached async-runner entrypoint logic.
+ * Zones: async run process, command-template execution telemetry
+ */
+
+import { appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { appendRecipeContextToPiArgs } from "./actor-recipe-context.ts";
+import { execCommandTemplate } from "./command-templates.ts";
+import { executeRegisteredTool, type ToolExecOptions } from "./execution.ts";
+import { writeJsonAtomic } from "./file-state.ts";
+
+function quoteCommandDetailPart(value: string): string {
+  if (value === "") return "''";
+  if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value)) return value;
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function formatCommandDetail(command: string, args: string[]): string {
+  return [command, ...args].map(quoteCommandDetailPart).join(" ");
+}
+
+function summarizeCommandDetail(commandDetail: string): string {
+  return commandDetail.length > 160
+    ? `${commandDetail.slice(0, 157)}...`
+    : commandDetail;
+}
+
+export async function runAsyncRunner(stateDir = process.argv[2]): Promise<void> {
+  if (!stateDir) throw new Error("missing state dir");
+
+  const runPath = join(stateDir, "run.json");
+  const progressPath = join(stateDir, "progress.json");
+  const resultPath = join(stateDir, "result.json");
+  const eventsPath = join(stateDir, "events.jsonl");
+  const outboxPath = join(stateDir, "outbox.jsonl");
+  const stdoutPath = join(stateDir, "stdout.log");
+  const stderrPath = join(stateDir, "stderr.log");
+  const meta = JSON.parse(readFileSync(runPath, "utf8"));
+
+  function event(name: string, data: Record<string, unknown> = {}): void {
+    appendFileSync(
+      eventsPath,
+      `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`,
+    );
+  }
+
+  function outbox(
+    name: string,
+    summary: string,
+    data: Record<string, unknown> = {},
+    delivery = "log",
+    level = "info",
+  ): void {
+    appendFileSync(
+      outboxPath,
+      `${JSON.stringify({ body: data, data, delivery, event: name, from: `run:${meta.run}`, level, summary, to: "coordinator", ts: new Date().toISOString(), type: name })}\n`,
+    );
+  }
+
+  function progress(phase: string, extra: Record<string, unknown> = {}): void {
+    writeJsonAtomic(progressPath, {
+      phase,
+      updatedAt: new Date().toISOString(),
+      ...extra,
+    });
+  }
+
+  let activeSubagents = 0;
+  let completedSubagents = 0;
+  const subagentFailures: Record<string, unknown>[] = [];
+
+  function getCommandDoneDelivery(result: { code: number }): string {
+    return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
+  }
+
+  function progressRunning(): void {
+    progress("running", {
+      activeSubagents,
+      completed: completedSubagents,
+      failures: subagentFailures,
+    });
+  }
+
+  async function observedExec(command: string, args: string[], options?: ToolExecOptions) {
+    const commandDetail = formatCommandDetail(command, args);
+    const execArgs = appendRecipeContextToPiArgs(
+      command,
+      args,
+      meta.recipe_context_records,
+      options?.actorRecipeContext,
+    );
+    activeSubagents += 1;
+    event("command.start", { activeSubagents, command: commandDetail });
+    progressRunning();
+    const result = await execCommandTemplate(command, execArgs, options);
+    activeSubagents = Math.max(0, activeSubagents - 1);
+    completedSubagents += 1;
+    if (result.code !== 0) {
+      subagentFailures.push({
+        code: result.code,
+        command: commandDetail,
+        killed: result.killed,
+      });
+    }
+    event("command.done", {
+      activeSubagents,
+      code: result.code,
+      command: commandDetail,
+      killed: result.killed,
+    });
+    outbox(
+      "command.done",
+      `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`,
+      {
+        activeSubagents,
+        ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
+        run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
+        code: result.code,
+        command: commandDetail,
+        killed: result.killed,
+      },
+      getCommandDoneDelivery(result),
+      result.code === 0 ? "info" : "error",
+    );
+    progressRunning();
+    return result;
+  }
+
+  try {
+    event("run.runner.start", { pid: process.pid });
+    progressRunning();
+    const result = await executeRegisteredTool(
+      {
+        name: "run_actor",
+        description: "Detached command-template run actor",
+        template: meta.template,
+        args: [],
+        defaults: {},
+      },
+      meta.values || {},
+      observedExec,
+      meta.cwd,
+    );
+    const text = result.content?.[0]?.text || "";
+    appendFileSync(stdoutPath, text);
+    writeJsonAtomic(resultPath, {
+      code: result.details.code,
+      command: result.details.command,
+      killed: result.details.killed,
+      truncated: result.details.truncated,
+      completedAt: new Date().toISOString(),
+    });
+    progress("done", {
+      completed: 1,
+      failures: result.details.nonCriticalFailures || [],
+    });
+    event("run.done", { code: result.details.code });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    appendFileSync(stderrPath, `${message}\n`);
+    writeJsonAtomic(resultPath, {
+      code: 1,
+      error: message,
+      killed: false,
+      completedAt: new Date().toISOString(),
+    });
+    progress("failed", { completed: 0, failures: [{ message }] });
+    event("run.failed", { error: message });
+    throw error;
+  }
+}

package/lib/async-runs.ts

@@ -33,6 +33,7 @@ import type {
 } from "./command-templates.ts";
 import { substituteCommandTemplateToken } from "./command-templates.ts";
 import { writeJsonAtomic } from "./file-state.ts";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.ts";
 import * as Paths from "./paths.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as RecipeUsage from "./recipe-usage.ts";
@@ -345,11 +346,10 @@ function resolveStartParams(params: AsyncRunStartParams): AsyncRunStartParams {
 }
 
 function readJson(path: string): Record<string, unknown> | undefined {
-  try {
-    return JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
-  } catch {
-    return undefined;
-  }
+  return readJsonFileResilient<Record<string, unknown> | undefined>(
+    path,
+    undefined,
+  ).value;
 }
 
 function isAlive(pid: number): boolean {
@@ -392,16 +392,12 @@ function tailLines(path: string, lines: number): string[] {
 function getInterruptedRunStatus(
   stateDir: string,
 ): "cancelled" | "killed" | undefined {
-  const events = tailFile(join(stateDir, "events.jsonl"), 200);
-  if (!events) return undefined;
-  for (const line of events.split("\n").reverse()) {
-    try {
-      const event = JSON.parse(line) as Record<string, unknown>;
-      if (event.event === "run.kill") return "killed";
-      if (event.event === "run.cancel") return "cancelled";
-    } catch {
-      // Ignore malformed event lines.
-    }
+  const events = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "events.jsonl"),
+  ).records.slice(-200);
+  for (const event of events.reverse()) {
+    if (event.event === "run.kill") return "killed";
+    if (event.event === "run.cancel") return "cancelled";
   }
   return undefined;
 }
@@ -913,13 +909,7 @@ function parseRunInboxLine(line: string): RunInboxMessage | undefined {
 }
 
 function readRunInboxMessagesFromStateDir(stateDir: string): RunInboxMessage[] {
-  const file = runInboxFile(stateDir);
-  if (!existsSync(file)) return [];
-  return readFileSync(file, "utf8")
-    .split("\n")
-    .filter((line) => line.trim())
-    .map(parseRunInboxLine)
-    .filter((message): message is RunInboxMessage => Boolean(message));
+  return readJsonlFileResilient<RunInboxMessage>(runInboxFile(stateDir)).records;
 }
 
 function writeRunInboxMessages(