@llblab/pi-kit 0.1.13 → 0.3.0

package/node_modules/@llblab/pi-actors/lib/run-ui-runtime.ts

@@ -5,12 +5,16 @@
  */
 
 import * as AsyncRuns from "./async-runs.ts";
+import * as Limits from "./limits.ts";
 import * as Observability from "./observability.ts";
 import * as Paths from "./paths.ts";
 import * as Pi from "./pi.ts";
+import * as RunDelivery from "./run-delivery.ts";
 
 export interface RunUiRuntime {
   close(): void;
+  flushCompletionBatch(ctx: Pi.ExtensionContext): boolean;
+  projectContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
   shutdown(
     eventReason: string,
     ownerId: string | undefined,
@@ -24,6 +28,7 @@ export interface RunUiRuntimeDeps {
   createRunStateWatcher?: typeof Observability.createRunStateWatcher;
   createRunTerminalReconciliationLoop?:
     typeof Observability.createRunTerminalReconciliationLoop;
+  deliveryDebounceMs?: number;
   getActiveContext(): Pi.ExtensionContext | undefined;
   notificationDelayMs?: number;
   onCallbackError?: (error: unknown) => void;
@@ -36,12 +41,16 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
   let activeContext: Pi.ExtensionContext | undefined;
   let activeOwnerId: string | undefined;
   let animationInterval: NodeJS.Timeout | undefined;
+  let deliveryTimeout: NodeJS.Timeout | undefined;
   let notifyTimeout: NodeJS.Timeout | undefined;
+  let recoverQueuedBatch = false;
+  let recoverQueuedSteers = false;
   let running = false;
   let lastWatcherDiagnosticId = 0;
   const observation = Observability.createRunUiObservationState();
+  const deliveryRecoveryDiagnostics = new Set<string>();
   const retirementAttempts = new Set<string>();
-  const terminalNotificationsInFlight = new Set<string>();
+  const steerDiagnostics = new Set<string>();
 
   const close = (): void => {
     running = false;
@@ -59,6 +68,12 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     }
     if (notifyTimeout) clearTimeout(notifyTimeout);
     notifyTimeout = undefined;
+    if (deliveryTimeout) clearTimeout(deliveryTimeout);
+    deliveryTimeout = undefined;
+    recoverQueuedBatch = false;
+    recoverQueuedSteers = false;
+    deliveryRecoveryDiagnostics.clear();
+    steerDiagnostics.clear();
     if (animationInterval) clearInterval(animationInterval);
     animationInterval = undefined;
   };
@@ -107,29 +122,235 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       stopAfterCallbackFailure("Run retirement callback", error, ctx),
     );
   };
+  const journal = (ownerId: string): RunDelivery.RunDeliveryJournal =>
+    RunDelivery.readRunDeliveryJournal(
+      Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+      ownerId,
+    );
+  const finishPresentedBatch = (
+    ownerId: string,
+    batch: RunDelivery.RunCompletionBatch,
+  ): boolean => {
+    if (batch.phase !== "presented") return false;
+    for (const member of batch.members) {
+      AsyncRuns.markRunTerminalNotificationHandled(
+        member.state_dir,
+        member.status,
+        member.run_instance_id,
+      );
+    }
+    return RunDelivery.finalizeRunCompletionBatch({
+      batchId: batch.batch_id,
+      ownerId,
+      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+    });
+  };
+  const recoverPresentedBatch = (ownerId: string): void => {
+    const batch = journal(ownerId).completion_batch;
+    if (batch?.phase === "presented") finishPresentedBatch(ownerId, batch);
+  };
+  const finishPresentedSteer = (
+    ownerId: string,
+    steer: RunDelivery.RunSteerEnvelope,
+  ): boolean => {
+    if (steer.phase !== "presented") return false;
+    AsyncRuns.markRunSteerPresentationHandled(
+      steer.state_dir,
+      steer.run_instance_id,
+      steer.event_id,
+      steer.steer_id,
+    );
+    return RunDelivery.finalizeRunSteer({
+      ownerId,
+      steerId: steer.steer_id,
+      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+    });
+  };
+  const recoverPresentedSteers = (ownerId: string): void => {
+    for (const steer of journal(ownerId).steers) {
+      if (steer.phase === "presented") finishPresentedSteer(ownerId, steer);
+    }
+  };
+  const boundedSteerContent = (event: Observability.RunAttentionEvent): string => {
+    const text = Observability.formatRunAttentionMessage(event);
+    if (Buffer.byteLength(text, "utf8") <= Limits.RUN_DELIVERY_STEER_MAX_BYTES) {
+      return text;
+    }
+    let end = Math.min(text.length, Limits.RUN_DELIVERY_STEER_MAX_BYTES - 3);
+    while (end > 0 && Buffer.byteLength(text.slice(0, end), "utf8") >
+      Limits.RUN_DELIVERY_STEER_MAX_BYTES - 3) end -= 1;
+    return `${text.slice(0, end)}…`;
+  };
+  const admitSteerEvents = (
+    ctx: Pi.ExtensionContext,
+    ownerId: string,
+    events: Observability.RunAttentionEvent[],
+  ): void => {
+    for (const event of events.filter(Observability.isRunSteerAttentionEvent)) {
+      if (!event.runInstanceId) {
+        Observability.retryRunAttentionEvent(observation, event);
+        const key = `${event.stateDir}:${event.id}:missing_generation`;
+        if (!steerDiagnostics.has(key)) {
+          steerDiagnostics.add(key);
+          ctx.ui.notify(
+            `Actor urgent steer ${event.id} remains retryable because its Run generation is unavailable.`,
+            "warning",
+          );
+        }
+        continue;
+      }
+      try {
+        RunDelivery.admitRunSteerEnvelope({
+          content: boundedSteerContent(event),
+          eventId: event.id,
+          kind: event.kind,
+          level: event.level,
+          occurredAt: event.ts,
+          ownerId,
+          run: event.run,
+          runInstanceId: event.runInstanceId,
+          stateDir: event.stateDir,
+          tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+        });
+      } catch (error) {
+        Observability.retryRunAttentionEvent(observation, event);
+        const message = error instanceof Error ? error.message : String(error);
+        const key = `${event.stateDir}:${event.id}:${message}`;
+        if (!steerDiagnostics.has(key)) {
+          steerDiagnostics.add(key);
+          ctx.ui.notify(
+            `Actor urgent steer ${event.id} remains retryable: ${message.replaceAll(/\s+/g, " ").slice(0, 240)}`,
+            "warning",
+          );
+        }
+      }
+    }
+  };
+  const admitCompletionTransitions = (
+    ownerId: string,
+    transitions: Observability.RunTransition[],
+  ): boolean => {
+    const existing = journal(ownerId).completion_batch;
+    if (existing) return true;
+    const members = Observability.collectRunCompletionBatchMembers(transitions)
+      .slice(0, Limits.RUN_DELIVERY_BATCH_MAX_MEMBERS);
+    if (members.length === 0) return false;
+    RunDelivery.admitRunCompletionBatch({
+      members,
+      ownerId,
+      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+    });
+    return true;
+  };
+  const isIdle = (ctx: Pi.ExtensionContext): boolean =>
+    typeof ctx.isIdle !== "function" || ctx.isIdle();
+  let flushCompletionBatch = (_ctx: Pi.ExtensionContext): boolean => false;
+  const flushSteers = (ctx: Pi.ExtensionContext, ownerId: string): boolean => {
+    const recovering = recoverQueuedSteers;
+    for (const steer of journal(ownerId).steers) {
+      if (steer.phase === "presented") {
+        finishPresentedSteer(ownerId, steer);
+        continue;
+      }
+      let phase = steer.phase;
+      if (phase === "queued") {
+        if (!recovering) continue;
+        const evidence = Pi.inspectRunSteerSessionEvidence(ctx, {
+          content: steer.content,
+          eventId: steer.event_id,
+          steerId: steer.steer_id,
+        });
+        if (evidence.status === "present") continue;
+        if (evidence.status !== "absent") {
+          const key = `${steer.steer_id}:${evidence.status}:${evidence.reason ?? ""}`;
+          if (!steerDiagnostics.has(key)) {
+            steerDiagnostics.add(key);
+            ctx.ui.notify(
+              `Actor urgent steer recovery is ${evidence.status}: ${evidence.reason ?? "conflicting session evidence"}. Event ${steer.event_id} remains queued.`,
+              "warning",
+            );
+          }
+          continue;
+        }
+        if (!RunDelivery.resetRunSteerPending({
+          ownerId,
+          steerId: steer.steer_id,
+          tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+        })) continue;
+        phase = "pending";
+      }
+      if (phase !== "pending") continue;
+      try {
+        Pi.sendRunSteer(deps.pi, {
+          content: steer.content,
+          eventId: steer.event_id,
+          steerId: steer.steer_id,
+        });
+      } catch (error) {
+        RunDelivery.recordRunSteerDeliveryFailure({
+          error,
+          ownerId,
+          steerId: steer.steer_id,
+          tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+        });
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(
+          `Actor urgent steer delivery failed for event ${steer.event_id}: ${message.replaceAll(/\s+/g, " ").slice(0, 240)}`,
+          "error",
+        );
+        continue;
+      }
+      RunDelivery.markRunSteerQueued({
+        ownerId,
+        steerId: steer.steer_id,
+        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+      });
+    }
+    recoverQueuedSteers = false;
+    return journal(ownerId).steers.length > 0;
+  };
+  const scheduleCompletionFlush = (): void => {
+    if (!running) return;
+    if (deliveryTimeout) clearTimeout(deliveryTimeout);
+    deliveryTimeout = setTimeout(() => {
+      deliveryTimeout = undefined;
+      runActiveCallback("completion delivery callback", (ctx) => {
+        flushCompletionBatch(ctx);
+      });
+    }, deps.deliveryDebounceMs ?? 100);
+    deliveryTimeout.unref?.();
+  };
   const update = (
     ctx: Pi.ExtensionContext,
     ownerId: string,
     notify = false,
     terminalOnly = false,
-  ): void => {
+  ): boolean => {
     const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
     ctx.ui.setStatus(
       "zz-pi-actors-runs",
       snapshot.status ? ctx.ui.theme.fg("dim", snapshot.status) : undefined,
     );
-    if (!notify) return;
+    if (!notify) return false;
     const sink = Pi.createNotificationSink(deps.pi, ctx);
     retireCandidateRuns(ctx, snapshot.summary);
-    Observability.deliverRunTransitionNotifications(
-      snapshot.transitions,
-      sink,
-      terminalNotificationsInFlight,
-    );
+    const hasCompletionCandidates =
+      Observability.collectRunCompletionBatchMembers(snapshot.transitions).length > 0;
+    const hasCompletionBatch = Boolean(journal(ownerId).completion_batch);
+    admitSteerEvents(ctx, ownerId, snapshot.attentionEvents);
     Observability.pruneRunUiObservationState(observation, snapshot);
     if (!terminalOnly) {
-      Observability.deliverRunAttentionNotifications(snapshot.attentionEvents, sink);
+      Observability.deliverRunAttentionNotifications(
+        snapshot.attentionEvents.filter((event) =>
+          !Observability.isRunSteerAttentionEvent(event)),
+        sink,
+      );
+    }
+    const hasSteers = flushSteers(ctx, ownerId);
+    if ((hasCompletionBatch || hasCompletionCandidates) && isIdle(ctx)) {
+      scheduleCompletionFlush();
     }
+    return hasCompletionBatch || hasCompletionCandidates || hasSteers;
   };
   const reportDiagnostics = (ctx: Pi.ExtensionContext): void => {
     for (const diagnostic of watcher.getDiagnostics()) {
@@ -147,8 +368,8 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     notifyTimeout = setTimeout(() => {
       runActiveCallback("Run watcher callback", (ctx, ownerId) => {
         watcher.refresh();
-        update(ctx, ownerId, true);
-        deps.onRunEvent();
+        const completionDeferred = update(ctx, ownerId, true);
+        if (!completionDeferred) deps.onRunEvent();
         reportDiagnostics(ctx);
       });
     }, deps.notificationDelayMs ?? 50);
@@ -172,13 +393,7 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     },
     reconcile: () => {
       runActiveCallback("terminal reconciliation callback", (ctx, ownerId) => {
-        Observability.reconcileRunTerminalNotifications({
-          inFlight: terminalNotificationsInFlight,
-          ownerId,
-          sink: Pi.createNotificationSink(deps.pi, ctx),
-          state: observation,
-          includeAttention: true,
-        });
+        update(ctx, ownerId, true);
         reportDiagnostics(ctx);
       });
     },
@@ -187,8 +402,141 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
     },
   });
 
+  flushCompletionBatch = (ctx: Pi.ExtensionContext): boolean => {
+    if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx) return false;
+    const ownerId = activeOwnerId;
+    if (!ownerId) return false;
+    if (flushSteers(ctx, ownerId)) return true;
+    let batch = journal(ownerId).completion_batch;
+    if (!batch) {
+      const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
+      admitCompletionTransitions(ownerId, snapshot.transitions);
+      Observability.pruneRunUiObservationState(observation, snapshot);
+      batch = journal(ownerId).completion_batch;
+    }
+    if (!batch) return false;
+    if (batch.phase === "presented") {
+      finishPresentedBatch(ownerId, batch);
+      const snapshot = Observability.readRunUiSnapshot(observation, ownerId);
+      admitCompletionTransitions(ownerId, snapshot.transitions);
+      Observability.pruneRunUiObservationState(observation, snapshot);
+      batch = journal(ownerId).completion_batch;
+      if (!batch) return false;
+    }
+    if (!isIdle(ctx)) return true;
+    const content = RunDelivery.formatRunCompletionBatchMessage(batch);
+    if (batch.phase === "queued") {
+      if (!recoverQueuedBatch) return true;
+      recoverQueuedBatch = false;
+      const evidence = Pi.inspectRunCompletionBatchSessionEvidence(
+        ctx,
+        batch.batch_id,
+        content,
+      );
+      if (evidence.status === "present") return true;
+      if (evidence.status !== "absent") {
+        const diagnosticKey = `${batch.batch_id}:${evidence.status}:${evidence.reason ?? ""}`;
+        if (!deliveryRecoveryDiagnostics.has(diagnosticKey)) {
+          deliveryRecoveryDiagnostics.add(diagnosticKey);
+          ctx.ui.notify(
+            `Actor completion recovery is ${evidence.status}: ${evidence.reason ?? "conflicting session evidence"}. Batch ${batch.batch_id} remains queued.`,
+            "warning",
+          );
+        }
+        return true;
+      }
+      if (!RunDelivery.resetRunCompletionBatchPending({
+        batchId: batch.batch_id,
+        ownerId,
+        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+      })) return true;
+      batch = journal(ownerId).completion_batch!;
+    }
+    if (!isIdle(ctx)) return true;
+    try {
+      Pi.sendRunCompletionBatch(deps.pi, batch.batch_id, content);
+    } catch (error) {
+      RunDelivery.recordRunCompletionBatchDeliveryFailure({
+        batchId: batch.batch_id,
+        error,
+        ownerId,
+        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+      });
+      throw error;
+    }
+    if (!RunDelivery.markRunCompletionBatchQueued({
+      batchId: batch.batch_id,
+      ownerId,
+      tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+    })) {
+      throw new Error("Completion batch changed before queue acknowledgment");
+    }
+    recoverQueuedBatch = false;
+    return true;
+  };
+
   return {
     close,
+    flushCompletionBatch,
+    projectContext(messages, ctx) {
+      if (!running || activeContext !== ctx || deps.getActiveContext() !== ctx) {
+        return messages;
+      }
+      const ownerId = activeOwnerId;
+      if (!ownerId) return messages;
+      const steerContext = Pi.dedupeRunSteerContext(messages);
+      let contextMessages = steerContext.messages;
+      for (const steer of journal(ownerId).steers) {
+        const presented = steerContext.steers.get(steer.steer_id);
+        if (
+          !presented ||
+          presented.eventId !== steer.event_id ||
+          presented.content !== steer.content
+        ) {
+          contextMessages = Pi.removeRunSteerFromContext(
+            contextMessages,
+            steer.steer_id,
+          );
+          continue;
+        }
+        if (!RunDelivery.markRunSteerQueued({
+          ownerId,
+          steerId: steer.steer_id,
+          tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+        })) continue;
+        if (!RunDelivery.markRunSteerPresented({
+          ownerId,
+          steerId: steer.steer_id,
+          tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+        })) continue;
+        const durable = journal(ownerId).steers.find((item) =>
+          item.steer_id === steer.steer_id);
+        if (durable) finishPresentedSteer(ownerId, durable);
+      }
+      const projected = Pi.dedupeRunCompletionBatchContext(contextMessages);
+      const batch = journal(ownerId).completion_batch;
+      if (!batch) return projected.messages;
+      const content = projected.batches.get(batch.batch_id);
+      if (content !== RunDelivery.formatRunCompletionBatchMessage(batch)) {
+        return Pi.removeRunCompletionBatchFromContext(
+          projected.messages,
+          batch.batch_id,
+        );
+      }
+      if (!RunDelivery.markRunCompletionBatchQueued({
+        batchId: batch.batch_id,
+        ownerId,
+        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+      })) return projected.messages;
+      if (!RunDelivery.markRunCompletionBatchPresented({
+        batchId: batch.batch_id,
+        ownerId,
+        tempDir: Paths.EXTENSION_RUNTIME_PATHS.tempDir,
+      })) return projected.messages;
+      const presented = journal(ownerId).completion_batch;
+      if (presented) finishPresentedBatch(ownerId, presented);
+      return projected.messages;
+    },
     shutdown(eventReason, ownerId, ctx) {
       if (!ownerId) return;
       const teardown = (
@@ -212,8 +560,12 @@ export function createRunUiRuntime(deps: RunUiRuntimeDeps): RunUiRuntime {
       close();
       activeContext = ctx;
       activeOwnerId = ownerId;
+      recoverQueuedBatch = true;
+      recoverQueuedSteers = true;
       running = true;
       try {
+        recoverPresentedBatch(ownerId);
+        recoverPresentedSteers(ownerId);
         Observability.primeRunAttentionState(observation, ownerId);
         update(ctx, ownerId, true, true);
         watcher.refresh();

package/node_modules/@llblab/pi-actors/lib/runs-trace.ts

@@ -35,7 +35,7 @@ export interface TraceEvent {
   summary?: string;
   data?: unknown;
   level?: "info" | "warning" | "error";
-  attention?: "notify" | "followup";
+  attention?: "notify" | "followup" | "steer";
 }
 
 export interface AppendTraceEventInput {
@@ -167,9 +167,10 @@ function normalizeTraceEventInput(input: unknown): AppendTraceEventInput {
   if (
     record.attention !== undefined &&
     record.attention !== "notify" &&
-    record.attention !== "followup"
+    record.attention !== "followup" &&
+    record.attention !== "steer"
   ) {
-    throw new Error("Trace event attention must be notify or followup");
+    throw new Error("Trace event attention must be notify, followup, or steer");
   }
   return {
     kind: record.kind,
@@ -295,7 +296,8 @@ function isTraceEvent(value: unknown): value is TraceEvent {
   ) return false;
   return record.attention === undefined ||
     record.attention === "notify" ||
-    record.attention === "followup";
+    record.attention === "followup" ||
+    record.attention === "steer";
 }
 
 function isCount(value: unknown): value is number {

package/node_modules/@llblab/pi-actors/lib/session-evidence.ts

@@ -61,7 +61,160 @@ export interface SessionEvidenceReadOptions {
   maxTurns?: number;
 }
 
+export type ActiveSessionEntryMatch = "present" | "conflict" | undefined;
+export interface ActiveSessionEntryEvidence {
+  examinedBytes: number;
+  examinedEntries: number;
+  reason?: string;
+  status: "present" | "absent" | "conflict" | "unknown";
+}
+
+export interface ActiveSessionEntryEvidenceInput {
+  getEntry(id: string): unknown;
+  leaf: unknown;
+  match(entry: Record<string, unknown>): ActiveSessionEntryMatch;
+  maxBytes?: number;
+  maxEntries?: 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;
+
+function boundedJsonStringBytes(value: string): number {
+  let bytes = Buffer.byteLength(value, "utf8") + 2;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code === 0x22 || code === 0x5c) bytes += 1;
+    else if (code < 0x20) bytes += [0x08, 0x09, 0x0a, 0x0c, 0x0d].includes(code) ? 1 : 5;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) index += 1;
+      else bytes += 3;
+    } else if (code >= 0xdc00 && code <= 0xdfff) bytes += 3;
+  }
+  return bytes;
+}
+
+function boundedJsonBytes(
+  value: unknown,
+  ceiling: number,
+  seen = new WeakSet<object>(),
+): number | undefined {
+  if (value === null) return 4;
+  if (typeof value === "string") return boundedJsonStringBytes(value);
+  if (typeof value === "number") return Number.isFinite(value) ? String(value).length : 4;
+  if (typeof value === "boolean") return value ? 4 : 5;
+  if (typeof value !== "object") return undefined;
+  if (seen.has(value)) return undefined;
+  seen.add(value);
+  let bytes = 2;
+  const values: Array<[string | undefined, unknown]> = Array.isArray(value)
+    ? value.map((item) => [
+      undefined,
+      item === undefined || typeof item === "function" || typeof item === "symbol"
+        ? null
+        : item,
+    ])
+    : Object.entries(value as Record<string, unknown>).filter(([, item]) =>
+      item !== undefined && typeof item !== "function" && typeof item !== "symbol");
+  for (const [key, item] of values) {
+    if (bytes > ceiling) break;
+    if (bytes > 2) bytes += 1;
+    if (key !== undefined) bytes += boundedJsonStringBytes(key) + 1;
+    const itemBytes = boundedJsonBytes(item, ceiling - bytes, seen);
+    if (itemBytes === undefined) {
+      seen.delete(value);
+      return undefined;
+    }
+    bytes += itemBytes;
+  }
+  seen.delete(value);
+  return bytes;
+}
+
+/** Walk only the active parent chain under exact entry and byte ceilings. */
+export function inspectBoundedActiveSessionEntries(
+  input: ActiveSessionEntryEvidenceInput,
+): ActiveSessionEntryEvidence {
+  const maxBytes = input.maxBytes ?? Limits.RUN_DELIVERY_SESSION_MAX_BYTES;
+  const maxEntries = input.maxEntries ?? Limits.RUN_DELIVERY_SESSION_MAX_ENTRIES;
+  if (input.leaf === undefined || input.leaf === null) {
+    return { examinedBytes: 0, examinedEntries: 0, status: "absent" };
+  }
+  const visited = new Set<string>();
+  let current: unknown = input.leaf;
+  let examinedBytes = 0;
+  let examinedEntries = 0;
+  while (current !== undefined) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session entry is malformed",
+        status: "unknown",
+      };
+    }
+    const entry = current as Record<string, unknown>;
+    if (typeof entry.id !== "string" || !entry.id) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session entry id is malformed",
+        status: "unknown",
+      };
+    }
+    if (visited.has(entry.id)) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session entry cycle detected",
+        status: "unknown",
+      };
+    }
+    visited.add(entry.id);
+    const bytes = boundedJsonBytes(entry, maxBytes - examinedBytes);
+    if (bytes === undefined) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session entry is not serializable",
+        status: "unknown",
+      };
+    }
+    if (examinedEntries >= maxEntries || examinedBytes + bytes > maxBytes) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session evidence exceeds its inspection bound",
+        status: "unknown",
+      };
+    }
+    examinedEntries += 1;
+    examinedBytes += bytes;
+    const matched = input.match(entry);
+    if (matched) return { examinedBytes, examinedEntries, status: matched };
+    if (entry.parentId === null) {
+      return { examinedBytes, examinedEntries, status: "absent" };
+    }
+    if (typeof entry.parentId !== "string" || !entry.parentId) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session parent is malformed",
+        status: "unknown",
+      };
+    }
+    current = input.getEntry(entry.parentId);
+    if (current === undefined) {
+      return {
+        examinedBytes,
+        examinedEntries,
+        reason: "active session parent is unavailable",
+        status: "unknown",
+      };
+    }
+  }
+  return { examinedBytes, examinedEntries, status: "unknown" };
+}
 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> {

package/node_modules/@llblab/pi-actors/lib/temp.ts

@@ -14,7 +14,7 @@ export async function cleanupStaleTempEntries(
   tempDir: string,
   maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS,
   now = Date.now(),
-  preservedEntries = new Set(["runs"]),
+  preservedEntries = new Set(["runs", "delivery"]),
 ): Promise<number> {
   let entries: Array<{ name: string }>;
   let removed = 0;

package/node_modules/@llblab/pi-actors/lib/tools-inspect.ts

@@ -122,7 +122,10 @@ function runtimeTriage(
     const stateDir = typeof run.state_dir === "string" ? run.state_dir : undefined;
     if (!stateDir) return [];
     return RunsTrace.readRunTraceEvents(stateDir)
-      .filter((event) => event.attention === "notify" || event.attention === "followup")
+      .filter((event) =>
+      event.attention === "notify" ||
+      event.attention === "followup" ||
+      event.attention === "steer")
       .map((event) => ({
         run: run.run,
         id: event.id,