feat: add metadata_assistant agent, tool confirmations, and AiChatPanel tool display

- Create metadata_assistant agent with 6 metadata tools and system prompt
- Add requiresConfirmation: true to create_object and delete_field tools
- Enhance AiChatPanel to render tool invocation parts (calling/success/error/denied)
- Implement approval-requested UI with Approve/Deny buttons using addToolApprovalResponse
- Add tests for new agent, tool flags, and tool part persistence
- Update CHANGELOG.md

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/8a978a0a-5a20-45f0-b841-51f0a8857945

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -25,6 +25,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   absent, fixing the CI `@objectstack/client#test` failure.
 
 ### Added
+- **Metadata Assistant Agent (`service-ai`)** — New `metadata_assistant` agent definition that
+  binds all 6 metadata management tools (`create_object`, `add_field`, `modify_field`,
+  `delete_field`, `list_metadata_objects`, `describe_metadata_object`). Includes a tailored
+  system prompt that guides the AI to use snake_case naming, verify existing schemas before
+  modifications, and warn about destructive operations. Configured with `react` planning
+  strategy (10 iterations, replan enabled) for multi-step schema design conversations.
+- **Tool Confirmation Flags** — Added `requiresConfirmation: true` to `create_object` and
+  `delete_field` tool definitions. These destructive/creation operations now signal to the
+  frontend that user approval is needed before execution.
+- **Frontend Tool Call Display (`AiChatPanel`)** — Enhanced the AI Chat Panel to render tool
+  invocation parts from the Vercel AI SDK v6 stream protocol. Displays tool call status with
+  visual indicators:
+  - **Calling**: Spinner animation with tool name and argument summary
+  - **Confirmation**: Yellow-bordered card with Approve/Deny buttons for `requiresConfirmation` tools
+  - **Success**: Green success indicator with result preview
+  - **Error**: Red error indicator with error message
+  - **Denied**: Muted indicator for user-denied operations
+- **Operation Confirmation Mechanism** — Integrated the Vercel AI SDK `addToolApprovalResponse`
+  hook to support approval/denial workflows for tools marked with `requiresConfirmation`.
+  When the server sends an `approval-requested` state, the chat panel shows Approve and Deny
+  buttons. User decisions are sent back to the server to continue or abort the tool execution.
 - **Metadata Management Tools (`service-ai`)** — Added 6 built-in AI tools for metadata
   CRUD operations, each defined as a first-class `Tool` metadata file using `defineTool()`
   from `@objectstack/spec/ai`:

apps/studio/src/components/AiChatPanel.tsx

@@ -4,7 +4,10 @@ import { useState, useRef, useEffect, useMemo } from 'react';
 import { useChat } from '@ai-sdk/react';
 import { DefaultChatTransport } from 'ai';
 import type { UIMessage } from 'ai';
-import { Bot, X, Send, Trash2, Sparkles } from 'lucide-react';
+import {
+  Bot, X, Send, Trash2, Sparkles,
+  Wrench, CheckCircle2, XCircle, Loader2, ShieldAlert,
+} from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
@@ -25,6 +28,168 @@ function getMessageText(msg: UIMessage): string {
     .join('');
 }
 
+/**
+ * Convert a snake_case tool name to a human-readable label.
+ */
+function formatToolName(name: string): string {
+  return name
+    .replace(/_/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Render a concise summary of tool input arguments.
+ */
+function formatToolArgs(input: unknown): string {
+  if (!input || typeof input !== 'object') return '';
+  const entries = Object.entries(input as Record<string, unknown>);
+  if (entries.length === 0) return '';
+  return entries
+    .slice(0, 4)
+    .map(([k, v]) => {
+      const val = typeof v === 'string' ? v : JSON.stringify(v);
+      const display = typeof val === 'string' && val.length > 30 ? val.slice(0, 30) + '…' : val;
+      return `${k}: ${display}`;
+    })
+    .join(', ');
+}
+
+/**
+ * Type guard to check if a message part is a tool invocation (dynamic-tool).
+ */
+function isToolPart(part: UIMessage['parts'][number]): part is Extract<UIMessage['parts'][number], { type: 'dynamic-tool' }> {
+  return part.type === 'dynamic-tool';
+}
+
+// ── Tool Invocation State Labels ────────────────────────────────────
+
+interface ToolInvocationDisplayProps {
+  part: Extract<UIMessage['parts'][number], { type: 'dynamic-tool' }>;
+  onApprove?: (approvalId: string) => void;
+  onDeny?: (approvalId: string) => void;
+}
+
+/**
+ * Renders a single tool invocation part with appropriate status indicator.
+ */
+function ToolInvocationDisplay({ part, onApprove, onDeny }: ToolInvocationDisplayProps) {
+  const toolLabel = formatToolName(part.toolName);
+  const argsText = formatToolArgs(part.input);
+
+  switch (part.state) {
+    case 'input-streaming':
+    case 'input-available':
+      return (
+        <div
+          data-testid="tool-invocation-calling"
+          className="flex items-start gap-2 rounded-md border border-border/50 bg-muted/50 px-2.5 py-2 text-xs"
+        >
+          <Loader2 className="mt-0.5 h-3.5 w-3.5 shrink-0 animate-spin text-primary" />
+          <div className="min-w-0">
+            <span className="font-medium">Calling {toolLabel}</span>
+            {argsText && (
+              <p className="mt-0.5 truncate text-muted-foreground">{argsText}</p>
+            )}
+          </div>
+        </div>
+      );
+
+    case 'approval-requested':
+      return (
+        <div
+          data-testid="tool-invocation-confirm"
+          className="flex flex-col gap-2 rounded-md border border-yellow-500/40 bg-yellow-500/10 px-2.5 py-2 text-xs"
+        >
+          <div className="flex items-start gap-2">
+            <ShieldAlert className="mt-0.5 h-3.5 w-3.5 shrink-0 text-yellow-600 dark:text-yellow-400" />
+            <div className="min-w-0">
+              <span className="font-medium">Confirm: {toolLabel}</span>
+              {argsText && (
+                <p className="mt-0.5 text-muted-foreground">{argsText}</p>
+              )}
+            </div>
+          </div>
+          {part.approval && onApprove && onDeny && (
+            <div className="flex gap-2 pl-5">
+              <Button
+                size="sm"
+                variant="outline"
+                className="h-6 px-2 text-xs"
+                onClick={() => onApprove(part.approval!.id)}
+              >
+                <CheckCircle2 className="mr-1 h-3 w-3" />
+                Approve
+              </Button>
+              <Button
+                size="sm"
+                variant="ghost"
+                className="h-6 px-2 text-xs text-destructive hover:text-destructive"
+                onClick={() => onDeny(part.approval!.id)}
+              >
+                <XCircle className="mr-1 h-3 w-3" />
+                Deny
+              </Button>
+            </div>
+          )}
+        </div>
+      );
+
+    case 'output-available':
+      return (
+        <div
+          data-testid="tool-invocation-result"
+          className="flex items-start gap-2 rounded-md border border-green-500/30 bg-green-500/10 px-2.5 py-2 text-xs"
+        >
+          <CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0 text-green-600 dark:text-green-400" />
+          <div className="min-w-0">
+            <span className="font-medium">{toolLabel}</span>
+            <p className="mt-0.5 text-muted-foreground truncate">
+              {typeof part.output === 'string'
+                ? part.output.length > 80 ? part.output.slice(0, 80) + '…' : part.output
+                : JSON.stringify(part.output).slice(0, 80)}
+            </p>
+          </div>
+        </div>
+      );
+
+    case 'output-error':
+      return (
+        <div
+          data-testid="tool-invocation-error"
+          className="flex items-start gap-2 rounded-md border border-destructive/30 bg-destructive/10 px-2.5 py-2 text-xs"
+        >
+          <XCircle className="mt-0.5 h-3.5 w-3.5 shrink-0 text-destructive" />
+          <div className="min-w-0">
+            <span className="font-medium">{toolLabel} failed</span>
+            <p className="mt-0.5 text-destructive/80">{part.errorText}</p>
+          </div>
+        </div>
+      );
+
+    case 'output-denied':
+      return (
+        <div
+          data-testid="tool-invocation-denied"
+          className="flex items-start gap-2 rounded-md border border-border/50 bg-muted/50 px-2.5 py-2 text-xs"
+        >
+          <XCircle className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+          <span className="font-medium text-muted-foreground">{toolLabel} — denied</span>
+        </div>
+      );
+
+    default:
+      return (
+        <div
+          data-testid="tool-invocation-unknown"
+          className="flex items-start gap-2 rounded-md border border-border/50 bg-muted/50 px-2.5 py-2 text-xs"
+        >
+          <Wrench className="mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+          <span className="font-medium">{toolLabel}</span>
+        </div>
+      );
+  }
+}
+
 export function AiChatPanel() {
   const { isOpen, setOpen, toggle } = useAiChatPanel();
   const [input, setInput] = useState('');
@@ -39,7 +204,7 @@ export function AiChatPanel() {
     [baseUrl],
   );
 
-  const { messages, sendMessage, setMessages, status, error } = useChat({
+  const { messages, sendMessage, setMessages, status, error, addToolApprovalResponse } = useChat({
     transport,
     messages: initialMessages,
   });
@@ -167,12 +332,14 @@ export function AiChatPanel() {
           )}
           {messages.map((msg) => {
             const text = getMessageText(msg);
-            if (!text && msg.role !== 'user') return null;
+            const toolParts = (msg.parts ?? []).filter(isToolPart);
+            const hasContent = !!text || toolParts.length > 0;
+            if (!hasContent && msg.role !== 'user') return null;
             return (
               <div
                 key={msg.id}
                 className={cn(
-                  'flex flex-col gap-1 rounded-lg px-3 py-2 text-sm',
+                  'flex flex-col gap-1.5 rounded-lg px-3 py-2 text-sm',
                   msg.role === 'user'
                     ? 'ml-8 bg-primary text-primary-foreground'
                     : 'mr-8 bg-muted text-foreground',
@@ -181,7 +348,23 @@ export function AiChatPanel() {
                 <span className="text-[10px] font-medium opacity-60 uppercase">
                   {msg.role === 'user' ? 'You' : 'Assistant'}
                 </span>
-                <div className="whitespace-pre-wrap break-words">{text}</div>
+                {text && <div className="whitespace-pre-wrap break-words">{text}</div>}
+                {toolParts.map((toolPart) => (
+                  <ToolInvocationDisplay
+                    key={toolPart.toolCallId}
+                    part={toolPart}
+                    onApprove={(approvalId) =>
+                      addToolApprovalResponse({ id: approvalId, approved: true })
+                    }
+                    onDeny={(approvalId) =>
+                      addToolApprovalResponse({
+                        id: approvalId,
+                        approved: false,
+                        reason: 'User denied the operation',
+                      })
+                    }
+                  />
+                ))}
               </div>
             );
           })}

apps/studio/test/ai-chat-panel.test.tsx

@@ -16,6 +16,39 @@ function makeMsg(overrides: { id: string; role: 'user' | 'assistant'; content: s
   };
 }
 
+/**
+ * Create a UIMessage that includes tool invocation parts for testing.
+ */
+function makeMsgWithToolParts(overrides: {
+  id: string;
+  role: 'user' | 'assistant';
+  text?: string;
+  toolParts?: Array<{ toolName: string; toolCallId: string; state: string; input?: unknown; output?: unknown; errorText?: string }>;
+}): UIMessage {
+  const parts: UIMessage['parts'] = [];
+  if (overrides.text) {
+    parts.push({ type: 'text' as const, text: overrides.text });
+  }
+  if (overrides.toolParts) {
+    for (const tp of overrides.toolParts) {
+      parts.push({
+        type: 'dynamic-tool',
+        toolName: tp.toolName,
+        toolCallId: tp.toolCallId,
+        state: tp.state,
+        input: tp.input,
+        output: tp.output,
+        errorText: tp.errorText,
+      } as unknown as UIMessage['parts'][number]);
+    }
+  }
+  return {
+    id: overrides.id,
+    role: overrides.role,
+    parts,
+  };
+}
+
 describe('use-ai-chat-panel', () => {
   beforeEach(() => {
     localStorage.clear();
@@ -94,3 +127,75 @@ describe('AiChatPanel constants', () => {
     expect(localStorage.getItem('objectstack:ai-chat-messages')).toBeTruthy();
   });
 });
+
+// ═══════════════════════════════════════════════════════════════════
+// Tool Invocation Message Parts
+// ═══════════════════════════════════════════════════════════════════
+
+describe('Messages with tool invocation parts', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it('should persist and restore messages containing tool invocation parts', () => {
+    const msg = makeMsgWithToolParts({
+      id: 'a1',
+      role: 'assistant',
+      text: 'Creating object...',
+      toolParts: [
+        {
+          toolName: 'create_object',
+          toolCallId: 'tc_1',
+          state: 'output-available',
+          input: { name: 'project', label: 'Project' },
+          output: { name: 'project', label: 'Project', fieldCount: 0 },
+        },
+      ],
+    });
+    saveMessages([msg]);
+    const restored = loadMessages();
+    expect(restored).toHaveLength(1);
+    expect(restored[0].parts).toHaveLength(2); // text + tool part
+  });
+
+  it('should handle messages with only tool parts (no text)', () => {
+    const msg = makeMsgWithToolParts({
+      id: 'a2',
+      role: 'assistant',
+      toolParts: [
+        {
+          toolName: 'list_metadata_objects',
+          toolCallId: 'tc_2',
+          state: 'output-available',
+          input: {},
+          output: { objects: [], totalCount: 0 },
+        },
+      ],
+    });
+    saveMessages([msg]);
+    const restored = loadMessages();
+    expect(restored).toHaveLength(1);
+    expect(restored[0].parts).toHaveLength(1); // only tool part
+  });
+
+  it('should persist tool error parts', () => {
+    const msg = makeMsgWithToolParts({
+      id: 'a3',
+      role: 'assistant',
+      toolParts: [
+        {
+          toolName: 'create_object',
+          toolCallId: 'tc_3',
+          state: 'output-error',
+          input: { name: 'Bad Name' },
+          errorText: 'Invalid object name "Bad Name". Must be snake_case.',
+        },
+      ],
+    });
+    saveMessages([msg]);
+    const restored = loadMessages();
+    expect(restored).toHaveLength(1);
+    const toolPart = restored[0].parts.find((p: { type: string }) => p.type === 'dynamic-tool');
+    expect(toolPart).toBeDefined();
+  });
+});