feat: add context engine transcript maintenance (#51191)

Merged via squash.

Prepared head SHA: b42a3c28b4
Co-authored-by: jalehman <550978+jalehman@users.noreply.github.com>
Co-authored-by: jalehman <550978+jalehman@users.noreply.github.com>
Reviewed-by: @jalehman

src/context-engine/types.ts

@@ -57,7 +57,43 @@ export type SubagentSpawnPreparation = {
 };
 
 export type SubagentEndReason = "deleted" | "completed" | "swept" | "released";
-export type ContextEngineRuntimeContext = Record<string, unknown>;
+
+export type TranscriptRewriteReplacement = {
+  /** Existing transcript entry id to replace on the active branch. */
+  entryId: string;
+  /** Replacement message content for that entry. */
+  message: AgentMessage;
+};
+
+export type TranscriptRewriteRequest = {
+  /** Message entry replacements to apply in one branch-and-reappend pass. */
+  replacements: TranscriptRewriteReplacement[];
+};
+
+export type TranscriptRewriteResult = {
+  /** Whether the active branch changed. */
+  changed: boolean;
+  /** Estimated bytes removed from the active branch message payloads. */
+  bytesFreed: number;
+  /** Number of transcript message entries rewritten. */
+  rewrittenEntries: number;
+  /** Optional reason when no rewrite occurred. */
+  reason?: string;
+};
+
+export type ContextEngineMaintenanceResult = TranscriptRewriteResult;
+
+export type ContextEngineRuntimeContext = Record<string, unknown> & {
+  /**
+   * Safe transcript rewrite helper implemented by the runtime.
+   *
+   * Engines decide what is safe to rewrite; the runtime owns how the session
+   * DAG is updated on disk.
+   */
+  rewriteTranscriptEntries?: (
+    request: TranscriptRewriteRequest,
+  ) => Promise<TranscriptRewriteResult>;
+};
 
 /**
  * ContextEngine defines the pluggable contract for context management.
@@ -78,6 +114,19 @@ export interface ContextEngine {
     sessionFile: string;
   }): Promise<BootstrapResult>;
 
+  /**
+   * Run transcript maintenance after bootstrap, successful turns, or compaction.
+   *
+   * Engines can use runtimeContext.rewriteTranscriptEntries() to request safe
+   * branch-and-reappend transcript rewrites without depending on Pi internals.
+   */
+  maintain?(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    runtimeContext?: ContextEngineRuntimeContext;
+  }): Promise<ContextEngineMaintenanceResult>;
+
   /**
    * Ingest a single message into the engine's store.
    */