@huyooo/ai-chat-core 0.3.6 → 0.3.8

package/src/tool-manager/types.ts

@@ -1,389 +0,0 @@
-/**
- * 工具运行时类型定义
- *
- * - ToolDescriptor / Provider / Manager：注册、搜索、会话级启用
- * - MCP 连接信息、中间件与执行统计
- * - 与治理类型组合描述工具元数据与安全策略
- */
-
-import type {
-  AssetApprovalPolicy,
-  AssetHostDependency,
-  AssetSideEffectLevel,
-  AssetSource,
-  ManagedAssetSummaryBase,
-} from '../governance/types';
-import type { Tool, JsonSchemaObject, ToolUI } from '../types';
-
-// ══════════════════════ Tool Descriptor ══════════════════════
-
-/** 工具描述符（纯元数据，不含 execute 实现） */
-export interface ToolDescriptor {
-  /** 全局唯一标识：scoped 工具 = source:assetId:name，独立工具 = source:name */
-  id: string;
-  /** 工具集 ID（scope 命名空间） */
-  assetId: string;
-  /** scope 内的工具名 */
-  name: string;
-  /** 对模型/用户暴露的稳定别名 */
-  alias: string;
-  /** UI 展示名称 */
-  displayName: string;
-  description: string;
-  parameters: JsonSchemaObject;
-  /** 成功时 data 内的业务结构（JSON Schema，可选） */
-  outputSchema?: JsonSchemaObject;
-  /** 成功返回标准信封结构（JSON Schema，可选） */
-  resolvedOutputSchema?: JsonSchemaObject;
-  /** 失败返回结构（JSON Schema，默认平台标准错误结构） */
-  errorSchema?: JsonSchemaObject;
-  category: string;
-  tags: string[];
-  source: AssetSource;
-  /** 所属 provider id，用于追溯来源 */
-  provider: string;
-  ui?: ToolUI;
-  requiresApproval?: boolean;
-  approvalPolicy?: AssetApprovalPolicy;
-  sideEffectLevel?: AssetSideEffectLevel;
-  hostDependency?: AssetHostDependency;
-}
-
-// ══════════════════════ Management Summaries ══════════════════════
-
-/** 面向管理 API 的统一工具摘要 */
-export interface ManagedToolSummary extends ManagedAssetSummaryBase {
-  ref: string;
-  id: string;
-  assetId: string;
-  alias: string;
-  name: string;
-  displayName: string;
-  description: string;
-  /** 输入参数结构。tool_search 可带出，便于模型直接形成正确调用。 */
-  parameters?: JsonSchemaObject;
-  /** 成功返回结构。 */
-  outputSchema?: JsonSchemaObject;
-  /** 成功返回标准信封结构。 */
-  resolvedOutputSchema?: JsonSchemaObject;
-  /** 标准错误返回结构。 */
-  errorSchema?: JsonSchemaObject;
-  category: string;
-  tags: string[];
-  source: AssetSource;
-  provider: string;
-  active?: boolean;
-  chatEnabled?: boolean;
-  /** Whether this tool is callable in the current chat turn. */
-  callable?: boolean;
-  /** Machine-readable next action before the model may call this tool. */
-  requiredAction?: 'call_tool' | 'tool_enable';
-  /** Stable ref to pass to tool_enable when requiredAction is tool_enable. */
-  enableRef?: string;
-  /** Short instruction for agents consuming search/list results. */
-  usageHint?: string;
-  extension?: {
-    id: string;
-    name: string;
-    description: string;
-    source: string;
-    enabled: boolean;
-    features: string[];
-    category: string;
-    version?: string;
-    featureDetails?: Record<string, unknown>;
-  };
-}
-
-export interface ManagedToolDetail extends ManagedToolSummary {
-  parameters: JsonSchemaObject;
-  outputSchema?: JsonSchemaObject;
-  resolvedOutputSchema?: JsonSchemaObject;
-  errorSchema?: JsonSchemaObject;
-  hasProject: boolean;
-  sourceCode?: string;
-}
-
-/** 面向管理 API 的统一 MCP Server 摘要 */
-export interface ManagedMcpServerSummary extends ManagedAssetSummaryBase {
-  ref: string;
-  name: string;
-  description?: string;
-  category?: string;
-  tags: string[];
-  enabled: boolean;
-  status: McpConnectionStatus | 'disabled';
-  toolCount: number;
-  error?: string;
-  hasDistBundle: boolean;
-  projectDir: string;
-}
-
-export interface ManagedMcpServerDetail extends ManagedMcpServerSummary {
-  meta?: Record<string, unknown>;
-  code?: string;
-  dependencies?: Record<string, string>;
-}
-
-// ══════════════════════ Change Events ══════════════════════
-
-/** 工具变更事件 */
-export interface ToolChangeEvent {
-  type: 'added' | 'removed' | 'updated';
-  tools: ToolDescriptor[];
-  provider: string;
-  /** 重连导致的临时移除，工具将很快重新添加 */
-  reconnecting?: boolean;
-}
-
-export type ToolChangeListener = (event: ToolChangeEvent) => void;
-
-/** 会话工具变更事件 */
-export interface SessionToolsChangeEvent {
-  reason: 'enabled' | 'disabled' | 'provider_changed' | 'reloaded' | 'middleware_updated' | 'destroyed';
-  toolNames: string[];
-}
-
-export type SessionToolsChangeListener = (event: SessionToolsChangeEvent) => void | Promise<void>;
-
-// ══════════════════════ Connection Status ══════════════════════
-
-export type McpConnectionStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
-
-/** 连接状态变更事件 */
-export interface ConnectionStatusEvent {
-  provider: string;
-  status: McpConnectionStatus;
-  error?: string;
-}
-
-export type ConnectionStatusListener = (event: ConnectionStatusEvent) => void;
-
-// ══════════════════════ Middleware ══════════════════════
-
-/** 工具执行中间件（日志/限流/重试/监控等） */
-export interface ToolMiddleware {
-  beforeExecute?: (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
-  afterExecute?: (
-    name: string,
-    args: Record<string, unknown>,
-    result: import('../types').ToolResult,
-    durationMs: number,
-  ) => Promise<import('../types').ToolResult | void>;
-  onError?: (name: string, args: Record<string, unknown>, error: unknown) => Promise<void>;
-}
-
-// ══════════════════════ Execution Stats ══════════════════════
-
-/** 单个工具的执行统计 */
-export interface ToolExecutionStats {
-  totalCalls: number;
-  successCount: number;
-  errorCount: number;
-  totalDurationMs: number;
-  lastCallAt?: number;
-}
-
-// ══════════════════════ ToolProvider ══════════════════════
-
-/**
- * 工具提供者——任何工具来源的统一抽象
- *
- * InProcessProvider / McpProvider / 未来的 RemoteProvider 均实现此接口。
- */
-export interface ToolProvider {
-  readonly id: string;
-  readonly source: AssetSource;
-
-  /** 初始化（连接 MCP / 扫描磁盘 / 注册内置工具） */
-  init(): Promise<void>;
-  /** 销毁（断开连接 / 清理资源） */
-  destroy(): Promise<void>;
-
-  /** 当前所有工具的描述符 */
-  getDescriptors(): ToolDescriptor[];
-  /** 加载工具实例（返回可调用的 Tool） */
-  loadTool(name: string): Promise<Tool | null>;
-
-  addChangeListener(listener: ToolChangeListener): void;
-  removeChangeListener(listener: ToolChangeListener): void;
-
-  /** 远程 Provider 的连接信息（可选） */
-  getConnectionInfo?(): McpConnectionInfo;
-  /** 重新连接（可选） */
-  reconnect?(): Promise<void>;
-  addConnectionStatusListener?(listener: ConnectionStatusListener): void;
-  removeConnectionStatusListener?(listener: ConnectionStatusListener): void;
-}
-
-// ══════════════════════ InProcessProvider 扩展 ══════════════════════
-
-/** InProcessProvider 在 ToolProvider 基础上提供的额外方法 */
-export interface InProcessProvider extends ToolProvider {
-  register(tool: Tool, meta?: { category?: string; tags?: string[]; source?: AssetSource }): void;
-  registerAll(toolList: Tool[], meta?: { category?: string; tags?: string[]; source?: AssetSource }): void;
-  unregister(name: string): void;
-  /** 热替换（更新后自动通知） */
-  replace(tool: Tool, meta?: { category?: string; tags?: string[]; source?: AssetSource }): void;
-  has(name: string): boolean;
-}
-
-// ══════════════════════ McpProvider 扩展 ══════════════════════
-
-export interface McpReconnectConfig {
-  enabled?: boolean;
-  maxRetries?: number;
-  /** 首次重连延迟（ms），默认 1000 */
-  initialDelayMs?: number;
-  /** 最大重连延迟（ms），默认 30000 */
-  maxDelayMs?: number;
-}
-
-export interface StreamableHttpReconnectionOptions {
-  /** 首次重连延迟（ms），默认 1000 */
-  initialReconnectionDelay?: number;
-  /** 最大重连延迟（ms），默认 30000 */
-  maxReconnectionDelay?: number;
-  /** 退避增长因子，默认 1.5 */
-  reconnectionDelayGrowFactor?: number;
-  /** 最大重试次数，默认 2 */
-  maxRetries?: number;
-}
-
-export interface StdioMcpServerConfig {
-  name: string;
-  transport: 'stdio';
-  command: string;
-  args?: string[];
-  env?: Record<string, string>;
-  cwd?: string;
-  reconnect?: McpReconnectConfig;
-}
-
-export interface StreamableHttpMcpServerConfig {
-  name: string;
-  transport: 'streamableHttp';
-  url: string;
-  headers?: Record<string, string>;
-  /** SDK 内置重连配置（仅 streamableHttp 生效） */
-  reconnectionOptions?: StreamableHttpReconnectionOptions;
-  /** 恢复已有会话（仅 streamableHttp 生效） */
-  sessionId?: string;
-  /** 应用层会话级重连配置 */
-  reconnect?: McpReconnectConfig;
-}
-
-export interface SseMcpServerConfig {
-  name: string;
-  transport: 'sse';
-  url: string;
-  headers?: Record<string, string>;
-  /** 旧版 SSE 仅支持应用层重连 */
-  reconnect?: McpReconnectConfig;
-}
-
-/**
- * MCP Server 配置（判别联合）
- *
- * - stdio: 本地子进程，stdin/stdout 通信
- * - streamableHttp: 推荐的 HTTP 传输（SDK 内置重连 + 流恢复 + 会话管理）
- * - sse: 旧版 SSE 传输（已被 SDK 标记 deprecated，仅用于兼容旧 MCP Server）
- */
-export type McpServerConfig =
-  | StdioMcpServerConfig
-  | StreamableHttpMcpServerConfig
-  | SseMcpServerConfig;
-
-/** MCP 连接信息（只读快照） */
-export interface McpConnectionInfo {
-  name: string;
-  status: McpConnectionStatus;
-  toolCount: number;
-  error?: string;
-  lastConnectedAt?: number;
-  reconnectAttempts?: number;
-}
-
-/** McpProvider 在 ToolProvider 基础上提供的额外方法 */
-export interface McpProviderExtended extends ToolProvider {
-  getStatus(): McpConnectionStatus;
-  getError(): string | undefined;
-  getConfig(): McpServerConfig;
-  getConnectionInfo(): McpConnectionInfo;
-  reconnect(): Promise<void>;
-  addConnectionStatusListener(listener: ConnectionStatusListener): void;
-  removeConnectionStatusListener(listener: ConnectionStatusListener): void;
-}
-
-// ══════════════════════ Search ══════════════════════
-
-/** 搜索条件 */
-export interface ToolSearchQuery {
-  keyword?: string;
-  category?: string;
-  tags?: string[];
-  source?: AssetSource;
-}
-
-/** 分类汇总 */
-export interface CategorySummary {
-  category: string;
-  count: number;
-}
-
-// ══════════════════════ Provider Info ══════════════════════
-
-/** Provider 摘要信息 */
-export interface ProviderInfo {
-  id: string;
-  source: AssetSource;
-  toolCount: number;
-}
-
-// ══════════════════════ ToolRuntimeManager ══════════════════════
-
-/** 工具运行时管理器接口 */
-export interface ToolRuntimeManager {
-  // Provider 管理
-  addProvider(provider: ToolProvider): Promise<void>;
-  removeProvider(id: string): Promise<void>;
-  getProviders(): ProviderInfo[];
-  getProvider(id: string): ToolProvider | undefined;
-
-  // 精确查找
-  getDescriptor(name: string): ToolDescriptor | undefined;
-  hasDescriptor(name: string): boolean;
-
-  // 统一搜索
-  search(query?: ToolSearchQuery): ToolDescriptor[];
-  getAllDescriptors(): ToolDescriptor[];
-
-  // 会话级启用/禁用
-  enable(names: string[]): Promise<Tool[]>;
-  disable(names: string[]): void;
-  enableAll(): Promise<Tool[]>;
-  getSessionTools(): Map<string, Tool>;
-  getSessionToolNames(): string[];
-
-  // 中间件
-  use(middleware: ToolMiddleware): void;
-
-  // 变更订阅
-  addChangeListener(listener: ToolChangeListener): void;
-  removeChangeListener(listener: ToolChangeListener): void;
-  addConnectionStatusListener(listener: ConnectionStatusListener): void;
-  removeConnectionStatusListener(listener: ConnectionStatusListener): void;
-  addSessionToolsChangeListener(listener: SessionToolsChangeListener): void;
-  removeSessionToolsChangeListener(listener: SessionToolsChangeListener): void;
-
-  // 统计
-  categories(): CategorySummary[];
-  getStats(): Map<string, ToolExecutionStats>;
-  getToolStats(name: string): ToolExecutionStats | undefined;
-
-  // MCP 连接聚合
-  getMcpConnectionInfos(): McpConnectionInfo[];
-
-  // 生命周期
-  destroy(): Promise<void>;
-}