@ddlqhd/agent-sdk 0.1.0 → 0.2.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 (49) hide show
  1. package/README.md +4 -2
  2. package/dist/{chunk-5QMA2YBY.cjs → chunk-6X7EYQLS.cjs} +782 -114
  3. package/dist/chunk-6X7EYQLS.cjs.map +1 -0
  4. package/dist/{chunk-NDSL7NPN.js → chunk-D3UZNLZO.js} +769 -71
  5. package/dist/chunk-D3UZNLZO.js.map +1 -0
  6. package/dist/{chunk-Q3SOMX26.js → chunk-EQ5CXH44.js} +772 -111
  7. package/dist/chunk-EQ5CXH44.js.map +1 -0
  8. package/dist/chunk-LOYIGOBZ.js +54 -0
  9. package/dist/chunk-LOYIGOBZ.js.map +1 -0
  10. package/dist/{chunk-OHXW2YM6.js → chunk-MEJHTQJM.js} +289 -166
  11. package/dist/chunk-MEJHTQJM.js.map +1 -0
  12. package/dist/chunk-NYZD3THB.cjs +1521 -0
  13. package/dist/chunk-NYZD3THB.cjs.map +1 -0
  14. package/dist/chunk-OZO7D77N.cjs +59 -0
  15. package/dist/chunk-OZO7D77N.cjs.map +1 -0
  16. package/dist/{chunk-JF5AJQMU.cjs → chunk-Z45DHTDX.cjs} +291 -170
  17. package/dist/chunk-Z45DHTDX.cjs.map +1 -0
  18. package/dist/cli/index.cjs +47 -39
  19. package/dist/cli/index.cjs.map +1 -1
  20. package/dist/cli/index.js +22 -14
  21. package/dist/cli/index.js.map +1 -1
  22. package/dist/{index-DPsZ1zat.d.ts → index-Cw3SfEAB.d.ts} +20 -34
  23. package/dist/{index-RTPmFjMp.d.cts → index-D2Qntkn_.d.cts} +20 -34
  24. package/dist/index.cjs +125 -89
  25. package/dist/index.d.cts +62 -22
  26. package/dist/index.d.ts +62 -22
  27. package/dist/index.js +4 -4
  28. package/dist/models/index.cjs +19 -15
  29. package/dist/models/index.d.cts +55 -6
  30. package/dist/models/index.d.ts +55 -6
  31. package/dist/models/index.js +2 -2
  32. package/dist/tools/index.cjs +53 -61
  33. package/dist/tools/index.d.cts +3 -3
  34. package/dist/tools/index.d.ts +3 -3
  35. package/dist/tools/index.js +2 -2
  36. package/dist/{types-C0aX_Qdp.d.cts → types-CWPAYWzr.d.cts} +307 -61
  37. package/dist/{types-C0aX_Qdp.d.ts → types-CWPAYWzr.d.ts} +307 -61
  38. package/package.json +25 -14
  39. package/dist/chunk-5QMA2YBY.cjs.map +0 -1
  40. package/dist/chunk-CNSGZVRN.cjs +0 -152
  41. package/dist/chunk-CNSGZVRN.cjs.map +0 -1
  42. package/dist/chunk-JF5AJQMU.cjs.map +0 -1
  43. package/dist/chunk-NDSL7NPN.js.map +0 -1
  44. package/dist/chunk-OHXW2YM6.js.map +0 -1
  45. package/dist/chunk-Q3SOMX26.js.map +0 -1
  46. package/dist/chunk-WH3APNQ5.js +0 -147
  47. package/dist/chunk-WH3APNQ5.js.map +0 -1
  48. package/dist/chunk-X35MHWXE.cjs +0 -817
  49. package/dist/chunk-X35MHWXE.cjs.map +0 -1
@@ -128,52 +128,10 @@ declare const questionsSchema: z.ZodObject<{
128
128
  options: z.ZodArray<z.ZodObject<{
129
129
  label: z.ZodString;
130
130
  description: z.ZodString;
131
- }, "strip", z.ZodTypeAny, {
132
- description: string;
133
- label: string;
134
- }, {
135
- description: string;
136
- label: string;
137
- }>, "many">;
131
+ }, z.core.$strip>>;
138
132
  multiSelect: z.ZodDefault<z.ZodBoolean>;
139
- }, "strip", z.ZodTypeAny, {
140
- options: {
141
- description: string;
142
- label: string;
143
- }[];
144
- question: string;
145
- header: string;
146
- multiSelect: boolean;
147
- }, {
148
- options: {
149
- description: string;
150
- label: string;
151
- }[];
152
- question: string;
153
- header: string;
154
- multiSelect?: boolean | undefined;
155
- }>, "many">;
156
- }, "strip", z.ZodTypeAny, {
157
- questions: {
158
- options: {
159
- description: string;
160
- label: string;
161
- }[];
162
- question: string;
163
- header: string;
164
- multiSelect: boolean;
165
- }[];
166
- }, {
167
- questions: {
168
- options: {
169
- description: string;
170
- label: string;
171
- }[];
172
- question: string;
173
- header: string;
174
- multiSelect?: boolean | undefined;
175
- }[];
176
- }>;
133
+ }, z.core.$strip>>;
134
+ }, z.core.$strip>;
177
135
  type AskUserQuestionItem = z.infer<typeof questionsSchema>['questions'][number];
178
136
  type AskUserQuestionAnswer = {
179
137
  questionIndex: number;
@@ -220,6 +178,179 @@ interface Compressor {
220
178
  compress(messages: Message[], targetTokens: number): Promise<Message[]>;
221
179
  }
222
180
 
181
+ /**
182
+ * Agent lifecycle callbacks — **observation only**.
183
+ *
184
+ * Use these for UI, tracing, auditing, and metrics. They must not change execution outcomes.
185
+ * **Interception** (block tool calls, rewrite inputs, policy) belongs to {@link HookManager}
186
+ * and {@link ToolRegistry} execution policy, not to these callbacks.
187
+ *
188
+ * @module
189
+ */
190
+
191
+ /** Shared fields on run-level observation contexts */
192
+ interface AgentRunContext {
193
+ sessionId?: string;
194
+ cwd?: string;
195
+ }
196
+ interface AgentRunStartContext extends AgentRunContext {
197
+ /** Original user input length before skill processing */
198
+ inputLength: number;
199
+ /** Input length after skill / template processing */
200
+ processedInputLength: number;
201
+ /** Session id from {@link StreamOptions.sessionId} when resuming */
202
+ resumeSessionId?: string;
203
+ }
204
+ type AgentRunEndReason = 'complete' | 'aborted' | 'error' | 'max_iterations';
205
+ interface AgentRunEndContext extends AgentRunContext {
206
+ reason: AgentRunEndReason;
207
+ iterations: number;
208
+ usage?: TokenUsage;
209
+ error?: Error;
210
+ }
211
+ type SystemMessageSource = 'default_prompt' | 'runtime_prompt' | 'memory';
212
+ type UserMessageSource = 'raw_input' | 'processed_input' | 'interruption_marker';
213
+ interface MessageObservationContext extends AgentRunContext {
214
+ iteration?: number;
215
+ }
216
+ interface ModelRequestStartContext extends AgentRunContext {
217
+ iteration: number;
218
+ messageCount: number;
219
+ toolCount: number;
220
+ temperature?: number;
221
+ maxTokens?: number;
222
+ includeRawStreamEvents?: boolean;
223
+ }
224
+ /** Base context for tool execution observation (Agent layer) */
225
+ interface ToolExecutionBaseContext extends AgentRunContext {
226
+ iteration: number;
227
+ toolCallId: string;
228
+ toolName: string;
229
+ arguments: unknown;
230
+ projectDir?: string;
231
+ agentDepth?: number;
232
+ }
233
+ interface ToolExecutionEndContext extends ToolExecutionBaseContext {
234
+ durationMs: number;
235
+ isError: boolean;
236
+ /** Set when the tool handler threw (distinct from `isError` result) */
237
+ executionError?: Error;
238
+ }
239
+ interface ToolResultObservationContext extends ToolExecutionEndContext {
240
+ result: ToolResult;
241
+ }
242
+ /**
243
+ * Observation callbacks for the tool hook pipeline inside {@link ToolRegistry}.
244
+ * Does not replace {@link HookManager}; it only surfaces what happened.
245
+ */
246
+ interface ToolHookObserver {
247
+ /** Invoked immediately before a hook pipeline step runs for the given event type */
248
+ onHookStart?: (ctx: HookObservationContext) => void;
249
+ /** Invoked after `preToolUse` with the aggregate allow/deny decision */
250
+ onHookDecision?: (ctx: HookDecisionContext) => void;
251
+ /**
252
+ * Reserved for hook pipeline failures surfaced as `Error` (e.g. future hook instrumentation).
253
+ * Tool handler errors use {@link AgentLifecycleCallbacks.onToolExecutionError}.
254
+ */
255
+ onHookError?: (error: Error, ctx: HookObservationContext) => void;
256
+ }
257
+ interface HookObservationContext {
258
+ eventType: HookEventType;
259
+ toolName: string;
260
+ toolCallId?: string;
261
+ projectDir?: string;
262
+ }
263
+ interface HookDecisionContext extends HookObservationContext {
264
+ allowed: boolean;
265
+ reason?: string;
266
+ }
267
+ /** Optional second argument to {@link AgentCallbacks.onError} and lifecycle error hooks */
268
+ interface AgentErrorContext {
269
+ phase: 'run' | 'model' | 'tool' | 'hook' | 'persistence' | 'lifecycle_callback';
270
+ iteration?: number;
271
+ toolName?: string;
272
+ toolCallId?: string;
273
+ cause?: unknown;
274
+ }
275
+ /**
276
+ * Structured lifecycle callbacks for {@link Agent}.
277
+ *
278
+ * Prefer these over ad-hoc parsing of {@link StreamEvent} when you need stable, typed observation points.
279
+ */
280
+ interface AgentLifecycleCallbacks {
281
+ onRunStart?: (ctx: AgentRunStartContext) => void;
282
+ onRunEnd?: (ctx: AgentRunEndContext) => void;
283
+ onRunAbort?: (ctx: AgentRunContext & {
284
+ iteration?: number;
285
+ }) => void;
286
+ onSessionCreate?: (ctx: {
287
+ sessionId?: string;
288
+ }) => void;
289
+ onSessionResume?: (ctx: {
290
+ sessionId: string;
291
+ messageCount: number;
292
+ }) => void;
293
+ onIterationStart?: (ctx: {
294
+ iteration: number;
295
+ messageCount: number;
296
+ toolCount: number;
297
+ } & AgentRunContext) => void;
298
+ onIterationEnd?: (ctx: {
299
+ iteration: number;
300
+ hadToolCalls: boolean;
301
+ } & AgentRunContext) => void;
302
+ onContextCompressed?: (ctx: {
303
+ iteration: number;
304
+ stats: {
305
+ originalMessageCount: number;
306
+ compressedMessageCount: number;
307
+ durationMs: number;
308
+ };
309
+ } & AgentRunContext) => void;
310
+ onSystemMessage?: (message: Message, source: SystemMessageSource, ctx?: MessageObservationContext) => void;
311
+ onUserMessage?: (message: Message, source: UserMessageSource, ctx?: MessageObservationContext) => void;
312
+ onAssistantMessage?: (message: Message, ctx?: MessageObservationContext & {
313
+ iteration: number;
314
+ }) => void;
315
+ onToolMessage?: (message: Message, ctx?: MessageObservationContext & {
316
+ iteration: number;
317
+ toolCallId: string;
318
+ }) => void;
319
+ onMessagePersist?: (ctx: {
320
+ messageCount: number;
321
+ } & AgentRunContext) => void;
322
+ onModelRequestStart?: (ctx: ModelRequestStartContext) => void;
323
+ /**
324
+ * Fired for stream events that originate from the model adapter (see `isModelStreamEventType` / `MODEL_STREAM_EVENT_TYPES`).
325
+ * The same events are also delivered to {@link AgentCallbacks.onEvent}; subscribe to one or dedupe if both are set.
326
+ */
327
+ onModelEvent?: (event: StreamEvent) => void;
328
+ onModelUsage?: (ctx: {
329
+ usage: TokenUsage;
330
+ iteration?: number;
331
+ phase?: 'input' | 'output';
332
+ } & AgentRunContext) => void;
333
+ /** After the model stream for this iteration is fully flushed, before the assistant message is appended */
334
+ onModelRequestEnd?: (ctx: {
335
+ iteration: number;
336
+ } & AgentRunContext) => void;
337
+ /** When the model stream terminates with {@link StreamEvent} `end` and `reason: 'error'` */
338
+ onModelRequestError?: (error: Error, ctx: AgentErrorContext & {
339
+ iteration: number;
340
+ }) => void;
341
+ onToolCallPlanned?: (toolCall: ToolCall, ctx: {
342
+ iteration: number;
343
+ } & AgentRunContext) => void;
344
+ onToolExecutionStart?: (ctx: ToolExecutionBaseContext) => void;
345
+ onToolExecutionEnd?: (ctx: ToolExecutionEndContext) => void;
346
+ onToolResult?: (ctx: ToolResultObservationContext) => void;
347
+ onToolExecutionError?: (error: Error, ctx: AgentErrorContext) => void;
348
+ /** Bridges to {@link ToolRegistry} hook observation */
349
+ hooks?: ToolHookObserver;
350
+ /** Non-fatal agent-level errors (e.g. stream failure) */
351
+ onAgentError?: (error: Error, ctx: AgentErrorContext) => void;
352
+ }
353
+
223
354
  /**
224
355
  * 文本内容部分
225
356
  */
@@ -270,6 +401,56 @@ interface Message {
270
401
  name?: string;
271
402
  timestamp?: number;
272
403
  }
404
+ /**
405
+ * SDK 日志级别
406
+ */
407
+ type SDKLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
408
+ /**
409
+ * SDK 结构化日志事件
410
+ */
411
+ interface LogEvent {
412
+ /** 固定来源标识,便于宿主应用统一过滤 */
413
+ source: 'agent-sdk';
414
+ component: 'agent' | 'model' | 'streaming' | 'tooling' | 'memory';
415
+ event: string;
416
+ message?: string;
417
+ provider?: string;
418
+ model?: string;
419
+ operation?: 'stream' | 'complete' | 'compress' | 'tool_call';
420
+ sessionId?: string;
421
+ iteration?: number;
422
+ toolName?: string;
423
+ toolCallId?: string;
424
+ requestId?: string;
425
+ clientRequestId?: string;
426
+ statusCode?: number;
427
+ durationMs?: number;
428
+ errorName?: string;
429
+ errorMessage?: string;
430
+ metadata?: Record<string, unknown>;
431
+ }
432
+ /**
433
+ * SDK Logger 接口。宿主应用可将其桥接到 pino / winston / OTel 等实现。
434
+ */
435
+ interface SDKLogger {
436
+ debug?(event: LogEvent): void;
437
+ info?(event: LogEvent): void;
438
+ warn?(event: LogEvent): void;
439
+ error?(event: LogEvent): void;
440
+ }
441
+ /**
442
+ * 日志脱敏与输出控制
443
+ */
444
+ interface LogRedactionConfig {
445
+ /** 是否记录请求/响应 body,默认 false */
446
+ includeBodies?: boolean;
447
+ /** 是否记录工具调用参数,默认 false */
448
+ includeToolArguments?: boolean;
449
+ /** 单个字符串字段最大保留字符数,默认 4000 */
450
+ maxBodyChars?: number;
451
+ /** 额外需要脱敏的键名(大小写不敏感) */
452
+ redactKeys?: string[];
453
+ }
273
454
  /**
274
455
  * 系统消息
275
456
  */
@@ -314,11 +495,21 @@ interface ModelParams {
314
495
  * When true, adapters may attach `providerRaw` on each {@link StreamChunk} (e.g. Anthropic SSE JSON object).
315
496
  */
316
497
  includeRawStreamEvents?: boolean;
498
+ /** 会话标识;Agent 会在每次模型请求中填入,各适配器自行决定是否映射到 HTTP 请求。 */
499
+ sessionId?: string;
500
+ /** 当前请求使用的 SDK logger。 */
501
+ logger?: SDKLogger;
502
+ /** 当前请求使用的 SDK 日志级别。 */
503
+ logLevel?: SDKLogLevel;
504
+ /** 当前请求使用的日志脱敏策略。 */
505
+ redaction?: LogRedactionConfig;
317
506
  }
318
507
  /**
319
508
  * 流式块类型
320
509
  */
321
- type StreamChunkType = 'text' | 'tool_call' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'thinking' | 'error' | 'done' | 'metadata';
510
+ type StreamChunkType = 'text' | 'tool_call' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'thinking'
511
+ /** Adapters emit when a discrete thinking block ends (e.g. Anthropic content_block_stop). */
512
+ | 'thinking_block_end' | 'error' | 'done' | 'metadata';
322
513
  /**
323
514
  * 流式块
324
515
  */
@@ -450,7 +641,7 @@ interface ToolDefinition {
450
641
  /** 工具描述 */
451
642
  description: string;
452
643
  /** 参数 Schema (Zod) */
453
- parameters: z.ZodSchema;
644
+ parameters: z.ZodType;
454
645
  /** 处理函数 */
455
646
  handler: ToolHandler;
456
647
  /** 是否危险操作 */
@@ -500,7 +691,7 @@ interface StorageAdapter {
500
691
  /**
501
692
  * 流式事件类型
502
693
  */
503
- type StreamEventType = 'text_delta' | 'text_start' | 'text_end' | 'tool_call' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'tool_result' | 'tool_error' | 'thinking' | 'start' | 'end' | 'model_usage' | 'session_summary' | 'context_compressed';
694
+ type StreamEventType = 'text_delta' | 'text_start' | 'text_end' | 'tool_call' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'tool_result' | 'tool_error' | 'thinking' | 'thinking_start' | 'thinking_end' | 'start' | 'end' | 'model_usage' | 'session_summary' | 'context_compressed';
504
695
  /**
505
696
  * Optional fields on any stream event (observability, Claude-style correlation).
506
697
  */
@@ -553,10 +744,16 @@ type StreamEvent = ({
553
744
  type: 'tool_error';
554
745
  toolCallId: string;
555
746
  error: Error;
747
+ } | {
748
+ type: 'thinking_start';
749
+ signature?: string;
556
750
  } | {
557
751
  type: 'thinking';
558
752
  content: string;
559
753
  signature?: string;
754
+ } | {
755
+ type: 'thinking_end';
756
+ content?: string;
560
757
  } | {
561
758
  type: 'model_usage';
562
759
  usage: TokenUsage;
@@ -566,6 +763,7 @@ type StreamEvent = ({
566
763
  type: 'session_summary';
567
764
  /** Authoritative cumulative usage for the completed run (prefer over end.usage when both exist). */
568
765
  usage: TokenUsage;
766
+ /** Number of model rounds completed in this stream call (not message count). */
569
767
  iterations: number;
570
768
  } | {
571
769
  type: 'end';
@@ -574,8 +772,8 @@ type StreamEvent = ({
574
772
  * Optional usage (e.g. aborted mid-stream). When a session_summary event was emitted, use its usage for totals.
575
773
  */
576
774
  usage?: TokenUsage;
577
- /** Omitted or `complete` = normal completion */
578
- reason?: 'complete' | 'aborted' | 'error';
775
+ /** Omitted or `complete` = normal completion; `max_iterations` = hit `AgentConfig.maxIterations`. */
776
+ reason?: 'complete' | 'aborted' | 'error' | 'max_iterations';
579
777
  error?: Error;
580
778
  partialContent?: string;
581
779
  } | {
@@ -586,6 +784,16 @@ type StreamEvent = ({
586
784
  durationMs: number;
587
785
  };
588
786
  }) & StreamEventAnnotations;
787
+ /**
788
+ * 模型适配器在一次请求中可能产出的流式事件类型(与 {@link isModelStreamEventType} 共用此列表,避免与 `switch` 双处维护)。
789
+ * 新增 `StreamEvent` 变体时:若属于模型流,请在此数组中追加对应 `type` 字符串。
790
+ */
791
+ declare const MODEL_STREAM_EVENT_TYPES: readonly ["text_start", "text_delta", "text_end", "tool_call_start", "tool_call_delta", "tool_call", "tool_call_end", "thinking_start", "thinking", "thinking_end", "model_usage"];
792
+ /**
793
+ * 是否为由模型适配器流式产生的事件类型(用于 `lifecycle.onModelEvent` 过滤)。
794
+ * 排除 `start` / `end` / `session_summary` / `context_compressed` / `tool_result` / `tool_error` 等。
795
+ */
796
+ declare function isModelStreamEventType(type: StreamEventType): boolean;
589
797
  /**
590
798
  * MCP 服务器配置
591
799
  */
@@ -598,6 +806,12 @@ interface MCPServerConfig {
598
806
  command?: string;
599
807
  args?: string[];
600
808
  env?: Record<string, string>;
809
+ /**
810
+ * stdio 子进程工作目录(仅 `transport === 'stdio'` 时生效)。
811
+ * 经 `Agent.connectMCP` 且未设置或仅空白时,使用 `AgentConfig.cwd`,再否则为当前进程的 `process.cwd()`。
812
+ * 直接使用 `MCPClient` 且未设置时,spawn 不传 `cwd`,子进程继承父进程工作目录(通常即当时的 `process.cwd()`)。
813
+ */
814
+ cwd?: string;
601
815
  /** HTTP 配置 */
602
816
  url?: string;
603
817
  headers?: Record<string, string>;
@@ -710,12 +924,30 @@ interface ToolExecutionPolicy {
710
924
  allowedTools?: string[];
711
925
  canUseTool?: CanUseToolCallback;
712
926
  }
927
+ /**
928
+ * 与 `createModel` 参数对齐,供 `AgentConfig.modelConfig` 使用(避免 `types` 依赖 `models`)。
929
+ */
930
+ interface AgentModelConfig {
931
+ provider: 'openai' | 'anthropic' | 'ollama';
932
+ apiKey?: string;
933
+ baseUrl?: string;
934
+ model?: string;
935
+ /** Ollama:对应 `/api/chat` 的 `think` */
936
+ think?: boolean | 'low' | 'medium' | 'high';
937
+ }
713
938
  /**
714
939
  * Agent 配置
715
940
  */
716
941
  interface AgentConfig {
717
- /** 模型适配器 */
718
- model: ModelAdapter;
942
+ /**
943
+ * 模型适配器;与 {@link modelConfig} 二选一。
944
+ * 若需让 {@link env} 参与 API Key 等解析,请使用 `modelConfig`,由 Agent 内部调用 {@link mergeProcessEnv} 后构造适配器。
945
+ */
946
+ model?: ModelAdapter;
947
+ /**
948
+ * 由 Agent 在内部通过 `createModel(modelConfig, env)` 构造适配器;与 `model` 二选一。
949
+ */
950
+ modelConfig?: AgentModelConfig;
719
951
  /** 系统提示 (字符串或配置对象) */
720
952
  systemPrompt?: SystemPrompt;
721
953
  /**
@@ -751,6 +983,13 @@ interface AgentConfig {
751
983
  skills?: string[];
752
984
  /** MCP 服务器配置 */
753
985
  mcpServers?: MCPServerConfig[];
986
+ /**
987
+ * 对当前进程环境的补充与覆盖(合并到 stdio MCP 子进程;键与 `process.env` 冲突时以本字段为准)。
988
+ * 与 {@link includeEnvironment}(往 system prompt 注入工作区描述)无关。
989
+ * 使用 `modelConfig` 时,`env` 会一并用于构造模型适配器;若传入现成 `model`,请自行用 `mergeProcessEnv` 解析密钥等。
990
+ * 完整继承会将 `process.env` 中的敏感变量一并带入 MCP 子进程,由调用方控制。
991
+ */
992
+ env?: Record<string, string>;
754
993
  /** 用户级基础路径,默认 ~ (homedir),用于定位 .claude/ 目录 */
755
994
  userBasePath?: string;
756
995
  /** 存储配置 */
@@ -767,6 +1006,12 @@ interface AgentConfig {
767
1006
  sessionId?: string;
768
1007
  /** 回调函数 */
769
1008
  callbacks?: AgentCallbacks;
1009
+ /** SDK logger;由宿主应用决定最终输出位置。 */
1010
+ logger?: SDKLogger;
1011
+ /** SDK 日志级别;省略时可由环境变量控制。 */
1012
+ logLevel?: SDKLogLevel;
1013
+ /** 日志脱敏与 body 输出控制。 */
1014
+ redaction?: LogRedactionConfig;
770
1015
  /** 是否启用长期记忆 */
771
1016
  memory?: boolean;
772
1017
  /** 记忆配置 */
@@ -820,17 +1065,18 @@ interface SkillConfig {
820
1065
  additionalPaths?: string[];
821
1066
  }
822
1067
  /**
823
- * Agent 回调
1068
+ * Agent 回调:流式事件 + 可选的结构化生命周期观察。
1069
+ *
1070
+ * - **观察**:`onEvent`、`lifecycle` — 不改变执行结果。
1071
+ * - **拦截**:工具策略与 Hook 见 {@link AgentConfig.hookManager} / `hookConfigDir` 与 {@link ToolRegistry}。
824
1072
  */
825
1073
  interface AgentCallbacks {
826
- /** 流式事件回调 */
1074
+ /** 流式事件回调(与 {@link AgentLifecycleCallbacks.onModelEvent} 互补:后者仅模型侧子集) */
827
1075
  onEvent?: (event: StreamEvent) => void;
828
- /** 工具执行前回调 */
829
- beforeToolCall?: (toolCall: ToolCall) => Promise<boolean | void>;
830
- /** 工具执行后回调 */
831
- afterToolCall?: (toolCall: ToolCall, result: ToolResult) => void;
832
- /** 错误回调 */
833
- onError?: (error: Error) => void;
1076
+ /** 结构化生命周期观察 */
1077
+ lifecycle?: AgentLifecycleCallbacks;
1078
+ /** 错误回调;`context` 为可选扩展信息 */
1079
+ onError?: (error: Error, context?: AgentErrorContext) => void;
834
1080
  }
835
1081
  /**
836
1082
  * Agent 执行结果
@@ -914,4 +1160,4 @@ interface SkillOptions {
914
1160
  path?: string;
915
1161
  }
916
1162
 
917
- export { type StreamEventAnnotations as $, type AgentConfig as A, HookManager as B, type CLIConfig as C, type HookResult as D, type HooksSettings as E, type FlatCommandHookEntry as F, type HooksSettingsFile as G, type HookContext as H, type ImageContent as I, type MCPOptions as J, type MCPPromptArgument as K, type MCPResourceContent as L, type Message as M, type MessageRole as N, type ModelAdapter as O, type ParsedSkill as P, type ModelCapabilities as Q, type ModelParams as R, type StorageConfig as S, type ToolResult as T, type RunOptions as U, type SessionListOptions as V, type SkillConfig as W, type SkillDefinition as X, type SkillMetadata as Y, type SkillOptions as Z, type StreamChunkType as _, type SessionInfo as a, type StreamEventType as a0, type SystemMessage as a1, type SystemPromptConfig as a2, type TextContent as a3, type ThinkingContent as a4, type ToolCall as a5, type ToolExecutionContext as a6, type ToolExecutionPolicy as a7, type ToolHandler as a8, type ToolListOptions as a9, type ToolMessage as aa, type ToolResultMetadata as ab, type ToolSchema as ac, type UserMessage as ad, buildHookEnv as ae, createAskUserQuestionTool as af, createFunctionHook as ag, formatAnswerSummary as ah, formatAskUserQuestionPrompt as ai, getInteractionTools as aj, matchTool as ak, mergeCommandHookLayers as al, questionTool as am, type StorageAdapter as b, type ToolDefinition as c, type SystemPrompt as d, type StreamEvent as e, type AgentResult as f, type MCPServerConfig as g, type SessionTokenUsage as h, type TokenUsage as i, type StreamChunk as j, type MemoryConfig as k, type AgentCallbacks as l, type AskUserQuestionAnswer as m, type AskUserQuestionItem as n, type AskUserQuestionResolver as o, type AssistantMessage as p, type CanUseToolCallback as q, type ChatOptions as r, type CommandHookConfig as s, type CompletionResult as t, type ContentPart as u, type ContextManagerConfig as v, type CreateAskUserQuestionToolOptions as w, type FunctionHook as x, type HookEventType as y, type HookGroupConfig as z };
1163
+ export { type MCPPromptArgument as $, type AgentConfig as A, type ChatOptions as B, type CLIConfig as C, type CommandHookConfig as D, type CompletionResult as E, type ContentPart as F, type ContextManagerConfig as G, type CreateAskUserQuestionToolOptions as H, type FlatCommandHookEntry as I, type FunctionHook as J, type HookContext as K, type LogEvent as L, type Message as M, type HookDecisionContext as N, type HookEventType as O, type ParsedSkill as P, type HookGroupConfig as Q, HookManager as R, type StorageConfig as S, type ToolResult as T, type HookObservationContext as U, type HookResult as V, type HooksSettings as W, type HooksSettingsFile as X, type ImageContent as Y, type LogRedactionConfig as Z, type MCPOptions as _, type SessionInfo as a, type MCPResourceContent as a0, MODEL_STREAM_EVENT_TYPES as a1, type MessageObservationContext as a2, type MessageRole as a3, type ModelCapabilities as a4, type ModelParams as a5, type ModelRequestStartContext as a6, type RunOptions as a7, type SDKLogLevel as a8, type SessionListOptions as a9, buildHookEnv as aA, createAskUserQuestionTool as aB, createFunctionHook as aC, formatAnswerSummary as aD, formatAskUserQuestionPrompt as aE, getInteractionTools as aF, isModelStreamEventType as aG, matchTool as aH, mergeCommandHookLayers as aI, questionTool as aJ, type SkillConfig as aa, type SkillDefinition as ab, type SkillMetadata as ac, type SkillOptions as ad, type StreamChunkType as ae, type StreamEventAnnotations as af, type StreamEventType as ag, type SystemMessage as ah, type SystemMessageSource as ai, type SystemPromptConfig as aj, type TextContent as ak, type ThinkingContent as al, type ToolCall as am, type ToolExecutionBaseContext as an, type ToolExecutionContext as ao, type ToolExecutionEndContext as ap, type ToolExecutionPolicy as aq, type ToolHandler as ar, type ToolHookObserver as as, type ToolListOptions as at, type ToolMessage as au, type ToolResultMetadata as av, type ToolResultObservationContext as aw, type ToolSchema as ax, type UserMessage as ay, type UserMessageSource as az, type StorageAdapter as b, type MCPServerConfig as c, type ToolDefinition as d, type SystemPrompt as e, type StreamEvent as f, type AgentResult as g, type ModelAdapter as h, type SessionTokenUsage as i, type SDKLogger as j, type TokenUsage as k, type StreamChunk as l, type MemoryConfig as m, type AgentCallbacks as n, type AgentErrorContext as o, type AgentLifecycleCallbacks as p, type AgentModelConfig as q, type AgentRunContext as r, type AgentRunEndContext as s, type AgentRunEndReason as t, type AgentRunStartContext as u, type AskUserQuestionAnswer as v, type AskUserQuestionItem as w, type AskUserQuestionResolver as x, type AssistantMessage as y, type CanUseToolCallback as z };