@svadmin/core 0.47.1 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.47.1",
+  "version": "0.49.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",
@@ -68,6 +68,10 @@
     "./inferencer-graphql": {
       "types": "./src/inferencer-graphql.ts",
       "default": "./src/inferencer-graphql.ts"
+    },
+    "./admin-tool": {
+      "types": "./src/admin-tool.ts",
+      "default": "./src/admin-tool.ts"
     }
   },
   "bugs": {
@@ -86,7 +90,9 @@
   "sideEffects": false,
   "type": "module",
   "types": "src/index.ts",
-  "dependencies": {},
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.52"
+  },
   "peerDependenciesMeta": {
     "svelte": {
       "optional": true

package/src/admin-tool.ts

@@ -0,0 +1,99 @@
+import type { StaticDecode, TObject } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+
+/** Result returned by a tool execution. */
+export interface ToolResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+/**
+ * A tool that the Agent can invoke within the admin panel.
+ *
+ * @example
+ * ```ts
+ * const deletePostTool = defineAdminTool({
+ *   name: 'deletePosts',
+ *   description: 'Delete posts matching a filter',
+ *   parameters: Type.Object({
+ *     status: Type.Union([Type.Literal('draft'), Type.Literal('archived')]),
+ *   }),
+ *   needsApproval: true,
+ *   execute: async ({ status }) => {
+ *     const result = await dataProvider.getList({
+ *       resource: 'posts',
+ *       filters: [{ field: 'status', operator: 'eq', value: status }],
+ *     });
+ *     return { success: true, data: result };
+ *   },
+ * });
+ * ```
+ */
+export interface AdminTool<Schema extends TObject = TObject> {
+  /** Unique tool name (e.g. 'getList', 'deleteRecords', 'generateReport') */
+  name: string;
+  /** Human-readable description for LLM tool-use prompting */
+  description: string;
+  /** TypeBox schema used for static inference, runtime validation, and LLM projection. */
+  parameters: Schema;
+  /** Pause execution until the user explicitly approves the invocation. */
+  needsApproval?: boolean;
+  /** 显式声明是否为只读操作（只读操作可并发执行，无副作用）。 */
+  readOnly?: boolean;
+  /** 显式声明是否为破坏性或高风险操作。 */
+  destructive?: boolean;
+  /** 显式声明是否支持并发调用。 */
+  concurrent?: boolean;
+  /** Execute the tool with decoded arguments. */
+  execute(args: StaticDecode<Schema>): Promise<ToolResult>;
+}
+
+/** 保留具体 TypeBox Schema，让 execute 参数获得精确的静态类型。 */
+export function defineAdminTool<const Schema extends TObject>(
+  tool: AdminTool<Schema>,
+): AdminTool<Schema> {
+  return { ...tool, parameters: strictAdminToolSchema(tool.parameters) };
+}
+
+/** 在进入工具实现前统一执行 TypeBox 校验与转换。 */
+export function decodeAdminToolArgs<const Schema extends TObject>(
+  tool: AdminTool<Schema>,
+  input: unknown,
+): StaticDecode<Schema> {
+  return Value.Decode(strictAdminToolSchema(tool.parameters), input);
+}
+
+/** 解码并执行工具，避免调用方绕过运行时参数边界。 */
+export async function executeAdminTool<const Schema extends TObject>(
+  tool: AdminTool<Schema>,
+  input: unknown,
+): Promise<ToolResult> {
+  return tool.execute(decodeAdminToolArgs(tool, input));
+}
+
+/** 将工具投影为发给 LLM 或 MCP 客户端的公开 Schema。 */
+export function projectAdminToolSchema<Schema extends TObject>(tool: AdminTool<Schema>): {
+  name: string;
+  description: string;
+  parameters: Schema;
+  readOnly?: boolean;
+  destructive?: boolean;
+  concurrent?: boolean;
+  needsApproval?: boolean;
+} {
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: strictAdminToolSchema(tool.parameters),
+    ...(tool.readOnly !== undefined ? { readOnly: tool.readOnly } : {}),
+    ...(tool.destructive !== undefined ? { destructive: tool.destructive } : {}),
+    ...(tool.concurrent !== undefined ? { concurrent: tool.concurrent } : {}),
+    ...(tool.needsApproval !== undefined ? { needsApproval: tool.needsApproval } : {}),
+  };
+}
+
+function strictAdminToolSchema<Schema extends TObject>(schema: Schema): Schema {
+  if (schema.additionalProperties === false) return schema;
+  return { ...schema, additionalProperties: false };
+}

package/src/chatProvider.svelte.ts

@@ -1,49 +1,93 @@
-// Chat & Agent provider — headless interface for AI integration
-//
-// Two abstraction levels:
-//   1. ChatProvider  — simple message-in / text-out  (backward compatible)
-//   2. AgentProvider — tool calling, approval gates, generative UI events
-//
-// Inspired by Vercel AI SDK 6 agent abstractions.
-
-/** Describes an actionable button rendered in assistant messages (tool-call UX). */
-export interface ChatAction {
-  label: string;
-  /** Optional variant for styling (e.g. 'destructive' renders red) */
-  variant?: 'default' | 'destructive' | 'outline';
-  /** Arbitrary payload forwarded to the onAction handler */
-  payload?: Record<string, unknown>;
+// Headless AI contracts. Rendering lives in @svadmin/ai-elements.
+
+import type { AdminTool, ToolResult } from './admin-tool';
+
+export type { AdminTool, ToolResult } from './admin-tool';
+export {
+  decodeAdminToolArgs,
+  defineAdminTool,
+  executeAdminTool,
+  projectAdminToolSchema,
+} from './admin-tool';
+
+export type ToolState =
+  | 'input-streaming'
+  | 'input-available'
+  | 'approval-requested'
+  | 'approval-responded'
+  | 'output-available'
+  | 'output-denied'
+  | 'output-error';
+
+export type MessageStatus = 'submitted' | 'streaming' | 'complete' | 'aborted' | 'error';
+
+export interface ChatAttachment {
+  id: string;
+  name: string;
+  mediaType?: string;
+  url?: string;
+  size?: number;
+  /** 原始浏览器文件，供上传适配器直接读取；持久化恢复时不会保留。 */
+  file?: File;
+}
+
+export interface ChatSource {
+  id?: string;
+  title: string;
+  url?: string;
+  quote?: string;
+  description?: string;
 }
 
+export type ChatMessagePart =
+  | { id?: string; type: 'text'; text: string }
+  | { id?: string; type: 'reasoning'; text: string; streaming?: boolean }
+  | { id?: string; type: 'tool-call'; tool: string; input: unknown; state: ToolState; callId?: string }
+  | { id?: string; type: 'tool-result'; tool: string; output: unknown; error?: string; callId?: string }
+  | { id?: string; type: 'source'; source: ChatSource }
+  | { id?: string; type: 'image'; src: string; alt?: string; width?: number; height?: number }
+  | { id?: string; type: 'file'; file: ChatAttachment }
+  | {
+      id?: string;
+      type: 'approval';
+      approvalId: string;
+      tool: string;
+      input: Record<string, unknown>;
+      description: string;
+      approved?: boolean;
+    }
+  | { id?: string; type: 'component'; name: string; props: Record<string, unknown> };
+
 export interface ChatMessage {
   id: string;
   role: 'user' | 'assistant' | 'system';
-  content: string;
-  timestamp: number;
-  /** Tool-call action buttons rendered below the message bubble */
-  actions?: ChatAction[];
+  parts: ChatMessagePart[];
+  status?: MessageStatus;
+  createdAt: number;
+  attachments?: ChatAttachment[];
 }
 
-/** Admin context automatically injected into chat system messages. */
+/** Admin context passed separately from untrusted conversation messages. */
 export interface ChatContext {
   currentResource?: string;
-  selectedRecordId?: string;
-  currentView?: 'list' | 'edit' | 'create' | 'show';
+  selectedRecordId?: string | number;
+  currentView?: 'list' | 'edit' | 'create' | 'show' | string;
   pathname?: string;
+  metadata?: Record<string, unknown>;
 }
 
 /**
  * ChatProvider interface for integrating AI chat into admin panels.
  * Implement `sendMessage` to connect to any AI backend (OpenAI, self-hosted, etc.)
  *
- * Return a `string` for non-streaming responses, or an `AsyncGenerator<string>`
- * for streaming (SSE / chunked) responses.
+ * Return text or structured parts for non-streaming responses. For streaming
+ * transports, yield text chunks and/or structured parts from an async generator.
  */
 export interface ChatProvider {
   sendMessage(
     messages: ChatMessage[],
-    options?: { signal?: AbortSignal },
-  ): Promise<string> | AsyncGenerator<string, void, unknown>;
+    options?: { signal?: AbortSignal; context?: ChatContext },
+  ): Promise<ChatMessagePart[] | string> | AsyncGenerator<ChatMessagePart | string, void, unknown>;
 }
 
 // ─── Agent Provider (extends ChatProvider concept) ─────────────
@@ -53,72 +97,20 @@ export interface ChatProvider {
 //   • Approval gates — Dangerous tools require user confirmation before execution
 //   • Generative UI — Agent returns component name + props for dynamic rendering
 
-/** JSON-Schema-compatible parameter definition for an admin tool. */
-export interface AdminToolParameter {
-  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
-  description?: string;
-  enum?: string[];
-  required?: boolean;
-}
-
-/**
- * A tool that the Agent can invoke within the admin panel.
- *
- * @example
- * ```ts
- * const deletePostTool: AdminTool = {
- *   name: 'deletePosts',
- *   description: 'Delete posts matching a filter',
- *   parameters: {
- *     status: { type: 'string', description: 'Filter by status', enum: ['draft', 'archived'] },
- *   },
- *   needsApproval: true,
- *   execute: async (params) => {
- *     const result = await dataProvider.deleteMany({ resource: 'posts', ids: params.ids });
- *     return { success: true, data: result };
- *   },
- * };
- * ```
- */
-export interface AdminTool {
-  /** Unique tool name (e.g. 'getList', 'deleteRecords', 'generateReport') */
-  name: string;
-  /** Human-readable description for LLM tool-use prompting */
-  description: string;
-  /** JSON-Schema-style parameter definitions */
-  parameters: Record<string, AdminToolParameter>;
-  /**
-   * When `true`, execution is paused until the user explicitly approves.
-   * The agent emits an `approval_request` event and waits for `approveToolCall()`.
-   */
-  needsApproval?: boolean;
-  /** 显式声明是否为只读操作（只读操作可并发执行，无副作用） */
-  readOnly?: boolean;
-  /** 显式声明是否为破坏性/高风险操作（默认触发 Approval Gate） */
-  destructive?: boolean;
-  /** 显式声明是否支持并发调用 */
-  concurrent?: boolean;
-  /** Execute the tool with the given arguments. */
-  execute(args: Record<string, unknown>): Promise<ToolResult>;
-}
-
-/** Result returned by a tool execution. */
-export interface ToolResult {
-  success: boolean;
-  data?: unknown;
-  error?: string;
-}
-
 /** Discriminated union of events emitted by an AgentProvider. */
 export type AgentEvent =
   /** Streaming text chunk */
   | { type: 'text'; content: string }
+  /** Streaming reasoning chunk */
+  | { type: 'reasoning'; content: string; streaming?: boolean }
   /** Agent wants to call a tool (informational — execution is handled internally) */
-  | { type: 'tool_call'; tool: string; args: Record<string, unknown> }
+  | { type: 'tool_call'; tool: string; args: Record<string, unknown>; callId?: string }
   /** Agent wants to call a tool that requires user approval before execution */
   | { type: 'approval_request'; id: string; tool: string; args: Record<string, unknown>; description: string }
   /** Tool execution completed */
-  | { type: 'tool_result'; tool: string; result: ToolResult }
+  | { type: 'tool_result'; tool: string; result: ToolResult; callId?: string }
+  /** Source attribution emitted by a retrieval step */
+  | { type: 'source'; source: ChatSource }
   /** Agent wants to render a named component (Generative UI) */
   | { type: 'component'; name: string; props: Record<string, unknown> }
   /** Stream finished */
@@ -131,6 +123,14 @@ export interface AgentOptions {
   context?: ChatContext;
 }
 
+/**
+ * Cancellation signal supplied while an approval decision is being submitted.
+ * Providers must stop before committing tool execution when this signal aborts.
+ */
+export interface ApprovalResponseOptions {
+  signal: AbortSignal;
+}
+
 /**
  * AgentProvider — advanced AI integration with tool calling and approval gates.
  *
@@ -159,7 +159,11 @@ export interface AgentProvider {
     messages: ChatMessage[],
     options?: AgentOptions,
   ): AsyncGenerator<AgentEvent, void, unknown>;
-  approveToolCall?(id: string, approved: boolean): void;
+  approveToolCall?(
+    id: string,
+    approved: boolean,
+    options: ApprovalResponseOptions,
+  ): void | Promise<void>;
 }
 
 // ─── Chat Provider singleton ───────────────────────────────────
@@ -230,30 +234,6 @@ export function getChatContext(): ChatContext {
   return chatContext;
 }
 
-/**
- * 将 AdminTool 投影为发给 LLM / MCP 客户端的白名单 Schema。
- * 剥离底层执行逻辑（execute）与宿主私有状态，保留 name、description、parameters 及并发/安全声明。
- */
-export function projectAdminToolSchema(tool: AdminTool): {
-  name: string;
-  description: string;
-  parameters: Record<string, AdminToolParameter>;
-  readOnly?: boolean;
-  destructive?: boolean;
-  concurrent?: boolean;
-  needsApproval?: boolean;
-} {
-  return {
-    name: tool.name,
-    description: tool.description,
-    parameters: { ...tool.parameters },
-    ...(tool.readOnly !== undefined ? { readOnly: tool.readOnly } : {}),
-    ...(tool.destructive !== undefined ? { destructive: tool.destructive } : {}),
-    ...(tool.concurrent !== undefined ? { concurrent: tool.concurrent } : {}),
-    ...(tool.needsApproval !== undefined ? { needsApproval: tool.needsApproval } : {}),
-  };
-}
-
 export function resetChatProvider(): void {
   chatProvider = null;
   agentProvider = null;

package/src/index.ts

@@ -116,8 +116,12 @@ export type {
   WebhookSummary,
 } from './enterprise';
 export { assertEnterpriseRequestContext, createEnterpriseRequestContext } from './enterprise';
-export { setChatProvider, getChatProvider, setChatContext, getChatContext, setAgentProvider, getAgentProvider, registerApproval, resolveApproval, hasPendingApprovals, resetChatProvider, projectAdminToolSchema } from './chatProvider.svelte';
-export type { ChatProvider, ChatMessage, ChatContext, ChatAction, AgentProvider, AgentEvent, AgentOptions, AdminTool, AdminToolParameter, ToolResult } from './chatProvider.svelte';
+export { setChatProvider, getChatProvider, setChatContext, getChatContext, setAgentProvider, getAgentProvider, registerApproval, resolveApproval, hasPendingApprovals, resetChatProvider, defineAdminTool, decodeAdminToolArgs, executeAdminTool, projectAdminToolSchema } from './chatProvider.svelte';
+export type {
+  ChatProvider, ChatMessage, ChatMessagePart, ChatContext, ChatAttachment, ChatSource,
+  MessageStatus, ToolState, AgentProvider, AgentEvent, AgentOptions, ApprovalResponseOptions,
+  AdminTool, ToolResult,
+} from './chatProvider.svelte';
 export { getTheme, setTheme, toggleTheme, getResolvedTheme, getColorTheme, setColorTheme, getColorThemes, configureTheme, getThemeConfig, clearCssOverrides, builtinPresets, registerColorPreset, getColorPresets, registerThemeOwner, updateThemeOwner, unregisterThemeOwner, resetTheme } from './theme.svelte';
 export type { ThemeMode, ColorTheme, ThemeStrategy, ThemeConfig, ColorPreset, ThemeOwnerOptions, ThemeOwnerToken } from './theme.svelte';
 export { setUnsavedChanges, getUnsavedChanges, initUnsavedChangesNotifier, resetUnsavedChanges } from './unsaved-changes.svelte';