@llblab/pi-actors 0.22.5 → 0.24.0

package/lib/actor-rooms.ts

@@ -9,7 +9,13 @@ import { randomUUID } from "node:crypto";
 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;
@@ -49,10 +55,21 @@ export interface RoomMessagePreview {
   type: string;
 }
 
+export interface RoomCompactionInfo {
+  compacted_at: string;
+  dropped_count: number;
+  first_kept_at?: string;
+  last_kept_at?: string;
+  max_messages: number;
+}
+
 export interface RoomStatus {
   room: string;
   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;
@@ -105,7 +122,10 @@ function branchInboxFile(stateDir: string, branch: string): string {
   return path.join(stateDir, "branches", branch, "inbox.jsonl");
 }
 
-function branchIdFromAddress(address: string | undefined, run: string): string | undefined {
+function branchIdFromAddress(
+  address: string | undefined,
+  run: string,
+): string | undefined {
   if (!address) return undefined;
   const match = new RegExp(`^branch:${run}/(.+)$`).exec(address);
   return match?.[1];
@@ -119,7 +139,11 @@ function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
-function acquireStateLock(parentDir: string, name: string, label: string): () => void {
+function acquireStateLock(
+  parentDir: string,
+  name: string,
+  label: string,
+): () => void {
   fs.mkdirSync(parentDir, { recursive: true });
   const lockDir = path.join(parentDir, name);
   const started = Date.now();
@@ -150,11 +174,19 @@ function acquireStateLock(parentDir: string, name: string, label: string): () =>
 }
 
 function acquireRoomLock(stateDir: string, room: string): () => void {
-  return acquireStateLock(roomDir(stateDir, room), ".append.lock", `Room append ${room}`);
+  return acquireStateLock(
+    roomDir(stateDir, room),
+    ".append.lock",
+    `Room append ${room}`,
+  );
 }
 
 function acquireBranchInboxLock(stateDir: string, branch: string): () => void {
-  return acquireStateLock(path.dirname(branchInboxFile(stateDir, branch)), ".inbox.lock", `Branch inbox ${branch}`);
+  return acquireStateLock(
+    path.dirname(branchInboxFile(stateDir, branch)),
+    ".inbox.lock",
+    `Branch inbox ${branch}`,
+  );
 }
 
 function asRecord(value: unknown): Record<string, unknown> {
@@ -169,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 {
@@ -201,7 +228,10 @@ function positiveEnvInt(name: string, fallback: number): number {
 }
 
 function roomMaxMessages(): number {
-  return positiveEnvInt("PI_ACTORS_ROOM_MAX_MESSAGES", DEFAULT_ROOM_MAX_MESSAGES);
+  return positiveEnvInt(
+    "PI_ACTORS_ROOM_MAX_MESSAGES",
+    DEFAULT_ROOM_MAX_MESSAGES,
+  );
 }
 
 function snapshotMinIntervalMs(): number {
@@ -225,8 +255,22 @@ function compactRoomMessages(stateDir: string, room: string): void {
   if (lines.length <= maxMessages) return;
   const kept = lines.slice(-maxMessages);
   fs.writeFileSync(file, `${kept.join("\n")}\n`);
+  const keptMessages = kept.flatMap((line) => {
+    try {
+      return [JSON.parse(line) as RoomTimelineEntry];
+    } catch {
+      return [];
+    }
+  });
   writeJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), {
     compacted_at: new Date().toISOString(),
+    dropped_count: lines.length - kept.length,
+    ...(keptMessages[0]?.received_at
+      ? { first_kept_at: keptMessages[0].received_at }
+      : {}),
+    ...(keptMessages.at(-1)?.received_at
+      ? { last_kept_at: keptMessages.at(-1)?.received_at }
+      : {}),
     max_messages: maxMessages,
   });
 }
@@ -242,7 +286,13 @@ function readJsonlLineCount(file: string): number {
     let count = 0;
     let lastByte: number | undefined;
     while (position < stat.size) {
-      const bytesRead = fs.readSync(fd, chunk, 0, Math.min(chunkSize, stat.size - position), position);
+      const bytesRead = fs.readSync(
+        fd,
+        chunk,
+        0,
+        Math.min(chunkSize, stat.size - position),
+        position,
+      );
       if (bytesRead <= 0) break;
       position += bytesRead;
       for (let index = 0; index < bytesRead; index += 1) {
@@ -299,7 +349,10 @@ export function readRoomRoster(
   stateDir: string,
   room: string,
 ): Record<string, RoomMember> {
-  return readJsonFile<Record<string, RoomMember>>(rosterFile(stateDir, room), {});
+  return readJsonFile<Record<string, RoomMember>>(
+    rosterFile(stateDir, room),
+    {},
+  );
 }
 
 function writeRoomRoster(
@@ -353,29 +406,54 @@ function updateRosterForMessage(
   if (!message.from) return roster;
   const body = asRecord(message.body);
   const current = roster[message.from];
-  const next = message.type === "actor.leave"
-    ? {
-        address: message.from,
-        joined_at: current?.joined_at ?? receivedAt,
-        last_seen: receivedAt,
-        ...(current?.caps !== undefined ? { caps: current.caps } : {}),
-        ...(current?.claim !== undefined ? { claim: current.claim } : {}),
-        ...(current?.display !== undefined ? { display: current.display } : {}),
-        ...(current?.parent !== undefined ? { parent: current.parent } : {}),
-        ...(current?.role !== undefined ? { role: current.role } : { role: "actor" }),
-        status: String(body.status ?? "left"),
-      }
-    : {
-        address: message.from,
-        joined_at: current?.joined_at ?? receivedAt,
-        last_seen: receivedAt,
-        ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
-        ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
-        ...(body.display !== undefined ? { display: body.display } : current?.display !== undefined ? { display: current.display } : {}),
-        ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
-        ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
-        status: String(body.status ?? current?.status ?? "present"),
-      };
+  const next =
+    message.type === "actor.leave"
+      ? {
+          address: message.from,
+          joined_at: current?.joined_at ?? receivedAt,
+          last_seen: receivedAt,
+          ...(current?.caps !== undefined ? { caps: current.caps } : {}),
+          ...(current?.claim !== undefined ? { claim: current.claim } : {}),
+          ...(current?.display !== undefined
+            ? { display: current.display }
+            : {}),
+          ...(current?.parent !== undefined ? { parent: current.parent } : {}),
+          ...(current?.role !== undefined
+            ? { role: current.role }
+            : { role: "actor" }),
+          status: String(body.status ?? "left"),
+        }
+      : {
+          address: message.from,
+          joined_at: current?.joined_at ?? receivedAt,
+          last_seen: receivedAt,
+          ...(body.caps !== undefined
+            ? { caps: body.caps }
+            : current?.caps !== undefined
+              ? { caps: current.caps }
+              : {}),
+          ...(body.claim !== undefined
+            ? { claim: body.claim }
+            : current?.claim !== undefined
+              ? { claim: current.claim }
+              : {}),
+          ...(body.display !== undefined
+            ? { display: body.display }
+            : current?.display !== undefined
+              ? { display: current.display }
+              : {}),
+          ...(body.parent !== undefined
+            ? { parent: body.parent }
+            : current?.parent !== undefined
+              ? { parent: current.parent }
+              : {}),
+          ...(body.role !== undefined
+            ? { role: body.role }
+            : current?.role !== undefined
+              ? { role: current.role }
+              : { role: "actor" }),
+          status: String(body.status ?? current?.status ?? "present"),
+        };
   roster[message.from] = next;
   if (shouldWriteRoomRosterMember(stateDir, room, current, next)) {
     writeRoomRoster(stateDir, room, roster);
@@ -384,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;
@@ -401,7 +484,8 @@ function readBranchInboxFile(
   limit = 40,
 ): BranchInboxReadResult {
   const branch = branchIdFromAddress(address, run);
-  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  if (!branch)
+    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
   try {
     const lines = readJsonlTailLines(branchInboxFile(stateDir, branch), limit);
     const messages: BranchInboxRecord[] = [];
@@ -415,7 +499,8 @@ function readBranchInboxFile(
     }
     return { corrupted, messages };
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { corrupted: 0, messages: [] };
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return { corrupted: 0, messages: [] };
     throw error;
   }
 }
@@ -426,7 +511,8 @@ function readAllBranchInboxLines(
   address: string,
 ): Array<{ raw: string } | { message: BranchInboxRecord }> {
   const branch = branchIdFromAddress(address, run);
-  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  if (!branch)
+    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
   try {
     const content = fs.readFileSync(branchInboxFile(stateDir, branch), "utf8");
     return content
@@ -464,7 +550,9 @@ export function readBranchInboxDiagnostics(
 }
 
 export function getBranchInboxTerminalRetainLimit(): number {
-  const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
+  const value = Number(
+    process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "",
+  );
   return Number.isInteger(value) && value >= 0
     ? value
     : DEFAULT_BRANCH_INBOX_TERMINAL_RETAINED;
@@ -490,7 +578,8 @@ export function appendBranchInboxMessage(
   message: ActorMessage,
 ): void {
   const branch = branchIdFromAddress(address, run);
-  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  if (!branch)
+    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
   const releaseLock = acquireBranchInboxLock(stateDir, branch);
   try {
     fs.writeFileSync(
@@ -507,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,
@@ -516,7 +648,8 @@ export function updateBranchInboxMessageStatus(
   metadata: Record<string, unknown> = {},
 ): boolean {
   const branch = branchIdFromAddress(address, run);
-  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  if (!branch)
+    throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
   const releaseLock = acquireBranchInboxLock(stateDir, branch);
   try {
     const file = branchInboxFile(stateDir, branch);
@@ -526,11 +659,22 @@ export function updateBranchInboxMessageStatus(
     const updated = records.map((record) => {
       if (!("message" in record) || record.message.id !== id) return record;
       changed = true;
-      return { message: { ...record.message, ...metadata, [timestampKey]: new Date().toISOString(), status } };
+      return {
+        message: {
+          ...record.message,
+          ...metadata,
+          [timestampKey]: new Date().toISOString(),
+          status,
+        },
+      };
     });
     if (!changed) return false;
-    const validMessages = updated.flatMap((record) => "message" in record ? [record.message] : []);
-    const compactedIds = new Set(compactBranchInboxMessages(validMessages).map((message) => message.id));
+    const validMessages = updated.flatMap((record) =>
+      "message" in record ? [record.message] : [],
+    );
+    const compactedIds = new Set(
+      compactBranchInboxMessages(validMessages).map((message) => message.id),
+    );
     const lines = updated.flatMap((record) => {
       if ("raw" in record) return [record.raw];
       if (record.message.id && !compactedIds.has(record.message.id)) return [];
@@ -553,7 +697,10 @@ export function appendRoomMessage(
   try {
     const receivedAt = new Date().toISOString();
     const entry: RoomTimelineEntry = { ...message, received_at: receivedAt };
-    fs.appendFileSync(messagesFile(stateDir, room), `${JSON.stringify(entry)}\n`);
+    fs.appendFileSync(
+      messagesFile(stateDir, room),
+      `${JSON.stringify(entry)}\n`,
+    );
     compactRoomMessages(stateDir, room);
     const roster = updateRosterForMessage(stateDir, room, message, receivedAt);
     const run = runFromRoomAddress(message.to);
@@ -585,14 +732,23 @@ 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;
   }
 }
 
-function previewValue(value: unknown, maxLength = 120): string | undefined {
+function previewValue(
+  value: unknown,
+  maxLength = Limits.ROOM_MESSAGE_PREVIEW_CHARS,
+): string | undefined {
   if (value === undefined) return undefined;
   const text = typeof value === "string" ? value : JSON.stringify(value);
   const compact = text.replaceAll(/\s+/g, " ").trim();
@@ -608,7 +764,9 @@ export function readRoomMessagePreviews(
   limit = 40,
 ): RoomMessagePreview[] {
   return readRoomMessages(stateDir, room, limit).map((message) => ({
-    ...(previewValue(message.body) ? { body_preview: previewValue(message.body) } : {}),
+    ...(previewValue(message.body)
+      ? { body_preview: previewValue(message.body) }
+      : {}),
     ...(message.from ? { from: message.from } : {}),
     ...(message.summary ? { summary: message.summary } : {}),
     timestamp: message.received_at,
@@ -620,6 +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 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
       ? {
@@ -629,9 +803,16 @@ export function getRoomStatus(stateDir: string, room: string): RoomStatus {
           last_message_type: last.type,
         }
       : {}),
+    ...(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,
   };
 }
 
@@ -661,7 +842,10 @@ export function ensureRoomMember(
   });
 }
 
-export function ensureDefaultRoom(stateDir: string, run: string): RoomAppendResult {
+export function ensureDefaultRoom(
+  stateDir: string,
+  run: string,
+): RoomAppendResult {
   return ensureRoomMember(
     stateDir,
     run,
@@ -675,14 +859,10 @@ export function ensureDefaultRoom(stateDir: string, run: string): RoomAppendResu
 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(
@@ -753,6 +933,7 @@ function writeBranchCommunicationSnapshotDebounced(
 ): ActorCommunicationSnapshot | undefined {
   const branch = branchIdFromAddress(self, run);
   if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
-  if (shouldDebounceSnapshot(branchSnapshotFile(stateDir, branch))) return undefined;
+  if (shouldDebounceSnapshot(branchSnapshotFile(stateDir, branch)))
+    return undefined;
   return writeBranchCommunicationSnapshot(stateDir, run, self);
 }

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 });
+}