@llblab/pi-actors 0.54.0 → 0.56.0

package/lib/execution-sessions.ts

@@ -7,7 +7,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { observeExecutionFileReference } from "./execution-files.ts";
 import * as SessionEvidence from "./session-evidence.ts";
+import * as Limits from "./limits.ts";
 import { readJsonFileResilient } from "./state-readers.ts";
 
 export interface ExecutionTurnItem extends SessionEvidence.SessionEvidenceTurn {
@@ -21,33 +23,48 @@ export interface ExecutionTurnItem extends SessionEvidence.SessionEvidenceTurn {
   stage?: string;
 }
 
-function ownedSessionPath(
-  stateDir: string,
-  sessionFile: string,
-): string | undefined {
-  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;
-  } catch {
-    return undefined;
-  }
+export const EXECUTION_CHRONOLOGY = Symbol("execution-session-chronology");
+export interface ExecutionChronologyEntry extends SessionEvidence.SessionChronologyEntry {
+  commandId: string;
+  sessionFile: string;
+  sessionOrdinal: number;
 }
+export type ExecutionChronology = Readonly<{
+  basis: "recorded_execution_metadata";
+  entries: readonly Readonly<ExecutionChronologyEntry>[];
+} & ({ state: "available" } | { state: "unavailable"; reason: SessionEvidence.SessionChronologyReason | "source_changed" | "namespace_unavailable" })>;
+export type ExecutionTurnCollection = ExecutionTurnItem[] & { readonly [EXECUTION_CHRONOLOGY]?: ExecutionChronology };
 
-export function readExecutionTurns(stateDir: string): ExecutionTurnItem[] {
-  const execution = readJsonFileResilient<Record<string, unknown>>(
+export function readExecutionTurns(stateDir: string): ExecutionTurnCollection {
+  const read = readJsonFileResilient<Record<string, unknown>>(
     path.join(stateDir, "execution.json"),
     {},
-  ).value;
+  );
+  const execution = read.value;
+  const basis = "recorded_execution_metadata" as const;
+  let reason: Extract<ExecutionChronology, { state: "unavailable" }>["reason"] | undefined = read.diagnostics.length ? "source_unavailable" : undefined;
+  const metadata: Readonly<ExecutionChronologyEntry>[] = [];
+  let metadataBytes = Buffer.byteLength(JSON.stringify({ state: "available", basis, entries: [] }));
+  const refuse = (next: NonNullable<typeof reason>): void => { reason ??= next; metadata.length = 0; };
+  const collect = (commandId: string, sessionFile: string, frame: SessionEvidence.SessionChronology | undefined): void => {
+    if (reason) return;
+    if (!frame || frame.state !== "available") { refuse(frame?.state === "unavailable" ? frame.reason : "source_unavailable"); return; }
+    if (SessionEvidence.redactSessionEvidenceValue(commandId) !== commandId || SessionEvidence.redactSessionEvidenceValue(sessionFile) !== sessionFile) {
+      refuse("namespace_unavailable"); return;
+    }
+    for (const item of frame.entries) {
+      const entry = Object.freeze({ ...item, commandId, sessionFile, sessionOrdinal: item.ordinal, ordinal: metadata.length + 1 });
+      metadataBytes += Buffer.byteLength(JSON.stringify(entry)) + Number(metadata.length > 0);
+      if (metadataBytes > Limits.SESSION_EVIDENCE_MAX_BYTES) { refuse("metadata_too_large"); return; }
+      metadata.push(entry);
+    }
+  };
   const commands = Array.isArray(execution.commands)
     ? (execution.commands as Array<Record<string, unknown>>)
     : [];
+  if ((execution.commands !== undefined && !Array.isArray(execution.commands)) || commands.some((command) =>
+    !command || typeof command !== "object" || Array.isArray(command) ||
+    (command.session_files !== undefined && (!Array.isArray(command.session_files) || command.session_files.some((file) => typeof file !== "string"))))) refuse("source_unavailable");
   const recordedFiles = new Set(
     commands.flatMap((command) =>
       (Array.isArray(command.session_files) ? command.session_files : []).filter(
@@ -57,8 +74,13 @@ export function readExecutionTurns(stateDir: string): ExecutionTurnItem[] {
   );
   let discoveredCommands: Array<Record<string, unknown>> = [];
   try {
-    const sessionsDir = path.join(stateDir, "sessions");
-    discoveredCommands = fs
+    const state = path.resolve(stateDir);
+    const sessionsDir = path.join(state, "sessions");
+    const root = fs.lstatSync(state);
+    const rootObserved = root.isDirectory() && !root.isSymbolicLink();
+    const namespace = fs.lstatSync(sessionsDir, { throwIfNoEntry: false });
+    if (!rootObserved || (namespace && (!namespace.isDirectory() || namespace.isSymbolicLink()))) refuse("source_unavailable");
+    discoveredCommands = rootObserved && namespace?.isDirectory() && !namespace.isSymbolicLink() ? fs
       .readdirSync(sessionsDir, { withFileTypes: true })
       .filter((entry) => entry.isDirectory())
       .flatMap((entry) => {
@@ -72,18 +94,22 @@ export function readExecutionTurns(stateDir: string): ExecutionTurnItem[] {
         return files.length > 0
           ? [{ id: entry.name, session_files: files, stage: "subagent" }]
           : [];
-      });
+      }) : [];
   } catch {
+    refuse("source_unavailable");
     discoveredCommands = [];
   }
-  return [...commands, ...discoveredCommands]
+  const turns: ExecutionTurnCollection = [...commands, ...discoveredCommands]
     .flatMap((command) =>
       (Array.isArray(command.session_files) ? command.session_files : [])
         .filter((file): file is string => typeof file === "string")
         .flatMap((file) => {
-          const sessionPath = ownedSessionPath(stateDir, file);
-          if (!sessionPath) return [];
-          const session = SessionEvidence.readSessionEvidence(sessionPath);
+          const reference = observeExecutionFileReference(stateDir, { kind: "session", path: file });
+          if (reference.availability !== "available") { refuse("source_unavailable"); return []; }
+          const session = SessionEvidence.readSessionEvidence(reference.local_path);
+          if (!reference.unchanged()) { refuse("source_changed"); return []; }
+          if (typeof command.id !== "string" || !command.id) refuse("namespace_unavailable");
+          else collect(command.id, file, session[SessionEvidence.SESSION_EVIDENCE_CHRONOLOGY]);
           return session.turns.map((turn) => ({
             ...turn,
             commandId: String(command.id ?? "unknown"),
@@ -108,4 +134,8 @@ export function readExecutionTurns(stateDir: string): ExecutionTurnItem[] {
         }),
     )
     .map((turn, index) => ({ ...turn, index: index + 1 }));
+  Object.defineProperty(turns, EXECUTION_CHRONOLOGY, { value: Object.freeze(reason
+    ? { state: "unavailable", basis, reason, entries: Object.freeze([]) }
+    : { state: "available", basis, entries: Object.freeze(metadata) }) });
+  return turns;
 }

package/lib/execution.ts

@@ -1084,6 +1084,8 @@ export async function executeRegisteredTool(
   exec: RegisteredToolExec,
   cwd: string,
   signal?: AbortSignal,
+  kernel?: { readonly onPrimaryCommandSelected?: (result: Readonly<ToolExecResult>) => void | Promise<void>;
+    readonly onFinalResponseSelected?: (text: string, upstreamTruncated: boolean) => void | Promise<void> },
 ): Promise<RegisteredToolExecutionResult> {
   const executed = await executeTemplateSteps(
     cfg,
@@ -1126,6 +1128,12 @@ export async function executeRegisteredTool(
       },
     });
   }
+  // Only the plain successful leaf is admitted initially; compositions/acceptance policies are separate contracts.
+  if (typeof cfg.template === "string" && executed.commands.length === 1 && !executed.failures.length) {
+    await kernel?.onPrimaryCommandSelected?.(result);
+  }
+  await kernel?.onFinalResponseSelected?.(result.stdout, result.stdoutTruncated === true || executed.branches.some(branch =>
+    branch.status !== "done" && (branch.stderrTruncated === true || branch.stderrBytes > Buffer.byteLength(branch.stderr ?? ""))));
   const formatted = formatOutput(cfg.name, "stdout", result.stdout);
   const templateWarnings = CommandTemplates.getCommandTemplateWarnings(
     createTemplateConfig(cfg),

package/lib/extension-runtime.ts

@@ -4,6 +4,8 @@
  * Owns low-level Pi lifecycle effects and tool wrapping without owning event registration.
  */
 
+import { join } from "node:path";
+
 import * as AutomaticReviewRuntime from "./automatic-review-runtime.ts";
 import * as CommandTemplates from "./command-templates.ts";
 import * as Paths from "./paths.ts";
@@ -14,8 +16,16 @@ import * as RecipesReferences from "./recipes-references.ts";
 import * as RunUiRuntime from "./run-ui-runtime.ts";
 import * as Runtime from "./runtime.ts";
 import * as Temp from "./temp.ts";
+import * as RunRetention from "./runs-retention.ts";
 import * as Tools from "./tools.ts";
 import * as ToolsResponse from "./tools-response.ts";
+import {
+  createRunSupervisionOwner,
+  type RunSupervisionOwner,
+  type RunSupervisionOwnerSnapshotReading,
+} from "./runs-supervision.ts";
+import type { RunSupervisionControllerPorts } from "./run-supervision.ts";
+import type { AsyncRunStartOptions } from "./async-runs.ts";
 
 export interface ActorExtensionRuntime {
   beforeAgentStart(
@@ -26,23 +36,62 @@ export interface ActorExtensionRuntime {
   discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
   getRunOwnerId(ctx: Pi.ExtensionContext): string;
   onAgentSettled(ctx: Pi.ExtensionContext): void;
+  onTurnEnd(event: Pi.TurnEndEvent, ctx: Pi.ExtensionContext): Pi.TurnEndEventResult | undefined;
   onContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
   onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
-  onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
+  onSessionStart(ctx: Pi.ExtensionContext, event?: Pi.SessionStartEvent): Promise<void>;
   registerCoreTools(): void;
+  /** Private kernel observation only; no public tool route or reconstructed origin. */
+  observeRunSnapshot(expected: unknown, capturedAt: unknown, stateDir?: string): Readonly<RunSupervisionOwnerSnapshotReading>;
+  getRunAdmissionObserver(ctx: Pi.ExtensionContext): AsyncRunStartOptions["onSupervisionClockCaptured"];
 }
 
 export function createActorExtensionRuntime(
   pi: Pi.ExtensionAPI,
+  supervisionPorts?: Omit<RunSupervisionControllerPorts, "readCurrent">,
+  completionStreamSessionAdmission?: RunUiRuntime.RunUiRuntimeDeps["completionStreamSessionAdmission"],
+  captureCompletionBatch?: RunUiRuntime.RunUiRuntimeDeps["captureCompletionBatch"],
 ): ActorExtensionRuntime {
   let activeRunContext: Pi.ExtensionContext | undefined;
   let activeRunOwnerId: string | undefined;
-  const runOwnerIdsByContext = new WeakMap<Pi.ExtensionContext, string>();
+  let sessionStartTicket: object | undefined;
+  type ParentSession = {
+    ownerId: string;
+    sessionManager: Pi.ExtensionContext["sessionManager"];
+    shutdownAdmitted: boolean;
+  };
+  let parentSession: ParentSession | undefined;
+  const parentSessionsByContext = new WeakMap<Pi.ExtensionContext, ParentSession>();
+  const seenParentManagers = new WeakSet<Pi.ExtensionContext["sessionManager"]>();
   const recipeResolutionContextsBySession = new Map<
     string,
     RecipeResolution.RecipeResolutionContext
   >();
   const getRunOwnerId = Pi.getSessionId;
+  let supervision: {
+    context: Pi.ExtensionContext;
+    ownerId: string;
+    owner: Readonly<RunSupervisionOwner>;
+    ready: boolean;
+    sessionManager: Pi.ExtensionContext["sessionManager"];
+  } | undefined;
+  const closeSupervision = (): void => {
+    const scope = supervision;
+    supervision = undefined;
+    scope?.owner.close();
+  };
+  const getRunAdmissionObserver = (ctx: Pi.ExtensionContext): AsyncRunStartOptions["onSupervisionClockCaptured"] => {
+    if (!supervisionPorts) return undefined;
+    const scope = supervision;
+    const sessionManager = ctx.sessionManager;
+    const ownerId = sessionManager.getSessionId();
+    return capture => {
+      if (!scope || supervision !== scope || !scope.ready || scope.sessionManager !== sessionManager || scope.ownerId !== ownerId || capture.identity.ownerId !== ownerId) {
+        throw new Error("Run supervision coordinator admission is unavailable or changed.");
+      }
+      scope.owner.onSupervisionClockCaptured(capture);
+    };
+  };
   const getRecipeResolutionContext = (ctx: Pi.ExtensionContext) => {
     const sessionId = getRunOwnerId(ctx);
     const resolutionContext = recipeResolutionContextsBySession.get(sessionId);
@@ -57,6 +106,7 @@ export function createActorExtensionRuntime(
     getActiveContext: () => activeRunContext,
     getRunOwnerId,
     getThinkingLevel: () => pi.getThinkingLevel(),
+    getRunAdmissionObserver,
   });
   let recipeReload: Runtime.RecipeToolReloadWatcher | undefined;
   let runUiRuntime: RunUiRuntime.RunUiRuntime;
@@ -64,12 +114,16 @@ export function createActorExtensionRuntime(
     const ownerId = activeRunOwnerId;
     activeRunContext = undefined;
     activeRunOwnerId = undefined;
+    sessionStartTicket = undefined;
     runUiRuntime?.close();
     automaticReview.close();
     recipeReload?.close();
     if (ownerId) recipeResolutionContextsBySession.delete(ownerId);
   };
+  RunUiRuntime.registerRunCompletionRenderer(pi);
   runUiRuntime = RunUiRuntime.createRunUiRuntime({
+    completionStreamSessionAdmission,
+    captureCompletionBatch,
     getActiveContext: () => activeRunContext,
     onCallbackError: closeActiveSessionRuntimes,
     onRunEvent: automaticReview.schedule,
@@ -93,6 +147,7 @@ export function createActorExtensionRuntime(
               ctx as Pi.ExtensionContext,
             ),
             getThinkingLevel: () => pi.getThinkingLevel(),
+            onSupervisionClockCaptured: getRunAdmissionObserver(ctx as Pi.ExtensionContext),
           };
         }
         try {
@@ -142,22 +197,55 @@ export function createActorExtensionRuntime(
       return skillPaths.length > 0 ? { skillPaths } : undefined;
     },
     getRunOwnerId,
+    getRunAdmissionObserver,
+    observeRunSnapshot(expected, capturedAt, stateDir) {
+      return supervision?.owner.observeSnapshot(expected, capturedAt, stateDir) ?? Object.freeze({ state: "unavailable", reason: "origin_not_retained" });
+    },
     onAgentSettled(ctx) {
+      if ((completionStreamSessionAdmission || captureCompletionBatch) && !runUiRuntime.isCurrentSessionContext(ctx)) return;
       if (!activeRunOwnerId || getRunOwnerId(ctx) !== activeRunOwnerId) return;
       if (!runUiRuntime.flushCompletionBatch(ctx)) automaticReview.schedule();
     },
+    onTurnEnd(event, ctx) {
+      return runUiRuntime.onTurnEnd(event, ctx);
+    },
     onContext(messages, ctx) {
       return runUiRuntime.projectContext(messages, ctx);
     },
     onSessionShutdown(reason, ctx) {
-      const ownerId = runOwnerIdsByContext.get(ctx);
-      runOwnerIdsByContext.delete(ctx);
-      if (activeRunContext === ctx) closeActiveSessionRuntimes();
-      if (ownerId) recipeResolutionContextsBySession.delete(ownerId);
-      runUiRuntime.shutdown(reason, ownerId, ctx);
+      const scope = parentSession;
+      if (!scope?.shutdownAdmitted) return;
+      const known = parentSessionsByContext.get(ctx);
+      if (known && known !== scope) return;
+      if (!known) {
+        try {
+          if (ctx.sessionManager !== scope.sessionManager || scope.sessionManager.getSessionId() !== scope.ownerId) return;
+        } catch { return; /* Unknown invalidated wrappers cannot identify this lifetime. */ }
+      }
+      if (parentSession !== scope) return;
+      // Consume before cleanup/teardown: stale or reentrant callbacks cannot stop a replacement.
+      scope.shutdownAdmitted = false;
+      parentSessionsByContext.set(ctx, scope);
+      closeSupervision();
+      if (parentSession !== scope) return;
+      closeActiveSessionRuntimes();
+      if (parentSession !== scope) return;
+      recipeResolutionContextsBySession.delete(scope.ownerId);
+      runUiRuntime.shutdown(reason, scope.ownerId, ctx);
     },
-    async onSessionStart(ctx) {
-      const sessionId = getRunOwnerId(ctx);
+    async onSessionStart(ctx, event) {
+      const ticket = {};
+      sessionStartTicket = ticket;
+      parentSession = undefined;
+      const sessionManager = ctx.sessionManager;
+      const sessionId = sessionManager.getSessionId();
+      if (sessionStartTicket !== ticket) return;
+      const scopeBinding: ParentSession = { ownerId: sessionId, sessionManager,
+        shutdownAdmitted: !seenParentManagers.has(sessionManager) && !parentSessionsByContext.has(ctx) };
+      seenParentManagers.add(sessionManager);
+      if (!parentSessionsByContext.has(ctx)) parentSessionsByContext.set(ctx, scopeBinding);
+      parentSession = scopeBinding;
+      closeSupervision();
       recipeResolutionContextsBySession.set(
         sessionId,
         RecipeResolution.createEmptyRecipeResolutionContext(sessionId, ctx.cwd),
@@ -165,14 +253,20 @@ export function createActorExtensionRuntime(
       ctx.ui.setWidget("zz-pi-actors-comms", undefined);
       activeRunContext = ctx;
       activeRunOwnerId = sessionId;
-      runOwnerIdsByContext.set(ctx, sessionId);
       runUiRuntime.close();
       automaticReview.close();
       recipeReload.close();
+      const scope = supervisionPorts ? {
+        context: ctx, ownerId: sessionId, owner: createRunSupervisionOwner(supervisionPorts),
+        ready: false, sessionManager,
+      } : undefined;
+      supervision = scope;
       await Temp.prepareExtensionTempDir(Paths.EXTENSION_RUNTIME_PATHS.tempDir);
-      if (activeRunContext !== ctx || activeRunOwnerId !== sessionId) return;
+      await RunRetention.cleanupStaleRunEntries(join(Paths.EXTENSION_RUNTIME_PATHS.tempDir, "runs"));
+      if (sessionStartTicket !== ticket || activeRunContext !== ctx || activeRunOwnerId !== sessionId || supervision !== scope) return;
+      if (scope) scope.ready = true;
       automaticReview.start(ctx);
-      runUiRuntime.start(ctx, sessionId);
+      runUiRuntime.start(ctx, sessionId, event);
       recipeReload.watch(ctx);
     },
     registerCoreTools() {

package/lib/file-state.ts

@@ -260,10 +260,19 @@ export function withFileMutationLock<T>(
   options: FileMutationLockOptions = {},
 ): T {
   const release = acquireFileMutationLock(path, options);
+  let mutationFailed = false, mutationFailure: unknown;
   try {
     return mutate();
+  } catch (error) {
+    mutationFailed = true; mutationFailure = error;
+    throw error;
   } finally {
-    release();
+    try { release(); }
+    catch (releaseError) {
+      if (mutationFailed) throw new AggregateError([mutationFailure, releaseError],
+        "File mutation callback and lock release failed; effects may already exist.", { cause: mutationFailure });
+      throw releaseError;
+    }
   }
 }
 
@@ -273,7 +282,12 @@ function replaceFileWithRetry(source: string, target: string): void {
       renameSync(source, target);
       return;
     } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
+      let code: unknown;
+      try { code = (error as NodeJS.ErrnoException | null | undefined)?.code; }
+      catch (observationError) {
+        throw new AggregateError([error, observationError],
+          "File replacement failed and retry-code inspection also failed; effects may already exist.", { cause: error });
+      }
       if ((code !== "EPERM" && code !== "EBUSY") || attempt >= 19) throw error;
       Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
     }

package/lib/inspector-command.ts

@@ -5,7 +5,7 @@
  */
 
 import * as AsyncRuns from "./async-runs.ts";
-import * as InspectorActions from "./inspector-actions.ts";
+import * as Inspector from "./inspector.ts";
 import * as InspectorOverlay from "./inspector-overlay.ts";
 import * as Paths from "./paths.ts";
 import type * as Pi from "./pi.ts";
@@ -23,7 +23,7 @@ export function registerActorInspectorCommand(
           new InspectorOverlay.ActorInspectorOverlay({
             done,
             killRun: (run, runInstanceId) =>
-              InspectorActions.killOwnedRunFromInspector(
+              Inspector.killOwnedRunFromInspector(
                 getRunOwnerId(ctx),
                 run,
                 Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,