@llblab/pi-actors 0.41.1 → 0.42.1

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 }
@@ -119,6 +127,70 @@ export function readActorInspectorRuns(
   }
 }
 
+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[];
@@ -176,7 +248,7 @@ export function readActorInspectorTurns(stateDir: string): ActorInspectorTurnIte
             withFileTypes: true,
           })
           .filter((file) => file.isFile() && file.name.endsWith(".jsonl"))
-          .map((file) => path.join("sessions", entry.name, file.name))
+          .map((file) => path.posix.join("sessions", entry.name, file.name))
           .filter((file) => !recordedFiles.has(file));
         return files.length > 0
           ? [{ id: entry.name, session_files: files, stage: "subagent" }]

package/lib/observability.ts

@@ -5,9 +5,13 @@
  */
 
 import {
+  closeSync,
   existsSync,
+  fstatSync,
+  openSync,
   readdirSync,
   readFileSync,
+  readSync,
   watch,
   type FSWatcher,
 } from "node:fs";
@@ -41,12 +45,15 @@ export interface RunObservation {
   failures?: number;
   ownerId?: string;
   artifacts?: Record<string, string>;
+  launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
+  notificationPolicy?: "normal" | "silent";
   recipeFile?: string;
   terminalHandled?: boolean;
   retireWhen?: string;
   run: string;
+  semanticResult?: RunTerminalSemanticResult;
   tool?: string;
   stateDir?: string;
   status: RunObservedStatus;
@@ -161,6 +168,19 @@ export function deliverRunTransitionNotifications(
           transition.to,
         );
       }
+    } catch (error) {
+      if (transition.stateDir) {
+        AsyncRuns.recordRunTerminalDeliveryFailure(
+          transition.stateDir,
+          transition.to,
+          error,
+        );
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      sink.notify(
+        `Actor terminal delivery failed for run:${transition.run}: ${message.replaceAll(/\s+/g, " ").slice(0, 240)}`,
+        "error",
+      );
     } finally {
       inFlight.delete(key);
     }
@@ -419,12 +439,23 @@ export interface RunTransition {
   run: string;
   stateDir?: string;
   artifacts?: Record<string, string>;
+  launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
   modelPolicy?: Record<string, unknown>;
   recipeFile?: string;
   terminalHandled?: boolean;
   to: RunObservedStatus;
   tool?: string;
+  semanticResult?: RunTerminalSemanticResult;
+}
+
+export interface RunTerminalSemanticResult {
+  body?: string;
+  correlationId?: string;
+  metadata: Record<string, unknown>;
+  summary: string;
+  synthesized: boolean;
+  type: string;
 }
 
 export interface RunOutboxEvent {
@@ -503,15 +534,145 @@ function scanRunStateDirs(
   return result;
 }
 
+const TERMINAL_RESULT_BYTES = 8 * 1024;
+const TERMINAL_RESULT_CHARS = 4_000;
+
+function readBoundedStart(path: string): string {
+  if (!existsSync(path)) return "";
+  const fd = openSync(path, "r");
+  try {
+    const size = Math.min(fstatSync(fd).size, TERMINAL_RESULT_BYTES);
+    const buffer = Buffer.alloc(size);
+    const bytes = readSync(fd, buffer, 0, size, 0);
+    const text = buffer.subarray(0, bytes).toString("utf8").trim();
+    return text.length > TERMINAL_RESULT_CHARS
+      ? `${text.slice(0, TERMINAL_RESULT_CHARS - 1)}…`
+      : text;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function semanticBodyFromStdout(stateDir: string): string | undefined {
+  const text = readBoundedStart(join(stateDir, "stdout.log"));
+  if (!text) return undefined;
+  const withoutMarker = text.replace(/^ACTOR_REVIEW_RESULT\s*(?:\r?\n)?/, "").trim();
+  return withoutMarker || undefined;
+}
+
+function terminalSemanticResult(
+  status: Record<string, unknown>,
+  stateDir: string,
+  observedStatus: RunObservedStatus,
+): RunTerminalSemanticResult {
+  const correlation = status.launch_correlation &&
+    typeof status.launch_correlation === "object" &&
+    !Array.isArray(status.launch_correlation)
+    ? status.launch_correlation as Record<string, unknown>
+    : {};
+  const correlationId =
+    typeof correlation.correlation_id === "string"
+      ? correlation.correlation_id
+      : typeof correlation.tool_call_id === "string"
+        ? correlation.tool_call_id
+        : undefined;
+  const mailbox = status.mailbox &&
+    typeof status.mailbox === "object" &&
+    !Array.isArray(status.mailbox)
+    ? status.mailbox as Record<string, unknown>
+    : {};
+  const emits = Array.isArray(mailbox.emits)
+    ? mailbox.emits.filter((item): item is string => typeof item === "string")
+    : [];
+  const outbox = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "outbox.jsonl"),
+  ).records;
+  const explicit = outbox.findLast((record) => {
+    const type = String(record.type ?? record.event ?? "");
+    return emits.includes(type) && !["command.done", "run.done", "run.failed"].includes(type);
+  });
+  if (explicit) {
+    const type = String(explicit.type ?? explicit.event);
+    return {
+      ...(explicit.body === undefined
+        ? {} : { body: formatSemanticBody(explicit.body) }),
+      ...(typeof explicit.correlation_id === "string"
+        ? { correlationId: explicit.correlation_id } : correlationId ? { correlationId } : {}),
+      metadata: {
+        ...(explicit.metadata &&
+        typeof explicit.metadata === "object" &&
+        !Array.isArray(explicit.metadata)
+          ? explicit.metadata as Record<string, unknown> : {}),
+        ...(status.transport_context &&
+        typeof status.transport_context === "object" &&
+        !Array.isArray(status.transport_context)
+          ? {
+              transport_context: status.transport_context as Record<string, unknown>,
+            } : {}),
+        run: String(status.run ?? ""),
+        status: observedStatus,
+      },
+      summary: String(explicit.summary ?? type),
+      synthesized: false,
+      type,
+    };
+  }
+  const reviewCompleted = observedStatus === "done" && emits.includes("review.completed");
+  const result = status.result &&
+    typeof status.result === "object" &&
+    !Array.isArray(status.result)
+    ? status.result as Record<string, unknown>
+    : {};
+  const type = reviewCompleted
+    ? "review.completed"
+    : observedStatus === "done" ? "run.done" : "run.failed";
+  const stdoutBody = observedStatus === "done"
+    ? semanticBodyFromStdout(stateDir) : undefined;
+  return {
+    ...(stdoutBody
+      ? { body: stdoutBody }
+      : typeof result.error === "string" ? { body: result.error } : {}),
+    ...(correlationId ? { correlationId } : {}),
+    metadata: {
+      ...(status.transport_context &&
+      typeof status.transport_context === "object" &&
+      !Array.isArray(status.transport_context)
+        ? {
+            transport_context: status.transport_context as Record<string, unknown>,
+          } : {}),
+      run: String(status.run ?? ""), status: observedStatus,
+    },
+    summary: reviewCompleted ? "Review completed." :
+      observedStatus === "done" ? "Run completed." : `Run ${observedStatus}.`,
+    synthesized: true,
+    type,
+  };
+}
+
+function formatSemanticBody(body: unknown): string {
+  const rendered = typeof body === "string" ? body : JSON.stringify(body);
+  const text = typeof rendered === "string" ? rendered : String(body);
+  const compact = text.trim();
+  return compact.length > TERMINAL_RESULT_CHARS
+    ? `${compact.slice(0, TERMINAL_RESULT_CHARS - 1)}…`
+    : compact;
+}
+
 function observeRun(stateDir: string): RunObservation | undefined {
   try {
     const status = AsyncRuns.getRunStatus(stateDir);
     const progress = getProgress(status);
     const run = typeof status.run === "string" ? status.run : undefined;
     if (!run) return undefined;
+    const observedStatus = status.status as RunObservedStatus;
     return {
       activeSubagents: toNumber(progress.activeSubagents),
       completed: toNumber(progress.completed),
+      ...(status.launch_correlation &&
+      typeof status.launch_correlation === "object" &&
+      !Array.isArray(status.launch_correlation)
+        ? { launchCorrelation: status.launch_correlation as Record<string, string> }
+        : {}),
       failures: Array.isArray(progress.failures)
         ? progress.failures.length
         : undefined,
@@ -531,6 +692,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 }
         : {}),
@@ -538,9 +702,12 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(typeof status.retire_when === "string"
         ? { retireWhen: status.retire_when }
         : {}),
+      ...(TERMINAL.has(observedStatus)
+        ? { semanticResult: terminalSemanticResult(status, stateDir, observedStatus) }
+        : {}),
       run,
       stateDir,
-      status: status.status as RunObservedStatus,
+      status: observedStatus,
       ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
       updatedAt: getUpdatedAt(status),
     };
@@ -919,15 +1086,21 @@ 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,
         ...(run.stateDir ? { stateDir: run.stateDir } : {}),
         ...(run.artifacts ? { artifacts: run.artifacts } : {}),
+        ...(run.launchCorrelation ? { launchCorrelation: run.launchCorrelation } : {}),
         ...(run.launchSource ? { launchSource: run.launchSource } : {}),
         ...(run.modelPolicy ? { modelPolicy: run.modelPolicy } : {}),
         ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
+        ...(run.semanticResult ? { semanticResult: run.semanticResult } : {}),
         ...(run.terminalHandled ? { terminalHandled: true } : {}),
         to: run.status,
         ...(run.tool ? { tool: run.tool } : {}),
@@ -1037,6 +1210,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) {
@@ -1182,7 +1360,8 @@ function isUserRecipeFile(file: string | undefined): boolean {
   if (!file) return false;
   const recipeRoot = resolve(Paths.getRecipeRoot());
   const path = resolve(file);
-  return path === recipeRoot || path.startsWith(`${recipeRoot}/`);
+  const relation = relative(recipeRoot, path);
+  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
 }
 
 export function shouldSuggestRecipePersistence(
@@ -1232,16 +1411,26 @@ function formatTransitionNextActions(transition: RunTransition): string {
   return `\nNext actions: ${actions.join(" | ")}`;
 }
 
+function formatTransitionSemanticResult(transition: RunTransition): string {
+  const result = transition.semanticResult;
+  if (!result) return "";
+  const correlation = result.correlationId
+    ? `\nCorrelation: ${result.correlationId}` : "";
+  const body = result.body ? `\nResult:\n${result.body}` : "";
+  return `\nSemantic result: ${result.type} — ${result.summary}${correlation}${body}`;
+}
+
 export function formatRunTransitionMessage(transition: RunTransition): string {
   const artifacts = formatNamedArtifacts(transition.artifacts);
   const runFiles = formatRunFileList(getRunArtifacts(transition));
   const persistenceSuggestion = formatRecipePersistenceSuggestion(transition);
   const policy = formatTransitionPolicy(transition);
   const nextActions = formatTransitionNextActions(transition);
+  const semanticResult = formatTransitionSemanticResult(transition);
   if (transition.to === "done")
-    return `Run ${transition.run} completed successfully.${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
+    return `Run ${transition.run} completed successfully.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}${persistenceSuggestion}`;
   if (transition.to === "failed")
-    return `Run ${transition.run} failed.${policy}${artifacts}${runFiles}${nextActions}`;
+    return `Run ${transition.run} failed.${semanticResult}${policy}${artifacts}${runFiles}${nextActions}`;
   if (transition.to === "cancelled")
     return `Run ${transition.run} was cancelled.${policy}${nextActions}`;
   if (transition.to === "killed")

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}`);
   });
 }