@llblab/pi-actors 0.51.0 → 0.52.1

package/index.ts

@@ -15,6 +15,9 @@ export default function toolRegistryExtension(pi: Pi.ExtensionAPI) {
   );
   pi.on("session_start", async (_event, ctx) => runtime.onSessionStart(ctx));
   pi.on("agent_settled", async (_event, ctx) => runtime.onAgentSettled(ctx));
+  pi.on("context", async (event, ctx) => ({
+    messages: runtime.onContext(event.messages, ctx) as typeof event.messages,
+  }));
   pi.on("session_shutdown", async (event, ctx) =>
     runtime.onSessionShutdown(event.reason, ctx),
   );

package/lib/async-runs.ts

@@ -1136,30 +1136,51 @@ function stopRun(
 export function markRunTerminalNotificationHandled(
   stateDir: string,
   status: string,
-): void {
-  markTerminalHandled(stateDir, {
-    event: "run.notification",
-    status,
-  });
+  expectedRunInstanceId: string,
+): boolean {
+  const releaseLock = RunsStart.acquireStateStartLock(stateDir);
+  try {
+    if (!existsSync(join(stateDir, "run.json"))) return false;
+    const current = getRunStatus(stateDir);
+    if (
+      current.run_instance_id !== expectedRunInstanceId ||
+      current.status !== status
+    ) return false;
+    markTerminalHandled(stateDir, {
+      event: "run.notification",
+      run_instance_id: expectedRunInstanceId,
+      status,
+    });
+    rmSync(join(stateDir, "terminal-delivery-failure.json"), { force: true });
+    return true;
+  } finally {
+    releaseLock();
+  }
 }
 
-export function recordRunTerminalDeliveryFailure(
+export function markRunSteerPresentationHandled(
   stateDir: string,
-  status: string,
-  error: unknown,
-): void {
-  const path = join(stateDir, "terminal-delivery-failure.json");
-  const previous = readJson(path);
-  const message = (error instanceof Error ? error.message : String(error))
-    .replaceAll(/\s+/g, " ")
-    .trim()
-    .slice(0, 500);
-  writeJsonAtomic(path, {
-    attempts: Math.max(0, Number(previous?.attempts ?? 0)) + 1,
-    error: message || "unknown delivery failure",
-    status,
-    ts: new Date().toISOString(),
-  });
+  expectedRunInstanceId: string,
+  eventId: string,
+  steerId: string,
+): boolean {
+  const releaseLock = RunsStart.acquireStateStartLock(stateDir);
+  try {
+    if (!existsSync(join(stateDir, "run.json"))) return false;
+    const current = getRunStatus(stateDir);
+    if (current.run_instance_id !== expectedRunInstanceId) return false;
+    appendRunTraceEvent(stateDir, {
+      data: {
+        event_id: eventId,
+        run_instance_id: expectedRunInstanceId,
+        steer_id: steerId,
+      },
+      kind: "delivery.steer_presented",
+    });
+    return true;
+  } finally {
+    releaseLock();
+  }
 }
 
 export function cancelRun(

package/lib/extension-runtime.ts

@@ -26,6 +26,7 @@ export interface ActorExtensionRuntime {
   discoverResources(metaUrl: string): { skillPaths: string[] } | undefined;
   getRunOwnerId(ctx: Pi.ExtensionContext): string;
   onAgentSettled(ctx: Pi.ExtensionContext): void;
+  onContext(messages: unknown[], ctx: Pi.ExtensionContext): unknown[];
   onSessionShutdown(reason: string, ctx: Pi.ExtensionContext): void;
   onSessionStart(ctx: Pi.ExtensionContext): Promise<void>;
   registerCoreTools(): void;
@@ -142,7 +143,11 @@ export function createActorExtensionRuntime(
     },
     getRunOwnerId,
     onAgentSettled(ctx) {
-      if (activeRunContext === ctx) automaticReview.schedule();
+      if (activeRunContext !== ctx) return;
+      if (!runUiRuntime.flushCompletionBatch(ctx)) automaticReview.schedule();
+    },
+    onContext(messages, ctx) {
+      return runUiRuntime.projectContext(messages, ctx);
     },
     onSessionShutdown(reason, ctx) {
       const ownerId = runOwnerIdsByContext.get(ctx);

package/lib/limits.ts

@@ -28,3 +28,12 @@ export const RUN_CONTROL_ERROR_MAX_BYTES = 4 * 1024;
 export const RUN_CONTROL_JOURNAL_MAX_BYTES = 1024 * 1024;
 export const RUN_RETENTION_MAX_RECORDS = 256;
 export const RUN_RETENTION_MAX_BYTES = 1024 * 1024;
+export const RUN_DELIVERY_BATCH_MAX_MEMBERS = 256;
+export const RUN_DELIVERY_MODEL_MAX_MEMBERS = 64;
+export const RUN_DELIVERY_MODEL_MAX_BYTES = 16 * 1024;
+export const RUN_DELIVERY_RECEIPT_LIMIT = 128;
+export const RUN_DELIVERY_SESSION_MAX_ENTRIES = 256;
+export const RUN_DELIVERY_SESSION_MAX_BYTES = 1024 * 1024;
+export const RUN_DELIVERY_STEER_MAX_ENVELOPES = 64;
+export const RUN_DELIVERY_STEER_MAX_BYTES = 16 * 1024;
+export const RUN_DELIVERY_JOURNAL_MAX_BYTES = 1024 * 1024;

package/lib/observability.ts

@@ -26,6 +26,7 @@ import {
 import * as AsyncRuns from "./async-runs.ts";
 import * as Paths from "./paths.ts";
 import * as RunsTrace from "./runs-trace.ts";
+import type { RunCompletionBatchMember } from "./run-delivery.ts";
 import { readJsonlFileResilient } from "./state-readers.ts";
 
 export type RunObservedStatus =
@@ -35,7 +36,7 @@ export type RunObservedStatus =
   | "exited"
   | "cancelled"
   | "killed";
-export type RunTraceAttention = "log" | "notify" | "followup";
+export type RunTraceAttention = "log" | "notify" | "followup" | "steer";
 export type RunTraceLevel = "info" | "warning" | "error";
 
 export interface RunObservation {
@@ -53,6 +54,7 @@ export interface RunObservation {
   terminalHandled?: boolean;
   retireWhen?: string;
   run: string;
+  runInstanceId?: string;
   semanticResult?: RunTerminalSemanticResult;
   tool?: string;
   stateDir?: string;
@@ -149,70 +151,6 @@ 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 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: false,
-        details: transition,
-      });
-      if (transition.stateDir) {
-        AsyncRuns.markRunTerminalNotificationHandled(
-          transition.stateDir,
-          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);
-    }
-  }
-}
-
-export function reconcileRunTerminalNotifications(input: {
-  inFlight?: Set<string>;
-  ownerId: string;
-  sink: RunUiNotificationSink;
-  state: RunUiObservationState;
-  stateRoot?: string;
-  includeAttention?: boolean;
-}): RunUiSnapshot {
-  const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-    includeAttention: input.includeAttention,
-    stateRoot: input.stateRoot,
-  });
-  deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
-  if (input.includeAttention)
-    deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
-  pruneRunUiObservationState(input.state, snapshot);
-  return snapshot;
-}
-
 export function deliverRunAttentionNotifications(
   events: RunAttentionEvent[],
   sink: RunUiNotificationSink,
@@ -447,7 +385,9 @@ export interface RunRetirementExecutorOptions {
 export interface RunTransition {
   from: RunObservedStatus;
   run: string;
+  runInstanceId?: string;
   stateDir?: string;
+  terminalAt?: string;
   artifacts?: Record<string, string>;
   launchCorrelation?: Record<string, string>;
   launchSource?: AsyncRuns.AsyncRunLaunchSource;
@@ -477,6 +417,7 @@ export interface RunAttentionEvent {
   level: RunTraceLevel;
   metadata?: Record<string, unknown>;
   run: string;
+  runInstanceId?: string;
   stateDir: string;
   summary: string;
   ts: string;
@@ -513,11 +454,18 @@ function getProgress(status: Record<string, unknown>): Record<string, unknown> {
 
 function getUpdatedAt(status: Record<string, unknown>): string | undefined {
   const progress = getProgress(status);
-  return typeof progress.updatedAt === "string"
-    ? progress.updatedAt
-    : typeof status.createdAt === "string"
-      ? status.createdAt
-      : undefined;
+  const result = status.result &&
+    typeof status.result === "object" &&
+    !Array.isArray(status.result)
+    ? status.result as Record<string, unknown>
+    : {};
+  return typeof result.completed_at === "string"
+    ? result.completed_at
+    : typeof progress.updatedAt === "string"
+      ? progress.updatedAt
+      : typeof status.createdAt === "string"
+        ? status.createdAt
+        : undefined;
 }
 
 function scanRunStateDirs(
@@ -658,6 +606,9 @@ function observeRun(stateDir: string): RunObservation | undefined {
       ...(typeof status.recipe_file === "string"
         ? { recipeFile: status.recipe_file }
         : {}),
+      ...(typeof status.run_instance_id === "string"
+        ? { runInstanceId: status.run_instance_id }
+        : {}),
       ...(status.terminal_handled ? { terminalHandled: true } : {}),
       ...(typeof status.retire_when === "string"
         ? { retireWhen: status.retire_when }
@@ -1060,8 +1011,10 @@ export function detectRunTransitions(
         ...(run.launchSource ? { launchSource: run.launchSource } : {}),
         ...(run.modelPolicy ? { modelPolicy: run.modelPolicy } : {}),
         ...(run.recipeFile ? { recipeFile: run.recipeFile } : {}),
+        ...(run.runInstanceId ? { runInstanceId: run.runInstanceId } : {}),
         ...(run.semanticResult ? { semanticResult: run.semanticResult } : {}),
         ...(run.terminalHandled ? { terminalHandled: true } : {}),
+        ...(run.updatedAt ? { terminalAt: run.updatedAt } : {}),
         to: run.status,
         ...(run.tool ? { tool: run.tool } : {}),
       });
@@ -1107,7 +1060,9 @@ function parseAttentionRecord(
     ...(raw.body !== undefined ? { body: raw.body } : {}),
     ...(raw.data !== undefined ? { data: raw.data } : {}),
     attention:
-      raw.attention === "notify" || raw.attention === "followup"
+      raw.attention === "notify" ||
+      raw.attention === "followup" ||
+      raw.attention === "steer"
         ? raw.attention
         : normalizeTraceAttention(raw.delivery),
     id,
@@ -1119,6 +1074,7 @@ function parseAttentionRecord(
       ? { metadata: raw.metadata as Record<string, unknown> }
       : {}),
     run: run.run,
+    ...(run.runInstanceId ? { runInstanceId: run.runInstanceId } : {}),
     stateDir: run.stateDir,
     summary,
     ts,
@@ -1167,6 +1123,16 @@ export function detectRunAttentionEvents(
     const read = readTraceAttentionRecords(run);
     const retained = new Set<string>();
     const seen = seenEventIds.get(key) ?? new Set<string>();
+    const presentedSteerIds = new Set(read.records.flatMap((record) => {
+      if (
+        record.kind !== "delivery.steer_presented" ||
+        !record.data ||
+        typeof record.data !== "object" ||
+        Array.isArray(record.data)
+      ) return [];
+      const eventId = (record.data as Record<string, unknown>).event_id;
+      return typeof eventId === "string" && eventId ? [eventId] : [];
+    }));
     const start = read.canonical ? 0
       : Math.min(legacyLineCounts.get(key) ?? 0, read.records.length);
     for (const [index, record] of read.records.entries()) {
@@ -1174,8 +1140,14 @@ export function detectRunAttentionEvents(
       if (!event || !shouldNotifyRunAttentionEvent(event) ||
           event.kind === "runtime.trace_compacted") continue;
       retained.add(event.id);
-      if (prime || run.notificationPolicy === "silent") seen.add(event.id);
-      else if (index >= start && !seen.has(event.id)) {
+      if (isRunSteerAttentionEvent(event) && presentedSteerIds.has(event.id)) {
+        seen.add(event.id);
+        continue;
+      }
+      if (run.notificationPolicy === "silent") seen.add(event.id);
+      else if (prime) {
+        if (!isRunSteerAttentionEvent(event)) seen.add(event.id);
+      } else if (index >= start && !seen.has(event.id)) {
         events.push(event); seen.add(event.id);
       }
     }
@@ -1194,7 +1166,20 @@ export function getRunAttentionNotificationType(
 
 export function shouldNotifyRunAttentionEvent(event: RunAttentionEvent): boolean {
   if (event.kind === "command.done") return false;
-  return event.attention === "notify" || event.attention === "followup";
+  return event.attention === "notify" ||
+    event.attention === "followup" ||
+    event.attention === "steer";
+}
+
+export function isRunSteerAttentionEvent(event: RunAttentionEvent): boolean {
+  return event.kind !== "command.done" && event.attention === "steer";
+}
+
+export function retryRunAttentionEvent(
+  state: RunUiObservationState,
+  event: Pick<RunAttentionEvent, "id" | "stateDir">,
+): void {
+  state.attentionEventIds.get(event.stateDir)?.delete(event.id);
 }
 
 export function shouldSendRunAttentionFollowUp(event: RunAttentionEvent): boolean {
@@ -1297,10 +1282,43 @@ export function shouldNotifyRunTransition(transition: RunTransition): boolean {
   );
 }
 
-export function shouldSendRunTransitionFollowUp(
-  transition: RunTransition,
-): boolean {
-  return shouldNotifyRunTransition(transition);
+/** Build exact immutable generation members for owner-journal admission. */
+export function collectRunCompletionBatchMembers(
+  transitions: RunTransition[],
+): RunCompletionBatchMember[] {
+  return transitions.flatMap((transition) => {
+    if (
+      !shouldNotifyRunTransition(transition) ||
+      !transition.stateDir ||
+      !transition.runInstanceId ||
+      !transition.terminalAt ||
+      Number.isNaN(Date.parse(transition.terminalAt))
+    ) return [];
+    const artifactEntries = Object.entries(transition.artifacts ?? {})
+      .filter((entry): entry is [string, string] =>
+        typeof entry[1] === "string" && Boolean(entry[1]))
+      .slice(0, 4);
+    const rawSummary = transition.semanticResult?.summary.trim() ||
+      `Run ${transition.to}.`;
+    return [{
+      ...(artifactEntries.length > 0
+        ? { artifacts: Object.fromEntries(artifactEntries) }
+        : {}),
+      run: transition.run,
+      run_instance_id: transition.runInstanceId,
+      state_dir: transition.stateDir,
+      status: transition.to as RunCompletionBatchMember["status"],
+      summary: rawSummary.length > 1_000
+        ? `${rawSummary.slice(0, 999)}…`
+        : rawSummary,
+      terminal_at: transition.terminalAt,
+    }];
+  }).sort((left, right) =>
+    left.terminal_at.localeCompare(right.terminal_at) ||
+    left.run.localeCompare(right.run) ||
+    left.run_instance_id.localeCompare(right.run_instance_id) ||
+    left.state_dir.localeCompare(right.state_dir)
+  );
 }
 
 const TERMINAL_FOLLOW_UP_ARTIFACT_LIMIT = 4;

package/lib/pi.ts

@@ -9,8 +9,13 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 
+import * as SessionEvidence from "./session-evidence.ts";
+
 export type { ExtensionAPI, ExtensionContext };
 
+export const RUN_COMPLETION_BATCH_CUSTOM_TYPE = "pi-actors-run-batch";
+export const RUN_STEER_CUSTOM_TYPE = "pi-actors-run-steer";
+
 export interface PiNotificationSink {
   notify(message: string, level: "info" | "warning" | "error"): void;
   sendFollowUp(message: {
@@ -39,6 +44,211 @@ export function createNotificationSink(
   };
 }
 
+export function sendRunCompletionBatch(
+  pi: ExtensionAPI,
+  batchId: string,
+  content: string,
+): void {
+  pi.sendMessage({
+    customType: RUN_COMPLETION_BATCH_CUSTOM_TYPE,
+    content,
+    display: false,
+    details: {
+      pi_actors_delivery: {
+        batch_id: batchId,
+        kind: "completion_batch",
+      },
+    },
+  }, {
+    deliverAs: "followUp",
+    triggerTurn: true,
+  });
+}
+
+export function sendRunSteer(
+  pi: ExtensionAPI,
+  input: { content: string; eventId: string; steerId: string },
+): void {
+  pi.sendMessage({
+    customType: RUN_STEER_CUSTOM_TYPE,
+    content: input.content,
+    display: false,
+    details: {
+      pi_actors_delivery: {
+        event_id: input.eventId,
+        kind: "urgent_steer",
+        steer_id: input.steerId,
+      },
+    },
+  }, {
+    deliverAs: "steer",
+    triggerTurn: true,
+  });
+}
+
+function completionBatchMessage(
+  message: unknown,
+): { batchId: string; content: string } | undefined {
+  if (!message || typeof message !== "object" || Array.isArray(message)) return undefined;
+  const record = message as Record<string, unknown>;
+  if (
+    record.customType !== RUN_COMPLETION_BATCH_CUSTOM_TYPE ||
+    typeof record.content !== "string"
+  ) return undefined;
+  const details = record.details;
+  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+  const delivery = (details as Record<string, unknown>).pi_actors_delivery;
+  if (!delivery || typeof delivery !== "object" || Array.isArray(delivery)) return undefined;
+  const envelope = delivery as Record<string, unknown>;
+  if (
+    envelope.kind !== "completion_batch" ||
+    typeof envelope.batch_id !== "string" ||
+    !envelope.batch_id ||
+    envelope.batch_id.length > 128
+  ) return undefined;
+  return { batchId: envelope.batch_id, content: record.content };
+}
+
+/** Collapse exact retry duplicates and remove conflicting delivery envelopes. */
+export function dedupeRunCompletionBatchContext(messages: unknown[]): {
+  batches: Map<string, string>;
+  conflicts: Set<string>;
+  messages: unknown[];
+} {
+  const batches = new Map<string, string>();
+  const conflicts = new Set<string>();
+  for (const message of messages) {
+    const batch = completionBatchMessage(message);
+    if (!batch) continue;
+    const existing = batches.get(batch.batchId);
+    if (existing !== undefined && existing !== batch.content) {
+      conflicts.add(batch.batchId);
+    } else if (existing === undefined) {
+      batches.set(batch.batchId, batch.content);
+    }
+  }
+  const retained = new Set<string>();
+  const filtered = messages.filter((message) => {
+    const batch = completionBatchMessage(message);
+    if (!batch) return true;
+    if (conflicts.has(batch.batchId) || retained.has(batch.batchId)) return false;
+    retained.add(batch.batchId);
+    return true;
+  });
+  for (const batchId of conflicts) batches.delete(batchId);
+  return { batches, conflicts, messages: filtered };
+}
+
+export function removeRunCompletionBatchFromContext(
+  messages: unknown[],
+  batchId: string,
+): unknown[] {
+  return messages.filter((message) =>
+    completionBatchMessage(message)?.batchId !== batchId);
+}
+
+function steerMessage(
+  message: unknown,
+): { content: string; eventId: string; steerId: string } | undefined {
+  if (!message || typeof message !== "object" || Array.isArray(message)) return undefined;
+  const record = message as Record<string, unknown>;
+  if (record.customType !== RUN_STEER_CUSTOM_TYPE || typeof record.content !== "string") {
+    return undefined;
+  }
+  const details = record.details;
+  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+  const delivery = (details as Record<string, unknown>).pi_actors_delivery;
+  if (!delivery || typeof delivery !== "object" || Array.isArray(delivery)) return undefined;
+  const envelope = delivery as Record<string, unknown>;
+  if (
+    envelope.kind !== "urgent_steer" ||
+    typeof envelope.steer_id !== "string" ||
+    !envelope.steer_id ||
+    envelope.steer_id.length > 128 ||
+    typeof envelope.event_id !== "string" ||
+    !envelope.event_id ||
+    envelope.event_id.length > 256
+  ) return undefined;
+  return {
+    content: record.content,
+    eventId: envelope.event_id,
+    steerId: envelope.steer_id,
+  };
+}
+
+export function dedupeRunSteerContext(messages: unknown[]): {
+  conflicts: Set<string>;
+  messages: unknown[];
+  steers: Map<string, { content: string; eventId: string }>;
+} {
+  const conflicts = new Set<string>();
+  const steers = new Map<string, { content: string; eventId: string }>();
+  for (const message of messages) {
+    const steer = steerMessage(message);
+    if (!steer) continue;
+    const existing = steers.get(steer.steerId);
+    if (existing &&
+      (existing.content !== steer.content || existing.eventId !== steer.eventId)) {
+      conflicts.add(steer.steerId);
+    } else if (!existing) {
+      steers.set(steer.steerId, {
+        content: steer.content,
+        eventId: steer.eventId,
+      });
+    }
+  }
+  const retained = new Set<string>();
+  const filtered = messages.filter((message) => {
+    const steer = steerMessage(message);
+    if (!steer) return true;
+    if (conflicts.has(steer.steerId) || retained.has(steer.steerId)) return false;
+    retained.add(steer.steerId);
+    return true;
+  });
+  for (const steerId of conflicts) steers.delete(steerId);
+  return { conflicts, messages: filtered, steers };
+}
+
+export function removeRunSteerFromContext(
+  messages: unknown[],
+  steerId: string,
+): unknown[] {
+  return messages.filter((message) => steerMessage(message)?.steerId !== steerId);
+}
+
+export function inspectRunSteerSessionEvidence(
+  ctx: ExtensionContext,
+  input: { content: string; eventId: string; steerId: string },
+): SessionEvidence.ActiveSessionEntryEvidence {
+  return SessionEvidence.inspectBoundedActiveSessionEntries({
+    getEntry: (id) => ctx.sessionManager.getEntry(id),
+    leaf: ctx.sessionManager.getLeafEntry(),
+    match: (entry) => {
+      const steer = steerMessage(entry);
+      if (!steer || steer.steerId !== input.steerId) return undefined;
+      return steer.content === input.content && steer.eventId === input.eventId
+        ? "present"
+        : "conflict";
+    },
+  });
+}
+
+export function inspectRunCompletionBatchSessionEvidence(
+  ctx: ExtensionContext,
+  batchId: string,
+  content: string,
+): SessionEvidence.ActiveSessionEntryEvidence {
+  return SessionEvidence.inspectBoundedActiveSessionEntries({
+    getEntry: (id) => ctx.sessionManager.getEntry(id),
+    leaf: ctx.sessionManager.getLeafEntry(),
+    match: (entry) => {
+      const batch = completionBatchMessage(entry);
+      if (!batch || batch.batchId !== batchId) return undefined;
+      return batch.content === content ? "present" : "conflict";
+    },
+  });
+}
+
 export function registerToolDefinitions(
   pi: ExtensionAPI,
   definitions: Iterable<unknown>,