feat(service-ai): complete package-aware metadata tools implementation

- Add packageId parameter to all metadata tool definitions
- Implement package resolution helpers (getActivePackageId, resolvePackageId)
- Update all metadata handlers to validate and use package context
- Enforce read-only protection for filesystem-based packages
- Return packageId in all tool responses for tracking

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/69c4b16a-f22c-45a6-88a1-e6b2d10527d8

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Claude

packages/services/service-ai/src/tools/add-field.tool.ts

@@ -20,6 +20,10 @@ export const addFieldTool = defineTool({
   parameters: {
     type: 'object',
     properties: {
+      packageId: {
+        type: 'string',
+        description: 'Package ID that owns the target object (e.g., com.acme.crm). If not provided, uses the active package from conversation context.',
+      },
       objectName: {
         type: 'string',
         description: 'Target object machine name (snake_case)',

packages/services/service-ai/src/tools/delete-field.tool.ts

@@ -23,6 +23,10 @@ export const deleteFieldTool = defineTool({
   parameters: {
     type: 'object',
     properties: {
+      packageId: {
+        type: 'string',
+        description: 'Package ID that owns the target object (e.g., com.acme.crm). If not provided, uses the active package from conversation context.',
+      },
       objectName: {
         type: 'string',
         description: 'Target object machine name (snake_case)',

packages/services/service-ai/src/tools/metadata-tools.ts

@@ -69,6 +69,76 @@ function isSnakeCase(value: string): boolean {
   return SNAKE_CASE_RE.test(value);
 }
 
+// ---------------------------------------------------------------------------
+// Package Resolution Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieves the active package ID from the conversation context.
+ * Returns null if no conversation service is available or no active package is set.
+ */
+async function getActivePackageId(ctx: MetadataToolContext): Promise<string | null> {
+  if (!ctx.conversationService?.getMetadata || !ctx.conversationId) {
+    return null;
+  }
+
+  const metadata = await ctx.conversationService.getMetadata(ctx.conversationId);
+  return (metadata?.activePackageId as string) ?? null;
+}
+
+/**
+ * Resolves the package ID to use for a metadata operation.
+ * Priority: explicit packageId > active package from conversation > error
+ *
+ * Also validates that the package exists and checks if it's read-only.
+ *
+ * @returns Object with packageId or error message
+ */
+async function resolvePackageId(
+  ctx: MetadataToolContext,
+  explicitPackageId?: string,
+): Promise<{ packageId: string | null; error?: string; warning?: string }> {
+  let packageId: string | null = null;
+
+  // 1. Try explicit packageId parameter
+  if (explicitPackageId) {
+    packageId = explicitPackageId;
+  } else {
+    // 2. Try active package from conversation
+    packageId = await getActivePackageId(ctx);
+  }
+
+  // If no package ID could be resolved, return error
+  if (!packageId) {
+    return {
+      packageId: null,
+      error: 'No package specified. Either provide packageId parameter or set an active package using set_active_package.',
+    };
+  }
+
+  // Validate package exists (if registry is available)
+  if (ctx.packageRegistry) {
+    const exists = await ctx.packageRegistry.exists(packageId);
+    if (!exists) {
+      return {
+        packageId: null,
+        error: `Package "${packageId}" not found. Use list_packages to see available packages or create_package to create a new one.`,
+      };
+    }
+
+    // Check if package is read-only (code-based)
+    const pkg = await ctx.packageRegistry.get(packageId);
+    if (pkg?.manifest.source === 'filesystem') {
+      return {
+        packageId: null,
+        error: `Package "${packageId}" is read-only (loaded from code). Only database packages can be modified. Use create_package to create a new database package.`,
+      };
+    }
+  }
+
+  return { packageId };
+}
+
 // ---------------------------------------------------------------------------
 // Context — injected once at registration time
 // ---------------------------------------------------------------------------
@@ -104,9 +174,10 @@ export interface MetadataToolContext {
 
 function createCreateObjectHandler(ctx: MetadataToolContext): ToolHandler {
   return async (args) => {
-    const { name, label, fields, enableFeatures } = args as {
+    const { name, label, packageId: explicitPackageId, fields, enableFeatures } = args as {
       name: string;
       label: string;
+      packageId?: string;
       fields?: Array<{ name: string; label?: string; type: string; required?: boolean }>;
       enableFeatures?: Record<string, boolean>;
     };
@@ -115,6 +186,13 @@ function createCreateObjectHandler(ctx: MetadataToolContext): ToolHandler {
       return JSON.stringify({ error: 'Both "name" and "label" are required' });
     }
 
+    // Resolve package ID
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
+    const packageId = resolved.packageId!;
+
     // Validate snake_case name
     if (!isSnakeCase(name)) {
       return JSON.stringify({ error: `Invalid object name "${name}". Must be snake_case.` });
@@ -152,6 +230,7 @@ function createCreateObjectHandler(ctx: MetadataToolContext): ToolHandler {
     const objectDef: Record<string, unknown> = {
       name,
       label,
+      packageId,
       ...(Object.keys(fieldMap).length > 0 ? { fields: fieldMap } : {}),
       ...(enableFeatures ? { enable: enableFeatures } : {}),
     };
@@ -161,14 +240,15 @@ function createCreateObjectHandler(ctx: MetadataToolContext): ToolHandler {
     return JSON.stringify({
       name,
       label,
+      packageId,
       fieldCount: Object.keys(fieldMap).length,
     });
   };
 }
 
 function createAddFieldHandler(ctx: MetadataToolContext): ToolHandler {
   return async (args) => {
-    const { objectName, name, label, type, required, defaultValue, options, reference } = args as {
+    const { objectName, name, label, type, required, defaultValue, options, reference, packageId: explicitPackageId } = args as {
       objectName: string;
       name: string;
       label?: string;
@@ -177,12 +257,19 @@ function createAddFieldHandler(ctx: MetadataToolContext): ToolHandler {
       defaultValue?: unknown;
       options?: Array<{ label: string; value: string }>;
       reference?: string;
+      packageId?: string;
     };
 
     if (!objectName || !name || !type) {
       return JSON.stringify({ error: '"objectName", "name", and "type" are required' });
     }
 
+    // Resolve package ID (for validation and tracking)
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
+
     // Validate snake_case names
     if (!isSnakeCase(objectName)) {
       return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
@@ -238,22 +325,30 @@ function createAddFieldHandler(ctx: MetadataToolContext): ToolHandler {
       objectName,
       fieldName: name,
       fieldType: type,
+      packageId: resolved.packageId,
     });
   };
 }
 
 function createModifyFieldHandler(ctx: MetadataToolContext): ToolHandler {
   return async (args) => {
-    const { objectName, fieldName, changes } = args as {
+    const { objectName, fieldName, changes, packageId: explicitPackageId } = args as {
       objectName: string;
       fieldName: string;
       changes: Record<string, unknown>;
+      packageId?: string;
     };
 
     if (!objectName || !fieldName || !changes) {
       return JSON.stringify({ error: '"objectName", "fieldName", and "changes" are required' });
     }
 
+    // Resolve package ID (for validation and tracking)
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
+
     // Validate snake_case names
     if (!isSnakeCase(objectName)) {
       return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
@@ -287,21 +382,29 @@ function createModifyFieldHandler(ctx: MetadataToolContext): ToolHandler {
       objectName,
       fieldName,
       updatedProperties: Object.keys(changes),
+      packageId: resolved.packageId,
     });
   };
 }
 
 function createDeleteFieldHandler(ctx: MetadataToolContext): ToolHandler {
   return async (args) => {
-    const { objectName, fieldName } = args as {
+    const { objectName, fieldName, packageId: explicitPackageId } = args as {
       objectName: string;
       fieldName: string;
+      packageId?: string;
     };
 
     if (!objectName || !fieldName) {
       return JSON.stringify({ error: '"objectName" and "fieldName" are required' });
     }
 
+    // Resolve package ID (for validation and tracking)
+    const resolved = await resolvePackageId(ctx, explicitPackageId);
+    if (resolved.error) {
+      return JSON.stringify({ error: resolved.error });
+    }
+
     // Validate snake_case names
     if (!isSnakeCase(objectName)) {
       return JSON.stringify({ error: `Invalid object name "${objectName}". Must be snake_case.` });
@@ -332,6 +435,7 @@ function createDeleteFieldHandler(ctx: MetadataToolContext): ToolHandler {
       objectName,
       fieldName,
       success: true,
+      packageId: resolved.packageId,
     });
   };
 }

packages/services/service-ai/src/tools/modify-field.tool.ts

@@ -19,6 +19,10 @@ export const modifyFieldTool = defineTool({
   parameters: {
     type: 'object',
     properties: {
+      packageId: {
+        type: 'string',
+        description: 'Package ID that owns the target object (e.g., com.acme.crm). If not provided, uses the active package from conversation context.',
+      },
       objectName: {
         type: 'string',
         description: 'Target object machine name (snake_case)',