// 助手工具的标准格式(SPI):所有能力来源——知识库、ai-api 函数、宿主 ai-tools/ 声明——
// 最终都编译成同一种工具包对象进注册中心。
//
// 原子工具契约直接采用 Vercel AI SDK 的 ToolSet,不另造格式:入参 zod 校验、
// 工具调用协议、流式回放都由 SDK 白拿,本层只负责"注册与治理"这一段。
//
// 工具包只回一件事:一个 bundle。工具面、展示文案、提示词能力段同源同刻产出,
// 避免"列工具"与"跑工具"看到两份不一致的视图(tools-meta 与 chat 共用此入口)。

import type { ToolSet } from 'ai';
import type { AiRuntimeConfig } from '../../ai-shared/AiRuntimeConfig';

export interface AssistantToolkitContext {
  config: AiRuntimeConfig;
  hostDir: string;
  /** assistant.toolkits.<name> 的配置透传,工具包自行解释。 */
  options: Record<string, unknown>;
  /** 声明式工具回调宿主自身接口用的 origin;取不到时为空串。 */
  requestOrigin: string;
  /** 会话超时预算信号;工具包内的扫描/读盘都应遵守。 */
  signal?: AbortSignal;
}

/** Widget 三态文案,面向最终用户,不含实现细节。 */
export interface AssistantToolDisplay {
  pending: string;
  done: string;
  error: string;
}

export interface AssistantToolBundle {
  tools: ToolSet;
  /** 按工具名下发的展示文案;缺项由 Widget 回退通用文案。 */
  display?: Record<string, AssistantToolDisplay>;
  /** 本包贡献的提示词能力段;无能力可用时返回 undefined。 */
  systemPrompt?: string;
}

export interface AssistantToolkit {
  /** 工具包名,同时是 assistant.toolkits.<name> 的配置键。 */
  readonly name: string;
  /**
   * 宿主未在配置里表态时的开关缺省值,省略即 true。
   * 只有"光装包还不够、宿主必须再接一段适配才真正生效"的包才写 false
   * (如 page-operate 需要宿主在浏览器侧接事件桥),免得能力名存实亡。
   */
  readonly defaultEnabled?: boolean;
  create(context: AssistantToolkitContext): Promise<AssistantToolBundle> | AssistantToolBundle;
}