[onechat] implement tool namespaces (#233854)

## Summary

Implement the tool namespacing strategy as defined in the corresponding
RFC

- move/rename our tools to the `platform.core.*` namespace
- add a `readonly` attribute on all tool definitions (built-in tools are
readonly, users tools are not)
- change tool validation logic to handle protected namespaces (and get
rid of the old `.prefix` format we were using)
- remove labels from our tools

## Screenshots

**listing**

<img width="1251" height="813" alt="Screenshot 2025-09-03 at 17 04 14"
src="https://github.com/user-attachments/assets/d47e7489-8487-4306-8c20-0d9b080db16c"
/>

**validation**

<img width="1242" height="201" alt="Screenshot 2025-09-03 at 17 05 27"
src="https://github.com/user-attachments/assets/01720d35-327b-4193-96b8-676c7b679bf0"
/>

---------

Co-authored-by: kibanamachine <[email protected]>

Author: pgayvallet

x-pack/platform/packages/shared/onechat/onechat-common/index.ts

@@ -10,13 +10,10 @@ export {
   ToolType,
   type ToolDefinition,
   type ToolDefinitionWithSchema,
-  builtInToolIdPrefix,
-  builtinToolIds,
-  builtinTags,
+  platformCoreTools,
   defaultAgentToolIds,
   editableToolTypes,
   isReservedToolId,
-  isBuiltInToolId,
   type ByIdsToolSelection,
   type ToolSelection,
   isByIdsToolSelection,
@@ -31,15 +28,20 @@ export {
   type EsqlToolDefinition,
   type EsqlToolDefinitionWithSchema,
   EsqlToolFieldType,
-  idRegexp,
+  toolIdRegexp,
+  toolIdMaxLength,
   activeToolsCountWarningThreshold,
+  validateToolId,
   ToolResultType,
   type ToolResult,
   type ErrorResult,
   type QueryResult,
   type ResourceResult,
   type TabularDataResult,
   type OtherResult,
+  internalNamespaces as toolNamespaces,
+  protectedNamespaces as toolReservedNamespaces,
+  isInProtectedNamespace,
 } from './tools';
 export {
   OnechatErrorCode,

x-pack/platform/packages/shared/onechat/onechat-common/tools/constants.ts

@@ -6,18 +6,23 @@
  */
 
 import { ToolType } from './definition';
+import { internalNamespaces } from './namespaces';
+
+const platformCoreTool = (toolName: string) => {
+  return `${internalNamespaces.platformCore}.${toolName}`;
+};
 
 /**
  * Ids of built-in onechat tools
  */
-export const builtinToolIds = {
-  indexExplorer: '.index_explorer',
-  search: '.search',
-  listIndices: '.list_indices',
-  getIndexMapping: '.get_index_mapping',
-  getDocumentById: '.get_document_by_id',
-  generateEsql: '.generate_esql',
-  executeEsql: '.execute_esql',
+export const platformCoreTools = {
+  indexExplorer: platformCoreTool('index_explorer'),
+  search: platformCoreTool('search'),
+  listIndices: platformCoreTool('list_indices'),
+  getIndexMapping: platformCoreTool('get_index_mapping'),
+  getDocumentById: platformCoreTool('get_document_by_id'),
+  generateEsql: platformCoreTool('generate_esql'),
+  executeEsql: platformCoreTool('execute_esql'),
 } as const;
 
 /**
@@ -26,25 +31,12 @@ export const builtinToolIds = {
 export const editableToolTypes: ToolType[] = [ToolType.esql, ToolType.index_search];
 
 export const defaultAgentToolIds = [
-  builtinToolIds.search,
-  builtinToolIds.listIndices,
-  builtinToolIds.getIndexMapping,
-  builtinToolIds.getDocumentById,
+  platformCoreTools.search,
+  platformCoreTools.listIndices,
+  platformCoreTools.getIndexMapping,
+  platformCoreTools.getDocumentById,
 ];
 
-export const builtInToolIdPrefix = '.';
-export const reservedKeywords = ['new'];
-
-/**
- * Common set of tags used for platform tools.
- */
-export const builtinTags = {
-  /**
-   * Tag associated to tools related to data retrieval
-   */
-  retrieval: 'retrieval',
-} as const;
-
 /**
  * The number of active tools that will trigger a warning in the UI.
  * Agent will perform poorly if it has too many tools.

x-pack/platform/packages/shared/onechat/onechat-common/tools/definition.ts

@@ -43,9 +43,12 @@ export interface ToolDefinition<TConfig extends object = Record<string, unknown>
    * The description for this tool, which will be exposed to the LLM.
    */
   description: string;
+  /**
+   * Indicate whether this tool is editable by users or not.
+   */
+  readonly: boolean;
   /**
    * Optional list of tags attached to this tool.
-   * For built-in tools, this is specified during registration.
    */
   tags: string[];
   /**

x-pack/platform/packages/shared/onechat/onechat-common/tools/index.ts

@@ -6,11 +6,9 @@
  */
 
 export { ToolType, type ToolDefinition, type ToolDefinitionWithSchema } from './definition';
-export { isReservedToolId, isBuiltInToolId, idRegexp } from './tool_ids';
+export { isReservedToolId, validateToolId, toolIdRegexp, toolIdMaxLength } from './tool_ids';
 export {
-  builtinToolIds,
-  builtinTags,
-  builtInToolIdPrefix,
+  platformCoreTools,
   activeToolsCountWarningThreshold,
   defaultAgentToolIds,
   editableToolTypes,
@@ -49,3 +47,9 @@ export {
   type TabularDataResult,
   type OtherResult,
 } from './tool_result';
+export {
+  internalNamespaces,
+  protectedNamespaces,
+  isInProtectedNamespace,
+  hasProtectedNamespaceName,
+} from './namespaces';

x-pack/platform/packages/shared/onechat/onechat-common/tools/namespaces.test.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { isInProtectedNamespace } from './namespaces';
+
+describe('isInProtectedNamespace', () => {
+  it('returns true when the tool id is inside a protected namespace', () => {
+    expect(isInProtectedNamespace('platform.core.some_tool')).toBe(true);
+  });
+
+  it('returns true when the tool id is nested in a protected namespace', () => {
+    expect(isInProtectedNamespace('platform.core.nested.some_tool')).toBe(true);
+  });
+
+  it('returns false when the tool id is inside a part of a protected namespace', () => {
+    expect(isInProtectedNamespace('platform.some_tool')).toBe(false);
+  });
+});

x-pack/platform/packages/shared/onechat/onechat-common/tools/namespaces.ts

@@ -0,0 +1,38 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+/**
+ * List of internally used namespaces
+ * Note: those are not necessarily all protected.
+ */
+export const internalNamespaces = {
+  platformCore: 'platform.core',
+} as const;
+
+/**
+ * List of protected namespaces which can only be used by internal tools.
+ */
+export const protectedNamespaces: string[] = [internalNamespaces.platformCore];
+
+/**
+ * Checks if the provided tool name belongs to a protected namespace.
+ */
+export const isInProtectedNamespace = (toolName: string) => {
+  for (const namespace of protectedNamespaces) {
+    if (toolName.startsWith(`${namespace}.`)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Checks if the provided tool name belongs to a protected namespace.
+ */
+export const hasProtectedNamespaceName = (toolName: string) => {
+  return protectedNamespaces.includes(toolName);
+};

x-pack/platform/packages/shared/onechat/onechat-common/tools/tool_ids.test.ts

@@ -0,0 +1,113 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+import { toolIdRegexp, validateToolId, toolIdMaxLength } from './tool_ids';
+import { protectedNamespaces } from './namespaces';
+
+describe('validateToolId', () => {
+  test('returns undefined for valid id (non built-in)', () => {
+    expect(validateToolId({ toolId: 'mytool', builtIn: false })).toBeUndefined();
+
+    expect(validateToolId({ toolId: 'foo_bar-baz.qux_123', builtIn: false })).toBeUndefined();
+  });
+
+  test('fails on invalid format (regexp)', () => {
+    const invalids = [
+      '',
+      '.mytool',
+      'mytool.',
+      'core..mytool',
+      'MyTool',
+      'core.MyTool',
+      '-tool',
+      'tool-',
+      '_tool',
+      'tool_',
+      'tool..id',
+      'tool..',
+      'tool.',
+      '.tool',
+      'tool#id',
+      'tool/id',
+    ];
+
+    for (const toolId of invalids) {
+      const error = validateToolId({ toolId, builtIn: false });
+      expect(error).toBe(
+        'Tool ids must start and end with a letter or number, and can only contain lowercase letters, numbers, dots, hyphens and underscores'
+      );
+    }
+  });
+
+  test('fails on toolId exceeding max length', () => {
+    const overMax = 'a'.repeat(toolIdMaxLength + 1);
+    const error = validateToolId({ toolId: overMax, builtIn: false });
+    expect(error).toBe(`Tool ids are limited to ${toolIdMaxLength} characters.`);
+  });
+
+  test('fails when toolId equals a protected namespace name', () => {
+    const protectedNamespaceName = protectedNamespaces[0];
+    const error = validateToolId({ toolId: protectedNamespaceName, builtIn: false });
+    expect(error).toBe('Tool id cannot have the same name as a reserved namespaces');
+  });
+
+  test('fails when non built-in tool uses a protected namespace', () => {
+    const protectedNamespaceName = protectedNamespaces[0];
+    const toolId = `${protectedNamespaceName}.mytool`;
+    const error = validateToolId({ toolId, builtIn: false });
+    expect(error).toBe('Tool id is using a protected namespaces.');
+  });
+
+  test('allows built-in tool to use a protected namespace', () => {
+    const protectedNamespaceName = protectedNamespaces[0];
+    const toolId = `${protectedNamespaceName}.internal_tool`;
+    const error = validateToolId({ toolId, builtIn: true });
+    expect(error).toBeUndefined();
+  });
+});
+
+describe('toolId regexp', () => {
+  const validToolIds = [
+    'mytool',
+    'core.mytool',
+    'core.foo.mytool',
+    'a',
+    'a.b',
+    'tool_1',
+    'tool-1',
+    'foo_bar-baz.qux_123',
+    'a1.b2.c3',
+    'abc.def_ghi-jkl.mno',
+  ];
+
+  const invalidToolIds = [
+    '', // empty string
+    '.mytool', // starts with dot
+    'mytool.', // ends with dot
+    'core..mytool', // double dot
+    'MyTool', // uppercase
+    'core.MyTool', // uppercase segment
+    '-tool', // starts with hyphen
+    'tool-', // ends with hyphen
+    '_tool', // starts with underscore
+    'tool_', // ends with underscore
+    'tool..id', // consecutive dots
+    'tool..', // ends with dot
+    'tool.', // ends with dot
+    '.tool', // starts with dot
+    'tool#id', // illegal char
+    'tool/id', // illegal char
+  ];
+
+  test.each(validToolIds)('valid: %s', (toolId) => {
+    expect(toolIdRegexp.test(toolId)).toBe(true);
+  });
+
+  test.each(invalidToolIds)('invalid: %s', (toolId) => {
+    expect(toolIdRegexp.test(toolId)).toBe(false);
+  });
+});

x-pack/platform/packages/shared/onechat/onechat-common/tools/tool_ids.ts

@@ -5,21 +5,49 @@
  * 2.0.
  */
 
-import { builtInToolIdPrefix, reservedKeywords } from './constants';
+import { hasProtectedNamespaceName, isInProtectedNamespace } from './namespaces';
 
-export const idRegexp = /^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$/;
+export const toolIdRegexp =
+  /^(?:[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)(?:\.(?:[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?))*$/;
+export const toolIdMaxLength = 64;
+
+const reservedKeywords = ['new'];
 
 /**
- * Check if the given ID is a built-in ID (starting with `.`)
+ * Check if the given ID is a reserved ID
+ * Atm this only checks for `new` because that's a value we're using for url paths on the UI.
  */
-export const isBuiltInToolId = (id: string) => {
-  return id.startsWith(builtInToolIdPrefix);
+export const isReservedToolId = (id: string) => {
+  return reservedKeywords.includes(id);
 };
 
 /**
- * Check if the given ID is a reserved ID
- * Atm this only checks for built-in IDs, but it will check for MCP and such later.
+ * Validate that a tool id has the right format,
+ * returning an error message if it fails the validation,
+ * and undefined otherwise.
+ *
+ * @param toolId: the toolId to validate
+ * @param builtIn: set to true if we're validating a built-in (internal) tool id.
  */
-export const isReservedToolId = (id: string) => {
-  return isBuiltInToolId(id) || reservedKeywords.includes(id);
+export const validateToolId = ({
+  toolId,
+  builtIn,
+}: {
+  toolId: string;
+  builtIn: boolean;
+}): string | undefined => {
+  if (!toolIdRegexp.test(toolId)) {
+    return `Tool ids must start and end with a letter or number, and can only contain lowercase letters, numbers, dots, hyphens and underscores`;
+  }
+  if (toolId.length > toolIdMaxLength) {
+    return `Tool ids are limited to ${toolIdMaxLength} characters.`;
+  }
+  if (hasProtectedNamespaceName(toolId)) {
+    return `Tool id cannot have the same name as a reserved namespaces`;
+  }
+  if (!builtIn) {
+    if (isInProtectedNamespace(toolId)) {
+      return `Tool id is using a protected namespaces.`;
+    }
+  }
 };

x-pack/platform/packages/shared/onechat/onechat-genai-utils/langchain/tools.test.ts

@@ -21,6 +21,7 @@ const createTool = (
     type: ToolType.builtin,
     description: '',
     configuration: {},
+    readonly: false,
     tags: [],
     schema: z.object({}),
     execute: jest.fn(),