@llblab/pi-actors 0.40.1 → 0.41.1

package/dist/lib/observability.js

@@ -16,11 +16,13 @@ export function createRunUiObservationState() {
         outboxEventIds: new Map(),
     };
 }
-export function readRunUiSnapshot(state, ownerId) {
-    const summary = summarizeRuns(undefined, ownerId);
+export function readRunUiSnapshot(state, ownerId, options = {}) {
+    const summary = summarizeRuns(options.stateRoot, ownerId);
     const status = renderRunStatus(summary, state.frame++);
     return {
-        outboxEvents: detectRunOutboxEvents(state.eventLines, summary, state.outboxEventIds),
+        outboxEvents: options.includeOutbox === false
+            ? []
+            : detectRunOutboxEvents(state.eventLines, summary, state.outboxEventIds),
         status,
         summary,
         transitions: detectRunTransitions(state.observed, summary),
@@ -29,25 +31,43 @@ export function readRunUiSnapshot(state, ownerId) {
 export function pruneRunUiObservationState(state, snapshot) {
     pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.outboxEventIds);
 }
-export function deliverRunTransitionNotifications(transitions, sink) {
+export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
     for (const transition of transitions) {
         if (!shouldNotifyRunTransition(transition))
             continue;
-        const text = formatRunTransitionMessage(transition);
-        sink.notify(text, getRunTransitionNotificationType(transition));
-        if (!shouldSendRunTransitionFollowUp(transition))
+        const key = transition.stateDir ?? transition.run;
+        if (inFlight.has(key))
             continue;
-        sink.sendFollowUp({
-            customType: "pi-actors-run",
-            content: text,
-            display: true,
-            details: transition,
-        });
-        if (transition.stateDir) {
-            AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+        inFlight.add(key);
+        try {
+            const text = formatRunTransitionMessage(transition);
+            sink.notify(text, getRunTransitionNotificationType(transition));
+            if (!shouldSendRunTransitionFollowUp(transition))
+                continue;
+            sink.sendFollowUp({
+                customType: "pi-actors-run",
+                content: text,
+                display: true,
+                details: transition,
+            });
+            if (transition.stateDir) {
+                AsyncRuns.markRunTerminalNotificationHandled(transition.stateDir, transition.to);
+            }
+        }
+        finally {
+            inFlight.delete(key);
         }
     }
 }
+export function reconcileRunTerminalNotifications(input) {
+    const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
+        includeOutbox: false,
+        stateRoot: input.stateRoot,
+    });
+    deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
+    pruneRunUiObservationState(input.state, snapshot);
+    return snapshot;
+}
 export function deliverRunOutboxNotifications(events, sink) {
     for (const event of events) {
         if (!shouldNotifyRunOutboxEvent(event))
@@ -64,10 +84,58 @@ export function deliverRunOutboxNotifications(events, sink) {
         });
     }
 }
+const RUN_WATCHER_DIAGNOSTIC_LIMIT = 32;
 export function createRunStateWatcher(input) {
     const stateRoot = input.stateRoot ?? Paths.getRunStateRoot();
+    const pathExists = input.exists ?? existsSync;
+    const listDirectories = input.listDirectories ??
+        ((path) => readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(path, entry.name)));
+    const watchPath = input.watchPath ?? ((path, onChange) => watch(path, onChange));
+    let diagnosticId = 0;
+    let rootDegraded = false;
     let stateRootWatcher;
+    const degradedRunDirs = new Set();
+    const diagnostics = [];
+    const lastDiagnosticSignatures = new Map();
     const runDirWatchers = new Map();
+    const record = (code, scope, path, error) => {
+        const detail = error instanceof Error ? `: ${error.message}` : "";
+        const signature = `${code}${detail}`;
+        const signatureKey = `${scope}:${path}`;
+        if (lastDiagnosticSignatures.get(signatureKey) === signature)
+            return;
+        lastDiagnosticSignatures.set(signatureKey, signature);
+        const recovery = code === "rearmed"
+            ? "; terminal watch acceleration restored"
+            : "; terminal reconciliation remains active and watcher rearm will retry";
+        diagnostics.push({
+            code,
+            id: ++diagnosticId,
+            message: `Run-state ${scope} watcher ${code.replace("_", " ")} for ${path}${detail}${recovery}`,
+            path,
+            scope,
+            ts: new Date().toISOString(),
+        });
+        if (diagnostics.length > RUN_WATCHER_DIAGNOSTIC_LIMIT)
+            diagnostics.shift();
+    };
+    const removeRunWatcher = (stateDir, watcher, options = {}) => {
+        if (runDirWatchers.get(stateDir) !== watcher)
+            return;
+        watcher.close();
+        runDirWatchers.delete(stateDir);
+        if (options.degraded === false) {
+            degradedRunDirs.delete(stateDir);
+            lastDiagnosticSignatures.delete(`run:${stateDir}`);
+            return;
+        }
+        degradedRunDirs.add(stateDir);
+        if (options.error)
+            record("error", "run", stateDir, options.error);
+        record("removed", "run", stateDir);
+    };
     const close = () => {
         stateRootWatcher?.close();
         stateRootWatcher = undefined;
@@ -76,42 +144,92 @@ export function createRunStateWatcher(input) {
         runDirWatchers.clear();
     };
     const watchRunDir = (stateDir) => {
-        if (runDirWatchers.has(stateDir) || !existsSync(stateDir))
+        if (runDirWatchers.has(stateDir) || !pathExists(stateDir))
             return;
         try {
-            const watcher = watch(stateDir, input.onChange);
-            watcher.on("error", () => {
-                watcher.close();
-                runDirWatchers.delete(stateDir);
-            });
+            const watcher = watchPath(stateDir, input.onChange);
+            watcher.on("error", (error) => removeRunWatcher(stateDir, watcher, { error }));
             runDirWatchers.set(stateDir, watcher);
+            if (degradedRunDirs.delete(stateDir))
+                record("rearmed", "run", stateDir);
         }
-        catch {
-            // Watching is best-effort; explicit inspect remains available.
+        catch (error) {
+            degradedRunDirs.add(stateDir);
+            record("attach_failed", "run", stateDir, error);
         }
     };
     function refresh() {
-        if (!existsSync(stateRoot))
+        if (!pathExists(stateRoot))
             return;
         if (!stateRootWatcher) {
             try {
-                stateRootWatcher = watch(stateRoot, input.onChange);
-                stateRootWatcher.on("error", () => {
-                    stateRootWatcher?.close();
+                const watcher = watchPath(stateRoot, input.onChange);
+                stateRootWatcher = watcher;
+                watcher.on("error", (error) => {
+                    if (stateRootWatcher !== watcher)
+                        return;
+                    watcher.close();
                     stateRootWatcher = undefined;
+                    rootDegraded = true;
+                    record("error", "root", stateRoot, error);
+                    record("removed", "root", stateRoot);
                 });
+                if (rootDegraded) {
+                    rootDegraded = false;
+                    record("rearmed", "root", stateRoot);
+                }
             }
-            catch {
-                // Watching is best-effort; explicit inspect remains available.
+            catch (error) {
+                rootDegraded = true;
+                record("attach_failed", "root", stateRoot, error);
             }
         }
-        for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
-            if (!entry.isDirectory())
+        let stateDirs;
+        try {
+            stateDirs = listDirectories(stateRoot);
+        }
+        catch (error) {
+            record("attach_failed", "root", stateRoot, error);
+            return;
+        }
+        const present = new Set(stateDirs);
+        for (const [stateDir, watcher] of runDirWatchers) {
+            if (present.has(stateDir) && pathExists(stateDir))
                 continue;
-            watchRunDir(`${stateRoot}/${entry.name}`);
+            removeRunWatcher(stateDir, watcher, { degraded: false });
         }
+        for (const stateDir of stateDirs)
+            watchRunDir(stateDir);
     }
-    return { close, refresh };
+    return {
+        close,
+        getDiagnostics: () => [...diagnostics],
+        refresh,
+    };
+}
+export function createRunTerminalReconciliationLoop(input) {
+    const intervalMs = input.intervalMs ?? 10_000;
+    let interval;
+    const reconcileNow = () => {
+        try {
+            input.refreshWatcher();
+            input.reconcile();
+        }
+        catch (error) {
+            input.onError?.(error);
+        }
+    };
+    const close = () => {
+        if (interval)
+            clearInterval(interval);
+        interval = undefined;
+    };
+    const start = () => {
+        close();
+        interval = setInterval(reconcileNow, intervalMs);
+        interval.unref?.();
+    };
+    return { close, reconcileNow, start };
 }
 const TERMINAL = new Set([
     "done",

package/dist/lib/recipes-context.d.ts

@@ -14,6 +14,11 @@ export declare function markRecipeContextRecords(records: TemplateRecipeContextR
 export declare function formatRecipeContextJsonl(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function buildRecipeContextPromptBlock(records: TemplateRecipeContextRecord[], context?: CommandTemplateActorRecipeContext): string;
 export declare function appendRecipeContextToPiArgs(command: string, args: string[], records: TemplateRecipeContextRecord[] | undefined, context?: CommandTemplateActorRecipeContext): string[];
+export interface ManagedPiSessionArgs {
+    args: string[];
+    sessionDir?: string;
+}
+export declare function attachPiSessionDir(command: string, args: string[], sessionDir: string): ManagedPiSessionArgs;
 export interface MaterializedPiPrintPromptArgs {
     args: string[];
     promptBytes?: number;

package/dist/lib/recipes-context.js

@@ -134,6 +134,21 @@ export function appendRecipeContextToPiArgs(command, args, records, context) {
     next[promptIndex] = `${next[promptIndex]}\n\n${block}`;
     return next;
 }
+const PI_SESSION_POLICY_FLAGS = new Set([
+    "--fork",
+    "--no-session",
+    "--session",
+    "--session-dir",
+    "--session-id",
+]);
+export function attachPiSessionDir(command, args, sessionDir) {
+    if (!isPiCommand(command) || findPiPrintPromptIndex(args) === undefined) {
+        return { args };
+    }
+    if (args.some((arg) => PI_SESSION_POLICY_FLAGS.has(arg)))
+        return { args };
+    return { args: ["--session-dir", sessionDir, ...args], sessionDir };
+}
 export function materializePiPrintPromptArg(command, args, promptFile) {
     if (!isPiCommand(command))
         return { args };

package/dist/lib/session-evidence.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Persisted Pi session evidence reader.
+ * Zones: subagent turns, active session branches, bounded/redacted previews
+ * Owns read-only normalization of session JSONL into inspector-ready turns.
+ */
+import { type StateReadDiagnostic } from "./state-readers.ts";
+export interface SessionEvidenceToolCall {
+    arguments?: unknown;
+    id: string;
+    name: string;
+    result?: unknown;
+    resultError?: boolean;
+}
+export interface SessionEvidenceTurn {
+    assistantEntryId?: string;
+    assistantText?: string;
+    error?: string;
+    index: number;
+    model?: string;
+    provider?: string;
+    stopReason?: string;
+    thinking?: string;
+    timestamp?: string;
+    toolCalls: SessionEvidenceToolCall[];
+    unmatchedToolResults: number;
+    usage?: unknown;
+    userEntryId?: string;
+    userText?: string;
+}
+export interface SessionEvidence {
+    activeLeafId?: string;
+    diagnostics: StateReadDiagnostic[];
+    path: string;
+    session?: Record<string, unknown>;
+    totalTurns: number;
+    truncated: boolean;
+    turns: SessionEvidenceTurn[];
+}
+export interface SessionEvidenceReadOptions {
+    maxTextChars?: number;
+    maxToolCalls?: number;
+    maxTurns?: number;
+}
+export declare function redactSessionEvidenceValue(value: unknown, maxTextChars?: number, seen?: WeakSet<object>): unknown;
+export declare function readSessionEvidence(path: string, options?: SessionEvidenceReadOptions): SessionEvidence;

package/dist/lib/session-evidence.js

@@ -0,0 +1,204 @@
+/**
+ * Persisted Pi session evidence reader.
+ * Zones: subagent turns, active session branches, bounded/redacted previews
+ * Owns read-only normalization of session JSONL into inspector-ready turns.
+ */
+import * as Limits from "./limits.js";
+import { readJsonlFileResilient, } from "./state-readers.js";
+const SENSITIVE_KEY = /(?:^|[_-])(?:api[-_]?key|authorization|cookie|credential|password|private[-_]?key|secret|secret[-_]?access[-_]?key|token)$|^(?:access|refresh|auth|api)Token$|^(?:clientSecret|privateKey|secretAccessKey)$/i;
+const SENSITIVE_TEXT = /(bearer\s+)[A-Za-z0-9._~+/=-]+|["']?\b(api[-_]?key|authorization|clientSecret|cookie|password|private[-_]?key|privateKey|secret|secretAccessKey|token)["']?(\s*[:=]\s*)["']?([^\s,;"'}]+)/gi;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maxChars) {
+    if (typeof value !== "string")
+        return undefined;
+    if (/^\s*[\[{]/.test(value)) {
+        try {
+            const structured = JSON.stringify(redactSessionEvidenceValue(JSON.parse(value), maxChars));
+            return structured.length > maxChars
+                ? `${structured.slice(0, Math.max(0, maxChars - 1))}…`
+                : structured;
+        }
+        catch {
+            // Fall through to bounded text redaction.
+        }
+    }
+    const redacted = value.replaceAll(SENSITIVE_TEXT, (match, bearer, key, separator) => bearer ? `${bearer}[REDACTED]` : `${key}${separator}[REDACTED]`);
+    return redacted.length > maxChars
+        ? `${redacted.slice(0, Math.max(0, maxChars - 1))}…`
+        : redacted;
+}
+export function redactSessionEvidenceValue(value, maxTextChars = Limits.SESSION_EVIDENCE_TEXT_CHARS, seen = new WeakSet()) {
+    if (typeof value === "string")
+        return boundedText(value, maxTextChars);
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[CIRCULAR]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSessionEvidenceValue(item, maxTextChars, seen));
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        SENSITIVE_KEY.test(key)
+            ? "[REDACTED]"
+            : redactSessionEvidenceValue(item, maxTextChars, seen),
+    ]));
+}
+function contentBlocks(message) {
+    return Array.isArray(message.content)
+        ? message.content.map(asRecord)
+        : typeof message.content === "string"
+            ? [{ type: "text", text: message.content }]
+            : [];
+}
+function contentText(message, type, maxChars) {
+    const text = contentBlocks(message)
+        .filter((block) => block.type === type && typeof block[type] === "string")
+        .map((block) => String(block[type]))
+        .join("\n");
+    return boundedText(text, maxChars);
+}
+function activeBranch(entries, path, diagnostics) {
+    const treeEntries = entries.filter((entry) => entry.type !== "session" && typeof entry.id === "string");
+    const leaf = treeEntries.at(-1);
+    if (!leaf || typeof leaf.id !== "string")
+        return [];
+    const byId = new Map(treeEntries.map((entry) => [String(entry.id), entry]));
+    const branch = [];
+    const visited = new Set();
+    let current = leaf;
+    while (current && typeof current.id === "string") {
+        if (visited.has(current.id)) {
+            diagnostics.push({ message: `session entry cycle at ${current.id}`, path });
+            break;
+        }
+        visited.add(current.id);
+        branch.push(current);
+        if (current.parentId === null || current.parentId === undefined)
+            break;
+        if (typeof current.parentId !== "string" || !byId.has(current.parentId)) {
+            diagnostics.push({
+                message: `missing parent ${String(current.parentId)} for ${current.id}`,
+                path,
+            });
+            break;
+        }
+        current = byId.get(current.parentId);
+    }
+    return branch.reverse();
+}
+function toolCalls(message, maxTextChars, maxToolCalls) {
+    return contentBlocks(message)
+        .filter((block) => block.type === "toolCall" &&
+        typeof block.id === "string" &&
+        typeof block.name === "string")
+        .slice(0, maxToolCalls)
+        .map((block) => ({
+        arguments: redactSessionEvidenceValue(block.arguments, maxTextChars),
+        id: String(block.id),
+        name: String(block.name),
+    }));
+}
+export function readSessionEvidence(path, options = {}) {
+    const maxTextChars = Math.max(1, options.maxTextChars ?? Limits.SESSION_EVIDENCE_TEXT_CHARS);
+    const maxToolCalls = Math.max(1, options.maxToolCalls ?? Limits.SESSION_EVIDENCE_MAX_TOOL_CALLS);
+    const maxTurns = Math.max(1, options.maxTurns ?? Limits.SESSION_EVIDENCE_MAX_TURNS);
+    const read = readJsonlFileResilient(path);
+    const diagnostics = [...read.diagnostics];
+    const header = read.records.find((entry) => entry.type === "session");
+    const branch = activeBranch(read.records, path, diagnostics);
+    const turns = [];
+    let pendingUser;
+    let currentTurn;
+    for (const entry of branch) {
+        if (entry.type !== "message")
+            continue;
+        const message = asRecord(entry.message);
+        const role = message.role;
+        if (role === "user") {
+            pendingUser = {
+                id: String(entry.id),
+                text: contentText(message, "text", maxTextChars),
+            };
+            currentTurn = undefined;
+            continue;
+        }
+        if (role === "assistant") {
+            currentTurn = {
+                ...(typeof entry.id === "string" ? { assistantEntryId: entry.id } : {}),
+                ...(contentText(message, "text", maxTextChars)
+                    ? { assistantText: contentText(message, "text", maxTextChars) }
+                    : {}),
+                ...(typeof message.errorMessage === "string"
+                    ? { error: boundedText(message.errorMessage, maxTextChars) }
+                    : {}),
+                index: turns.length + 1,
+                ...(typeof message.model === "string" ? { model: message.model } : {}),
+                ...(typeof message.provider === "string"
+                    ? { provider: message.provider }
+                    : {}),
+                ...(typeof message.stopReason === "string"
+                    ? { stopReason: message.stopReason }
+                    : {}),
+                ...(contentText(message, "thinking", maxTextChars)
+                    ? { thinking: contentText(message, "thinking", maxTextChars) }
+                    : {}),
+                ...(typeof entry.timestamp === "string"
+                    ? { timestamp: entry.timestamp }
+                    : {}),
+                toolCalls: toolCalls(message, maxTextChars, maxToolCalls),
+                unmatchedToolResults: 0,
+                ...(message.usage !== undefined
+                    ? { usage: redactSessionEvidenceValue(message.usage, maxTextChars) }
+                    : {}),
+                ...(pendingUser
+                    ? {
+                        userEntryId: pendingUser.id,
+                        ...(pendingUser.text ? { userText: pendingUser.text } : {}),
+                    }
+                    : {}),
+            };
+            pendingUser = undefined;
+            turns.push(currentTurn);
+            continue;
+        }
+        if (role === "toolResult" && currentTurn) {
+            const callId = typeof message.toolCallId === "string" ? message.toolCallId : "";
+            const call = currentTurn.toolCalls.find((item) => item.id === callId);
+            if (!call) {
+                currentTurn.unmatchedToolResults += 1;
+                continue;
+            }
+            call.result = redactSessionEvidenceValue(message.content, maxTextChars);
+            call.resultError = message.isError === true;
+        }
+    }
+    if (pendingUser) {
+        turns.push({
+            index: turns.length + 1,
+            toolCalls: [],
+            unmatchedToolResults: 0,
+            userEntryId: pendingUser.id,
+            ...(pendingUser.text ? { userText: pendingUser.text } : {}),
+        });
+    }
+    const firstVisibleIndex = Math.max(0, turns.length - maxTurns);
+    const visibleTurns = turns.slice(firstVisibleIndex).map((turn, index) => ({
+        ...turn,
+        index: firstVisibleIndex + index + 1,
+    }));
+    return {
+        ...(branch.at(-1)?.id ? { activeLeafId: String(branch.at(-1)?.id) } : {}),
+        diagnostics,
+        path,
+        ...(header ? { session: asRecord(header) } : {}),
+        totalTurns: turns.length,
+        truncated: turns.length > visibleTurns.length,
+        turns: visibleTurns,
+    };
+}

package/dist/lib/tools-response.d.ts

@@ -3,6 +3,9 @@
  * Zones: compact text summaries, verbose JSON switching, next-action rendering
  * Owns model-facing response helpers shared by public tool execution paths
  */
+export declare function withLeadingLineBreak(text: string): string;
+export declare function spaceToolResult<T>(result: T): T;
+export declare function spaceToolError(error: unknown): unknown;
 export declare function asRecord(value: unknown): Record<string, unknown>;
 export declare function jsonText(value: unknown): string;
 export declare function compactPreview(value: unknown, maxLength?: number): string | undefined;

package/dist/lib/tools-response.js

@@ -5,6 +5,35 @@
  */
 import * as Limits from "./limits.js";
 import * as ToolsMailbox from "./tools-mailbox.js";
+export function withLeadingLineBreak(text) {
+    return `\n${text.replace(/^\n+/, "")}`;
+}
+export function spaceToolResult(result) {
+    if (!result || typeof result !== "object")
+        return result;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return result;
+    return {
+        ...result,
+        content: content.map((item) => item &&
+            typeof item === "object" &&
+            item.type === "text" &&
+            typeof item.text === "string"
+            ? {
+                ...item,
+                text: withLeadingLineBreak(item.text),
+            }
+            : item),
+    };
+}
+export function spaceToolError(error) {
+    if (error instanceof Error) {
+        error.message = withLeadingLineBreak(error.message);
+        return error;
+    }
+    return new Error(withLeadingLineBreak(String(error)));
+}
 export function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
         ? value