feat(core): introduce decoupled ContextManager and Sidecar architecture

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,94 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadContextManagementConfig } from './configLoader.js';
+import { defaultContextProfile } from './profiles.js';
+import { ContextProcessorRegistry } from './registry.js';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import type { Config } from '../../config/config.js';
+import type { JSONSchemaType } from 'ajv';
+
+describe('SidecarLoader (Real FS)', () => {
+  let tmpDir: string;
+  let registry: ContextProcessorRegistry;
+  let sidecarPath: string;
+  let mockConfig: Config;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gemini-sidecar-test-'));
+    sidecarPath = path.join(tmpDir, 'sidecar.json');
+    registry = new ContextProcessorRegistry();
+    registry.registerProcessor({
+      id: 'NodeTruncation',
+      schema: {
+        type: 'object',
+        properties: { maxTokens: { type: 'number' } },
+        required: ['maxTokens'],
+      } as unknown as JSONSchemaType<{ maxTokens: number }>,
+    });
+
+    mockConfig = {
+      getExperimentalContextManagementConfig: () => sidecarPath,
+    } as unknown as Config;
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('returns default profile if file does not exist', async () => {
+    const result = await loadContextManagementConfig(mockConfig, registry);
+    expect(result).toBe(defaultContextProfile);
+  });
+
+  it('returns default profile if file exists but is 0 bytes', async () => {
+    await fs.writeFile(sidecarPath, '');
+    const result = await loadContextManagementConfig(mockConfig, registry);
+    expect(result).toBe(defaultContextProfile);
+  });
+
+  it('returns parsed config if file is valid', async () => {
+    const validConfig = {
+      budget: { retainedTokens: 1000, maxTokens: 2000 },
+      processorOptions: {
+        myTruncation: {
+          type: 'NodeTruncation',
+          options: { maxTokens: 500 },
+        },
+      },
+    };
+    await fs.writeFile(sidecarPath, JSON.stringify(validConfig));
+    const result = await loadContextManagementConfig(mockConfig, registry);
+    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', async () => {
+    const invalidConfig = {
+      budget: { retainedTokens: 1000, maxTokens: 2000 },
+      processorOptions: {
+        myTruncation: {
+          type: 'NodeTruncation',
+          options: { maxTokens: 'this should be a number' },
+        },
+      },
+    };
+    await fs.writeFile(sidecarPath, JSON.stringify(invalidConfig));
+    await expect(
+      loadContextManagementConfig(mockConfig, registry),
+    ).rejects.toThrow('Validation error');
+  });
+
+  it('throws validation error if file is empty whitespace', async () => {
+    await fs.writeFile(sidecarPath, '   \n  ');
+    await expect(
+      loadContextManagementConfig(mockConfig, registry),
+    ).rejects.toThrow('Unexpected end of JSON input');
+  });
+});

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

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Config } from '../../config/config.js';
+import * as fsSync from 'node:fs';
+import * as fs from 'node:fs/promises';
+import type { ContextManagementConfig } from './types.js';
+import { defaultContextProfile, type ContextProfile } from './profiles.js';
+import { SchemaValidator } from '../../utils/schemaValidator.js';
+import { getContextManagementConfigSchema } from './schema.js';
+import type { ContextProcessorRegistry } from './registry.js';
+import { getErrorMessage } from '../../utils/errors.js';
+
+/**
+ * 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.
+ */
+async function loadConfigFromFile(
+  sidecarPath: string,
+  registry: ContextProcessorRegistry,
+): Promise<ContextProfile> {
+  const fileContent = await fs.readFile(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(
+    getContextManagementConfigSchema(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 ContextManagementConfig;
+  return {
+    ...defaultContextProfile,
+    config: {
+      ...defaultContextProfile.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.
+ */
+export async function loadContextManagementConfig(
+  config: Config,
+  registry: ContextProcessorRegistry,
+): Promise<ContextProfile> {
+  const sidecarPath = config.getExperimentalContextManagementConfig();
+
+  if (sidecarPath && fsSync.existsSync(sidecarPath)) {
+    const size = fsSync.statSync(sidecarPath).size;
+    // If the file exists but is completely empty (0 bytes), it's safe to fallback.
+    if (size === 0) {
+      return defaultContextProfile;
+    }
+
+    // If the file has content, enforce strict validation and throw on failure.
+    return loadConfigFromFile(sidecarPath, registry);
+  }
+
+  return defaultContextProfile;
+}

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

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+  AsyncPipelineDef,
+  ContextManagementConfig,
+  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: ContextManagementConfig | 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: ContextManagementConfig;
+  buildPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ) => PipelineDef[];
+  buildAsyncPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ) => AsyncPipelineDef[];
+}
+
+/**
+ * The standard default context management profile.
+ * Optimized for safety, precision, and reliable summarization.
+ */
+export const defaultContextProfile: ContextProfile = {
+  config: {
+    budget: {
+      retainedTokens: 65000,
+      maxTokens: 150000,
+    },
+  },
+
+  buildPipelines: (
+    env: ContextEnvironment,
+    config?: ContextManagementConfig,
+  ): 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?: ContextManagementConfig,
+  ): AsyncPipelineDef[] => [
+    {
+      name: 'Async Background GC',
+      triggers: ['nodes_aged_out'],
+      processors: [
+        createStateSnapshotAsyncProcessor(
+          'StateSnapshotAsync',
+          env,
+          resolveProcessorOptions(config, 'StateSnapshotAsync', {
+            type: 'accumulate',
+          }),
+        ),
+      ],
+    },
+  ],
+};