@objectstack/service-ai 4.0.4 → 4.0.5

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

@@ -1,153 +0,0 @@
-// 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`;
-}
-
-/**
- * Encode data using Vercel AI SDK Data Stream Protocol prefixes.
- * @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
- */
-function dataStreamLine(prefix: string, data: object): string {
-  return `${prefix}:${JSON.stringify(data)}\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),
-      });
-
-    // Handle reasoning/thinking streams (DeepSeek R1, o1-style models)
-    // Use 'g:' prefix for reasoning content per Vercel AI SDK protocol
-    case 'reasoning-start':
-      return dataStreamLine('g', { text: '' });
-
-    case 'reasoning-delta':
-      return dataStreamLine('g', { text: part.text });
-
-    case 'reasoning-end':
-      return ''; // No specific end marker needed for reasoning
-
-    // finish-step and finish are handled by the generator, not here
-    default:
-      // Pass through any unknown event types that might be custom
-      // (e.g., step-start, step-finish from custom providers)
-      if ((part as any).type?.startsWith('step-')) {
-        return sse(part as any);
-      }
-      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

@@ -1,70 +0,0 @@
-// 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

@@ -1,66 +0,0 @@
-// 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,293 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { AIToolDefinition, IDataEngine } from '@objectstack/spec/contracts';
-import type { ToolHandler } from './tool-registry.js';
-import type { ToolRegistry } from './tool-registry.js';
-
-// ---------------------------------------------------------------------------
-// Data context — injected once at registration time
-// ---------------------------------------------------------------------------
-
-/**
- * Services required by the built-in data tools.
- *
- * These are provided by the kernel at `ai:ready` time and closed over
- * by the handler functions so they stay framework-agnostic.
- */
-export interface DataToolContext {
-  /** ObjectQL data engine for record-level operations. */
-  dataEngine: IDataEngine;
-}
-
-// ---------------------------------------------------------------------------
-// Tool Definitions
-// ---------------------------------------------------------------------------
-
-/** Maximum number of records a single query may return. */
-const MAX_QUERY_LIMIT = 200;
-
-/** Default record limit when not specified. */
-const DEFAULT_QUERY_LIMIT = 20;
-
-export const QUERY_RECORDS_TOOL: AIToolDefinition = {
-  name: 'query_records',
-  description:
-    'Query records from a data object with optional filters, field selection, ' +
-    'sorting, and pagination. Returns an array of matching records.',
-  parameters: {
-    type: 'object',
-    properties: {
-      objectName: {
-        type: 'string',
-        description: 'The snake_case name of the object to query',
-      },
-      where: {
-        type: 'object',
-        description:
-          'Filter conditions as key-value pairs (e.g. { "status": "active" }) ' +
-          'or MongoDB-style operators (e.g. { "amount": { "$gt": 100 } })',
-      },
-      fields: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'List of field names to return (omit for all fields)',
-      },
-      orderBy: {
-        type: 'array',
-        items: {
-          type: 'object',
-          properties: {
-            field: { type: 'string' },
-            order: { type: 'string', enum: ['asc', 'desc'] },
-          },
-        },
-        description: 'Sort order (e.g. [{ "field": "created_at", "order": "desc" }])',
-      },
-      limit: {
-        type: 'number',
-        description: `Maximum number of records to return (default ${DEFAULT_QUERY_LIMIT}, max ${MAX_QUERY_LIMIT})`,
-      },
-      offset: {
-        type: 'number',
-        description: 'Number of records to skip for pagination',
-      },
-    },
-    required: ['objectName'],
-    additionalProperties: false,
-  },
-};
-
-export const GET_RECORD_TOOL: AIToolDefinition = {
-  name: 'get_record',
-  description: 'Get a single record by its ID from a data object.',
-  parameters: {
-    type: 'object',
-    properties: {
-      objectName: {
-        type: 'string',
-        description: 'The snake_case name of the object',
-      },
-      recordId: {
-        type: 'string',
-        description: 'The unique ID of the record',
-      },
-      fields: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'List of field names to return (omit for all fields)',
-      },
-    },
-    required: ['objectName', 'recordId'],
-    additionalProperties: false,
-  },
-};
-
-export const AGGREGATE_DATA_TOOL: AIToolDefinition = {
-  name: 'aggregate_data',
-  description:
-    'Perform aggregation/statistical operations on a data object. ' +
-    'Supports count, sum, avg, min, max with optional groupBy and where filters.',
-  parameters: {
-    type: 'object',
-    properties: {
-      objectName: {
-        type: 'string',
-        description: 'The snake_case name of the object to aggregate',
-      },
-      aggregations: {
-        type: 'array',
-        items: {
-          type: 'object',
-          properties: {
-            function: {
-              type: 'string',
-              enum: ['count', 'sum', 'avg', 'min', 'max', 'count_distinct'],
-              description: 'Aggregation function',
-            },
-            field: {
-              type: 'string',
-              description: 'Field to aggregate (optional for count)',
-            },
-            alias: {
-              type: 'string',
-              description: 'Result column alias',
-            },
-          },
-          required: ['function', 'alias'],
-        },
-        description: 'Aggregation definitions',
-      },
-      groupBy: {
-        type: 'array',
-        items: { type: 'string' },
-        description: 'Fields to group by',
-      },
-      where: {
-        type: 'object',
-        description: 'Filter conditions applied before aggregation',
-      },
-    },
-    required: ['objectName', 'aggregations'],
-    additionalProperties: false,
-  },
-};
-
-/** All built-in data tools definitions. */
-export const DATA_TOOL_DEFINITIONS: AIToolDefinition[] = [
-  QUERY_RECORDS_TOOL,
-  GET_RECORD_TOOL,
-  AGGREGATE_DATA_TOOL,
-];
-
-// ---------------------------------------------------------------------------
-// Handler Factories
-// ---------------------------------------------------------------------------
-
-function createQueryRecordsHandler(ctx: DataToolContext): ToolHandler {
-  return async (args) => {
-    const {
-      objectName,
-      where,
-      fields,
-      orderBy,
-      limit,
-      offset,
-    } = args as {
-      objectName: string;
-      where?: Record<string, unknown>;
-      fields?: string[];
-      orderBy?: Array<{ field: string; order: 'asc' | 'desc' }>;
-      limit?: number;
-      offset?: number;
-    };
-
-    // Validate and clamp limit to [1, MAX_QUERY_LIMIT]
-    const rawLimit = limit ?? DEFAULT_QUERY_LIMIT;
-    const safeLimit = Number.isFinite(rawLimit) && rawLimit > 0
-      ? Math.min(Math.floor(rawLimit), MAX_QUERY_LIMIT)
-      : DEFAULT_QUERY_LIMIT;
-
-    // Validate offset: must be a non-negative finite integer
-    const safeOffset = (Number.isFinite(offset) && (offset as number) >= 0)
-      ? Math.floor(offset as number)
-      : undefined;
-
-    const records = await ctx.dataEngine.find(objectName, {
-      where,
-      fields,
-      orderBy,
-      limit: safeLimit,
-      offset: safeOffset,
-    });
-
-    return JSON.stringify({ count: records.length, records });
-  };
-}
-
-function createGetRecordHandler(ctx: DataToolContext): ToolHandler {
-  return async (args) => {
-    const { objectName, recordId, fields } = args as {
-      objectName: string;
-      recordId: string;
-      fields?: string[];
-    };
-
-    const record = await ctx.dataEngine.findOne(objectName, {
-      where: { id: recordId },
-      fields,
-    });
-
-    if (!record) {
-      return JSON.stringify({ error: `Record "${recordId}" not found in "${objectName}"` });
-    }
-
-    return JSON.stringify(record);
-  };
-}
-
-/** Aggregation function names supported by the data engine. */
-type AggFn = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct';
-
-/** Set of valid aggregation function names for runtime validation. */
-const VALID_AGG_FUNCTIONS = new Set<string>([
-  'count', 'sum', 'avg', 'min', 'max', 'count_distinct',
-]);
-
-function createAggregateDataHandler(ctx: DataToolContext): ToolHandler {
-  return async (args) => {
-    const { objectName, aggregations, groupBy, where } = args as {
-      objectName: string;
-      aggregations: Array<{ function: string; field?: string; alias: string }>;
-      groupBy?: string[];
-      where?: Record<string, unknown>;
-    };
-
-    // Validate aggregation functions at runtime
-    for (const a of aggregations) {
-      if (!VALID_AGG_FUNCTIONS.has(a.function)) {
-        return JSON.stringify({
-          error: `Invalid aggregation function "${a.function}". ` +
-            `Allowed: ${[...VALID_AGG_FUNCTIONS].join(', ')}`,
-        });
-      }
-    }
-
-    const result = await ctx.dataEngine.aggregate(objectName, {
-      where,
-      groupBy,
-      aggregations: aggregations.map(a => ({
-        function: a.function as AggFn,
-        field: a.field,
-        alias: a.alias,
-      })),
-    });
-
-    return JSON.stringify(result);
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Public Registration Helper
-// ---------------------------------------------------------------------------
-
-/**
- * Register all built-in data tools on the given {@link ToolRegistry}.
- *
- * 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');
- *   registerDataTools(aiService.toolRegistry, { dataEngine });
- * });
- * ```
- */
-export function registerDataTools(
-  registry: ToolRegistry,
-  context: DataToolContext,
-): void {
-  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

@@ -1,38 +0,0 @@
-// 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

@@ -1,31 +0,0 @@
-// 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,18 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-export { ToolRegistry } 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';