@notic/agent-engine 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/LICENSE +190 -0
  2. package/README.md +725 -0
  3. package/dist/adapter/AnthropicAdapter.d.ts +47 -0
  4. package/dist/adapter/AnthropicAdapter.d.ts.map +1 -0
  5. package/dist/adapter/AnthropicAdapter.js +341 -0
  6. package/dist/adapter/AnthropicAdapter.js.map +1 -0
  7. package/dist/adapter/GeminiAdapter.d.ts +47 -0
  8. package/dist/adapter/GeminiAdapter.d.ts.map +1 -0
  9. package/dist/adapter/GeminiAdapter.js +315 -0
  10. package/dist/adapter/GeminiAdapter.js.map +1 -0
  11. package/dist/adapter/MessageAdapter.d.ts +66 -0
  12. package/dist/adapter/MessageAdapter.d.ts.map +1 -0
  13. package/dist/adapter/MessageAdapter.js +66 -0
  14. package/dist/adapter/MessageAdapter.js.map +1 -0
  15. package/dist/adapter/OpenAIAdapter.d.ts +45 -0
  16. package/dist/adapter/OpenAIAdapter.d.ts.map +1 -0
  17. package/dist/adapter/OpenAIAdapter.js +305 -0
  18. package/dist/adapter/OpenAIAdapter.js.map +1 -0
  19. package/dist/adapter/index.d.ts +5 -0
  20. package/dist/adapter/index.d.ts.map +1 -0
  21. package/dist/adapter/index.js +10 -0
  22. package/dist/adapter/index.js.map +1 -0
  23. package/dist/agent/Agent.d.ts +319 -0
  24. package/dist/agent/Agent.d.ts.map +1 -0
  25. package/dist/agent/Agent.js +876 -0
  26. package/dist/agent/Agent.js.map +1 -0
  27. package/dist/agent/index.d.ts +2 -0
  28. package/dist/agent/index.d.ts.map +1 -0
  29. package/dist/agent/index.js +8 -0
  30. package/dist/agent/index.js.map +1 -0
  31. package/dist/config/RequestConfig.d.ts +119 -0
  32. package/dist/config/RequestConfig.d.ts.map +1 -0
  33. package/dist/config/RequestConfig.js +257 -0
  34. package/dist/config/RequestConfig.js.map +1 -0
  35. package/dist/config/index.d.ts +2 -0
  36. package/dist/config/index.d.ts.map +1 -0
  37. package/dist/config/index.js +6 -0
  38. package/dist/config/index.js.map +1 -0
  39. package/dist/index.d.ts +29 -0
  40. package/dist/index.d.ts.map +1 -0
  41. package/dist/index.js +69 -0
  42. package/dist/index.js.map +1 -0
  43. package/dist/media/DefaultMediaResolver.d.ts +17 -0
  44. package/dist/media/DefaultMediaResolver.d.ts.map +1 -0
  45. package/dist/media/DefaultMediaResolver.js +114 -0
  46. package/dist/media/DefaultMediaResolver.js.map +1 -0
  47. package/dist/media/MediaResolver.d.ts +20 -0
  48. package/dist/media/MediaResolver.d.ts.map +1 -0
  49. package/dist/media/MediaResolver.js +3 -0
  50. package/dist/media/MediaResolver.js.map +1 -0
  51. package/dist/media/index.d.ts +3 -0
  52. package/dist/media/index.d.ts.map +1 -0
  53. package/dist/media/index.js +6 -0
  54. package/dist/media/index.js.map +1 -0
  55. package/dist/message/Message.d.ts +121 -0
  56. package/dist/message/Message.d.ts.map +1 -0
  57. package/dist/message/Message.js +345 -0
  58. package/dist/message/Message.js.map +1 -0
  59. package/dist/message/MessagePart.d.ts +46 -0
  60. package/dist/message/MessagePart.d.ts.map +1 -0
  61. package/dist/message/MessagePart.js +6 -0
  62. package/dist/message/MessagePart.js.map +1 -0
  63. package/dist/message/Role.d.ts +10 -0
  64. package/dist/message/Role.d.ts.map +1 -0
  65. package/dist/message/Role.js +14 -0
  66. package/dist/message/Role.js.map +1 -0
  67. package/dist/message/Usage.d.ts +31 -0
  68. package/dist/message/Usage.d.ts.map +1 -0
  69. package/dist/message/Usage.js +58 -0
  70. package/dist/message/Usage.js.map +1 -0
  71. package/dist/message/index.d.ts +5 -0
  72. package/dist/message/index.d.ts.map +1 -0
  73. package/dist/message/index.js +10 -0
  74. package/dist/message/index.js.map +1 -0
  75. package/dist/prompt/Injection.d.ts +72 -0
  76. package/dist/prompt/Injection.d.ts.map +1 -0
  77. package/dist/prompt/Injection.js +123 -0
  78. package/dist/prompt/Injection.js.map +1 -0
  79. package/dist/prompt/PromptBuilder.d.ts +276 -0
  80. package/dist/prompt/PromptBuilder.d.ts.map +1 -0
  81. package/dist/prompt/PromptBuilder.js +465 -0
  82. package/dist/prompt/PromptBuilder.js.map +1 -0
  83. package/dist/prompt/Rule.d.ts +98 -0
  84. package/dist/prompt/Rule.d.ts.map +1 -0
  85. package/dist/prompt/Rule.js +275 -0
  86. package/dist/prompt/Rule.js.map +1 -0
  87. package/dist/prompt/index.d.ts +4 -0
  88. package/dist/prompt/index.d.ts.map +1 -0
  89. package/dist/prompt/index.js +10 -0
  90. package/dist/prompt/index.js.map +1 -0
  91. package/dist/session/Inserter.d.ts +76 -0
  92. package/dist/session/Inserter.d.ts.map +1 -0
  93. package/dist/session/Inserter.js +217 -0
  94. package/dist/session/Inserter.js.map +1 -0
  95. package/dist/session/Paginator.d.ts +52 -0
  96. package/dist/session/Paginator.d.ts.map +1 -0
  97. package/dist/session/Paginator.js +110 -0
  98. package/dist/session/Paginator.js.map +1 -0
  99. package/dist/session/Query.d.ts +54 -0
  100. package/dist/session/Query.d.ts.map +1 -0
  101. package/dist/session/Query.js +97 -0
  102. package/dist/session/Query.js.map +1 -0
  103. package/dist/session/SearchCriteria.d.ts +39 -0
  104. package/dist/session/SearchCriteria.d.ts.map +1 -0
  105. package/dist/session/SearchCriteria.js +28 -0
  106. package/dist/session/SearchCriteria.js.map +1 -0
  107. package/dist/session/Session.d.ts +139 -0
  108. package/dist/session/Session.d.ts.map +1 -0
  109. package/dist/session/Session.js +344 -0
  110. package/dist/session/Session.js.map +1 -0
  111. package/dist/session/index.d.ts +6 -0
  112. package/dist/session/index.d.ts.map +1 -0
  113. package/dist/session/index.js +15 -0
  114. package/dist/session/index.js.map +1 -0
  115. package/dist/session/matchUtils.d.ts +22 -0
  116. package/dist/session/matchUtils.d.ts.map +1 -0
  117. package/dist/session/matchUtils.js +138 -0
  118. package/dist/session/matchUtils.js.map +1 -0
  119. package/dist/stream/StreamEvent.d.ts +193 -0
  120. package/dist/stream/StreamEvent.d.ts.map +1 -0
  121. package/dist/stream/StreamEvent.js +44 -0
  122. package/dist/stream/StreamEvent.js.map +1 -0
  123. package/dist/stream/StreamParser.d.ts +47 -0
  124. package/dist/stream/StreamParser.d.ts.map +1 -0
  125. package/dist/stream/StreamParser.js +225 -0
  126. package/dist/stream/StreamParser.js.map +1 -0
  127. package/dist/stream/index.d.ts +3 -0
  128. package/dist/stream/index.d.ts.map +1 -0
  129. package/dist/stream/index.js +8 -0
  130. package/dist/stream/index.js.map +1 -0
  131. package/dist/tool/Context.d.ts +30 -0
  132. package/dist/tool/Context.d.ts.map +1 -0
  133. package/dist/tool/Context.js +50 -0
  134. package/dist/tool/Context.js.map +1 -0
  135. package/dist/tool/Hook.d.ts +23 -0
  136. package/dist/tool/Hook.d.ts.map +1 -0
  137. package/dist/tool/Hook.js +27 -0
  138. package/dist/tool/Hook.js.map +1 -0
  139. package/dist/tool/McpToolAdapter.d.ts +47 -0
  140. package/dist/tool/McpToolAdapter.d.ts.map +1 -0
  141. package/dist/tool/McpToolAdapter.js +88 -0
  142. package/dist/tool/McpToolAdapter.js.map +1 -0
  143. package/dist/tool/Param.d.ts +68 -0
  144. package/dist/tool/Param.d.ts.map +1 -0
  145. package/dist/tool/Param.js +161 -0
  146. package/dist/tool/Param.js.map +1 -0
  147. package/dist/tool/Tool.d.ts +92 -0
  148. package/dist/tool/Tool.d.ts.map +1 -0
  149. package/dist/tool/Tool.js +198 -0
  150. package/dist/tool/Tool.js.map +1 -0
  151. package/dist/tool/ToolCall.d.ts +37 -0
  152. package/dist/tool/ToolCall.d.ts.map +1 -0
  153. package/dist/tool/ToolCall.js +118 -0
  154. package/dist/tool/ToolCall.js.map +1 -0
  155. package/dist/tool/ToolKit.d.ts +87 -0
  156. package/dist/tool/ToolKit.d.ts.map +1 -0
  157. package/dist/tool/ToolKit.js +173 -0
  158. package/dist/tool/ToolKit.js.map +1 -0
  159. package/dist/tool/ValueType.d.ts +12 -0
  160. package/dist/tool/ValueType.d.ts.map +1 -0
  161. package/dist/tool/ValueType.js +16 -0
  162. package/dist/tool/ValueType.js.map +1 -0
  163. package/dist/tool/index.d.ts +9 -0
  164. package/dist/tool/index.d.ts.map +1 -0
  165. package/dist/tool/index.js +21 -0
  166. package/dist/tool/index.js.map +1 -0
  167. package/dist/utils/generateId.d.ts +10 -0
  168. package/dist/utils/generateId.d.ts.map +1 -0
  169. package/dist/utils/generateId.js +18 -0
  170. package/dist/utils/generateId.js.map +1 -0
  171. package/dist/utils/index.d.ts +2 -0
  172. package/dist/utils/index.d.ts.map +1 -0
  173. package/dist/utils/index.js +6 -0
  174. package/dist/utils/index.js.map +1 -0
  175. package/package.json +72 -0
@@ -0,0 +1,876 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.Agent = exports.AgentTimeoutError = exports.AgentAbortError = void 0;
4
+ const Message_1 = require("../message/Message");
5
+ const Usage_1 = require("../message/Usage");
6
+ const OpenAIAdapter_1 = require("../adapter/OpenAIAdapter");
7
+ const ToolKit_1 = require("../tool/ToolKit");
8
+ const StreamParser_1 = require("../stream/StreamParser");
9
+ const StreamEvent_1 = require("../stream/StreamEvent");
10
+ const utils_1 = require("../utils");
11
+ /** Agent 主动中断错误 */
12
+ class AgentAbortError extends Error {
13
+ constructor(message = "Agent run aborted") {
14
+ super(message);
15
+ this.name = "AbortError";
16
+ }
17
+ }
18
+ exports.AgentAbortError = AgentAbortError;
19
+ /** Agent 超时错误 */
20
+ class AgentTimeoutError extends Error {
21
+ constructor(timeoutMs) {
22
+ super(`Agent run timed out after ${timeoutMs}ms`);
23
+ this.name = "TimeoutError";
24
+ }
25
+ }
26
+ exports.AgentTimeoutError = AgentTimeoutError;
27
+ /**
28
+ * 智能体 — 自动循环层
29
+ *
30
+ * 串联Session + Adapter + ToolKit + StreamParser,
31
+ * 实现流式调用→ 解析 → 工具执行 → 再调用的自动循环。
32
+ *
33
+ * 用法:
34
+ *const agent = new Agent({ client, model, session, toolkit });
35
+ * agent
36
+ * .on(StreamEventType.TEXT_DELTA, (e) => process.stdout.write(e.delta))
37
+ * .on(StreamEventType.TOOL_CALL_START, (e) => console.log(`🔧 ${e.name}`));
38
+ *
39
+ * const reply = await agent.run("北京天气怎么样?");
40
+ */
41
+ class Agent {
42
+ _client;
43
+ _model;
44
+ _adapter;
45
+ _toolkit;
46
+ _session;
47
+ _promptBuilder;
48
+ _maxTurns;
49
+ _config;
50
+ _requestOptions;
51
+ _toolApproval;
52
+ _toolApprovalMode;
53
+ _toolApprovalTimeoutMs;
54
+ _toolApprovalTimeoutPolicy;
55
+ _toolErrorPolicy;
56
+ _pendingApprovals = new Map();
57
+ _handlers = new Map();
58
+ _activeAbortController;
59
+ _lastRunState;
60
+ constructor(options) {
61
+ this._client = options.client;
62
+ this._model = options.model;
63
+ this._adapter = options.adapter || new OpenAIAdapter_1.OpenAIAdapter();
64
+ this._toolkit = options.toolkit;
65
+ this._session = options.session;
66
+ this._promptBuilder = options.promptBuilder;
67
+ this._config = options.config;
68
+ this._maxTurns = options.maxTurns ?? 10;
69
+ this._requestOptions = options.requestOptions ?? {};
70
+ this._toolApproval = options.toolApproval;
71
+ this._toolApprovalMode = options.toolApprovalMode ?? "auto";
72
+ this._toolApprovalTimeoutMs = options.toolApprovalTimeoutMs;
73
+ this._toolApprovalTimeoutPolicy = options.toolApprovalTimeoutPolicy ?? "reject";
74
+ this._toolErrorPolicy = options.toolErrorPolicy ?? "return_to_model";
75
+ // 初始化所有事件的handler列表
76
+ for (const type of Object.values(StreamEvent_1.StreamEventType)) {
77
+ this._handlers.set(type, []);
78
+ }
79
+ }
80
+ on(event, handler) {
81
+ const events = Array.isArray(event) ? event : [event];
82
+ for (const e of events) {
83
+ if (!this._handlers.has(e)) {
84
+ this._handlers.set(e, []);
85
+ }
86
+ this._handlers.get(e).push(handler);
87
+ }
88
+ return this;
89
+ }
90
+ off(event, handler) {
91
+ const handlers = this._handlers.get(event);
92
+ if (handlers) {
93
+ const index = handlers.indexOf(handler);
94
+ if (index !== -1)
95
+ handlers.splice(index, 1);
96
+ }
97
+ return this;
98
+ }
99
+ once(event, handler) {
100
+ const wrapper = (e) => {
101
+ this.off(event, wrapper);
102
+ handler(e);
103
+ };
104
+ return this.on(event, wrapper);
105
+ }
106
+ /**
107
+ * 移除指定事件的所有监听器,不传参则移除所有事件的所有监听器
108
+ */
109
+ removeAllListeners(event) {
110
+ if (event) {
111
+ this._handlers.set(event, []);
112
+ }
113
+ else {
114
+ for (const key of this._handlers.keys()) {
115
+ this._handlers.set(key, []);
116
+ }
117
+ }
118
+ return this;
119
+ }
120
+ // ========================
121
+ // 运行
122
+ // ========================
123
+ /**
124
+ * 流式运行 — 最常用的入口
125
+ *
126
+ * 自动addUser → 循环(stream → parse → toolCall → execute) → addAssistant
127
+ *
128
+ * @param content 用户输入
129
+ * @param options 临时覆盖的请求参数
130
+ * @returns 最终的Assistant Message
131
+ */
132
+ async run(content, options) {
133
+ const userMsg = Message_1.Message.user(content);
134
+ return this.runWith(userMsg, options);
135
+ }
136
+ /**
137
+ * 传入已构建的 Message 运行
138
+ *
139
+ * 直接将完整的 Message 对象追加到 Session,
140
+ * 保留其所有 parts(多模态内容)、tags、metadata。
141
+ */
142
+ async runWith(message, options) {
143
+ this._session.addMessage(message);
144
+ return this.executeLoop(options);
145
+ }
146
+ /**
147
+ * 直接传入历史运行(不走Session)
148
+ */
149
+ async runRaw(messages, options) {
150
+ const run = this.prepareRunOptions(options);
151
+ try {
152
+ this.throwIfAborted(run.signal);
153
+ const configParams = this._config ? this._config.build() : {};
154
+ const mergedOptions = { ...configParams, ...this._requestOptions, ...run.requestOptions };
155
+ const parser = new StreamParser_1.StreamParser();
156
+ const { messages: serialized } = await this.raceWithAbort(this._adapter.serialize(messages, run.serializeOptions), run.signal);
157
+ const requestParams = {
158
+ model: this._model,
159
+ messages: serialized,
160
+ stream: true,
161
+ ...mergedOptions,
162
+ };
163
+ if (this._toolkit && this._toolkit.size > 0) {
164
+ requestParams.tools = this._toolkit.schemas;
165
+ }
166
+ const stream = await this.raceWithAbort(this._client.chat.completions.create(requestParams, this.createClientOptions(run.signal)), run.signal);
167
+ for await (const chunk of stream) {
168
+ this.throwIfAborted(run.signal);
169
+ const events = parser.feed(chunk);
170
+ this.emitAll(events);
171
+ }
172
+ this.throwIfAborted(run.signal);
173
+ const finalEvents = parser.finish();
174
+ this.emitAll(finalEvents);
175
+ const message = this.extractMessage(finalEvents);
176
+ return message;
177
+ }
178
+ catch (e) {
179
+ const error = this.toError(e);
180
+ this.emitError(error);
181
+ throw error;
182
+ }
183
+ finally {
184
+ run.cleanup();
185
+ }
186
+ }
187
+ // ========================
188
+ // 配置
189
+ // ========================
190
+ /** 修改模型 */
191
+ setModel(model) {
192
+ this._model = model;
193
+ return this;
194
+ }
195
+ /** 修改最大轮次 */
196
+ setMaxTurns(n) {
197
+ this._maxTurns = n;
198
+ return this;
199
+ }
200
+ /** 设置请求参数配置 */
201
+ setConfig(config) {
202
+ this._config = config;
203
+ return this;
204
+ }
205
+ /** 获取请求参数配置 */
206
+ get config() {
207
+ return this._config;
208
+ }
209
+ /** 设置额外请求参数(兼容旧 API) */
210
+ setRequestOptions(options) {
211
+ this._requestOptions = { ...this._requestOptions, ...options };
212
+ return this;
213
+ }
214
+ /** 获取关联的Session */
215
+ get session() {
216
+ return this._session;
217
+ }
218
+ /** 获取提示词构建器 */
219
+ get promptBuilder() {
220
+ return this._promptBuilder;
221
+ }
222
+ /** 设置提示词构建器 */
223
+ setPromptBuilder(builder) {
224
+ this._promptBuilder = builder;
225
+ return this;
226
+ }
227
+ /** 设置工具审批函数 */
228
+ setToolApproval(handler) {
229
+ this._toolApproval = handler;
230
+ return this;
231
+ }
232
+ /** 设置工具审批模式 */
233
+ setToolApprovalMode(mode) {
234
+ this._toolApprovalMode = mode;
235
+ return this;
236
+ }
237
+ /** 获取工具审批函数 */
238
+ get toolApproval() {
239
+ return this._toolApproval;
240
+ }
241
+ /** 获取当前等待外部决策的审批请求 */
242
+ get pendingApprovals() {
243
+ return Array.from(this._pendingApprovals.values()).map(({ resolve, reject, createdAt, ...req }) => req);
244
+ }
245
+ /** 外部批准一个 manual 工具审批请求 */
246
+ approve(approvalId) {
247
+ return this.resolvePendingApproval(approvalId, true);
248
+ }
249
+ /** 外部拒绝一个 manual 工具审批请求 */
250
+ reject(approvalId, reason) {
251
+ return this.resolvePendingApproval(approvalId, { approved: false, reason });
252
+ }
253
+ /** 设置工具错误策略 */
254
+ setToolErrorPolicy(policy) {
255
+ this._toolErrorPolicy = policy;
256
+ return this;
257
+ }
258
+ /** 获取工具错误策略 */
259
+ get toolErrorPolicy() {
260
+ return this._toolErrorPolicy;
261
+ }
262
+ /** 获取当前模型 */
263
+ get model() {
264
+ return this._model;
265
+ }
266
+ /** 最近一次运行状态 */
267
+ get lastRunState() {
268
+ return this._lastRunState;
269
+ }
270
+ /** 是否存在可恢复的异常中断现场 */
271
+ get canResume() {
272
+ return this._lastRunState?.canResume ?? false;
273
+ }
274
+ /** 是否可以继续当前任务:异常可恢复,或当前 Session 光标在 assistant 消息上 */
275
+ get canContinue() {
276
+ return this.canResume || this._session.cursor.role === "assistant";
277
+ }
278
+ /** 当前是否有运行中的请求 */
279
+ get isRunning() {
280
+ return !!this._activeAbortController && !this._activeAbortController.signal.aborted;
281
+ }
282
+ /**
283
+ * 中断当前运行中的 Agent。
284
+ *
285
+ * 返回 true 表示确实触发了中断;返回 false 表示当前没有可中断的运行。
286
+ */
287
+ abort(reason) {
288
+ if (!this._activeAbortController || this._activeAbortController.signal.aborted) {
289
+ return false;
290
+ }
291
+ const error = reason instanceof Error
292
+ ? reason
293
+ : new AgentAbortError(reason ?? "Agent run aborted by user");
294
+ this._activeAbortController.abort(error);
295
+ return true;
296
+ }
297
+ /**
298
+ * 继续当前任务。
299
+ *
300
+ * mode=auto 时:若上次运行可恢复,则走 resume 语义;否则追加普通继续提示。
301
+ */
302
+ async continue(options) {
303
+ const mode = options?.mode ?? "auto";
304
+ const shouldResume = mode === "resume" || (mode === "auto" && this.canResume);
305
+ if (mode === "resume" && !this.canResume) {
306
+ throw new Error("当前没有可恢复的中断任务");
307
+ }
308
+ if (!shouldResume && !this.canContinue) {
309
+ throw new Error("当前没有可继续的上下文");
310
+ }
311
+ const prompt = options?.prompt ?? (shouldResume
312
+ ? "请从上一次中断的位置继续完成任务。不要重复已经完成的内容。如果上一次停在句子中间,请自然衔接;如果停在工具调用或操作流程中,请继续完成剩余步骤。"
313
+ : "请继续完成上一个任务,保持相同的结构和风格,不要重复已经完成的内容。");
314
+ const serializeOptions = options?.serializeOptions ?? {
315
+ thinking: {
316
+ mode: options?.thinkingMode ?? (shouldResume ? "auto" : "none"),
317
+ scope: shouldResume ? "last" : "none",
318
+ },
319
+ };
320
+ const { mode: _mode, prompt: _prompt, thinkingMode: _thinkingMode, ...runOptions } = options ?? {};
321
+ return this.run(prompt, {
322
+ ...runOptions,
323
+ serializeOptions,
324
+ });
325
+ }
326
+ /** 严格从异常中断处恢复 */
327
+ async resume(options) {
328
+ return this.continue({ ...options, mode: "resume" });
329
+ }
330
+ // ========================
331
+ // 核心循环
332
+ // ========================
333
+ async executeLoop(options) {
334
+ const run = this.prepareRunOptions(options);
335
+ this.startRunState();
336
+ let currentParser;
337
+ let partialAlreadyPersisted = false;
338
+ try {
339
+ const mergedOptions = this.buildMergedOptions(run.requestOptions);
340
+ let lastAssistantMsg;
341
+ for (let turn = 0; turn < this._maxTurns; turn++) {
342
+ this.throwIfAborted(run.signal);
343
+ const parser = new StreamParser_1.StreamParser();
344
+ currentParser = parser;
345
+ partialAlreadyPersisted = false;
346
+ this.updateRunState({ turn });
347
+ this.emit({ type: StreamEvent_1.StreamEventType.TURN_START, turn });
348
+ // 流式调用 + 解析
349
+ const { assistantMsg, finishReason } = await this.executeSingleStream(parser, mergedOptions, run);
350
+ // 添加到 Session
351
+ this._session.addAssistant(assistantMsg);
352
+ lastAssistantMsg = assistantMsg;
353
+ currentParser = undefined;
354
+ partialAlreadyPersisted = true;
355
+ this.updateRunState({ lastMessage: assistantMsg });
356
+ // 输出长度限制
357
+ if (finishReason === "length") {
358
+ this.failRunState(new Error("模型输出达到长度限制,未完成最终回复"), "max_tokens", assistantMsg, true);
359
+ return assistantMsg;
360
+ }
361
+ const hasToolCalls = assistantMsg.toolCalls.length > 0;
362
+ this.emit({ type: StreamEvent_1.StreamEventType.TURN_END, turn, hasToolCalls });
363
+ // 如果没有工具调用,循环结束
364
+ if (!hasToolCalls || !this._toolkit) {
365
+ this.completeRunState(assistantMsg, "final");
366
+ return assistantMsg;
367
+ }
368
+ // 工具审批 + 执行
369
+ await this.processToolCalls(assistantMsg.toolCalls, turn, run.signal);
370
+ }
371
+ // 循环结束后的检查
372
+ return this.handleLoopExhausted(lastAssistantMsg);
373
+ }
374
+ catch (e) {
375
+ const error = this.toError(e);
376
+ const reason = this.classifyStopReason(error);
377
+ const partial = currentParser && !partialAlreadyPersisted
378
+ ? this.persistPartialSnapshot(currentParser, reason)
379
+ : undefined;
380
+ if (this._lastRunState?.error !== error) {
381
+ this.failRunState(error, reason, partial, !!partial || this.isContinuableError(error));
382
+ }
383
+ this.emitError(error);
384
+ throw error;
385
+ }
386
+ finally {
387
+ run.cleanup();
388
+ }
389
+ }
390
+ /**
391
+ * 合并请求参数:Config → requestOptions → run options
392
+ */
393
+ buildMergedOptions(runOptions) {
394
+ const configParams = this._config ? this._config.build() : {};
395
+ return { ...configParams, ...this._requestOptions, ...runOptions };
396
+ }
397
+ /**
398
+ * 执行单轮流式调用:序列化 → 请求 → 解析 → 返回 Message
399
+ */
400
+ async executeSingleStream(parser, mergedOptions, run) {
401
+ // 获取会话历史,经 PromptBuilder 注入后序列化
402
+ const history = this._session.history();
403
+ const context = this._promptBuilder
404
+ ? this._promptBuilder.build(history, run.promptBuildOptions)
405
+ : history;
406
+ const { messages: serialized } = await this.raceWithAbort(this._adapter.serialize(context, run.serializeOptions), run.signal);
407
+ // 构建请求参数
408
+ const requestParams = {
409
+ model: this._model,
410
+ messages: serialized,
411
+ stream: true,
412
+ ...mergedOptions,
413
+ };
414
+ if (this._toolkit && this._toolkit.size > 0) {
415
+ requestParams.tools = this._toolkit.schemas;
416
+ }
417
+ // 流式调用
418
+ const stream = await this.raceWithAbort(this._client.chat.completions.create(requestParams, this.createClientOptions(run.signal)), run.signal);
419
+ // 解析 chunks
420
+ let streamUsage;
421
+ for await (const chunk of stream) {
422
+ this.throwIfAborted(run.signal);
423
+ if (chunk.usage) {
424
+ streamUsage = Usage_1.Usage.fromRaw(chunk.usage);
425
+ }
426
+ const events = parser.feed(chunk);
427
+ this.emitAll(events);
428
+ }
429
+ this.throwIfAborted(run.signal);
430
+ // 结束解析
431
+ const finalEvents = parser.finish();
432
+ this.emitAll(finalEvents);
433
+ // 提取组装好的 Message
434
+ const assistantMsg = this.extractMessage(finalEvents);
435
+ const finishReason = this.extractFinishReason(finalEvents);
436
+ // 填充 model 和 usage
437
+ assistantMsg.model = this._model;
438
+ if (streamUsage) {
439
+ assistantMsg.usage = streamUsage;
440
+ }
441
+ return { assistantMsg, finishReason };
442
+ }
443
+ /**
444
+ * 处理工具调用:审批 → 执行 → 结果回写 Session
445
+ */
446
+ async processToolCalls(toolCalls, turn, signal) {
447
+ // 工具审批
448
+ const approvalResults = await this.approveToolCalls(toolCalls, turn, signal);
449
+ const approvedToolCalls = approvalResults
450
+ .filter((item) => item.approved)
451
+ .map((item) => item.toolCall);
452
+ const rejectedToolResults = approvalResults
453
+ .filter((item) => !item.approved)
454
+ .map((item) => Message_1.Message.tool(item.toolCall.toolCallId, JSON.stringify({ error: item.reason || "工具调用被拒绝", rejected: true })));
455
+ if (approvedToolCalls.length === 0) {
456
+ if (rejectedToolResults.length > 0) {
457
+ this._session.addTool(rejectedToolResults);
458
+ }
459
+ const error = new Error("所有工具调用均被审批拒绝");
460
+ this.failRunState(error, "tool_approval_rejected", undefined, true);
461
+ throw error;
462
+ }
463
+ // 为每个工具调用发出 START 事件
464
+ for (const tc of approvedToolCalls) {
465
+ this.throwIfAborted(signal);
466
+ this.emit({
467
+ type: StreamEvent_1.StreamEventType.TOOL_EXECUTE_START,
468
+ toolCallId: tc.toolCallId,
469
+ name: tc.name,
470
+ });
471
+ }
472
+ // 并行执行所有工具调用
473
+ const toolResults = await this.executeApprovedToolCalls(approvedToolCalls, rejectedToolResults, signal);
474
+ // 添加工具结果到 Session
475
+ this._session.addTool(toolResults);
476
+ }
477
+ /**
478
+ * 循环耗尽后的结果检查
479
+ */
480
+ handleLoopExhausted(lastAssistantMsg) {
481
+ if (!lastAssistantMsg) {
482
+ throw new Error("Agent 运行失败:未获得任何回复");
483
+ }
484
+ if (lastAssistantMsg.toolCalls.length > 0 && this._toolkit) {
485
+ const error = new Error(`Agent 达到最大循环轮次 maxTurns=${this._maxTurns},但仍未获得最终回复`);
486
+ this.failRunState(error, "max_turns", lastAssistantMsg, true);
487
+ throw error;
488
+ }
489
+ this.completeRunState(lastAssistantMsg, "final");
490
+ return lastAssistantMsg;
491
+ }
492
+ // ========================
493
+ // 事件分发
494
+ // ========================
495
+ /**
496
+ * 发射事件(支持内置事件和自定义事件)
497
+ *
498
+ * 内置事件由 Agent 循环自动发射,用户也可手动发射自定义事件:
499
+ *
500
+ * agent.emit({ type: "my_abort", reason: "用户取消" });
501
+ *
502
+ * 结合 on() 可实现自定义中断等高级功能:
503
+ *
504
+ * agent.on("abort", (e) => { ... });
505
+ * agent.emit({ type: "abort" });
506
+ */
507
+ emit(event) {
508
+ const handlers = this._handlers.get(event.type) || [];
509
+ for (const handler of handlers) {
510
+ try {
511
+ handler(event);
512
+ }
513
+ catch (e) {
514
+ // handler异常不应中断流程
515
+ console.error(`Event handler error [${event.type}]:`, e);
516
+ }
517
+ }
518
+ }
519
+ emitAll(events) {
520
+ for (const event of events) {
521
+ this.emit(event);
522
+ }
523
+ }
524
+ // ========================
525
+ // 辅助
526
+ // ========================
527
+ extractMessage(events) {
528
+ for (const event of events) {
529
+ if (event.type === StreamEvent_1.StreamEventType.MESSAGE_DONE) {
530
+ return event.message;
531
+ }
532
+ }
533
+ throw new Error("未找到 MESSAGE_DONE 事件");
534
+ }
535
+ extractFinishReason(events) {
536
+ for (const event of events) {
537
+ if (event.type === StreamEvent_1.StreamEventType.MESSAGE_DONE) {
538
+ return event.finishReason;
539
+ }
540
+ }
541
+ return undefined;
542
+ }
543
+ async executeApprovedToolCalls(approvedToolCalls, rejectedToolResults, signal) {
544
+ const policy = this._toolErrorPolicy;
545
+ const toolResults = [];
546
+ if (policy === "throw") {
547
+ try {
548
+ const results = await this.raceWithAbort(this._toolkit.executeAll(approvedToolCalls, {
549
+ signal,
550
+ errorPolicy: "throw",
551
+ }), signal);
552
+ toolResults.push(...results);
553
+ }
554
+ catch (e) {
555
+ const error = this.toError(e);
556
+ this.emitToolExecutionError(error);
557
+ this.failRunState(error, "tool_execution_error", undefined, false);
558
+ throw error;
559
+ }
560
+ }
561
+ else {
562
+ for (const toolCall of approvedToolCalls) {
563
+ this.throwIfAborted(signal);
564
+ const result = await this.raceWithAbort(this._toolkit.execute(toolCall, {
565
+ signal,
566
+ errorPolicy: policy === "pause" ? "throw" : "return_to_model",
567
+ }), signal).catch((e) => this.handleToolExecutionFailure(toolCall, e, policy));
568
+ if (result) {
569
+ toolResults.push(result);
570
+ }
571
+ }
572
+ }
573
+ for (let i = 0; i < approvedToolCalls.length; i++) {
574
+ const result = toolResults.find((msg) => msg.parts.some((part) => part.type === "tool_result" && part.toolCallId === approvedToolCalls[i].toolCallId));
575
+ if (!result)
576
+ continue;
577
+ this.throwIfAborted(signal);
578
+ this.emit({
579
+ type: StreamEvent_1.StreamEventType.TOOL_EXECUTE_DONE,
580
+ toolCallId: approvedToolCalls[i].toolCallId,
581
+ name: approvedToolCalls[i].name,
582
+ result,
583
+ });
584
+ }
585
+ return [...rejectedToolResults, ...toolResults];
586
+ }
587
+ handleToolExecutionFailure(toolCall, errorLike, policy) {
588
+ const error = this.toError(errorLike);
589
+ if (policy === "pause") {
590
+ const result = Message_1.Message.tool(toolCall.toolCallId, JSON.stringify({ error: error.message, paused: true }));
591
+ this.emitToolExecutionError(error, toolCall, result);
592
+ this._session.addTool([result]);
593
+ this.failRunState(error, "tool_execution_error", result, true);
594
+ throw error;
595
+ }
596
+ this.emitToolExecutionError(error, toolCall);
597
+ return Message_1.Message.tool(toolCall.toolCallId, JSON.stringify({ error: error.message }));
598
+ }
599
+ emitToolExecutionError(error, toolCall, result) {
600
+ const toolError = error instanceof ToolKit_1.ToolExecutionError ? error : undefined;
601
+ this.emit({
602
+ type: StreamEvent_1.StreamEventType.TOOL_EXECUTE_ERROR,
603
+ toolCallId: toolCall?.toolCallId ?? toolError?.toolCallId ?? "",
604
+ name: toolCall?.name ?? toolError?.toolName ?? "",
605
+ error,
606
+ result,
607
+ });
608
+ }
609
+ async approveToolCalls(toolCalls, turn, signal) {
610
+ const results = [];
611
+ for (const toolCall of toolCalls) {
612
+ this.throwIfAborted(signal);
613
+ const approvalId = this.generateApprovalId();
614
+ const request = {
615
+ approvalId,
616
+ toolCallId: toolCall.toolCallId,
617
+ name: toolCall.name,
618
+ arguments: this.safeParseArguments(toolCall.arguments),
619
+ rawArguments: toolCall.arguments,
620
+ turn,
621
+ };
622
+ this.emit({
623
+ type: StreamEvent_1.StreamEventType.TOOL_APPROVAL_REQUIRED,
624
+ ...request,
625
+ });
626
+ const normalized = this.normalizeApprovalResult(await this.resolveToolApproval(request, signal));
627
+ if (normalized.approved) {
628
+ this.emit({
629
+ type: StreamEvent_1.StreamEventType.TOOL_APPROVAL_ACCEPTED,
630
+ approvalId,
631
+ toolCallId: toolCall.toolCallId,
632
+ name: toolCall.name,
633
+ });
634
+ }
635
+ else {
636
+ this.emit({
637
+ type: StreamEvent_1.StreamEventType.TOOL_APPROVAL_REJECTED,
638
+ approvalId,
639
+ toolCallId: toolCall.toolCallId,
640
+ name: toolCall.name,
641
+ reason: normalized.reason,
642
+ });
643
+ }
644
+ results.push({ toolCall, ...normalized });
645
+ }
646
+ return results;
647
+ }
648
+ normalizeApprovalResult(result) {
649
+ if (typeof result === "boolean")
650
+ return { approved: result };
651
+ return {
652
+ approved: result.approved,
653
+ reason: result.reason,
654
+ };
655
+ }
656
+ resolveToolApproval(request, signal) {
657
+ if (this._toolApproval) {
658
+ return this.raceWithAbort(Promise.resolve(this._toolApproval(request)), signal);
659
+ }
660
+ if (this._toolApprovalMode !== "manual") {
661
+ return Promise.resolve(true);
662
+ }
663
+ return this.waitForManualApproval(request, signal);
664
+ }
665
+ waitForManualApproval(request, signal) {
666
+ return new Promise((resolve, reject) => {
667
+ let settled = false;
668
+ let timer;
669
+ const cleanup = () => {
670
+ if (timer)
671
+ clearTimeout(timer);
672
+ signal?.removeEventListener("abort", onAbort);
673
+ this._pendingApprovals.delete(request.approvalId);
674
+ };
675
+ const settleResolve = (result) => {
676
+ if (settled)
677
+ return;
678
+ settled = true;
679
+ cleanup();
680
+ resolve(result);
681
+ };
682
+ const settleReject = (error) => {
683
+ if (settled)
684
+ return;
685
+ settled = true;
686
+ cleanup();
687
+ reject(error);
688
+ };
689
+ const onAbort = () => settleReject(this.getAbortReason(signal));
690
+ if (signal?.aborted) {
691
+ settleReject(this.getAbortReason(signal));
692
+ return;
693
+ }
694
+ if (signal) {
695
+ signal.addEventListener("abort", onAbort, { once: true });
696
+ }
697
+ if (this._toolApprovalTimeoutMs !== undefined) {
698
+ timer = setTimeout(() => {
699
+ if (this._toolApprovalTimeoutPolicy === "abort") {
700
+ settleReject(new Error(`工具审批超时: ${request.name}`));
701
+ }
702
+ else {
703
+ settleResolve({ approved: false, reason: "工具审批超时" });
704
+ }
705
+ }, Math.max(0, this._toolApprovalTimeoutMs));
706
+ }
707
+ this._pendingApprovals.set(request.approvalId, {
708
+ ...request,
709
+ createdAt: new Date(),
710
+ resolve: settleResolve,
711
+ reject: settleReject,
712
+ });
713
+ });
714
+ }
715
+ resolvePendingApproval(approvalId, result) {
716
+ const pending = this._pendingApprovals.get(approvalId);
717
+ if (!pending)
718
+ return false;
719
+ pending.resolve(result);
720
+ return true;
721
+ }
722
+ safeParseArguments(args) {
723
+ try {
724
+ const parsed = JSON.parse(args);
725
+ return typeof parsed === "object" && parsed !== null ? parsed : {};
726
+ }
727
+ catch {
728
+ return {};
729
+ }
730
+ }
731
+ generateApprovalId() {
732
+ return (0, utils_1.generateId)("approval");
733
+ }
734
+ prepareRunOptions(options) {
735
+ const { signal: externalSignal, timeoutMs, promptBuildOptions, serializeOptions, ...requestOptions } = options ?? {};
736
+ const cleanupFns = [];
737
+ const controller = new AbortController();
738
+ const signal = controller.signal;
739
+ this._activeAbortController = controller;
740
+ if (externalSignal?.aborted) {
741
+ controller.abort(this.getAbortReason(externalSignal));
742
+ }
743
+ else if (externalSignal) {
744
+ const onAbort = () => controller.abort(this.getAbortReason(externalSignal));
745
+ externalSignal.addEventListener("abort", onAbort, { once: true });
746
+ cleanupFns.push(() => externalSignal.removeEventListener("abort", onAbort));
747
+ }
748
+ if (timeoutMs !== undefined) {
749
+ const timer = setTimeout(() => {
750
+ controller.abort(new AgentTimeoutError(timeoutMs));
751
+ }, Math.max(0, timeoutMs));
752
+ cleanupFns.push(() => clearTimeout(timer));
753
+ }
754
+ return {
755
+ requestOptions,
756
+ signal,
757
+ promptBuildOptions,
758
+ serializeOptions,
759
+ cleanup: () => {
760
+ for (const fn of cleanupFns)
761
+ fn();
762
+ if (this._activeAbortController === controller) {
763
+ this._activeAbortController = undefined;
764
+ }
765
+ },
766
+ };
767
+ }
768
+ createClientOptions(signal) {
769
+ return signal ? { signal } : undefined;
770
+ }
771
+ throwIfAborted(signal) {
772
+ if (signal?.aborted) {
773
+ throw this.getAbortReason(signal);
774
+ }
775
+ }
776
+ getAbortReason(signal) {
777
+ const reason = signal.reason;
778
+ if (reason instanceof Error)
779
+ return reason;
780
+ if (reason !== undefined)
781
+ return new AgentAbortError(String(reason));
782
+ return new AgentAbortError();
783
+ }
784
+ async raceWithAbort(promise, signal) {
785
+ this.throwIfAborted(signal);
786
+ if (!signal)
787
+ return promise;
788
+ return Promise.race([
789
+ promise,
790
+ new Promise((_, reject) => {
791
+ const onAbort = () => reject(this.getAbortReason(signal));
792
+ const cleanup = () => signal.removeEventListener("abort", onAbort);
793
+ signal.addEventListener("abort", onAbort, { once: true });
794
+ promise.then(cleanup, cleanup);
795
+ }),
796
+ ]);
797
+ }
798
+ toError(error) {
799
+ return error instanceof Error ? error : new Error(String(error));
800
+ }
801
+ emitError(error) {
802
+ this.emit({
803
+ type: StreamEvent_1.StreamEventType.ERROR,
804
+ error,
805
+ });
806
+ }
807
+ startRunState() {
808
+ const now = new Date();
809
+ this._lastRunState = {
810
+ id: (0, utils_1.generateId)("run"),
811
+ status: "running",
812
+ turn: 0,
813
+ canResume: false,
814
+ createdAt: now,
815
+ updatedAt: now,
816
+ };
817
+ }
818
+ updateRunState(patch) {
819
+ if (!this._lastRunState)
820
+ return;
821
+ this._lastRunState = {
822
+ ...this._lastRunState,
823
+ ...patch,
824
+ updatedAt: new Date(),
825
+ };
826
+ }
827
+ completeRunState(message, reason) {
828
+ this.updateRunState({
829
+ status: "completed",
830
+ stopReason: reason,
831
+ lastMessage: message,
832
+ canResume: false,
833
+ });
834
+ }
835
+ failRunState(error, reason, partial, canResume = false) {
836
+ this.updateRunState({
837
+ status: reason === "abort" || reason === "timeout" ? "interrupted" : "failed",
838
+ stopReason: reason,
839
+ error,
840
+ partialMessage: partial,
841
+ canResume,
842
+ });
843
+ }
844
+ classifyStopReason(error) {
845
+ if (error instanceof AgentTimeoutError || error.name === "TimeoutError")
846
+ return "timeout";
847
+ if (error instanceof AgentAbortError || error.name === "AbortError")
848
+ return "abort";
849
+ if (error instanceof ToolKit_1.ToolExecutionError || error.name === "ToolExecutionError")
850
+ return "tool_execution_error";
851
+ return "unknown_error";
852
+ }
853
+ persistPartialSnapshot(parser, reason) {
854
+ if (!parser.hasSnapshotContent)
855
+ return undefined;
856
+ const partial = parser.snapshot;
857
+ partial.model = this._model;
858
+ partial
859
+ .setMeta("partial", true)
860
+ .setMeta("stopReason", reason)
861
+ .setMeta("finishReason", parser.finishReason);
862
+ partial.tag("partial", "recoverable");
863
+ this._session.addAssistant(partial);
864
+ return partial;
865
+ }
866
+ isContinuableError(error) {
867
+ return error instanceof AgentTimeoutError ||
868
+ error instanceof AgentAbortError ||
869
+ error instanceof ToolKit_1.ToolExecutionError ||
870
+ error.name === "TimeoutError" ||
871
+ error.name === "AbortError" ||
872
+ error.name === "ToolExecutionError";
873
+ }
874
+ }
875
+ exports.Agent = Agent;
876
+ //# sourceMappingURL=Agent.js.map