@theia/ai-tool-sketchpad 1.74.0-next.53

package/lib/common/sketched-tool.js

@@ -0,0 +1,85 @@
+"use strict";
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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 });
+exports.SketchedToolService = exports.SKETCHED_TOOLS_PROVIDER_NAME = exports.SketchedToolDefinition = void 0;
+const core_1 = require("@theia/core");
+var SketchedToolDefinition;
+(function (SketchedToolDefinition) {
+    function is(obj) {
+        // eslint-disable-next-line no-null/no-null
+        if (typeof obj !== 'object' || obj === null) {
+            return false;
+        }
+        const candidate = obj;
+        if (typeof candidate.id !== 'string' || typeof candidate.name !== 'string') {
+            return false;
+        }
+        if (typeof candidate.description !== 'string') {
+            return false;
+        }
+        if (!Array.isArray(candidate.parameters)) {
+            return false;
+        }
+        if (candidate.returnMode !== undefined && candidate.returnMode !== 'static' && candidate.returnMode !== 'askAtRuntime') {
+            return false;
+        }
+        // returnMode and staticReturn are optional here; normalize() fills in defaults.
+        if (candidate.staticReturn !== undefined && typeof candidate.staticReturn !== 'string') {
+            return false;
+        }
+        return true;
+    }
+    SketchedToolDefinition.is = is;
+    function normalize(obj) {
+        return {
+            ...obj,
+            returnMode: obj.returnMode ?? 'static',
+            staticReturn: obj.staticReturn ?? ''
+        };
+    }
+    SketchedToolDefinition.normalize = normalize;
+    /**
+     * Pattern accepted as a tool name by most LLM providers (e.g. OpenAI, Anthropic).
+     * The name is also used as the id under which the tool is registered, so it must be unique.
+     */
+    SketchedToolDefinition.NAME_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;
+    /**
+     * Validates a tool name for use as a registered tool id.
+     *
+     * @param name the name to validate
+     * @param existingTools the currently defined tools, used to check for name collisions
+     * @param selfId the id of the tool being edited, so it is not compared against itself
+     * @returns a localized error message if the name is invalid, otherwise `undefined`
+     */
+    function validateName(name, existingTools, selfId) {
+        const trimmed = name.trim();
+        if (!trimmed) {
+            return core_1.nls.localize('theia/ai-tool-sketchpad/nameEmpty', 'Tool name must not be empty.');
+        }
+        if (!SketchedToolDefinition.NAME_PATTERN.test(trimmed)) {
+            return core_1.nls.localize('theia/ai-tool-sketchpad/nameInvalid', 'Tool name may only contain letters, digits, underscores and hyphens (1-128 characters).');
+        }
+        if (existingTools.some(tool => tool.id !== selfId && tool.name.trim() === trimmed)) {
+            return core_1.nls.localize('theia/ai-tool-sketchpad/nameDuplicate', 'A tool with this name already exists.');
+        }
+        return undefined;
+    }
+    SketchedToolDefinition.validateName = validateName;
+})(SketchedToolDefinition || (exports.SketchedToolDefinition = SketchedToolDefinition = {}));
+exports.SKETCHED_TOOLS_PROVIDER_NAME = 'ai-tool-sketchpad';
+exports.SketchedToolService = Symbol('SketchedToolService');
+//# sourceMappingURL=sketched-tool.js.map

package/lib/common/sketched-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sketched-tool.js","sourceRoot":"","sources":["../../src/common/sketched-tool.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,+CAA+C;AAC/C,EAAE;AACF,2EAA2E;AAC3E,mEAAmE;AACnE,wCAAwC;AACxC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,uDAAuD;AACvD,EAAE;AACF,gFAAgF;AAChF,gFAAgF;;;AAEhF,sCAAyC;AA4BzC,IAAiB,sBAAsB,CA8DtC;AA9DD,WAAiB,sBAAsB;IACnC,SAAgB,EAAE,CAAC,GAAY;QAC3B,2CAA2C;QAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,MAAM,SAAS,GAAG,GAA8B,CAAC;QACjD,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzE,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,OAAO,SAAS,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS,IAAI,SAAS,CAAC,UAAU,KAAK,QAAQ,IAAI,SAAS,CAAC,UAAU,KAAK,cAAc,EAAE,CAAC;YACrH,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,gFAAgF;QAChF,IAAI,SAAS,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;YACrF,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAvBe,yBAAE,KAuBjB,CAAA;IAED,SAAgB,SAAS,CAAC,GAA2B;QACjD,OAAO;YACH,GAAG,GAAG;YACN,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,QAAQ;YACtC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;SACvC,CAAC;IACN,CAAC;IANe,gCAAS,YAMxB,CAAA;IAED;;;OAGG;IACU,mCAAY,GAAG,wBAAwB,CAAC;IAErD;;;;;;;OAOG;IACH,SAAgB,YAAY,CAAC,IAAY,EAAE,aAAuC,EAAE,MAAe;QAC/F,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,UAAG,CAAC,QAAQ,CAAC,mCAAmC,EAAE,8BAA8B,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,CAAC,uBAAA,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO,UAAG,CAAC,QAAQ,CAAC,qCAAqC,EACrD,yFAAyF,CAAC,CAAC;QACnG,CAAC;QACD,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,OAAO,CAAC,EAAE,CAAC;YACjF,OAAO,UAAG,CAAC,QAAQ,CAAC,uCAAuC,EAAE,uCAAuC,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;IAbe,mCAAY,eAa3B,CAAA;AACL,CAAC,EA9DgB,sBAAsB,sCAAtB,sBAAsB,QA8DtC;AAEY,QAAA,4BAA4B,GAAG,mBAAmB,CAAC;AAEnD,QAAA,mBAAmB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC"}

package/lib/package.spec.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=package.spec.d.ts.map

package/lib/package.spec.d.ts.map

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

package/lib/package.spec.js

@@ -0,0 +1,24 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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
+// *****************************************************************************
+/*
+ * This is a placeholder for tests that the extension package should implement
+ * but as yet does not.
+ * Please delete this file when a real test is implemented.
+ */
+describe('ai-tool-sketchpad package', () => {
+    it('placeholder to enable mocha', () => true);
+});
+//# sourceMappingURL=package.spec.js.map

package/lib/package.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.spec.js","sourceRoot":"","sources":["../src/package.spec.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,+CAA+C;AAC/C,EAAE;AACF,2EAA2E;AAC3E,mEAAmE;AACnE,wCAAwC;AACxC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,uDAAuD;AACvD,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAEhF;;;;GAIG;AAEH,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@theia/ai-tool-sketchpad",
+  "version": "1.74.0-next.53+8e4e53136c6",
+  "description": "Theia - AI Tool Sketchpad for defining ad-hoc LLM tools",
+  "dependencies": {
+    "@theia/ai-core": "1.74.0-next.53+8e4e53136c6",
+    "@theia/core": "1.74.0-next.53+8e4e53136c6",
+    "@theia/filesystem": "1.74.0-next.53+8e4e53136c6",
+    "js-yaml": "^4.1.0",
+    "tslib": "^2.6.2"
+  },
+  "main": "lib/common",
+  "publishConfig": {
+    "access": "public"
+  },
+  "theiaExtensions": [
+    {
+      "frontend": "lib/browser/frontend-module"
+    }
+  ],
+  "keywords": [
+    "theia-extension"
+  ],
+  "license": "EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eclipse-theia/theia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eclipse-theia/theia/issues"
+  },
+  "homepage": "https://github.com/eclipse-theia/theia",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "theiaext build",
+    "clean": "theiaext clean",
+    "compile": "theiaext compile",
+    "lint": "theiaext lint",
+    "test": "theiaext test",
+    "watch": "theiaext watch"
+  },
+  "devDependencies": {
+    "@theia/ext-scripts": "1.73.0"
+  },
+  "nyc": {
+    "extends": "../../configs/nyc.json"
+  },
+  "gitHead": "8e4e53136c69cec1ef61747c7269f9a935b76574"
+}

package/src/browser/frontend-module.ts

@@ -0,0 +1,43 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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 '../../src/browser/style/index.css';
+
+import { ContainerModule } from '@theia/core/shared/inversify';
+import { FrontendApplicationContribution, WidgetFactory, bindViewContribution } from '@theia/core/lib/browser';
+import { SketchedToolService } from '../common';
+import { SketchedToolServiceImpl } from './sketched-tool-service';
+import { SketchedToolWidget } from './sketched-tool-widget';
+import { SketchedToolViewContribution } from './sketched-tool-contribution';
+
+export default new ContainerModule(bind => {
+    // Service
+    bind(SketchedToolServiceImpl).toSelf().inSingletonScope();
+    bind(SketchedToolService).toService(SketchedToolServiceImpl);
+    bind(FrontendApplicationContribution).toService(SketchedToolServiceImpl);
+
+    // Widget
+    bind(SketchedToolWidget).toSelf();
+    bind(WidgetFactory)
+        .toDynamicValue(ctx => ({
+            id: SketchedToolWidget.ID,
+            createWidget: () => ctx.container.get(SketchedToolWidget)
+        }))
+        .inSingletonScope();
+
+    // View contribution
+    bindViewContribution(bind, SketchedToolViewContribution);
+});

package/src/browser/index.ts

@@ -0,0 +1,19 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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
+// *****************************************************************************
+
+export * from './sketched-tool-service';
+export * from './sketched-tool-widget';
+export * from './sketched-tool-contribution';

package/src/browser/sketched-tool-contribution.ts

@@ -0,0 +1,37 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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 { injectable } from '@theia/core/shared/inversify';
+import { AIViewContribution } from '@theia/ai-core/lib/browser';
+import { SketchedToolWidget } from './sketched-tool-widget';
+
+export const SKETCHED_TOOL_TOGGLE_COMMAND_ID = 'aiToolSketchpad:toggle';
+
+@injectable()
+export class SketchedToolViewContribution extends AIViewContribution<SketchedToolWidget> {
+
+    constructor() {
+        super({
+            widgetId: SketchedToolWidget.ID,
+            widgetName: SketchedToolWidget.LABEL,
+            defaultWidgetOptions: {
+                area: 'main',
+                rank: 200
+            },
+            toggleCommandId: SKETCHED_TOOL_TOGGLE_COMMAND_ID
+        });
+    }
+}

package/src/browser/sketched-tool-service.ts

@@ -0,0 +1,282 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource 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 { DisposableCollection, Emitter, Event, nls, URI } from '@theia/core';
+import { FrontendApplicationContribution, QuickInputService } from '@theia/core/lib/browser';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
+import { BinaryBuffer } from '@theia/core/lib/common/buffer';
+import { inject, injectable, postConstruct } from '@theia/core/shared/inversify';
+import { FileService } from '@theia/filesystem/lib/browser/file-service';
+import { FileChangesEvent } from '@theia/filesystem/lib/common/files';
+import {
+    ToolInvocationRegistry,
+    ToolRequest,
+    ToolRequestParameters,
+    ToolRequestParameterProperty
+} from '@theia/ai-core';
+import { dump, load } from 'js-yaml';
+import {
+    SketchedToolDefinition,
+    SketchedToolParameterDefinition,
+    SketchedToolService,
+    SKETCHED_TOOLS_PROVIDER_NAME
+} from '../common';
+
+const SKETCHED_TOOLS_FILENAME = 'sketchedTools.yml';
+
+@injectable()
+export class SketchedToolServiceImpl implements SketchedToolService, FrontendApplicationContribution {
+
+    @inject(FileService)
+    protected readonly fileService: FileService;
+
+    @inject(EnvVariablesServer)
+    protected readonly envVariablesServer: EnvVariablesServer;
+
+    @inject(ToolInvocationRegistry)
+    protected readonly toolInvocationRegistry: ToolInvocationRegistry;
+
+    @inject(QuickInputService)
+    protected readonly quickInputService: QuickInputService;
+
+    protected tools: SketchedToolDefinition[] = [];
+    protected fileUri: URI | undefined;
+    protected readonly toDispose = new DisposableCollection();
+    protected loading = false;
+    /** The content we last wrote to disk, used to ignore file-watch events triggered by our own writes. */
+    protected lastPersistedContent: string | undefined;
+
+    protected readonly onDidChangeSketchedToolsEmitter = new Emitter<void>();
+    readonly onDidChangeSketchedTools: Event<void> = this.onDidChangeSketchedToolsEmitter.event;
+
+    @postConstruct()
+    protected init(): void {
+        this.toDispose.push(this.onDidChangeSketchedToolsEmitter);
+    }
+
+    async onStart(): Promise<void> {
+        this.fileUri = await this.resolveFileUri();
+        await this.loadFromDisk();
+        this.watchFile();
+    }
+
+    getSketchedTools(): SketchedToolDefinition[] {
+        return [...this.tools];
+    }
+
+    async addSketchedTool(tool: SketchedToolDefinition): Promise<void> {
+        this.tools.push(tool);
+        this.registerAllTools();
+        await this.persistToDisk();
+        this.onDidChangeSketchedToolsEmitter.fire();
+    }
+
+    async updateSketchedTool(tool: SketchedToolDefinition): Promise<void> {
+        const index = this.tools.findIndex(t => t.id === tool.id);
+        if (index >= 0) {
+            this.tools[index] = tool;
+        } else {
+            this.tools.push(tool);
+        }
+        this.registerAllTools();
+        await this.persistToDisk();
+        this.onDidChangeSketchedToolsEmitter.fire();
+    }
+
+    async removeSketchedTool(toolId: string): Promise<void> {
+        this.tools = this.tools.filter(t => t.id !== toolId);
+        this.registerAllTools();
+        await this.persistToDisk();
+        this.onDidChangeSketchedToolsEmitter.fire();
+    }
+
+    protected async resolveFileUri(): Promise<URI> {
+        const configDirUri = await this.envVariablesServer.getConfigDirUri();
+        return new URI(configDirUri).resolve('prompt-templates').resolve(SKETCHED_TOOLS_FILENAME);
+    }
+
+    protected async loadFromDisk(): Promise<void> {
+        if (!this.fileUri) {
+            return;
+        }
+        this.loading = true;
+        try {
+            const exists = await this.fileService.exists(this.fileUri);
+            if (!exists) {
+                this.tools = [];
+                this.registerAllTools();
+                return;
+            }
+            const fileContent = await this.fileService.read(this.fileUri, { encoding: 'utf-8' });
+            if (fileContent.value === this.lastPersistedContent) {
+                // This change was triggered by our own write; the in-memory state is already up to date.
+                return;
+            }
+            const doc = load(fileContent.value);
+            if (Array.isArray(doc)) {
+                // Skip invalid entries rather than discarding all tools if one entry is malformed.
+                const valid = doc.filter(entry => SketchedToolDefinition.is(entry)) as SketchedToolDefinition[];
+                const skipped = doc.length - valid.length;
+                if (skipped > 0) {
+                    console.debug(`Skipped ${skipped} invalid entr${skipped === 1 ? 'y' : 'ies'} in ${SKETCHED_TOOLS_FILENAME}.`);
+                }
+                this.tools = valid.map(SketchedToolDefinition.normalize);
+            } else {
+                console.debug(`Invalid ${SKETCHED_TOOLS_FILENAME} content, ignoring.`);
+                this.tools = [];
+            }
+            this.registerAllTools();
+            this.onDidChangeSketchedToolsEmitter.fire();
+        } catch (e) {
+            console.debug(`Error loading ${SKETCHED_TOOLS_FILENAME}: ${e.message}`, e);
+        } finally {
+            this.loading = false;
+        }
+    }
+
+    onStop(): void {
+        this.toDispose.dispose();
+    }
+
+    protected async persistToDisk(): Promise<void> {
+        if (!this.fileUri) {
+            return;
+        }
+        try {
+            const yamlContent = dump(this.tools, { lineWidth: -1 });
+            const buffer = BinaryBuffer.fromString(yamlContent);
+            if (await this.fileService.exists(this.fileUri)) {
+                await this.fileService.writeFile(this.fileUri, buffer);
+            } else {
+                await this.fileService.createFile(this.fileUri, buffer);
+            }
+            this.lastPersistedContent = yamlContent;
+        } catch (e) {
+            console.error(`Error persisting ${SKETCHED_TOOLS_FILENAME}: ${e.message}`, e);
+        }
+    }
+
+    protected watchFile(): void {
+        if (!this.fileUri) {
+            return;
+        }
+        const parentUri = this.fileUri.parent;
+        this.toDispose.push(this.fileService.watch(parentUri));
+        const listener = this.fileService.onDidFilesChange((event: FileChangesEvent) => {
+            if (this.fileUri && event.contains(this.fileUri) && !this.loading) {
+                this.loadFromDisk();
+            }
+        });
+        this.toDispose.push(listener);
+    }
+
+    protected registerAllTools(): void {
+        this.toolInvocationRegistry.unregisterAllTools(SKETCHED_TOOLS_PROVIDER_NAME);
+        // Guard against invalid or duplicate names in hand-edited YAML: the name is the registered id,
+        // so an invalid name is uncallable and a duplicate would collide. Register the first valid one.
+        const registeredNames = new Set<string>();
+        for (const def of this.tools) {
+            const name = def.name.trim();
+            if (!SketchedToolDefinition.NAME_PATTERN.test(name)) {
+                console.warn(`Skipping sketched tool "${def.name}": name is empty or contains invalid characters.`);
+                continue;
+            }
+            if (registeredNames.has(name)) {
+                console.warn(`Skipping sketched tool "${name}": another tool with the same name is already registered.`);
+                continue;
+            }
+            registeredNames.add(name);
+            this.toolInvocationRegistry.registerTool(this.toToolRequest(def, name));
+        }
+    }
+
+    protected toToolRequest(def: SketchedToolDefinition, name: string): ToolRequest {
+        const parameters = this.convertParameters(def.parameters);
+        return {
+            // The readable name doubles as the id so chat completions insert a meaningful reference;
+            // the internal UUID (def.id) remains the persistence key, keeping renames lossless.
+            id: name,
+            name,
+            description: def.description,
+            providerName: SKETCHED_TOOLS_PROVIDER_NAME,
+            parameters,
+            handler: async (argString: string) => {
+                if (def.returnMode === 'askAtRuntime') {
+                    return this.askUserForReturnValue(name, argString);
+                }
+                return def.staticReturn;
+            }
+        };
+    }
+
+    protected async askUserForReturnValue(toolName: string, argString: string): Promise<string> {
+        const result = await this.quickInputService.input({
+            prompt: nls.localize('theia/ai-tool-sketchpad/askReturnPrompt',
+                'Tool "{0}" was called with: {1}', toolName, argString),
+            placeHolder: nls.localize('theia/ai-tool-sketchpad/askReturnPlaceholder',
+                'Enter the return value for this tool call...')
+        });
+        return result ?? '';
+    }
+
+    protected convertParameters(params: SketchedToolParameterDefinition[]): ToolRequestParameters {
+        const properties: Record<string, ToolRequestParameterProperty> = {};
+        const required: string[] = [];
+
+        for (const param of params) {
+            properties[param.name] = this.convertParameterProperty(param);
+            if (param.required) {
+                required.push(param.name);
+            }
+        }
+
+        return {
+            type: 'object',
+            properties,
+            ...(required.length > 0 ? { required } : {})
+        };
+    }
+
+    protected convertParameterProperty(param: SketchedToolParameterDefinition): ToolRequestParameterProperty {
+        const prop: ToolRequestParameterProperty = {
+            type: param.type,
+            description: param.description
+        };
+
+        if (param.type === 'object' && param.properties && param.properties.length > 0) {
+            const nested = this.convertParameters(param.properties);
+            prop.properties = nested.properties;
+            if (nested.required && nested.required.length > 0) {
+                prop.required = nested.required;
+            }
+        }
+
+        if (param.type === 'array' && param.itemType) {
+            if (param.itemType === 'object' && param.itemProperties && param.itemProperties.length > 0) {
+                const nested = this.convertParameters(param.itemProperties);
+                prop.items = {
+                    type: 'object',
+                    properties: nested.properties,
+                    ...(nested.required && nested.required.length > 0 ? { required: nested.required } : {})
+                };
+            } else {
+                prop.items = { type: param.itemType };
+            }
+        }
+
+        return prop;
+    }
+}