@objectstack/service-ai 4.0.0 → 4.0.2

package/src/routes/index.ts

@@ -1,4 +1,4 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export { buildAIRoutes } from './ai-routes.js';
-export type { RouteDefinition, RouteRequest, RouteResponse } from './ai-routes.js';
+export type { RouteDefinition, RouteRequest, RouteResponse, RouteUserContext } from './ai-routes.js';

package/src/stream/index.ts

@@ -0,0 +1,3 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { encodeStreamPart, encodeVercelDataStream } from './vercel-stream-encoder.js';

package/src/stream/vercel-stream-encoder.ts

@@ -0,0 +1,129 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Vercel AI SDK v6 — UI Message Stream Encoder
+ *
+ * Converts `AsyncIterable<TextStreamPart<ToolSet>>` (the internal ObjectStack
+ * streaming format) into the Vercel AI SDK v6 **UI Message Stream Protocol**.
+ *
+ * Wire format: Server-Sent Events (SSE) with JSON payloads.
+ *   `data: {"type":"text-delta","id":"0","delta":"Hello"}\n\n`
+ *
+ * The client-side `DefaultChatTransport` from `ai` v6 uses
+ * `parseJsonEventStream` to parse these SSE events.
+ *
+ * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
+ */
+
+import type { TextStreamPart, ToolSet } from 'ai';
+
+// ── SSE helpers ──────────────────────────────────────────────────────
+
+function sse(data: object): string {
+  return `data: ${JSON.stringify(data)}\n\n`;
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Encode a single `TextStreamPart` event into SSE-formatted UI Message
+ * Stream chunk(s).
+ *
+ * Returns an empty string for event types that have no wire-format mapping.
+ */
+export function encodeStreamPart(part: TextStreamPart<ToolSet>): string {
+  switch (part.type) {
+    case 'text-delta':
+      return sse({ type: 'text-delta', id: '0', delta: part.text });
+
+    case 'tool-input-start':
+      return sse({
+        type: 'tool-input-start',
+        toolCallId: part.id,
+        toolName: part.toolName,
+      });
+
+    case 'tool-input-delta':
+      return sse({
+        type: 'tool-input-delta',
+        toolCallId: part.id,
+        inputTextDelta: part.delta,
+      });
+
+    case 'tool-call':
+      return sse({
+        type: 'tool-input-available',
+        toolCallId: part.toolCallId,
+        toolName: part.toolName,
+        input: part.input,
+      });
+
+    case 'tool-result':
+      return sse({
+        type: 'tool-output-available',
+        toolCallId: part.toolCallId,
+        output: part.output,
+      });
+
+    case 'error':
+      return sse({
+        type: 'error',
+        errorText: String(part.error),
+      });
+
+    // finish-step and finish are handled by the generator, not here
+    default:
+      return '';
+  }
+}
+
+/**
+ * Transform an `AsyncIterable<TextStreamPart>` into an `AsyncIterable<string>`
+ * where each yielded string is an SSE-formatted UI Message Stream chunk.
+ *
+ * Lifecycle order required by the client:
+ *   start → start-step → text-start → text-delta* → text-end → finish-step → finish → [DONE]
+ */
+export async function* encodeVercelDataStream(
+  events: AsyncIterable<TextStreamPart<ToolSet>>,
+): AsyncIterable<string> {
+  // Preamble
+  yield sse({ type: 'start' });
+  yield sse({ type: 'start-step' });
+  yield sse({ type: 'text-start', id: '0' });
+
+  let textOpen = true;
+  let finishReason = 'stop';
+
+  for await (const part of events) {
+    // Capture finish reason
+    if (part.type === 'finish') {
+      finishReason = part.finishReason ?? 'stop';
+    }
+
+    // Before finish-step/finish, close the text part first
+    if (part.type === 'finish-step' || part.type === 'finish') {
+      if (textOpen) {
+        yield sse({ type: 'text-end', id: '0' });
+        textOpen = false;
+      }
+      // Don't emit these via encodeStreamPart — we handle them in postamble
+      continue;
+    }
+
+    const frame = encodeStreamPart(part);
+    if (frame) {
+      yield frame;
+    }
+  }
+
+  // Close text if still open (safety)
+  if (textOpen) {
+    yield sse({ type: 'text-end', id: '0' });
+  }
+
+  // Postamble
+  yield sse({ type: 'finish-step' });
+  yield sse({ type: 'finish', finishReason });
+  yield 'data: [DONE]\n\n';
+}

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

@@ -0,0 +1,70 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * add_field — AI Tool Metadata
+ *
+ * Adds a new field (column) to an existing data object.
+ * Validates snake_case for objectName, field name, reference,
+ * and select option values before merging into the definition.
+ */
+export const addFieldTool = defineTool({
+  name: 'add_field',
+  label: 'Add Field',
+  description:
+    'Adds a new field (column) to an existing data object. ' +
+    'Use this when the user wants to add a property, column, or attribute to a table.',
+  category: 'data',
+  builtIn: true,
+  parameters: {
+    type: 'object',
+    properties: {
+      objectName: {
+        type: 'string',
+        description: 'Target object machine name (snake_case)',
+      },
+      name: {
+        type: 'string',
+        description: 'Field machine name (snake_case, e.g. due_date)',
+      },
+      label: {
+        type: 'string',
+        description: 'Human-readable field label (e.g. Due Date)',
+      },
+      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',
+      },
+      defaultValue: {
+        description: 'Default value for the field',
+      },
+      options: {
+        type: 'array',
+        description: 'Options for select/picklist fields',
+        items: {
+          type: 'object',
+          properties: {
+            label: { type: 'string' },
+            value: {
+              type: 'string',
+              description: 'Option machine identifier (lowercase snake_case, e.g. high_priority)',
+              pattern: '^[a-z_][a-z0-9_]*$',
+            },
+          },
+        },
+      },
+      reference: {
+        type: 'string',
+        description: 'Referenced object name for lookup fields (snake_case, e.g. account)',
+      },
+    },
+    required: ['objectName', 'name', 'type'],
+    additionalProperties: false,
+  },
+});

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/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-metadata-object.tool.ts

@@ -0,0 +1,32 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { defineTool } from '@objectstack/spec/ai';
+
+/**
+ * describe_metadata_object — AI Tool Metadata
+ *
+ * Returns the full metadata schema of a data object including all
+ * fields, types, relationships, and configuration. Uses a unique name
+ * (`describe_metadata_object`) to avoid collision with the data-tools
+ * `describe_object` tool.
+ */
+export const describeMetadataObjectTool = defineTool({
+  name: 'describe_metadata_object',
+  label: 'Describe Metadata Object',
+  description:
+    'Returns the full metadata schema details of a data object, including all fields, types, relationships, and configuration. ' +
+    'Use this when the user wants to inspect or understand the metadata structure of a specific table or entity.',
+  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 { listMetadataObjectsTool } from './list-metadata-objects.tool.js';
+export { describeMetadataObjectTool } from './describe-metadata-object.tool.js';

package/src/tools/list-metadata-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_metadata_objects — AI Tool Metadata
+ *
+ * Lists all registered metadata objects (tables) with optional filtering.
+ * Uses a unique name (`list_metadata_objects`) to avoid collision with
+ * the data-tools `list_objects` tool.
+ */
+export const listMetadataObjectsTool = defineTool({
+  name: 'list_metadata_objects',
+  label: 'List Metadata Objects',
+  description:
+    'Lists all registered metadata objects (tables) in the current environment. ' +
+    'Use this when the user wants to see what tables, entities, or data models are defined in metadata.',
+  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,
+  },
+});