@llblab/pi-actors 0.49.1 → 0.50.0

package/lib/run-ui-runtime.ts

@@ -11,25 +11,89 @@ import * as Pi from "./pi.ts";
 
 export interface RunUiRuntime {
   close(): void;
-  shutdown(eventReason: string, ctx: Pi.ExtensionContext): void;
-  start(ctx: Pi.ExtensionContext): void;
+  shutdown(
+    eventReason: string,
+    ownerId: string | undefined,
+    ctx?: Pi.ExtensionContext,
+  ): void;
+  start(ctx: Pi.ExtensionContext, ownerId: string): void;
 }
 
 export interface RunUiRuntimeDeps {
+  animationIntervalMs?: number;
+  createRunStateWatcher?: typeof Observability.createRunStateWatcher;
+  createRunTerminalReconciliationLoop?:
+    typeof Observability.createRunTerminalReconciliationLoop;
   getActiveContext(): Pi.ExtensionContext | undefined;
-  getRunOwnerId(ctx: Pi.ExtensionContext): string;
+  notificationDelayMs?: number;
+  onCallbackError?: (error: unknown) => void;
   onRunEvent(): void;
   pi: Pi.ExtensionAPI;
+  teardownRunsOwnedByParent?: typeof AsyncRuns.teardownRunsOwnedByParent;
 }
 
 export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
+  let activeContext: Pi.ExtensionContext | undefined;
+  let activeOwnerId: string | undefined;
   let animationInterval: NodeJS.Timeout | undefined;
   let notifyTimeout: NodeJS.Timeout | undefined;
+  let running = false;
   let lastWatcherDiagnosticId = 0;
   const observation = Observability.createRunUiObservationState();
   const retirementAttempts = new Set<string>();
   const terminalNotificationsInFlight = new Set<string>();
 
+  const close = (): void => {
+    running = false;
+    activeContext = undefined;
+    activeOwnerId = undefined;
+    try {
+      watcher.close();
+    } catch {
+      /* cleanup must not escape a host callback */
+    }
+    try {
+      reconciliation.close();
+    } catch {
+      /* cleanup must not escape a host callback */
+    }
+    if (notifyTimeout) clearTimeout(notifyTimeout);
+    notifyTimeout = undefined;
+    if (animationInterval) clearInterval(animationInterval);
+    animationInterval = undefined;
+  };
+  const stopAfterCallbackFailure = (
+    label: string,
+    error: unknown,
+    expectedContext: Pi.ExtensionContext,
+  ): void => {
+    if (activeContext !== expectedContext) return;
+    close();
+    try {
+      deps.onCallbackError?.(error);
+    } catch {
+      /* host callback containment must remain no-throw */
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+      expectedContext.ui.notify(`Actor ${label} failed: ${message}`, "error");
+    } catch {
+      /* stale context or unavailable UI */
+    }
+  };
+  const runActiveCallback = (
+    label: string,
+    callback: (ctx: Pi.ExtensionContext, ownerId: string) => void,
+  ): void => {
+    if (!running || !activeContext || !activeOwnerId) return;
+    const ctx = activeContext;
+    try {
+      if (deps.getActiveContext() !== ctx) return;
+      callback(ctx, activeOwnerId);
+    } catch (error) {
+      stopAfterCallbackFailure(label, error, ctx);
+    }
+  };
   const retireCandidateRuns = (
     ctx: Pi.ExtensionContext,
     summary: Observability.RunSummary,
@@ -39,14 +103,16 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       cancelRun: (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
       notify: (message, level) => ctx.ui.notify(message, level),
       sendStop: async (candidate) => AsyncRuns.cancelRun(candidate.stateDir),
-    });
+    }).catch((error) =>
+      stopAfterCallbackFailure("Run retirement callback", error, ctx),
+    );
   };
   const update = (
     ctx: Pi.ExtensionContext,
+    ownerId: string,
     notify = false,
     terminalOnly = false,
   ): void => {
-    const ownerId = deps.getRunOwnerId(ctx);
     const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
     ctx.ui.setStatus(
       "zz-pi-actors-runs",
@@ -76,61 +142,63 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     }
   };
   const scheduleUpdate = (): void => {
+    if (!running) return;
     if (notifyTimeout) clearTimeout(notifyTimeout);
     notifyTimeout = setTimeout(() => {
-      const ctx = deps.getActiveContext();
-      if (!ctx) return;
-      watcher.refresh();
-      update(ctx, true);
-      deps.onRunEvent();
-      reportDiagnostics(ctx);
-    }, 50);
+      runActiveCallback("Run watcher callback", (ctx, ownerId) => {
+        watcher.refresh();
+        update(ctx, ownerId, true);
+        deps.onRunEvent();
+        reportDiagnostics(ctx);
+      });
+    }, deps.notificationDelayMs ?? 50);
     notifyTimeout.unref?.();
   };
-  const watcher = Observability.createRunStateWatcher({
+  const watcher = (deps.createRunStateWatcher ?? Observability.createRunStateWatcher)({
     stateRoot: Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
     onChange: scheduleUpdate,
   });
-  const reconciliation = Observability.createRunTerminalReconciliationLoop({
+  const reconciliation = (
+    deps.createRunTerminalReconciliationLoop ??
+    Observability.createRunTerminalReconciliationLoop
+  )({
     onError: (error) => {
-      const ctx = deps.getActiveContext();
-      if (!ctx) return;
-      const message = error instanceof Error ? error.message : String(error);
-      ctx.ui.notify(`Actor terminal reconciliation failed: ${message}`, "error");
+      if (!running || !activeContext) return;
+      stopAfterCallbackFailure(
+        "terminal reconciliation callback",
+        error,
+        activeContext,
+      );
     },
     reconcile: () => {
-      const ctx = deps.getActiveContext();
-      if (!ctx) return;
-      Observability.reconcileRunTerminalNotifications({
-        inFlight: terminalNotificationsInFlight,
-        ownerId: deps.getRunOwnerId(ctx),
-        sink: Pi.createNotificationSink(deps.pi, ctx),
-        state: observation,
-        includeAttention: true,
+      runActiveCallback("terminal reconciliation callback", (ctx, ownerId) => {
+        Observability.reconcileRunTerminalNotifications({
+          inFlight: terminalNotificationsInFlight,
+          ownerId,
+          sink: Pi.createNotificationSink(deps.pi, ctx),
+          state: observation,
+          includeAttention: true,
+        });
+        reportDiagnostics(ctx);
       });
-      reportDiagnostics(ctx);
     },
-    refreshWatcher: () => watcher.refresh(),
+    refreshWatcher: () => {
+      if (running) watcher.refresh();
+    },
   });
-  const close = (): void => {
-    watcher.close();
-    reconciliation.close();
-    if (notifyTimeout) clearTimeout(notifyTimeout);
-    notifyTimeout = undefined;
-    if (animationInterval) clearInterval(animationInterval);
-    animationInterval = undefined;
-  };
 
   return {
     close,
-    shutdown(eventReason, ctx) {
-      close();
-      const teardown = AsyncRuns.teardownRunsOwnedByParent(
-        deps.getRunOwnerId(ctx),
+    shutdown(eventReason, ownerId, ctx) {
+      if (!ownerId) return;
+      const teardown = (
+        deps.teardownRunsOwnedByParent ?? AsyncRuns.teardownRunsOwnedByParent
+      )(
+        ownerId,
         Paths.EXTENSION_RUNTIME_PATHS.runStateRoot,
         { trigger: `session_shutdown:${eventReason}` },
       );
-      if (teardown.failed === 0) return;
+      if (teardown.failed === 0 || !ctx) return;
       try {
         ctx.ui.notify(
           `Actor shutdown teardown: killed=${teardown.killed} failed=${teardown.failed} skipped=${teardown.skipped} discovery_failed=${teardown.discoveryFailed}. Summary: ${teardown.summaryPath ?? "unavailable"}.`,
@@ -140,16 +208,26 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
         /* stale shutdown context */
       }
     },
-    start(ctx) {
+    start(ctx, ownerId) {
       close();
-      Observability.primeRunAttentionState(observation, deps.getRunOwnerId(ctx));
-      update(ctx, true, true);
-      watcher.refresh();
-      reconciliation.start();
-      animationInterval = setInterval(() => {
-        if (deps.getActiveContext() === ctx) update(ctx);
-      }, 1000);
-      animationInterval.unref?.();
+      activeContext = ctx;
+      activeOwnerId = ownerId;
+      running = true;
+      try {
+        Observability.primeRunAttentionState(observation, ownerId);
+        update(ctx, ownerId, true, true);
+        watcher.refresh();
+        reconciliation.start();
+        animationInterval = setInterval(() => {
+          runActiveCallback("status animation callback", (current, currentOwnerId) =>
+            update(current, currentOwnerId),
+          );
+        }, deps.animationIntervalMs ?? 1000);
+        animationInterval.unref?.();
+      } catch (error) {
+        close();
+        throw error;
+      }
     },
   };
 }

package/lib/runs-artifacts.ts

@@ -4,7 +4,12 @@
  */
 
 import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
+import {
+  closeSync,
+  fstatSync,
+  openSync,
+  readSync,
+} from "node:fs";
 
 import { substituteCommandTemplateToken } from "./command-templates.ts";
 
@@ -22,6 +27,31 @@ export interface RunArtifactManifestEntry {
   size?: number;
 }
 
+function hashArtifactFile(path: string): { sha256: string; size: number } {
+  const fd = openSync(path, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const hash = createHash("sha256");
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    while (position < size) {
+      const bytesRead = readSync(
+        fd,
+        chunk,
+        0,
+        Math.min(chunk.byteLength, size - position),
+        position,
+      );
+      if (bytesRead === 0) break;
+      hash.update(chunk.subarray(0, bytesRead));
+      position += bytesRead;
+    }
+    return { sha256: hash.digest("hex"), size: position };
+  } finally {
+    closeSync(fd);
+  }
+}
+
 export function resolveArtifactPaths(
   artifacts: Record<string, RunArtifactDeclaration> | undefined,
   values: Record<string, unknown>,
@@ -64,7 +94,7 @@ export function resolveArtifactManifest(
       typeof artifact === "string" ? { path: artifact } : artifact;
     if (!declaration?.path) continue;
     try {
-      const content = readFileSync(declaration.path);
+      const hashed = hashArtifactFile(declaration.path);
       manifest[name] = {
         exists: true,
         ...(declaration.kind ? { kind: declaration.kind } : {}),
@@ -75,8 +105,8 @@ export function resolveArtifactManifest(
         ...(declaration.required !== undefined
           ? { required: declaration.required }
           : {}),
-        sha256: createHash("sha256").update(content).digest("hex"),
-        size: content.byteLength,
+        sha256: hashed.sha256,
+        size: hashed.size,
       };
     } catch {
       manifest[name] = {

package/lib/runtime.ts

@@ -308,7 +308,9 @@ export function createAutoToolsRuntime(
 export interface RecipeToolReloadWatcherDeps {
   exists?: (path: string) => boolean;
   getResolutionContext?: () => RecipeResolutionContext | undefined;
+  onCallbackError?: (error: unknown) => void;
   recipeRoot?: string;
+  reloadDelayMs?: number;
   watchPath?: typeof watch;
 }
 
@@ -336,22 +338,39 @@ export function createRecipeToolReloadWatcher(
     reloadTimeout = undefined;
     setWatchStatus("closed");
   };
+  const reportCallbackError = (error: unknown): void => {
+    try {
+      deps.onCallbackError?.(error);
+    } catch {
+      /* host callback containment must remain no-throw */
+    }
+  };
   const notifyFailure = (ctx: RuntimeContext): void => {
     if (failureNotified) return;
     failureNotified = true;
     setWatchStatus("failed");
-    ctx.ui.notify(
-      "Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.",
-      "warning",
-    );
+    try {
+      ctx.ui.notify(
+        "Recipe live reload watcher failed; restart the session or use register_tool again to refresh recipe tools.",
+        "warning",
+      );
+    } catch (error) {
+      reportCallbackError(error);
+    }
   };
   const scheduleReload = (ctx: RuntimeContext): void => {
     failureNotified = false;
     if (reloadTimeout) clearTimeout(reloadTimeout);
     reloadTimeout = setTimeout(() => {
-      runtime.loadTools(ctx, deps.getResolutionContext?.());
-      ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
-    }, 150);
+      reloadTimeout = undefined;
+      try {
+        runtime.loadTools(ctx, deps.getResolutionContext?.());
+        ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+      } catch (error) {
+        notifyFailure(ctx);
+        reportCallbackError(error);
+      }
+    }, deps.reloadDelayMs ?? 150);
     reloadTimeout.unref?.();
   };
   const watchParent = (ctx: RuntimeContext, recipeRoot: string): void => {

package/lib/session-evidence.ts

@@ -55,6 +55,7 @@ export interface SessionEvidence {
 }
 
 export interface SessionEvidenceReadOptions {
+  maxBytes?: number;
   maxTextChars?: number;
   maxToolCalls?: number;
   maxTurns?: number;
@@ -195,6 +196,10 @@ export function readSessionEvidence(
   path: string,
   options: SessionEvidenceReadOptions = {},
 ): SessionEvidence {
+  const maxBytes = Math.max(
+    1,
+    options.maxBytes ?? Limits.SESSION_EVIDENCE_MAX_BYTES,
+  );
   const maxTextChars = Math.max(
     1,
     options.maxTextChars ?? Limits.SESSION_EVIDENCE_TEXT_CHARS,
@@ -207,7 +212,7 @@ export function readSessionEvidence(
     1,
     options.maxTurns ?? Limits.SESSION_EVIDENCE_MAX_TURNS,
   );
-  const read = readJsonlFileResilient<SessionEntry>(path);
+  const read = readJsonlFileResilient<SessionEntry>(path, { maxBytes });
   const diagnostics = [...read.diagnostics];
   const header = read.records.find((entry) => entry.type === "session");
   const branch = activeBranch(read.records, path, diagnostics);
@@ -296,7 +301,7 @@ export function readSessionEvidence(
     path,
     ...(header ? { session: asRecord(header) } : {}),
     totalTurns: turns.length,
-    truncated: turns.length > visibleTurns.length,
+    truncated: read.truncated === true || turns.length > visibleTurns.length,
     turns: visibleTurns,
   };
 }

package/lib/state-readers.ts

@@ -4,7 +4,13 @@
  * Owns best-effort JSON and JSONL parsing helpers for operator-facing state reads.
  */
 
-import { readFileSync } from "node:fs";
+import {
+  closeSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+} from "node:fs";
 
 export interface StateReadDiagnostic {
   line?: number;
@@ -20,6 +26,11 @@ export interface JsonReadResult<T> {
 export interface JsonlReadResult<T> {
   diagnostics: StateReadDiagnostic[];
   records: T[];
+  truncated?: boolean;
+}
+
+export interface JsonlReadOptions {
+  maxBytes?: number;
 }
 
 function isEnoent(error: unknown): boolean {
@@ -30,6 +41,31 @@ function diagnosticMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function readTextFileCapped(path: string, maxBytes: number | undefined): string {
+  if (maxBytes === undefined) return readFileSync(path, "utf8");
+  const limit = Math.max(0, Math.floor(maxBytes));
+  const fd = openSync(path, "r");
+  try {
+    const size = fstatSync(fd).size;
+    if (size > limit) {
+      throw Object.assign(
+        new Error(`file exceeds bounded read limit (${size} > ${limit} bytes)`),
+        { code: "EFBIG" },
+      );
+    }
+    const content = Buffer.allocUnsafe(size);
+    let offset = 0;
+    while (offset < size) {
+      const bytesRead = readSync(fd, content, offset, size - offset, offset);
+      if (bytesRead === 0) break;
+      offset += bytesRead;
+    }
+    return content.subarray(0, offset).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+
 export function readJsonFileResilient<T>(path: string, fallback: T): JsonReadResult<T> {
   try {
     return {
@@ -50,11 +86,14 @@ export function readJsonFileResilient<T>(path: string, fallback: T): JsonReadRes
   }
 }
 
-export function readJsonlFileResilient<T>(path: string): JsonlReadResult<T> {
+export function readJsonlFileResilient<T>(
+  path: string,
+  options: JsonlReadOptions = {},
+): JsonlReadResult<T> {
   try {
     const records: T[] = [];
     const diagnostics: StateReadDiagnostic[] = [];
-    const lines = readFileSync(path, "utf8").split("\n");
+    const lines = readTextFileCapped(path, options.maxBytes).split("\n");
     for (const [index, line] of lines.entries()) {
       if (!line.trim()) continue;
       try {
@@ -78,6 +117,9 @@ export function readJsonlFileResilient<T>(path: string): JsonlReadResult<T> {
         },
       ],
       records: [],
+      ...((error as NodeJS.ErrnoException).code === "EFBIG"
+        ? { truncated: true }
+        : {}),
     };
   }
 }

package/lib/tools-access.ts

@@ -17,8 +17,11 @@ export function getContextSessionId(ctx: unknown): string | undefined {
 export function requireContextSessionId(ctx: unknown, actor: string): string {
   const sessionId = getContextSessionId(ctx);
   if (!sessionId) {
-    throw new Error(
-      `${actor} requires a current coordinator session; use session:<id> or session:all for explicit session inventory.`,
+    throw Object.assign(
+      new Error(
+        `${actor} reason=session_unavailable requires a current coordinator session; retry from an active coordinator session.`,
+      ),
+      { reason: "session_unavailable" },
     );
   }
   return sessionId;
@@ -33,16 +36,13 @@ export function sessionMismatchError(input: {
   const ownerSession = input.expectedSession ?? "none";
   const currentSession = input.currentSession ?? "none";
   const actor = input.run ? `run:${input.run}` : (input.target ?? "session");
-  const hintTarget = input.expectedSession
-    ? `session:${input.expectedSession}`
-    : "session:all";
   return Object.assign(
     new Error(
-      `${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_session:${input.expectedSession ?? "all"}`,
+      `${actor} reason=session_mismatch owner_session=${ownerSession} current_session=${currentSession} hint=inspect_runtime_runs`,
     ),
     {
       current_session: input.currentSession,
-      hint: `inspect target=${hintTarget} view=status`,
+      hint: "inspect target=runtime view=runs",
       owner_session: input.expectedSession,
       reason: "session_mismatch",
       run: input.run,
@@ -51,18 +51,32 @@ export function sessionMismatchError(input: {
   );
 }
 
-export function assertRunAccessibleToContext(
+export function assertRunStatusAccessibleToContext(
   runId: string,
+  status: Record<string, unknown>,
   ctx: unknown,
 ): Record<string, unknown> {
-  const status = AsyncRuns.getRunStatus(runId);
-  const sessionId = getContextSessionId(ctx);
-  if (sessionId && status.ownerId && status.ownerId !== sessionId) {
+  const sessionId = requireContextSessionId(ctx, `run:${runId}`);
+  const ownerId = typeof status.ownerId === "string" && status.ownerId
+    ? status.ownerId
+    : undefined;
+  if (ownerId !== sessionId) {
     throw sessionMismatchError({
       currentSession: sessionId,
-      expectedSession: String(status.ownerId),
+      expectedSession: ownerId,
       run: runId,
     });
   }
   return status;
 }
+
+export function assertRunAccessibleToContext(
+  runId: string,
+  ctx: unknown,
+): Record<string, unknown> {
+  return assertRunStatusAccessibleToContext(
+    runId,
+    AsyncRuns.getRunStatus(runId),
+    ctx,
+  );
+}

package/lib/tools-inspect.ts

@@ -42,7 +42,7 @@ export interface InspectToolDeps<TContext = unknown> {
 
 function runtimeStatus(): Record<string, unknown> {
   return {
-    automatic_review: process.env.PI_ACTORS_AUTOMATIC_REVIEW !== "off",
+    automatic_review: Paths.isAutomaticRecipeReviewEnabled(),
     run_root: Paths.getRunStateRoot(),
     state_schema: RuntimeIdentity.RUN_STATE_SCHEMA,
     version: RuntimeIdentity.getPackageVersion(),
@@ -54,7 +54,7 @@ function runtimeRuns(
   deps: InspectToolDeps,
   status: string | undefined,
 ): Record<string, unknown> {
-  const session = ToolsAccess.getContextSessionId(ctx);
+  const session = ToolsAccess.requireContextSessionId(ctx, "runtime Run inventory");
   const listed = deps.listRuns
     ? deps.listRuns()
     : AsyncRuns.listRuns(undefined, status);
@@ -68,8 +68,8 @@ function runtimeRuns(
         return run;
       }
     })
-    .filter((run) => !session || !run.ownerId || run.ownerId === session);
-  return { ...(session ? { owner_session: session } : {}), runs };
+    .filter((run) => run.ownerId === session);
+  return { owner_session: session, runs };
 }
 
 function runtimeTriage(
@@ -463,7 +463,11 @@ function inspectRun(
     throw new Error("inspect run:<id> supports view=recipe, view=trace, or view=control.");
   }
   const status = deps.getRunStatus
-    ? deps.getRunStatus(run)
+    ? ToolsAccess.assertRunStatusAccessibleToContext(
+        run,
+        deps.getRunStatus(run),
+        ctx,
+      )
     : ToolsAccess.assertRunAccessibleToContext(run, ctx);
   const stateDir = String(status.state_dir);
   if (view === "recipe") {

package/lib/tools-message.ts

@@ -46,6 +46,7 @@ function runNextActions(run: string, result: Record<string, unknown>): string[]
 }
 
 export interface ControlToolDeps {
+  getRunStatus?: (run: string) => Record<string, unknown>;
   handleRuntimeControl?: (
     action: string,
     input: unknown,
@@ -94,7 +95,13 @@ export function createControlToolDefinition<TContext = unknown>(
         result = deps.handleRuntimeControl(request.action, request.input);
       } else {
         const run = request.target.slice(4);
-        const status = ToolsAccess.assertRunAccessibleToContext(run, ctx);
+        const status = deps.getRunStatus
+          ? ToolsAccess.assertRunStatusAccessibleToContext(
+              run,
+              deps.getRunStatus(run),
+              ctx,
+            )
+          : ToolsAccess.assertRunAccessibleToContext(run, ctx);
         const runInstanceId =
           typeof status.run_instance_id === "string"
             ? status.run_instance_id

package/package.json

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