@objectstack/service-ai 4.0.1 → 4.0.3

package/src/tools/create-object.tool.ts

@@ -0,0 +1,66 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * create_object — AI Tool Metadata
+ *
+ * Creates a new data object (table) with schema validation.
+ * Validates snake_case naming for object and initial fields,
+ * checks for duplicates, and registers the object definition.
+ */
+export const createObjectTool = defineTool({
+  name: 'create_object',
+  label: 'Create Object',
+  description:
+    'Creates a new data object (table) with the specified name, label, and optional field definitions. ' +
+    'Use this when the user wants to create a new entity, table, or data model.',
+  category: 'data',
+  builtIn: true,
+  // NOTE: requiresConfirmation is intentionally false (default) because the
+  // server-side tool-call loop in AIService.chatWithTools/streamChatWithTools
+  // executes tool calls immediately without checking this flag.  The flag
+  // should only be set once server-side approval gating is implemented to
+  // avoid giving users a false sense of safety.
+  parameters: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Machine name for the object (snake_case, e.g. project_task)',
+      },
+      label: {
+        type: 'string',
+        description: 'Human-readable display name (e.g. Project Task)',
+      },
+      fields: {
+        type: 'array',
+        description: 'Initial fields to create with the object',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'Field machine name (snake_case)' },
+            label: { type: 'string', description: 'Field display name' },
+            type: {
+              type: 'string',
+              description: 'Field data type',
+              enum: ['text', 'textarea', 'number', 'boolean', 'date', 'datetime', 'select', 'lookup', 'formula', 'autonumber'],
+            },
+            required: { type: 'boolean', description: 'Whether the field is required' },
+          },
+          required: ['name', 'type'],
+        },
+      },
+      enableFeatures: {
+        type: 'object',
+        description: 'Object capability flags',
+        properties: {
+          trackHistory: { type: 'boolean' },
+          apiEnabled: { type: 'boolean' },
+        },
+      },
+    },
+    required: ['name', 'label'],
+    additionalProperties: false,
+  },
+});

package/src/tools/data-tools.ts

@@ -1,30 +1,9 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import type { AIToolDefinition, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
+import type { AIToolDefinition, IDataEngine } from '@objectstack/spec/contracts';
 import type { ToolHandler } from './tool-registry.js';
 import type { ToolRegistry } from './tool-registry.js';
 
-// ---------------------------------------------------------------------------
-// Internal type aliases for metadata payloads (returned as `unknown` from
-// IMetadataService — we cast to these lightweight shapes for field access).
-// ---------------------------------------------------------------------------
-
-/** Minimal shape of an object definition as returned by IMetadataService. */
-interface ObjectDef {
-  name: string;
-  label?: string;
-  fields?: Record<string, FieldDef>;
-}
-
-/** Minimal shape of a field definition inside an object. */
-interface FieldDef {
-  type?: string;
-  label?: string;
-  required?: boolean;
-  reference?: string;
-  options?: unknown;
-}
-
 // ---------------------------------------------------------------------------
 // Data context — injected once at registration time
 // ---------------------------------------------------------------------------
@@ -38,8 +17,6 @@ interface FieldDef {
 export interface DataToolContext {
   /** ObjectQL data engine for record-level operations. */
   dataEngine: IDataEngine;
-  /** Metadata service for schema/object introspection. */
-  metadataService: IMetadataService;
 }
 
 // ---------------------------------------------------------------------------
@@ -52,34 +29,6 @@ const MAX_QUERY_LIMIT = 200;
 /** Default record limit when not specified. */
 const DEFAULT_QUERY_LIMIT = 20;
 
-export const LIST_OBJECTS_TOOL: AIToolDefinition = {
-  name: 'list_objects',
-  description: 'List all available data objects (tables) in the system. Returns object names and labels.',
-  parameters: {
-    type: 'object',
-    properties: {},
-    additionalProperties: false,
-  },
-};
-
-export const DESCRIBE_OBJECT_TOOL: AIToolDefinition = {
-  name: 'describe_object',
-  description:
-    'Get the schema (fields, types, labels) of a specific data object. ' +
-    'Use this to understand the structure of a table before querying it.',
-  parameters: {
-    type: 'object',
-    properties: {
-      objectName: {
-        type: 'string',
-        description: 'The snake_case name of the object to describe',
-      },
-    },
-    required: ['objectName'],
-    additionalProperties: false,
-  },
-};
-
 export const QUERY_RECORDS_TOOL: AIToolDefinition = {
   name: 'query_records',
   description:
@@ -203,10 +152,8 @@ export const AGGREGATE_DATA_TOOL: AIToolDefinition = {
   },
 };
 
-/** All built-in data tool definitions. */
+/** All built-in data tools definitions. */
 export const DATA_TOOL_DEFINITIONS: AIToolDefinition[] = [
-  LIST_OBJECTS_TOOL,
-  DESCRIBE_OBJECT_TOOL,
   QUERY_RECORDS_TOOL,
   GET_RECORD_TOOL,
   AGGREGATE_DATA_TOOL,
@@ -216,46 +163,6 @@ export const DATA_TOOL_DEFINITIONS: AIToolDefinition[] = [
 // Handler Factories
 // ---------------------------------------------------------------------------
 
-function createListObjectsHandler(ctx: DataToolContext): ToolHandler {
-  return async () => {
-    const objects = await ctx.metadataService.listObjects();
-    const summary = (objects as ObjectDef[]).map(o => ({
-      name: o.name,
-      label: o.label ?? o.name,
-    }));
-    return JSON.stringify(summary);
-  };
-}
-
-function createDescribeObjectHandler(ctx: DataToolContext): ToolHandler {
-  return async (args) => {
-    const { objectName } = args as { objectName: string };
-    const objectDef = await ctx.metadataService.getObject(objectName);
-    if (!objectDef) {
-      return JSON.stringify({ error: `Object "${objectName}" not found` });
-    }
-
-    const def = objectDef as ObjectDef;
-    const fields = def.fields ?? {};
-    const fieldSummary: Record<string, Record<string, unknown>> = {};
-    for (const [key, f] of Object.entries(fields)) {
-      fieldSummary[key] = {
-        type: f.type,
-        label: f.label ?? key,
-        required: f.required ?? false,
-        ...(f.reference ? { reference: f.reference } : {}),
-        ...(f.options ? { options: f.options } : {}),
-      };
-    }
-
-    return JSON.stringify({
-      name: def.name,
-      label: def.label ?? def.name,
-      fields: fieldSummary,
-    });
-  };
-}
-
 function createQueryRecordsHandler(ctx: DataToolContext): ToolHandler {
   return async (args) => {
     const {
@@ -366,15 +273,13 @@ function createAggregateDataHandler(ctx: DataToolContext): ToolHandler {
 /**
  * Register all built-in data tools on the given {@link ToolRegistry}.
  *
- * Typically called from the `ai:ready` hook after both the data engine
- * and metadata service are available.
+ * Typically called from the `ai:ready` hook after the data engine is available.
  *
  * @example
  * ```ts
  * ctx.hook('ai:ready', async (aiService) => {
  *   const dataEngine = ctx.getService<IDataEngine>('data');
- *   const metadataService = ctx.getService<IMetadataService>('metadata');
- *   registerDataTools(aiService.toolRegistry, { dataEngine, metadataService });
+ *   registerDataTools(aiService.toolRegistry, { dataEngine });
  * });
  * ```
  */
@@ -382,8 +287,6 @@ export function registerDataTools(
   registry: ToolRegistry,
   context: DataToolContext,
 ): void {
-  registry.register(LIST_OBJECTS_TOOL, createListObjectsHandler(context));
-  registry.register(DESCRIBE_OBJECT_TOOL, createDescribeObjectHandler(context));
   registry.register(QUERY_RECORDS_TOOL, createQueryRecordsHandler(context));
   registry.register(GET_RECORD_TOOL, createGetRecordHandler(context));
   registry.register(AGGREGATE_DATA_TOOL, createAggregateDataHandler(context));

package/src/tools/delete-field.tool.ts

@@ -0,0 +1,38 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * delete_field — AI Tool Metadata
+ *
+ * Removes a field (column) from an existing data object.
+ * This is a destructive operation.
+ */
+export const deleteFieldTool = defineTool({
+  name: 'delete_field',
+  label: 'Delete Field',
+  description:
+    'Removes a field (column) from an existing data object. This is a destructive operation. ' +
+    'Use this when the user explicitly wants to remove an attribute or column from a table.',
+  category: 'data',
+  builtIn: true,
+  // NOTE: requiresConfirmation is intentionally false (default) because the
+  // server-side tool-call loop in AIService.chatWithTools/streamChatWithTools
+  // executes tool calls immediately without checking this flag.  The flag
+  // should only be set once server-side approval gating is implemented.
+  parameters: {
+    type: 'object',
+    properties: {
+      objectName: {
+        type: 'string',
+        description: 'Target object machine name (snake_case)',
+      },
+      fieldName: {
+        type: 'string',
+        description: 'Field machine name to delete (snake_case)',
+      },
+    },
+    required: ['objectName', 'fieldName'],
+    additionalProperties: false,
+  },
+});

package/src/tools/describe-object.tool.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * describe_object — AI Tool Metadata
+ *
+ * Returns the full schema of a data object including all fields, types,
+ * relationships, and configuration. This is the single, unified tool for
+ * describing objects — used by both data_chat and metadata_assistant agents.
+ */
+export const describeObjectTool = defineTool({
+  name: 'describe_object',
+  label: 'Describe Object',
+  description:
+    'Returns the full schema details of a data object, including all fields, types, relationships, and configuration. ' +
+    'Use this to understand the structure of a table before querying or modifying it.',
+  category: 'data',
+  builtIn: true,
+  parameters: {
+    type: 'object',
+    properties: {
+      objectName: {
+        type: 'string',
+        description: 'Object machine name to describe (snake_case)',
+      },
+    },
+    required: ['objectName'],
+    additionalProperties: false,
+  },
+});

package/src/tools/index.ts

@@ -1,7 +1,18 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export { ToolRegistry } from './tool-registry.js';
-export type { ToolHandler } from './tool-registry.js';
+export type { ToolHandler, ToolExecutionResult } from './tool-registry.js';
 
 export { registerDataTools, DATA_TOOL_DEFINITIONS } from './data-tools.js';
 export type { DataToolContext } from './data-tools.js';
+
+export { registerMetadataTools, METADATA_TOOL_DEFINITIONS } from './metadata-tools.js';
+export type { MetadataToolContext } from './metadata-tools.js';
+
+// Individual tool metadata exports
+export { createObjectTool } from './create-object.tool.js';
+export { addFieldTool } from './add-field.tool.js';
+export { modifyFieldTool } from './modify-field.tool.js';
+export { deleteFieldTool } from './delete-field.tool.js';
+export { listObjectsTool } from './list-objects.tool.js';
+export { describeObjectTool } from './describe-object.tool.js';

package/src/tools/list-objects.tool.ts

@@ -0,0 +1,34 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * list_objects — AI Tool Metadata
+ *
+ * Lists all registered data objects (tables) with optional filtering
+ * and field summaries. This is the single, unified tool for listing
+ * objects — used by both data_chat and metadata_assistant agents.
+ */
+export const listObjectsTool = defineTool({
+  name: 'list_objects',
+  label: 'List Objects',
+  description:
+    'Lists all registered data objects (tables) in the current environment. ' +
+    'Use this when the user wants to see what tables, entities, or data models are available.',
+  category: 'data',
+  builtIn: true,
+  parameters: {
+    type: 'object',
+    properties: {
+      filter: {
+        type: 'string',
+        description: 'Optional name or label substring to filter objects',
+      },
+      includeFields: {
+        type: 'boolean',
+        description: 'Whether to include field summaries for each object (default: false)',
+      },
+    },
+    additionalProperties: false,
+  },
+});