@llblab/pi-actors 0.40.1 → 0.41.1

package/lib/observability.ts

@@ -101,15 +101,19 @@ export function createRunUiObservationState(): RunUiObservationState {
 export function readRunUiSnapshot(
   state: RunUiObservationState,
   ownerId: string,
+  options: { includeOutbox?: boolean; stateRoot?: string } = {},
 ): RunUiSnapshot {
-  const summary = summarizeRuns(undefined, ownerId);
+  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),
@@ -134,27 +138,55 @@ export function pruneRunUiObservationState(
 export function deliverRunTransitionNotifications(
   transitions: RunTransition[],
   sink: RunUiNotificationSink,
+  inFlight: Set<string> = new Set(),
 ): void {
   for (const transition of transitions) {
     if (!shouldNotifyRunTransition(transition)) continue;
-    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,
-      );
+    const key = transition.stateDir ?? transition.run;
+    if (inFlight.has(key)) continue;
+    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: {
+  inFlight?: Set<string>;
+  ownerId: string;
+  sink: RunUiNotificationSink;
+  state: RunUiObservationState;
+  stateRoot?: string;
+}): RunUiSnapshot {
+  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: RunOutboxEvent[],
   sink: RunUiNotificationSink,
@@ -189,18 +221,94 @@ export interface RunRetirementExecution {
   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;
 }
 
+const RUN_WATCHER_DIAGNOSTIC_LIMIT = 32;
+
 export function createRunStateWatcher(input: {
-  stateRoot?: string;
+  exists?: (path: string) => boolean;
+  listDirectories?: (path: string) => string[];
   onChange: () => void;
+  stateRoot?: string;
+  watchPath?: (path: string, onChange: () => void) => FSWatcher;
 }): RunStateWatcher {
   const stateRoot = input.stateRoot ?? Paths.getRunStateRoot();
+  const pathExists = input.exists ?? existsSync;
+  const listDirectories =
+    input.listDirectories ??
+    ((path: string) =>
+      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: FSWatcher | undefined;
+  const degradedRunDirs = new Set<string>();
+  const diagnostics: RunStateWatcherDiagnostic[] = [];
+  const lastDiagnosticSignatures = new Map<string, string>();
   const runDirWatchers = new Map<string, FSWatcher>();
+  const record = (
+    code: RunStateWatcherDiagnosticCode,
+    scope: "root" | "run",
+    path: string,
+    error?: unknown,
+  ): void => {
+    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: string,
+    watcher: FSWatcher,
+    options: { degraded?: boolean; error?: unknown } = {},
+  ): void => {
+    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 = (): void => {
     stateRootWatcher?.close();
     stateRootWatcher = undefined;
@@ -208,37 +316,95 @@ export function createRunStateWatcher(input: {
     runDirWatchers.clear();
   };
   const watchRunDir = (stateDir: string): void => {
-    if (runDirWatchers.has(stateDir) || !existsSync(stateDir)) return;
+    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);
-    } catch {
-      // Watching is best-effort; explicit inspect remains available.
+      if (degradedRunDirs.delete(stateDir)) record("rearmed", "run", stateDir);
+    } catch (error) {
+      degradedRunDirs.add(stateDir);
+      record("attach_failed", "run", stateDir, error);
     }
   };
   function refresh(): void {
-    if (!existsSync(stateRoot)) return;
+    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);
         });
-      } catch {
-        // Watching is best-effort; explicit inspect remains available.
+        if (rootDegraded) {
+          rootDegraded = false;
+          record("rearmed", "root", stateRoot);
+        }
+      } catch (error) {
+        rootDegraded = true;
+        record("attach_failed", "root", stateRoot, error);
       }
     }
-    for (const entry of readdirSync(stateRoot, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      watchRunDir(`${stateRoot}/${entry.name}`);
+    let stateDirs: string[];
+    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;
+      removeRunWatcher(stateDir, watcher, { degraded: false });
+    }
+    for (const stateDir of stateDirs) watchRunDir(stateDir);
   }
-  return { close, refresh };
+  return {
+    close,
+    getDiagnostics: () => [...diagnostics],
+    refresh,
+  };
+}
+
+export interface RunTerminalReconciliationLoop {
+  close(): void;
+  reconcileNow(): void;
+  start(): void;
+}
+
+export function createRunTerminalReconciliationLoop(input: {
+  intervalMs?: number;
+  onError?: (error: unknown) => void;
+  reconcile: () => void;
+  refreshWatcher: () => void;
+}): RunTerminalReconciliationLoop {
+  const intervalMs = input.intervalMs ?? 10_000;
+  let interval: NodeJS.Timeout | undefined;
+  const reconcileNow = (): void => {
+    try {
+      input.refreshWatcher();
+      input.reconcile();
+    } catch (error) {
+      input.onError?.(error);
+    }
+  };
+  const close = (): void => {
+    if (interval) clearInterval(interval);
+    interval = undefined;
+  };
+  const start = (): void => {
+    close();
+    interval = setInterval(reconcileNow, intervalMs);
+    interval.unref?.();
+  };
+  return { close, reconcileNow, start };
 }
 
 export interface RunRetirementExecutorOptions {

package/lib/recipes-context.ts

@@ -167,6 +167,31 @@ export function appendRecipeContextToPiArgs(
   return next;
 }
 
+export interface ManagedPiSessionArgs {
+  args: string[];
+  sessionDir?: string;
+}
+
+const PI_SESSION_POLICY_FLAGS = new Set([
+  "--fork",
+  "--no-session",
+  "--session",
+  "--session-dir",
+  "--session-id",
+]);
+
+export function attachPiSessionDir(
+  command: string,
+  args: string[],
+  sessionDir: string,
+): ManagedPiSessionArgs {
+  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 interface MaterializedPiPrintPromptArgs {
   args: string[];
   promptBytes?: number;

package/lib/session-evidence.ts

@@ -0,0 +1,302 @@
+/**
+ * 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.ts";
+import {
+  readJsonlFileResilient,
+  type StateReadDiagnostic,
+} from "./state-readers.ts";
+
+interface SessionEntry {
+  id?: unknown;
+  message?: unknown;
+  parentId?: unknown;
+  timestamp?: unknown;
+  type?: unknown;
+  [key: string]: unknown;
+}
+
+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;
+}
+
+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: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function boundedText(value: unknown, maxChars: number): string | undefined {
+  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: string | undefined, key: string | undefined, separator: string | undefined) =>
+      bearer ? `${bearer}[REDACTED]` : `${key}${separator}[REDACTED]`,
+  );
+  return redacted.length > maxChars
+    ? `${redacted.slice(0, Math.max(0, maxChars - 1))}…`
+    : redacted;
+}
+
+export function redactSessionEvidenceValue(
+  value: unknown,
+  maxTextChars = Limits.SESSION_EVIDENCE_TEXT_CHARS,
+  seen = new WeakSet<object>(),
+): unknown {
+  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 as Record<string, unknown>).map(([key, item]) => [
+      key,
+      SENSITIVE_KEY.test(key)
+        ? "[REDACTED]"
+        : redactSessionEvidenceValue(item, maxTextChars, seen),
+    ]),
+  );
+}
+
+function contentBlocks(message: Record<string, unknown>): Record<string, unknown>[] {
+  return Array.isArray(message.content)
+    ? message.content.map(asRecord)
+    : typeof message.content === "string"
+      ? [{ type: "text", text: message.content }]
+      : [];
+}
+
+function contentText(
+  message: Record<string, unknown>,
+  type: "text" | "thinking",
+  maxChars: number,
+): string | undefined {
+  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: SessionEntry[],
+  path: string,
+  diagnostics: StateReadDiagnostic[],
+): SessionEntry[] {
+  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] as const),
+  );
+  const branch: SessionEntry[] = [];
+  const visited = new Set<string>();
+  let current: SessionEntry | undefined = 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: Record<string, unknown>,
+  maxTextChars: number,
+  maxToolCalls: number,
+): SessionEvidenceToolCall[] {
+  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: string,
+  options: SessionEvidenceReadOptions = {},
+): SessionEvidence {
+  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<SessionEntry>(path);
+  const diagnostics = [...read.diagnostics];
+  const header = read.records.find((entry) => entry.type === "session");
+  const branch = activeBranch(read.records, path, diagnostics);
+  const turns: SessionEvidenceTurn[] = [];
+  let pendingUser: { id: string; text?: string } | undefined;
+  let currentTurn: SessionEvidenceTurn | undefined;
+  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/lib/tools-response.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.40.1",
+  "version": "0.41.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [