@llblab/pi-actors 0.40.1 → 0.41.1

package/dist/lib/inspector.d.ts

@@ -3,6 +3,7 @@
  * Zones: terminal run inspection, room/direct message previews, no-dependency UI formatting
  * Owns read-only previews and TUI-ready summaries; actor routing stays outside.
  */
+import * as SessionEvidence from "./session-evidence.ts";
 export interface ActorInspectorPreview {
     body_preview?: string;
     branch?: string;
@@ -45,47 +46,30 @@ export interface ActorInspectorPreviewReadOptions {
     ownerId?: string;
     branch?: string;
     currentRunOnly?: boolean;
+    run?: string;
     channels?: ActorInspectorPreview["channel"][];
     mention?: string;
     readKeys?: Iterable<string>;
     roomLimitPerRun?: number;
     unreadOnly?: boolean;
 }
-export interface ActorInspectorControllerState {
-    branch?: string;
-    channels?: ActorInspectorPreview["channel"][];
-    mention?: string;
-    readKeys: Set<string>;
-    roomLimitPerRun: number;
-    rows: number;
-    selectedSequence?: number;
-    unreadOnly: boolean;
-    visible: boolean;
+export interface ActorInspectorRunItem {
+    run: string;
+    status: string;
+    updatedAt?: string;
 }
-export interface ActorInspectorCommandResult {
-    notify: string;
-    type: "info" | "warning";
-    update: boolean;
+export declare function readActorInspectorRuns(stateRoot: string, ownerId: string): ActorInspectorRunItem[];
+export interface ActorInspectorTurnItem extends SessionEvidence.SessionEvidenceTurn {
+    commandId: string;
+    diagnostics: string[];
+    promptBytes?: number;
+    promptFile?: string;
+    recipeContext?: unknown;
+    sessionFile: string;
+    sessionTruncated: boolean;
+    stage?: string;
 }
-export declare const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-export declare const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS: {
-    filter: string;
-    inspect: string;
-    toggle: string;
-};
-export declare function createActorInspectorControllerState(): ActorInspectorControllerState;
-export declare function getActorInspectorPreviewOptions(state: ActorInspectorControllerState, ownerId: string): ActorInspectorPreviewReadOptions;
-export declare function handleActorInspectorToggle(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
-export declare function handleActorInspectorFilter(state: ActorInspectorControllerState, args: unknown): ActorInspectorCommandResult;
-export declare function handleActorInspectorInspect(state: ActorInspectorControllerState, args: unknown, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
-export declare function selectActorInspectorSequence(state: ActorInspectorControllerState, sequence: number, previews: ActorInspectorPreview[]): ActorInspectorCommandResult;
-export declare function renderActorInspectorPanel(input: {
-    stateRoot: string;
-    state: ActorInspectorControllerState;
-    ownerId: string;
-    width: number;
-    style: ActorInspectorWidgetStyle;
-}): string[];
+export declare function readActorInspectorTurns(stateDir: string): ActorInspectorTurnItem[];
 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[];

package/dist/lib/inspector.js

@@ -8,164 +8,111 @@ 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 * as SessionEvidence from "./session-evidence.js";
 import { readJsonFileResilient, readJsonlFileResilient, } from "./state-readers.js";
-export const DEFAULT_ACTOR_INSPECTOR_ROWS = 12;
-export const ACTOR_INSPECTOR_COMMAND_DESCRIPTIONS = {
-    filter: "Filter actor inspector rows: all, room, direct, broadcast, unread, branch <name>, mention <text>",
-    inspect: "Inspect actor message by visible number",
-    toggle: "Toggle actor inspector widget; optional row count",
-};
-export function createActorInspectorControllerState() {
-    return {
-        readKeys: new Set(),
-        roomLimitPerRun: DEFAULT_ACTOR_INSPECTOR_ROWS,
-        rows: DEFAULT_ACTOR_INSPECTOR_ROWS,
-        unreadOnly: false,
-        visible: false,
-    };
-}
-export function getActorInspectorPreviewOptions(state, ownerId) {
-    return {
-        channels: state.channels,
-        currentRunOnly: true,
-        branch: state.branch,
-        mention: state.mention,
-        ownerId,
-        readKeys: state.readKeys,
-        roomLimitPerRun: state.roomLimitPerRun,
-        unreadOnly: state.unreadOnly,
-    };
-}
-export function handleActorInspectorToggle(state, args) {
-    const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-    if (String(raw).trim()) {
-        const rows = Number.parseInt(String(raw), 10);
-        if (!Number.isFinite(rows) || rows <= 0) {
-            return {
-                notify: "Usage: /actors-inspector-toggle [rows] where rows > 0",
-                type: "warning",
-                update: false,
-            };
-        }
-        state.rows = rows;
-        state.roomLimitPerRun = rows;
-        state.selectedSequence = undefined;
-        state.visible = true;
-        return {
-            notify: `Actor inspector rows ${rows}`,
-            type: "info",
-            update: true,
-        };
-    }
-    if (state.selectedSequence !== undefined) {
-        state.selectedSequence = undefined;
-        state.visible = true;
-        return { notify: "Actor inspector table", type: "info", update: true };
+export function readActorInspectorRuns(stateRoot, ownerId) {
+    try {
+        return fs
+            .readdirSync(stateRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const stateDir = path.join(stateRoot, entry.name);
+            if (!matchesOwner(stateDir, ownerId))
+                return [];
+            const progress = readJsonFileResilient(path.join(stateDir, "progress.json"), {}).value;
+            const result = readJsonFileResilient(path.join(stateDir, "result.json"), {}).value;
+            return [{
+                    run: entry.name,
+                    status: String(progress.phase ?? (Object.keys(result).length ? "terminal" : "unknown")),
+                    ...(typeof progress.updatedAt === "string"
+                        ? { updatedAt: progress.updatedAt }
+                        : typeof result.completedAt === "string"
+                            ? { updatedAt: result.completedAt }
+                            : {}),
+                }];
+        })
+            .sort((left, right) => {
+            const recency = String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? ""));
+            return recency || right.run.localeCompare(left.run);
+        });
     }
-    if (state.visible)
-        state.visible = false;
-    else {
-        state.rows = DEFAULT_ACTOR_INSPECTOR_ROWS;
-        state.roomLimitPerRun = DEFAULT_ACTOR_INSPECTOR_ROWS;
-        state.visible = true;
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [];
     }
-    return {
-        notify: `Actor inspector ${state.visible ? "shown" : "hidden"}`,
-        type: "info",
-        update: true,
-    };
 }
-export function handleActorInspectorFilter(state, args) {
-    const parts = Array.isArray(args)
-        ? args.map(String)
-        : String(args ?? "").split(/\s+/);
-    const mode = (parts[0] ?? "").trim().toLowerCase();
-    if (!mode || mode === "all" || mode === "clear") {
-        state.channels = undefined;
-        state.mention = undefined;
-        state.branch = undefined;
-        state.unreadOnly = false;
-    }
-    else if (mode === "room" || mode === "direct" || mode === "broadcast") {
-        state.channels = [mode];
-        state.mention = undefined;
-    }
-    else if (mode === "unread") {
-        state.unreadOnly = true;
-    }
-    else if (mode === "branch" || mode === "current-branch") {
-        const branch = parts.slice(1).join(" ").trim();
-        if (!branch) {
-            return {
-                notify: `Usage: /actors-inspector-filter ${mode} <branch-name>`,
-                type: "warning",
-                update: false,
-            };
-        }
-        state.branch = branch;
-    }
-    else if (mode === "mention") {
-        const mention = parts.slice(1).join(" ").trim();
-        if (!mention) {
-            return {
-                notify: "Usage: /actors-inspector-filter mention <text>",
-                type: "warning",
-                update: false,
-            };
-        }
-        state.channels = undefined;
-        state.mention = mention;
+function ownedSessionPath(stateDir, sessionFile) {
+    if (path.isAbsolute(sessionFile))
+        return undefined;
+    const sessionsRoot = path.resolve(stateDir, "sessions");
+    const resolved = path.resolve(stateDir, sessionFile);
+    if (!resolved.startsWith(`${sessionsRoot}${path.sep}`))
+        return undefined;
+    try {
+        const canonicalRoot = fs.realpathSync(sessionsRoot);
+        const canonicalFile = fs.realpathSync(resolved);
+        return canonicalFile.startsWith(`${canonicalRoot}${path.sep}`)
+            ? canonicalFile
+            : undefined;
     }
-    else {
-        return {
-            notify: "Usage: /actors-inspector-filter all|room|direct|broadcast|unread|branch <name>|mention <text>",
-            type: "warning",
-            update: false,
-        };
+    catch {
+        return undefined;
     }
-    state.selectedSequence = undefined;
-    state.visible = true;
-    return {
-        notify: `Actor inspector filter ${mode || "all"}`,
-        type: "info",
-        update: true,
-    };
 }
-export function handleActorInspectorInspect(state, args, previews) {
-    const raw = Array.isArray(args) ? args[0] : String(args ?? "");
-    return selectActorInspectorSequence(state, Number.parseInt(String(raw), 10), previews);
-}
-export function selectActorInspectorSequence(state, sequence, previews) {
-    if (!Number.isFinite(sequence) || sequence <= 0) {
-        return {
-            notify: "Usage: /actors-inspect <number>",
-            type: "warning",
-            update: false,
-        };
+export function readActorInspectorTurns(stateDir) {
+    const evidence = readJsonFileResilient(path.join(stateDir, "review-evidence.json"), {}).value;
+    const commands = Array.isArray(evidence.commands)
+        ? evidence.commands
+        : [];
+    const recordedFiles = new Set(commands.flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : []).filter((file) => typeof file === "string")));
+    let discoveredCommands = [];
+    try {
+        const sessionsDir = path.join(stateDir, "sessions");
+        discoveredCommands = fs
+            .readdirSync(sessionsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .flatMap((entry) => {
+            const files = fs
+                .readdirSync(path.join(sessionsDir, entry.name), {
+                withFileTypes: true,
+            })
+                .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
+                .map((file) => path.join("sessions", entry.name, file.name))
+                .filter((file) => !recordedFiles.has(file));
+            return files.length > 0
+                ? [{ id: entry.name, session_files: files, stage: "subagent" }]
+                : [];
+        });
     }
-    const preview = previews.find((item) => item.sequence === sequence);
-    if (preview)
-        state.readKeys.add(inspectorPreviewReadKey(preview));
-    state.selectedSequence = sequence;
-    state.visible = true;
-    return {
-        notify: `Actor inspect item ${sequence}`,
-        type: "info",
-        update: true,
-    };
-}
-export function renderActorInspectorPanel(input) {
-    const previews = readActorInspectorPreviews(input.stateRoot, input.state.rows, getActorInspectorPreviewOptions(input.state, input.ownerId));
-    const rows = (input.state.selectedSequence !== undefined
-        ? renderInspectorItemView(previews, input.width, input.style, {
-            sequence: input.state.selectedSequence,
-        })
-        : renderInspectorWidget(previews, input.width, input.style)) ?? [];
-    const run = previews[0]?.run;
-    const roster = input.state.selectedSequence === undefined && run
-        ? renderInspectorRosterPanel(readActorInspectorRoster(input.stateRoot, run), input.width, input.style)
-        : undefined;
-    return roster ? [...roster, ...rows] : rows;
+    catch {
+        discoveredCommands = [];
+    }
+    return [...commands, ...discoveredCommands].flatMap((command) => (Array.isArray(command.session_files) ? command.session_files : [])
+        .filter((file) => typeof file === "string")
+        .flatMap((file) => {
+        const sessionPath = ownedSessionPath(stateDir, file);
+        if (!sessionPath)
+            return [];
+        const session = SessionEvidence.readSessionEvidence(sessionPath);
+        return session.turns.map((turn) => ({
+            ...turn,
+            commandId: String(command.id ?? "unknown"),
+            diagnostics: session.diagnostics.map((item) => `${item.line === undefined ? "" : `line ${item.line}: `}${item.message}`),
+            ...(typeof command.prompt_bytes === "number"
+                ? { promptBytes: command.prompt_bytes }
+                : {}),
+            ...(typeof command.prompt_file === "string"
+                ? { promptFile: command.prompt_file }
+                : {}),
+            ...(command.recipe_context !== undefined
+                ? { recipeContext: command.recipe_context }
+                : {}),
+            sessionFile: file,
+            sessionTruncated: session.truncated,
+            ...(typeof command.stage === "string" ? { stage: command.stage } : {}),
+        }));
+    })).map((turn, index) => ({ ...turn, index: index + 1 }));
 }
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -178,7 +125,8 @@ function readJsonLines(file) {
 function previewValue(value, maxLength = Limits.INSPECTOR_BODY_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
-    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const redacted = SessionEvidence.redactSessionEvidenceValue(value);
+    const text = typeof redacted === "string" ? redacted : JSON.stringify(redacted);
     const compact = text.replaceAll(/\s+/g, " ").trim();
     if (!compact)
         return undefined;
@@ -393,6 +341,8 @@ export function readActorInspectorPreviews(stateRoot = Paths.getRunStateRoot(),
             const stateDir = path.join(stateRoot, entry.name);
             if (!matchesOwner(stateDir, options.ownerId))
                 return [];
+            if (options.run && entry.name !== options.run)
+                return [];
             return [
                 ...readRoomPreviews(entry.name, stateDir),
                 ...readInboxPreviews(entry.name, stateDir),

package/dist/lib/limits.d.ts

@@ -9,3 +9,6 @@ export declare const COMPACT_PREVIEW_CHARS = 160;
 export declare const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export declare const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export declare const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export declare const SESSION_EVIDENCE_MAX_TURNS = 100;
+export declare const SESSION_EVIDENCE_TEXT_CHARS = 4000;
+export declare const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/limits.js

@@ -9,3 +9,6 @@ export const COMPACT_PREVIEW_CHARS = 160;
 export const INSPECTOR_BODY_PREVIEW_CHARS = 320;
 export const ROOM_MESSAGE_PREVIEW_CHARS = 320;
 export const DOCTOR_ACTION_PREVIEW_CHARS = 72;
+export const SESSION_EVIDENCE_MAX_TURNS = 100;
+export const SESSION_EVIDENCE_TEXT_CHARS = 4_000;
+export const SESSION_EVIDENCE_MAX_TOOL_CALLS = 100;

package/dist/lib/observability.d.ts

@@ -3,6 +3,7 @@
  * Zones: async runtime, ambient UI, diagnostics
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
+import { type FSWatcher } from "node:fs";
 import * as AsyncRuns from "./async-runs.ts";
 export type RunObservedStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
 export type RunOutboxDelivery = "log" | "notify" | "followup";
@@ -58,9 +59,19 @@ export interface RunUiNotificationSink {
     }): void;
 }
 export declare function createRunUiObservationState(): RunUiObservationState;
-export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string): RunUiSnapshot;
+export declare function readRunUiSnapshot(state: RunUiObservationState, ownerId: string, options?: {
+    includeOutbox?: boolean;
+    stateRoot?: string;
+}): RunUiSnapshot;
 export declare function pruneRunUiObservationState(state: RunUiObservationState, snapshot: Pick<RunUiSnapshot, "summary" | "transitions">): void;
-export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink): void;
+export declare function deliverRunTransitionNotifications(transitions: RunTransition[], sink: RunUiNotificationSink, inFlight?: Set<string>): void;
+export declare function reconcileRunTerminalNotifications(input: {
+    inFlight?: Set<string>;
+    ownerId: string;
+    sink: RunUiNotificationSink;
+    state: RunUiObservationState;
+    stateRoot?: string;
+}): RunUiSnapshot;
 export declare function deliverRunOutboxNotifications(events: RunOutboxEvent[], sink: RunUiNotificationSink): void;
 export interface RunRetirementCandidate {
     activeSubagents: number;
@@ -76,14 +87,38 @@ export interface RunRetirementExecution {
     run: string;
     stateDir: string;
 }
+export type RunStateWatcherDiagnosticCode = "attach_failed" | "error" | "removed" | "rearmed";
+export interface RunStateWatcherDiagnostic {
+    code: RunStateWatcherDiagnosticCode;
+    id: number;
+    message: string;
+    path: string;
+    scope: "root" | "run";
+    ts: string;
+}
 export interface RunStateWatcher {
     close(): void;
+    getDiagnostics(): RunStateWatcherDiagnostic[];
     refresh(): void;
 }
 export declare function createRunStateWatcher(input: {
-    stateRoot?: string;
+    exists?: (path: string) => boolean;
+    listDirectories?: (path: string) => string[];
     onChange: () => void;
+    stateRoot?: string;
+    watchPath?: (path: string, onChange: () => void) => FSWatcher;
 }): RunStateWatcher;
+export interface RunTerminalReconciliationLoop {
+    close(): void;
+    reconcileNow(): void;
+    start(): void;
+}
+export declare function createRunTerminalReconciliationLoop(input: {
+    intervalMs?: number;
+    onError?: (error: unknown) => void;
+    reconcile: () => void;
+    refreshWatcher: () => void;
+}): RunTerminalReconciliationLoop;
 export interface RunRetirementExecutorOptions {
     attempted?: Set<string>;
     cancelRun: (candidate: RunRetirementCandidate) => Record<string, unknown>;