@llblab/pi-actors 0.41.0 → 0.42.0

package/lib/inspector.ts

@@ -74,6 +74,7 @@ export interface ActorInspectorPreviewReadOptions {
 
 export interface ActorInspectorRunItem {
   run: string;
+  runInstanceId?: string;
   status: string;
   updatedAt?: string;
 }
@@ -89,6 +90,10 @@ export function readActorInspectorRuns(
       .flatMap((entry) => {
         const stateDir = path.join(stateRoot, entry.name);
         if (!matchesOwner(stateDir, ownerId)) return [];
+        const runMeta = readJsonFileResilient<Record<string, unknown>>(
+          path.join(stateDir, "run.json"),
+          {},
+        ).value;
         const progress = readJsonFileResilient<Record<string, unknown>>(
           path.join(stateDir, "progress.json"),
           {},
@@ -99,6 +104,9 @@ export function readActorInspectorRuns(
         ).value;
         return [{
           run: entry.name,
+          ...(typeof runMeta.run_instance_id === "string"
+            ? { runInstanceId: runMeta.run_instance_id }
+            : {}),
           status: String(progress.phase ?? (Object.keys(result).length ? "terminal" : "unknown")),
           ...(typeof progress.updatedAt === "string"
             ? { updatedAt: progress.updatedAt }
@@ -107,15 +115,82 @@ export function readActorInspectorRuns(
               : {}),
         }];
       })
-      .sort((left, right) =>
-        String(left.updatedAt ?? "").localeCompare(String(right.updatedAt ?? "")),
-      );
+      .sort((left, right) => {
+        const recency = String(right.updatedAt ?? "").localeCompare(
+          String(left.updatedAt ?? ""),
+        );
+        return recency || right.run.localeCompare(left.run);
+      });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
     return [];
   }
 }
 
+export interface ActorInspectorRecipeView {
+  composition: Array<Record<string, unknown>>;
+  definition?: Record<string, unknown>;
+  diagnostics: string[];
+  identity: Record<string, unknown>;
+  launch: Record<string, unknown>;
+}
+
+export function readActorInspectorRecipe(
+  stateDir: string,
+): ActorInspectorRecipeView {
+  const result = readJsonFileResilient<Record<string, unknown>>(
+    path.join(stateDir, "run.json"),
+    {},
+  );
+  const meta = result.value;
+  const contexts = Array.isArray(meta.recipe_context_records)
+    ? meta.recipe_context_records
+        .filter((entry): entry is Record<string, unknown> =>
+          Boolean(entry && typeof entry === "object" && !Array.isArray(entry)),
+        )
+    : [];
+  const primary = contexts.find((entry) => entry.depth === 0) ?? contexts[0];
+  const definition = primary?.recipe && typeof primary.recipe === "object" &&
+      !Array.isArray(primary.recipe)
+    ? primary.recipe as Record<string, unknown>
+    : undefined;
+  const redacted = (value: unknown): unknown =>
+    SessionEvidence.redactSessionEvidenceValue(value);
+  const redactedRecord = (value: Record<string, unknown>): Record<string, unknown> =>
+    redacted(Object.fromEntries(
+      Object.entries(value).filter(([, entry]) => entry !== undefined),
+    )) as Record<string, unknown>;
+  return {
+    composition: contexts.map((entry) => redactedRecord({
+      ...(typeof entry.alias === "string" ? { alias: entry.alias } : {}),
+      depth: entry.depth,
+      file: entry.file,
+      import_path: entry.import_path,
+      name: entry.name,
+    })),
+    ...(definition
+      ? { definition: redactedRecord(definition) }
+      : {}),
+    diagnostics: result.diagnostics.map((diagnostic) => diagnostic.message),
+    identity: redactedRecord({
+      run: meta.run,
+      recipe: meta.recipe,
+      recipe_file: meta.recipe_file,
+      launch_source: meta.launch_source,
+    }),
+    launch: redactedRecord({
+      cwd: meta.cwd,
+      template: meta.template,
+      values: meta.values,
+      model_policy: meta.model_policy,
+      mailbox: meta.mailbox,
+      artifacts: meta.artifacts,
+      notification_policy: meta.notification_policy,
+      retire_when: meta.retire_when,
+    }),
+  };
+}
+
 export interface ActorInspectorTurnItem extends SessionEvidence.SessionEvidenceTurn {
   commandId: string;
   diagnostics: string[];

package/lib/observability.ts

@@ -43,6 +43,7 @@ export interface RunObservation {
   artifacts?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
+  notificationPolicy?: "normal" | "silent";
   recipeFile?: string;
   terminalHandled?: boolean;
   retireWhen?: string;
@@ -101,15 +102,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 +139,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 +222,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 +317,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 {
@@ -365,6 +532,9 @@ function observeRun(stateDir: string): RunObservation | undefined {
       !Array.isArray(status.model_policy)
         ? { modelPolicy: status.model_policy as Record<string, unknown> }
         : {}),
+      ...(status.notification_policy === "silent"
+        ? { notificationPolicy: "silent" as const }
+        : {}),
       ...(typeof status.recipe_file === "string"
         ? { recipeFile: status.recipe_file }
         : {}),
@@ -753,7 +923,11 @@ export function detectRunTransitions(
   for (const run of summary.runs) {
     const key = runObservationKey(run);
     const old = previous.get(key);
-    if (!run.terminalHandled && TERMINAL.has(run.status)) {
+    if (
+      run.notificationPolicy !== "silent" &&
+      !run.terminalHandled &&
+      TERMINAL.has(run.status)
+    ) {
       transitions.push({
         from: old ?? "running",
         run: run.run,
@@ -871,6 +1045,11 @@ export function detectRunOutboxEvents(
     const key = run.stateDir ?? run.run;
     const records = readOutboxRecords(run);
     const previousCount = previousLineCounts.get(key) ?? 0;
+    if (run.notificationPolicy === "silent") {
+      previousLineCounts.set(key, records.length);
+      seenEventIds.set(key, seenEventIds.get(key) ?? new Set<string>());
+      continue;
+    }
     const start = Math.min(previousCount, records.length);
     const seen = seenEventIds.get(key) ?? new Set<string>();
     for (let index = start; index < records.length; index += 1) {

package/lib/paths.ts

@@ -17,6 +17,13 @@ export function getAgentDir(
     : join(homedir(), ".pi", "agent");
 }
 
+export function isAutomaticRecipeReviewEnabled(
+  env: Record<string, string | undefined> = process.env,
+): boolean {
+  const value = env.PI_ACTORS_AUTOMATIC_REVIEW?.trim().toLowerCase();
+  return value === undefined || !["0", "false", "off"].includes(value);
+}
+
 export interface ExtensionRuntimePaths {
   configPath: string;
   runStateRoot: string;
@@ -38,6 +45,42 @@ export function getRunStateRoot(agentDir = getAgentDir()): string {
   return join(getExtensionTmpDir(agentDir), "runs");
 }
 
+export function getDraftSleepRoot(agentDir = getAgentDir()): string {
+  return join(getExtensionTmpDir(agentDir), "draft-sleep");
+}
+
+export function getDraftSleepStatePath(agentDir = getAgentDir()): string {
+  return join(getDraftSleepRoot(agentDir), "state.json");
+}
+
+export function getDraftSleepBatchDir(
+  batchId: string,
+  agentDir = getAgentDir(),
+): string {
+  if (!/^[a-f0-9-]{36}$/u.test(batchId)) {
+    throw new Error("Invalid draft sleep batch id.");
+  }
+  return join(getDraftSleepRoot(agentDir), "batches", batchId);
+}
+
+export function getToolReviewRoot(agentDir = getAgentDir()): string {
+  return join(getExtensionTmpDir(agentDir), "tool-review");
+}
+
+export function getToolReviewStatePath(agentDir = getAgentDir()): string {
+  return join(getToolReviewRoot(agentDir), "state.json");
+}
+
+export function getToolReviewBatchDir(
+  reviewId: string,
+  agentDir = getAgentDir(),
+): string {
+  if (!/^[a-f0-9-]{36}$/u.test(reviewId)) {
+    throw new Error("Invalid tool review id.");
+  }
+  return join(getToolReviewRoot(agentDir), "batches", reviewId);
+}
+
 export function getExtensionRuntimePaths(
   agentDir = getAgentDir(),
 ): ExtensionRuntimePaths {

package/lib/recipes-discovery.ts

@@ -703,32 +703,40 @@ function templatePreview(value: unknown): string | undefined {
 
 export function listDraftRecipes(root: string): Array<Record<string, unknown>> {
   return listRecipeFiles(root).map((path) => {
-    const id = RecipesReferences.getRecipeIdFromPath(path);
-    const bytes = readFileSync(path);
-    const stat = statSync(path);
-    const config = RecipesReferences.readRawRecipeConfig(path);
-    const resolved = RecipesReferences.readResolvedRecipeConfig(path);
-    const diagnostics = getRecipeConfigDiagnostics(path, resolved);
-    const sourceRun = String(config?.description ?? "").match(
-      /spawn run ([^\s]+)/,
-    )?.[1];
-    const preview = templatePreview(config?.template);
-    const riskLabels = getRecipeRiskLabels(resolved);
-    return {
-      id,
-      path,
-      sha256: createHash("sha256").update(bytes).digest("hex"),
-      size: bytes.byteLength,
-      created_at: stat.birthtime.toISOString(),
-      modified_at: stat.mtime.toISOString(),
-      valid: Boolean(resolved),
-      diagnostics,
-      ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
-      ...(config?.description ? { description: config.description } : {}),
-      ...(sourceRun ? { source_run: sourceRun } : {}),
-      ...(config?.async !== undefined ? { async: config.async } : {}),
-      ...(preview ? { template_preview: preview } : {}),
-    };
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const id = RecipesReferences.getRecipeIdFromPath(path);
+      const bytes = readFileSync(path);
+      const fingerprint = createHash("sha256").update(bytes).digest("hex");
+      const stat = statSync(path);
+      const config = RecipesReferences.readRawRecipeConfig(path);
+      const resolved = RecipesReferences.readResolvedRecipeConfig(path);
+      const diagnostics = getRecipeConfigDiagnostics(path, resolved);
+      const after = readFileSync(path);
+      if (createHash("sha256").update(after).digest("hex") !== fingerprint) {
+        continue;
+      }
+      const sourceRun = String(config?.description ?? "").match(
+        /spawn run ([^\s]+)/,
+      )?.[1];
+      const preview = templatePreview(config?.template);
+      const riskLabels = getRecipeRiskLabels(resolved);
+      return {
+        id,
+        path,
+        sha256: fingerprint,
+        size: bytes.byteLength,
+        created_at: stat.birthtime.toISOString(),
+        modified_at: stat.mtime.toISOString(),
+        valid: Boolean(resolved),
+        diagnostics,
+        ...(riskLabels.length ? { risk_labels: riskLabels } : {}),
+        ...(config?.description ? { description: config.description } : {}),
+        ...(sourceRun ? { source_run: sourceRun } : {}),
+        ...(config?.async !== undefined ? { async: config.async } : {}),
+        ...(preview ? { template_preview: preview } : {}),
+      };
+    }
+    throw new Error(`Draft changed repeatedly during inventory: ${path}`);
   });
 }