@svadmin/core 0.48.0 → 0.49.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.48.0",
+  "version": "0.49.1",
   "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,5 +1,15 @@
 // 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'
@@ -87,62 +97,6 @@ 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 */
@@ -280,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,11 +116,11 @@ 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 { 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, AdminToolParameter, ToolResult,
+  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';