@theia/ai-terminal 1.76.0-next.7 → 1.76.0

package/src/browser/predefined-shell-tool.spec.ts

@@ -0,0 +1,222 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+let disableJSDOM = enableJSDOM();
+import { FrontendApplicationConfigProvider } from '@theia/core/lib/browser/frontend-application-config-provider';
+FrontendApplicationConfigProvider.set({});
+
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { Container } from '@theia/core/shared/inversify';
+import { CancellationTokenSource } from '@theia/core/lib/common/cancellation';
+import URI from '@theia/core/lib/common/uri';
+import { WorkspaceService } from '@theia/workspace/lib/browser/workspace-service';
+import { ShellExecutionRequest, ShellExecutionResult, ShellExecutionServer } from '../common/shell-execution-server';
+import { PREDEFINED_SHELL_TOOL_PROVIDER, PredefinedShellTool } from './predefined-shell-tool';
+
+disableJSDOM();
+
+class TestPredefinedShellTool extends PredefinedShellTool {
+    readonly id = 'test-predefined';
+    readonly description = 'A test predefined shell tool that returns hello';
+
+    protected buildCommand(args: Record<string, unknown>): string {
+        const upper = args.upper === true;
+        return upper ? 'echo HELLO' : 'echo hello';
+    }
+
+    protected resolveWorkspaceRoot(args: Record<string, unknown>): string | undefined {
+        return typeof args.cwd === 'string' ? args.cwd : this.firstWorkspaceRoot();
+    }
+}
+
+function createResult(overrides: Partial<ShellExecutionResult> = {}): ShellExecutionResult {
+    return {
+        success: true,
+        exitCode: 0,
+        stdout: 'hello\n',
+        stderr: '',
+        duration: 5,
+        ...overrides
+    };
+}
+
+describe('PredefinedShellTool', () => {
+
+    let container: Container;
+    let shellServer: { execute: sinon.SinonStub; cancel: sinon.SinonStub };
+    let tool: TestPredefinedShellTool;
+
+    before(() => {
+        disableJSDOM = enableJSDOM();
+    });
+
+    after(() => {
+        disableJSDOM();
+    });
+
+    beforeEach(() => {
+        container = new Container();
+        shellServer = {
+            execute: sinon.stub().resolves(createResult()),
+            cancel: sinon.stub().resolves(true)
+        };
+        const workspaceService: Partial<WorkspaceService> = {
+            getWorkspaceRootUri: () => new URI('file:///workspace')
+        };
+        container.bind(ShellExecutionServer).toConstantValue(shellServer as unknown as ShellExecutionServer);
+        container.bind(WorkspaceService).toConstantValue(workspaceService as WorkspaceService);
+        container.bind(TestPredefinedShellTool).toSelf();
+        tool = container.get(TestPredefinedShellTool);
+    });
+
+    it('exposes the subclass id and description on the tool', () => {
+        const request = tool.getTool();
+        expect(request.id).to.equal('test-predefined');
+        expect(request.name).to.equal('test-predefined');
+        expect(request.description).to.equal('A test predefined shell tool that returns hello');
+        expect(request.providerName).to.equal(PREDEFINED_SHELL_TOOL_PROVIDER);
+    });
+
+    it('does not declare checkAutoAction so confirmation flows through the normal ToolConfirmationManager', () => {
+        const request = tool.getTool();
+        expect(request.checkAutoAction).to.be.undefined;
+    });
+
+    it('passes the hardcoded command, workspace root and a generated execution id to ShellExecutionServer', async () => {
+        const request = tool.getTool();
+        await request.handler('{}');
+        expect(shellServer.execute.calledOnce).to.be.true;
+        const arg = shellServer.execute.firstCall.args[0] as ShellExecutionRequest;
+        expect(arg.command).to.equal('echo hello');
+        // URI.fsPath() uses the platform-native separator, so the cwd comes back as
+        // `\workspace` on Windows. Normalize before asserting to keep the test platform-agnostic.
+        expect(arg.cwd?.replace(/\\/g, '/')).to.equal('/workspace');
+        expect(arg.timeout).to.equal(30_000);
+        expect(typeof arg.executionId).to.equal('string');
+        expect(arg.executionId!.length).to.be.greaterThan(0);
+    });
+
+    it('forwards typed args to buildCommand', async () => {
+        const request = tool.getTool();
+        await request.handler(JSON.stringify({ upper: true }));
+        const arg = shellServer.execute.firstCall.args[0] as ShellExecutionRequest;
+        expect(arg.command).to.equal('echo HELLO');
+    });
+
+    it('forwards the same typed args to resolveWorkspaceRoot, so the cwd can depend on them', async () => {
+        await tool.getTool().handler(JSON.stringify({ cwd: '/elsewhere' }));
+        const arg = shellServer.execute.firstCall.args[0] as ShellExecutionRequest;
+        expect(arg.cwd).to.equal('/elsewhere');
+    });
+
+    it('handles an empty argument string as an empty args object', async () => {
+        const request = tool.getTool();
+        await request.handler('');
+        const arg = shellServer.execute.firstCall.args[0] as ShellExecutionRequest;
+        expect(arg.command).to.equal('echo hello');
+    });
+
+    it('returns a formatted result with combined output', async () => {
+        shellServer.execute.resolves(createResult({ stdout: 'out\n', stderr: 'err\n' }));
+        const request = tool.getTool();
+        const raw = await request.handler('{}');
+        expect(raw).to.deep.include({
+            success: true,
+            exitCode: 0
+        });
+        const result = raw as { output: string };
+        expect(result.output).to.contain('out');
+        expect(result.output).to.contain('err');
+    });
+
+    it('returns a canceled result when the underlying execution is canceled', async () => {
+        shellServer.execute.resolves(createResult({ canceled: true, stdout: 'partial\n', stderr: '' }));
+        const request = tool.getTool();
+        const result = await request.handler('{}') as { canceled: true; output?: string };
+        expect(result.canceled).to.be.true;
+        expect(result.output).to.contain('partial');
+    });
+
+    it('wires the invocation cancellation token to ShellExecutionServer.cancel', async () => {
+        const cts = new CancellationTokenSource();
+        const request = tool.getTool();
+
+        let capturedExecutionId: string | undefined;
+        shellServer.execute.callsFake(async (req: ShellExecutionRequest) => {
+            capturedExecutionId = req.executionId;
+            return new Promise<ShellExecutionResult>(resolve => {
+                cts.token.onCancellationRequested(() => resolve(createResult({ canceled: true, stdout: '', stderr: '' })));
+            });
+        });
+
+        const handlerPromise = request.handler('{}', { toolCallId: 'tc-1', cancellationToken: cts.token });
+        cts.cancel();
+        await handlerPromise;
+
+        expect(shellServer.cancel.calledOnce).to.be.true;
+        expect(shellServer.cancel.firstCall.args[0]).to.equal(capturedExecutionId);
+    });
+
+    it('tracks the execution by tool call id so it can be cancelled by id', async () => {
+        let capturedExecutionId: string | undefined;
+        let release: (() => void) | undefined;
+        shellServer.execute.callsFake(async (req: ShellExecutionRequest) => {
+            capturedExecutionId = req.executionId;
+            return new Promise<ShellExecutionResult>(resolve => {
+                release = () => resolve(createResult());
+            });
+        });
+
+        const handlerPromise = tool.getTool().handler('{}', { toolCallId: 'tc-1' });
+        expect(tool.isExecutionRunning('tc-1')).to.be.true;
+
+        expect(await tool.cancelExecution('tc-1')).to.be.true;
+        expect(shellServer.cancel.firstCall.args[0]).to.equal(capturedExecutionId);
+
+        release!();
+        await handlerPromise;
+        expect(tool.isExecutionRunning('tc-1')).to.be.false;
+    });
+
+    it('applies the default truncation budget, keeping only the first and last 50 lines', async () => {
+        const stdout = Array.from({ length: 500 }, (_unused, index) => `line ${index}`).join('\n');
+        shellServer.execute.resolves(createResult({ stdout }));
+
+        const result = await tool.getTool().handler('{}') as { output: string };
+
+        expect(result.output).to.contain('line 0');
+        expect(result.output).to.contain('line 499');
+        expect(result.output).to.not.contain('line 250');
+        expect(result.output).to.contain('400 lines omitted');
+    });
+
+    it('honours a raised truncation budget declared by the subclass', async () => {
+        class GenerousTool extends TestPredefinedShellTool {
+            protected override readonly truncation = { headLines: 400, tailLines: 100 };
+        }
+        container.bind(GenerousTool).toSelf();
+        const generous = container.get(GenerousTool);
+        const stdout = Array.from({ length: 500 }, (_unused, index) => `line ${index}`).join('\n');
+        shellServer.execute.resolves(createResult({ stdout }));
+
+        const result = await generous.getTool().handler('{}') as { output: string };
+
+        expect(result.output).to.contain('line 250');
+        expect(result.output).to.not.contain('lines omitted');
+    });
+});

package/src/browser/predefined-shell-tool.ts

@@ -0,0 +1,100 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { injectable } from '@theia/core/shared/inversify';
+import { ToolInvocationContext, ToolRequest, ToolRequestParameters } from '@theia/ai-core';
+import { AbstractShellExecutionTool } from './abstract-shell-execution-tool';
+import { OutputTruncationOptions, ShellExecutionCanceledResult, ShellExecutionToolResult } from '../common/shell-execution-server';
+
+/** `providerName` reported by tools that derive from {@link PredefinedShellTool}. */
+export const PREDEFINED_SHELL_TOOL_PROVIDER = 'ai-predefined-shell';
+
+/**
+ * Base class for tools that execute a fixed, hardcoded shell command. A subclass declares its
+ * tool `id`, its parameters and a `buildCommand(args)` method that assembles the command from
+ * typed arguments. The LLM only supplies the typed arguments, so the subclass stays in control
+ * of the command.
+ *
+ * Unlike the general-purpose `shellExecute` tool, a {@link PredefinedShellTool} does not consult
+ * `ShellCommandPermissionService` and does not appear on the user's shell allow/deny lists. The
+ * safety boundary is the subclass `buildCommand`, which must not be coercible into running
+ * arbitrary commands.
+ */
+@injectable()
+export abstract class PredefinedShellTool extends AbstractShellExecutionTool {
+
+    /** The unique identifier of this tool. Must not be `shellExecute`. */
+    abstract readonly id: string;
+
+    /** Human-readable description of this tool, shown to the LLM. */
+    abstract readonly description: string;
+
+    protected readonly parameters: ToolRequestParameters = { type: 'object', properties: {} };
+
+    /** Timeout for the underlying shell execution, in milliseconds. */
+    protected readonly timeout: number = 30_000;
+
+    /** Output truncation budget. `undefined` keeps the `shellExecute` defaults (first/last 50 lines). */
+    protected readonly truncation: OutputTruncationOptions | undefined = undefined;
+
+    /** Build the exact shell command to execute from the parsed arguments. */
+    protected abstract buildCommand(args: Record<string, unknown>): string;
+
+    /**
+     * Resolves the working directory for the shell command, given the same parsed arguments that
+     * {@link buildCommand} receives, so a tool can let the caller pick the folder it runs in.
+     *
+     * Deliberately abstract: the cwd materially affects most predefined commands (anything
+     * talking to a specific repository, build script, or per-folder tool), and silently
+     * defaulting to an arbitrary workspace root produces results that look plausible but describe
+     * the wrong folder.
+     *
+     * Subclasses that genuinely do not care about the cwd can return
+     * {@link firstWorkspaceRoot} or `undefined`.
+     */
+    protected abstract resolveWorkspaceRoot(args: Record<string, unknown>): string | undefined;
+
+    /**
+     * The **first** workspace root, or `undefined` when no workspace is open. Only a sensible
+     * `resolveWorkspaceRoot` implementation for commands that produce the same output regardless
+     * of cwd. In a multi-root workspace the first root is arbitrary.
+     */
+    protected firstWorkspaceRoot(): string | undefined {
+        return this.workspaceService.getWorkspaceRootUri(undefined)?.path.fsPath();
+    }
+
+    getTool(): ToolRequest {
+        return {
+            id: this.id,
+            name: this.id,
+            providerName: PREDEFINED_SHELL_TOOL_PROVIDER,
+            description: this.description,
+            parameters: this.parameters,
+            handler: (argString: string, ctx?: ToolInvocationContext) => this.execute(argString, ctx)
+        };
+    }
+
+    protected async execute(argString: string, ctx?: ToolInvocationContext): Promise<ShellExecutionToolResult | ShellExecutionCanceledResult> {
+        const args: Record<string, unknown> = argString ? JSON.parse(argString) : {};
+        return this.runShellCommand({
+            command: this.buildCommand(args),
+            cwd: this.resolveWorkspaceRoot(args),
+            timeout: this.timeout,
+            ctx,
+            truncation: this.truncation
+        });
+    }
+}

package/src/browser/shell-execution-tool.ts

@@ -15,48 +15,22 @@
 // *****************************************************************************
 
 import { injectable, inject } from '@theia/core/shared/inversify';
-import { ToolProvider, ToolRequest, AutoActionResult } from '@theia/ai-core';
+import { ToolRequest, AutoActionResult } from '@theia/ai-core';
 import { ShellCommandPermissionService } from './shell-command-permission-service';
-import { WorkspaceService } from '@theia/workspace/lib/browser';
+import { AbstractShellExecutionTool } from './abstract-shell-execution-tool';
 import {
     SHELL_EXECUTION_FUNCTION_ID,
-    ShellExecutionServer,
     ShellExecutionToolResult,
-    ShellExecutionCanceledResult,
-    combineAndTruncate
+    ShellExecutionCanceledResult
 } from '../common/shell-execution-server';
-import { CancellationToken, generateUuid, Path } from '@theia/core';
+import { Path } from '@theia/core';
 
 @injectable()
-export class ShellExecutionTool implements ToolProvider {
-
-    @inject(ShellExecutionServer)
-    protected readonly shellServer: ShellExecutionServer;
-
-    @inject(WorkspaceService)
-    protected readonly workspaceService: WorkspaceService;
+export class ShellExecutionTool extends AbstractShellExecutionTool {
 
     @inject(ShellCommandPermissionService)
     protected readonly shellCommandPermissionService: ShellCommandPermissionService;
 
-    protected readonly runningExecutions = new Map<string, string>();
-
-    async cancelExecution(toolCallId: string): Promise<boolean> {
-        const executionId = this.runningExecutions.get(toolCallId);
-        if (executionId) {
-            const canceled = await this.shellServer.cancel(executionId);
-            if (canceled) {
-                this.runningExecutions.delete(toolCallId);
-            }
-            return canceled;
-        }
-        return false;
-    }
-
-    isExecutionRunning(toolCallId: string): boolean {
-        return this.runningExecutions.has(toolCallId);
-    }
-
     getTool(): ToolRequest {
         return {
             id: SHELL_EXECUTION_FUNCTION_ID,
@@ -171,56 +145,12 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
             timeout?: number;
         } = JSON.parse(argString);
 
-        const resolvedCwd = this.resolveCwd(args.cwd);
-
-        // Generate execution ID and get tool call ID from context
-        const executionId = generateUuid();
-        const toolCallId = this.extractToolCallId(ctx);
-        const cancellationToken = this.extractCancellationToken(ctx);
-
-        // Track this execution
-        if (toolCallId) {
-            this.runningExecutions.set(toolCallId, executionId);
-        }
-
-        const cancellationListener = cancellationToken?.onCancellationRequested(() => {
-            this.shellServer.cancel(executionId);
+        return this.runShellCommand({
+            command: args.command,
+            cwd: this.resolveCwd(args.cwd),
+            timeout: args.timeout,
+            ctx
         });
-
-        try {
-            const result = await this.shellServer.execute({
-                command: args.command,
-                cwd: resolvedCwd,
-                timeout: args.timeout,
-                executionId,
-            });
-
-            if (result.canceled) {
-                return {
-                    canceled: true,
-                    output: this.combineAndTruncate(result.stdout, result.stderr) || undefined,
-                    duration: result.duration,
-                };
-            }
-
-            // Combine stdout and stderr, apply truncation
-            const combinedOutput = this.combineAndTruncate(result.stdout, result.stderr);
-
-            return {
-                success: result.success,
-                exitCode: result.exitCode,
-                output: combinedOutput,
-                error: result.error,
-                duration: result.duration,
-                cwd: result.resolvedCwd,
-            };
-        } finally {
-            // Clean up
-            cancellationListener?.dispose();
-            if (toolCallId) {
-                this.runningExecutions.delete(toolCallId);
-            }
-        }
     }
 
     /**
@@ -269,27 +199,4 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
         );
     }
 
-    protected extractToolCallId(ctx?: unknown): string | undefined {
-        if (ctx && typeof ctx === 'object' && 'toolCallId' in ctx) {
-            return (ctx as { toolCallId?: string }).toolCallId;
-        }
-        return undefined;
-    }
-
-    protected extractCancellationToken(ctx: unknown): CancellationToken | undefined {
-        if (ctx && typeof ctx === 'object') {
-            // Check for MutableChatRequestModel structure (response.cancellationToken)
-            if ('response' in ctx) {
-                const response = (ctx as { response?: { cancellationToken?: CancellationToken } }).response;
-                if (response?.cancellationToken) {
-                    return response.cancellationToken;
-                }
-            }
-        }
-        return undefined;
-    }
-
-    protected combineAndTruncate(stdout: string, stderr: string): string {
-        return combineAndTruncate(stdout, stderr);
-    }
 }

package/src/common/shell-execution-input-parser.spec.ts

@@ -105,10 +105,10 @@ describe('parseShellExecutionInput', () => {
             expect(result.command).to.equal('echo "hello"');
         });
 
-        it('should handle incomplete command with backslash', () => {
-            // During streaming, we get partial content - the regex stops at first unescaped quote
+        it('should unescape a quote in an incomplete command', () => {
+            // During streaming, we get partial content - the escaped quote is part of the command, not its end
             const result = parseShellExecutionInput('{"command": "echo \\"hello');
-            expect(result.command).to.equal('echo \\');
+            expect(result.command).to.equal('echo "hello');
         });
 
         it('should handle command with pipes and redirects', () => {

package/src/common/shell-execution-server.ts

@@ -82,16 +82,38 @@ export const TAIL_LINES = 50;
 export const GRACE_LINES = 10;
 export const MAX_LINE_LENGTH = 1000;
 
-export function truncateLine(line: string): string {
-    if (line.length <= MAX_LINE_LENGTH) {
+/**
+ * Line and line-length budget applied to combined command output. The defaults suit the
+ * general-purpose `shellExecute` tool, where output is often a long build or test log and only
+ * the beginning and the end carry information. Tools whose output is meaningful as a whole
+ * (e.g. a diff) should raise these limits.
+ */
+export interface OutputTruncationOptions {
+    /** Number of leading lines to keep. Default {@link HEAD_LINES}. */
+    headLines?: number;
+    /** Number of trailing lines to keep. Default {@link TAIL_LINES}. */
+    tailLines?: number;
+    /** Extra lines tolerated before truncation kicks in at all. Default {@link GRACE_LINES}. */
+    graceLines?: number;
+    /** Maximum length of a single line before its middle is elided. Default {@link MAX_LINE_LENGTH}. */
+    maxLineLength?: number;
+}
+
+export function truncateLine(line: string, maxLineLength: number = MAX_LINE_LENGTH): string {
+    if (line.length <= maxLineLength) {
         return line;
     }
-    const halfLength = Math.floor((MAX_LINE_LENGTH - 30) / 2);
+    const halfLength = Math.floor((maxLineLength - 30) / 2);
     const omittedCount = line.length - halfLength * 2;
     return `${line.slice(0, halfLength)} ... [${omittedCount} chars omitted] ... ${line.slice(-halfLength)}`;
 }
 
-export function combineAndTruncate(stdout: string, stderr: string): string {
+export function combineAndTruncate(stdout: string, stderr: string, options?: OutputTruncationOptions): string {
+    const head = options?.headLines ?? HEAD_LINES;
+    const tail = options?.tailLines ?? TAIL_LINES;
+    const grace = options?.graceLines ?? GRACE_LINES;
+    const maxLineLength = options?.maxLineLength ?? MAX_LINE_LENGTH;
+
     const trimmedStdout = stdout.trim();
     const trimmedStderr = stderr.trim();
 
@@ -108,13 +130,13 @@ export function combineAndTruncate(stdout: string, stderr: string): string {
 
     const lines = output.split('\n');
 
-    if (lines.length <= HEAD_LINES + TAIL_LINES + GRACE_LINES) {
-        return lines.map(truncateLine).join('\n');
+    if (lines.length <= head + tail + grace) {
+        return lines.map(line => truncateLine(line, maxLineLength)).join('\n');
     }
 
-    const headLines = lines.slice(0, HEAD_LINES).map(truncateLine);
-    const tailLines = lines.slice(-TAIL_LINES).map(truncateLine);
-    const omittedCount = lines.length - HEAD_LINES - TAIL_LINES;
+    const headLines = lines.slice(0, head).map(line => truncateLine(line, maxLineLength));
+    const tailLines = lines.slice(-tail).map(line => truncateLine(line, maxLineLength));
+    const omittedCount = lines.length - head - tail;
 
     return [...headLines, `\n... [${omittedCount} lines omitted] ...\n`, ...tailLines].join('\n');
 }