refactor(core): introduce InjectionService with source-aware injection and backend-native background completions (#22544)

packages/core/src/config/config.ts

@@ -151,7 +151,8 @@ import { startupProfiler } from '../telemetry/startupProfiler.js';
 import type { AgentDefinition } from '../agents/types.js';
 import { fetchAdminControls } from '../code_assist/admin/admin_controls.js';
 import { isSubpath, resolveToRealPath } from '../utils/paths.js';
-import { UserHintService } from './userHintService.js';
+import { InjectionService } from './injectionService.js';
+import { ExecutionLifecycleService } from '../services/executionLifecycleService.js';
 import { WORKSPACE_POLICY_TIER } from '../policy/config.js';
 import { loadPoliciesFromToml } from '../policy/toml-loader.js';
 
@@ -856,7 +857,7 @@ export class Config implements McpContext, AgentLoopContext {
   private remoteAdminSettings: AdminControlsSettings | undefined;
   private latestApiRequest: GenerateContentParameters | undefined;
   private lastModeSwitchTime: number = performance.now();
-  readonly userHintService: UserHintService;
+  readonly injectionService: InjectionService;
   private approvedPlanPath: string | undefined;
 
   constructor(params: ConfigParameters) {
@@ -996,9 +997,10 @@ export class Config implements McpContext, AgentLoopContext {
     this.experimentalJitContext = params.experimentalJitContext ?? false;
     this.topicUpdateNarration = params.topicUpdateNarration ?? false;
     this.modelSteering = params.modelSteering ?? false;
-    this.userHintService = new UserHintService(() =>
+    this.injectionService = new InjectionService(() =>
       this.isModelSteeringEnabled(),
     );
+    ExecutionLifecycleService.setInjectionService(this.injectionService);
     this.toolOutputMasking = {
       enabled: params.toolOutputMasking?.enabled ?? true,
       toolProtectionThreshold:

packages/core/src/config/injectionService.test.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { InjectionService } from './injectionService.js';
+
+describe('InjectionService', () => {
+  it('is disabled by default and ignores user_steering injections', () => {
+    const service = new InjectionService(() => false);
+    service.addInjection('this hint should be ignored', 'user_steering');
+    expect(service.getInjections()).toEqual([]);
+    expect(service.getLatestInjectionIndex()).toBe(-1);
+  });
+
+  it('stores trimmed injections and exposes them via indexing when enabled', () => {
+    const service = new InjectionService(() => true);
+
+    service.addInjection('  first hint  ', 'user_steering');
+    service.addInjection('second hint', 'user_steering');
+    service.addInjection('   ', 'user_steering');
+
+    expect(service.getInjections()).toEqual(['first hint', 'second hint']);
+    expect(service.getLatestInjectionIndex()).toBe(1);
+    expect(service.getInjectionsAfter(-1)).toEqual([
+      'first hint',
+      'second hint',
+    ]);
+    expect(service.getInjectionsAfter(0)).toEqual(['second hint']);
+    expect(service.getInjectionsAfter(1)).toEqual([]);
+  });
+
+  it('notifies listeners when an injection is added', () => {
+    const service = new InjectionService(() => true);
+    const listener = vi.fn();
+    service.onInjection(listener);
+
+    service.addInjection('new hint', 'user_steering');
+
+    expect(listener).toHaveBeenCalledWith('new hint', 'user_steering');
+  });
+
+  it('does NOT notify listeners after they are unregistered', () => {
+    const service = new InjectionService(() => true);
+    const listener = vi.fn();
+    service.onInjection(listener);
+    service.offInjection(listener);
+
+    service.addInjection('ignored hint', 'user_steering');
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('should clear all injections', () => {
+    const service = new InjectionService(() => true);
+    service.addInjection('hint 1', 'user_steering');
+    service.addInjection('hint 2', 'user_steering');
+    expect(service.getInjections()).toHaveLength(2);
+
+    service.clear();
+    expect(service.getInjections()).toHaveLength(0);
+    expect(service.getLatestInjectionIndex()).toBe(-1);
+  });
+
+  describe('source-specific behavior', () => {
+    it('notifies listeners with source for user_steering', () => {
+      const service = new InjectionService(() => true);
+      const listener = vi.fn();
+      service.onInjection(listener);
+
+      service.addInjection('steering hint', 'user_steering');
+
+      expect(listener).toHaveBeenCalledWith('steering hint', 'user_steering');
+    });
+
+    it('notifies listeners with source for background_completion', () => {
+      const service = new InjectionService(() => true);
+      const listener = vi.fn();
+      service.onInjection(listener);
+
+      service.addInjection('bg output', 'background_completion');
+
+      expect(listener).toHaveBeenCalledWith(
+        'bg output',
+        'background_completion',
+      );
+    });
+
+    it('accepts background_completion even when model steering is disabled', () => {
+      const service = new InjectionService(() => false);
+      const listener = vi.fn();
+      service.onInjection(listener);
+
+      service.addInjection('bg output', 'background_completion');
+
+      expect(listener).toHaveBeenCalledWith(
+        'bg output',
+        'background_completion',
+      );
+      expect(service.getInjections()).toEqual(['bg output']);
+    });
+
+    it('filters injections by source when requested', () => {
+      const service = new InjectionService(() => true);
+      service.addInjection('hint', 'user_steering');
+      service.addInjection('bg output', 'background_completion');
+      service.addInjection('hint 2', 'user_steering');
+
+      expect(service.getInjections('user_steering')).toEqual([
+        'hint',
+        'hint 2',
+      ]);
+      expect(service.getInjections('background_completion')).toEqual([
+        'bg output',
+      ]);
+      expect(service.getInjections()).toEqual(['hint', 'bg output', 'hint 2']);
+
+      expect(service.getInjectionsAfter(0, 'user_steering')).toEqual([
+        'hint 2',
+      ]);
+      expect(service.getInjectionsAfter(0, 'background_completion')).toEqual([
+        'bg output',
+      ]);
+    });
+
+    it('rejects user_steering when model steering is disabled', () => {
+      const service = new InjectionService(() => false);
+      const listener = vi.fn();
+      service.onInjection(listener);
+
+      service.addInjection('steering hint', 'user_steering');
+
+      expect(listener).not.toHaveBeenCalled();
+      expect(service.getInjections()).toEqual([]);
+    });
+  });
+});

packages/core/src/config/injectionService.ts

@@ -0,0 +1,115 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Source of an injection into the model conversation.
+ * - `user_steering`: Interactive guidance from the user (gated on model steering).
+ * - `background_completion`: Output from a backgrounded execution that has finished.
+ */
+
+import { debugLogger } from '../utils/debugLogger.js';
+
+export type InjectionSource = 'user_steering' | 'background_completion';
+
+/**
+ * Typed listener that receives both the injection text and its source.
+ */
+export type InjectionListener = (text: string, source: InjectionSource) => void;
+
+/**
+ * Service for managing injections into the model conversation.
+ *
+ * Multiple sources (user steering, background execution completions, etc.)
+ * can feed into this service. Consumers register listeners via
+ * {@link onInjection} to receive injections with source information.
+ */
+export class InjectionService {
+  private readonly injections: Array<{
+    text: string;
+    source: InjectionSource;
+    timestamp: number;
+  }> = [];
+  private readonly injectionListeners: Set<InjectionListener> = new Set();
+
+  constructor(private readonly isEnabled: () => boolean) {}
+
+  /**
+   * Adds an injection from any source.
+   *
+   * `user_steering` injections are gated on model steering being enabled.
+   * Other sources (e.g. `background_completion`) are always accepted.
+   */
+  addInjection(text: string, source: InjectionSource): void {
+    if (source === 'user_steering' && !this.isEnabled()) {
+      return;
+    }
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+    this.injections.push({ text: trimmed, source, timestamp: Date.now() });
+
+    for (const listener of this.injectionListeners) {
+      try {
+        listener(trimmed, source);
+      } catch (error) {
+        debugLogger.warn(
+          `Injection listener failed for source "${source}": ${error}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Registers a listener for injections from any source.
+   */
+  onInjection(listener: InjectionListener): void {
+    this.injectionListeners.add(listener);
+  }
+
+  /**
+   * Unregisters an injection listener.
+   */
+  offInjection(listener: InjectionListener): void {
+    this.injectionListeners.delete(listener);
+  }
+
+  /**
+   * Returns collected injection texts, optionally filtered by source.
+   */
+  getInjections(source?: InjectionSource): string[] {
+    const items = source
+      ? this.injections.filter((h) => h.source === source)
+      : this.injections;
+    return items.map((h) => h.text);
+  }
+
+  /**
+   * Returns injection texts added after a specific index, optionally filtered by source.
+   */
+  getInjectionsAfter(index: number, source?: InjectionSource): string[] {
+    if (index < 0) {
+      return this.getInjections(source);
+    }
+    const items = this.injections.slice(index + 1);
+    const filtered = source ? items.filter((h) => h.source === source) : items;
+    return filtered.map((h) => h.text);
+  }
+
+  /**
+   * Returns the index of the latest injection.
+   */
+  getLatestInjectionIndex(): number {
+    return this.injections.length - 1;
+  }
+
+  /**
+   * Clears all collected injections.
+   */
+  clear(): void {
+    this.injections.length = 0;
+  }
+}

packages/core/src/config/userHintService.test.ts

@@ -1,77 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { UserHintService } from './userHintService.js';
-
-describe('UserHintService', () => {
-  it('is disabled by default and ignores hints', () => {
-    const service = new UserHintService(() => false);
-    service.addUserHint('this hint should be ignored');
-    expect(service.getUserHints()).toEqual([]);
-    expect(service.getLatestHintIndex()).toBe(-1);
-  });
-
-  it('stores trimmed hints and exposes them via indexing when enabled', () => {
-    const service = new UserHintService(() => true);
-
-    service.addUserHint('  first hint  ');
-    service.addUserHint('second hint');
-    service.addUserHint('   ');
-
-    expect(service.getUserHints()).toEqual(['first hint', 'second hint']);
-    expect(service.getLatestHintIndex()).toBe(1);
-    expect(service.getUserHintsAfter(-1)).toEqual([
-      'first hint',
-      'second hint',
-    ]);
-    expect(service.getUserHintsAfter(0)).toEqual(['second hint']);
-    expect(service.getUserHintsAfter(1)).toEqual([]);
-  });
-
-  it('tracks the last hint timestamp', () => {
-    const service = new UserHintService(() => true);
-
-    expect(service.getLastUserHintAt()).toBeNull();
-    service.addUserHint('hint');
-
-    const timestamp = service.getLastUserHintAt();
-    expect(timestamp).not.toBeNull();
-    expect(typeof timestamp).toBe('number');
-  });
-
-  it('notifies listeners when a hint is added', () => {
-    const service = new UserHintService(() => true);
-    const listener = vi.fn();
-    service.onUserHint(listener);
-
-    service.addUserHint('new hint');
-
-    expect(listener).toHaveBeenCalledWith('new hint');
-  });
-
-  it('does NOT notify listeners after they are unregistered', () => {
-    const service = new UserHintService(() => true);
-    const listener = vi.fn();
-    service.onUserHint(listener);
-    service.offUserHint(listener);
-
-    service.addUserHint('ignored hint');
-
-    expect(listener).not.toHaveBeenCalled();
-  });
-
-  it('should clear all hints', () => {
-    const service = new UserHintService(() => true);
-    service.addUserHint('hint 1');
-    service.addUserHint('hint 2');
-    expect(service.getUserHints()).toHaveLength(2);
-
-    service.clear();
-    expect(service.getUserHints()).toHaveLength(0);
-    expect(service.getLatestHintIndex()).toBe(-1);
-  });
-});

packages/core/src/config/userHintService.ts

@@ -1,87 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * Service for managing user steering hints during a session.
- */
-export class UserHintService {
-  private readonly userHints: Array<{ text: string; timestamp: number }> = [];
-  private readonly userHintListeners: Set<(hint: string) => void> = new Set();
-
-  constructor(private readonly isEnabled: () => boolean) {}
-
-  /**
-   * Adds a new steering hint from the user.
-   */
-  addUserHint(hint: string): void {
-    if (!this.isEnabled()) {
-      return;
-    }
-    const trimmed = hint.trim();
-    if (trimmed.length === 0) {
-      return;
-    }
-    this.userHints.push({ text: trimmed, timestamp: Date.now() });
-    for (const listener of this.userHintListeners) {
-      listener(trimmed);
-    }
-  }
-
-  /**
-   * Registers a listener for new user hints.
-   */
-  onUserHint(listener: (hint: string) => void): void {
-    this.userHintListeners.add(listener);
-  }
-
-  /**
-   * Unregisters a listener for new user hints.
-   */
-  offUserHint(listener: (hint: string) => void): void {
-    this.userHintListeners.delete(listener);
-  }
-
-  /**
-   * Returns all collected hints.
-   */
-  getUserHints(): string[] {
-    return this.userHints.map((h) => h.text);
-  }
-
-  /**
-   * Returns hints added after a specific index.
-   */
-  getUserHintsAfter(index: number): string[] {
-    if (index < 0) {
-      return this.getUserHints();
-    }
-    return this.userHints.slice(index + 1).map((h) => h.text);
-  }
-
-  /**
-   * Returns the index of the latest hint.
-   */
-  getLatestHintIndex(): number {
-    return this.userHints.length - 1;
-  }
-
-  /**
-   * Returns the timestamp of the last user hint.
-   */
-  getLastUserHintAt(): number | null {
-    if (this.userHints.length === 0) {
-      return null;
-    }
-    return this.userHints[this.userHints.length - 1].timestamp;
-  }
-
-  /**
-   * Clears all collected hints.
-   */
-  clear(): void {
-    this.userHints.length = 0;
-  }
-}