@ruixutong.manee/agent-framework 1.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/agent/decorators/index.ts","../src/agent/schema.ts","../src/agent/index.ts","../src/llm/base/index.ts","../src/llm/openai-schema.ts","../src/llm/chat/index.ts","../src/llm/responses/index.ts"],"sourcesContent":["import type { ToolDefinition, ToolRuntimeDefinition } from '../types';\n\nconst toolDefinitionsMetadataKey = Symbol.for('@manee/agent-framework/toolDefinitions');\n\ninterface ToolInitializerReceiver {\n  tools?: ToolRuntimeDefinition[];\n}\n\n/**\n * 将 Agent 方法声明为可被模型调用的工具。\n *\n * 装饰器在类级 metadata 中记录 `toolsDefinition` 静态定义，并为每个实例\n * 注册绑定后的运行时 handler。\n */\nexport function Tool(definition: ToolDefinition) {\n  return function (value: unknown, context: ClassMethodDecoratorContext) {\n    if (context.kind !== 'method' || typeof value !== 'function') {\n      throw new Error('@Tool can only decorate methods.');\n    }\n\n    const method = value as (this: object, parameters: unknown) => unknown | Promise<unknown>;\n\n    // 2023-11 decorator metadata 位于类级别；写入前复制继承数组，避免子类工具\n    // 污染父类的 `toolsDefinition`。\n    registerToolDefinition(context.metadata as Record<PropertyKey, unknown>, {\n      ...definition,\n    });\n\n    // initializer 绑定当前实例，使 private method 也能安全作为运行时工具执行。\n    context.addInitializer(function (this: unknown) {\n      if (typeof this !== 'object' || this === null) {\n        return;\n      }\n\n      const receiver = this as ToolInitializerReceiver;\n\n      receiver.tools ??= [];\n      receiver.tools.push({\n        ...definition,\n        handler: method.bind(receiver),\n      });\n    });\n  };\n}\n\n/** 获取类构造器的静态工具定义浅拷贝，避免外部修改内部定义数组。 */\nexport function getToolDefinitions(target: object): ToolDefinition[] {\n  const metadata = (target as Record<PropertyKey, unknown>)[getMetadataSymbol()] as\n    | Record<PropertyKey, unknown>\n    | undefined;\n  const definitions = metadata?.[toolDefinitionsMetadataKey];\n\n  return Array.isArray(definitions)\n    ? definitions.map((definition) => ({\n        ...definition,\n      }))\n    : [];\n}\n\nfunction registerToolDefinition(\n  metadata: Record<PropertyKey, unknown>,\n  definition: ToolDefinition,\n): void {\n  // 子类第一次写入 metadata 时需要复制父类数组，否则会把子类工具挂到父类上。\n  const hasOwnDefinitions = Object.prototype.hasOwnProperty.call(\n    metadata,\n    toolDefinitionsMetadataKey,\n  );\n  const currentDefinitions = metadata[toolDefinitionsMetadataKey];\n  const definitions =\n    hasOwnDefinitions && Array.isArray(currentDefinitions)\n      ? currentDefinitions\n      : Array.isArray(currentDefinitions)\n        ? [...currentDefinitions]\n        : [];\n\n  definitions.push(definition);\n  metadata[toolDefinitionsMetadataKey] = definitions;\n}\n\nfunction getMetadataSymbol(): symbol {\n  // 兼容不同运行时对 2023-11 decorator metadata symbol 的实现命名。\n  return (\n    (Symbol as typeof Symbol & { metadata?: symbol }).metadata ?? Symbol.for('Symbol.metadata')\n  );\n}\n","import { z } from 'zod';\n\nimport type { ToolParametersSchema } from './types';\n\nconst emptyParametersSchema = z.object({});\n\n/** 为没有声明参数的工具提供默认空对象 schema，供本地参数校验使用。 */\nexport function getDefaultToolParametersSchema(): ToolParametersSchema {\n  return emptyParametersSchema;\n}\n","import { z } from 'zod';\n\nimport { getToolDefinitions, Tool } from './decorators';\nimport { getDefaultToolParametersSchema } from './schema';\nimport type {\n  AfterToolCallCallback,\n  AgentConstructor,\n  AgentErrorCallback,\n  AgentOptions,\n  AgentProtocol,\n  AgentSkill,\n  AgentStatus,\n  AgentStatusChangedCallback,\n  AgentToolCall,\n  BeforeToolCallCallback,\n  ContextOf,\n  ModelResponseCallback,\n  ToolOf,\n  ToolCallErrorCallback,\n  ToolDefinition,\n  ToolEventOptions,\n  ToolRuntimeDefinition,\n  Unsubscribe,\n  UserMessageOf,\n} from './types';\n\ninterface ToolEventListener<TCallback> {\n  toolName: string;\n  callback: TCallback;\n  options: Required<ToolEventOptions>;\n}\n\ninterface AgentStatusListener<P extends AgentProtocol> {\n  status: AgentStatus;\n  callback: AgentStatusChangedCallback<P>;\n}\n\nconst beforeToolErrorPrefix = '函数调用的前置工作出现异常，异常为：';\nconst internalEndAgentPrompt =\n  '框架约束：当任务完成时，必须单独调用 end-agent 工具结束任务；不能仅用自然语言回答表示结束，也不能把 end-agent 与其他工具放在同一轮调用。';\n// 装饰器 initializer 早于类字段 initializer 执行，因此借助 symbol-backed\n// 存储和公开访问器保留实例工具，避免工具数组被字段初始化覆盖。\nconst toolsStorageKey: unique symbol = Symbol('agent.tools');\n\ninterface ToolsStorageCarrier {\n  [toolsStorageKey]?: ToolRuntimeDefinition[];\n}\n\n/**\n * 运行于 Node.js 的 Agent 主执行器。\n *\n * Agent 管理由模型协议泛型指定的上下文、工具、技能、子代理与生命周期事件。\n * 协议消息的生成和工具调用解析由 `Model<P>` 提供；配置完运行时工具或子代理后，\n * 必须先调用 `init()`，再调用 `agent()` 或 `toolCall()`。\n */\nexport class Agent<P extends AgentProtocol> {\n  /**\n   * 当前 Agent 实例可调用的运行时工具集合。\n   *\n   * 装饰器工具会在实例构造阶段自动注册；也可以在 `init()` 前追加仅在本实例\n   * 生效的工具。\n   */\n  get tools(): ToolRuntimeDefinition[] {\n    return getToolsStorage(this);\n  }\n\n  /** 替换当前实例工具集合；替换后需要重新调用 `init()` 进行重复名校验。 */\n  set tools(tools: ToolRuntimeDefinition[]) {\n    setToolsStorage(this, tools);\n  }\n\n  #rawContext: ContextOf<P>[] = [];\n  #context: ContextOf<P>[] = [];\n  #skills: AgentSkill[] = [];\n  #systemPrompts: string[] = [];\n  #status: AgentStatus = 'idle';\n  #maxIterations: number | undefined;\n  #llm: AgentOptions<P>['llm'];\n  #initialized = false;\n\n  #beforeToolListeners: ToolEventListener<BeforeToolCallCallback<P>>[] = [];\n  #afterToolListeners: ToolEventListener<AfterToolCallCallback<P>>[] = [];\n  #toolCallErrorListeners: ToolCallErrorCallback<P>[] = [];\n  #statusListeners: AgentStatusListener<P>[] = [];\n  #modelResponseListeners: ModelResponseCallback<P>[] = [];\n\n  #agentErrorListeners: AgentErrorCallback[] = [];\n\n  /** 该类作为子代理暴露时使用的人类可读说明。 */\n  static description?: string;\n\n  /** 可由内置 `agent` 工具调度的子代理类集合。 */\n  subAgents: AgentConstructor<P>[] = [];\n\n  /** 当前类及其父类通过装饰器声明的静态工具定义。 */\n  static get toolsDefinition(): readonly ToolDefinition[] {\n    return getToolDefinitions(this);\n  }\n\n  @Tool({\n    name: 'agent',\n    description: ({ subAgents }) => {\n      const agentList =\n        subAgents.length === 0\n          ? '当前没有可调度的子代理。'\n          : subAgents.map(formatSubAgentDescription).join('\\n\\n');\n\n      return [\n        '这是一个子代理调度工具，当你需要调用一个子代理来完成某个任务时，请使用这个工具。调用时请在参数中说明需要调用的子代理名称和输入子代理的内容。',\n        '每次调度同一子代理都是全新的代理，并且可以同时调度多个相同子代理。',\n        '调度子代理时，需要指定任务的描述，以及需要子代理最后汇报你的东西的描述。比如如果是一个任务，那需要汇报你任务的报告；如果是需要一个问题的答案，则是问题的回答。',\n        '以下是当前可用的子代理列表：',\n        agentList,\n      ].join('\\n\\n');\n    },\n    parameters: z.object({\n      agentName: z.string().describe('要调用的子代理名称'),\n      input: z.string().describe('输入子代理的内容'),\n      outputDescription: z\n        .string()\n        .describe('需要让子代理最后交付你的东西的描述，比如任务的报告、问题的回答'),\n    }),\n  })\n  async #toolSubAgent(parameters: unknown): Promise<string> {\n    // `agent` 工具的 handler 只接收一个参数对象，便于所有协议共用同一套调用约定。\n    const { agentName, input, outputDescription } = parameters as {\n      agentName: string;\n      input: string;\n      outputDescription: string;\n    };\n    const TargetAgent = this.subAgents.find((agent) => agent.name === agentName);\n\n    if (!TargetAgent) {\n      return `没有找到名称为 ${agentName} 的子代理。`;\n    }\n\n    let agentResult: string | undefined;\n    const BaseSubAgent = TargetAgent as unknown as new (options: AgentOptions<P>) => Agent<P>;\n\n    // 为本次调度创建临时子类，仅向这一轮子代理执行暴露 `agent-result`。\n    class RuntimeSubAgent extends BaseSubAgent {\n      @Tool({\n        name: 'agent-result',\n        description: `这是一个结果汇报工具，你需要在完成任务后调用这个工具把结果汇报回来`,\n        parameters: z.object({\n          result: z.string().describe(outputDescription),\n        }),\n      })\n      #reportResult(parameters: unknown): string {\n        const { result } = parameters as { result: string };\n\n        agentResult = result;\n        return result;\n      }\n    }\n\n    // 子代理复用模型适配器，但拥有独立上下文，并在启动前走同样的配置校验。\n    const subAgent = new RuntimeSubAgent({\n      llm: this.#llm,\n      systemPrompts: [\n        `你现在是被主代理调度的子代理：${agentName}。`,\n        `主代理输入给你的任务：\\n${input}`,\n        [\n          '完成任务后，调用 end-agent 前必须先调用 agent-result 工具把结果汇报回来。',\n          `agent-result.result 必须满足如下交付描述：\\n${outputDescription}`,\n        ].join('\\n'),\n      ],\n    });\n\n    subAgent.init();\n    await subAgent.agent(input);\n\n    return agentResult ?? '子代理已结束但未通过 agent-result 汇报结果。';\n  }\n\n  /** 使用模型适配器及可选运行配置创建 Agent 实例。 */\n  constructor(options: AgentOptions<P>) {\n    this.#llm = options.llm;\n    this.#maxIterations = options.maxIterations;\n    this.#context = [...(options.initContext ?? options.initRawContext ?? [])];\n    this.#rawContext = [...(options.initRawContext ?? options.initContext ?? [])];\n    this.tools ??= [];\n    this.subAgents = [...(options.subAgents ?? [])];\n\n    if (\n      this.#maxIterations !== undefined &&\n      (this.#maxIterations < 1 || !Number.isInteger(this.#maxIterations))\n    ) {\n      throw new Error('maxIterations must be a positive integer.');\n    }\n\n    this.addSkill(...(options.skills ?? []));\n    this.addSystemPrompts(...(options.systemPrompts ?? []));\n  }\n\n  /** 获取完整历史记录；返回的数组为浅拷贝。 */\n  getHistory(): readonly ContextOf<P>[] {\n    return [...this.#rawContext];\n  }\n\n  /** 获取模型请求使用的活动上下文，不包含临时注入的内部系统提示词。 */\n  getContext(): readonly ContextOf<P>[] {\n    return [...this.#context];\n  }\n\n  /**\n   * 校验运行时配置并将 Agent 标记为已初始化。\n   *\n   * 修改 `tools` 或 `subAgents` 后应重新调用本方法；重复调用只重新校验配置，\n   * 不会清空历史或事件监听。\n   */\n  init(): this {\n    this.#initialized = false;\n    this.#assertUniqueToolNames();\n    this.#assertUniqueSubAgentNames();\n    this.#initialized = true;\n\n    return this;\n  }\n\n  /** 追加非空系统提示词；请求模型时它们排在框架内部提示词之后。 */\n  addSystemPrompts(...prompts: string[]): this {\n    for (const prompt of prompts) {\n      if (prompt.trim().length > 0) {\n        this.#systemPrompts.push(prompt);\n      }\n    }\n\n    return this;\n  }\n\n  /** 追加技能手册；新增技能会从下一次模型请求开始对模型可见。 */\n  addSkill(...skills: AgentSkill[]): this {\n    this.#skills.push(...skills);\n    return this;\n  }\n\n  /** 向完整历史和活动上下文同时追加文本或多模态消息。 */\n  appendContext(message: ContextOf<P>): this {\n    this.#appendMessage(message);\n    return this;\n  }\n\n  /** 在任一模型返回消息写入上下文前，监听该轮完整消息数组。 */\n  onModelResponse(callback: ModelResponseCallback<P>): Unsubscribe {\n    return addListener(this.#modelResponseListeners, callback);\n  }\n\n  /** 监听指定工具的调用前阶段；可通过 options 等待回调或在异常时取消调用。 */\n  onBeforeToolCall(\n    toolName: string,\n    callback: BeforeToolCallCallback<P>,\n    options?: ToolEventOptions,\n  ): Unsubscribe {\n    return addListener(this.#beforeToolListeners, {\n      toolName,\n      callback,\n      options: normalizeToolEventOptions(options),\n    });\n  }\n\n  /** 监听指定工具处理器返回后的阶段；回调异常会上报，但不会中断主流程。 */\n  onAfterToolCall(\n    toolName: string,\n    callback: AfterToolCallCallback<P>,\n    options?: ToolEventOptions,\n  ): Unsubscribe {\n    return addListener(this.#afterToolListeners, {\n      toolName,\n      callback,\n      options: normalizeToolEventOptions(options),\n    });\n  }\n\n  /** 监听工具在 `before`、`calling` 或 `after` 阶段发生的异常。 */\n  onToolCallError(callback: ToolCallErrorCallback<P>): Unsubscribe {\n    return addListener(this.#toolCallErrorListeners, callback);\n  }\n\n  /** 监听 Agent 进入指定状态的事件。 */\n  onAgentStatusChanged(status: AgentStatus, callback: AgentStatusChangedCallback<P>): Unsubscribe {\n    return addListener(this.#statusListeners, {\n      status,\n      callback,\n    });\n  }\n\n  /** 监听 `agent()` 抛出的错误；listener 自身异常不会影响 Agent 状态。 */\n  onAgentError(callback: AgentErrorCallback): Unsubscribe {\n    return addListener(this.#agentErrorListeners, callback);\n  }\n\n  @Tool({\n    name: 'get-skill',\n    description: '获取指定下标的技能手册完整内容。',\n    parameters: z.object({\n      index: z.number().int().nonnegative(),\n    }),\n  })\n  #getSkill(parameters: unknown): string {\n    // 技能列表通过 system prompt 暴露索引，工具只负责按索引返回完整手册。\n    const { index } = parameters as { index: number };\n    const skill = this.#skills[index];\n\n    if (!skill) {\n      return `没有找到下标为 ${index} 的技能手册。`;\n    }\n\n    const parts = [\n      `手册标题：${skill.name}`,\n      `手册描述：${skill.description}`,\n      skill.systemContent ? `全局适用内容：${skill.systemContent}` : '',\n      ...(skill.sops ?? []).map((sop, sopIndex) =>\n        [`工作流${sopIndex + 1}：${sop.description}`, `执行流程：\\n${sop.content}`].join('\\n'),\n      ),\n    ].filter((part) => part.length > 0);\n\n    return parts.join('\\n\\n');\n  }\n\n  @Tool({\n    name: 'end-agent',\n    description:\n      '当你认为你已经彻底完成了用户交代的任务，并且不需要更多信息时，请调用这个工具。该工具必须在任务确定结束时单独调用，不能跟其他工具一起调用。',\n  })\n  #endAgent(): string {\n    // Agent 的结束条件集中在该内置工具中，避免自然语言回答误判为完成。\n    this.#changeStatus('ended');\n    return 'Agent 已结束。';\n  }\n\n  /**\n   * 执行一个已解析的模型函数调用，并返回本地结果 item。\n   *\n   * 成功结果会先由 Model 构建并写入上下文，再触发 after listener，使 listener\n   * 追加的消息排在对应工具结果之后。\n   */\n  async toolCall(callInfo: AgentToolCall<P>): Promise<ContextOf<P>> {\n    this.#assertInitialized();\n\n    const tool = this.tools.find((candidate) => candidate.name === callInfo.name);\n    const fallbackParameters: unknown = {};\n\n    if (!tool) {\n      const error = new Error(`Unknown tool: ${callInfo.name}`);\n      await this.#emitToolCallError(callInfo.name, 'calling', error, fallbackParameters, callInfo);\n      return this.#appendToolMessage(\n        this.#createToolMessage(callInfo.id, normalizeErrorMessage(error)),\n      );\n    }\n\n    const parsedArguments = await this.#parseToolArguments(tool, callInfo);\n\n    if (!parsedArguments.ok) {\n      return this.#appendToolMessage(this.#createToolMessage(callInfo.id, parsedArguments.message));\n    }\n\n    const parameters = parsedArguments.parameters;\n    const beforeResult = await this.#runBeforeToolListeners(tool.name, parameters, callInfo);\n\n    if (beforeResult.canceled) {\n      return this.#appendToolMessage(\n        this.#createToolMessage(\n          callInfo.id,\n          `${beforeToolErrorPrefix}${normalizeErrorMessage(beforeResult.error)}`,\n        ),\n      );\n    }\n\n    let result: unknown;\n\n    try {\n      result = await tool.handler(parameters);\n    } catch (error) {\n      await this.#emitToolCallError(tool.name, 'calling', error, parameters, callInfo);\n      return this.#appendToolMessage(\n        this.#createToolMessage(callInfo.id, normalizeErrorMessage(error)),\n      );\n    }\n\n    const resultMessage = this.#appendToolMessage(\n      this.#createToolMessage(callInfo.id, serializeToolResult(result)),\n    );\n\n    await this.#runAfterToolListeners(tool.name, parameters, callInfo, result);\n\n    return resultMessage;\n  }\n\n  /**\n   * 启动 Agent 任务循环。\n   *\n   * 每轮先原样保存模型返回的协议消息，再执行 Model 反解析出的工具调用。\n   * 只有内置 `end-agent` 工具把状态改为 `ended` 后任务才结束；当前版本\n   * 尚不支持流式调用。\n   */\n  async agent(input: string | UserMessageOf<P>, stream = false): Promise<ContextOf<P>[]> {\n    let shouldFailOnError = true;\n\n    try {\n      this.#assertInitialized();\n\n      if (this.#status === 'running') {\n        shouldFailOnError = false;\n        throw new Error('Agent is already running.');\n      }\n\n      if (stream) {\n        throw new Error('Agent streaming is not supported in this version.');\n      }\n\n      this.#appendMessage(\n        this.#llm.buildUserMessage(\n          typeof input === 'string'\n            ? {\n                content: [{ type: 'text', text: input }],\n              }\n            : input,\n        ),\n      );\n\n      this.#changeStatus('running');\n\n      for (\n        let iteration = 0;\n        this.#maxIterations === undefined || iteration < this.#maxIterations;\n        iteration += 1\n      ) {\n        const response = await this.#generateWithEmptyMessagesRetry();\n\n        await this.#emitModelResponse(response.messages);\n\n        // 模型消息可能带有提供方元数据，必须整批原样保存后再执行本地工具。\n        for (const message of response.messages) {\n          this.#appendMessage(message);\n        }\n\n        for (const call of this.#llm.parseToolCalls(response.messages)) {\n          await this.toolCall(call);\n        }\n\n        if (this.#status === 'ended') {\n          return [...this.#context];\n        }\n      }\n\n      throw new Error(`Agent exceeded maxIterations: ${this.#maxIterations}.`);\n    } catch (error) {\n      const agentError = toError(error);\n\n      if (shouldFailOnError && this.#status !== 'ended') {\n        this.#changeStatus('failed');\n      }\n\n      this.#emitAgentError(agentError);\n\n      throw error instanceof Error ? error : agentError;\n    }\n  }\n\n  #assertUniqueToolNames(): void {\n    // 显式 init 阶段统一做配置校验，运行时不在每轮请求重复扫描。\n    this.tools ??= [];\n    const seen = new Set<string>();\n\n    for (const tool of this.tools) {\n      if (seen.has(tool.name)) {\n        throw new Error(`Duplicate tool name: ${tool.name}`);\n      }\n\n      seen.add(tool.name);\n    }\n  }\n\n  #assertUniqueSubAgentNames(): void {\n    // 子代理通过 static name 被模型选择，因此同一父代理内必须唯一。\n    const seen = new Set<string>();\n\n    for (const agent of this.subAgents) {\n      if (seen.has(agent.name)) {\n        throw new Error(`Duplicate sub-agent name: ${agent.name}`);\n      }\n\n      seen.add(agent.name);\n    }\n  }\n\n  #assertInitialized(): void {\n    // 直接调用 toolCall() 也需要初始化，因为运行时工具可能由外部数组追加。\n    if (!this.#initialized) {\n      throw new Error('Agent has not been initialized. Call init() before agent().');\n    }\n  }\n\n  #buildContextForModel(): ContextOf<P>[] {\n    // 框架协议提示词仅在请求模型时临时前置，不写入 context/history。\n    const systemMessages = [\n      internalEndAgentPrompt,\n      this.#buildSkillPrompt(),\n      ...this.#systemPrompts,\n    ].map((content) => this.#llm.buildSystemMessage({ content }));\n\n    return [...systemMessages, ...this.#context];\n  }\n\n  #buildSkillPrompt(): string {\n    // 技能选择指引放在 system prompt 中，让 `get-skill` 的工具描述保持精简。\n    const skillList =\n      this.#skills.length === 0\n        ? '当前没有可查询的技能手册，不要调用 get-skill。'\n        : this.#skills\n            .map(\n              (skill, index) =>\n                `技能手册${index}：\\n名称：${skill.name}\\n描述：${skill.description}`,\n            )\n            .join('\\n\\n');\n\n    return [\n      '框架技能约束：当正在执行的任务匹配到如下技能手册描述时，必须先调用 get-skill 工具获取对应下标的完整手册内容，然后检查手册内是否有具体工作流；如果匹配到具体工作流，必须按照该工作流执行。',\n      skillList,\n    ].join('\\n\\n');\n  }\n\n  #buildToolsForModel(): ToolOf<P>[] {\n    return this.tools.map((tool) => {\n      // 动态 description 只能看到协议无关上下文，避免装饰器 API 绑定具体 Model。\n      const toolContext: {\n        name: string;\n        parameters?: NonNullable<ToolRuntimeDefinition['parameters']>;\n        strict?: boolean;\n      } = {\n        name: tool.name,\n      };\n\n      if (tool.parameters) {\n        toolContext.parameters = tool.parameters;\n      }\n\n      if (tool.strict !== undefined) {\n        toolContext.strict = tool.strict;\n      }\n\n      const description =\n        typeof tool.description === 'function'\n          ? tool.description({\n              skills: [...this.#skills],\n              subAgents: [\n                ...this.subAgents,\n              ] as unknown as readonly AgentConstructor<AgentProtocol>[],\n              context: [...this.#context],\n              history: [...this.#rawContext],\n              systemPrompts: [...this.#systemPrompts],\n              tool: toolContext,\n            })\n          : tool.description;\n\n      return this.#llm.buildToolMessage({\n        name: tool.name,\n        description,\n        parameters: tool.parameters ?? getDefaultToolParametersSchema(),\n        ...(tool.strict === undefined ? {} : { strict: tool.strict }),\n      });\n    });\n  }\n\n  async #generateWithEmptyMessagesRetry() {\n    // 只重试“成功响应但没有消息”的情况；网络/API 异常由外层 catch 统一处理。\n    let lastResponseText = 'Model returned no messages.';\n\n    for (let attempt = 0; attempt <= 3; attempt += 1) {\n      const response = await this.#llm.generate({\n        context: this.#buildContextForModel(),\n        tools: this.#buildToolsForModel(),\n      });\n\n      if (response.messages.length > 0) {\n        return response;\n      }\n\n      lastResponseText = `Model returned no messages after ${attempt + 1} attempt(s).`;\n    }\n\n    throw new Error(lastResponseText);\n  }\n\n  async #parseToolArguments(\n    tool: ToolRuntimeDefinition,\n    callInfo: AgentToolCall<P>,\n  ): Promise<\n    | {\n        ok: true;\n        parameters: unknown;\n      }\n    | {\n        ok: false;\n        message: string;\n      }\n  > {\n    let rawParameters: unknown;\n\n    // 模型输出必须是 JSON 字符串；解析失败时把错误作为工具结果交回模型处理。\n    try {\n      rawParameters = callInfo.arguments.trim().length > 0 ? JSON.parse(callInfo.arguments) : {};\n    } catch (error) {\n      await this.#emitToolCallError(tool.name, 'calling', error, {}, callInfo);\n      return {\n        ok: false,\n        message: normalizeErrorMessage(error),\n      };\n    }\n\n    const schema = tool.parameters ?? getDefaultToolParametersSchema();\n    const parsed = schema.safeParse(rawParameters);\n\n    // Zod 校验失败同样不终止 Agent，而是写入工具结果让模型自行修正参数。\n    if (!parsed.success) {\n      await this.#emitToolCallError(tool.name, 'calling', parsed.error, rawParameters, callInfo);\n      return {\n        ok: false,\n        message: normalizeErrorMessage(parsed.error),\n      };\n    }\n\n    return {\n      ok: true,\n      parameters: parsed.data,\n    };\n  }\n\n  async #runBeforeToolListeners(\n    toolName: string,\n    parameters: unknown,\n    message: AgentToolCall<P>,\n  ): Promise<\n    | {\n        canceled: true;\n        error: unknown;\n      }\n    | {\n        canceled: false;\n      }\n  > {\n    for (const listener of this.#beforeToolListeners.filter((item) => item.toolName === toolName)) {\n      try {\n        const result = listener.callback(parameters, message);\n\n        if (listener.options.await) {\n          await result;\n        } else {\n          void Promise.resolve(result).catch((error: unknown) => {\n            void this.#emitToolCallError(toolName, 'before', error, parameters, message);\n          });\n        }\n      } catch (error) {\n        await this.#emitToolCallError(toolName, 'before', error, parameters, message);\n\n        // 只有 before listener 可以通过异常取消真实工具调用。\n        if (listener.options.errorCancel) {\n          return {\n            canceled: true,\n            error,\n          };\n        }\n      }\n    }\n\n    return {\n      canceled: false,\n    };\n  }\n\n  async #runAfterToolListeners(\n    toolName: string,\n    parameters: unknown,\n    message: AgentToolCall<P>,\n    result: unknown,\n  ): Promise<void> {\n    for (const listener of this.#afterToolListeners.filter((item) => item.toolName === toolName)) {\n      try {\n        const callbackResult = listener.callback(parameters, message, result);\n\n        if (listener.options.await) {\n          await callbackResult;\n        } else {\n          void Promise.resolve(callbackResult).catch((error: unknown) => {\n            void this.#emitToolCallError(toolName, 'after', error, parameters, message, result);\n          });\n        }\n      } catch (error) {\n        // after listener 的失败可以被观察，但不能中断 Agent 主循环。\n        await this.#emitToolCallError(toolName, 'after', error, parameters, message, result);\n      }\n    }\n  }\n\n  async #emitModelResponse(messages: readonly ContextOf<P>[]): Promise<void> {\n    for (const listener of this.#modelResponseListeners) {\n      try {\n        await listener(messages);\n      } catch {\n        // 模型响应 listener 仅用于观察，不应打断 Agent 主循环。\n      }\n    }\n  }\n\n  async #emitToolCallError(\n    name: string,\n    triggerType: 'before' | 'calling' | 'after',\n    error: unknown,\n    parameters: unknown,\n    message: AgentToolCall<P>,\n    result?: unknown,\n  ): Promise<void> {\n    for (const listener of this.#toolCallErrorListeners) {\n      try {\n        await listener(name, triggerType, error, parameters, message, result);\n      } catch {\n        // 工具错误 listener 仅用于观察，不应产生新的工具错误。\n      }\n    }\n  }\n\n  #emitAgentError(error: Error): void {\n    for (const listener of this.#agentErrorListeners) {\n      try {\n        const result = listener(error);\n\n        void Promise.resolve(result).catch((listenerError: unknown) => {\n          void listenerError;\n          // 错误 listener 属于非阻塞观察者；暂不向控制台重复输出其异常。\n        });\n      } catch (listenerError) {\n        void listenerError;\n        // Agent 错误 listener 仅用于观察，不应制造新的 Agent 错误。\n      }\n    }\n  }\n\n  #appendMessage(message: ContextOf<P>): void {\n    this.#rawContext.push(message);\n    this.#context.push(message);\n  }\n\n  #appendToolMessage(message: ContextOf<P>): ContextOf<P> {\n    this.#appendMessage(message);\n    return message;\n  }\n\n  #createToolMessage(callId: string, output: string): ContextOf<P> {\n    return this.#llm.buildToolCallOutputMessage({\n      callId,\n      output,\n    });\n  }\n\n  #changeStatus(status: AgentStatus): void {\n    if (this.#status === status) {\n      return;\n    }\n\n    this.#status = status;\n\n    for (const listener of this.#statusListeners.filter((item) => item.status === status)) {\n      void Promise.resolve(listener.callback([...this.#rawContext], [...this.#context])).catch(\n        () => {\n          // 状态 listener 仅用于观察，不应打断状态迁移。\n        },\n      );\n    }\n  }\n}\n\nfunction addListener<TListener>(listeners: TListener[], listener: TListener): Unsubscribe {\n  // 所有事件注册都返回轻量 unsubscribe，避免调用方持有内部数组引用。\n  listeners.push(listener);\n\n  return () => {\n    const index = listeners.indexOf(listener);\n\n    if (index >= 0) {\n      listeners.splice(index, 1);\n    }\n  };\n}\n\nfunction normalizeToolEventOptions(options?: ToolEventOptions): Required<ToolEventOptions> {\n  // 默认 observer 不阻塞主流程，也不会因 before 异常取消真实工具调用。\n  return {\n    await: options?.await ?? false,\n    errorCancel: options?.errorCancel ?? false,\n  };\n}\n\nfunction serializeToolResult(result: unknown): string {\n  // 工具 handler 可以返回对象；Agent 统一序列化为协议工具结果可传输的字符串。\n  if (typeof result === 'string') {\n    return result;\n  }\n\n  if (result === undefined) {\n    return '';\n  }\n\n  try {\n    return JSON.stringify(result);\n  } catch {\n    return String(result);\n  }\n}\n\nfunction normalizeErrorMessage(error: unknown): string {\n  // 写入模型上下文的错误需要保持短文本，避免暴露多余堆栈。\n  if (error instanceof Error) {\n    return error.message;\n  }\n\n  return serializeToolResult(error);\n}\n\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n\nfunction getToolsStorage(agent: object): ToolRuntimeDefinition[] {\n  // 若装饰器 initializer 尚未写入 symbol slot，则按需创建实例工具数组。\n  const carrier = agent as ToolsStorageCarrier;\n\n  carrier[toolsStorageKey] ??= [];\n\n  return carrier[toolsStorageKey];\n}\n\nfunction setToolsStorage(agent: object, tools: ToolRuntimeDefinition[]): void {\n  // 使用 symbol slot 避免用户声明同名 public 字段时覆盖装饰器注册结果。\n  const carrier = agent as ToolsStorageCarrier;\n\n  carrier[toolsStorageKey] = tools;\n}\n\nfunction formatSubAgentDescription(agent: AgentConstructor<AgentProtocol>, index: number): string {\n  // 子代理描述只使用 static metadata，不需要实例化子代理读取工具定义。\n  const toolList =\n    agent.toolsDefinition.length === 0\n      ? '    当前子代理没有声明工具能力。'\n      : agent.toolsDefinition.map(formatStaticToolDescription).join('\\n');\n\n  return [\n    `子代理${index + 1}：`,\n    `  名称：${agent.name || '未命名代理'}`,\n    `  描述：${agent.description ?? '未提供描述。'}`,\n    '  工具能力：',\n    toolList,\n  ].join('\\n');\n}\n\nfunction formatStaticToolDescription(tool: ToolDefinition, index: number): string {\n  // 动态工具描述依赖运行时上下文，静态 toolsDefinition 中只能提示其为运行时生成。\n  return [\n    `    - 工具${index + 1}：${tool.name}`,\n    `      描述：${typeof tool.description === 'function' ? '动态描述，运行时生成。' : tool.description}`,\n  ].join('\\n');\n}\n\nexport { Tool };\nexport type * from './types';\n","import type {\n  AgentBaseSystemMessage,\n  AgentBaseToolCallOutputMessage,\n  AgentBaseUserMessage,\n  AgentParsedMessage,\n  AgentProtocol,\n  AgentToolCall,\n  AgentToolDefinitionInput,\n  AssistantMessageOf,\n  ContextOf,\n  SystemMessageOf,\n  ToolCallOutputMessageOf,\n  ToolOf,\n  UserMessageOf,\n} from '../../agent/types';\nimport type { ModelGenerateRequest, ModelGenerateResult } from './types';\n\nexport type { ModelGenerateRequest, ModelGenerateResult } from './types';\n\n/**\n * Agent 使用的协议适配器抽象基类。\n *\n * builder 将 Agent 基础结构转换为协议消息，parser 从混合上下文中筛选并反解析目标消息，\n * `generate()` 负责实际模型请求。\n */\nexport abstract class Model<P extends AgentProtocol> {\n  /**\n   * 执行一轮非流式模型调用。\n   *\n   * `context` 和 `tools` 已经由 Agent 通过本 Model 的 builder 转成目标协议结构；\n   * 返回的 `messages` 会被 Agent 原样写入上下文，并继续交给 parser 提取工具调用。\n   */\n  abstract generate(request: ModelGenerateRequest<P>): Promise<ModelGenerateResult<P>>;\n\n  /**\n   * 将 Agent 的基础用户消息或协议专属用户消息构建为可持久保存的上下文项。\n   *\n   * 字符串任务会先被 Agent 包装为 `{ type: \"text\" }` 内容块，再进入本方法。\n   */\n  abstract buildUserMessage(input: AgentBaseUserMessage | UserMessageOf<P>): ContextOf<P>;\n\n  /**\n   * 将框架内部提示词或调用方 system prompt 构建为协议 system 上下文项。\n   *\n   * Agent 每轮请求都会临时构建这些消息，但不会把它们写入持久 context/history。\n   */\n  abstract buildSystemMessage(input: AgentBaseSystemMessage | SystemMessageOf<P>): ContextOf<P>;\n\n  /**\n   * 将本地工具执行结果构建为协议工具结果消息。\n   *\n   * Agent 只提供通用的 `callId + output` 语义；具体 wire 字段由协议适配器决定。\n   */\n  abstract buildToolCallOutputMessage(\n    input: AgentBaseToolCallOutputMessage | ToolCallOutputMessageOf<P>,\n  ): ContextOf<P>;\n\n  /**\n   * 将框架工具定义构建为模型 API 接收的工具声明。\n   *\n   * `strict` 仅在工具显式设置时出现；schema 的 OpenAI-compatible 转换也应在 Model 层完成。\n   */\n  abstract buildToolMessage(input: AgentToolDefinitionInput): ToolOf<P>;\n\n  /**\n   * 从混合上下文中筛选用户消息并反解析为协议用户消息结构。\n   *\n   * 不匹配的上下文项必须被跳过，解析结果需要保留原始 `sourceMessage`。\n   */\n  abstract parseUserMessages(\n    context: readonly ContextOf<P>[],\n  ): readonly AgentParsedMessage<UserMessageOf<P>, ContextOf<P>>[];\n\n  /**\n   * 从混合上下文中筛选 system 消息并反解析。\n   *\n   * 主要供应用调试、恢复历史和自定义模型适配器测试使用。\n   */\n  abstract parseSystemMessages(\n    context: readonly ContextOf<P>[],\n  ): readonly AgentParsedMessage<SystemMessageOf<P>, ContextOf<P>>[];\n\n  /**\n   * 从混合上下文中筛选 assistant 文本/拒绝等普通输出。\n   *\n   * provider 专属推理项可以保留在原始 context 中，不必强行映射到 assistant 消息。\n   */\n  abstract parseAssistantMessages(\n    context: readonly ContextOf<P>[],\n  ): readonly AgentParsedMessage<AssistantMessageOf<P>, ContextOf<P>>[];\n\n  /**\n   * 从一批模型返回消息中按协议顺序提取本地可执行的工具调用。\n   *\n   * Chat 协议中一条 assistant message 可能展开多个调用；Responses 通常一条 item\n   * 对应一个调用。返回项需要携带原始 `sourceCall`。\n   */\n  abstract parseToolCalls(context: readonly ContextOf<P>[]): readonly AgentToolCall<P>[];\n\n  /**\n   * 从混合上下文中筛选工具结果消息并反解析。\n   *\n   * 该方法不参与 Agent 主循环，但用于外部审计、测试和恢复上下文。\n   */\n  abstract parseToolCallOutputMessages(\n    context: readonly ContextOf<P>[],\n  ): readonly AgentParsedMessage<ToolCallOutputMessageOf<P>, ContextOf<P>>[];\n}\n","import { z } from 'zod';\nimport { zodToJsonSchema } from 'zod-to-json-schema';\n\nimport type { JsonObject, ToolParametersSchema } from '../agent/types';\n\n/** 将框架工具 schema 转换为 OpenAI-compatible function tool 参数定义。 */\nexport function toOpenAIToolParameters(schema: ToolParametersSchema): JsonObject {\n  const converted = normalizeRootSchema(convertWithZodToJsonSchema(schema));\n\n  if (converted) {\n    return converted;\n  }\n\n  const native = normalizeRootSchema(convertWithNativeZod(schema));\n\n  if (native) {\n    return native;\n  }\n\n  throw new Error('Tool parameters must resolve to a JSON object schema.');\n}\n\nfunction convertWithZodToJsonSchema(schema: ToolParametersSchema): unknown {\n  // zod-to-json-schema 对 Zod v3/v4 兼容路径更成熟，优先尝试 OpenAI target。\n  try {\n    return zodToJsonSchema(schema as never, {\n      target: 'openAi',\n    });\n  } catch {\n    return null;\n  }\n}\n\nfunction convertWithNativeZod(schema: ToolParametersSchema): unknown {\n  // 若 zod-to-json-schema 无法处理当前 schema，再回退到 Zod 自带 JSON Schema 输出。\n  try {\n    return z.toJSONSchema(schema as never);\n  } catch {\n    return null;\n  }\n}\n\nfunction normalizeRootSchema(schema: unknown): JsonObject | null {\n  // OpenAI tool parameters 必须是 object；所有 ref/$schema 清理都限制在 wire 层。\n  if (!isJsonObject(schema)) {\n    return null;\n  }\n\n  const root = stripSchemaKeyword(schema);\n  const resolved = resolveLocalRootRef(root);\n  const normalized = stripSchemaKeyword(resolved);\n\n  // OpenAI function tool 的参数必须以 object 为根；此处隔离 wire 层限制。\n  if (normalized.type !== 'object') {\n    return null;\n  }\n\n  return normalized;\n}\n\nfunction resolveLocalRootRef(schema: JsonObject): JsonObject {\n  // zod-to-json-schema 可能把根对象写成本地 $ref，这里只解析根级本地引用。\n  const ref = schema.$ref;\n\n  if (typeof ref !== 'string' || !ref.startsWith('#/')) {\n    return schema;\n  }\n\n  const resolved = findLocalRef(schema, ref);\n\n  if (!resolved) {\n    return schema;\n  }\n\n  const next: JsonObject = {\n    ...resolved,\n  };\n\n  if (isJsonObject(schema.definitions) && !('definitions' in next)) {\n    next.definitions = schema.definitions;\n  }\n\n  if (isJsonObject(schema.$defs) && !('$defs' in next)) {\n    next.$defs = schema.$defs;\n  }\n\n  return next;\n}\n\nfunction findLocalRef(schema: JsonObject, ref: string): JsonObject | null {\n  // JSON Pointer 中的 ~1 和 ~0 需要按规范反转义。\n  const path = ref\n    .slice(2)\n    .split('/')\n    .map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~'));\n\n  let current: unknown = schema;\n\n  for (const part of path) {\n    if (!isJsonObject(current)) {\n      return null;\n    }\n\n    current = current[part];\n  }\n\n  return isJsonObject(current) ? current : null;\n}\n\nfunction stripSchemaKeyword(schema: JsonObject): JsonObject {\n  // OpenAI tool schema 不需要顶层 $schema，保留会增加 provider 兼容风险。\n  const next: JsonObject = {\n    ...schema,\n  };\n\n  delete next.$schema;\n\n  return next;\n}\n\nfunction isJsonObject(value: unknown): value is JsonObject {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n","import OpenAI from 'openai';\nimport type {\n  ChatCompletionCreateParamsNonStreaming,\n  ChatCompletionMessageParam,\n  ChatCompletionTool,\n} from 'openai/resources/chat/completions/completions';\n\nimport { getDefaultToolParametersSchema } from '../../agent/schema';\nimport type {\n  AgentBaseSystemMessage,\n  AgentBaseToolCallOutputMessage,\n  AgentBaseUserMessage,\n  AgentParsedMessage,\n  AgentTextPart,\n  AgentToolCall,\n  AgentToolDefinitionInput,\n} from '../../agent/types';\nimport { Model, type ModelGenerateRequest, type ModelGenerateResult } from '../base';\nimport { toOpenAIToolParameters } from '../openai-schema';\nimport type {\n  OpenAIChatAssistantContextMessage,\n  OpenAIChatAssistantMessage,\n  OpenAIChatContext,\n  OpenAIChatModelOptions,\n  OpenAIChatProtocol,\n  OpenAIChatSystemMessage,\n  OpenAIChatTextPart,\n  OpenAIChatTool,\n  OpenAIChatToolCallOutputMessage,\n  OpenAIChatUserContentPart,\n  OpenAIChatUserContextMessage,\n  OpenAIChatUserMessage,\n} from './types';\n\nexport type * from './types';\n\n/**\n * OpenAI-compatible Chat Completions 模型适配器。\n *\n * 该类把 Agent 的协议无关消息转换为 Chat `messages` / `tools`，并从\n * assistant `tool_calls[]` 中反解析本地工具调用。它只支持新版 tool calling\n * 闭环，不再暴露 deprecated `function_call` / `function` role。\n */\nexport class OpenAIChatModel extends Model<OpenAIChatProtocol> {\n  #openai: OpenAI;\n  #model: string;\n  #defaultParams: OpenAIChatModelOptions['defaultParams'];\n\n  /**\n   * 创建 Chat Completions 适配器。\n   *\n   * 可以直接传入 OpenAI SDK `ClientOptions`，也可以通过 `client` 注入已配置好的\n   * SDK 实例；`defaultParams` 会透传到每次非流式 Chat 请求。\n   */\n  constructor(options: OpenAIChatModelOptions) {\n    super();\n\n    const { client, model, defaultParams, ...clientOptions } = options;\n\n    this.#model = model;\n    this.#defaultParams = defaultParams;\n    this.#openai = client ?? new OpenAI(clientOptions);\n  }\n\n  /**\n   * 调用 Chat Completions，并将首个 choice 的 assistant message 原样返回给 Agent。\n   *\n   * 如果服务端成功响应但没有 choice，返回空数组，由 Agent 负责空响应重试。\n   */\n  async generate(\n    request: ModelGenerateRequest<OpenAIChatProtocol>,\n  ): Promise<ModelGenerateResult<OpenAIChatProtocol>> {\n    const params: ChatCompletionCreateParamsNonStreaming = {\n      ...this.#defaultParams,\n      model: this.#model,\n      messages: request.context as unknown as ChatCompletionMessageParam[],\n    };\n\n    if (request.tools.length > 0) {\n      params.tools = request.tools as unknown as ChatCompletionTool[];\n    }\n\n    const response = await this.#openai.chat.completions.create(params);\n    const message = response.choices[0]?.message;\n\n    return {\n      messages: message ? [message as unknown as OpenAIChatContext] : [],\n      raw: response,\n    };\n  }\n\n  /**\n   * 构建 Chat user message。\n   *\n   * Agent 基础文本 part 会转换为 Chat `text` part；协议专属的 `image_url`、\n   * `input_audio`、`file` part 会被原样保留。\n   */\n  buildUserMessage(input: AgentBaseUserMessage | OpenAIChatUserMessage): OpenAIChatContext {\n    return {\n      role: 'user',\n      content: input.content.map((part) =>\n        part.type === 'text'\n          ? {\n              type: 'text',\n              text: part.text,\n            }\n          : part,\n      ),\n      ...('name' in input && input.name ? { name: input.name } : {}),\n    };\n  }\n\n  /** 构建 Chat system message，保留可选 `name` 字段。 */\n  buildSystemMessage(input: AgentBaseSystemMessage | OpenAIChatSystemMessage): OpenAIChatContext {\n    return {\n      role: 'system',\n      content: input.content,\n      ...('name' in input && input.name ? { name: input.name } : {}),\n    };\n  }\n\n  /** 构建 Chat `tool` role 消息，用于把本地工具结果回传给对应 `tool_call_id`。 */\n  buildToolCallOutputMessage(\n    input: AgentBaseToolCallOutputMessage | OpenAIChatToolCallOutputMessage,\n  ): OpenAIChatContext {\n    return {\n      role: 'tool',\n      tool_call_id: input.callId,\n      content: input.output,\n    };\n  }\n\n  /**\n   * 构建 Chat function tool 声明。\n   *\n   * 参数 schema 在此处转换为 OpenAI-compatible JSON Schema；`strict` 只在调用方\n   * 显式设置时透传。\n   */\n  buildToolMessage(input: AgentToolDefinitionInput): OpenAIChatTool {\n    return {\n      type: 'function',\n      function: {\n        name: input.name,\n        description: input.description,\n        parameters: toOpenAIToolParameters(input.parameters ?? getDefaultToolParametersSchema()),\n        ...(input.strict === undefined ? {} : { strict: input.strict }),\n      },\n    };\n  }\n\n  /** 从混合 Chat context 中筛选 user 消息，并把字符串内容归一为 `text` part。 */\n  parseUserMessages(\n    context: readonly OpenAIChatContext[],\n  ): readonly AgentParsedMessage<OpenAIChatUserMessage, OpenAIChatContext>[] {\n    return context.flatMap((message) =>\n      message.role === 'user'\n        ? [\n            {\n              message: {\n                content: parseUserContent(message.content),\n                ...(message.name ? { name: message.name } : {}),\n              },\n              sourceMessage: message,\n            },\n          ]\n        : [],\n    );\n  }\n\n  /** 从混合 Chat context 中筛选 system 消息，并读取其中的文本内容。 */\n  parseSystemMessages(\n    context: readonly OpenAIChatContext[],\n  ): readonly AgentParsedMessage<OpenAIChatSystemMessage, OpenAIChatContext>[] {\n    return context.flatMap((message) =>\n      message.role === 'system'\n        ? [\n            {\n              message: {\n                content: readTextContent(message.content),\n                ...(message.name ? { name: message.name } : {}),\n              },\n              sourceMessage: message,\n            },\n          ]\n        : [],\n    );\n  }\n\n  /**\n   * 从 Chat assistant 消息中解析文本输出和 refusal 内容。\n   *\n   * 该方法不解析工具调用；工具调用由 `parseToolCalls()` 单独按顺序展开。\n   */\n  parseAssistantMessages(\n    context: readonly OpenAIChatContext[],\n  ): readonly AgentParsedMessage<OpenAIChatAssistantMessage, OpenAIChatContext>[] {\n    return context.flatMap((message) => {\n      if (message.role !== 'assistant') {\n        return [];\n      }\n\n      const parsed = parseAssistantContent(message.content);\n\n      return [\n        {\n          message: {\n            content: parsed.content,\n            ...(parsed.refusals.length > 0 ? { refusals: parsed.refusals } : {}),\n            ...(message.refusal !== undefined ? { refusal: message.refusal } : {}),\n          },\n          sourceMessage: message,\n        },\n      ];\n    });\n  }\n\n  /**\n   * 从 assistant `tool_calls[]` 中提取本地 function tool 调用。\n   *\n   * Chat custom tool call 会被保留在原始消息里，但不会映射为本地 `@Tool` 调用。\n   */\n  parseToolCalls(\n    context: readonly OpenAIChatContext[],\n  ): readonly AgentToolCall<OpenAIChatProtocol>[] {\n    return context.flatMap((message) =>\n      message.role === 'assistant'\n        ? (message.tool_calls ?? []).flatMap((call) =>\n            call.type === 'function'\n              ? [\n                  {\n                    id: call.id,\n                    name: call.function.name,\n                    arguments: call.function.arguments,\n                    sourceMessage: message,\n                    sourceCall: call,\n                  },\n                ]\n              : [],\n          )\n        : [],\n    );\n  }\n\n  /** 从 Chat `tool` role message 中解析工具结果。 */\n  parseToolCallOutputMessages(\n    context: readonly OpenAIChatContext[],\n  ): readonly AgentParsedMessage<OpenAIChatToolCallOutputMessage, OpenAIChatContext>[] {\n    return context.flatMap((message) =>\n      message.role === 'tool'\n        ? [\n            {\n              message: {\n                callId: message.tool_call_id,\n                output: readTextContent(message.content),\n              },\n              sourceMessage: message,\n            },\n          ]\n        : [],\n    );\n  }\n}\n\nfunction parseUserContent(\n  content: OpenAIChatUserContextMessage['content'],\n): OpenAIChatUserContentPart[] {\n  // SDK 允许 user content 是字符串；框架解析结果统一暴露为内容块数组。\n  if (typeof content === 'string') {\n    return [{ type: 'text', text: content }];\n  }\n\n  return content.map((part) => (part.type === 'text' ? { type: 'text', text: part.text } : part));\n}\n\nfunction readTextContent(content: string | readonly OpenAIChatTextPart[]): string {\n  return typeof content === 'string' ? content : content.map((part) => part.text).join('');\n}\n\nfunction parseAssistantContent(content: OpenAIChatAssistantContextMessage['content']): {\n  content: AgentTextPart[];\n  refusals: string[];\n} {\n  // assistant content 可能为空，尤其是仅返回 tool_calls 的场景。\n  if (typeof content === 'string') {\n    return { content: [{ type: 'text', text: content }], refusals: [] };\n  }\n\n  if (!content) {\n    return { content: [], refusals: [] };\n  }\n\n  return {\n    content: content.flatMap((part) =>\n      part.type === 'text' ? [{ type: 'text' as const, text: part.text }] : [],\n    ),\n    refusals: content.flatMap((part) => (part.type === 'refusal' ? [part.refusal] : [])),\n  };\n}\n","import { createReadStream } from 'node:fs';\n\nimport OpenAI from 'openai';\nimport type { FileCreateParams } from 'openai/resources/files';\nimport type {\n  ResponseCreateParamsNonStreaming,\n  ResponseInput,\n  Tool as ResponseTool,\n} from 'openai/resources/responses/responses';\n\nimport { getDefaultToolParametersSchema } from '../../agent/schema';\nimport type {\n  AgentBaseSystemMessage,\n  AgentBaseToolCallOutputMessage,\n  AgentBaseUserMessage,\n  AgentParsedMessage,\n  AgentTextPart,\n  AgentToolCall,\n  AgentToolDefinitionInput,\n} from '../../agent/types';\nimport { Model, type ModelGenerateRequest, type ModelGenerateResult } from '../base';\nimport { toOpenAIToolParameters } from '../openai-schema';\nimport type {\n  OpenAIFileObject,\n  OpenAIFileUploadOptions,\n  OpenAIResponsesAssistantMessage,\n  OpenAIResponsesContext,\n  OpenAIResponsesFunctionCallOutput,\n  OpenAIResponsesInputMessage,\n  OpenAIResponsesModelOptions,\n  OpenAIResponsesProtocol,\n  OpenAIResponsesSystemMessage,\n  OpenAIResponsesTool,\n  OpenAIResponsesToolCallOutputMessage,\n  OpenAIResponsesUserExtensionPart,\n  OpenAIResponsesUserMessage,\n} from './types';\n\nexport type * from './types';\n\n/**\n * OpenAI-compatible Responses 模型适配器，提供标准 Files 上传能力。\n *\n * 该适配器把 Agent 基础消息构建为 Responses `input` 项，并把服务端返回的\n * `output` item 原样交给 Agent 保存和回传；只有 `function_call` 会被解析为\n * 本地工具调用。\n */\nexport class OpenAIResponsesModel extends Model<OpenAIResponsesProtocol> {\n  #openai: OpenAI;\n  #model: string;\n  #defaultParams: OpenAIResponsesModelOptions['defaultParams'];\n\n  /**\n   * 创建 Responses 适配器。\n   *\n   * `baseURL`、`apiKey` 等 OpenAI SDK 配置可直接透传；方舟 `api/v3` 兼容\n   * endpoint 也通过这里配置。`defaultParams` 会合入每次非流式 Responses 请求。\n   */\n  constructor(options: OpenAIResponsesModelOptions) {\n    super();\n\n    const { client, model, defaultParams, ...clientOptions } = options;\n\n    this.#model = model;\n    this.#defaultParams = defaultParams;\n    this.#openai = client ?? new OpenAI(clientOptions);\n  }\n\n  /**\n   * 调用 Responses API，并将完整 `response.output` 作为协议 context 返回。\n   *\n   * Agent 不会裁剪这些 output item；如服务端返回空 output，则由 Agent 处理重试。\n   */\n  async generate(\n    request: ModelGenerateRequest<OpenAIResponsesProtocol>,\n  ): Promise<ModelGenerateResult<OpenAIResponsesProtocol>> {\n    const params: ResponseCreateParamsNonStreaming = {\n      ...this.#defaultParams,\n      model: this.#model,\n      input: request.context as unknown as ResponseInput,\n    };\n\n    if (request.tools.length > 0) {\n      params.tools = request.tools as unknown as ResponseTool[];\n    }\n\n    const response = await this.#openai.responses.create(params);\n\n    return {\n      messages: response.output as unknown as readonly OpenAIResponsesContext[],\n      raw: response,\n    };\n  }\n\n  /**\n   * 构建 Responses user input message。\n   *\n   * 基础 `{ type: \"text\" }` 会转换为 `input_text`；已声明的图片、文件、视频、\n   * 音频扩展 part 会按 Responses/方舟兼容字段原样保留。\n   */\n  buildUserMessage(\n    input: AgentBaseUserMessage | OpenAIResponsesUserMessage,\n  ): OpenAIResponsesInputMessage {\n    return {\n      role: 'user',\n      content: input.content.map((part) =>\n        part.type === 'text'\n          ? {\n              type: 'input_text',\n              text: part.text,\n            }\n          : part,\n      ),\n    };\n  }\n\n  /** 构建 Responses system input message，用于框架内部提示词和调用方 system prompt。 */\n  buildSystemMessage(\n    input: AgentBaseSystemMessage | OpenAIResponsesSystemMessage,\n  ): OpenAIResponsesInputMessage {\n    return {\n      role: 'system',\n      content: [{ type: 'input_text', text: input.content }],\n    };\n  }\n\n  /** 构建 Responses `function_call_output` item，用于把本地工具结果回传给模型。 */\n  buildToolCallOutputMessage(\n    input: AgentBaseToolCallOutputMessage | OpenAIResponsesToolCallOutputMessage,\n  ): OpenAIResponsesFunctionCallOutput {\n    return {\n      type: 'function_call_output',\n      call_id: input.callId,\n      output: input.output,\n    };\n  }\n\n  /**\n   * 构建 Responses function tool 声明。\n   *\n   * 参数 schema 在此处转换为 OpenAI-compatible JSON Schema；`strict` 只在工具\n   * 显式声明时出现在请求中。\n   */\n  buildToolMessage(input: AgentToolDefinitionInput): OpenAIResponsesTool {\n    return {\n      type: 'function',\n      name: input.name,\n      description: input.description,\n      parameters: toOpenAIToolParameters(input.parameters ?? getDefaultToolParametersSchema()),\n      ...(input.strict === undefined ? {} : { strict: input.strict }),\n    };\n  }\n\n  /** 从混合 Responses context 中筛选 user input message，并反解析多模态内容块。 */\n  parseUserMessages(\n    context: readonly OpenAIResponsesContext[],\n  ): readonly AgentParsedMessage<OpenAIResponsesUserMessage, OpenAIResponsesContext>[] {\n    return context.flatMap((message) =>\n      isInputMessage(message, 'user')\n        ? [\n            {\n              message: { content: parseInputParts(message.content) },\n              sourceMessage: message,\n            },\n          ]\n        : [],\n    );\n  }\n\n  /** 从混合 Responses context 中筛选 system input message，并读取文本提示词。 */\n  parseSystemMessages(\n    context: readonly OpenAIResponsesContext[],\n  ): readonly AgentParsedMessage<OpenAIResponsesSystemMessage, OpenAIResponsesContext>[] {\n    return context.flatMap((message) =>\n      isInputMessage(message, 'system')\n        ? [\n            {\n              message: { content: readInputText(message.content) },\n              sourceMessage: message,\n            },\n          ]\n        : [],\n    );\n  }\n\n  /**\n   * 从 Responses assistant output message 中解析文本和 refusal。\n   *\n   * `reasoning` 等 provider 专属 item 保留在原始 context 中，不映射为 assistant 文本。\n   */\n  parseAssistantMessages(\n    context: readonly OpenAIResponsesContext[],\n  ): readonly AgentParsedMessage<OpenAIResponsesAssistantMessage, OpenAIResponsesContext>[] {\n    return context.flatMap((message) => {\n      if (message.type !== 'message' || message.role !== 'assistant' || !('id' in message)) {\n        return [];\n      }\n\n      return [\n        {\n          message: {\n            content: message.content.flatMap((part) =>\n              part.type === 'output_text' ? [{ type: 'text' as const, text: part.text }] : [],\n            ),\n            refusals: message.content.flatMap((part) =>\n              part.type === 'refusal' ? [part.refusal] : [],\n            ),\n          },\n          sourceMessage: message,\n        },\n      ];\n    });\n  }\n\n  /** 从 Responses `function_call` item 中提取本地工具调用。 */\n  parseToolCalls(\n    context: readonly OpenAIResponsesContext[],\n  ): readonly AgentToolCall<OpenAIResponsesProtocol>[] {\n    return context.flatMap((message) =>\n      message.type === 'function_call'\n        ? [\n            {\n              id: message.call_id,\n              name: message.name,\n              arguments: message.arguments,\n              sourceMessage: message,\n              sourceCall: message,\n            },\n          ]\n        : [],\n    );\n  }\n\n  /** 从 Responses `function_call_output` item 中解析工具结果，保留字符串或内容数组 output。 */\n  parseToolCallOutputMessages(\n    context: readonly OpenAIResponsesContext[],\n  ): readonly AgentParsedMessage<OpenAIResponsesToolCallOutputMessage, OpenAIResponsesContext>[] {\n    return context.flatMap((message) =>\n      message.type === 'function_call_output'\n        ? [\n            {\n              message: {\n                callId: message.call_id,\n                output: message.output,\n              },\n              sourceMessage: message,\n            },\n          ]\n        : [],\n    );\n  }\n\n  /**\n   * 上传本地文件，供后续 Responses 输入内容块通过 `file_id` 引用。\n   *\n   * 默认 `purpose` 为 `user_data`，适合截图、文档等用户输入材料；返回值为\n   * OpenAI SDK 的标准 FileObject。\n   */\n  async uploadFile(\n    filePath: string,\n    options: OpenAIFileUploadOptions = {},\n  ): Promise<OpenAIFileObject> {\n    return this.#openai.files.create({\n      file: createReadStream(filePath),\n      purpose: options.purpose ?? 'user_data',\n    } as FileCreateParams);\n  }\n}\n\nfunction parseInputParts(\n  content: OpenAIResponsesInputMessage['content'],\n): Array<AgentTextPart | OpenAIResponsesUserExtensionPart> {\n  // 兼容历史或外部手写 context 中仍以字符串保存的 input 内容。\n  if (typeof content === 'string') {\n    return [{ type: 'text', text: content }];\n  }\n\n  return content.map((part) =>\n    part.type === 'input_text' ? { type: 'text', text: part.text } : part,\n  );\n}\n\nfunction readInputText(content: OpenAIResponsesInputMessage['content']): string {\n  // system/developer/user input 中可能混有多模态 part；system parser 只提取文本。\n  if (typeof content === 'string') {\n    return content;\n  }\n\n  return content.flatMap((part) => (part.type === 'input_text' ? [part.text] : [])).join('\\n');\n}\n\nfunction isInputMessage(\n  message: OpenAIResponsesContext,\n  role: 'system' | 'user',\n): message is OpenAIResponsesInputMessage {\n  // 模型 output message 也可能有 role 字段；带 id 的项视为响应，不作为 input 解析。\n  return 'role' in message && message.role === role && !('id' in message);\n}\n"],"mappings":"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"}

package/dist/llm/base/index.d.ts

@@ -0,0 +1,73 @@
+import type { AgentBaseSystemMessage, AgentBaseToolCallOutputMessage, AgentBaseUserMessage, AgentParsedMessage, AgentProtocol, AgentToolCall, AgentToolDefinitionInput, AssistantMessageOf, ContextOf, SystemMessageOf, ToolCallOutputMessageOf, ToolOf, UserMessageOf } from '../../agent/types';
+import type { ModelGenerateRequest, ModelGenerateResult } from './types';
+export type { ModelGenerateRequest, ModelGenerateResult } from './types';
+/**
+ * Agent 使用的协议适配器抽象基类。
+ *
+ * builder 将 Agent 基础结构转换为协议消息，parser 从混合上下文中筛选并反解析目标消息，
+ * `generate()` 负责实际模型请求。
+ */
+export declare abstract class Model<P extends AgentProtocol> {
+    /**
+     * 执行一轮非流式模型调用。
+     *
+     * `context` 和 `tools` 已经由 Agent 通过本 Model 的 builder 转成目标协议结构；
+     * 返回的 `messages` 会被 Agent 原样写入上下文，并继续交给 parser 提取工具调用。
+     */
+    abstract generate(request: ModelGenerateRequest<P>): Promise<ModelGenerateResult<P>>;
+    /**
+     * 将 Agent 的基础用户消息或协议专属用户消息构建为可持久保存的上下文项。
+     *
+     * 字符串任务会先被 Agent 包装为 `{ type: "text" }` 内容块，再进入本方法。
+     */
+    abstract buildUserMessage(input: AgentBaseUserMessage | UserMessageOf<P>): ContextOf<P>;
+    /**
+     * 将框架内部提示词或调用方 system prompt 构建为协议 system 上下文项。
+     *
+     * Agent 每轮请求都会临时构建这些消息，但不会把它们写入持久 context/history。
+     */
+    abstract buildSystemMessage(input: AgentBaseSystemMessage | SystemMessageOf<P>): ContextOf<P>;
+    /**
+     * 将本地工具执行结果构建为协议工具结果消息。
+     *
+     * Agent 只提供通用的 `callId + output` 语义；具体 wire 字段由协议适配器决定。
+     */
+    abstract buildToolCallOutputMessage(input: AgentBaseToolCallOutputMessage | ToolCallOutputMessageOf<P>): ContextOf<P>;
+    /**
+     * 将框架工具定义构建为模型 API 接收的工具声明。
+     *
+     * `strict` 仅在工具显式设置时出现；schema 的 OpenAI-compatible 转换也应在 Model 层完成。
+     */
+    abstract buildToolMessage(input: AgentToolDefinitionInput): ToolOf<P>;
+    /**
+     * 从混合上下文中筛选用户消息并反解析为协议用户消息结构。
+     *
+     * 不匹配的上下文项必须被跳过，解析结果需要保留原始 `sourceMessage`。
+     */
+    abstract parseUserMessages(context: readonly ContextOf<P>[]): readonly AgentParsedMessage<UserMessageOf<P>, ContextOf<P>>[];
+    /**
+     * 从混合上下文中筛选 system 消息并反解析。
+     *
+     * 主要供应用调试、恢复历史和自定义模型适配器测试使用。
+     */
+    abstract parseSystemMessages(context: readonly ContextOf<P>[]): readonly AgentParsedMessage<SystemMessageOf<P>, ContextOf<P>>[];
+    /**
+     * 从混合上下文中筛选 assistant 文本/拒绝等普通输出。
+     *
+     * provider 专属推理项可以保留在原始 context 中，不必强行映射到 assistant 消息。
+     */
+    abstract parseAssistantMessages(context: readonly ContextOf<P>[]): readonly AgentParsedMessage<AssistantMessageOf<P>, ContextOf<P>>[];
+    /**
+     * 从一批模型返回消息中按协议顺序提取本地可执行的工具调用。
+     *
+     * Chat 协议中一条 assistant message 可能展开多个调用；Responses 通常一条 item
+     * 对应一个调用。返回项需要携带原始 `sourceCall`。
+     */
+    abstract parseToolCalls(context: readonly ContextOf<P>[]): readonly AgentToolCall<P>[];
+    /**
+     * 从混合上下文中筛选工具结果消息并反解析。
+     *
+     * 该方法不参与 Agent 主循环，但用于外部审计、测试和恢复上下文。
+     */
+    abstract parseToolCallOutputMessages(context: readonly ContextOf<P>[]): readonly AgentParsedMessage<ToolCallOutputMessageOf<P>, ContextOf<P>>[];
+}

package/dist/llm/base/types.d.ts

@@ -0,0 +1,15 @@
+import type { AgentProtocol, ContextOf, ToolOf } from '../../agent/types';
+/** Model 执行一轮模型调用时接收的协议上下文与工具。 */
+export interface ModelGenerateRequest<P extends AgentProtocol> {
+    /** 已由 Model builder 构建好的协议上下文，包含临时 system prompt 与持久历史。 */
+    context: readonly ContextOf<P>[];
+    /** 已由 Model builder 构建好的协议工具声明。 */
+    tools: readonly ToolOf<P>[];
+}
+/** Model 执行一轮模型调用后返回的协议消息与可选完整响应。 */
+export interface ModelGenerateResult<P extends AgentProtocol> {
+    /** 本轮模型生成的协议消息；Agent 会按顺序原样写入 context/history。 */
+    messages: readonly ContextOf<P>[];
+    /** SDK 或 provider 返回的完整原始响应，供调试和审计使用。 */
+    raw?: P['rawResponse'];
+}

package/dist/llm/chat/index.d.ts

@@ -0,0 +1,63 @@
+import type { AgentBaseSystemMessage, AgentBaseToolCallOutputMessage, AgentBaseUserMessage, AgentParsedMessage, AgentToolCall, AgentToolDefinitionInput } from '../../agent/types';
+import { Model, type ModelGenerateRequest, type ModelGenerateResult } from '../base';
+import type { OpenAIChatAssistantMessage, OpenAIChatContext, OpenAIChatModelOptions, OpenAIChatProtocol, OpenAIChatSystemMessage, OpenAIChatTool, OpenAIChatToolCallOutputMessage, OpenAIChatUserMessage } from './types';
+export type * from './types';
+/**
+ * OpenAI-compatible Chat Completions 模型适配器。
+ *
+ * 该类把 Agent 的协议无关消息转换为 Chat `messages` / `tools`，并从
+ * assistant `tool_calls[]` 中反解析本地工具调用。它只支持新版 tool calling
+ * 闭环，不再暴露 deprecated `function_call` / `function` role。
+ */
+export declare class OpenAIChatModel extends Model<OpenAIChatProtocol> {
+    #private;
+    /**
+     * 创建 Chat Completions 适配器。
+     *
+     * 可以直接传入 OpenAI SDK `ClientOptions`，也可以通过 `client` 注入已配置好的
+     * SDK 实例；`defaultParams` 会透传到每次非流式 Chat 请求。
+     */
+    constructor(options: OpenAIChatModelOptions);
+    /**
+     * 调用 Chat Completions，并将首个 choice 的 assistant message 原样返回给 Agent。
+     *
+     * 如果服务端成功响应但没有 choice，返回空数组，由 Agent 负责空响应重试。
+     */
+    generate(request: ModelGenerateRequest<OpenAIChatProtocol>): Promise<ModelGenerateResult<OpenAIChatProtocol>>;
+    /**
+     * 构建 Chat user message。
+     *
+     * Agent 基础文本 part 会转换为 Chat `text` part；协议专属的 `image_url`、
+     * `input_audio`、`file` part 会被原样保留。
+     */
+    buildUserMessage(input: AgentBaseUserMessage | OpenAIChatUserMessage): OpenAIChatContext;
+    /** 构建 Chat system message，保留可选 `name` 字段。 */
+    buildSystemMessage(input: AgentBaseSystemMessage | OpenAIChatSystemMessage): OpenAIChatContext;
+    /** 构建 Chat `tool` role 消息，用于把本地工具结果回传给对应 `tool_call_id`。 */
+    buildToolCallOutputMessage(input: AgentBaseToolCallOutputMessage | OpenAIChatToolCallOutputMessage): OpenAIChatContext;
+    /**
+     * 构建 Chat function tool 声明。
+     *
+     * 参数 schema 在此处转换为 OpenAI-compatible JSON Schema；`strict` 只在调用方
+     * 显式设置时透传。
+     */
+    buildToolMessage(input: AgentToolDefinitionInput): OpenAIChatTool;
+    /** 从混合 Chat context 中筛选 user 消息，并把字符串内容归一为 `text` part。 */
+    parseUserMessages(context: readonly OpenAIChatContext[]): readonly AgentParsedMessage<OpenAIChatUserMessage, OpenAIChatContext>[];
+    /** 从混合 Chat context 中筛选 system 消息，并读取其中的文本内容。 */
+    parseSystemMessages(context: readonly OpenAIChatContext[]): readonly AgentParsedMessage<OpenAIChatSystemMessage, OpenAIChatContext>[];
+    /**
+     * 从 Chat assistant 消息中解析文本输出和 refusal 内容。
+     *
+     * 该方法不解析工具调用；工具调用由 `parseToolCalls()` 单独按顺序展开。
+     */
+    parseAssistantMessages(context: readonly OpenAIChatContext[]): readonly AgentParsedMessage<OpenAIChatAssistantMessage, OpenAIChatContext>[];
+    /**
+     * 从 assistant `tool_calls[]` 中提取本地 function tool 调用。
+     *
+     * Chat custom tool call 会被保留在原始消息里，但不会映射为本地 `@Tool` 调用。
+     */
+    parseToolCalls(context: readonly OpenAIChatContext[]): readonly AgentToolCall<OpenAIChatProtocol>[];
+    /** 从 Chat `tool` role message 中解析工具结果。 */
+    parseToolCallOutputMessages(context: readonly OpenAIChatContext[]): readonly AgentParsedMessage<OpenAIChatToolCallOutputMessage, OpenAIChatContext>[];
+}

package/dist/llm/chat/types.d.ts

@@ -0,0 +1,162 @@
+import type OpenAI from 'openai';
+import type { ClientOptions } from 'openai';
+import type { ChatCompletion, ChatCompletionCreateParamsNonStreaming } from 'openai/resources/chat/completions/completions';
+import type { AgentBaseToolCallOutputMessage, AgentProtocol, AgentTextPart, JsonObject } from '../../agent/types';
+/** Chat 用户消息中的文本内容块。 */
+export interface OpenAIChatTextPart {
+    type: 'text';
+    text: string;
+}
+/** Chat 用户消息中的图片内容块。 */
+export interface OpenAIChatImagePart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+/** Chat 用户消息中的音频内容块。 */
+export interface OpenAIChatInputAudioPart {
+    type: 'input_audio';
+    input_audio: {
+        data: string;
+        format: 'wav' | 'mp3';
+    };
+}
+/** Chat 用户消息中的文件内容块。 */
+export interface OpenAIChatFilePart {
+    type: 'file';
+    file: {
+        file_data?: string;
+        file_id?: string;
+        filename?: string;
+    };
+}
+/** Chat assistant 消息中的拒绝内容块。 */
+export interface OpenAIChatRefusalPart {
+    type: 'refusal';
+    refusal: string;
+}
+/** 应用可通过 `buildUserMessage()` 写入 Chat user message 的内容块集合。 */
+export type OpenAIChatUserContentPart = AgentTextPart | OpenAIChatImagePart | OpenAIChatInputAudioPart | OpenAIChatFilePart;
+/** 应用通过 builder 构建的 Chat 用户消息。 */
+export interface OpenAIChatUserMessage {
+    content: readonly OpenAIChatUserContentPart[];
+    name?: string;
+}
+/** 应用通过 builder 构建的 Chat system 消息。 */
+export interface OpenAIChatSystemMessage {
+    content: string;
+    name?: string;
+}
+/** 从 Chat assistant 消息解析出的标准文本及拒绝内容。 */
+export interface OpenAIChatAssistantMessage {
+    content: readonly AgentTextPart[];
+    refusals?: readonly string[];
+    refusal?: string | null;
+}
+/** Chat 工具结果 builder 使用的基础结构，对应请求中的 `tool` role message。 */
+export type OpenAIChatToolCallOutputMessage = AgentBaseToolCallOutputMessage;
+/** Agent 可以执行的 Chat function tool call。 */
+export interface OpenAIChatRawToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Chat API 可能返回但不映射到本地 `@Tool` 的 custom tool call。 */
+export interface OpenAIChatCustomToolCall {
+    id: string;
+    type: 'custom';
+    custom: {
+        name: string;
+        input: string;
+    };
+}
+/** Chat assistant message 中可能出现的工具调用类型集合。 */
+export type OpenAIChatToolCall = OpenAIChatRawToolCall | OpenAIChatCustomToolCall;
+/** Chat developer message；当前 parser 不单独抽象 developer，但 context 会原样保留。 */
+export interface OpenAIChatDeveloperContextMessage {
+    role: 'developer';
+    content: string | readonly OpenAIChatTextPart[];
+    name?: string;
+}
+/** Chat user message，可由 builder 创建，也可来自初始化上下文。 */
+export interface OpenAIChatUserContextMessage {
+    role: 'user';
+    content: string | readonly OpenAIChatUserContentPart[];
+    name?: string;
+}
+/** Chat system message，用于框架提示词和调用方 system prompt。 */
+export interface OpenAIChatSystemContextMessage {
+    role: 'system';
+    content: string | readonly OpenAIChatTextPart[];
+    name?: string;
+}
+/** Chat 音频输出引用；assistant message 可以仅携带引用而不内联音频。 */
+export interface OpenAIChatAudioReference {
+    id: string;
+}
+/** Chat 音频输出内容；保留 SDK 返回的音频数据、过期时间和转写文本。 */
+export interface OpenAIChatResponseAudio extends OpenAIChatAudioReference {
+    data: string;
+    expires_at: number;
+    transcript: string;
+}
+/** Chat 文本输出中的 URL citation 注解。 */
+export interface OpenAIChatUrlCitationAnnotation {
+    type: 'url_citation';
+    url_citation: {
+        start_index: number;
+        end_index: number;
+        title: string;
+        url: string;
+    };
+}
+/** Chat assistant message；工具调用由 `tool_calls` 承载。 */
+export interface OpenAIChatAssistantContextMessage {
+    role: 'assistant';
+    content?: string | readonly (OpenAIChatTextPart | OpenAIChatRefusalPart)[] | null;
+    audio?: OpenAIChatAudioReference | OpenAIChatResponseAudio | null;
+    annotations?: readonly OpenAIChatUrlCitationAnnotation[];
+    name?: string;
+    refusal?: string | null;
+    tool_calls?: readonly OpenAIChatToolCall[];
+}
+/** Chat 工具结果消息，对应某个 assistant `tool_calls[]` 项。 */
+export interface OpenAIChatToolContextMessage {
+    role: 'tool';
+    tool_call_id: string;
+    content: string | readonly OpenAIChatTextPart[];
+}
+/** Chat 协议上下文消息集合，只保留新版 tool_calls / tool role 工具闭环。 */
+export type OpenAIChatContext = OpenAIChatDeveloperContextMessage | OpenAIChatUserContextMessage | OpenAIChatSystemContextMessage | OpenAIChatAssistantContextMessage | OpenAIChatToolContextMessage;
+/** Chat Completions function tool wire structure。 */
+export interface OpenAIChatTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonObject;
+        strict?: boolean;
+    };
+}
+/** Chat 协议下 Agent 与 Model 共享的关联类型。 */
+export interface OpenAIChatProtocol extends AgentProtocol {
+    context: OpenAIChatContext;
+    tool: OpenAIChatTool;
+    userMessage: OpenAIChatUserMessage;
+    systemMessage: OpenAIChatSystemMessage;
+    assistantMessage: OpenAIChatAssistantMessage;
+    toolCallOutputMessage: OpenAIChatToolCallOutputMessage;
+    rawToolCall: OpenAIChatRawToolCall;
+    rawResponse: ChatCompletion;
+}
+/** 基于 OpenAI SDK 的 Chat Completions 适配器配置。 */
+export interface OpenAIChatModelOptions extends ClientOptions {
+    model: string;
+    client?: OpenAI;
+    defaultParams?: Omit<ChatCompletionCreateParamsNonStreaming, 'messages' | 'model' | 'stream' | 'tools'>;
+}

package/dist/llm/index.d.ts

@@ -0,0 +1,6 @@
+export { Model } from './base';
+export type { ModelGenerateRequest, ModelGenerateResult } from './base';
+export { OpenAIChatModel } from './chat';
+export type { OpenAIChatContext, OpenAIChatAssistantContextMessage, OpenAIChatAssistantMessage, OpenAIChatAudioReference, OpenAIChatCustomToolCall, OpenAIChatDeveloperContextMessage, OpenAIChatFilePart, OpenAIChatImagePart, OpenAIChatInputAudioPart, OpenAIChatModelOptions, OpenAIChatProtocol, OpenAIChatRawToolCall, OpenAIChatRefusalPart, OpenAIChatResponseAudio, OpenAIChatSystemContextMessage, OpenAIChatSystemMessage, OpenAIChatTextPart, OpenAIChatTool, OpenAIChatToolCall, OpenAIChatToolCallOutputMessage, OpenAIChatToolContextMessage, OpenAIChatUrlCitationAnnotation, OpenAIChatUserContentPart, OpenAIChatUserContextMessage, OpenAIChatUserMessage, } from './chat';
+export { OpenAIResponsesModel } from './responses';
+export type { OpenAIFileObject, OpenAIFileUploadOptions, OpenAIResponsesAnnotation, OpenAIResponsesContext, OpenAIResponsesAssistantMessage, OpenAIResponsesContainerFileCitationAnnotation, OpenAIResponsesFileCitationAnnotation, OpenAIResponsesFilePathAnnotation, OpenAIResponsesFunctionCall, OpenAIResponsesFunctionCallOutput, OpenAIResponsesFunctionCallOutputContentPart, OpenAIResponsesFunctionCallOutputValue, OpenAIResponsesImagePixelLimit, OpenAIResponsesInputAudioPart, OpenAIResponsesInputFilePart, OpenAIResponsesInputImagePart, OpenAIResponsesInputMessage, OpenAIResponsesInputTextPart, OpenAIResponsesInputVideoPart, OpenAIResponsesItemStatus, OpenAIResponsesLogprob, OpenAIResponsesModelOptions, OpenAIResponsesOutputMessage, OpenAIResponsesOutputRefusalPart, OpenAIResponsesOutputTextPart, OpenAIResponsesProtocol, OpenAIResponsesReasoningContentPart, OpenAIResponsesReasoningItem, OpenAIResponsesReasoningSummaryPart, OpenAIResponsesSystemMessage, OpenAIResponsesTopLogprob, OpenAIResponsesTool, OpenAIResponsesToolCallOutputMessage, OpenAIResponsesUrlCitationAnnotation, OpenAIResponsesUserExtensionPart, OpenAIResponsesUserMessage, } from './responses';

package/dist/llm/openai-schema.d.ts

@@ -0,0 +1,3 @@
+import type { JsonObject, ToolParametersSchema } from '../agent/types';
+/** 将框架工具 schema 转换为 OpenAI-compatible function tool 参数定义。 */
+export declare function toOpenAIToolParameters(schema: ToolParametersSchema): JsonObject;

package/dist/llm/responses/index.d.ts

@@ -0,0 +1,66 @@
+import type { AgentBaseSystemMessage, AgentBaseToolCallOutputMessage, AgentBaseUserMessage, AgentParsedMessage, AgentToolCall, AgentToolDefinitionInput } from '../../agent/types';
+import { Model, type ModelGenerateRequest, type ModelGenerateResult } from '../base';
+import type { OpenAIFileObject, OpenAIFileUploadOptions, OpenAIResponsesAssistantMessage, OpenAIResponsesContext, OpenAIResponsesFunctionCallOutput, OpenAIResponsesInputMessage, OpenAIResponsesModelOptions, OpenAIResponsesProtocol, OpenAIResponsesSystemMessage, OpenAIResponsesTool, OpenAIResponsesToolCallOutputMessage, OpenAIResponsesUserMessage } from './types';
+export type * from './types';
+/**
+ * OpenAI-compatible Responses 模型适配器，提供标准 Files 上传能力。
+ *
+ * 该适配器把 Agent 基础消息构建为 Responses `input` 项，并把服务端返回的
+ * `output` item 原样交给 Agent 保存和回传；只有 `function_call` 会被解析为
+ * 本地工具调用。
+ */
+export declare class OpenAIResponsesModel extends Model<OpenAIResponsesProtocol> {
+    #private;
+    /**
+     * 创建 Responses 适配器。
+     *
+     * `baseURL`、`apiKey` 等 OpenAI SDK 配置可直接透传；方舟 `api/v3` 兼容
+     * endpoint 也通过这里配置。`defaultParams` 会合入每次非流式 Responses 请求。
+     */
+    constructor(options: OpenAIResponsesModelOptions);
+    /**
+     * 调用 Responses API，并将完整 `response.output` 作为协议 context 返回。
+     *
+     * Agent 不会裁剪这些 output item；如服务端返回空 output，则由 Agent 处理重试。
+     */
+    generate(request: ModelGenerateRequest<OpenAIResponsesProtocol>): Promise<ModelGenerateResult<OpenAIResponsesProtocol>>;
+    /**
+     * 构建 Responses user input message。
+     *
+     * 基础 `{ type: "text" }` 会转换为 `input_text`；已声明的图片、文件、视频、
+     * 音频扩展 part 会按 Responses/方舟兼容字段原样保留。
+     */
+    buildUserMessage(input: AgentBaseUserMessage | OpenAIResponsesUserMessage): OpenAIResponsesInputMessage;
+    /** 构建 Responses system input message，用于框架内部提示词和调用方 system prompt。 */
+    buildSystemMessage(input: AgentBaseSystemMessage | OpenAIResponsesSystemMessage): OpenAIResponsesInputMessage;
+    /** 构建 Responses `function_call_output` item，用于把本地工具结果回传给模型。 */
+    buildToolCallOutputMessage(input: AgentBaseToolCallOutputMessage | OpenAIResponsesToolCallOutputMessage): OpenAIResponsesFunctionCallOutput;
+    /**
+     * 构建 Responses function tool 声明。
+     *
+     * 参数 schema 在此处转换为 OpenAI-compatible JSON Schema；`strict` 只在工具
+     * 显式声明时出现在请求中。
+     */
+    buildToolMessage(input: AgentToolDefinitionInput): OpenAIResponsesTool;
+    /** 从混合 Responses context 中筛选 user input message，并反解析多模态内容块。 */
+    parseUserMessages(context: readonly OpenAIResponsesContext[]): readonly AgentParsedMessage<OpenAIResponsesUserMessage, OpenAIResponsesContext>[];
+    /** 从混合 Responses context 中筛选 system input message，并读取文本提示词。 */
+    parseSystemMessages(context: readonly OpenAIResponsesContext[]): readonly AgentParsedMessage<OpenAIResponsesSystemMessage, OpenAIResponsesContext>[];
+    /**
+     * 从 Responses assistant output message 中解析文本和 refusal。
+     *
+     * `reasoning` 等 provider 专属 item 保留在原始 context 中，不映射为 assistant 文本。
+     */
+    parseAssistantMessages(context: readonly OpenAIResponsesContext[]): readonly AgentParsedMessage<OpenAIResponsesAssistantMessage, OpenAIResponsesContext>[];
+    /** 从 Responses `function_call` item 中提取本地工具调用。 */
+    parseToolCalls(context: readonly OpenAIResponsesContext[]): readonly AgentToolCall<OpenAIResponsesProtocol>[];
+    /** 从 Responses `function_call_output` item 中解析工具结果，保留字符串或内容数组 output。 */
+    parseToolCallOutputMessages(context: readonly OpenAIResponsesContext[]): readonly AgentParsedMessage<OpenAIResponsesToolCallOutputMessage, OpenAIResponsesContext>[];
+    /**
+     * 上传本地文件，供后续 Responses 输入内容块通过 `file_id` 引用。
+     *
+     * 默认 `purpose` 为 `user_data`，适合截图、文档等用户输入材料；返回值为
+     * OpenAI SDK 的标准 FileObject。
+     */
+    uploadFile(filePath: string, options?: OpenAIFileUploadOptions): Promise<OpenAIFileObject>;
+}