@llblab/pi-actors 0.22.5 → 0.24.0

package/dist/fixtures/protocol/mailbox-contract.json

@@ -0,0 +1,15 @@
+{
+  "accepts": [
+    "task.assign",
+    {
+      "type": "control.stop",
+      "description": "Request graceful worker shutdown"
+    }
+  ],
+  "emits": [
+    "task.claim",
+    "task.result",
+    "awaiting_assignment",
+    "actor.leave"
+  ]
+}

package/dist/fixtures/protocol/recipe-summary.json

@@ -0,0 +1,16 @@
+{
+  "id": "actor-worker",
+  "path": "recipes/actor-worker.json",
+  "location": "packaged",
+  "active": true,
+  "args": [
+    "run",
+    "branch",
+    "poll_ms",
+    "state_dir"
+  ],
+  "mailbox": {
+    "kind": "branch",
+    "accepts": ["task.assign", "control.stop"]
+  }
+}

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/index.js

@@ -39,6 +39,7 @@ export default function toolRegistryExtension(pi) {
     const runDirWatchers = new Map();
     const observedRuns = new Map();
     const observedRunEventLines = new Map();
+    const observedRunOutboxEventIds = new Map();
     const retirementAttempts = new Set();
     let runStatusFrame = 0;
     let communicationWidgetVisible = false;
@@ -49,6 +50,7 @@ export default function toolRegistryExtension(pi) {
     let actorInspectorUnreadOnly = false;
     let actorInspectorRoomLimitPerRun = 12;
     let selectedInspectorSequence;
+    const actorInspectorReadKeys = new Set();
     let recipeWatcherFailureNotified = false;
     const getRunOwnerId = (ctx) => ctx.sessionManager.getSessionId();
     const retireCandidateRuns = (ctx, summary) => {
@@ -84,6 +86,7 @@ export default function toolRegistryExtension(pi) {
                             branch: actorInspectorBranch,
                             mention: actorInspectorMention,
                             ownerId,
+                            readKeys: actorInspectorReadKeys,
                             roomLimitPerRun: actorInspectorRoomLimitPerRun,
                             unreadOnly: actorInspectorUnreadOnly,
                         });
@@ -100,7 +103,7 @@ export default function toolRegistryExtension(pi) {
             }
             : undefined, { placement: "belowEditor" });
         const transitions = Observability.detectRunTransitions(observedRuns, summary);
-        const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary);
+        const outboxEvents = Observability.detectRunOutboxEvents(observedRunEventLines, summary, observedRunOutboxEventIds);
         if (!notify)
             return;
         retireCandidateRuns(ctx, summary);
@@ -119,7 +122,7 @@ export default function toolRegistryExtension(pi) {
                 details: transition,
             }, { deliverAs: "followUp", triggerTurn: true });
         }
-        Observability.pruneRunObservationState(observedRuns, observedRunEventLines, summary, transitions.map((transition) => transition.stateDir ?? transition.run));
+        Observability.pruneRunObservationState(observedRuns, observedRunEventLines, summary, transitions.map((transition) => transition.stateDir ?? transition.run), observedRunOutboxEventIds);
         for (const event of outboxEvents) {
             if (!Observability.shouldNotifyRunOutboxEvent(event))
                 continue;
@@ -356,6 +359,19 @@ export default function toolRegistryExtension(pi) {
                 ctx.ui.notify("Usage: /actors-inspect <number>", "warning");
                 return;
             }
+            const previews = ActorInspectorTui.readActorInspectorPreviews(RUN_STATE_ROOT, actorInspectorRows, {
+                channels: actorInspectorChannels,
+                currentRunOnly: true,
+                branch: actorInspectorBranch,
+                mention: actorInspectorMention,
+                ownerId: getRunOwnerId(ctx),
+                readKeys: actorInspectorReadKeys,
+                roomLimitPerRun: actorInspectorRoomLimitPerRun,
+                unreadOnly: actorInspectorUnreadOnly,
+            });
+            const preview = previews.find((item) => item.sequence === sequence);
+            if (preview)
+                actorInspectorReadKeys.add(ActorInspectorTui.inspectorPreviewReadKey(preview));
             selectedInspectorSequence = sequence;
             communicationWidgetVisible = true;
             updateRunUi(ctx);

package/dist/lib/actor-inspector-tui.d.ts

@@ -6,10 +6,12 @@ export interface ActorInspectorPreview {
     body_preview?: string;
     branch?: string;
     channel: "broadcast" | "direct" | "room";
+    event_id?: string;
     from?: string;
     from_display?: string;
     inbox_status?: string;
     message_id?: string;
+    needs_response?: boolean;
     run: string;
     sequence?: number;
     summary?: string;
@@ -44,9 +46,11 @@ export interface ActorInspectorPreviewReadOptions {
     currentRunOnly?: boolean;
     channels?: ActorInspectorPreview["channel"][];
     mention?: string;
+    readKeys?: Iterable<string>;
     roomLimitPerRun?: number;
     unreadOnly?: boolean;
 }
+export declare function inspectorPreviewReadKey(preview: ActorInspectorPreview): string;
 export declare function readActorInspectorPreviews(stateRoot?: string, limit?: number, options?: ActorInspectorPreviewReadOptions): ActorInspectorPreview[];
 export declare function readActorInspectorRoster(stateRoot: string | undefined, run: string, room?: string): ActorInspectorRosterMember[];
 export declare function renderInspectorRosterLine(members: ActorInspectorRosterMember[], width?: number, styles?: ActorInspectorWidgetStyle): string | undefined;

package/dist/lib/actor-inspector-tui.js

@@ -5,34 +5,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { visibleWidth } from "@earendil-works/pi-tui";
+import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
+import { readJsonFileResilient, readJsonlFileResilient } from "./state-readers.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value
         : {};
 }
 function readJsonLines(file) {
-    try {
-        return fs
-            .readFileSync(file, "utf8")
-            .split("\n")
-            .filter(Boolean)
-            .flatMap((line) => {
-            try {
-                return [JSON.parse(line)];
-            }
-            catch {
-                return [];
-            }
-        });
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        return [];
-    }
+    return readJsonlFileResilient(file).records;
 }
-function previewValue(value, maxLength = 320) {
+function previewValue(value, maxLength = Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
     const text = typeof value === "string" ? value : JSON.stringify(value);
@@ -58,6 +42,10 @@ function previewFromMessage(run, message, timestamp, displayNames = {}) {
     const from = typeof message.from === "string" ? message.from : undefined;
     const summary = typeof message.summary === "string" ? message.summary : undefined;
     const body = asRecord(message.body);
+    const metadata = asRecord(message.metadata);
+    const eventId = typeof message.id === "string" && message.id.trim()
+        ? message.id.trim()
+        : undefined;
     const display = from
         ? typeof body.display === "string" && body.display.trim()
             ? body.display.trim()
@@ -68,8 +56,10 @@ function previewFromMessage(run, message, timestamp, displayNames = {}) {
             ? { body_preview: previewValue(message.body) }
             : {}),
         channel: channelFor({ to }),
+        ...(eventId ? { event_id: eventId } : {}),
         ...(from ? { from } : {}),
         ...(display ? { from_display: display } : {}),
+        ...(metadata.requires_response === true ? { needs_response: true } : {}),
         run,
         ...(summary ? { summary } : {}),
         timestamp,
@@ -78,12 +68,7 @@ function previewFromMessage(run, message, timestamp, displayNames = {}) {
     };
 }
 function readRoomRosterRecords(stateDir, room) {
-    try {
-        return JSON.parse(fs.readFileSync(path.join(stateDir, "rooms", room, "roster.json"), "utf8"));
-    }
-    catch {
-        return {};
-    }
+    return readJsonFileResilient(path.join(stateDir, "rooms", room, "roster.json"), {}).value;
 }
 function memberDisplay(_address, member) {
     const display = typeof member.display === "string" ? member.display.trim() : "";
@@ -129,14 +114,21 @@ function readBranchInboxPreviews(run, stateDir) {
             .filter((entry) => entry.isDirectory())
             .flatMap((entry) => readJsonLines(path.join(branchesDir, entry.name, "inbox.jsonl"))
             .map((message) => {
-            const preview = previewFromMessage(run, message, String(message.queued_at ?? message.received_at ?? message.timestamp ?? ""));
+            const preview = previewFromMessage(run, message, String(message.queued_at ??
+                message.received_at ??
+                message.timestamp ??
+                ""));
             if (!preview)
                 return undefined;
             return {
                 ...preview,
                 branch: entry.name,
-                ...(typeof message.id === "string" ? { message_id: message.id } : {}),
-                ...(typeof message.status === "string" ? { inbox_status: message.status } : {}),
+                ...(typeof message.id === "string"
+                    ? { message_id: message.id }
+                    : {}),
+                ...(typeof message.status === "string"
+                    ? { inbox_status: message.status }
+                    : {}),
             };
         })
             .filter((preview) => Boolean(preview)));
@@ -156,19 +148,28 @@ function readOutboxPreviews(run, stateDir) {
         .filter((preview) => Boolean(preview));
 }
 function getRunOwnerId(stateDir) {
-    try {
-        const meta = JSON.parse(fs.readFileSync(path.join(stateDir, "run.json"), "utf8"));
-        return typeof meta.ownerId === "string" ? meta.ownerId : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    const meta = readJsonFileResilient(path.join(stateDir, "run.json"), undefined).value;
+    return typeof meta?.ownerId === "string" ? meta.ownerId : undefined;
 }
 function matchesOwner(stateDir, ownerId) {
     return ownerId === undefined || getRunOwnerId(stateDir) === ownerId;
 }
-function isUnreadPreview(preview) {
-    return preview.inbox_status === "queued" || preview.inbox_status === undefined && preview.branch !== undefined;
+export function inspectorPreviewReadKey(preview) {
+    return [
+        preview.channel,
+        preview.run,
+        preview.branch ?? "",
+        preview.event_id ?? preview.message_id ?? preview.timestamp,
+        preview.from ?? "",
+        preview.to,
+        preview.type,
+    ].join("|");
+}
+function isUnreadPreview(preview, readKeys) {
+    if (readKeys?.has(inspectorPreviewReadKey(preview)))
+        return false;
+    return (preview.inbox_status === "queued" ||
+        (preview.inbox_status === undefined && preview.branch !== undefined));
 }
 function matchesBranchFilter(preview, branch) {
     const name = branch?.trim();
@@ -183,7 +184,8 @@ function matchesPreviewFilter(preview, options) {
     if (options.channels?.length && !options.channels.includes(preview.channel)) {
         return false;
     }
-    if (options.unreadOnly && !isUnreadPreview(preview))
+    const readKeys = options.readKeys ? new Set(options.readKeys) : undefined;
+    if (options.unreadOnly && !isUnreadPreview(preview, readKeys))
         return false;
     if (!matchesBranchFilter(preview, options.branch))
         return false;
@@ -298,6 +300,9 @@ function routeText(preview) {
         return `${actor} ⇢ ${preview.to}`;
     return `${actor} → ${actorName(preview.to)}`;
 }
+function attentionMarker(preview) {
+    return preview.needs_response ? "! " : "";
+}
 function style(styleFn, text) {
     return styleFn ? styleFn(text) : text;
 }
@@ -351,7 +356,7 @@ function renderCompactInspectorEntry(preview, width, sequenceWidth, routeWidth,
     const contentWidth = Math.max(8, width - prefix.length - suffix.length);
     const sequence = String(preview.sequence ?? 0).padStart(sequenceWidth, " ");
     const sequencePrefix = `${sequence}${separator}`;
-    const route = routeText(preview);
+    const route = `${attentionMarker(preview)}${routeText(preview)}`;
     const routePadding = " ".repeat(Math.max(0, routeWidth - displayWidth(route)));
     const typePadding = " ".repeat(Math.max(0, typeWidth - displayWidth(preview.type)));
     const headline = previewText(preview);
@@ -382,7 +387,7 @@ function renderInspectorEntry(preview, width, sequenceWidth, routeWidth, typeWid
     const contentWidth = Math.max(8, width - prefix.length - suffix.length);
     const sequence = String(preview.sequence ?? 0).padStart(sequenceWidth, " ");
     const sequencePrefix = `${sequence}${separator}`;
-    const route = routeText(preview);
+    const route = `${attentionMarker(preview)}${routeText(preview)}`;
     const type = preview.type;
     const summary = preview.summary?.trim() ?? "";
     const body = preview.body_preview?.trim() || (!summary ? previewText(preview) : "-");
@@ -430,7 +435,10 @@ export function readActorInspectorRoster(stateRoot = Paths.getRunStateRoot(), ru
 }
 function rosterRoleText(role) {
     const roleLabel = role?.split(";")[0] ?? "";
-    const cleaned = roleLabel.replaceAll(/\s*\([^)]*\)\s*$/g, "").trim().toLowerCase();
+    const cleaned = roleLabel
+        .replaceAll(/\s*\([^)]*\)\s*$/g, "")
+        .trim()
+        .toLowerCase();
     if (!cleaned || cleaned === "actor")
         return undefined;
     return cleaned.replaceAll(/\s+/g, "-");
@@ -444,7 +452,10 @@ function rosterMemberText(member) {
 }
 function isRosterMemberActive(member) {
     const status = member.status?.trim().toLowerCase();
-    return !status || status === "present" || status === "active" || status === "running";
+    return (!status ||
+        status === "present" ||
+        status === "active" ||
+        status === "running");
 }
 export function renderInspectorRosterLine(members, width = 80, styles = {}) {
     return renderInspectorRosterPanel(members, width, styles)?.[0];
@@ -491,12 +502,15 @@ export function renderInspectorItemView(previews, width = 80, styles = {}, optio
     const orderedKeys = [
         "channel",
         "run",
+        "event_id",
         "from",
         "from_display",
         "to",
         "type",
         "summary",
         "body_preview",
+        "message_id",
+        "needs_response",
         "timestamp",
         "stripe",
     ];
@@ -540,7 +554,7 @@ export function renderInspectorWidget(previews, width = 80, styles = {}, options
     const sequencePrefixWidth = sequenceWidth + separatorWidth;
     const fixedSeparatorsWidth = separatorWidth * 3;
     const availableForColumns = Math.max(0, safeWidth - 1 - sequencePrefixWidth - fixedSeparatorsWidth);
-    const naturalRouteWidth = Math.max(...visible.map(({ preview }) => displayWidth(routeText(preview))));
+    const naturalRouteWidth = Math.max(...visible.map(({ preview }) => displayWidth(`${attentionMarker(preview)}${routeText(preview)}`)));
     const naturalTypeWidth = Math.max(...visible.map(({ preview }) => displayWidth(preview.type)));
     const routeWidth = Math.min(naturalRouteWidth, Math.max(4, Math.floor(availableForColumns * 0.35)));
     const typeWidth = Math.min(naturalTypeWidth, Math.max(4, Math.floor(availableForColumns * 0.25)));

package/dist/lib/actor-rooms.d.ts

@@ -32,10 +32,20 @@ export interface RoomMessagePreview {
     to: string;
     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;
@@ -63,6 +73,11 @@ export interface ActorCommunicationSnapshot {
 }
 export declare function readRoomRoster(stateDir: string, room: string): Record<string, RoomMember>;
 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;
@@ -75,6 +90,7 @@ export declare function readBranchInboxMessages(stateDir: string, run: string, a
 export declare function readBranchInboxDiagnostics(stateDir: string, run: string, address: string, limit?: number): BranchInboxReadResult;
 export declare function getBranchInboxTerminalRetainLimit(): number;
 export declare function appendBranchInboxMessage(stateDir: string, run: string, address: string, message: ActorMessage): void;
+export declare function claimBranchInboxMessage(stateDir: string, run: string, address: string, owner?: string, statuses?: string[]): BranchInboxRecord | undefined;
 export declare function updateBranchInboxMessageStatus(stateDir: string, run: string, address: string, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
 export declare function appendRoomMessage(stateDir: string, room: string, message: ActorMessage): RoomAppendResult;
 export declare function readRoomMessages(stateDir: string, room: string, limit?: number): RoomTimelineEntry[];