@google/gemini-cli-core 0.34.0-preview.2 → 0.35.0-nightly.20260313.bb060d7a9

package/dist/src/services/executionLifecycleService.js

@@ -0,0 +1,271 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const NON_PROCESS_EXECUTION_ID_START = 2_000_000_000;
+/**
+ * Central owner for execution backgrounding lifecycle across shell and tools.
+ */
+export class ExecutionLifecycleService {
+    static EXIT_INFO_TTL_MS = 5 * 60 * 1000;
+    static nextExecutionId = NON_PROCESS_EXECUTION_ID_START;
+    static activeExecutions = new Map();
+    static activeResolvers = new Map();
+    static activeListeners = new Map();
+    static exitedExecutionInfo = new Map();
+    static storeExitInfo(executionId, exitCode, signal) {
+        this.exitedExecutionInfo.set(executionId, {
+            exitCode,
+            signal,
+        });
+        setTimeout(() => {
+            this.exitedExecutionInfo.delete(executionId);
+        }, this.EXIT_INFO_TTL_MS).unref();
+    }
+    static allocateExecutionId() {
+        let executionId = ++this.nextExecutionId;
+        while (this.activeExecutions.has(executionId)) {
+            executionId = ++this.nextExecutionId;
+        }
+        return executionId;
+    }
+    static createPendingResult(executionId) {
+        return new Promise((resolve) => {
+            this.activeResolvers.set(executionId, resolve);
+        });
+    }
+    static createAbortedResult(executionId, execution) {
+        const output = execution.getBackgroundOutput?.() ?? execution.output;
+        return {
+            rawOutput: Buffer.from(output, 'utf8'),
+            output,
+            exitCode: 130,
+            signal: null,
+            error: new Error('Operation cancelled by user.'),
+            aborted: true,
+            pid: executionId,
+            executionMethod: execution.executionMethod,
+        };
+    }
+    /**
+     * Resets lifecycle state for isolated unit tests.
+     */
+    static resetForTest() {
+        this.activeExecutions.clear();
+        this.activeResolvers.clear();
+        this.activeListeners.clear();
+        this.exitedExecutionInfo.clear();
+        this.nextExecutionId = NON_PROCESS_EXECUTION_ID_START;
+    }
+    static attachExecution(executionId, registration) {
+        if (this.activeExecutions.has(executionId) ||
+            this.activeResolvers.has(executionId)) {
+            throw new Error(`Execution ${executionId} is already attached.`);
+        }
+        this.exitedExecutionInfo.delete(executionId);
+        this.activeExecutions.set(executionId, {
+            executionMethod: registration.executionMethod,
+            output: registration.initialOutput ?? '',
+            kind: 'external',
+            getBackgroundOutput: registration.getBackgroundOutput,
+            getSubscriptionSnapshot: registration.getSubscriptionSnapshot,
+            writeInput: registration.writeInput,
+            kill: registration.kill,
+            isActive: registration.isActive,
+        });
+        return {
+            pid: executionId,
+            result: this.createPendingResult(executionId),
+        };
+    }
+    static createExecution(initialOutput = '', onKill, executionMethod = 'none') {
+        const executionId = this.allocateExecutionId();
+        this.activeExecutions.set(executionId, {
+            executionMethod,
+            output: initialOutput,
+            kind: 'virtual',
+            onKill,
+            getBackgroundOutput: () => {
+                const state = this.activeExecutions.get(executionId);
+                return state?.output ?? initialOutput;
+            },
+            getSubscriptionSnapshot: () => {
+                const state = this.activeExecutions.get(executionId);
+                return state?.output ?? initialOutput;
+            },
+        });
+        return {
+            pid: executionId,
+            result: this.createPendingResult(executionId),
+        };
+    }
+    static appendOutput(executionId, chunk) {
+        const execution = this.activeExecutions.get(executionId);
+        if (!execution || chunk.length === 0) {
+            return;
+        }
+        execution.output += chunk;
+        this.emitEvent(executionId, { type: 'data', chunk });
+    }
+    static emitEvent(executionId, event) {
+        const listeners = this.activeListeners.get(executionId);
+        if (listeners) {
+            listeners.forEach((listener) => listener(event));
+        }
+    }
+    static resolvePending(executionId, result) {
+        const resolve = this.activeResolvers.get(executionId);
+        if (!resolve) {
+            return;
+        }
+        resolve(result);
+        this.activeResolvers.delete(executionId);
+    }
+    static settleExecution(executionId, result) {
+        if (!this.activeExecutions.has(executionId)) {
+            return;
+        }
+        this.resolvePending(executionId, result);
+        this.emitEvent(executionId, {
+            type: 'exit',
+            exitCode: result.exitCode,
+            signal: result.signal,
+        });
+        this.activeListeners.delete(executionId);
+        this.activeExecutions.delete(executionId);
+        this.storeExitInfo(executionId, result.exitCode ?? 0, result.signal ?? undefined);
+    }
+    static completeExecution(executionId, options) {
+        const execution = this.activeExecutions.get(executionId);
+        if (!execution) {
+            return;
+        }
+        const { error = null, aborted = false, exitCode = error ? 1 : 0, signal = null, } = options ?? {};
+        const output = execution.getBackgroundOutput?.() ?? execution.output;
+        this.settleExecution(executionId, {
+            rawOutput: Buffer.from(output, 'utf8'),
+            output,
+            exitCode,
+            signal,
+            error,
+            aborted,
+            pid: executionId,
+            executionMethod: execution.executionMethod,
+        });
+    }
+    static completeWithResult(executionId, result) {
+        this.settleExecution(executionId, result);
+    }
+    static background(executionId) {
+        const resolve = this.activeResolvers.get(executionId);
+        if (!resolve) {
+            return;
+        }
+        const execution = this.activeExecutions.get(executionId);
+        if (!execution) {
+            return;
+        }
+        const output = execution.getBackgroundOutput?.() ?? execution.output;
+        resolve({
+            rawOutput: Buffer.from(''),
+            output,
+            exitCode: null,
+            signal: null,
+            error: null,
+            aborted: false,
+            pid: executionId,
+            executionMethod: execution.executionMethod,
+            backgrounded: true,
+        });
+        this.activeResolvers.delete(executionId);
+    }
+    static subscribe(executionId, listener) {
+        if (!this.activeListeners.has(executionId)) {
+            this.activeListeners.set(executionId, new Set());
+        }
+        this.activeListeners.get(executionId)?.add(listener);
+        const execution = this.activeExecutions.get(executionId);
+        if (execution) {
+            const snapshot = execution.getSubscriptionSnapshot?.() ??
+                (execution.output.length > 0 ? execution.output : undefined);
+            if (snapshot && (typeof snapshot !== 'string' || snapshot.length > 0)) {
+                listener({ type: 'data', chunk: snapshot });
+            }
+        }
+        return () => {
+            this.activeListeners.get(executionId)?.delete(listener);
+            if (this.activeListeners.get(executionId)?.size === 0) {
+                this.activeListeners.delete(executionId);
+            }
+        };
+    }
+    static onExit(executionId, callback) {
+        if (this.activeExecutions.has(executionId)) {
+            const listener = (event) => {
+                if (event.type === 'exit') {
+                    callback(event.exitCode ?? 0, event.signal ?? undefined);
+                    unsubscribe();
+                }
+            };
+            const unsubscribe = this.subscribe(executionId, listener);
+            return unsubscribe;
+        }
+        const exitedInfo = this.exitedExecutionInfo.get(executionId);
+        if (exitedInfo) {
+            callback(exitedInfo.exitCode, exitedInfo.signal);
+        }
+        return () => { };
+    }
+    static kill(executionId) {
+        const execution = this.activeExecutions.get(executionId);
+        if (!execution) {
+            return;
+        }
+        if (execution.kind === 'virtual') {
+            execution.onKill?.();
+        }
+        if (execution.kind === 'external') {
+            execution.kill?.();
+        }
+        this.completeWithResult(executionId, this.createAbortedResult(executionId, execution));
+    }
+    static isActive(executionId) {
+        const execution = this.activeExecutions.get(executionId);
+        if (!execution) {
+            if (executionId >= NON_PROCESS_EXECUTION_ID_START) {
+                return false;
+            }
+            try {
+                return process.kill(executionId, 0);
+            }
+            catch {
+                return false;
+            }
+        }
+        if (execution.kind === 'virtual') {
+            return true;
+        }
+        if (execution.kind === 'external' && execution.isActive) {
+            try {
+                return execution.isActive();
+            }
+            catch {
+                return false;
+            }
+        }
+        try {
+            return process.kill(executionId, 0);
+        }
+        catch {
+            return false;
+        }
+    }
+    static writeInput(executionId, input) {
+        const execution = this.activeExecutions.get(executionId);
+        if (execution?.kind === 'external') {
+            execution.writeInput?.(input);
+        }
+    }
+}
+//# sourceMappingURL=executionLifecycleService.js.map

package/dist/src/services/executionLifecycleService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executionLifecycleService.js","sourceRoot":"","sources":["../../../src/services/executionLifecycleService.ts"],"names":[],"mappings":"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"}

package/dist/src/services/executionLifecycleService.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/services/executionLifecycleService.test.js

@@ -0,0 +1,227 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { ExecutionLifecycleService, } from './executionLifecycleService.js';
+function createResult(overrides = {}) {
+    return {
+        rawOutput: Buffer.from(''),
+        output: '',
+        exitCode: 0,
+        signal: null,
+        error: null,
+        aborted: false,
+        pid: 123,
+        executionMethod: 'child_process',
+        ...overrides,
+    };
+}
+describe('ExecutionLifecycleService', () => {
+    beforeEach(() => {
+        ExecutionLifecycleService.resetForTest();
+    });
+    it('completes managed executions in the foreground and notifies exit subscribers', async () => {
+        const handle = ExecutionLifecycleService.createExecution();
+        if (handle.pid === undefined) {
+            throw new Error('Expected execution ID.');
+        }
+        const onExit = vi.fn();
+        const unsubscribe = ExecutionLifecycleService.onExit(handle.pid, onExit);
+        ExecutionLifecycleService.appendOutput(handle.pid, 'Hello');
+        ExecutionLifecycleService.appendOutput(handle.pid, ' World');
+        ExecutionLifecycleService.completeExecution(handle.pid, {
+            exitCode: 0,
+        });
+        const result = await handle.result;
+        expect(result.output).toBe('Hello World');
+        expect(result.executionMethod).toBe('none');
+        expect(result.backgrounded).toBeUndefined();
+        await vi.waitFor(() => {
+            expect(onExit).toHaveBeenCalledWith(0, undefined);
+        });
+        unsubscribe();
+    });
+    it('supports explicit execution methods for managed executions', async () => {
+        const handle = ExecutionLifecycleService.createExecution('', undefined, 'remote_agent');
+        if (handle.pid === undefined) {
+            throw new Error('Expected execution ID.');
+        }
+        ExecutionLifecycleService.completeExecution(handle.pid, {
+            exitCode: 0,
+        });
+        const result = await handle.result;
+        expect(result.executionMethod).toBe('remote_agent');
+    });
+    it('supports backgrounding managed executions and continues streaming updates', async () => {
+        const handle = ExecutionLifecycleService.createExecution();
+        if (handle.pid === undefined) {
+            throw new Error('Expected execution ID.');
+        }
+        const chunks = [];
+        const onExit = vi.fn();
+        const unsubscribeStream = ExecutionLifecycleService.subscribe(handle.pid, (event) => {
+            if (event.type === 'data' && typeof event.chunk === 'string') {
+                chunks.push(event.chunk);
+            }
+        });
+        const unsubscribeExit = ExecutionLifecycleService.onExit(handle.pid, onExit);
+        ExecutionLifecycleService.appendOutput(handle.pid, 'Chunk 1');
+        ExecutionLifecycleService.background(handle.pid);
+        const backgroundResult = await handle.result;
+        expect(backgroundResult.backgrounded).toBe(true);
+        expect(backgroundResult.output).toBe('Chunk 1');
+        ExecutionLifecycleService.appendOutput(handle.pid, '\nChunk 2');
+        ExecutionLifecycleService.completeExecution(handle.pid, {
+            exitCode: 0,
+        });
+        await vi.waitFor(() => {
+            expect(chunks.join('')).toContain('Chunk 2');
+            expect(onExit).toHaveBeenCalledWith(0, undefined);
+        });
+        unsubscribeStream();
+        unsubscribeExit();
+    });
+    it('kills managed executions and resolves with aborted result', async () => {
+        const onKill = vi.fn();
+        const handle = ExecutionLifecycleService.createExecution('', onKill);
+        if (handle.pid === undefined) {
+            throw new Error('Expected execution ID.');
+        }
+        ExecutionLifecycleService.appendOutput(handle.pid, 'work');
+        ExecutionLifecycleService.kill(handle.pid);
+        const result = await handle.result;
+        expect(onKill).toHaveBeenCalledTimes(1);
+        expect(result.aborted).toBe(true);
+        expect(result.exitCode).toBe(130);
+        expect(result.error?.message).toContain('Operation cancelled by user');
+    });
+    it('does not probe OS process state for completed non-process execution IDs', async () => {
+        const handle = ExecutionLifecycleService.createExecution();
+        if (handle.pid === undefined) {
+            throw new Error('Expected execution ID.');
+        }
+        ExecutionLifecycleService.completeExecution(handle.pid, { exitCode: 0 });
+        await handle.result;
+        const processKillSpy = vi.spyOn(process, 'kill');
+        expect(ExecutionLifecycleService.isActive(handle.pid)).toBe(false);
+        expect(processKillSpy).not.toHaveBeenCalled();
+        processKillSpy.mockRestore();
+    });
+    it('manages external executions through registration hooks', async () => {
+        const writeInput = vi.fn();
+        const isActive = vi.fn().mockReturnValue(true);
+        const exitListener = vi.fn();
+        const chunks = [];
+        let output = 'seed';
+        const handle = ExecutionLifecycleService.attachExecution(4321, {
+            executionMethod: 'child_process',
+            getBackgroundOutput: () => output,
+            getSubscriptionSnapshot: () => output,
+            writeInput,
+            isActive,
+        });
+        const unsubscribe = ExecutionLifecycleService.subscribe(4321, (event) => {
+            if (event.type === 'data' && typeof event.chunk === 'string') {
+                chunks.push(event.chunk);
+            }
+        });
+        ExecutionLifecycleService.onExit(4321, exitListener);
+        ExecutionLifecycleService.writeInput(4321, 'stdin');
+        expect(writeInput).toHaveBeenCalledWith('stdin');
+        expect(ExecutionLifecycleService.isActive(4321)).toBe(true);
+        const firstChunk = { type: 'data', chunk: ' +delta' };
+        ExecutionLifecycleService.emitEvent(4321, firstChunk);
+        output += firstChunk.chunk;
+        ExecutionLifecycleService.background(4321);
+        const backgroundResult = await handle.result;
+        expect(backgroundResult.backgrounded).toBe(true);
+        expect(backgroundResult.output).toBe('seed +delta');
+        expect(backgroundResult.executionMethod).toBe('child_process');
+        ExecutionLifecycleService.completeWithResult(4321, createResult({
+            pid: 4321,
+            output: 'seed +delta done',
+            rawOutput: Buffer.from('seed +delta done'),
+            executionMethod: 'child_process',
+        }));
+        await vi.waitFor(() => {
+            expect(exitListener).toHaveBeenCalledWith(0, undefined);
+        });
+        const lateExit = vi.fn();
+        ExecutionLifecycleService.onExit(4321, lateExit);
+        expect(lateExit).toHaveBeenCalledWith(0, undefined);
+        unsubscribe();
+    });
+    it('supports late subscription catch-up after backgrounding an external execution', async () => {
+        let output = 'seed';
+        const onExit = vi.fn();
+        const handle = ExecutionLifecycleService.attachExecution(4322, {
+            executionMethod: 'child_process',
+            getBackgroundOutput: () => output,
+            getSubscriptionSnapshot: () => output,
+        });
+        ExecutionLifecycleService.onExit(4322, onExit);
+        ExecutionLifecycleService.background(4322);
+        const backgroundResult = await handle.result;
+        expect(backgroundResult.backgrounded).toBe(true);
+        expect(backgroundResult.output).toBe('seed');
+        output += ' +late';
+        ExecutionLifecycleService.emitEvent(4322, {
+            type: 'data',
+            chunk: ' +late',
+        });
+        const chunks = [];
+        const unsubscribe = ExecutionLifecycleService.subscribe(4322, (event) => {
+            if (event.type === 'data' && typeof event.chunk === 'string') {
+                chunks.push(event.chunk);
+            }
+        });
+        expect(chunks[0]).toBe('seed +late');
+        output += ' +live';
+        ExecutionLifecycleService.emitEvent(4322, {
+            type: 'data',
+            chunk: ' +live',
+        });
+        expect(chunks[chunks.length - 1]).toBe(' +live');
+        ExecutionLifecycleService.completeWithResult(4322, createResult({
+            pid: 4322,
+            output,
+            rawOutput: Buffer.from(output),
+            executionMethod: 'child_process',
+        }));
+        await vi.waitFor(() => {
+            expect(onExit).toHaveBeenCalledWith(0, undefined);
+        });
+        unsubscribe();
+    });
+    it('kills external executions and settles pending promises', async () => {
+        const terminate = vi.fn();
+        const onExit = vi.fn();
+        const handle = ExecutionLifecycleService.attachExecution(4323, {
+            executionMethod: 'child_process',
+            initialOutput: 'running',
+            kill: terminate,
+        });
+        ExecutionLifecycleService.onExit(4323, onExit);
+        ExecutionLifecycleService.kill(4323);
+        const result = await handle.result;
+        expect(terminate).toHaveBeenCalledTimes(1);
+        expect(result.aborted).toBe(true);
+        expect(result.exitCode).toBe(130);
+        expect(result.output).toBe('running');
+        expect(result.error?.message).toContain('Operation cancelled by user');
+        expect(onExit).toHaveBeenCalledWith(130, undefined);
+    });
+    it('rejects duplicate execution registration for active execution IDs', () => {
+        ExecutionLifecycleService.attachExecution(4324, {
+            executionMethod: 'child_process',
+        });
+        expect(() => {
+            ExecutionLifecycleService.attachExecution(4324, {
+                executionMethod: 'child_process',
+            });
+        }).toThrow('Execution 4324 is already attached.');
+    });
+});
+//# sourceMappingURL=executionLifecycleService.test.js.map

package/dist/src/services/executionLifecycleService.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executionLifecycleService.test.js","sourceRoot":"","sources":["../../../src/services/executionLifecycleService.test.ts"],"names":[],"mappings":"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"}

package/dist/src/services/sandboxManager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type EnvironmentSanitizationConfig } from './environmentSanitization.js';
+/**
+ * Request for preparing a command to run in a sandbox.
+ */
+export interface SandboxRequest {
+    /** The program to execute. */
+    command: string;
+    /** Arguments for the program. */
+    args: string[];
+    /** The working directory. */
+    cwd: string;
+    /** Environment variables to be passed to the program. */
+    env: NodeJS.ProcessEnv;
+    /** Optional sandbox-specific configuration. */
+    config?: {
+        sanitizationConfig?: Partial<EnvironmentSanitizationConfig>;
+    };
+}
+/**
+ * A command that has been prepared for sandboxed execution.
+ */
+export interface SandboxedCommand {
+    /** The program or wrapper to execute. */
+    program: string;
+    /** Final arguments for the program. */
+    args: string[];
+    /** Sanitized environment variables. */
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Interface for a service that prepares commands for sandboxed execution.
+ */
+export interface SandboxManager {
+    /**
+     * Prepares a command to run in a sandbox, including environment sanitization.
+     */
+    prepareCommand(req: SandboxRequest): Promise<SandboxedCommand>;
+}
+/**
+ * A no-op implementation of SandboxManager that silently passes commands
+ * through while applying environment sanitization.
+ */
+export declare class NoopSandboxManager implements SandboxManager {
+    /**
+     * Prepares a command by sanitizing the environment and passing through
+     * the original program and arguments.
+     */
+    prepareCommand(req: SandboxRequest): Promise<SandboxedCommand>;
+}

package/dist/src/services/sandboxManager.js

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { sanitizeEnvironment, } from './environmentSanitization.js';
+/**
+ * A no-op implementation of SandboxManager that silently passes commands
+ * through while applying environment sanitization.
+ */
+export class NoopSandboxManager {
+    /**
+     * Prepares a command by sanitizing the environment and passing through
+     * the original program and arguments.
+     */
+    async prepareCommand(req) {
+        const sanitizationConfig = {
+            allowedEnvironmentVariables: req.config?.sanitizationConfig?.allowedEnvironmentVariables ?? [],
+            blockedEnvironmentVariables: req.config?.sanitizationConfig?.blockedEnvironmentVariables ?? [],
+            enableEnvironmentVariableRedaction: true, // Forced for safety
+        };
+        const sanitizedEnv = sanitizeEnvironment(req.env, sanitizationConfig);
+        return {
+            program: req.command,
+            args: req.args,
+            env: sanitizedEnv,
+        };
+    }
+}
+//# sourceMappingURL=sandboxManager.js.map

package/dist/src/services/sandboxManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxManager.js","sourceRoot":"","sources":["../../../src/services/sandboxManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,mBAAmB,GAEpB,MAAM,8BAA8B,CAAC;AA0CtC;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B;;;OAGG;IACH,KAAK,CAAC,cAAc,CAAC,GAAmB;QACtC,MAAM,kBAAkB,GAAkC;YACxD,2BAA2B,EACzB,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,2BAA2B,IAAI,EAAE;YACnE,2BAA2B,EACzB,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,2BAA2B,IAAI,EAAE;YACnE,kCAAkC,EAAE,IAAI,EAAE,oBAAoB;SAC/D,CAAC;QAEF,MAAM,YAAY,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;QAEtE,OAAO;YACL,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,GAAG,EAAE,YAAY;SAClB,CAAC;IACJ,CAAC;CACF"}

package/dist/src/services/sandboxManager.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};