Simplify.

This commit serves as the final polish for the context architecture unification.

Key Changes:
- **Lexical Cleansing:** Swept the entire `context` module (including tests, documentation, and snapshot configurations) to replace all legacy terms ('worker', 'ContextWorker', 'StateSnapshotWorker') with their modern unified equivalents ('async pipeline', 'AsyncContextProcessor', 'StateSnapshotAsyncProcessor').
- **Registry Cleanup:** Stripped `registry.ts` of `ContextWorkerDef` maps, unifying around a single, clean processor definition registry.
- **File Reorganization:** Dismantled the monolithic `sidecar/` directory (which initially housed both engine machinery and configuration loaders).
  - `pipeline/`: Now houses the core execution engine (`orchestrator`, `inbox`, `contextWorkingBuffer`, `environment`).
  - `config/`: Now exclusively contains the dynamic JSON configuration logic (`SidecarLoader`, `profiles`, `schema`, `registry`).

packages/core/src/config/config.ts

@@ -699,6 +699,7 @@ export interface ConfigParameters {
   experimentalJitContext?: boolean;
   autoDistillation?: boolean;
   experimentalMemoryManager?: boolean;
+  experimentalContextManagementConfig?: string;
   experimentalAgentHistoryTruncation?: boolean;
   experimentalAgentHistoryTruncationThreshold?: number;
   experimentalAgentHistoryRetainedMessages?: number;
@@ -940,6 +941,7 @@ export class Config implements McpContext, AgentLoopContext {
   private readonly adminSkillsEnabled: boolean;
   private readonly experimentalJitContext: boolean;
   private readonly experimentalMemoryManager: boolean;
+  private readonly experimentalContextManagementConfig?: string;
   private readonly memoryBoundaryMarkers: readonly string[];
   private readonly topicUpdateNarration: boolean;
   private readonly disableLLMCorrection: boolean;
@@ -1151,6 +1153,8 @@ export class Config implements McpContext, AgentLoopContext {
 
     this.experimentalJitContext = params.experimentalJitContext ?? false;
     this.experimentalMemoryManager = params.experimentalMemoryManager ?? false;
+    this.experimentalContextManagementConfig =
+      params.experimentalContextManagementConfig;
     this.memoryBoundaryMarkers = params.memoryBoundaryMarkers ?? ['.git'];
     this.contextManagement = {
       enabled: params.contextManagement?.enabled ?? false,
@@ -2413,6 +2417,10 @@ export class Config implements McpContext, AgentLoopContext {
     return this.experimentalMemoryManager;
   }
 
+  getExperimentalContextManagementConfig(): string | undefined {
+    return this.experimentalContextManagementConfig;
+  }
+
   getContextManagementConfig(): ContextManagementConfig {
     return this.contextManagement;
   }

packages/core/src/context/config/configLoader.test.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SidecarLoader } from './configLoader.js';
+import { defaultSidecarProfile } from './profiles.js';
+import { SidecarRegistry } from './registry.js';
+import { InMemoryFileSystem } from '../system/InMemoryFileSystem.js';
+import type { Config } from 'src/config/config.js';
+
+describe('SidecarLoader (Fake FS)', () => {
+  let fileSystem: InMemoryFileSystem;
+  let registry: SidecarRegistry;
+
+  beforeEach(() => {
+    fileSystem = new InMemoryFileSystem();
+    registry = new SidecarRegistry();
+    registry.registerProcessor({
+      id: 'NodeTruncation',
+      schema: { type: 'object', properties: { maxTokens: { type: 'number' } } },
+    });
+  });
+
+  const mockConfig = {
+    getExperimentalContextManagementConfig: () => '/path/to/sidecar.json',
+  } as unknown as Config;
+
+  it('returns default profile if file does not exist', () => {
+    const result = SidecarLoader.fromConfig(mockConfig, registry, fileSystem);
+    expect(result).toBe(defaultSidecarProfile);
+  });
+
+  it('returns default profile if file exists but is 0 bytes', () => {
+    fileSystem.setFile('/path/to/sidecar.json', '');
+    const result = SidecarLoader.fromConfig(mockConfig, registry, fileSystem);
+    expect(result).toBe(defaultSidecarProfile);
+  });
+
+  it('throws an error if file is empty whitespace', () => {
+    fileSystem.setFile('/path/to/sidecar.json', '   \n  ');
+    expect(() =>
+      SidecarLoader.fromConfig(mockConfig, registry, fileSystem),
+    ).toThrow('is empty');
+  });
+
+  it('returns parsed config if file is valid', () => {
+    const validConfig = {
+      budget: { retainedTokens: 1000, maxTokens: 2000 },
+      processorOptions: {
+        myTruncation: {
+          type: 'NodeTruncation',
+          options: { maxTokens: 500 },
+        },
+      },
+    };
+    fileSystem.setFile('/path/to/sidecar.json', JSON.stringify(validConfig));
+    const result = SidecarLoader.fromConfig(mockConfig, registry, fileSystem);
+    expect(result.config.budget?.maxTokens).toBe(2000);
+    expect(result.config.processorOptions?.['myTruncation']).toBeDefined();
+  });
+
+  it('throws validation error if processorOptions contains invalid data for the schema', () => {
+    const invalidConfig = {
+      budget: { retainedTokens: 1000, maxTokens: 2000 },
+      processorOptions: {
+        myTruncation: {
+          type: 'NodeTruncation',
+          options: { maxTokens: 'this should be a number' },
+        },
+      },
+    };
+    fileSystem.setFile('/path/to/sidecar.json', JSON.stringify(invalidConfig));
+    expect(() =>
+      SidecarLoader.fromConfig(mockConfig, registry, fileSystem),
+    ).toThrow('Validation error');
+  });
+
+  it('throws validation error if file is empty whitespace', () => {
+    fileSystem.setFile('/path/to/sidecar.json', '   \n  ');
+    expect(() =>
+      SidecarLoader.fromConfig(mockConfig, registry, fileSystem),
+    ).toThrow('is empty');
+  });
+});

packages/core/src/context/config/configLoader.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config } from '../../config/config.js';
+import type { SidecarConfig } from './types.js';
+import { defaultSidecarProfile, type ContextProfile } from './profiles.js';
+import { SchemaValidator } from '../../utils/schemaValidator.js';
+import { getSidecarConfigSchema } from './schema.js';
+import type { SidecarRegistry } from './registry.js';
+import type { IFileSystem } from '../system/IFileSystem.js';
+import { NodeFileSystem } from '../system/NodeFileSystem.js';
+import { getErrorMessage } from '../../utils/errors.js';
+
+export class SidecarLoader {
+  /**
+   * Loads and validates a sidecar config from a specific file path.
+   * Throws an error if the file cannot be read, parsed, or fails schema validation.
+   */
+  static loadFromFile(
+    sidecarPath: string,
+    registry: SidecarRegistry,
+    fileSystem: IFileSystem = new NodeFileSystem(),
+  ): ContextProfile {
+    const fileContent = fileSystem.readFileSync(sidecarPath, 'utf8');
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fileContent);
+    } catch (error) {
+      throw new Error(
+        `Failed to parse Sidecar configuration file at ${sidecarPath}: ${
+          getErrorMessage(error)
+        }`,
+      );
+    }
+
+    // Validate the complete structure, including deep options
+    const validationError = SchemaValidator.validate(
+      getSidecarConfigSchema(registry),
+      parsed,
+    );
+
+    if (validationError) {
+      throw new Error(
+        `Invalid sidecar configuration in ${sidecarPath}. Validation error: ${validationError}`,
+      );
+    }
+
+    // Extract strictly what we need.
+    // Why this unsafe cast is acceptable:
+    // SchemaValidator just ran \`getSidecarConfigSchema(registry)\` against \`parsed\`.
+    // That function dynamically maps the \`processorOptions\` to strict JSON schema definitions,
+    // so we know with absolute certainty at runtime that \`parsed\` conforms to this shape.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const validConfig = parsed as SidecarConfig;
+    return {
+      ...defaultSidecarProfile,
+      config: {
+        ...defaultSidecarProfile.config,
+        ...(validConfig.budget ? { budget: validConfig.budget } : {}),
+        ...(validConfig.processorOptions
+          ? { processorOptions: validConfig.processorOptions }
+          : {}),
+      },
+    };
+  }
+
+  /**
+   * Generates a Sidecar JSON graph from the experimental config file path or defaults.
+   * If a config file is present but invalid, this will THROW to prevent silent misconfiguration.
+   */
+  static fromConfig(
+    config: Config,
+    registry: SidecarRegistry,
+    fileSystem: IFileSystem = new NodeFileSystem(),
+  ): ContextProfile {
+    const sidecarPath = config.getExperimentalContextManagementConfig();
+
+    if (sidecarPath && fileSystem.existsSync(sidecarPath)) {
+      const size = fileSystem.statSyncSize(sidecarPath);
+      // If the file exists but is completely empty (0 bytes), it's safe to fallback.
+      if (size === 0) {
+        return defaultSidecarProfile;
+      }
+
+      // If the file has content, enforce strict validation and throw on failure.
+      return this.loadFromFile(sidecarPath, registry, fileSystem);
+    }
+
+    return defaultSidecarProfile;
+  }
+}

packages/core/src/context/config/profiles.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { AsyncPipelineDef, SidecarConfig, PipelineDef } from './types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+
+// Import factories
+import { createToolMaskingProcessor } from '../processors/toolMaskingProcessor.js';
+import { createBlobDegradationProcessor } from '../processors/blobDegradationProcessor.js';
+import { createNodeTruncationProcessor } from '../processors/nodeTruncationProcessor.js';
+import { createNodeDistillationProcessor } from '../processors/nodeDistillationProcessor.js';
+import { createStateSnapshotProcessor } from '../processors/stateSnapshotProcessor.js';
+import { createStateSnapshotAsyncProcessor } from '../processors/stateSnapshotAsyncProcessor.js';
+
+/**
+ * Helper to safely merge static default options with dynamically loaded
+ * JSON overrides from the SidecarConfig.
+ *
+ * Why the unsafe cast is acceptable here:
+ * Before the \`config\` object ever reaches this function, \`SidecarLoader.ts\`
+ * passes the raw JSON through \`SchemaValidator\`. The schema dynamically generates
+ * a \`oneOf\` map linking every \`type\` discriminator to its corresponding processor
+ * schema definition. By the time we access \`options\` here, its shape has been
+ * strictly validated against the corresponding Zod/JSONSchema definition at runtime,
+ * making the generic cast to \`<T>\` structurally safe.
+ */
+function resolveProcessorOptions<T>(
+  config: SidecarConfig | undefined,
+  id: string,
+  defaultOptions: T,
+): T {
+  if (config?.processorOptions && config.processorOptions[id]) {
+    return {
+      ...defaultOptions,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      ...(config.processorOptions[id].options as T),
+    };
+  }
+  return defaultOptions;
+}
+
+export interface ContextProfile {
+  config: SidecarConfig;
+  buildPipelines: (
+    env: ContextEnvironment,
+    config?: SidecarConfig,
+  ) => PipelineDef[];
+  buildAsyncPipelines: (
+    env: ContextEnvironment,
+    config?: SidecarConfig,
+  ) => AsyncPipelineDef[];
+}
+
+/**
+ * The standard default context management profile.
+ * Optimized for safety, precision, and reliable summarization.
+ */
+export const defaultSidecarProfile: ContextProfile = {
+  config: {
+    budget: {
+      retainedTokens: 65000,
+      maxTokens: 150000,
+    },
+  },
+
+  buildPipelines: (
+    env: ContextEnvironment,
+    config?: SidecarConfig,
+  ): PipelineDef[] =>
+    // Helper to merge default options with dynamically loaded processorOptions by ID
+    [
+      {
+        name: 'Immediate Sanitization',
+        triggers: ['new_message'],
+        processors: [
+          createToolMaskingProcessor(
+            'ToolMasking',
+            env,
+            resolveProcessorOptions(config, 'ToolMasking', {
+              stringLengthThresholdTokens: 8000,
+            }),
+          ),
+          createBlobDegradationProcessor('BlobDegradation', env), // No options
+        ],
+      },
+      {
+        name: 'Normalization',
+        triggers: ['retained_exceeded'],
+        processors: [
+          createNodeTruncationProcessor(
+            'NodeTruncation',
+            env,
+            resolveProcessorOptions(config, 'NodeTruncation', {
+              maxTokensPerNode: 3000,
+            }),
+          ),
+          createNodeDistillationProcessor(
+            'NodeDistillation',
+            env,
+            resolveProcessorOptions(config, 'NodeDistillation', {
+              nodeThresholdTokens: 5000,
+            }),
+          ),
+        ],
+      },
+      {
+        name: 'Emergency Backstop',
+        triggers: ['gc_backstop'],
+        processors: [
+          createStateSnapshotProcessor(
+            'StateSnapshotSync',
+            env,
+            resolveProcessorOptions(config, 'StateSnapshotSync', {
+              target: 'max',
+            }),
+          ),
+        ],
+      },
+    ],
+  buildAsyncPipelines: (
+    env: ContextEnvironment,
+    config?: SidecarConfig,
+  ): AsyncPipelineDef[] => [
+    {
+      name: 'Async Background GC',
+      triggers: ['nodes_aged_out'],
+      processors: [
+        createStateSnapshotAsyncProcessor(
+          'StateSnapshotAsync',
+          env,
+          resolveProcessorOptions(config, 'StateSnapshotAsync', {
+            type: 'accumulate',
+          }),
+        ),
+      ],
+    },
+  ],
+};

packages/core/src/context/config/registry.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface ContextProcessorDef {
+  readonly id: string;
+  readonly schema: object;
+}
+
+/**
+ * Registry for validating declarative sidecar configuration schemas.
+ * (Dynamic instantiation has been replaced by static ContextProfiles)
+ */
+export class SidecarRegistry {
+  private readonly processors = new Map<string, ContextProcessorDef>();
+
+  registerProcessor(def: ContextProcessorDef) {
+    this.processors.set(def.id, def);
+  }
+
+  getSchema(id: string): object | undefined {
+    return this.processors.get(id)?.schema;
+  }
+
+  getSchemaDefs(): ContextProcessorDef[] {
+    const defs = [];
+    for (const def of this.processors.values()) {
+      if (def.schema) defs.push({ id: def.id, schema: def.schema });
+    }
+    return defs;
+  }
+
+  clear() {
+    this.processors.clear();
+  }
+}

packages/core/src/context/config/schema.ts

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { SidecarRegistry } from './registry.js';
+
+export function getSidecarConfigSchema(registry?: SidecarRegistry) {
+  // If a registry is provided, we can deeply validate processor overrides.
+  // We do this by generating a `oneOf` list that matches the `type` discriminator
+  // to the specific processor `options` schema.
+  const processorOptionSchemas = registry
+    ? registry.getSchemaDefs().map((def) => ({
+        type: 'object',
+        required: ['type', 'options'],
+        properties: {
+          type: { const: def.id },
+          options: def.schema,
+        },
+      }))
+    : [];
+
+  const processorOptionsMapping =
+    processorOptionSchemas.length > 0
+      ? { oneOf: processorOptionSchemas }
+      : {
+          type: 'object',
+          required: ['type', 'options'],
+          properties: {
+            type: {
+              type: 'string',
+              description:
+                'The registry type of the processor (e.g. NodeTruncation)',
+            },
+            options: {
+              type: 'object',
+              description: 'The hyperparameter overrides',
+            },
+          },
+        };
+
+  return {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'SidecarConfig',
+    description: 'The Hyperparameter schema for a Context Profile.',
+    type: 'object',
+    properties: {
+      budget: {
+        type: 'object',
+        description: 'Defines the token ceilings and limits for the pipeline.',
+        required: ['retainedTokens', 'maxTokens'],
+        properties: {
+          retainedTokens: {
+            type: 'number',
+            description:
+              'The ideal token count the pipeline tries to shrink down to.',
+          },
+          maxTokens: {
+            type: 'number',
+            description:
+              'The absolute maximum token count allowed before synchronous truncation kicks in.',
+          },
+        },
+      },
+      processorOptions: {
+        type: 'object',
+        description:
+          'Named hyperparameter configurations for ContextProcessors and AsyncProcessors.',
+        additionalProperties: processorOptionsMapping,
+      },
+    },
+  };
+}

packages/core/src/context/config/types.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ContextProcessor, AsyncContextProcessor } from '../pipeline.js';
+
+export type PipelineTrigger =
+  | 'new_message'
+  | 'retained_exceeded'
+  | 'gc_backstop'
+  | 'nodes_added'
+  | 'nodes_aged_out'
+  | { type: 'timer'; intervalMs: number };
+
+export interface PipelineDef {
+  name: string;
+  triggers: PipelineTrigger[];
+  processors: ContextProcessor[];
+}
+
+export interface AsyncPipelineDef {
+  name: string;
+  triggers: PipelineTrigger[];
+  processors: AsyncContextProcessor[];
+}
+
+/**
+ * The Data-Driven Schema for the Context Manager.
+ */
+export interface SidecarConfig {
+  /** Defines the token ceilings and limits for the pipeline. */
+  budget: {
+    retainedTokens: number;
+    maxTokens: number;
+  };
+  /**
+   * Dynamic hyperparameter overrides for individual ContextProcessors and AsyncProcessors.
+   * Keys are named identifiers (e.g. "gentleTruncation").
+   */
+  processorOptions?: Record<string, { type: string; options: unknown }>;
+}

packages/core/src/context/contextManager.barrier.test.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { testTruncateProfile } from './testing/testProfile.js';
+import {
+  createSyntheticHistory,
+  createMockContextConfig,
+  setupContextComponentTest,
+} from './testing/contextTestUtils.js';
+
+describe('ContextManager Sync Pressure Barrier Tests', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('should instantly truncate history when maxTokens is exceeded using truncate strategy', async () => {
+    // 1. Setup
+    const config = createMockContextConfig();
+    const { chatHistory, contextManager } = setupContextComponentTest(
+      config,
+      testTruncateProfile,
+    );
+
+    // 2. Add System Prompt (Episode 0 - Protected)
+    chatHistory.set([
+      { role: 'user', parts: [{ text: 'System prompt' }] },
+      { role: 'model', parts: [{ text: 'Understood.' }] },
+    ]);
+
+    // 3. Add massive history that blows past the 150k maxTokens limit
+    // 20 turns * 10,000 tokens/turn = ~200,000 tokens
+    const massiveHistory = createSyntheticHistory(20, 35000);
+    chatHistory.set([...chatHistory.get(), ...massiveHistory]);
+
+    // 4. Add the Latest Turn (Protected)
+    chatHistory.set([
+      ...chatHistory.get(),
+      { role: 'user', parts: [{ text: 'Final question.' }] },
+      { role: 'model', parts: [{ text: 'Final answer.' }] },
+    ]);
+
+    const rawHistoryLength = chatHistory.get().length;
+
+    // 5. Project History (Triggers Sync Barrier)
+    const projection = await contextManager.projectCompressedHistory();
+
+    // 6. Assertions
+    // The barrier should have dropped several older episodes to get under 150k.
+
+    expect(projection.length).toBeLessThan(rawHistoryLength);
+
+    // Verify Episode 0 (System) is perfectly preserved at the front
+
+    expect(projection[0].role).toBe('user');
+    expect(projection[0].parts![0].text).toBe('System prompt');
+
+    // Filter out synthetic Yield nodes (they are model responses without actual tool/text bodies)
+    const contentNodes = projection.filter(
+      (p) =>
+        p.parts && p.parts.some((part) => part.text && part.text !== 'Yield'),
+    );
+
+    // Verify the latest turn is perfectly preserved at the back
+    const lastUser = contentNodes[contentNodes.length - 2];
+    const lastModel = contentNodes[contentNodes.length - 1];
+
+    expect(lastUser.role).toBe('user');
+    expect(lastUser.parts![0].text).toBe('Final question.');
+
+    expect(lastModel.role).toBe('model');
+    expect(lastModel.parts![0].text).toBe('Final answer.');
+  });
+});

packages/core/src/context/contextManager.ts

@@ -0,0 +1,269 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/genai';
+import type { AgentChatHistory, HistoryEvent } from '../core/agentChatHistory.js';
+import type { ConcreteNode } from './ir/types.js';
+import type { ContextTracer } from './tracer.js';
+import type { ContextEnvironment } from './pipeline/environment.js';
+import type { ContextProfile } from './config/profiles.js';
+import { IrProjector } from './ir/projector.js';
+import { ContextWorkingBufferImpl } from './pipeline/contextWorkingBuffer.js';
+import type { PipelineDef, AsyncPipelineDef, PipelineTrigger } from './config/types.js';
+import { debugLogger } from '../utils/debugLogger.js';
+
+export class ContextManager {
+  private buffer: ContextWorkingBufferImpl = ContextWorkingBufferImpl.initialize([]);
+  private pristineNodes: readonly ConcreteNode[] = [];
+  
+  private unsubscribeHistory?: () => void;
+  private seenNodeIds = new Set<string>();
+  private activeTimers: NodeJS.Timeout[] = [];
+  
+  private pipelines: PipelineDef[] = [];
+  private asyncPipelines: AsyncPipelineDef[] = [];
+
+  constructor(
+    private readonly sidecar: ContextProfile,
+    private readonly env: ContextEnvironment,
+    private readonly tracer: ContextTracer,
+    private readonly chatHistory: AgentChatHistory,
+  ) {
+    this.pipelines = sidecar.buildPipelines(env);
+    this.asyncPipelines = sidecar.buildAsyncPipelines(env);
+    this.setupTriggers();
+    this.startHistoryObserver();
+  }
+
+  private startHistoryObserver() {
+    this.unsubscribeHistory = this.chatHistory.subscribe((_event: HistoryEvent) => {
+      const pristineEpisodes = this.env.irMapper.toIr(
+        this.chatHistory.get(),
+        this.env.tokenCalculator,
+      );
+
+      const nodes: ConcreteNode[] = [];
+      for (const ep of pristineEpisodes) {
+        if (ep.concreteNodes) {
+          for (const child of ep.concreteNodes) {
+            nodes.push(child);
+          }
+        }
+      }
+
+      const newNodes = new Set<string>();
+      for (const node of nodes) {
+        if (!this.seenNodeIds.has(node.id)) {
+          newNodes.add(node.id);
+          this.seenNodeIds.add(node.id);
+        }
+      }
+
+      this.tracer.logEvent(
+        'ContextManager',
+        'Rebuilt pristine graph from chat history update',
+        { nodesSize: nodes.length, newNodesCount: newNodes.size },
+      );
+
+      this.pristineNodes = nodes;
+
+      const existingIds = new Set(this.buffer.nodes.map((n) => n.id));
+      const addedNodes = nodes.filter((n) => !existingIds.has(n.id));
+
+      if (addedNodes.length > 0) {
+        this.buffer = this.buffer.appendPristineNodes(addedNodes);
+      }
+
+      this.evaluateTriggers(newNodes);
+    });
+  }
+
+  private setupTriggers() {
+    // In V1, background timers were set up here.
+    for (const pipeline of this.pipelines) {
+      for (const trigger of pipeline.triggers) {
+        if (typeof trigger === 'object' && trigger.type === 'timer') {
+          const timer = setInterval(() => {}, trigger.intervalMs);
+          this.activeTimers.push(timer);
+        }
+      }
+    }
+  }
+
+  private evaluateTriggers(newNodes: Set<string>) {
+    if (!this.sidecar.config.budget) return;
+
+    if (newNodes.size > 0) {
+      this.executeTrigger('new_message', newNodes);
+      this.executeTrigger('nodes_added', newNodes);
+    }
+
+    const currentTokens = this.env.tokenCalculator.calculateConcreteListTokens(this.buffer.nodes);
+
+    if (currentTokens > this.sidecar.config.budget.retainedTokens) {
+      const agedOutNodes = new Set<string>();
+      let rollingTokens = 0;
+      for (let i = this.buffer.nodes.length - 1; i >= 0; i--) {
+        const node = this.buffer.nodes[i];
+        rollingTokens += this.env.tokenCalculator.calculateConcreteListTokens([node]);
+        if (rollingTokens > this.sidecar.config.budget.retainedTokens) {
+          agedOutNodes.add(node.id);
+        }
+      }
+
+      if (agedOutNodes.size > 0) {
+        this.executeTrigger('retained_exceeded', agedOutNodes);
+        this.executeTrigger('nodes_aged_out', agedOutNodes);
+      }
+    }
+  }
+
+  private executeTrigger(trigger: PipelineTrigger, targetNodeIds: ReadonlySet<string>) {
+    const triggerPipelines = this.pipelines.filter(p => p.triggers.includes(trigger));
+    for (const pipeline of triggerPipelines) {
+      void this.executePipelineAsync(pipeline, this.buffer.nodes, targetNodeIds, new Set());
+    }
+
+    const triggerAsyncPipelines = this.asyncPipelines.filter(p => p.triggers.includes(trigger));
+    for (const pipeline of triggerAsyncPipelines) {
+      const targets = this.buffer.nodes.filter(n => targetNodeIds.has(n.id));
+      for (const processor of pipeline.processors) {
+        processor.process({
+          targets,
+          snapshotCache: this.env.snapshotCache,
+          buffer: ContextWorkingBufferImpl.initialize(this.buffer.nodes),
+        }).catch(e => debugLogger.error(`AsyncProcessor ${processor.name} failed:`, e));
+      }
+    }
+  }
+
+  async executeTriggerSync(
+    trigger: PipelineTrigger,
+    nodes: readonly ConcreteNode[],
+    triggerTargets: ReadonlySet<string>,
+    protectedLogicalIds: ReadonlySet<string> = new Set(),
+  ): Promise<readonly ConcreteNode[]> {
+    let currentBuffer = ContextWorkingBufferImpl.initialize(nodes);
+    const triggerPipelines = this.pipelines.filter((p) => p.triggers.includes(trigger));
+
+    for (const pipeline of triggerPipelines) {
+      for (const processor of pipeline.processors) {
+        try {
+          this.tracer.logEvent('ContextManager', `Executing processor synchronously: ${processor.id}`);
+
+          const allowedTargets = currentBuffer.nodes.filter((n) =>
+            this.isNodeAllowed(n, triggerTargets, protectedLogicalIds)
+          );
+
+          const returnedNodes = await processor.process({
+            buffer: currentBuffer,
+            targets: allowedTargets,
+            snapshotCache: this.env.snapshotCache,
+          });
+
+          currentBuffer = currentBuffer.applyProcessorResult(
+            processor.id,
+            allowedTargets,
+            returnedNodes,
+          );
+        } catch (error) {
+          debugLogger.error(`Synchronous processor ${processor.id} failed:`, error);
+        }
+      }
+    }
+
+    return currentBuffer.nodes;
+  }
+
+  private async executePipelineAsync(
+    pipeline: PipelineDef,
+    nodes: readonly ConcreteNode[],
+    triggerTargets: ReadonlySet<string>,
+    protectedLogicalIds: ReadonlySet<string> = new Set(),
+  ) {
+    this.tracer.logEvent('ContextManager', `Triggering async pipeline: ${pipeline.name}`);
+    if (!nodes || nodes.length === 0) return;
+
+    let currentBuffer = ContextWorkingBufferImpl.initialize(nodes);
+
+    for (const processor of pipeline.processors) {
+      try {
+        this.tracer.logEvent('ContextManager', `Executing processor: ${processor.id} (async)`);
+
+        const allowedTargets = currentBuffer.nodes.filter((n) =>
+          this.isNodeAllowed(n, triggerTargets, protectedLogicalIds)
+        );
+
+        const returnedNodes = await processor.process({
+          buffer: currentBuffer,
+          targets: allowedTargets,
+          snapshotCache: this.env.snapshotCache,
+        });
+
+        currentBuffer = currentBuffer.applyProcessorResult(
+          processor.id,
+          allowedTargets,
+          returnedNodes,
+        );
+      } catch (error) {
+        debugLogger.error(`Pipeline ${pipeline.name} failed async at ${processor.id}:`, error);
+        return;
+      }
+    }
+    
+    // Push the state to buffer
+    this.buffer = currentBuffer;
+  }
+
+  private isNodeAllowed(
+    node: ConcreteNode,
+    triggerTargets: ReadonlySet<string>,
+    protectedLogicalIds: ReadonlySet<string> = new Set(),
+  ): boolean {
+    return (
+      triggerTargets.has(node.id) &&
+      !protectedLogicalIds.has(node.id) &&
+      (!node.logicalParentId || !protectedLogicalIds.has(node.logicalParentId))
+    );
+  }
+
+  shutdown() {
+    for (const timer of this.activeTimers) {
+      clearInterval(timer);
+    }
+    if (this.unsubscribeHistory) {
+      this.unsubscribeHistory();
+      this.unsubscribeHistory = undefined;
+    }
+  }
+
+  getPristineGraph(): readonly ConcreteNode[] {
+    return [...this.pristineNodes];
+  }
+
+  getNodes(): readonly ConcreteNode[] {
+    return [...this.buffer.nodes];
+  }
+
+  async projectCompressedHistory(
+    activeTaskIds: Set<string> = new Set(),
+  ): Promise<Content[]> {
+    this.tracer.logEvent('ContextManager', 'Starting projection to LLM context');
+    
+    const finalHistory = await IrProjector.project(
+      this.buffer.nodes,
+      this,
+      this.sidecar,
+      this.tracer,
+      this.env,
+      activeTaskIds,
+    );
+
+    this.tracer.logEvent('ContextManager', 'Finished projection');
+
+    return finalHistory;
+  }
+}

packages/core/src/context/ir/behaviorRegistry.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content, Part } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+
+export interface IrSerializationWriter {
+  appendContent(content: Content): void;
+  appendModelPart(part: Part): void;
+  appendUserPart(part: Part): void;
+  flushModelParts(): void;
+}
+
+export interface IrNodeBehavior<T extends ConcreteNode = ConcreteNode> {
+  readonly type: T['type'];
+
+  /** Serializes the node into the Gemini Content structure. */
+  serialize(node: T, writer: IrSerializationWriter): void;
+
+  /**
+   * Generates a structural representation of the node for the purpose
+   * of estimating its token cost.
+   */
+  getEstimatableParts(node: T): Part[];
+}
+
+export class IrNodeBehaviorRegistry {
+  private readonly behaviors = new Map<string, IrNodeBehavior<ConcreteNode>>();
+
+  register<T extends ConcreteNode>(behavior: IrNodeBehavior<T>) {
+    this.behaviors.set(behavior.type, behavior as IrNodeBehavior<ConcreteNode>);
+  }
+
+  get(type: string): IrNodeBehavior<ConcreteNode> {
+    const behavior = this.behaviors.get(type);
+    if (!behavior) {
+      throw new Error(`Unregistered IrNode type: ${type}`);
+    }
+    return behavior;
+  }
+}

packages/core/src/context/ir/builtinBehaviors.ts

@@ -0,0 +1,175 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Part } from '@google/genai';
+import type {
+  IrNodeBehavior,
+  IrNodeBehaviorRegistry,
+} from './behaviorRegistry.js';
+import type {
+  UserPrompt,
+  AgentThought,
+  ToolExecution,
+  MaskedTool,
+  AgentYield,
+  Snapshot,
+  RollingSummary,
+  SystemEvent,
+} from './types.js';
+
+export const UserPromptBehavior: IrNodeBehavior<UserPrompt> = {
+  type: 'USER_PROMPT',
+  getEstimatableParts(prompt) {
+    const parts: Part[] = [];
+    for (const sp of prompt.semanticParts) {
+      switch (sp.type) {
+        case 'text':
+          parts.push({ text: sp.text });
+          break;
+        case 'inline_data':
+          parts.push({ inlineData: { mimeType: sp.mimeType, data: sp.data } });
+          break;
+        case 'file_data':
+          parts.push({
+            fileData: { mimeType: sp.mimeType, fileUri: sp.fileUri },
+          });
+          break;
+        case 'raw_part':
+          parts.push(sp.part);
+          break;
+        default:
+          break;
+      }
+    }
+    return parts;
+  },
+  serialize(prompt, writer) {
+    const parts = this.getEstimatableParts(prompt);
+    if (parts.length > 0) {
+      writer.flushModelParts();
+      writer.appendContent({ role: 'user', parts });
+    }
+  },
+};
+
+export const AgentThoughtBehavior: IrNodeBehavior<AgentThought> = {
+  type: 'AGENT_THOUGHT',
+  getEstimatableParts(thought) {
+    return [{ text: thought.text }];
+  },
+  serialize(thought, writer) {
+    writer.appendModelPart({ text: thought.text });
+  },
+};
+
+export const ToolExecutionBehavior: IrNodeBehavior<ToolExecution> = {
+  type: 'TOOL_EXECUTION',
+  getEstimatableParts(tool) {
+    return [
+      { functionCall: { id: tool.id, name: tool.toolName, args: tool.intent } },
+      {
+        functionResponse: {
+          id: tool.id,
+          name: tool.toolName,
+          response:
+            typeof tool.observation === 'string'
+              ? { message: tool.observation }
+              : tool.observation,
+        },
+      },
+    ];
+  },
+  serialize(tool, writer) {
+    const parts = this.getEstimatableParts(tool);
+    writer.appendModelPart(parts[0]);
+    writer.flushModelParts();
+    writer.appendUserPart(parts[1]);
+  },
+};
+
+export const MaskedToolBehavior: IrNodeBehavior<MaskedTool> = {
+  type: 'MASKED_TOOL',
+  getEstimatableParts(tool) {
+    return [
+      {
+        functionCall: {
+          id: tool.id,
+          name: tool.toolName,
+          args: tool.intent ?? {},
+        },
+      },
+      {
+        functionResponse: {
+          id: tool.id,
+          name: tool.toolName,
+          response:
+            typeof tool.observation === 'string'
+              ? { message: tool.observation }
+              : (tool.observation ?? {}),
+        },
+      },
+    ];
+  },
+  serialize(tool, writer) {
+    const parts = this.getEstimatableParts(tool);
+    writer.appendModelPart(parts[0]);
+    writer.flushModelParts();
+    writer.appendUserPart(parts[1]);
+  },
+};
+
+export const AgentYieldBehavior: IrNodeBehavior<AgentYield> = {
+  type: 'AGENT_YIELD',
+  getEstimatableParts(yieldNode) {
+    return [{ text: yieldNode.text }];
+  },
+  serialize(yieldNode, writer) {
+    writer.appendModelPart({ text: yieldNode.text });
+    writer.flushModelParts();
+  },
+};
+
+export const SystemEventBehavior: IrNodeBehavior<SystemEvent> = {
+  type: 'SYSTEM_EVENT',
+  getEstimatableParts() {
+    return [];
+  },
+  serialize(node, writer) {
+    writer.flushModelParts();
+  },
+};
+
+export const SnapshotBehavior: IrNodeBehavior<Snapshot> = {
+  type: 'SNAPSHOT',
+  getEstimatableParts(node) {
+    return [{ text: node.text }];
+  },
+  serialize(node, writer) {
+    writer.flushModelParts();
+    writer.appendUserPart({ text: node.text });
+  },
+};
+
+export const RollingSummaryBehavior: IrNodeBehavior<RollingSummary> = {
+  type: 'ROLLING_SUMMARY',
+  getEstimatableParts(node) {
+    return [{ text: node.text }];
+  },
+  serialize(node, writer) {
+    writer.flushModelParts();
+    writer.appendUserPart({ text: node.text });
+  },
+};
+
+export function registerBuiltInBehaviors(registry: IrNodeBehaviorRegistry) {
+  registry.register(UserPromptBehavior);
+  registry.register(AgentThoughtBehavior);
+  registry.register(ToolExecutionBehavior);
+  registry.register(MaskedToolBehavior);
+  registry.register(AgentYieldBehavior);
+  registry.register(SystemEventBehavior);
+  registry.register(SnapshotBehavior);
+  registry.register(RollingSummaryBehavior);
+}

packages/core/src/context/ir/fromIr.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content, Part } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+import type {
+  IrSerializationWriter,
+  IrNodeBehaviorRegistry,
+} from './behaviorRegistry.js';
+
+class IrSerializer implements IrSerializationWriter {
+  private history: Content[] = [];
+  private currentModelParts: Part[] = [];
+
+  appendContent(content: Content) {
+    this.flushModelParts();
+    this.history.push(content);
+  }
+
+  appendModelPart(part: Part) {
+    this.currentModelParts.push(part);
+  }
+
+  appendUserPart(part: Part) {
+    this.flushModelParts();
+    this.history.push({ role: 'user', parts: [part] });
+  }
+
+  flushModelParts() {
+    if (this.currentModelParts.length > 0) {
+      this.history.push({ role: 'model', parts: [...this.currentModelParts] });
+      this.currentModelParts = [];
+    }
+  }
+
+  getContents(): Content[] {
+    this.flushModelParts();
+    return this.history;
+  }
+}
+
+export function fromIr(
+  nodes: readonly ConcreteNode[],
+  registry: IrNodeBehaviorRegistry,
+): Content[] {
+  const writer = new IrSerializer();
+  for (const node of nodes) {
+    const behavior = registry.get(node.type);
+    behavior.serialize(node, writer);
+  }
+  return writer.getContents();
+}

packages/core/src/context/ir/graphUtils.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  Episode,
+  Task,
+  IrNode,
+  AgentThought,
+  ToolExecution,
+  MaskedTool,
+  UserPrompt,
+  AgentYield,
+  SystemEvent,
+  Snapshot,
+  RollingSummary,
+} from './types.js';
+
+export function isEpisode(node: IrNode): node is Episode {
+  return node.type === 'EPISODE';
+}
+
+export function isTask(node: IrNode): node is Task {
+  return node.type === 'TASK';
+}
+
+export function isAgentThought(node: IrNode): node is AgentThought {
+  return node.type === 'AGENT_THOUGHT';
+}
+
+export function isAgentYield(node: IrNode): node is AgentYield {
+  return node.type === 'AGENT_YIELD';
+}
+
+export function isToolExecution(node: IrNode): node is ToolExecution {
+  return node.type === 'TOOL_EXECUTION';
+}
+
+export function isMaskedTool(node: IrNode): node is MaskedTool {
+  return node.type === 'MASKED_TOOL';
+}
+
+export function isUserPrompt(node: IrNode): node is UserPrompt {
+  return node.type === 'USER_PROMPT';
+}
+
+export function isSystemEvent(node: IrNode): node is SystemEvent {
+  return node.type === 'SYSTEM_EVENT';
+}
+
+export function isSnapshot(node: IrNode): node is Snapshot {
+  return node.type === 'SNAPSHOT';
+}
+
+export function isRollingSummary(node: IrNode): node is RollingSummary {
+  return node.type === 'ROLLING_SUMMARY';
+}

packages/core/src/context/ir/mapper.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Content } from '@google/genai';
+import type { Episode, ConcreteNode } from './types.js';
+import { toIr } from './toIr.js';
+import { fromIr } from './fromIr.js';
+import type { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import type { IrNodeBehaviorRegistry } from './behaviorRegistry.js';
+import type { IIdGenerator } from '../system/IIdGenerator.js';
+
+export class IrMapper {
+  private readonly nodeIdentityMap = new WeakMap<object, string>();
+
+  constructor(
+    private readonly registry: IrNodeBehaviorRegistry,
+    private readonly idGenerator: IIdGenerator,
+  ) {}
+
+  toIr(
+    history: readonly Content[],
+    tokenCalculator: ContextTokenCalculator,
+  ): Episode[] {
+    return toIr(
+      history,
+      tokenCalculator,
+      this.nodeIdentityMap,
+      this.idGenerator,
+    );
+  }
+
+  fromIr(nodes: readonly ConcreteNode[]): Content[] {
+    return fromIr(nodes, this.registry);
+  }
+}

packages/core/src/context/ir/projector.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/genai';
+import type { ConcreteNode } from './types.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import type {
+  ContextEnvironment,
+  ContextTracer,
+} from '../pipeline/environment.js';
+import type { ContextManager } from '../contextManager.js';
+import type { ContextProfile } from '../config/profiles.js';
+
+export class IrProjector {
+  /**
+   * Orchestrates the final projection: takes a working buffer view (The Nodes),
+   * applies the Immediate Sanitization pipeline, and enforces token boundaries.
+   */
+  static async project(
+    nodes: readonly ConcreteNode[],
+    contextManager: ContextManager,
+    sidecar: ContextProfile,
+    tracer: ContextTracer,
+    env: ContextEnvironment,
+    protectedIds: Set<string>,
+  ): Promise<Content[]> {
+    if (!sidecar.config.budget) {
+      const contents = env.irMapper.fromIr(nodes);
+      tracer.logEvent('IrProjector', 'Projected Context to LLM (No Budget)', {
+        projectedContext: contents,
+      });
+      return contents;
+    }
+
+    const maxTokens = sidecar.config.budget.maxTokens;
+    const currentTokens =
+      env.tokenCalculator.calculateConcreteListTokens(nodes);
+
+    // V0: Always protect the first node (System Prompt) and the last turn
+    if (nodes.length > 0) {
+      protectedIds.add(nodes[0].id);
+      if (nodes[0].logicalParentId) protectedIds.add(nodes[0].logicalParentId);
+
+      const lastNode = nodes[nodes.length - 1];
+      protectedIds.add(lastNode.id);
+      if (lastNode.logicalParentId) protectedIds.add(lastNode.logicalParentId);
+    }
+
+    if (currentTokens <= maxTokens) {
+      tracer.logEvent(
+        'IrProjector',
+        `View is within maxTokens (${currentTokens} <= ${maxTokens}). Returning view.`,
+      );
+      const contents = env.irMapper.fromIr(nodes);
+      tracer.logEvent('IrProjector', 'Projected Context to LLM', {
+        projectedContext: contents,
+      });
+      return contents;
+    }
+
+    tracer.logEvent(
+      'IrProjector',
+      `View exceeds maxTokens (${currentTokens} > ${maxTokens}). Hitting Synchronous Pressure Barrier.`,
+    );
+    debugLogger.log(
+      `Context Manager Synchronous Barrier triggered: View at ${currentTokens} tokens (limit: ${maxTokens}).`,
+    );
+
+    // Calculate exactly which nodes aged out of the retainedTokens budget to form our target delta
+    const agedOutNodes = new Set<string>();
+    let rollingTokens = 0;
+    // Start from newest and count backwards
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      const node = nodes[i];
+      const nodeTokens = env.tokenCalculator.calculateConcreteListTokens([
+        node,
+      ]);
+      rollingTokens += nodeTokens;
+      if (rollingTokens > sidecar.config.budget.retainedTokens) {
+        agedOutNodes.add(node.id);
+      }
+    }
+
+    const processedNodes = await contextManager.executeTriggerSync(
+      'gc_backstop',
+      nodes,
+      agedOutNodes,
+      protectedIds,
+    );
+
+    const finalTokens =
+      env.tokenCalculator.calculateConcreteListTokens(processedNodes);
+    tracer.logEvent(
+      'IrProjector',
+      `Finished projection. Final token count: ${finalTokens}.`,
+    );
+    debugLogger.log(
+      `Context Manager finished. Final actual token count: ${finalTokens}.`,
+    );
+
+    // Apply skipList logic to abstract over summarized nodes
+    const skipList = new Set<string>();
+    for (const node of processedNodes) {
+      if (node.abstractsIds) {
+        for (const id of node.abstractsIds) skipList.add(id);
+      }
+    }
+
+    const visibleNodes = processedNodes.filter((n) => !skipList.has(n.id));
+
+    const contents = env.irMapper.fromIr(visibleNodes);
+    tracer.logEvent('IrProjector', 'Projected Sanitized Context to LLM', {
+      projectedContextSanitized: contents,
+    });
+    return contents;
+  }
+}

packages/core/src/context/ir/toIr.ts

@@ -0,0 +1,246 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content, Part } from '@google/genai';
+import type {
+  Episode,
+  SemanticPart,
+  ToolExecution,
+  AgentThought,
+  AgentYield,
+  UserPrompt,
+} from './types.js';
+import type { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import type { IIdGenerator } from '../system/IIdGenerator.js';
+
+// We remove the global nodeIdentityMap and instead rely on one passed from IrMapper
+export function getStableId(
+  obj: object,
+  nodeIdentityMap: WeakMap<object, string>,
+  idGenerator: IIdGenerator,
+): string {
+  let id = nodeIdentityMap.get(obj);
+  if (!id) {
+    id = idGenerator.generateId();
+    nodeIdentityMap.set(obj, id);
+  }
+  return id;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isCompleteEpisode(ep: Partial<Episode>): ep is Episode {
+  return (
+    typeof ep.id === 'string' &&
+    typeof ep.timestamp === 'number' &&
+    Array.isArray(ep.concreteNodes) &&
+    ep.concreteNodes.length > 0
+  );
+}
+
+export function toIr(
+  history: readonly Content[],
+  tokenCalculator: ContextTokenCalculator,
+  nodeIdentityMap: WeakMap<object, string>,
+  idGenerator: IIdGenerator,
+): Episode[] {
+  const episodes: Episode[] = [];
+  let currentEpisode: Partial<Episode> | null = null;
+  const pendingCallParts: Map<string, Part> = new Map();
+
+  const finalizeEpisode = () => {
+    if (currentEpisode && isCompleteEpisode(currentEpisode)) {
+      episodes.push(currentEpisode);
+    }
+    currentEpisode = null;
+  };
+
+  for (const msg of history) {
+    if (!msg.parts) continue;
+
+    if (msg.role === 'user') {
+      const hasToolResponses = msg.parts.some((p) => !!p.functionResponse);
+      const hasUserParts = msg.parts.some(
+        (p) => !!p.text || !!p.inlineData || !!p.fileData,
+      );
+
+      if (hasToolResponses) {
+        currentEpisode = parseToolResponses(
+          msg,
+          currentEpisode,
+          pendingCallParts,
+          tokenCalculator,
+          nodeIdentityMap,
+          idGenerator,
+        );
+      }
+
+      if (hasUserParts) {
+        finalizeEpisode();
+        currentEpisode = parseUserParts(msg, nodeIdentityMap, idGenerator);
+      }
+    } else if (msg.role === 'model') {
+      currentEpisode = parseModelParts(
+        msg,
+        currentEpisode,
+        pendingCallParts,
+        nodeIdentityMap,
+        idGenerator,
+      );
+    }
+  }
+
+  if (currentEpisode) {
+    finalizeYield(currentEpisode, idGenerator);
+    finalizeEpisode();
+  }
+
+  return episodes;
+}
+
+function parseToolResponses(
+  msg: Content,
+  currentEpisode: Partial<Episode> | null,
+  pendingCallParts: Map<string, Part>,
+  tokenCalculator: ContextTokenCalculator,
+  nodeIdentityMap: WeakMap<object, string>,
+  idGenerator: IIdGenerator,
+): Partial<Episode> {
+  if (!currentEpisode) {
+    currentEpisode = {
+      id: getStableId(msg, nodeIdentityMap, idGenerator),
+      timestamp: Date.now(),
+      concreteNodes: [],
+    };
+  }
+
+  const parts = msg.parts || [];
+  for (const part of parts) {
+    if (part.functionResponse) {
+      const callId = part.functionResponse.id || '';
+      const matchingCall = pendingCallParts.get(callId);
+
+      const intentTokens = matchingCall
+        ? tokenCalculator.estimateTokensForParts([matchingCall])
+        : 0;
+      const obsTokens = tokenCalculator.estimateTokensForParts([part]);
+
+      const step: ToolExecution = {
+        id: getStableId(part, nodeIdentityMap, idGenerator),
+        type: 'TOOL_EXECUTION',
+        toolName: part.functionResponse.name || 'unknown',
+        intent: isRecord(matchingCall?.functionCall?.args)
+          ? matchingCall.functionCall.args
+          : {},
+        observation: isRecord(part.functionResponse.response)
+          ? part.functionResponse.response
+          : {},
+        tokens: {
+          intent: intentTokens,
+          observation: obsTokens,
+        },
+      };
+      currentEpisode.concreteNodes = [
+        ...(currentEpisode.concreteNodes || []),
+        step,
+      ];
+      if (callId) pendingCallParts.delete(callId);
+    }
+  }
+  return currentEpisode;
+}
+
+function parseUserParts(
+  msg: Content,
+  nodeIdentityMap: WeakMap<object, string>,
+  idGenerator: IIdGenerator,
+): Partial<Episode> {
+  const semanticParts: SemanticPart[] = [];
+  const parts = msg.parts || [];
+  for (const p of parts) {
+    if (p.text !== undefined)
+      semanticParts.push({ type: 'text', text: p.text });
+    else if (p.inlineData)
+      semanticParts.push({
+        type: 'inline_data',
+        mimeType: p.inlineData.mimeType || '',
+        data: p.inlineData.data || '',
+      });
+    else if (p.fileData)
+      semanticParts.push({
+        type: 'file_data',
+        mimeType: p.fileData.mimeType || '',
+        fileUri: p.fileData.fileUri || '',
+      });
+    else if (!p.functionResponse)
+      semanticParts.push({ type: 'raw_part', part: p }); // Preserve unknowns
+  }
+
+  const baseObj = parts.length > 0 ? parts[0] : msg;
+  const trigger: UserPrompt = {
+    id: getStableId(baseObj, nodeIdentityMap, idGenerator),
+    type: 'USER_PROMPT',
+    semanticParts,
+  };
+  return {
+    id: getStableId(msg, nodeIdentityMap, idGenerator),
+    timestamp: Date.now(),
+    concreteNodes: [trigger],
+  };
+}
+
+function parseModelParts(
+  msg: Content,
+  currentEpisode: Partial<Episode> | null,
+  pendingCallParts: Map<string, Part>,
+  nodeIdentityMap: WeakMap<object, string>,
+  idGenerator: IIdGenerator,
+): Partial<Episode> {
+  if (!currentEpisode) {
+    currentEpisode = {
+      id: getStableId(msg, nodeIdentityMap, idGenerator),
+      timestamp: Date.now(),
+      concreteNodes: [],
+    };
+  }
+
+  const parts = msg.parts || [];
+  for (const part of parts) {
+    if (part.functionCall) {
+      const callId = part.functionCall.id || '';
+      if (callId) pendingCallParts.set(callId, part);
+    } else if (part.text) {
+      const thought: AgentThought = {
+        id: getStableId(part, nodeIdentityMap, idGenerator),
+        type: 'AGENT_THOUGHT',
+        text: part.text,
+      };
+
+      currentEpisode.concreteNodes = [
+        ...(currentEpisode.concreteNodes || []),
+        thought,
+      ];
+    }
+  }
+  return currentEpisode;
+}
+
+function finalizeYield(
+  currentEpisode: Partial<Episode>,
+  idGenerator: IIdGenerator,
+) {
+  if (currentEpisode.concreteNodes && currentEpisode.concreteNodes.length > 0) {
+    const yieldNode: AgentYield = {
+      id: idGenerator.generateId(),
+      type: 'AGENT_YIELD',
+      text: 'Yield', // Synthesized yield since we don't have the original concrete node
+    };
+    const existingNodes = currentEpisode.concreteNodes || [];
+    currentEpisode.concreteNodes = [...existingNodes, yieldNode];
+  }
+}

packages/core/src/context/ir/types.ts

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Part } from '@google/genai';
+
+export type IrNodeType =
+  // Organic Concrete Nodes
+  | 'USER_PROMPT'
+  | 'SYSTEM_EVENT'
+  | 'AGENT_THOUGHT'
+  | 'TOOL_EXECUTION'
+  | 'AGENT_YIELD'
+
+  // Synthetic Concrete Nodes
+  | 'SNAPSHOT'
+  | 'ROLLING_SUMMARY'
+  | 'MASKED_TOOL'
+
+  // Logical Nodes
+  | 'TASK'
+  | 'EPISODE';
+
+/** Base interface for all nodes in the Episodic IR */
+export interface IrNode {
+  readonly id: string;
+  readonly type: IrNodeType;
+}
+
+/**
+ * Concrete Nodes: The atomic, renderable pieces of data.
+ * These are the actual "planks" of the Nodes of Theseus.
+ */
+export interface BaseConcreteNode extends IrNode {
+  /** The ID of the Logical Node (e.g., Episode) that structurally owns this node */
+  readonly logicalParentId?: string;
+
+  /** If this node replaced a single node 1:1 (e.g., masking), this points to the original */
+  readonly replacesId?: string;
+
+  /** If this node is a synthetic summary of N nodes, this points to the original IDs */
+  readonly abstractsIds?: readonly string[];
+}
+
+/**
+ * Semantic Parts for User Prompts
+ */
+export type SemanticPart =
+  | {
+      readonly type: 'text';
+      readonly text: string;
+    }
+  | {
+      readonly type: 'inline_data';
+      readonly mimeType: string;
+      readonly data: string;
+    }
+  | {
+      readonly type: 'file_data';
+      readonly mimeType: string;
+      readonly fileUri: string;
+    }
+  | {
+      readonly type: 'raw_part';
+      readonly part: Part;
+    };
+
+/**
+ * Trigger Nodes
+ * Events that wake the agent up and initiate an Episode.
+ */
+export interface UserPrompt extends BaseConcreteNode {
+  readonly type: 'USER_PROMPT';
+  readonly semanticParts: readonly SemanticPart[];
+}
+
+export interface SystemEvent extends BaseConcreteNode {
+  readonly type: 'SYSTEM_EVENT';
+  readonly name: string;
+  readonly payload: Record<string, unknown>;
+}
+
+export type EpisodeTrigger = UserPrompt | SystemEvent;
+
+/**
+ * Step Nodes
+ * The internal autonomous actions taken by the agent during its loop.
+ */
+export interface AgentThought extends BaseConcreteNode {
+  readonly type: 'AGENT_THOUGHT';
+  readonly text: string;
+}
+
+export interface ToolExecution extends BaseConcreteNode {
+  readonly type: 'TOOL_EXECUTION';
+  readonly toolName: string;
+  readonly intent: Record<string, unknown>;
+  readonly observation: string | Record<string, unknown>;
+  readonly tokens: {
+    readonly intent: number;
+    readonly observation: number;
+  };
+}
+
+export interface MaskedTool extends BaseConcreteNode {
+  readonly type: 'MASKED_TOOL';
+  readonly toolName: string;
+  readonly intent?: Record<string, unknown>;
+  readonly observation?: string | Record<string, unknown>;
+  readonly tokens: {
+    readonly intent: number;
+    readonly observation: number;
+  };
+}
+
+export type EpisodeStep = AgentThought | ToolExecution | MaskedTool;
+
+/**
+ * Resolution Node
+ * The final message where the agent yields control back to the user.
+ */
+export interface AgentYield extends BaseConcreteNode {
+  readonly type: 'AGENT_YIELD';
+  readonly text: string;
+}
+
+/**
+ * Synthetic Leaf Interfaces
+ * Processors that generate summaries emit explicit synthetic nodes.
+ */
+export interface Snapshot extends BaseConcreteNode {
+  readonly type: 'SNAPSHOT';
+  readonly timestamp: number;
+  readonly text: string;
+}
+
+export interface RollingSummary extends BaseConcreteNode {
+  readonly type: 'ROLLING_SUMMARY';
+  readonly timestamp: number;
+  readonly text: string;
+}
+
+export type SyntheticLeaf = Snapshot | RollingSummary;
+
+export type ConcreteNode =
+  | UserPrompt
+  | SystemEvent
+  | AgentThought
+  | ToolExecution
+  | MaskedTool
+  | AgentYield
+  | Snapshot
+  | RollingSummary;
+
+/**
+ * Logical Nodes
+ * These define hierarchy and grouping. They do not directly render to Gemini.
+ */
+export interface Episode extends IrNode {
+  readonly type: 'EPISODE';
+  readonly timestamp: number;
+  /** References to the Concrete Node IDs that conceptually belong to this Episode. */
+  concreteNodes: readonly ConcreteNode[];
+}
+
+export interface Task extends IrNode {
+  readonly type: 'TASK';
+  readonly timestamp: number;
+  readonly goal: string;
+  readonly status: 'active' | 'completed' | 'failed';
+  /** References to the Episode IDs that belong to this task */
+  readonly episodeIds: readonly string[];
+}
+
+export type LogicalNode = Task | Episode;

packages/core/src/context/pipeline.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ConcreteNode } from './ir/types.js';
+
+export interface SnapshotProposal {
+  id: string;
+  newText: string;
+  consumedIds: string[];
+  type: string;
+  timestamp: number;
+}
+
+export interface SnapshotCache {
+  getProposals(): ReadonlyArray<SnapshotProposal>;
+  consume(id: string): void;
+  publish(proposal: Omit<SnapshotProposal, 'id' | 'timestamp'>, idGenerator: { generateId(): string }): void;
+}
+
+export interface GraphMutation {
+  readonly processorId: string;
+  readonly timestamp: number;
+  readonly removedIds: readonly string[];
+  readonly addedNodes: readonly ConcreteNode[];
+}
+
+export interface ContextWorkingBuffer {
+  readonly nodes: readonly ConcreteNode[];
+  getPristineNodes(id: string): readonly ConcreteNode[];
+  getLineage(id: string): readonly ConcreteNode[];
+  getAuditLog(): readonly GraphMutation[];
+}
+
+export interface ProcessArgs {
+  readonly buffer: ContextWorkingBuffer;
+  readonly targets: readonly ConcreteNode[];
+  readonly snapshotCache: SnapshotCache;
+}
+
+/**
+ * A ContextProcessor is a pure, closure-based object that returns a modified subset of nodes
+ * (or the original targets if no changes are needed).
+ * The Orchestrator will use this to generate a new graph delta.
+ */
+export interface ContextProcessor {
+  readonly id: string;
+  readonly name: string;
+  process(args: ProcessArgs): Promise<readonly ConcreteNode[]>;
+}
+
+export interface AsyncContextProcessor {
+  readonly id: string;
+  readonly name: string;
+  process(args: ProcessArgs): Promise<void>;
+}
+
+export interface BackstopTargetOptions {
+  target?: 'incremental' | 'freeNTokens' | 'max';
+  freeTokensTarget?: number;
+}

packages/core/src/context/pipeline/contextWorkingBuffer.test.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ContextWorkingBufferImpl } from './contextWorkingBuffer.js';
+import { createDummyNode } from '../testing/contextTestUtils.js';
+
+describe('ContextWorkingBufferImpl', () => {
+  it('should initialize with a pristine graph correctly', () => {
+    const pristine1 = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      undefined,
+      'p1',
+    );
+    const pristine2 = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      10,
+      undefined,
+      'p2',
+    );
+
+    const buffer = ContextWorkingBufferImpl.initialize([pristine1, pristine2]);
+
+    expect(buffer.nodes).toHaveLength(2);
+    expect(buffer.getAuditLog()).toHaveLength(0);
+
+    // Pristine nodes should point to themselves
+    expect(buffer.getPristineNodes('p1')).toEqual([pristine1]);
+    expect(buffer.getPristineNodes('p2')).toEqual([pristine2]);
+  });
+
+  it('should track 1:1 replacements (e.g., masking) and append to audit log', () => {
+    const pristine1 = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      undefined,
+      'p1',
+    );
+    let buffer = ContextWorkingBufferImpl.initialize([pristine1]);
+
+    const maskedNode = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      5,
+      undefined,
+      'm1',
+    );
+    // Simulate what a processor does
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (maskedNode as any).replacesId = 'p1';
+
+    buffer = buffer.applyProcessorResult(
+      'ToolMasking',
+      [pristine1],
+      [maskedNode],
+    );
+
+    expect(buffer.nodes).toHaveLength(1);
+    expect(buffer.nodes[0].id).toBe('m1');
+
+    const log = buffer.getAuditLog();
+    expect(log).toHaveLength(1);
+    expect(log[0].processorId).toBe('ToolMasking');
+    expect(log[0].removedIds).toEqual(['p1']);
+    expect(log[0].addedNodes[0].id).toBe('m1');
+
+    // Provenance lookup: the masked node should resolve back to the pristine root
+    expect(buffer.getPristineNodes('m1')).toEqual([pristine1]);
+  });
+
+  it('should track N:1 abstractions (e.g., rolling summaries)', () => {
+    const p1 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p1');
+    const p2 = createDummyNode('ep1', 'AGENT_THOUGHT', 10, undefined, 'p2');
+    const p3 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p3');
+
+    let buffer = ContextWorkingBufferImpl.initialize([p1, p2, p3]);
+
+    const summaryNode = createDummyNode(
+      'ep1',
+      'ROLLING_SUMMARY',
+      15,
+      undefined,
+      's1',
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (summaryNode as any).abstractsIds = ['p1', 'p2'];
+
+    buffer = buffer.applyProcessorResult('Summarizer', [p1, p2], [summaryNode]);
+
+    // p1 and p2 are removed, p3 remains, s1 is added
+    expect(buffer.nodes.map((n) => n.id)).toEqual(['p3', 's1']);
+
+    // Provenance lookup: The summary node should resolve to both p1 and p2!
+    const roots = buffer.getPristineNodes('s1');
+    expect(roots).toHaveLength(2);
+    expect(roots).toContain(p1);
+    expect(roots).toContain(p2);
+  });
+
+  it('should track multi-generation provenance correctly', () => {
+    const p1 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p1');
+    let buffer = ContextWorkingBufferImpl.initialize([p1]);
+
+    // Gen 1: Masked
+    const gen1 = createDummyNode('ep1', 'USER_PROMPT', 8, undefined, 'gen1');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (gen1 as any).replacesId = 'p1';
+    buffer = buffer.applyProcessorResult('Masking', [p1], [gen1]);
+
+    // Gen 2: Summarized
+    const gen2 = createDummyNode(
+      'ep1',
+      'ROLLING_SUMMARY',
+      5,
+      undefined,
+      'gen2',
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (gen2 as any).abstractsIds = ['gen1'];
+    buffer = buffer.applyProcessorResult('Summarizer', [gen1], [gen2]);
+
+    expect(buffer.nodes).toHaveLength(1);
+    expect(buffer.nodes[0].id).toBe('gen2');
+
+    // Audit log should show sequence
+    const log = buffer.getAuditLog();
+    expect(log).toHaveLength(2);
+    expect(log[0].processorId).toBe('Masking');
+    expect(log[1].processorId).toBe('Summarizer');
+
+    // Multi-gen Provenance lookup: gen2 -> gen1 -> p1
+    expect(buffer.getPristineNodes('gen2')).toEqual([p1]);
+  });
+
+  it('should handle net-new injected nodes without throwing', () => {
+    const p1 = createDummyNode('ep1', 'USER_PROMPT', 10, undefined, 'p1');
+    let buffer = ContextWorkingBufferImpl.initialize([p1]);
+
+    const injected = createDummyNode(
+      'ep1',
+      'SYSTEM_EVENT',
+      5,
+      undefined,
+      'injected1',
+    );
+    // No replacesId or abstractsIds
+
+    buffer = buffer.applyProcessorResult('Injector', [], [injected]);
+
+    expect(buffer.nodes.map((n) => n.id)).toEqual(['p1', 'injected1']);
+
+    // It should root to itself
+    expect(buffer.getPristineNodes('injected1')).toEqual([injected]);
+  });
+});

packages/core/src/context/pipeline/contextWorkingBuffer.ts

@@ -0,0 +1,195 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { ContextWorkingBuffer, GraphMutation } from '../pipeline.js';
+import type { ConcreteNode } from '../ir/types.js';
+
+export class ContextWorkingBufferImpl implements ContextWorkingBuffer {
+  // The current active graph
+  readonly nodes: readonly ConcreteNode[];
+
+  // The AOT pre-calculated provenance index (Current ID -> Pristine IDs)
+  private readonly provenanceMap: ReadonlyMap<string, ReadonlySet<string>>;
+
+  // The original immutable pristine nodes mapping
+  private readonly pristineNodesMap: ReadonlyMap<string, ConcreteNode>;
+
+  // The historical linked list of changes
+  private readonly history: readonly GraphMutation[];
+
+  private constructor(
+    nodes: readonly ConcreteNode[],
+    pristineNodesMap: ReadonlyMap<string, ConcreteNode>,
+    provenanceMap: ReadonlyMap<string, ReadonlySet<string>>,
+    history: readonly GraphMutation[],
+  ) {
+    this.nodes = nodes;
+    this.pristineNodesMap = pristineNodesMap;
+    this.provenanceMap = provenanceMap;
+    this.history = history;
+  }
+
+  /**
+   * Initializes a brand new ContextWorkingBuffer from a pristine graph.
+   * Every node's provenance points to itself.
+   */
+  static initialize(
+    pristineNodes: readonly ConcreteNode[],
+  ): ContextWorkingBufferImpl {
+    const pristineMap = new Map<string, ConcreteNode>();
+    const initialProvenance = new Map<string, ReadonlySet<string>>();
+
+    for (const node of pristineNodes) {
+      pristineMap.set(node.id, node);
+      initialProvenance.set(node.id, new Set([node.id]));
+    }
+
+    return new ContextWorkingBufferImpl(
+      pristineNodes,
+      pristineMap,
+      initialProvenance,
+      [], // Empty history
+    );
+  }
+
+  /**
+   * Appends newly observed pristine nodes (e.g. from a user message) to the working buffer.
+   * Ensures they are tracked in the pristine map and point to themselves in provenance.
+   */
+  appendPristineNodes(
+    newNodes: readonly ConcreteNode[],
+  ): ContextWorkingBufferImpl {
+    if (newNodes.length === 0) return this;
+
+    const newPristineMap = new Map<string, ConcreteNode>(this.pristineNodesMap);
+    const newProvenanceMap = new Map(this.provenanceMap);
+
+    for (const node of newNodes) {
+      newPristineMap.set(node.id, node);
+      newProvenanceMap.set(node.id, new Set([node.id]));
+    }
+
+    return new ContextWorkingBufferImpl(
+      [...this.nodes, ...newNodes],
+      newPristineMap,
+      newProvenanceMap,
+      [...this.history],
+    );
+  }
+
+  /**
+   * Generates an entirely new buffer instance by calculating the delta between the processor's input and output.
+   */
+  applyProcessorResult(
+    processorId: string,
+    inputTargets: readonly ConcreteNode[],
+    outputNodes: readonly ConcreteNode[],
+  ): ContextWorkingBufferImpl {
+    const outputIds = new Set(outputNodes.map((n) => n.id));
+    const inputIds = new Set(inputTargets.map((n) => n.id));
+
+    // Calculate diffs
+    const removedIds = inputTargets
+      .filter((n) => !outputIds.has(n.id))
+      .map((n) => n.id);
+    const addedNodes = outputNodes.filter((n) => !inputIds.has(n.id));
+
+    // Create mutation record
+    const mutation: GraphMutation = {
+      processorId,
+      timestamp: Date.now(),
+      removedIds,
+      addedNodes,
+    };
+
+    // Calculate new node array
+    const removedSet = new Set(removedIds);
+    const retainedNodes = this.nodes.filter((n) => !removedSet.has(n.id));
+    const newGraph = [...retainedNodes];
+
+    // We append the output nodes in the same general position if possible,
+    // but in a complex graph we just ensure they exist. V2 graph uses timestamps for order.
+    // For simplicity, we just push added nodes to the end of the retained array
+    newGraph.push(...addedNodes);
+
+    // Calculate new provenance map
+    const newProvenanceMap = new Map(this.provenanceMap);
+
+    let finalPristineMap = this.pristineNodesMap;
+
+    // Map the new synthetic nodes back to their pristine roots
+    for (const added of addedNodes) {
+      const roots = new Set<string>();
+
+      // 1:1 Replacement (e.g. Masked Node)
+      if (added.replacesId) {
+        const inheritedRoots = this.provenanceMap.get(added.replacesId);
+        if (inheritedRoots) {
+          for (const rootId of inheritedRoots) roots.add(rootId);
+        }
+      }
+
+      // N:1 Abstraction (e.g. Rolling Summary)
+      if (added.abstractsIds) {
+        for (const abstractId of added.abstractsIds) {
+          const inheritedRoots = this.provenanceMap.get(abstractId);
+          if (inheritedRoots) {
+            for (const rootId of inheritedRoots) roots.add(rootId);
+          }
+        }
+      }
+
+      // If it has no links back to the original graph, it is its own root
+      // (e.g., a system-injected instruction)
+      if (roots.size === 0) {
+        roots.add(added.id);
+        // It acts as a net-new pristine root.
+        if (!finalPristineMap.has(added.id)) {
+          const mutableMap = new Map<string, ConcreteNode>(finalPristineMap);
+          mutableMap.set(added.id, added);
+          finalPristineMap = mutableMap;
+        }
+      }
+
+      newProvenanceMap.set(added.id, roots);
+    }
+
+    return new ContextWorkingBufferImpl(
+      newGraph,
+      finalPristineMap,
+      newProvenanceMap,
+      [...this.history, mutation],
+    );
+  }
+
+  getPristineNodes(id: string): readonly ConcreteNode[] {
+    const pristineIds = this.provenanceMap.get(id);
+    if (!pristineIds) return [];
+    return Array.from(pristineIds).map(
+      (pid) => this.pristineNodesMap.get(pid)!,
+    );
+  }
+
+  getAuditLog(): readonly GraphMutation[] {
+    return this.history;
+  }
+
+  getLineage(id: string): readonly ConcreteNode[] {
+    const lineage: ConcreteNode[] = [];
+    const currentNodesMap = new Map(this.nodes.map((n) => [n.id, n]));
+
+    let current = currentNodesMap.get(id);
+    while (current) {
+      lineage.push(current);
+      if (current.logicalParentId && current.logicalParentId !== current.id) {
+        current = currentNodesMap.get(current.logicalParentId);
+      } else {
+        break;
+      }
+    }
+    return lineage;
+  }
+}

packages/core/src/context/pipeline/environment.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import type { ContextTracer } from '../tracer.js';
+import type { IFileSystem } from '../system/IFileSystem.js';
+import type { IIdGenerator } from '../system/IIdGenerator.js';
+import type { SnapshotCache } from '../pipeline.js';
+import type { IrNodeBehaviorRegistry } from '../ir/behaviorRegistry.js';
+import type { IrMapper } from '../ir/mapper.js';
+
+export type { ContextTracer };
+
+export interface ContextEnvironment {
+  readonly llmClient: BaseLlmClient;
+  readonly promptId: string;
+  readonly sessionId: string;
+  readonly traceDir: string;
+  readonly projectTempDir: string;
+  readonly tracer: ContextTracer;
+  readonly charsPerToken: number;
+  readonly tokenCalculator: ContextTokenCalculator;
+  readonly fileSystem: IFileSystem;
+  readonly idGenerator: IIdGenerator;
+  readonly snapshotCache: SnapshotCache;
+  readonly behaviorRegistry: IrNodeBehaviorRegistry;
+  readonly irMapper: IrMapper;
+}

packages/core/src/context/pipeline/environmentImpl.test.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { ContextEnvironmentImpl } from './environmentImpl.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import { ContextTracer } from '../tracer.js';
+
+describe('ContextEnvironmentImpl', () => {
+  it('should initialize with provided dependencies and default optional ones', () => {
+    // Mock required dependencies
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const llmClient = {} as BaseLlmClient;
+    const tracer = new ContextTracer({
+      targetDir: '/tmp',
+      sessionId: 'test-session',
+    });
+
+    const env = new ContextEnvironmentImpl(
+      llmClient,
+      'test-session',
+      'test-prompt-id',
+      '/tmp/trace',
+      '/tmp/temp',
+      tracer,
+      4,
+    );
+
+    // Verify injected properties
+    expect(env.llmClient).toBe(llmClient);
+    expect(env.sessionId).toBe('test-session');
+    expect(env.promptId).toBe('test-prompt-id');
+    expect(env.traceDir).toBe('/tmp/trace');
+    expect(env.projectTempDir).toBe('/tmp/temp');
+    expect(env.tracer).toBe(tracer);
+    expect(env.charsPerToken).toBe(4);
+
+    // Verify default initialized properties
+    expect(env.tokenCalculator).toBeDefined();
+    expect(env.fileSystem).toBeDefined();
+    expect(env.idGenerator).toBeDefined();
+    expect(env.snapshotCache).toBeDefined();
+    expect(env.behaviorRegistry).toBeDefined();
+    expect(env.irMapper).toBeDefined();
+  });
+});

packages/core/src/context/pipeline/environmentImpl.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { ContextTracer } from '../tracer.js';
+import type { ContextEnvironment } from './environment.js';
+import { ContextTokenCalculator } from '../utils/contextTokenCalculator.js';
+import type { IFileSystem } from '../system/IFileSystem.js';
+import { NodeFileSystem } from '../system/NodeFileSystem.js';
+import type { IIdGenerator } from '../system/IIdGenerator.js';
+import { NodeIdGenerator } from '../system/NodeIdGenerator.js';
+import { LiveSnapshotCache } from './snapshotCache.js';
+import { IrNodeBehaviorRegistry } from '../ir/behaviorRegistry.js';
+import { registerBuiltInBehaviors } from '../ir/builtinBehaviors.js';
+import { IrMapper } from '../ir/mapper.js';
+import type { SnapshotCache } from '../pipeline.js';
+
+export class ContextEnvironmentImpl implements ContextEnvironment {
+  readonly tokenCalculator: ContextTokenCalculator;
+  readonly fileSystem: IFileSystem;
+  readonly idGenerator: IIdGenerator;
+  readonly snapshotCache: SnapshotCache;
+  readonly behaviorRegistry: IrNodeBehaviorRegistry;
+  readonly irMapper: IrMapper;
+
+  constructor(
+    readonly llmClient: BaseLlmClient,
+    readonly sessionId: string,
+    readonly promptId: string,
+    readonly traceDir: string,
+    readonly projectTempDir: string,
+    readonly tracer: ContextTracer,
+    readonly charsPerToken: number,
+    fileSystem?: IFileSystem,
+    idGenerator?: IIdGenerator,
+  ) {
+    this.behaviorRegistry = new IrNodeBehaviorRegistry();
+    registerBuiltInBehaviors(this.behaviorRegistry);
+    this.tokenCalculator = new ContextTokenCalculator(
+      this.charsPerToken,
+      this.behaviorRegistry,
+    );
+    this.fileSystem = fileSystem || new NodeFileSystem();
+    this.idGenerator = idGenerator || new NodeIdGenerator();
+    this.snapshotCache = new LiveSnapshotCache();
+    this.irMapper = new IrMapper(this.behaviorRegistry, this.idGenerator);
+  }
+}

packages/core/src/context/pipeline/snapshotCache.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SnapshotProposal, SnapshotCache } from '../pipeline.js';
+
+export class LiveSnapshotCache implements SnapshotCache {
+  private proposals: SnapshotProposal[] = [];
+  private consumedIds = new Set<string>();
+
+  publish(
+    proposal: Omit<SnapshotProposal, 'id' | 'timestamp'>,
+    idGenerator: { generateId(): string },
+  ): void {
+    this.proposals.push({
+      ...proposal,
+      id: idGenerator.generateId(),
+      timestamp: Date.now(),
+    });
+  }
+
+  getProposals(): readonly SnapshotProposal[] {
+    return this.proposals.filter((p) => !this.consumedIds.has(p.id));
+  }
+
+  consume(proposalId: string): void {
+    this.consumedIds.add(proposalId);
+  }
+}

packages/core/src/context/processors/blobDegradationProcessor.test.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createBlobDegradationProcessor } from './blobDegradationProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+import type { UserPrompt, SemanticPart, ConcreteNode } from '../ir/types.js';
+
+describe('BlobDegradationProcessor', () => {
+  it('should ignore text parts and only target inline_data and file_data', async () => {
+    const env = createMockEnvironment();
+    // charsPerToken = 1
+    // We want the degraded text to be cheaper than the original blob.
+    // Degraded text is ~100 chars ("...degraded to text...").
+    // So we make the blob data 200 chars.
+    const fakeData = 'A'.repeat(200);
+
+    const processor = createBlobDegradationProcessor(
+      'BlobDegradationProcessor',
+      env,
+    );
+
+    const parts: SemanticPart[] = [
+      { type: 'text', text: 'Hello' },
+      { type: 'inline_data', mimeType: 'image/png', data: fakeData },
+      { type: 'text', text: 'World' },
+    ];
+
+    const prompt = createDummyNode('ep1', 'USER_PROMPT', 100, {
+      semanticParts: parts,
+    }) as UserPrompt;
+
+    const targets = [prompt];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(1);
+    const modifiedPrompt = result[0] as UserPrompt;
+
+    expect(modifiedPrompt.id).not.toBe(prompt.id);
+    expect(modifiedPrompt.semanticParts.length).toBe(3);
+
+    // Text parts should be untouched
+    expect(modifiedPrompt.semanticParts[0]).toEqual(parts[0]);
+    expect(modifiedPrompt.semanticParts[2]).toEqual(parts[2]);
+
+    // The inline_data part should be replaced with text
+    const degradedPart = modifiedPrompt.semanticParts[1];
+    expect(degradedPart.type).toBe('text');
+    assert(degradedPart.type === 'text');
+    expect(degradedPart.text).toContain(
+      '[Multi-Modal Blob (image/png, 0.00MB) degraded to text',
+    );
+  });
+
+  it('should degrade all blobs unconditionally', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createBlobDegradationProcessor(
+      'BlobDegradationProcessor',
+      env,
+    );
+
+    // Tokens for fileData = 258.
+    // Degraded text = "[File Reference (video/mp4) degraded to text to preserve context window. Original URI: gs://test1]"
+    // Degraded text length ~100 characters.
+    // Since charsPerToken=1, degraded text = 100 tokens.
+    // Tokens saved = 258 - 100 = 158. This is > 0, so it WILL degrade it!
+
+    const prompt = createDummyNode('ep1', 'USER_PROMPT', 100, {
+      semanticParts: [
+        { type: 'file_data', mimeType: 'video/mp4', fileUri: 'gs://test1' },
+        { type: 'file_data', mimeType: 'video/mp4', fileUri: 'gs://test2' },
+      ],
+    }) as UserPrompt;
+
+    const targets = [prompt];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    const modifiedPrompt = result[0] as UserPrompt;
+    expect(modifiedPrompt.semanticParts.length).toBe(2);
+
+    // Both parts should be degraded
+    expect(modifiedPrompt.semanticParts[0].type).toBe('text');
+    expect(modifiedPrompt.semanticParts[1].type).toBe('text');
+  });
+
+  it('should return exactly the targets array if targets are empty', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createBlobDegradationProcessor(
+      'BlobDegradationProcessor',
+      env,
+    );
+    const targets: ConcreteNode[] = [];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result).toBe(targets);
+  });
+});

packages/core/src/context/processors/blobDegradationProcessor.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ProcessArgs, ContextProcessor } from '../pipeline.js';
+import type { ConcreteNode, UserPrompt } from '../ir/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { sanitizeFilenamePart } from '../../utils/fileUtils.js';
+
+export function createBlobDegradationProcessor(
+  id: string,
+  env: ContextEnvironment,
+): ContextProcessor {
+  return {
+    id,
+    name: 'BlobDegradationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      if (targets.length === 0) {
+        return targets;
+      }
+
+      let directoryCreated = false;
+
+      let blobOutputsDir = env.fileSystem.join(
+        env.projectTempDir,
+        'degraded-blobs',
+      );
+      const sessionId = env.sessionId;
+      if (sessionId) {
+        blobOutputsDir = env.fileSystem.join(
+          blobOutputsDir,
+          `session-${sanitizeFilenamePart(sessionId)}`,
+        );
+      }
+
+      const ensureDir = async () => {
+        if (!directoryCreated) {
+          await env.fileSystem.mkdir(blobOutputsDir, { recursive: true });
+          directoryCreated = true;
+        }
+      };
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      // Forward scan, looking for bloated non-text parts to degrade
+      for (const node of targets) {
+        switch (node.type) {
+          case 'USER_PROMPT': {
+            let modified = false;
+            const newParts = [...node.semanticParts];
+
+            for (let j = 0; j < node.semanticParts.length; j++) {
+              const part = node.semanticParts[j];
+              if (part.type === 'text') continue;
+
+              let newText = '';
+              let tokensSaved = 0;
+
+              switch (part.type) {
+                case 'inline_data': {
+                  await ensureDir();
+                  const ext = part.mimeType.split('/')[1] || 'bin';
+                  const fileName = `blob_${Date.now()}_${env.idGenerator.generateId()}.${ext}`;
+                  const filePath = env.fileSystem.join(
+                    blobOutputsDir,
+                    fileName,
+                  );
+
+                  const buffer = Buffer.from(part.data, 'base64');
+                  await env.fileSystem.writeFile(filePath, buffer);
+
+                  const mb = (buffer.byteLength / 1024 / 1024).toFixed(2);
+                  newText = `[Multi-Modal Blob (${part.mimeType}, ${mb}MB) degraded to text to preserve context window. Saved to: ${filePath}]`;
+
+                  const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                    {
+                      inlineData: { mimeType: part.mimeType, data: part.data },
+                    },
+                  ]);
+                  const newTokens = env.tokenCalculator.estimateTokensForParts([
+                    { text: newText },
+                  ]);
+                  tokensSaved = oldTokens - newTokens;
+                  break;
+                }
+                case 'file_data': {
+                  newText = `[File Reference (${part.mimeType}) degraded to text to preserve context window. Original URI: ${part.fileUri}]`;
+                  const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                    {
+                      fileData: {
+                        mimeType: part.mimeType,
+                        fileUri: part.fileUri,
+                      },
+                    },
+                  ]);
+                  const newTokens = env.tokenCalculator.estimateTokensForParts([
+                    { text: newText },
+                  ]);
+                  tokensSaved = oldTokens - newTokens;
+                  break;
+                }
+                case 'raw_part': {
+                  newText = `[Unknown Part degraded to text to preserve context window.]`;
+                  const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                    part.part,
+                  ]);
+                  const newTokens = env.tokenCalculator.estimateTokensForParts([
+                    { text: newText },
+                  ]);
+                  tokensSaved = oldTokens - newTokens;
+                  break;
+                }
+                default:
+                  break;
+              }
+
+              if (newText && tokensSaved > 0) {
+                newParts[j] = { type: 'text', text: newText };
+                modified = true;
+              }
+            }
+
+            if (modified) {
+              const degradedNode: UserPrompt = {
+                ...node,
+                id: env.idGenerator.generateId(),
+                semanticParts: newParts,
+                replacesId: node.id,
+              };
+              returnedNodes.push(degradedNode);
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/processors/historyTruncationProcessor.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  ContextProcessor,
+  BackstopTargetOptions,
+  ProcessArgs,
+} from '../pipeline.js';
+import type { ConcreteNode } from '../ir/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+
+export type HistoryTruncationProcessorOptions = BackstopTargetOptions;
+
+export function createHistoryTruncationProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: HistoryTruncationProcessorOptions,
+): ContextProcessor {
+  return {
+    id,
+    name: 'HistoryTruncationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      const strategy = options.target ?? 'max';
+      const keptNodes: ConcreteNode[] = [];
+
+      if (strategy === 'incremental') {
+        // 'incremental' simply drops the single oldest node in the targets, ignoring tokens.
+        let removedNodes = 0;
+        for (const node of targets) {
+          if (removedNodes < 1) {
+            removedNodes++;
+            continue;
+          }
+          keptNodes.push(node);
+        }
+        return keptNodes;
+      }
+
+      let targetTokensToRemove = 0;
+      if (strategy === 'freeNTokens') {
+        targetTokensToRemove = options.freeTokensTarget ?? 0;
+        if (targetTokensToRemove <= 0) return targets;
+      } else if (strategy === 'max') {
+        // 'max' means we remove all targets without stopping early
+        targetTokensToRemove = Infinity;
+      }
+
+      let removedTokens = 0;
+
+      // The targets are sequentially ordered from oldest to newest.
+      // We want to delete the oldest targets first.
+      for (const node of targets) {
+        if (removedTokens >= targetTokensToRemove) {
+          keptNodes.push(node);
+          continue;
+        }
+
+        removedTokens += env.tokenCalculator.getTokenCost(node);
+      }
+
+      return keptNodes;
+    },
+  };
+}

packages/core/src/context/processors/nodeDistillationProcessor.test.ts

@@ -0,0 +1,148 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createNodeDistillationProcessor } from './nodeDistillationProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+  createDummyToolNode,
+  createMockLlmClient,
+} from '../testing/contextTestUtils.js';
+import type { UserPrompt, AgentThought, ToolExecution } from '../ir/types.js';
+
+describe('NodeDistillationProcessor', () => {
+  it('should trigger summarization via LLM for long text parts', async () => {
+    const mockLlmClient = createMockLlmClient(['Mocked Summary!']);
+
+    // Use charsPerToken=1 naturally.
+    const env = createMockEnvironment({
+      llmClient: mockLlmClient,
+    });
+
+    const processor = createNodeDistillationProcessor(
+      'NodeDistillationProcessor',
+      env,
+      {
+        nodeThresholdTokens: 10,
+      },
+    );
+
+    const longText = 'A'.repeat(50); // 50 chars
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      50,
+      {
+        semanticParts: [{ type: 'text', text: longText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      50,
+      {
+        text: longText,
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const tool = createDummyToolNode(
+      'ep1',
+      5,
+      500,
+      {
+        observation: { result: 'A'.repeat(500) },
+      },
+      'tool-id',
+    );
+
+    const targets = [prompt, thought, tool];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(3);
+
+    // 1. User Prompt
+    const compressedPrompt = result[0] as UserPrompt;
+    expect(compressedPrompt.id).not.toBe(prompt.id);
+    expect(compressedPrompt.semanticParts[0].type).toBe('text');
+    assert(compressedPrompt.semanticParts[0].type === 'text');
+    expect(compressedPrompt.semanticParts[0].text).toBe('Mocked Summary!');
+
+    // 2. Agent Thought
+    const compressedThought = result[1] as AgentThought;
+    expect(compressedThought.id).not.toBe(thought.id);
+    expect(compressedThought.text).toBe('Mocked Summary!');
+
+    // 3. Tool Execution
+    const compressedTool = result[2] as ToolExecution;
+    expect(compressedTool.id).not.toBe(tool.id);
+    expect(compressedTool.observation).toEqual({ summary: 'Mocked Summary!' });
+
+    expect(mockLlmClient.generateContent).toHaveBeenCalledTimes(3);
+  });
+
+  it('should ignore nodes that are below the threshold', async () => {
+    const mockLlmClient = createMockLlmClient(['S']); // length = 1
+
+    const env = createMockEnvironment({
+      llmClient: mockLlmClient,
+    });
+
+    const processor = createNodeDistillationProcessor(
+      'NodeDistillationProcessor',
+      env,
+      {
+        nodeThresholdTokens: 100, // Very high threshold
+      },
+    );
+
+    const shortText = 'Short text'; // 10 chars
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      {
+        semanticParts: [{ type: 'text', text: shortText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      13,
+      {
+        text: 'Short thought',
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const targets = [prompt, thought];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(2);
+
+    // 1. User Prompt (NOT compressed)
+    const untouchedPrompt = result[0] as UserPrompt;
+    expect(untouchedPrompt.id).toBe(prompt.id);
+
+    // 2. Agent Thought (NOT compressed)
+    const untouchedThought = result[1] as AgentThought;
+    expect(untouchedThought.id).toBe(thought.id);
+
+    // LLM should not have been called
+    expect(mockLlmClient.generateContent).toHaveBeenCalledTimes(0);
+  });
+});

packages/core/src/context/processors/nodeDistillationProcessor.ts

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ConcreteNode } from '../ir/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { getResponseText } from '../../utils/partUtils.js';
+
+import { LlmRole } from '../../telemetry/llmRole.js';
+
+export interface NodeDistillationProcessorOptions {
+  nodeThresholdTokens: number;
+}
+
+export function createNodeDistillationProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: NodeDistillationProcessorOptions,
+): ContextProcessor {
+  const generateSummary = async (
+    text: string,
+    contextInfo: string,
+  ): Promise<string> => {
+    try {
+      const response = await env.llmClient.generateContent({
+        role: LlmRole.UTILITY_COMPRESSOR,
+        modelConfigKey: { model: 'gemini-3-flash-base' },
+        promptId: env.promptId,
+        abortSignal: new AbortController().signal,
+        contents: [
+          {
+            role: 'user',
+            parts: [{ text }],
+          },
+        ],
+        systemInstruction: {
+          role: 'system',
+          parts: [
+            {
+              text: `You are an expert context compressor. Your job is to drastically shorten the following ${contextInfo} while preserving the absolute core semantic meaning, facts, and intent. Omit all conversational filler, pleasantries, or redundant information. Return ONLY the compressed summary.`,
+            },
+          ],
+        },
+      });
+      return getResponseText(response) || text;
+    } catch (e) {
+      debugLogger.warn(
+        `NodeDistillationProcessor failed to summarize ${contextInfo}`,
+        e,
+      );
+      return text; // Fallback to original text on API failure
+    }
+  };
+
+  return {
+    id,
+    name: 'NodeDistillationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      const semanticConfig = options;
+      const limitTokens = semanticConfig.nodeThresholdTokens;
+      const thresholdChars = env.tokenCalculator.tokensToChars(limitTokens);
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      // Scan the target working buffer and unconditionally apply the configured hyperparameter threshold
+      for (const node of targets) {
+        switch (node.type) {
+          case 'USER_PROMPT': {
+            let modified = false;
+            const newParts = [...node.semanticParts];
+
+            for (let j = 0; j < node.semanticParts.length; j++) {
+              const part = node.semanticParts[j];
+              if (part.type !== 'text') continue;
+
+              if (part.text.length > thresholdChars) {
+                const summary = await generateSummary(part.text, 'User Prompt');
+                const newTokens = env.tokenCalculator.estimateTokensForParts([
+                  { text: summary },
+                ]);
+                const oldTokens = env.tokenCalculator.estimateTokensForParts([
+                  { text: part.text },
+                ]);
+
+                if (newTokens < oldTokens) {
+                  newParts[j] = { type: 'text', text: summary };
+                  modified = true;
+                }
+              }
+            }
+
+            if (modified) {
+              returnedNodes.push({
+                ...node,
+                id: env.idGenerator.generateId(),
+                semanticParts: newParts,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          case 'AGENT_THOUGHT': {
+            if (node.text.length > thresholdChars) {
+              const summary = await generateSummary(node.text, 'Agent Thought');
+              const newTokens = env.tokenCalculator.estimateTokensForParts([
+                { text: summary },
+              ]);
+              const oldTokens = env.tokenCalculator.getTokenCost(node);
+
+              if (newTokens < oldTokens) {
+                returnedNodes.push({
+                  ...node,
+                  id: env.idGenerator.generateId(),
+                  text: summary,
+                  replacesId: node.id,
+                });
+                break;
+              }
+            }
+            returnedNodes.push(node);
+            break;
+          }
+
+          case 'TOOL_EXECUTION': {
+            const rawObs = node.observation;
+
+            let stringifiedObs = '';
+            if (typeof rawObs === 'string') {
+              stringifiedObs = rawObs;
+            } else {
+              try {
+                stringifiedObs = JSON.stringify(rawObs);
+              } catch {
+                stringifiedObs = String(rawObs);
+              }
+            }
+
+            if (stringifiedObs.length > thresholdChars) {
+              const summary = await generateSummary(
+                stringifiedObs,
+                node.toolName || 'unknown',
+              );
+              const newObsObject = { summary };
+
+              const newObsTokens = env.tokenCalculator.estimateTokensForParts([
+                {
+                  functionResponse: {
+                    name: node.toolName || 'unknown',
+                    response: newObsObject,
+                    id: node.id,
+                  },
+                },
+              ]);
+
+              const oldObsTokens =
+                node.tokens?.observation ??
+                env.tokenCalculator.getTokenCost(node);
+              const intentTokens = node.tokens?.intent ?? 0;
+
+              if (newObsTokens < oldObsTokens) {
+                returnedNodes.push({
+                  ...node,
+                  id: env.idGenerator.generateId(),
+                  observation: newObsObject as Record<string, unknown>,
+                  tokens: {
+                    intent: intentTokens,
+                    observation: newObsTokens,
+                  },
+                  replacesId: node.id,
+                });
+                break;
+              }
+            }
+            returnedNodes.push(node);
+            break;
+          }
+
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/processors/nodeTruncationProcessor.test.ts

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import { describe, it, expect } from 'vitest';
+import { createNodeTruncationProcessor } from './nodeTruncationProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+import type { UserPrompt, AgentThought, AgentYield } from '../ir/types.js';
+
+describe('NodeTruncationProcessor', () => {
+  it('should truncate nodes that exceed maxTokensPerNode', async () => {
+    // env.tokenCalculator uses charsPerToken=1 natively.
+    const env = createMockEnvironment();
+
+    const processor = createNodeTruncationProcessor(
+      'NodeTruncationProcessor',
+      env,
+      {
+        maxTokensPerNode: 10, // 10 chars limit
+      },
+    );
+
+    const longText = 'A'.repeat(50); // 50 tokens
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      50,
+      {
+        semanticParts: [{ type: 'text', text: longText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      50,
+      {
+        text: longText,
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const yieldNode = createDummyNode(
+      'ep1',
+      'AGENT_YIELD',
+      50,
+      {
+        text: longText,
+      },
+      'yield-id',
+    ) as AgentYield;
+
+    const targets = [prompt, thought, yieldNode];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(3);
+
+    // 1. User Prompt
+    const squashedPrompt = result[0] as UserPrompt;
+    expect(squashedPrompt.id).not.toBe(prompt.id);
+    expect(squashedPrompt.semanticParts[0].type).toBe('text');
+    assert(squashedPrompt.semanticParts[0].type === 'text');
+    expect(squashedPrompt.semanticParts[0].text).toContain('[... OMITTED');
+
+    // 2. Agent Thought
+    const squashedThought = result[1] as AgentThought;
+    expect(squashedThought.id).not.toBe(thought.id);
+    expect(squashedThought.text).toContain('[... OMITTED');
+
+    // 3. Agent Yield
+    const squashedYield = result[2] as AgentYield;
+    expect(squashedYield.id).not.toBe(yieldNode.id);
+    expect(squashedYield.text).toContain('[... OMITTED');
+  });
+
+  it('should ignore nodes that are below maxTokensPerNode', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createNodeTruncationProcessor(
+      'NodeTruncationProcessor',
+      env,
+      {
+        maxTokensPerNode: 100, // 100 chars limit
+      },
+    );
+
+    const shortText = 'Short text'; // 10 chars
+
+    const prompt = createDummyNode(
+      'ep1',
+      'USER_PROMPT',
+      10,
+      {
+        semanticParts: [{ type: 'text', text: shortText }],
+      },
+      'prompt-id',
+    ) as UserPrompt;
+
+    const thought = createDummyNode(
+      'ep1',
+      'AGENT_THOUGHT',
+      13,
+      {
+        text: 'Short thought', // 13 chars
+      },
+      'thought-id',
+    ) as AgentThought;
+
+    const targets = [prompt, thought];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    expect(result.length).toBe(2);
+
+    // 1. User Prompt (untouched)
+    const squashedPrompt = result[0] as UserPrompt;
+    expect(squashedPrompt.id).toBe(prompt.id);
+    assert(squashedPrompt.semanticParts[0].type === 'text');
+    expect(squashedPrompt.semanticParts[0].text).not.toContain('[... OMITTED');
+
+    // 2. Agent Thought (untouched)
+    const untouchedThought = result[1] as AgentThought;
+    expect(untouchedThought.id).toBe(thought.id);
+    expect(untouchedThought.text).not.toContain('[... OMITTED');
+  });
+});

packages/core/src/context/processors/nodeTruncationProcessor.ts

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { truncateProportionally } from '../truncation.js';
+import type { ConcreteNode } from '../ir/types.js';
+
+export interface NodeTruncationProcessorOptions {
+  maxTokensPerNode: number;
+}
+
+export function createNodeTruncationProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: NodeTruncationProcessorOptions,
+): ContextProcessor {
+  const tryApplySquash = (
+    text: string,
+    limitChars: number,
+  ): {
+    text: string;
+    newTokens: number;
+    oldTokens: number;
+    tokensSaved: number;
+  } | null => {
+    const originalLength = text.length;
+    if (originalLength <= limitChars) return null;
+
+    const newText = truncateProportionally(
+      text,
+      limitChars,
+      `\n\n[... OMITTED ${originalLength - limitChars} chars ...]\n\n`,
+    );
+
+    if (newText !== text) {
+      // Using accurate TokenCalculator instead of simple math
+      const newTokens = env.tokenCalculator.estimateTokensForString(newText);
+      const oldTokens = env.tokenCalculator.estimateTokensForString(text);
+      const tokensSaved = oldTokens - newTokens;
+
+      if (tokensSaved > 0) {
+        return { text: newText, newTokens, oldTokens, tokensSaved };
+      }
+    }
+    return null;
+  };
+
+  return {
+    id,
+    name: 'NodeTruncationProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      if (targets.length === 0) {
+        return targets;
+      }
+
+      const { maxTokensPerNode } = options;
+      const limitChars = env.tokenCalculator.tokensToChars(maxTokensPerNode);
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      for (const node of targets) {
+        switch (node.type) {
+          case 'USER_PROMPT': {
+            let modified = false;
+            const newParts = [...node.semanticParts];
+
+            for (let j = 0; j < node.semanticParts.length; j++) {
+              const part = node.semanticParts[j];
+              if (part.type === 'text') {
+                const squashResult = tryApplySquash(part.text, limitChars);
+                if (squashResult) {
+                  newParts[j] = { type: 'text', text: squashResult.text };
+                  modified = true;
+                }
+              }
+            }
+
+            if (modified) {
+              returnedNodes.push({
+                ...node,
+                id: env.idGenerator.generateId(),
+                semanticParts: newParts,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          case 'AGENT_THOUGHT': {
+            const squashResult = tryApplySquash(node.text, limitChars);
+            if (squashResult) {
+              returnedNodes.push({
+                ...node,
+                id: env.idGenerator.generateId(),
+                text: squashResult.text,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          case 'AGENT_YIELD': {
+            const squashResult = tryApplySquash(node.text, limitChars);
+            if (squashResult) {
+              returnedNodes.push({
+                ...node,
+                id: env.idGenerator.generateId(),
+                text: squashResult.text,
+                replacesId: node.id,
+              });
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/processors/rollingSummaryProcessor.test.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createRollingSummaryProcessor } from './rollingSummaryProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyNode,
+} from '../testing/contextTestUtils.js';
+
+describe('RollingSummaryProcessor', () => {
+  it('should initialize with correct default options', () => {
+    const env = createMockEnvironment();
+    const processor = createRollingSummaryProcessor(
+      'RollingSummaryProcessor',
+      env,
+      {
+        target: 'incremental',
+      },
+    );
+    expect(processor.id).toBe('RollingSummaryProcessor');
+  });
+
+  it('should summarize older nodes when the deficit exceeds the threshold', async () => {
+    // env.tokenCalculator uses charsPerToken=1 based on createMockEnvironment
+    const env = createMockEnvironment();
+
+    // We want to free exactly 100 tokens.
+    // We will supply nodes that cost 50 tokens each.
+    const processor = createRollingSummaryProcessor(
+      'RollingSummaryProcessor',
+      env,
+      {
+        target: 'freeNTokens',
+        freeTokensTarget: 100,
+      },
+    );
+
+    const text50 = 'A'.repeat(50);
+    const targets = [
+      createDummyNode(
+        'ep1',
+        'USER_PROMPT',
+        50,
+        { semanticParts: [{ type: 'text', text: text50 }] },
+        'id1',
+      ),
+      createDummyNode('ep1', 'AGENT_THOUGHT', 50, { text: text50 }, 'id2'),
+      createDummyNode('ep1', 'AGENT_YIELD', 50, { text: text50 }, 'id3'),
+    ];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    // 3 nodes at 50 cost each.
+    // The first node (id1) is the initial USER_PROMPT and is always skipped by RollingSummaryProcessor.
+    // Node id2 adds 50 deficit. Node id3 adds 50 deficit. Total = 100 deficit, which hits the target break point.
+    // Thus, id2 and id3 are summarized into a new ROLLING_SUMMARY node.
+    expect(result.length).toBe(2);
+    expect(result[0].type).toBe('USER_PROMPT');
+    expect(result[1].type).toBe('ROLLING_SUMMARY');
+  });
+
+  it('should preserve targets if deficit does not trigger summary', async () => {
+    const env = createMockEnvironment();
+
+    // We want to free 100 tokens, but our nodes will only cost 10 tokens each.
+    const processor = createRollingSummaryProcessor(
+      'RollingSummaryProcessor',
+      env,
+      {
+        target: 'freeNTokens',
+        freeTokensTarget: 100,
+      },
+    );
+
+    const text10 = 'A'.repeat(10);
+    const targets = [
+      createDummyNode(
+        'ep1',
+        'USER_PROMPT',
+        10,
+        { semanticParts: [{ type: 'text', text: text10 }] },
+        'id1',
+      ),
+      createDummyNode('ep1', 'AGENT_THOUGHT', 10, { text: text10 }, 'id2'),
+    ];
+
+    const result = await processor.process(createMockProcessArgs(targets));
+
+    // Deficit accumulator reaches 10. This is < 100 limit, and total summarizable nodes < 2 anyway.
+    expect(result.length).toBe(2);
+    expect(result[0].type).toBe('USER_PROMPT');
+    expect(result[1].type).toBe('AGENT_THOUGHT');
+  });
+});

packages/core/src/context/processors/rollingSummaryProcessor.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type {
+  ContextProcessor,
+  ProcessArgs,
+  BackstopTargetOptions,
+} from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode, RollingSummary } from '../ir/types.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { LlmRole } from '../../telemetry/llmRole.js';
+
+export interface RollingSummaryProcessorOptions extends BackstopTargetOptions {
+  systemInstruction?: string;
+}
+
+export function createRollingSummaryProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: RollingSummaryProcessorOptions,
+): ContextProcessor {
+  const generateRollingSummary = async (
+    nodes: ConcreteNode[],
+  ): Promise<string> => {
+    let transcript = '';
+    for (const node of nodes) {
+      let nodeContent = '';
+      if ('text' in node && typeof node.text === 'string') {
+        nodeContent = node.text;
+      } else if ('semanticParts' in node) {
+        nodeContent = JSON.stringify(node.semanticParts);
+      } else if ('observation' in node) {
+        nodeContent =
+          typeof node.observation === 'string'
+            ? node.observation
+            : JSON.stringify(node.observation);
+      }
+      transcript += `[${node.type}]: ${nodeContent}\n`;
+    }
+
+    const systemPrompt =
+      options.systemInstruction ??
+      `You are an expert context compressor. Your job is to drastically shorten the provided conversational transcript while preserving the absolute core semantic meaning, facts, and intent. Omit all conversational filler, pleasantries, or redundant information. Return ONLY the compressed summary.`;
+
+    const response = await env.llmClient.generateContent({
+      role: LlmRole.UTILITY_COMPRESSOR,
+      modelConfigKey: { model: 'gemini-3-flash-base' },
+      promptId: env.promptId,
+      abortSignal: new AbortController().signal,
+      contents: [{ role: 'user', parts: [{ text: transcript }] }],
+      systemInstruction: { role: 'system', parts: [{ text: systemPrompt }] },
+    });
+
+    const candidate = response.candidates?.[0];
+    const textPart = candidate?.content?.parts?.[0];
+    return textPart?.text || '';
+  };
+
+  return {
+    id,
+    name: 'RollingSummaryProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      if (targets.length === 0) return targets;
+
+      const strategy = options.target ?? 'max';
+      const nodesToSummarize: ConcreteNode[] = [];
+
+      if (strategy === 'incremental') {
+        // 'incremental' simply summarizes the minimum viable chunk (the oldest 2 nodes), ignoring token math.
+        for (const node of targets) {
+          if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+            continue; // Keep system prompt
+          }
+          nodesToSummarize.push(node);
+          if (nodesToSummarize.length >= 2) break; // We have enough for a minimum rolling summary
+        }
+      } else {
+        let targetTokensToRemove = 0;
+        if (strategy === 'freeNTokens') {
+          targetTokensToRemove = options.freeTokensTarget ?? Infinity;
+        } else if (strategy === 'max') {
+          targetTokensToRemove = Infinity;
+        }
+
+        if (targetTokensToRemove > 0) {
+          let deficitAccumulator = 0;
+          for (const node of targets) {
+            if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+              continue; // Keep system prompt
+            }
+            nodesToSummarize.push(node);
+            deficitAccumulator += env.tokenCalculator.getTokenCost(node);
+            if (deficitAccumulator >= targetTokensToRemove) break;
+          }
+        }
+      }
+
+      if (nodesToSummarize.length < 2) return targets; // Not enough context to summarize
+
+      try {
+        // Synthesize the rolling summary synchronously
+        const snapshotText = await generateRollingSummary(nodesToSummarize);
+        const newId = env.idGenerator.generateId();
+
+        const summaryNode: RollingSummary = {
+          id: newId,
+          logicalParentId: newId,
+          type: 'ROLLING_SUMMARY',
+          timestamp: Date.now(),
+          text: snapshotText,
+          abstractsIds: nodesToSummarize.map((n) => n.id),
+        };
+
+        const consumedIds = nodesToSummarize.map((n) => n.id);
+        const returnedNodes = targets.filter(
+          (t) => !consumedIds.includes(t.id),
+        );
+        const firstRemovedIdx = targets.findIndex((t) =>
+          consumedIds.includes(t.id),
+        );
+
+        if (firstRemovedIdx !== -1) {
+          const idx = Math.max(0, firstRemovedIdx);
+          returnedNodes.splice(idx, 0, summaryNode);
+        } else {
+          returnedNodes.unshift(summaryNode);
+        }
+
+        return returnedNodes;
+      } catch (e) {
+        debugLogger.error('RollingSummaryProcessor failed sync backstop', e);
+        return targets;
+      }
+    },
+  };
+}

packages/core/src/context/processors/stateSnapshotAsyncProcessor.test.ts

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createStateSnapshotAsyncProcessor } from './stateSnapshotAsyncProcessor.js';
+import {
+  createMockEnvironment,
+  createDummyNode,
+  createMockProcessArgs,
+} from '../testing/contextTestUtils.js';
+
+describe('StateSnapshotAsyncProcessor', () => {
+  it('should generate a snapshot and publish it to the cache', async () => {
+    const env = createMockEnvironment();
+    
+    const worker = createStateSnapshotAsyncProcessor(
+      'StateSnapshotAsyncProcessor',
+      env,
+      { type: 'point-in-time' },
+    );
+
+    const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 60, {}, 'node-B');
+
+    const targets = [nodeA, nodeB];
+    const args = createMockProcessArgs(targets, targets, []);
+    const publishSpy = vi.spyOn(args.snapshotCache, 'publish');
+
+    await worker.process(args);
+
+    // Ensure generateContent was called
+    expect(env.llmClient.generateContent).toHaveBeenCalled();
+
+    // Verify it published to the cache
+    expect(publishSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        newText: 'Mock LLM summary response',
+        consumedIds: ['node-A', 'node-B'],
+        type: 'point-in-time',
+      }),
+      env.idGenerator,
+    );
+  });
+
+  it('should pull previous accumulate snapshot from cache and append new targets', async () => {
+    const env = createMockEnvironment();
+    const worker = createStateSnapshotAsyncProcessor(
+      'StateSnapshotAsyncProcessor',
+      env,
+      { type: 'accumulate' },
+    );
+
+    const nodeC = createDummyNode('ep2', 'USER_PROMPT', 50, {}, 'node-C');
+    const targets = [nodeC];
+
+    const proposals = [
+      {
+        id: 'draft-1',
+        timestamp: Date.now() - 1000,
+        consumedIds: ['node-A', 'node-B'],
+        newText: '<old snapshot>',
+        type: 'accumulate',
+      },
+    ];
+
+    const args = createMockProcessArgs(targets, targets, proposals);
+    const publishSpy = vi.spyOn(args.snapshotCache, 'publish');
+    const consumeSpy = vi.spyOn(args.snapshotCache, 'consume');
+
+    await worker.process(args);
+
+    // The old draft should be consumed
+    expect(consumeSpy).toHaveBeenCalledWith('draft-1');
+
+    // The new publish should contain ALL consumed IDs (old + new)
+    expect(publishSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        newText: 'Mock LLM summary response',
+        consumedIds: ['node-A', 'node-B', 'node-C'], // Aggregated!
+        type: 'accumulate',
+      }),
+      env.idGenerator,
+    );
+
+    // Verify the LLM was called with the old snapshot prepended
+    expect(env.llmClient.generateContent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contents: expect.arrayContaining([
+          expect.objectContaining({
+            parts: expect.arrayContaining([
+              expect.objectContaining({
+                text: expect.stringContaining('<old snapshot>'),
+              }),
+            ]),
+          }),
+        ]),
+      }),
+    );
+  });
+
+  it('should ignore empty targets', async () => {
+    const env = createMockEnvironment();
+    const worker = createStateSnapshotAsyncProcessor(
+      'StateSnapshotAsyncProcessor',
+      env,
+      { type: 'accumulate' },
+    );
+
+    const args = createMockProcessArgs([], [], []);
+    const publishSpy = vi.spyOn(args.snapshotCache, 'publish');
+
+    await worker.process(args);
+
+    expect(env.llmClient.generateContent).not.toHaveBeenCalled();
+    expect(publishSpy).not.toHaveBeenCalled();
+  });
+});

packages/core/src/context/processors/stateSnapshotAsyncProcessor.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AsyncContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode } from '../ir/types.js';
+import { SnapshotGenerator } from '../utils/snapshotGenerator.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+
+export interface StateSnapshotAsyncProcessorOptions {
+  type?: 'accumulate' | 'point-in-time';
+  systemInstruction?: string;
+}
+
+export function createStateSnapshotAsyncProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: StateSnapshotAsyncProcessorOptions,
+): AsyncContextProcessor {
+  const generator = new SnapshotGenerator(env);
+
+  return {
+    id,
+    name: 'StateSnapshotAsyncProcessor',
+    process: async ({ targets, snapshotCache }: ProcessArgs): Promise<void> => {
+      if (targets.length === 0) return;
+
+      try {
+        let nodesToSummarize = [...targets];
+        let previousConsumedIds: string[] = [];
+        const processorType = options.type ?? 'point-in-time';
+
+        if (processorType === 'accumulate') {
+          // Look for the most recent unconsumed accumulate snapshot in the cache
+          const proposedSnapshots = snapshotCache.getProposals();
+          const accumulateSnapshots = proposedSnapshots.filter(
+            (s) => s.type === 'accumulate',
+          );
+
+          if (accumulateSnapshots.length > 0) {
+            // Sort to find the most recent
+            const latest = [...accumulateSnapshots].sort(
+              (a, b) => b.timestamp - a.timestamp,
+            )[0];
+
+            // Consume the old draft so the cache doesn't fill up with stale drafts
+            snapshotCache.consume(latest.id);
+
+            previousConsumedIds = latest.consumedIds;
+
+            // Prepend a synthetic node representing the previous rolling state
+            const previousStateNode: ConcreteNode = {
+              id: env.idGenerator.generateId(),
+              logicalParentId: '',
+              type: 'SNAPSHOT',
+              timestamp: latest.timestamp,
+              text: latest.newText,
+            };
+
+            nodesToSummarize = [previousStateNode, ...targets];
+          }
+        }
+
+        const snapshotText = await generator.synthesizeSnapshot(
+          nodesToSummarize,
+          options.systemInstruction,
+        );
+
+        const newConsumedIds = [
+          ...previousConsumedIds,
+          ...targets.map((t) => t.id),
+        ];
+
+        snapshotCache.publish(
+          {
+            newText: snapshotText,
+            consumedIds: newConsumedIds,
+            type: processorType,
+          },
+          env.idGenerator,
+        );
+      } catch (e) {
+        debugLogger.error(
+          'StateSnapshotAsyncProcessor failed to generate snapshot',
+          e,
+        );
+      }
+    },
+  };
+}

packages/core/src/context/processors/stateSnapshotProcessor.test.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { createStateSnapshotProcessor } from './stateSnapshotProcessor.js';
+import {
+  createMockEnvironment,
+  createDummyNode,
+  createMockProcessArgs,
+} from '../testing/contextTestUtils.js';
+
+describe('StateSnapshotProcessor', () => {
+  it('should return original targets if no nodes to process', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, {
+      target: 'max',
+    });
+
+    const result = await processor.process(createMockProcessArgs([], []));
+    expect(result).toEqual([]);
+  });
+
+  it('should use pre-computed snapshot from cache if valid', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, {
+      target: 'max', // implies 'accumulate' type
+    });
+
+    const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 50, {}, 'node-B');
+    const nodeC = createDummyNode('ep1', 'TOOL_EXECUTION', 50, {}, 'node-C');
+
+    const targets = [nodeA, nodeB, nodeC];
+
+    const proposals = [
+      {
+        id: 'msg-1',
+        timestamp: Date.now(),
+        newText: 'Pre-computed summary of A and B',
+        consumedIds: ['node-A', 'node-B'],
+        type: 'accumulate',
+      },
+    ];
+
+    const processArgs = createMockProcessArgs(targets, targets, proposals);
+    const consumeSpy = vi.spyOn(processArgs.snapshotCache, 'consume');
+
+    const result = await processor.process(processArgs);
+
+    // It should have replaced A and B with a SNAPSHOT, and kept C
+    expect(result.length).toBe(2);
+    expect(result[0].type).toBe('SNAPSHOT');
+    expect((result[0] as any).text).toBe('Pre-computed summary of A and B');
+    expect(result[1]).toEqual(nodeC);
+
+    // The message should be consumed
+    expect(consumeSpy).toHaveBeenCalledWith('msg-1');
+  });
+
+  it('should fall back to synchronous generation if no valid snapshot in cache', async () => {
+    const env = createMockEnvironment();
+    const processor = createStateSnapshotProcessor('StateSnapshotProcessor', env, {
+      target: 'max',
+    });
+
+    const nodeA = createDummyNode('ep1', 'USER_PROMPT', 50, {}, 'node-A');
+    const nodeB = createDummyNode('ep1', 'AGENT_THOUGHT', 50, {}, 'node-B');
+
+    const targets = [nodeA, nodeB];
+
+    // Invalid snapshot (consumes a node that isn't in targets)
+    const proposals = [
+      {
+        id: 'msg-1',
+        timestamp: Date.now(),
+        newText: 'Invalid summary',
+        consumedIds: ['node-X'],
+        type: 'accumulate',
+      },
+    ];
+
+    const processArgs = createMockProcessArgs(targets, targets, proposals);
+    const consumeSpy = vi.spyOn(processArgs.snapshotCache, 'consume');
+
+    const result = await processor.process(processArgs);
+
+    // Should have generated synchronously
+    expect(env.llmClient.generateContent).toHaveBeenCalled();
+    expect(result.length).toBe(1);
+    expect(result[0].type).toBe('SNAPSHOT');
+    expect((result[0] as any).text).toBe('Mock LLM summary response');
+
+    // Should not have consumed the invalid message
+    expect(consumeSpy).not.toHaveBeenCalledWith('msg-1');
+  });
+});

packages/core/src/context/processors/stateSnapshotProcessor.ts

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type {
+  ContextProcessor,
+  ProcessArgs,
+  BackstopTargetOptions,
+} from '../pipeline.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { ConcreteNode, Snapshot } from '../ir/types.js';
+import { SnapshotGenerator } from '../utils/snapshotGenerator.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+
+export interface StateSnapshotProcessorOptions extends BackstopTargetOptions {
+  model?: string;
+  systemInstruction?: string;
+}
+
+export function createStateSnapshotProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: StateSnapshotProcessorOptions,
+): ContextProcessor {
+  const generator = new SnapshotGenerator(env);
+
+  return {
+    id,
+    name: 'StateSnapshotProcessor',
+    process: async ({ targets, snapshotCache }: ProcessArgs) => {
+      if (targets.length === 0) {
+        return targets;
+      }
+
+      // Determine what mode we are looking for: 'incremental' -> 'point-in-time', 'max' -> 'accumulate'
+      const strategy = options.target ?? 'max';
+      const expectedType =
+        strategy === 'incremental' ? 'point-in-time' : 'accumulate';
+
+      // 1. Check cache for a completed Snapshot (The Fast Path)
+      const proposedSnapshots = snapshotCache.getProposals();
+
+      if (proposedSnapshots.length > 0) {
+        // Filter for the snapshot type that matches our processor mode
+        const matchingSnapshots = proposedSnapshots.filter(
+          (s) => s.type === expectedType,
+        );
+
+        // Sort by newest timestamp first (we want the most accumulated snapshot)
+        const sorted = [...matchingSnapshots].sort(
+          (a, b) => b.timestamp - a.timestamp,
+        );
+
+        for (const proposed of sorted) {
+          const { consumedIds, newText } = proposed;
+
+          // Verify all consumed IDs still exist sequentially in targets
+          const targetIds = new Set(targets.map((t) => t.id));
+          const isValid = consumedIds.every((id) => targetIds.has(id));
+
+          if (isValid) {
+            // If valid, apply it!
+            const newId = env.idGenerator.generateId();
+
+            const snapshotNode: Snapshot = {
+              id: newId,
+              logicalParentId: newId,
+              type: 'SNAPSHOT',
+              timestamp: Date.now(),
+              text: newText,
+              abstractsIds: consumedIds,
+            };
+
+            // Remove the consumed nodes and insert the snapshot at the earliest index
+            const returnedNodes = targets.filter(
+              (t) => !consumedIds.includes(t.id),
+            );
+            const firstRemovedIdx = targets.findIndex((t) =>
+              consumedIds.includes(t.id),
+            );
+
+            if (firstRemovedIdx !== -1) {
+              const idx = Math.max(0, firstRemovedIdx);
+              returnedNodes.splice(idx, 0, snapshotNode);
+            } else {
+              returnedNodes.unshift(snapshotNode);
+            }
+
+            snapshotCache.consume(proposed.id);
+            return returnedNodes;
+          }
+        }
+      }
+
+      // 2. The Synchronous Backstop (The Slow Path)
+      let targetTokensToRemove = 0;
+
+      if (strategy === 'incremental') {
+        targetTokensToRemove = Infinity; // incremental implies removing as much as possible if no state is passed
+      } else if (strategy === 'freeNTokens') {
+        targetTokensToRemove = options.freeTokensTarget ?? Infinity;
+      } else if (strategy === 'max') {
+        targetTokensToRemove = Infinity;
+      }
+
+      let deficitAccumulator = 0;
+      const nodesToSummarize: ConcreteNode[] = [];
+
+      // Scan oldest to newest
+      for (const node of targets) {
+        if (node.id === targets[0].id && node.type === 'USER_PROMPT') {
+          // Keep system prompt if it's the very first node
+          // In a real system, system prompt is protected, but we double check
+          continue;
+        }
+
+        nodesToSummarize.push(node);
+        deficitAccumulator += env.tokenCalculator.getTokenCost(node);
+
+        if (deficitAccumulator >= targetTokensToRemove) break;
+      }
+
+      if (nodesToSummarize.length < 2) return targets; // Not enough context
+
+      try {
+        const snapshotText = await generator.synthesizeSnapshot(
+          nodesToSummarize,
+          options.systemInstruction,
+        );
+        const newId = env.idGenerator.generateId();
+        const snapshotNode: Snapshot = {
+          id: newId,
+          logicalParentId: newId,
+          type: 'SNAPSHOT',
+          timestamp: Date.now(),
+          text: snapshotText,
+          abstractsIds: nodesToSummarize.map((n) => n.id),
+        };
+
+        const consumedIds = nodesToSummarize.map((n) => n.id);
+        const returnedNodes = targets.filter(
+          (t) => !consumedIds.includes(t.id),
+        );
+        const firstRemovedIdx = targets.findIndex((t) =>
+          consumedIds.includes(t.id),
+        );
+
+        if (firstRemovedIdx !== -1) {
+          const idx = Math.max(0, firstRemovedIdx);
+          returnedNodes.splice(idx, 0, snapshotNode);
+        } else {
+          returnedNodes.unshift(snapshotNode);
+        }
+
+        return returnedNodes;
+      } catch (e) {
+        debugLogger.error('StateSnapshotProcessor failed sync backstop', e);
+        return targets;
+      }
+    },
+  };
+}

packages/core/src/context/processors/toolMaskingProcessor.test.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect } from 'vitest';
+import { createToolMaskingProcessor } from './toolMaskingProcessor.js';
+import {
+  createMockProcessArgs,
+  createMockEnvironment,
+  createDummyToolNode,
+} from '../testing/contextTestUtils.js';
+import type { ToolExecution } from '../ir/types.js';
+
+describe('ToolMaskingProcessor', () => {
+  it('should write large strings to disk and replace them with a masked pointer', async () => {
+    const env = createMockEnvironment();
+    // env uses charsPerToken=1 natively.
+    // original string lengths > stringLengthThresholdTokens (which is 10) will be masked
+
+    const processor = createToolMaskingProcessor('ToolMaskingProcessor', env, {
+      stringLengthThresholdTokens: 10,
+    });
+
+    const longString = 'A'.repeat(500); // 500 chars
+
+    const toolStep = createDummyToolNode('ep1', 50, 500, {
+      observation: {
+        result: longString,
+        metadata: 'short', // 5 chars, will not be masked
+      },
+    });
+
+    const result = await processor.process(createMockProcessArgs([toolStep]));
+
+    expect(result.length).toBe(1);
+    const masked = result[0] as ToolExecution;
+
+    // It should have generated a new ID because it modified it
+    expect(masked.id).not.toBe(toolStep.id);
+
+    // It should have masked the observation
+    const obs = masked.observation as { result: string; metadata: string };
+    expect(obs.result).toContain('<tool_output_masked>');
+    expect(obs.metadata).toBe('short'); // Untouched
+  });
+
+  it('should skip unmaskable tools', async () => {
+    const env = createMockEnvironment();
+
+    const processor = createToolMaskingProcessor('ToolMaskingProcessor', env, {
+      stringLengthThresholdTokens: 10,
+    });
+
+    const toolStep = createDummyToolNode('ep1', 10, 10, {
+      toolName: 'activate_skill',
+      observation: {
+        result:
+          'this is a really long string that normally would get masked but wont because of the tool name',
+      },
+    });
+
+    const result = await processor.process(createMockProcessArgs([toolStep]));
+
+    // Returned the exact same object reference
+    expect(result[0]).toBe(toolStep);
+  });
+});

packages/core/src/context/processors/toolMaskingProcessor.ts

@@ -0,0 +1,261 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProcessor, ProcessArgs } from '../pipeline.js';
+import type { ConcreteNode, ToolExecution } from '../ir/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { sanitizeFilenamePart } from '../../utils/fileUtils.js';
+import {
+  ACTIVATE_SKILL_TOOL_NAME,
+  MEMORY_TOOL_NAME,
+  ASK_USER_TOOL_NAME,
+  ENTER_PLAN_MODE_TOOL_NAME,
+  EXIT_PLAN_MODE_TOOL_NAME,
+} from '../../tools/tool-names.js';
+import type { Part } from '@google/genai';
+
+const UNMASKABLE_TOOLS = new Set([
+  ACTIVATE_SKILL_TOOL_NAME,
+  MEMORY_TOOL_NAME,
+  ASK_USER_TOOL_NAME,
+  ENTER_PLAN_MODE_TOOL_NAME,
+  EXIT_PLAN_MODE_TOOL_NAME,
+]);
+
+export interface ToolMaskingProcessorOptions {
+  stringLengthThresholdTokens: number;
+}
+
+type MaskableValue =
+  | string
+  | number
+  | boolean
+  | null
+  | MaskableValue[]
+  | { [key: string]: MaskableValue };
+
+function isMaskableValue(val: unknown): val is MaskableValue {
+  if (
+    val === null ||
+    typeof val === 'string' ||
+    typeof val === 'number' ||
+    typeof val === 'boolean'
+  ) {
+    return true;
+  }
+  if (Array.isArray(val)) {
+    return val.every(isMaskableValue);
+  }
+  if (typeof val === 'object') {
+    return Object.values(val).every(isMaskableValue);
+  }
+  return false;
+}
+
+function isMaskableRecord(val: unknown): val is Record<string, MaskableValue> {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    !Array.isArray(val) &&
+    isMaskableValue(val)
+  );
+}
+
+export function createToolMaskingProcessor(
+  id: string,
+  env: ContextEnvironment,
+  options: ToolMaskingProcessorOptions,
+): ContextProcessor {
+  const isAlreadyMasked = (text: string): boolean =>
+    text.includes('<tool_output_masked>');
+
+  return {
+    id,
+    name: 'ToolMaskingProcessor',
+    process: async ({ targets }: ProcessArgs) => {
+      const maskingConfig = options;
+      if (!maskingConfig) return targets;
+      if (targets.length === 0) return targets;
+
+      const limitChars = env.tokenCalculator.tokensToChars(
+        maskingConfig.stringLengthThresholdTokens,
+      );
+
+      let toolOutputsDir = env.fileSystem.join(
+        env.projectTempDir,
+        'tool-outputs',
+      );
+      const sessionId = env.sessionId;
+      if (sessionId) {
+        toolOutputsDir = env.fileSystem.join(
+          toolOutputsDir,
+          `session-${sanitizeFilenamePart(sessionId)}`,
+        );
+      }
+
+      let directoryCreated = false;
+
+      const handleMasking = async (
+        content: string,
+        toolName: string,
+        callId: string,
+        nodeType: string,
+      ): Promise<string> => {
+        if (!directoryCreated) {
+          await env.fileSystem.mkdir(toolOutputsDir, { recursive: true });
+          directoryCreated = true;
+        }
+
+        const fileName = `${sanitizeFilenamePart(toolName).toLowerCase()}_${sanitizeFilenamePart(callId).toLowerCase()}_${nodeType}_${env.idGenerator.generateId()}.txt`;
+        const filePath = env.fileSystem.join(toolOutputsDir, fileName);
+
+        await env.fileSystem.writeFile(filePath, content);
+
+        const fileSizeMB = (
+          Buffer.byteLength(content, 'utf8') /
+          1024 /
+          1024
+        ).toFixed(2);
+        const totalLines = content.split('\n').length;
+        return `<tool_output_masked>\n[Tool ${nodeType} string (${fileSizeMB}MB, ${totalLines} lines) masked to preserve context window. Full string saved to: ${filePath}]\n</tool_output_masked>`;
+      };
+
+      const returnedNodes: ConcreteNode[] = [];
+
+      for (const node of targets) {
+        switch (node.type) {
+          case 'TOOL_EXECUTION': {
+            const toolName = node.toolName;
+            if (toolName && UNMASKABLE_TOOLS.has(toolName)) {
+              returnedNodes.push(node);
+              break;
+            }
+
+            const callId = node.id || Date.now().toString();
+
+            const maskAsync = async (
+              obj: MaskableValue,
+              nodeType: string,
+            ): Promise<{ masked: MaskableValue; changed: boolean }> => {
+              if (typeof obj === 'string') {
+                if (obj.length > limitChars && !isAlreadyMasked(obj)) {
+                  const newString = await handleMasking(
+                    obj,
+                    toolName || 'unknown',
+                    callId,
+                    nodeType,
+                  );
+                  return { masked: newString, changed: true };
+                }
+                return { masked: obj, changed: false };
+              }
+              if (Array.isArray(obj)) {
+                let changed = false;
+                const masked: MaskableValue[] = [];
+                for (const item of obj) {
+                  const res = await maskAsync(item, nodeType);
+                  if (res.changed) changed = true;
+                  masked.push(res.masked);
+                }
+                return { masked, changed };
+              }
+              if (typeof obj === 'object' && obj !== null) {
+                let changed = false;
+                const masked: Record<string, MaskableValue> = {};
+                for (const [key, value] of Object.entries(obj)) {
+                  const res = await maskAsync(value, nodeType);
+                  if (res.changed) changed = true;
+                  masked[key] = res.masked;
+                }
+                return { masked, changed };
+              }
+              return { masked: obj, changed: false };
+            };
+
+            const rawIntent = node.intent;
+            const rawObs = node.observation;
+
+            if (!isMaskableRecord(rawIntent) || !isMaskableValue(rawObs)) {
+              returnedNodes.push(node);
+              break;
+            }
+
+            const intentRes = await maskAsync(rawIntent, 'intent');
+            const obsRes = await maskAsync(rawObs, 'observation');
+
+            if (intentRes.changed || obsRes.changed) {
+              const maskedIntent = isMaskableRecord(intentRes.masked)
+                ? (intentRes.masked as Record<string, unknown>)
+                : undefined;
+              // Handle observation explicitly as string vs object
+              const maskedObs =
+                typeof obsRes.masked === 'string'
+                  ? ({ message: obsRes.masked } as Record<string, unknown>)
+                  : isMaskableRecord(obsRes.masked)
+                    ? (obsRes.masked as Record<string, unknown>)
+                    : undefined;
+
+              const newIntentTokens =
+                env.tokenCalculator.estimateTokensForParts([
+                  {
+                    functionCall: {
+                      name: toolName || 'unknown',
+                      args: maskedIntent,
+                      id: callId,
+                    },
+                  },
+                ]);
+
+              let obsPart: Record<string, unknown> = {};
+              if (maskedObs) {
+                obsPart = {
+                  functionResponse: {
+                    name: toolName || 'unknown',
+                    response: maskedObs,
+                    id: callId,
+                  },
+                };
+              }
+
+              const newObsTokens = env.tokenCalculator.estimateTokensForParts([
+                obsPart as Part,
+              ]);
+
+              const tokensSaved =
+                env.tokenCalculator.getTokenCost(node) -
+                (newIntentTokens + newObsTokens);
+
+              if (tokensSaved > 0) {
+                const maskedNode: ToolExecution = {
+                  ...node,
+                  id: env.idGenerator.generateId(), // Modified, so generate new ID
+                  intent: maskedIntent ?? node.intent,
+                  observation: maskedObs ?? node.observation,
+                  tokens: {
+                    intent: newIntentTokens,
+                    observation: newObsTokens,
+                  },
+                  replacesId: node.id,
+                };
+
+                returnedNodes.push(maskedNode);
+              } else {
+                returnedNodes.push(node);
+              }
+            } else {
+              returnedNodes.push(node);
+            }
+            break;
+          }
+          default:
+            returnedNodes.push(node);
+            break;
+        }
+      }
+
+      return returnedNodes;
+    },
+  };
+}

packages/core/src/context/system-tests/lifecycle.golden.test.ts

@@ -0,0 +1,246 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { SimulationHarness } from './simulationHarness.js';
+import { createMockLlmClient } from '../testing/contextTestUtils.js';
+import type { ContextProfile } from '../config/profiles.js';
+import { createToolMaskingProcessor } from '../processors/toolMaskingProcessor.js';
+import { createBlobDegradationProcessor } from '../processors/blobDegradationProcessor.js';
+import { createStateSnapshotProcessor } from '../processors/stateSnapshotProcessor.js';
+import { createHistoryTruncationProcessor } from '../processors/historyTruncationProcessor.js';
+import { createStateSnapshotAsyncProcessor } from '../processors/stateSnapshotAsyncProcessor.js';
+
+expect.addSnapshotSerializer({
+  test: (val) =>
+    typeof val === 'string' &&
+    (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+      val,
+    ) ||
+      /^\/tmp\/sim/.test(val)), // Mask temp directories and UUIDs
+  print: (val) =>
+    typeof val === 'string' && /^\/tmp\/sim/.test(val)
+      ? '"<MOCKED_DIR>"'
+      : '"<UUID>"',
+});
+
+describe('System Lifecycle Golden Tests', () => {
+  beforeAll(() => {
+    vi.spyOn(Math, 'random').mockReturnValue(0.5);
+  });
+
+  afterAll(() => {
+    vi.restoreAllMocks();
+  });
+
+  const getAggressiveConfig = (): ContextProfile => ({
+    config: {
+      budget: { maxTokens: 1000, retainedTokens: 500 }, // Extremely tight limits
+    },
+    buildPipelines: (env) => [
+      {
+        name: 'Pressure Relief', // Emits from eventBus 'retained_exceeded'
+        triggers: ['retained_exceeded'],
+        processors: [
+          createBlobDegradationProcessor('BlobDegradationProcessor', env),
+          createToolMaskingProcessor('ToolMaskingProcessor', env, {
+            stringLengthThresholdTokens: 50,
+          }),
+          createStateSnapshotProcessor('StateSnapshotProcessor', env, {}),
+        ],
+      },
+      {
+        name: 'Immediate Sanitization', // The magic string the projector is hardcoded to use
+        triggers: ['retained_exceeded'],
+        processors: [
+          createHistoryTruncationProcessor(
+            'HistoryTruncationProcessor',
+            env,
+            {},
+          ),
+        ],
+      },
+    ],
+    buildAsyncPipelines: (env) => [
+      {
+        name: 'Async',
+        triggers: ['nodes_aged_out'],
+        processors: [
+          createStateSnapshotAsyncProcessor(
+            'StateSnapshotAsyncProcessor',
+            env,
+            {},
+          ),
+        ],
+      },
+    ],
+  });
+
+  const mockLlmClient = createMockLlmClient([
+    '<MOCKED_STATE_SNAPSHOT_SUMMARY>',
+  ]);
+
+  it('Scenario 1: Organic Growth with Huge Tool Output & Images', async () => {
+    const harness = await SimulationHarness.create(
+      getAggressiveConfig(),
+      mockLlmClient,
+    );
+
+    // Turn 0: System Prompt
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'System Instructions' }] },
+      { role: 'model', parts: [{ text: 'Ack.' }] },
+    ]);
+
+    // Turn 1: Normal conversation
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Hello!' }] },
+      { role: 'model', parts: [{ text: 'Hi, how can I help?' }] },
+    ]);
+
+    // Turn 2: Massive Tool Output (Should trigger ToolMaskingProcessor in background)
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Read the logs.' }] },
+      {
+        role: 'model',
+        parts: [
+          {
+            functionCall: {
+              name: 'run_shell_command',
+              args: { cmd: 'cat server.log' },
+            },
+          },
+        ],
+      },
+      {
+        role: 'user',
+        parts: [
+          {
+            functionResponse: {
+              name: 'run_shell_command',
+              response: { output: 'LOG '.repeat(5000) },
+            },
+          },
+        ],
+      },
+      { role: 'model', parts: [{ text: 'The logs are very long.' }] },
+    ]);
+
+    // Turn 3: Multi-modal blob (Should trigger BlobDegradationProcessor)
+    await harness.simulateTurn([
+      {
+        role: 'user',
+        parts: [
+          { text: 'Look at this architecture diagram:' },
+          {
+            inlineData: {
+              mimeType: 'image/png',
+              data: 'fake_base64_data_'.repeat(1000),
+            },
+          },
+        ],
+      },
+      { role: 'model', parts: [{ text: 'Nice diagram.' }] },
+    ]);
+
+    // Turn 4: More conversation to trigger StateSnapshot
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Can we refactor?' }] },
+      { role: 'model', parts: [{ text: 'Yes we can.' }] },
+    ]);
+
+    // Get final state
+    const goldenState = await harness.getGoldenState();
+
+    // In a perfectly functioning opportunistic system, the token trajectory should show
+    // the massive spikes in Turn 2 and 3 being immediately resolved by the background tasks.
+    // The final projection should fit neatly under the Max Tokens limit.
+
+    expect(goldenState).toMatchSnapshot();
+  });
+
+  it('Scenario 2: Under Budget (No Modifications)', async () => {
+    const generousConfig: ContextProfile = {
+      config: {
+        budget: { maxTokens: 100000, retainedTokens: 50000 },
+      },
+      buildPipelines: () => [],
+      buildAsyncPipelines: () => [],
+    };
+
+    const harness = await SimulationHarness.create(
+      generousConfig,
+      mockLlmClient,
+    );
+
+    // Turn 0: System Prompt
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'System Instructions' }] },
+      { role: 'model', parts: [{ text: 'Ack.' }] },
+    ]);
+
+    // Turn 1: Normal conversation
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'Hello!' }] },
+      { role: 'model', parts: [{ text: 'Hi, how can I help?' }] },
+    ]);
+
+    const goldenState = await harness.getGoldenState();
+
+    // Total tokens should cleanly match character count with no synthetic nodes
+    expect(goldenState).toMatchSnapshot();
+  });
+
+  it('Scenario 3: Async-Driven Background GC', async () => {
+    const gcConfig: ContextProfile = {
+      config: {
+        budget: { maxTokens: 200, retainedTokens: 100 },
+      },
+      buildPipelines: () => [],
+      buildAsyncPipelines: (env) => [
+        {
+          name: 'Async',
+          triggers: ['nodes_aged_out'],
+          processors: [
+            createStateSnapshotAsyncProcessor(
+              'StateSnapshotAsyncProcessor',
+              env,
+              {},
+            ),
+          ],
+        },
+      ],
+    };
+
+    const harness = await SimulationHarness.create(gcConfig, mockLlmClient);
+
+    // Turn 0
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'A'.repeat(50) }] },
+      { role: 'model', parts: [{ text: 'B'.repeat(50) }] },
+    ]);
+
+    // Turn 1 (Should trigger StateSnapshotasync pipeline because we exceed 100 retainedTokens)
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'C'.repeat(50) }] },
+      { role: 'model', parts: [{ text: 'D'.repeat(50) }] },
+    ]);
+
+    // Give the async background pipeline an extra beat to complete its async execution and emit variants
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Turn 2
+    await harness.simulateTurn([
+      { role: 'user', parts: [{ text: 'E'.repeat(50) }] },
+      { role: 'model', parts: [{ text: 'F'.repeat(50) }] },
+    ]);
+
+    const goldenState = await harness.getGoldenState();
+
+    // We should see ROLLING_SUMMARY nodes injected into the graph, proving the async pipeline ran in the background
+    expect(goldenState).toMatchSnapshot();
+  });
+});

packages/core/src/context/system-tests/simulationHarness.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ContextManager } from '../contextManager.js';
+import { AgentChatHistory } from '../../core/agentChatHistory.js';
+import type { Content } from '@google/genai';
+import type { ContextProfile } from '../config/profiles.js';
+import { ContextEnvironmentImpl } from '../pipeline/environmentImpl.js';
+import { ContextTracer } from '../tracer.js';
+import { debugLogger } from '../../utils/debugLogger.js';
+import { DeterministicIdGenerator } from '../system/DeterministicIdGenerator.js';
+import { InMemoryFileSystem } from '../system/InMemoryFileSystem.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+
+export interface TurnSummary {
+  turnIndex: number;
+  tokensBeforeBackground: number;
+  tokensAfterBackground: number;
+}
+
+export class SimulationHarness {
+  readonly chatHistory: AgentChatHistory;
+  contextManager!: ContextManager;
+  env!: ContextEnvironmentImpl;
+  config!: ContextProfile;
+  private tracer!: ContextTracer;
+  private currentTurnIndex = 0;
+  private tokenTrajectory: TurnSummary[] = [];
+
+  static async create(
+    config: ContextProfile,
+    mockLlmClient: BaseLlmClient,
+    mockTempDir = '/tmp/sim',
+  ): Promise<SimulationHarness> {
+    const harness = new SimulationHarness();
+    await harness.init(config, mockLlmClient, mockTempDir);
+    return harness;
+  }
+
+  private constructor() {
+    this.chatHistory = new AgentChatHistory();
+  }
+
+  private async init(
+    config: ContextProfile,
+    mockLlmClient: BaseLlmClient,
+    mockTempDir: string,
+  ) {
+    this.config = config;
+
+    this.tracer = new ContextTracer({
+      targetDir: mockTempDir,
+      sessionId: 'sim-session',
+    });
+    this.env = new ContextEnvironmentImpl(
+      mockLlmClient,
+      'sim-prompt',
+      'sim-session',
+      mockTempDir,
+      mockTempDir,
+      this.tracer,
+      1, // 1 char per token average
+      new InMemoryFileSystem(),
+      new DeterministicIdGenerator(),
+    );
+
+    this.contextManager = new ContextManager(
+      config,
+      this.env,
+      this.tracer,
+      this.chatHistory,
+    );
+  }
+
+  async simulateTurn(messages: Content[]) {
+    const currentHistory = this.chatHistory.get();
+    this.chatHistory.set([...currentHistory, ...messages]);
+
+    const tokensBefore = this.env.tokenCalculator.calculateConcreteListTokens(
+      this.contextManager.getNodes(),
+    );
+    debugLogger.log(
+      `[Turn ${this.currentTurnIndex}] Tokens BEFORE: ${tokensBefore}`,
+    );
+
+    // Yield to let internal event loops settle
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    let currentView = this.contextManager.getNodes();
+    const currentTokens =
+      this.env.tokenCalculator.calculateConcreteListTokens(currentView);
+    if (
+      this.config.config.budget &&
+      currentTokens > this.config.config.budget.maxTokens
+    ) {
+      debugLogger.log(
+        `[Turn ${this.currentTurnIndex}] Sync panic triggered! ${currentTokens} > ${this.config.config.budget.maxTokens}`,
+      );
+      
+      const modifiedView = await this.contextManager.executeTriggerSync(
+        'gc_backstop',
+        currentView,
+        new Set(currentView.map((e) => e.id)),
+        new Set<string>(),
+      );
+
+      currentView = modifiedView;
+    }
+
+    const tokensAfter = this.env.tokenCalculator.calculateConcreteListTokens(
+      this.contextManager.getNodes(),
+    );
+    debugLogger.log(
+      `[Turn ${this.currentTurnIndex}] Tokens AFTER: ${tokensAfter}`,
+    );
+
+    this.tokenTrajectory.push({
+      turnIndex: this.currentTurnIndex++,
+      tokensBeforeBackground: tokensBefore,
+      tokensAfterBackground: tokensAfter,
+    });
+  }
+
+  async getGoldenState() {
+    const finalProjection =
+      await this.contextManager.projectCompressedHistory();
+    return {
+      tokenTrajectory: this.tokenTrajectory,
+      finalProjection,
+    };
+  }
+}

packages/core/src/context/system/DeterministicIdGenerator.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { IIdGenerator } from './IIdGenerator.js';
+
+export class DeterministicIdGenerator implements IIdGenerator {
+  private counter = 0;
+
+  constructor(private prefix: string = 'id-') {}
+
+  generateId(): string {
+    this.counter++;
+    return `${this.prefix}${this.counter}`;
+  }
+}

packages/core/src/context/system/IFileSystem.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface IFileSystem {
+  existsSync(path: string): boolean;
+  statSyncSize(path: string): number;
+  readFileSync(path: string, encoding: 'utf8'): string;
+  writeFileSync(path: string, data: string | Buffer, encoding?: 'utf-8'): void;
+  appendFileSync(path: string, data: string, encoding: 'utf-8'): void;
+  mkdirSync(path: string, options?: { recursive?: boolean }): void;
+
+  writeFile(path: string, data: string | Buffer): Promise<void>;
+  mkdir(path: string, options?: { recursive?: boolean }): Promise<void>;
+
+  join(...paths: string[]): string;
+  dirname(path: string): string;
+}

packages/core/src/context/system/IIdGenerator.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface IIdGenerator {
+  generateId(): string;
+}

packages/core/src/context/system/InMemoryFileSystem.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { IFileSystem } from './IFileSystem.js';
+
+export class InMemoryFileSystem implements IFileSystem {
+  private files = new Map<string, string | Buffer>();
+
+  getFiles(): ReadonlyMap<string, string | Buffer> {
+    return this.files;
+  }
+
+  setFile(path: string, content: string | Buffer) {
+    this.files.set(this.normalize(path), content);
+  }
+
+  private normalize(p: string): string {
+    return p.replace(/\/+/g, '/');
+  }
+
+  existsSync(p: string): boolean {
+    return this.files.has(this.normalize(p));
+  }
+
+  statSyncSize(p: string): number {
+    const content = this.files.get(this.normalize(p));
+    if (content === undefined) {
+      throw new Error(`ENOENT: no such file or directory, stat '${p}'`);
+    }
+    return Buffer.isBuffer(content)
+      ? content.byteLength
+      : Buffer.byteLength(content, 'utf8');
+  }
+
+  readFileSync(p: string, encoding: 'utf8'): string {
+    const content = this.files.get(this.normalize(p));
+    if (content === undefined) {
+      throw new Error(`ENOENT: no such file or directory, open '${p}'`);
+    }
+    if (Buffer.isBuffer(content)) {
+      return content.toString(encoding);
+    }
+    return content;
+  }
+
+  writeFileSync(p: string, data: string | Buffer, _encoding?: 'utf-8'): void {
+    this.files.set(this.normalize(p), data);
+  }
+
+  appendFileSync(p: string, data: string, _encoding: 'utf-8'): void {
+    const norm = this.normalize(p);
+    const existing = this.files.get(norm) || '';
+    const existingStr = Buffer.isBuffer(existing)
+      ? existing.toString('utf8')
+      : existing;
+    this.files.set(norm, existingStr + data);
+  }
+
+  mkdirSync(_p: string, _options?: { recursive?: boolean }): void {}
+
+  async writeFile(p: string, data: string | Buffer): Promise<void> {
+    this.writeFileSync(p, data);
+  }
+
+  async mkdir(_p: string, _options?: { recursive?: boolean }): Promise<void> {}
+
+  join(...paths: string[]): string {
+    return this.normalize(paths.join('/'));
+  }
+
+  dirname(p: string): string {
+    const parts = this.normalize(p).split('/');
+    parts.pop();
+    return parts.length === 0 ? '.' : parts.join('/') || '/';
+  }
+}

packages/core/src/context/system/NodeFileSystem.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as fsPromises from 'node:fs/promises';
+import * as path from 'node:path';
+import type { IFileSystem } from './IFileSystem.js';
+
+export class NodeFileSystem implements IFileSystem {
+  existsSync(p: string): boolean {
+    return fs.existsSync(p);
+  }
+
+  statSyncSize(p: string): number {
+    return fs.statSync(p).size;
+  }
+
+  readFileSync(p: string, encoding: 'utf8'): string {
+    return fs.readFileSync(p, encoding);
+  }
+
+  writeFileSync(p: string, data: string | Buffer, encoding?: 'utf-8'): void {
+    if (Buffer.isBuffer(data)) {
+      fs.writeFileSync(p, data);
+    } else {
+      fs.writeFileSync(p, data, encoding);
+    }
+  }
+
+  appendFileSync(p: string, data: string, encoding: 'utf-8'): void {
+    fs.appendFileSync(p, data, encoding);
+  }
+
+  mkdirSync(p: string, options?: { recursive?: boolean }): void {
+    fs.mkdirSync(p, options);
+  }
+
+  async writeFile(p: string, data: string | Buffer): Promise<void> {
+    await fsPromises.writeFile(p, data);
+  }
+
+  async mkdir(p: string, options?: { recursive?: boolean }): Promise<void> {
+    await fsPromises.mkdir(p, options);
+  }
+
+  join(...paths: string[]): string {
+    return path.join(...paths);
+  }
+
+  dirname(p: string): string {
+    return path.dirname(p);
+  }
+}

packages/core/src/context/system/NodeIdGenerator.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { IIdGenerator } from './IIdGenerator.js';
+
+export class NodeIdGenerator implements IIdGenerator {
+  generateId(): string {
+    return randomUUID();
+  }
+}

packages/core/src/context/testing/contextTestUtils.ts

@@ -0,0 +1,256 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { vi } from 'vitest';
+import { AgentChatHistory } from '../../core/agentChatHistory.js';
+import { ContextManager } from '../contextManager.js';
+import { InMemoryFileSystem } from '../system/InMemoryFileSystem.js';
+import { DeterministicIdGenerator } from '../system/DeterministicIdGenerator.js';
+import { randomUUID } from 'node:crypto';
+import { ContextTracer } from '../tracer.js';
+import { ContextEnvironmentImpl } from '../pipeline/environmentImpl.js';
+import { SidecarLoader } from '../config/configLoader.js';
+import { SidecarRegistry } from '../config/registry.js';
+import type { ConcreteNode, ToolExecution } from '../ir/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import type { Config } from '../../config/config.js';
+import type { BaseLlmClient } from '../../core/baseLlmClient.js';
+import type { Content, GenerateContentResponse } from '@google/genai';
+import type { SnapshotProposal, ProcessArgs } from '../pipeline.js';
+import type { ContextProfile } from '../config/profiles.js';
+import type { Mock } from 'vitest';
+import { LiveSnapshotCache } from '../pipeline/snapshotCache.js';
+import { ContextWorkingBufferImpl } from '../pipeline/contextWorkingBuffer.js';
+
+export const createMockGenerateContentResponse = (
+  text: string,
+): GenerateContentResponse =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  ({
+    candidates: [{ content: { role: 'model', parts: [{ text }] }, index: 0 }],
+  }) as GenerateContentResponse;
+
+export function createDummyNode(
+  logicalParentId: string,
+  type: ConcreteNode['type'],
+  tokens = 100,
+  overrides?: Partial<ConcreteNode>,
+  id?: string,
+): ConcreteNode {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return {
+    id: id || randomUUID(),
+    episodeId: logicalParentId,
+    logicalParentId,
+    type,
+    timestamp: Date.now(),
+    text: `Dummy ${type}`,
+    name: type === 'SYSTEM_EVENT' ? 'dummy_event' : undefined,
+    payload: type === 'SYSTEM_EVENT' ? {} : undefined,
+    semanticParts: [],
+    metadata: {
+      originalTokens: tokens,
+      currentTokens: tokens,
+      transformations: [],
+    },
+    ...overrides,
+  } as unknown as ConcreteNode;
+}
+
+export function createDummyToolNode(
+  logicalParentId: string,
+  intentTokens = 100,
+  obsTokens = 200,
+  overrides?: Partial<ToolExecution>,
+  id?: string,
+): ToolExecution {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return {
+    id: id || randomUUID(),
+    episodeId: logicalParentId,
+    logicalParentId,
+    type: 'TOOL_EXECUTION',
+    timestamp: Date.now(),
+    toolName: 'dummy_tool',
+    intent: { action: 'test' },
+    observation: { result: 'ok' },
+    tokens: {
+      intent: intentTokens,
+      observation: obsTokens,
+    },
+    metadata: {
+      originalTokens: intentTokens + obsTokens,
+      currentTokens: intentTokens + obsTokens,
+      transformations: [],
+    },
+    ...overrides,
+  } as unknown as ToolExecution;
+}
+
+export interface MockLlmClient extends BaseLlmClient {
+  generateContent: Mock;
+}
+
+export function createMockLlmClient(
+  responses?: Array<string | GenerateContentResponse>,
+): MockLlmClient {
+  const generateContentMock = vi.fn();
+
+  if (responses && responses.length > 0) {
+    for (const response of responses) {
+      if (typeof response === 'string') {
+        generateContentMock.mockResolvedValueOnce(
+          createMockGenerateContentResponse(response),
+        );
+      } else {
+        generateContentMock.mockResolvedValueOnce(response);
+      }
+    }
+    const lastResponse = responses[responses.length - 1];
+    if (typeof lastResponse === 'string') {
+      generateContentMock.mockResolvedValue(
+        createMockGenerateContentResponse(lastResponse),
+      );
+    } else {
+      generateContentMock.mockResolvedValue(lastResponse);
+    }
+  } else {
+    generateContentMock.mockResolvedValue(
+      createMockGenerateContentResponse('Mock LLM response'),
+    );
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return {
+    generateContent: generateContentMock,
+  } as unknown as MockLlmClient;
+}
+
+export function createMockEnvironment(
+  overrides?: Partial<ContextEnvironment>,
+): ContextEnvironment {
+  const llmClient = createMockLlmClient(['Mock LLM summary response']);
+
+  const tracer = new ContextTracer({
+    targetDir: '/tmp',
+    sessionId: 'mock-session',
+  });
+
+  const env = new ContextEnvironmentImpl(
+    llmClient,
+    'mock-session',
+    'mock-prompt-id',
+    '/tmp/.gemini/trace',
+    '/tmp/.gemini/tool-outputs',
+    tracer,
+    1,
+    new InMemoryFileSystem(),
+    new DeterministicIdGenerator('mock-uuid-'),
+  );
+
+  if (overrides) {
+    Object.assign(env, overrides);
+  }
+  return env;
+}
+
+export function createMockProcessArgs(
+  targets: ConcreteNode[],
+  bufferNodes: ConcreteNode[] = [],
+  proposals: SnapshotProposal[] = [],
+): ProcessArgs {
+  const cache = new LiveSnapshotCache();
+  // We can just manually add the proposals for the mock
+  for (const p of proposals) {
+    (cache as any).proposals.push(p);
+  }
+
+  return {
+    targets,
+    buffer: ContextWorkingBufferImpl.initialize(
+      bufferNodes.length ? bufferNodes : targets,
+    ),
+    snapshotCache: cache,
+  };
+}
+
+export function createSyntheticHistory(
+  numTurns: number,
+  tokensPerTurn: number,
+): Content[] {
+  const history: Content[] = [];
+  const charsPerTurn = tokensPerTurn * 1;
+
+  for (let i = 0; i < numTurns; i++) {
+    history.push({
+      role: 'user',
+      parts: [{ text: `User turn ${i}. ` + 'A'.repeat(charsPerTurn) }],
+    });
+    history.push({
+      role: 'model',
+      parts: [{ text: `Model response ${i}. ` + 'B'.repeat(charsPerTurn) }],
+    });
+  }
+
+  return history;
+}
+
+export function createMockContextConfig(
+  overrides?: Record<string, unknown>,
+  llmClientOverride?: unknown,
+): Config {
+  const defaultConfig = {
+    isContextManagementEnabled: vi.fn().mockReturnValue(true),
+    storage: {
+      getProjectTempDir: vi.fn().mockReturnValue('/tmp/gemini-test'),
+    },
+    getBaseLlmClient: vi.fn().mockReturnValue(
+      llmClientOverride || {
+        generateContent: vi.fn().mockResolvedValue({
+          text: '<mocked_snapshot>Synthesized state</mocked_snapshot>',
+        }),
+      },
+    ),
+    getUsageStatisticsEnabled: vi.fn().mockReturnValue(false),
+    getTargetDir: vi.fn().mockReturnValue('/tmp'),
+    getSessionId: vi.fn().mockReturnValue('test-session'),
+    getExperimentalContextManagementConfig: vi.fn().mockReturnValue(undefined),
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return { ...defaultConfig, ...overrides } as unknown as Config;
+}
+
+export function setupContextComponentTest(
+  config: Config,
+  sidecarOverride?: ContextProfile,
+): { chatHistory: AgentChatHistory; contextManager: ContextManager } {
+  const chatHistory = new AgentChatHistory();
+  const registry = new SidecarRegistry();
+  const sidecar = sidecarOverride || SidecarLoader.fromConfig(config, registry);
+  const tracer = new ContextTracer({
+    targetDir: '/tmp',
+    sessionId: 'test-session',
+  });
+  const env = new ContextEnvironmentImpl(
+    config.getBaseLlmClient(),
+    'test prompt-id',
+    'test-session',
+    '/tmp',
+    '/tmp/gemini-test',
+    tracer,
+    1,
+  );
+
+  const contextManager = new ContextManager(
+    sidecar,
+    env,
+    tracer,
+    chatHistory,
+  );
+
+  return { chatHistory, contextManager };
+}

packages/core/src/context/testing/testProfile.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ContextProfile } from '../config/profiles.js';
+import type { PipelineDef } from '../config/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { createHistoryTruncationProcessor } from '../processors/historyTruncationProcessor.js';
+
+export const testTruncateProfile: ContextProfile = {
+  config: {
+    budget: {
+      retainedTokens: 65000,
+      maxTokens: 150000,
+    },
+  },
+  buildPipelines: (env: ContextEnvironment): PipelineDef[] => [
+    {
+      name: 'Emergency Backstop (Truncate Only)',
+      triggers: ['gc_backstop', 'retained_exceeded'],
+      processors: [
+        createHistoryTruncationProcessor('HistoryTruncation', env, {}),
+      ],
+    },
+  ],
+  buildAsyncPipelines: () => [],
+};

packages/core/src/context/tracer.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ContextTracer } from './tracer.js';
+import { InMemoryFileSystem } from './system/InMemoryFileSystem.js';
+import { DeterministicIdGenerator } from './system/DeterministicIdGenerator.js';
+
+describe('ContextTracer (Fake FS & ID Gen)', () => {
+  let fileSystem: InMemoryFileSystem;
+  let idGenerator: DeterministicIdGenerator;
+
+  beforeEach(() => {
+    fileSystem = new InMemoryFileSystem();
+    idGenerator = new DeterministicIdGenerator('mock-uuid-');
+
+    // We must mock Date.now() to ensure asset file names are perfectly deterministic
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-01-01T12:00:00Z'));
+  });
+
+  it('initializes, logs events, and auto-saves large assets deterministically', () => {
+    const tracer = new ContextTracer(
+      { enabled: true, targetDir: '/fake/target', sessionId: 'test-session' },
+      fileSystem,
+      idGenerator,
+    );
+
+    // Verify Initialization
+    const initTraceLog = fileSystem.readFileSync(
+      '/fake/target/.gemini/context_trace/test-session/trace.log',
+      'utf8',
+    );
+    expect(initTraceLog).toContain('[SYSTEM] Context Tracer Initialized');
+
+    // Small logging: shouldn't trigger saveAsset
+    tracer.logEvent('TestComponent', 'TestAction', { key: 'value' });
+
+    const smallTraceLog = fileSystem.readFileSync(
+      '/fake/target/.gemini/context_trace/test-session/trace.log',
+      'utf8',
+    );
+    expect(smallTraceLog).toContain('[TestComponent] TestAction');
+    expect(smallTraceLog).toContain('{"key":"value"}');
+
+    // Large logging: should trigger auto-asset save
+    const hugeString = 'a'.repeat(2000);
+    tracer.logEvent('TestComponent', 'LargeAction', { largeKey: hugeString });
+
+    // 1767268800000 is 2026-01-01T12:00:00Z
+    const expectedAssetPath =
+      '/fake/target/.gemini/context_trace/test-session/assets/1767268800000-mock-uuid-1-largeKey.json';
+
+    // Assert asset was written to FS
+    expect(fileSystem.existsSync(expectedAssetPath)).toBe(true);
+
+    const largeTraceLog = fileSystem.readFileSync(
+      '/fake/target/.gemini/context_trace/test-session/trace.log',
+      'utf8',
+    );
+    expect(largeTraceLog).toContain('[TestComponent] LargeAction');
+    expect(largeTraceLog).toContain(
+      `{"largeKey":{"$asset":"1767268800000-mock-uuid-1-largeKey.json"}}`,
+    );
+  });
+
+  it('silently ignores logging when disabled', () => {
+    const tracer = new ContextTracer(
+      { enabled: false, targetDir: '/fake/target', sessionId: 'test-session' },
+      fileSystem,
+      idGenerator,
+    );
+
+    tracer.logEvent('TestComponent', 'TestAction');
+
+    const hugeString = 'a'.repeat(2000);
+    tracer.logEvent('TestComponent', 'LargeAction', { largeKey: hugeString });
+
+    // FS should be completely empty
+    expect(fileSystem.getFiles().size).toBe(0);
+  });
+});

packages/core/src/context/tracer.ts

@@ -0,0 +1,120 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { debugLogger } from '../utils/debugLogger.js';
+import type { IFileSystem } from './system/IFileSystem.js';
+import { NodeFileSystem } from './system/NodeFileSystem.js';
+import type { IIdGenerator } from './system/IIdGenerator.js';
+import { NodeIdGenerator } from './system/NodeIdGenerator.js';
+
+export interface ContextTracerOptions {
+  enabled?: boolean;
+  targetDir: string;
+  sessionId: string;
+}
+
+export class ContextTracer {
+  private traceDir: string;
+  private assetsDir: string;
+  private enabled: boolean;
+  private fileSystem: IFileSystem;
+  private idGenerator: IIdGenerator;
+
+  private readonly MAX_INLINE_SIZE = 1000;
+
+  constructor(
+    options: ContextTracerOptions,
+    fileSystem: IFileSystem = new NodeFileSystem(),
+    idGenerator: IIdGenerator = new NodeIdGenerator(),
+  ) {
+    this.enabled = options.enabled ?? false;
+    this.fileSystem = fileSystem;
+    this.idGenerator = idGenerator;
+
+    this.traceDir = this.fileSystem.join(
+      options.targetDir,
+      '.gemini',
+      'context_trace',
+      options.sessionId,
+    );
+    this.assetsDir = this.fileSystem.join(this.traceDir, 'assets');
+
+    if (this.enabled) {
+      try {
+        this.fileSystem.mkdirSync(this.assetsDir, { recursive: true });
+        this.logEvent('SYSTEM', 'Context Tracer Initialized', {
+          sessionId: options.sessionId,
+        });
+      } catch (e) {
+        debugLogger.error('Failed to initialize ContextTracer', e);
+        this.enabled = false;
+      }
+    }
+  }
+
+  logEvent(
+    component: string,
+    action: string,
+    details?: Record<string, unknown>,
+  ) {
+    if (!this.enabled) return;
+    try {
+      let processedDetails: Record<string, unknown> | undefined;
+
+      if (details) {
+        processedDetails = {};
+        for (const [key, value] of Object.entries(details)) {
+          const strValue =
+            typeof value === 'string' ? value : JSON.stringify(value);
+          if (strValue && strValue.length > this.MAX_INLINE_SIZE) {
+            const assetId = this.saveAsset(component, key, value);
+            processedDetails[key] = { $asset: assetId };
+          } else {
+            processedDetails[key] = value;
+          }
+        }
+      }
+
+      const timestamp = new Date().toISOString();
+      const detailsStr = processedDetails
+        ? ` | Details: ${JSON.stringify(processedDetails)}`
+        : '';
+      const logLine = `[${timestamp}] [${component}] ${action}${detailsStr}\n`;
+      this.fileSystem.appendFileSync(
+        this.fileSystem.join(this.traceDir, 'trace.log'),
+        logLine,
+        'utf-8',
+      );
+    } catch (e) {
+      debugLogger.warn(`Tracing failed: ${e}`);
+    }
+  }
+
+  private saveAsset(
+    component: string,
+    assetName: string,
+    data: unknown,
+  ): string {
+    if (!this.enabled) return 'asset-recording-disabled';
+    try {
+      const assetId = `${Date.now()}-${this.idGenerator.generateId()}-${assetName}.json`;
+      const assetPath = this.fileSystem.join(this.assetsDir, assetId);
+
+      this.fileSystem.writeFileSync(
+        assetPath,
+        JSON.stringify(data, null, 2),
+        'utf-8',
+      );
+      this.logEvent(component, `Saved asset: ${assetName}`, { assetId });
+      return assetId;
+    } catch (e) {
+      this.logEvent(component, `Failed to save asset: ${assetName}`, {
+        error: String(e),
+      });
+      return 'asset-save-failed';
+    }
+  }
+}

packages/core/src/context/utils/contextTokenCalculator.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Part } from '@google/genai';
+import { estimateTokenCountSync as baseEstimate } from '../../utils/tokenCalculation.js';
+import type { ConcreteNode } from '../ir/types.js';
+import type { IrNodeBehaviorRegistry } from '../ir/behaviorRegistry.js';
+
+/**
+ * The flat token cost assigned to a single multi-modal asset (like an image tile)
+ * by the Gemini API. We use this as a baseline heuristic for inlineData/fileData.
+ */
+
+export class ContextTokenCalculator {
+  private readonly tokenCache = new Map<string, number>();
+
+  constructor(
+    private readonly charsPerToken: number,
+    private readonly registry: IrNodeBehaviorRegistry,
+  ) {}
+
+  /**
+   * Estimates tokens for a simple string based on character count.
+   * Fast, but inherently inaccurate compared to real model tokenization.
+   */
+  estimateTokensForString(text: string): number {
+    return Math.ceil(text.length / this.charsPerToken);
+  }
+
+  /**
+   * Fast, simple heuristic conversion from tokens to expected character length.
+   * Useful for calculating truncation thresholds.
+   */
+  tokensToChars(tokens: number): number {
+    return tokens * this.charsPerToken;
+  }
+
+  /**
+   * Pre-calculates and caches the token cost of a newly minted node.
+   * Because nodes are immutable, this cost never changes for this node ID.
+   */
+  cacheNodeTokens(node: ConcreteNode): number {
+    const behavior = this.registry.get(node.type);
+    const parts = behavior.getEstimatableParts(node);
+    const tokens = this.estimateTokensForParts(parts);
+    this.tokenCache.set(node.id, tokens);
+    return tokens;
+  }
+
+  /**
+   * Retrieves the token cost of a single node from the cache.
+   * If it misses the cache, it computes it and caches it.
+   */
+  getTokenCost(node: ConcreteNode): number {
+    const cached = this.tokenCache.get(node.id);
+    if (cached !== undefined) return cached;
+    return this.cacheNodeTokens(node);
+  }
+
+  /**
+   * Fast calculation for a flat array of ConcreteNodes (The Nodes).
+   * It relies entirely on the O(1) sidecar token cache.
+   */
+  calculateConcreteListTokens(nodes: readonly ConcreteNode[]): number {
+    let tokens = 0;
+    for (const node of nodes) {
+      tokens += this.getTokenCost(node);
+    }
+    return tokens;
+  }
+  /**
+   * Slower, precise estimation for a Gemini Content/Part graph.
+   * Deeply inspects the nested structure and uses the base tokenization math.
+   */
+  estimateTokensForParts(parts: Part[], depth: number = 0): number {
+    let totalTokens = 0;
+    for (const part of parts) {
+      if (typeof part.text === 'string') {
+        totalTokens += Math.ceil(part.text.length / this.charsPerToken);
+      } else if (part.inlineData !== undefined || part.fileData !== undefined) {
+        totalTokens += 258;
+      } else {
+        totalTokens += Math.ceil(
+          JSON.stringify(part).length / this.charsPerToken,
+        );
+      }
+    }
+    // Also include structural overhead
+    return totalTokens + baseEstimate(parts, depth);
+  }
+}

packages/core/src/context/utils/snapshotGenerator.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ConcreteNode } from '../ir/types.js';
+import type { ContextEnvironment } from '../pipeline/environment.js';
+import { LlmRole } from '../../telemetry/llmRole.js';
+
+export class SnapshotGenerator {
+  constructor(private readonly env: ContextEnvironment) {}
+
+  async synthesizeSnapshot(
+    nodes: readonly ConcreteNode[],
+    systemInstruction?: string,
+  ): Promise<string> {
+    const systemPrompt =
+      systemInstruction ??
+      `You are an expert Context Memory Manager. You will be provided with a raw transcript of older conversation turns between a user and an AI assistant.
+Your task is to synthesize these turns into a single, dense, factual snapshot that preserves all critical context, preferences, active tasks, and factual knowledge, but discards conversational filler, pleasantries, and redundant back-and-forth iterations.
+
+Output ONLY the raw factual snapshot, formatted compactly. Do not include markdown wrappers, prefixes like "Here is the snapshot", or conversational elements.`;
+
+    let userPromptText = 'TRANSCRIPT TO SNAPSHOT:\n\n';
+    for (const node of nodes) {
+      let nodeContent = '';
+      if ('text' in node && typeof node.text === 'string') {
+        nodeContent = node.text;
+      } else if ('semanticParts' in node) {
+        nodeContent = JSON.stringify(node.semanticParts);
+      } else if ('observation' in node) {
+        nodeContent =
+          typeof node.observation === 'string'
+            ? node.observation
+            : JSON.stringify(node.observation);
+      }
+
+      userPromptText += `[${node.type}]: ${nodeContent}\n`;
+    }
+
+    const response = await this.env.llmClient.generateContent({
+      role: LlmRole.UTILITY_STATE_SNAPSHOT_PROCESSOR,
+      modelConfigKey: { model: 'gemini-3-flash-base' },
+      contents: [{ role: 'user', parts: [{ text: userPromptText }] }],
+      systemInstruction: { role: 'system', parts: [{ text: systemPrompt }] },
+      promptId: this.env.promptId,
+      abortSignal: new AbortController().signal,
+    });
+
+    const candidate = response.candidates?.[0];
+    const textPart = candidate?.content?.parts?.[0];
+    return textPart?.text || '';
+  }
+}

packages/core/src/core/agentChatHistory.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Content } from '@google/genai';
+
+export type HistoryEventType = 'PUSH' | 'SYNC_FULL' | 'CLEAR';
+
+export interface HistoryEvent {
+  type: HistoryEventType;
+  payload: readonly Content[];
+}
+
+export type HistoryListener = (event: HistoryEvent) => void;
+
+export class AgentChatHistory {
+  private history: Content[];
+  private listeners: Set<HistoryListener> = new Set();
+
+  constructor(initialHistory: Content[] = []) {
+    this.history = [...initialHistory];
+  }
+
+  subscribe(listener: HistoryListener): () => void {
+    this.listeners.add(listener);
+    // Emit initial state to new subscriber
+    listener({ type: 'SYNC_FULL', payload: this.history });
+    return () => this.listeners.delete(listener);
+  }
+
+  private notify(type: HistoryEventType, payload: readonly Content[]) {
+    const event: HistoryEvent = { type, payload };
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+
+  push(content: Content) {
+    this.history.push(content);
+    this.notify('PUSH', [content]);
+  }
+
+  set(history: readonly Content[]) {
+    this.history = [...history];
+    this.notify('SYNC_FULL', this.history);
+  }
+
+  clear() {
+    this.history = [];
+    this.notify('CLEAR', []);
+  }
+
+  get(): readonly Content[] {
+    return this.history;
+  }
+
+  map(callback: (value: Content, index: number, array: Content[]) => Content) {
+    this.history = this.history.map(callback);
+    this.notify('SYNC_FULL', this.history);
+  }
+
+  flatMap<U>(
+    callback: (
+      value: Content,
+      index: number,
+      array: Content[],
+    ) => U | readonly U[],
+  ): U[] {
+    return this.history.flatMap(callback);
+  }
+
+  get length(): number {
+    return this.history.length;
+  }
+}

packages/core/src/telemetry/llmRole.ts

@@ -16,4 +16,5 @@ export enum LlmRole {
   UTILITY_EDIT_CORRECTOR = 'utility_edit_corrector',
   UTILITY_AUTOCOMPLETE = 'utility_autocomplete',
   UTILITY_FAST_ACK_HELPER = 'utility_fast_ack_helper',
+  UTILITY_STATE_SNAPSHOT_PROCESSOR = 'utility_state_snapshot_processor',
 }