@theia/ai-terminal 1.77.0-next.57 → 1.77.0-next.63

package/lib/browser/shell-execution-tool.d.ts

@@ -2,15 +2,23 @@ import { ToolRequest } from '@theia/ai-core';
 import { ShellCommandPermissionService } from './shell-command-permission-service';
 import { AbstractShellExecutionTool } from './abstract-shell-execution-tool';
 import { ShellExecutionToolResult, ShellExecutionCanceledResult } from '../common/shell-execution-server';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
 export declare class ShellExecutionTool extends AbstractShellExecutionTool {
     protected readonly shellCommandPermissionService: ShellCommandPermissionService;
+    protected readonly envVariablesServer: EnvVariablesServer;
     getTool(): ToolRequest;
     protected executeCommand(argString: string, ctx?: unknown): Promise<ShellExecutionToolResult | ShellExecutionCanceledResult>;
     /**
      * Resolves a cwd value to an absolute filesystem path.
-     * Handles: undefined (falls back to workspace root), absolute paths (pass-through),
-     * root-relative paths (<rootName>/...), and bare root names.
+     * Handles: undefined (falls back to the workspace root in a single-root workspace), absolute paths
+     * and `file://` URIs, `~` for the home directory, root-prefixed paths (`<rootName>/...`) and bare
+     * root names, with the root names of {@link WorkspaceService.getRootNames}.
      */
-    private resolveCwd;
+    protected resolveCwd(cwd: string | undefined): Promise<string>;
+    protected exampleRootName(): string;
+    /**
+     * Lists the workspace root names with their locations, for error messages.
+     */
+    protected describeRoots(): string;
 }
 //# sourceMappingURL=shell-execution-tool.d.ts.map

package/lib/browser/shell-execution-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-execution-tool.d.ts","sourceRoot":"","sources":["../../src/browser/shell-execution-tool.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,WAAW,EAAoB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAEH,wBAAwB,EACxB,4BAA4B,EAC/B,MAAM,kCAAkC,CAAC;AAG1C,qBACa,kBAAmB,SAAQ,0BAA0B;IAG9D,SAAS,CAAC,QAAQ,CAAC,6BAA6B,EAAE,6BAA6B,CAAC;IAEhF,OAAO,IAAI,WAAW;cA2GN,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,wBAAwB,GAAG,4BAA4B,CAAC;IAelI;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAyCrB"}
+{"version":3,"file":"shell-execution-tool.d.ts","sourceRoot":"","sources":["../../src/browser/shell-execution-tool.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,WAAW,EAAoB,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAEH,wBAAwB,EACxB,4BAA4B,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE1E,qBACa,kBAAmB,SAAQ,0BAA0B;IAG9D,SAAS,CAAC,QAAQ,CAAC,6BAA6B,EAAE,6BAA6B,CAAC;IAGhF,SAAS,CAAC,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAC;IAE1D,OAAO,IAAI,WAAW;cAgHN,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,wBAAwB,GAAG,4BAA4B,CAAC;IAelI;;;;;OAKG;cACa,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IA6CpE,SAAS,CAAC,eAAe,IAAI,MAAM;IAInC;;OAEG;IACH,SAAS,CAAC,aAAa,IAAI,MAAM;CAIpC"}

package/lib/browser/shell-execution-tool.js

@@ -22,6 +22,7 @@ const shell_command_permission_service_1 = require("./shell-command-permission-s
 const abstract_shell_execution_tool_1 = require("./abstract-shell-execution-tool");
 const shell_execution_server_1 = require("../common/shell-execution-server");
 const core_1 = require("@theia/core");
+const env_variables_1 = require("@theia/core/lib/common/env-variables");
 let ShellExecutionTool = class ShellExecutionTool extends abstract_shell_execution_tool_1.AbstractShellExecutionTool {
     getTool() {
         return {
@@ -62,6 +63,10 @@ To avoid losing important information, limit output size in your commands:
 - Use wc -l to count lines before fetching full output
 - Redirect verbose output to /dev/null if not needed
 
+WORKING DIRECTORY: The command runs inside the directory given as cwd, so relative paths in the command
+are relative to it. In a multi-root workspace, cwd is required: a workspace root name such as "backend" is the
+root folder itself, not a folder to change into.
+
 TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer commands.`,
             parameters: {
                 type: 'object',
@@ -95,10 +100,11 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
                     },
                     cwd: {
                         type: 'string',
-                        description: 'Working directory for command execution. ' +
-                            'Use a workspace-relative path (e.g., "backend", "frontend/src") ' +
-                            'or an absolute filesystem path. ' +
-                            'If omitted, defaults to the workspace root (single-root workspaces only).'
+                        description: 'Working directory in which the command runs. ' +
+                            'Use a workspace root name (e.g., "backend"), a path starting with a root name (e.g., "backend/src"), ' +
+                            'as in the paths returned by the workspace tools, or an absolute filesystem path. ' +
+                            'The command starts inside this directory: with cwd "backend", do not `cd backend` in the command. ' +
+                            'Required in a multi-root workspace. If omitted in a single-root workspace, defaults to the workspace root.'
                     },
                     timeout: {
                         type: 'number',
@@ -133,45 +139,57 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
         const args = JSON.parse(argString);
         return this.runShellCommand({
             command: args.command,
-            cwd: this.resolveCwd(args.cwd),
+            cwd: await this.resolveCwd(args.cwd),
             timeout: args.timeout,
             ctx
         });
     }
     /**
      * Resolves a cwd value to an absolute filesystem path.
-     * Handles: undefined (falls back to workspace root), absolute paths (pass-through),
-     * root-relative paths (<rootName>/...), and bare root names.
+     * Handles: undefined (falls back to the workspace root in a single-root workspace), absolute paths
+     * and `file://` URIs, `~` for the home directory, root-prefixed paths (`<rootName>/...`) and bare
+     * root names, with the root names of {@link WorkspaceService.getRootNames}.
      */
-    resolveCwd(cwd) {
+    async resolveCwd(cwd) {
         const roots = this.workspaceService.tryGetRoots();
-        const rootNames = roots.map(r => r.resource.path.base);
         if (!cwd) {
             if (roots.length === 1) {
                 return roots[0].resource.path.fsPath();
             }
             throw new Error('A working directory (cwd) is required in a multi-root workspace. ' +
-                `Available workspace roots: ${rootNames.join(', ')}. ` +
-                'Provide one as cwd (e.g., "backend") or use a sub-path (e.g., "backend/src").');
+                `Provide a workspace root name as cwd (e.g., "${this.exampleRootName()}") or a path in it ` +
+                `(e.g., "${this.exampleRootName()}/src"). Available workspace roots: ${this.describeRoots()}.`);
+        }
+        if (cwd.startsWith('file://')) {
+            return new core_1.URI(cwd).path.fsPath();
         }
         const normalized = core_1.Path.normalizePathSeparator(cwd);
-        if (new core_1.Path(normalized).isAbsolute) {
+        if (new core_1.Path(normalized).isAbsolute || core_1.Path.isDrive(normalized.split('/')[0])) {
             return normalized;
         }
-        const segments = normalized.split('/');
-        for (const root of roots) {
-            if (root.resource.path.base === segments[0]) {
-                const rest = segments.slice(1).join('/');
-                const resolved = rest ? root.resource.resolve(rest) : root.resource;
-                return resolved.path.fsPath();
-            }
+        if (normalized === '~' || normalized.startsWith('~/')) {
+            const home = new core_1.URI(await this.envVariablesServer.getHomeDirUri());
+            return (normalized === '~' ? home : home.resolve(normalized.substring(2))).path.fsPath();
+        }
+        const rootPrefixed = this.workspaceService.resolveRootPrefixedPath(normalized);
+        if (rootPrefixed) {
+            return rootPrefixed.path.fsPath();
         }
         if (roots.length === 1) {
             return roots[0].resource.resolve(normalized).path.fsPath();
         }
         throw new Error(`Could not resolve working directory '${cwd}' to a workspace root. ` +
             'In a multi-root workspace, prefix paths with the workspace root name ' +
-            `(e.g., '${rootNames[0]}/path'). Available roots: ${rootNames.join(', ')}.`);
+            `(e.g., '${this.exampleRootName()}/path'). Available workspace roots: ${this.describeRoots()}.`);
+    }
+    exampleRootName() {
+        return this.workspaceService.getRootNames().keys().next().value ?? 'rootName';
+    }
+    /**
+     * Lists the workspace root names with their locations, for error messages.
+     */
+    describeRoots() {
+        return Array.from(this.workspaceService.getRootNames(), ([name, uri]) => `${name} (${uri.path.fsPath()})`).join(', ');
     }
 };
 exports.ShellExecutionTool = ShellExecutionTool;
@@ -179,6 +197,10 @@ tslib_1.__decorate([
     (0, inversify_1.inject)(shell_command_permission_service_1.ShellCommandPermissionService),
     tslib_1.__metadata("design:type", shell_command_permission_service_1.ShellCommandPermissionService)
 ], ShellExecutionTool.prototype, "shellCommandPermissionService", void 0);
+tslib_1.__decorate([
+    (0, inversify_1.inject)(env_variables_1.EnvVariablesServer),
+    tslib_1.__metadata("design:type", Object)
+], ShellExecutionTool.prototype, "envVariablesServer", void 0);
 exports.ShellExecutionTool = ShellExecutionTool = tslib_1.__decorate([
     (0, inversify_1.injectable)()
 ], ShellExecutionTool);

package/lib/browser/shell-execution-tool.js.map

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

package/lib/browser/shell-execution-tool.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shell-execution-tool.spec.d.ts.map

package/lib/browser/shell-execution-tool.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-execution-tool.spec.d.ts","sourceRoot":"","sources":["../../src/browser/shell-execution-tool.spec.ts"],"names":[],"mappings":""}

package/lib/browser/shell-execution-tool.spec.js

@@ -0,0 +1,122 @@
+"use strict";
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// 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
+// *****************************************************************************
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const jsdom_1 = require("@theia/core/lib/browser/test/jsdom");
+let disableJSDOM = (0, jsdom_1.enableJSDOM)();
+const frontend_application_config_provider_1 = require("@theia/core/lib/browser/frontend-application-config-provider");
+frontend_application_config_provider_1.FrontendApplicationConfigProvider.set({});
+const chai_1 = require("chai");
+const sinon = tslib_1.__importStar(require("sinon"));
+const core_1 = require("@theia/core");
+const uri_1 = tslib_1.__importDefault(require("@theia/core/lib/common/uri"));
+const inversify_1 = require("@theia/core/shared/inversify");
+const env_variables_1 = require("@theia/core/lib/common/env-variables");
+const workspace_service_1 = require("@theia/workspace/lib/browser/workspace-service");
+const with_workspace_service_defaults_1 = require("@theia/workspace/lib/browser/test/with-workspace-service-defaults");
+const shell_execution_server_1 = require("../common/shell-execution-server");
+const shell_command_permission_service_1 = require("./shell-command-permission-service");
+const shell_execution_tool_1 = require("./shell-execution-tool");
+disableJSDOM();
+describe('ShellExecutionTool working directory', () => {
+    let shellServer;
+    let tool;
+    let originalIsWindows;
+    before(() => {
+        disableJSDOM = (0, jsdom_1.enableJSDOM)();
+    });
+    after(() => {
+        disableJSDOM();
+    });
+    beforeEach(() => {
+        originalIsWindows = core_1.OS.backend.isWindows;
+        core_1.OS.backend.isWindows = false;
+    });
+    afterEach(() => {
+        core_1.OS.backend.isWindows = originalIsWindows;
+    });
+    const setUp = (roots) => {
+        const container = new inversify_1.Container();
+        shellServer = {
+            execute: sinon.stub().callsFake(async (request) => ({
+                success: true, exitCode: 0, stdout: '', stderr: '', duration: 0, resolvedCwd: request.cwd
+            })),
+            cancel: sinon.stub().resolves(true)
+        };
+        const workspaceService = (0, with_workspace_service_defaults_1.withWorkspaceServiceDefaults)({
+            tryGetRoots: () => roots.map(root => ({ resource: new uri_1.default(root), isDirectory: true }))
+        });
+        container.bind(shell_execution_server_1.ShellExecutionServer).toConstantValue(shellServer);
+        container.bind(workspace_service_1.WorkspaceService).toConstantValue(workspaceService);
+        container.bind(shell_command_permission_service_1.ShellCommandPermissionService).toConstantValue({});
+        container.bind(env_variables_1.EnvVariablesServer).toConstantValue({ getHomeDirUri: async () => 'file:///home/test' });
+        container.bind(shell_execution_tool_1.ShellExecutionTool).toSelf();
+        tool = container.get(shell_execution_tool_1.ShellExecutionTool);
+    };
+    const run = (args) => Promise.resolve(tool.getTool().handler(JSON.stringify({ command: 'pwd', description: 'Print the working directory', ...args }), undefined));
+    const executedCwd = () => shellServer.execute.lastCall.args[0].cwd;
+    it('defaults to the workspace root in a single-root workspace', async () => {
+        setUp(['file:///ws/theia']);
+        await run({});
+        (0, chai_1.expect)(executedCwd()).to.equal('/ws/theia');
+    });
+    it('runs in the root directory named by cwd, so the command must not change into it again', async () => {
+        setUp(['file:///ws/theia', 'file:///ws/other']);
+        await run({ cwd: 'theia' });
+        (0, chai_1.expect)(executedCwd()).to.equal('/ws/theia');
+    });
+    it('resolves a root name shared with another root by its parent-qualified name', async () => {
+        setUp(['file:///x/app', 'file:///y/app']);
+        await run({ cwd: 'y/app/src' });
+        (0, chai_1.expect)(executedCwd()).to.equal('/y/app/src');
+    });
+    it('resolves absolute paths, file URIs and the home directory', async () => {
+        setUp(['file:///ws/theia', 'file:///ws/other']);
+        await run({ cwd: '/tmp/build' });
+        (0, chai_1.expect)(executedCwd()).to.equal('/tmp/build');
+        await run({ cwd: 'file:///ws/other/src' });
+        (0, chai_1.expect)(executedCwd()).to.equal('/ws/other/src');
+        await run({ cwd: '~/projects' });
+        (0, chai_1.expect)(executedCwd()).to.equal('/home/test/projects');
+    });
+    it('rejects a basename shared by several roots, listing the root names', async () => {
+        setUp(['file:///x/app', 'file:///y/app']);
+        let error;
+        try {
+            await run({ cwd: 'app' });
+        }
+        catch (e) {
+            error = e;
+        }
+        (0, chai_1.expect)(error?.message).to.contain('x/app (/x/app), y/app (/y/app)');
+        (0, chai_1.expect)(shellServer.execute.called).to.be.false;
+    });
+    // Agents often omit cwd on their first call and get this error (D1). It is required by design.
+    it('requires cwd in a multi-root workspace (D1)', async () => {
+        setUp(['file:///ws/theia', 'file:///ws/other']);
+        let error;
+        try {
+            await run({});
+        }
+        catch (e) {
+            error = e;
+        }
+        (0, chai_1.expect)(error?.message).to.contain('A working directory (cwd) is required in a multi-root workspace');
+        (0, chai_1.expect)(shellServer.execute.called).to.be.false;
+    });
+});
+//# sourceMappingURL=shell-execution-tool.spec.js.map

package/lib/browser/shell-execution-tool.spec.js.map

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

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@theia/ai-terminal",
-  "version": "1.77.0-next.57+81ea5f939",
+  "version": "1.77.0-next.63+046af0812",
   "description": "Theia - AI Terminal Extension",
   "dependencies": {
-    "@theia/ai-chat": "1.77.0-next.57+81ea5f939",
-    "@theia/ai-chat-ui": "1.77.0-next.57+81ea5f939",
-    "@theia/ai-core": "1.77.0-next.57+81ea5f939",
-    "@theia/core": "1.77.0-next.57+81ea5f939",
-    "@theia/terminal": "1.77.0-next.57+81ea5f939",
-    "@theia/workspace": "1.77.0-next.57+81ea5f939",
+    "@theia/ai-chat": "1.77.0-next.63+046af0812",
+    "@theia/ai-chat-ui": "1.77.0-next.63+046af0812",
+    "@theia/ai-core": "1.77.0-next.63+046af0812",
+    "@theia/core": "1.77.0-next.63+046af0812",
+    "@theia/terminal": "1.77.0-next.63+046af0812",
+    "@theia/workspace": "1.77.0-next.63+046af0812",
     "tslib": "^2.8.1",
     "zod": "^4.4.3"
   },
@@ -51,5 +51,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "81ea5f939c40c905de91083d07e284bfd7437fac"
+  "gitHead": "046af0812516f46f2bf7ce3357cca0b672159b20"
 }

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

@@ -0,0 +1,132 @@
+// *****************************************************************************
+// Copyright (C) 2026 STMicroelectronics and others.
+//
+// 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 { OS } from '@theia/core';
+import URI from '@theia/core/lib/common/uri';
+import { Container } from '@theia/core/shared/inversify';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
+import { WorkspaceService } from '@theia/workspace/lib/browser/workspace-service';
+import { withWorkspaceServiceDefaults } from '@theia/workspace/lib/browser/test/with-workspace-service-defaults';
+import { ShellExecutionRequest, ShellExecutionServer } from '../common/shell-execution-server';
+import { ShellCommandPermissionService } from './shell-command-permission-service';
+import { ShellExecutionTool } from './shell-execution-tool';
+
+disableJSDOM();
+
+describe('ShellExecutionTool working directory', () => {
+
+    let shellServer: { execute: sinon.SinonStub; cancel: sinon.SinonStub };
+    let tool: ShellExecutionTool;
+
+    let originalIsWindows: boolean;
+    before(() => {
+        disableJSDOM = enableJSDOM();
+    });
+    after(() => {
+        disableJSDOM();
+    });
+    beforeEach(() => {
+        originalIsWindows = OS.backend.isWindows;
+        OS.backend.isWindows = false;
+    });
+    afterEach(() => {
+        OS.backend.isWindows = originalIsWindows;
+    });
+
+    const setUp = (roots: string[]): void => {
+        const container = new Container();
+        shellServer = {
+            execute: sinon.stub().callsFake(async (request: ShellExecutionRequest) => ({
+                success: true, exitCode: 0, stdout: '', stderr: '', duration: 0, resolvedCwd: request.cwd
+            })),
+            cancel: sinon.stub().resolves(true)
+        };
+        const workspaceService = withWorkspaceServiceDefaults({
+            tryGetRoots: () => roots.map(root => ({ resource: new URI(root), isDirectory: true }))
+        });
+        container.bind(ShellExecutionServer).toConstantValue(shellServer as unknown as ShellExecutionServer);
+        container.bind(WorkspaceService).toConstantValue(workspaceService);
+        container.bind(ShellCommandPermissionService).toConstantValue({} as ShellCommandPermissionService);
+        container.bind(EnvVariablesServer).toConstantValue({ getHomeDirUri: async () => 'file:///home/test' } as unknown as EnvVariablesServer);
+        container.bind(ShellExecutionTool).toSelf();
+        tool = container.get(ShellExecutionTool);
+    };
+
+    const run = (args: { cwd?: string }): Promise<unknown> =>
+        Promise.resolve(tool.getTool().handler(JSON.stringify({ command: 'pwd', description: 'Print the working directory', ...args }), undefined));
+
+    const executedCwd = (): string | undefined => (shellServer.execute.lastCall.args[0] as ShellExecutionRequest).cwd;
+
+    it('defaults to the workspace root in a single-root workspace', async () => {
+        setUp(['file:///ws/theia']);
+        await run({});
+        expect(executedCwd()).to.equal('/ws/theia');
+    });
+
+    it('runs in the root directory named by cwd, so the command must not change into it again', async () => {
+        setUp(['file:///ws/theia', 'file:///ws/other']);
+        await run({ cwd: 'theia' });
+        expect(executedCwd()).to.equal('/ws/theia');
+    });
+
+    it('resolves a root name shared with another root by its parent-qualified name', async () => {
+        setUp(['file:///x/app', 'file:///y/app']);
+        await run({ cwd: 'y/app/src' });
+        expect(executedCwd()).to.equal('/y/app/src');
+    });
+
+    it('resolves absolute paths, file URIs and the home directory', async () => {
+        setUp(['file:///ws/theia', 'file:///ws/other']);
+        await run({ cwd: '/tmp/build' });
+        expect(executedCwd()).to.equal('/tmp/build');
+        await run({ cwd: 'file:///ws/other/src' });
+        expect(executedCwd()).to.equal('/ws/other/src');
+        await run({ cwd: '~/projects' });
+        expect(executedCwd()).to.equal('/home/test/projects');
+    });
+
+    it('rejects a basename shared by several roots, listing the root names', async () => {
+        setUp(['file:///x/app', 'file:///y/app']);
+        let error: Error | undefined;
+        try {
+            await run({ cwd: 'app' });
+        } catch (e) {
+            error = e;
+        }
+        expect(error?.message).to.contain('x/app (/x/app), y/app (/y/app)');
+        expect(shellServer.execute.called).to.be.false;
+    });
+
+    // Agents often omit cwd on their first call and get this error (D1). It is required by design.
+    it('requires cwd in a multi-root workspace (D1)', async () => {
+        setUp(['file:///ws/theia', 'file:///ws/other']);
+        let error: Error | undefined;
+        try {
+            await run({});
+        } catch (e) {
+            error = e;
+        }
+        expect(error?.message).to.contain('A working directory (cwd) is required in a multi-root workspace');
+        expect(shellServer.execute.called).to.be.false;
+    });
+});

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

@@ -23,7 +23,8 @@ import {
     ShellExecutionToolResult,
     ShellExecutionCanceledResult
 } from '../common/shell-execution-server';
-import { Path } from '@theia/core';
+import { Path, URI } from '@theia/core';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
 
 @injectable()
 export class ShellExecutionTool extends AbstractShellExecutionTool {
@@ -31,6 +32,9 @@ export class ShellExecutionTool extends AbstractShellExecutionTool {
     @inject(ShellCommandPermissionService)
     protected readonly shellCommandPermissionService: ShellCommandPermissionService;
 
+    @inject(EnvVariablesServer)
+    protected readonly envVariablesServer: EnvVariablesServer;
+
     getTool(): ToolRequest {
         return {
             id: SHELL_EXECUTION_FUNCTION_ID,
@@ -70,6 +74,10 @@ To avoid losing important information, limit output size in your commands:
 - Use wc -l to count lines before fetching full output
 - Redirect verbose output to /dev/null if not needed
 
+WORKING DIRECTORY: The command runs inside the directory given as cwd, so relative paths in the command
+are relative to it. In a multi-root workspace, cwd is required: a workspace root name such as "backend" is the
+root folder itself, not a folder to change into.
+
 TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer commands.`,
             parameters: {
                 type: 'object',
@@ -103,10 +111,11 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
                     },
                     cwd: {
                         type: 'string',
-                        description: 'Working directory for command execution. ' +
-                            'Use a workspace-relative path (e.g., "backend", "frontend/src") ' +
-                            'or an absolute filesystem path. ' +
-                            'If omitted, defaults to the workspace root (single-root workspaces only).'
+                        description: 'Working directory in which the command runs. ' +
+                            'Use a workspace root name (e.g., "backend"), a path starting with a root name (e.g., "backend/src"), ' +
+                            'as in the paths returned by the workspace tools, or an absolute filesystem path. ' +
+                            'The command starts inside this directory: with cwd "backend", do not `cd backend` in the command. ' +
+                            'Required in a multi-root workspace. If omitted in a single-root workspace, defaults to the workspace root.'
                     },
                     timeout: {
                         type: 'number',
@@ -147,7 +156,7 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
 
         return this.runShellCommand({
             command: args.command,
-            cwd: this.resolveCwd(args.cwd),
+            cwd: await this.resolveCwd(args.cwd),
             timeout: args.timeout,
             ctx
         });
@@ -155,37 +164,42 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
 
     /**
      * Resolves a cwd value to an absolute filesystem path.
-     * Handles: undefined (falls back to workspace root), absolute paths (pass-through),
-     * root-relative paths (<rootName>/...), and bare root names.
+     * Handles: undefined (falls back to the workspace root in a single-root workspace), absolute paths
+     * and `file://` URIs, `~` for the home directory, root-prefixed paths (`<rootName>/...`) and bare
+     * root names, with the root names of {@link WorkspaceService.getRootNames}.
      */
-    private resolveCwd(cwd: string | undefined): string {
+    protected async resolveCwd(cwd: string | undefined): Promise<string> {
         const roots = this.workspaceService.tryGetRoots();
 
-        const rootNames = roots.map(r => r.resource.path.base);
         if (!cwd) {
             if (roots.length === 1) {
                 return roots[0].resource.path.fsPath();
             }
             throw new Error(
                 'A working directory (cwd) is required in a multi-root workspace. ' +
-                `Available workspace roots: ${rootNames.join(', ')}. ` +
-                'Provide one as cwd (e.g., "backend") or use a sub-path (e.g., "backend/src").'
+                `Provide a workspace root name as cwd (e.g., "${this.exampleRootName()}") or a path in it ` +
+                `(e.g., "${this.exampleRootName()}/src"). Available workspace roots: ${this.describeRoots()}.`
             );
         }
 
+        if (cwd.startsWith('file://')) {
+            return new URI(cwd).path.fsPath();
+        }
+
         const normalized = Path.normalizePathSeparator(cwd);
 
-        if (new Path(normalized).isAbsolute) {
+        if (new Path(normalized).isAbsolute || Path.isDrive(normalized.split('/')[0])) {
             return normalized;
         }
 
-        const segments = normalized.split('/');
-        for (const root of roots) {
-            if (root.resource.path.base === segments[0]) {
-                const rest = segments.slice(1).join('/');
-                const resolved = rest ? root.resource.resolve(rest) : root.resource;
-                return resolved.path.fsPath();
-            }
+        if (normalized === '~' || normalized.startsWith('~/')) {
+            const home = new URI(await this.envVariablesServer.getHomeDirUri());
+            return (normalized === '~' ? home : home.resolve(normalized.substring(2))).path.fsPath();
+        }
+
+        const rootPrefixed = this.workspaceService.resolveRootPrefixedPath(normalized);
+        if (rootPrefixed) {
+            return rootPrefixed.path.fsPath();
         }
 
         if (roots.length === 1) {
@@ -195,8 +209,19 @@ TIMEOUT: Default 2 minutes, max 10 minutes. Specify higher timeout for longer co
         throw new Error(
             `Could not resolve working directory '${cwd}' to a workspace root. ` +
             'In a multi-root workspace, prefix paths with the workspace root name ' +
-            `(e.g., '${rootNames[0]}/path'). Available roots: ${rootNames.join(', ')}.`
+            `(e.g., '${this.exampleRootName()}/path'). Available workspace roots: ${this.describeRoots()}.`
         );
     }
 
+    protected exampleRootName(): string {
+        return this.workspaceService.getRootNames().keys().next().value ?? 'rootName';
+    }
+
+    /**
+     * Lists the workspace root names with their locations, for error messages.
+     */
+    protected describeRoots(): string {
+        return Array.from(this.workspaceService.getRootNames(), ([name, uri]) => `${name} (${uri.path.fsPath()})`).join(', ');
+    }
+
 }