@ddlqhd/agent-sdk 0.1.1 → 0.2.1

package/dist/tools/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import '../chunk-A3S3AGE3.js';
-export { DEFAULT_GREP_HEAD_LIMIT, FileStorageStrategy, HookManager, MAX_LINE_LENGTH, OUTPUT_CONFIG, OutputHandler, PaginationHintStrategy, SmartTruncateStrategy, ToolRegistry, agentTool, bashTool, buildHookEnv, createAgentTool, createAskUserQuestionTool, createFunctionHook, createOutputHandler, createSkillTool, createTool, editTool, formatAnswerSummary, formatAskUserQuestionPrompt, getAllBuiltinTools, getFileSystemTools, getGlobalRegistry, getGrepTools, getInteractionTools, getSafeBuiltinTools, getShellTools, getSkillTools, getSubagentTools, getTaskTools, getWebTools, globTool, grepTool, loadHooksSettingsFromProject, loadHooksSettingsFromUser, matchTool, mergeCommandHookLayers, parseHooksSettingsFile, questionTool, readFileTool, subagentRequestSchema, taskCreateTool, taskListTool, taskUpdateTool, truncateMatchLineForDisplay, webFetchTool, webSearchTool, writeFileTool } from '../chunk-THKEF32L.js';
+export { DEFAULT_GREP_HEAD_LIMIT, FileStorageStrategy, HookManager, MAX_LINE_LENGTH, OUTPUT_CONFIG, OutputHandler, PaginationHintStrategy, SUBAGENT_EXPLORE_DEFAULT_TOOL_NAMES, SUBAGENT_TYPES, SmartTruncateStrategy, ToolRegistry, agentTool, bashTool, buildHookEnv, createAgentTool, createAskUserQuestionTool, createFunctionHook, createOutputHandler, createSkillTool, createTool, editTool, formatAnswerSummary, formatAskUserQuestionPrompt, getAllBuiltinTools, getFileSystemTools, getGlobalRegistry, getGrepTools, getInteractionTools, getPlanningTools, getSafeBuiltinTools, getShellTools, getSkillTools, getSubagentTools, getWebTools, globTool, grepTool, loadHooksSettingsFromProject, loadHooksSettingsFromUser, matchTool, mergeCommandHookLayers, parseHooksSettingsFile, questionTool, readFileTool, resolveSubagentTypeAppend, subagentExploreDefaultsUnavailableMessage, subagentRequestSchema, todoWriteTool, truncateMatchLineForDisplay, webFetchTool, webSearchTool, writeFileTool } from '../chunk-TKUPLTGJ.js';
 import '../chunk-LOYIGOBZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{types-BLf9IqRs.d.cts → types-BUwjMwNH.d.cts}

@@ -178,6 +178,179 @@ interface Compressor {
     compress(messages: Message[], targetTokens: number): Promise<Message[]>;
 }
 
+/**
+ * Agent lifecycle callbacks — **observation only**.
+ *
+ * Use these for UI, tracing, auditing, and metrics. They must not change execution outcomes.
+ * **Interception** (block tool calls, rewrite inputs, policy) belongs to {@link HookManager}
+ * and {@link ToolRegistry} execution policy, not to these callbacks.
+ *
+ * @module
+ */
+
+/** Shared fields on run-level observation contexts */
+interface AgentRunContext {
+    sessionId?: string;
+    cwd?: string;
+}
+interface AgentRunStartContext extends AgentRunContext {
+    /** Original user input length before skill processing */
+    inputLength: number;
+    /** Input length after skill / template processing */
+    processedInputLength: number;
+    /** Session id from {@link StreamOptions.sessionId} when resuming */
+    resumeSessionId?: string;
+}
+type AgentRunEndReason = 'complete' | 'aborted' | 'error' | 'max_iterations';
+interface AgentRunEndContext extends AgentRunContext {
+    reason: AgentRunEndReason;
+    iterations: number;
+    usage?: TokenUsage;
+    error?: Error;
+}
+type SystemMessageSource = 'default_prompt' | 'runtime_prompt' | 'memory';
+type UserMessageSource = 'raw_input' | 'processed_input' | 'interruption_marker';
+interface MessageObservationContext extends AgentRunContext {
+    iteration?: number;
+}
+interface ModelRequestStartContext extends AgentRunContext {
+    iteration: number;
+    messageCount: number;
+    toolCount: number;
+    temperature?: number;
+    maxTokens?: number;
+    includeRawStreamEvents?: boolean;
+}
+/** Base context for tool execution observation (Agent layer) */
+interface ToolExecutionBaseContext extends AgentRunContext {
+    iteration: number;
+    toolCallId: string;
+    toolName: string;
+    arguments: unknown;
+    projectDir?: string;
+    agentDepth?: number;
+}
+interface ToolExecutionEndContext extends ToolExecutionBaseContext {
+    durationMs: number;
+    isError: boolean;
+    /** Set when the tool handler threw (distinct from `isError` result) */
+    executionError?: Error;
+}
+interface ToolResultObservationContext extends ToolExecutionEndContext {
+    result: ToolResult;
+}
+/**
+ * Observation callbacks for the tool hook pipeline inside {@link ToolRegistry}.
+ * Does not replace {@link HookManager}; it only surfaces what happened.
+ */
+interface ToolHookObserver {
+    /** Invoked immediately before a hook pipeline step runs for the given event type */
+    onHookStart?: (ctx: HookObservationContext) => void;
+    /** Invoked after `preToolUse` with the aggregate allow/deny decision */
+    onHookDecision?: (ctx: HookDecisionContext) => void;
+    /**
+     * Reserved for hook pipeline failures surfaced as `Error` (e.g. future hook instrumentation).
+     * Tool handler errors use {@link AgentLifecycleCallbacks.onToolExecutionError}.
+     */
+    onHookError?: (error: Error, ctx: HookObservationContext) => void;
+}
+interface HookObservationContext {
+    eventType: HookEventType;
+    toolName: string;
+    toolCallId?: string;
+    projectDir?: string;
+}
+interface HookDecisionContext extends HookObservationContext {
+    allowed: boolean;
+    reason?: string;
+}
+/** Optional second argument to {@link AgentCallbacks.onError} and lifecycle error hooks */
+interface AgentErrorContext {
+    phase: 'run' | 'model' | 'tool' | 'hook' | 'persistence' | 'lifecycle_callback';
+    iteration?: number;
+    toolName?: string;
+    toolCallId?: string;
+    cause?: unknown;
+}
+/**
+ * Structured lifecycle callbacks for {@link Agent}.
+ *
+ * Prefer these over ad-hoc parsing of {@link StreamEvent} when you need stable, typed observation points.
+ */
+interface AgentLifecycleCallbacks {
+    onRunStart?: (ctx: AgentRunStartContext) => void;
+    onRunEnd?: (ctx: AgentRunEndContext) => void;
+    onRunAbort?: (ctx: AgentRunContext & {
+        iteration?: number;
+    }) => void;
+    onSessionCreate?: (ctx: {
+        sessionId?: string;
+    }) => void;
+    onSessionResume?: (ctx: {
+        sessionId: string;
+        messageCount: number;
+    }) => void;
+    onIterationStart?: (ctx: {
+        iteration: number;
+        messageCount: number;
+        toolCount: number;
+    } & AgentRunContext) => void;
+    onIterationEnd?: (ctx: {
+        iteration: number;
+        hadToolCalls: boolean;
+    } & AgentRunContext) => void;
+    onContextCompressed?: (ctx: {
+        iteration: number;
+        stats: {
+            originalMessageCount: number;
+            compressedMessageCount: number;
+            durationMs: number;
+        };
+    } & AgentRunContext) => void;
+    onSystemMessage?: (message: Message, source: SystemMessageSource, ctx?: MessageObservationContext) => void;
+    onUserMessage?: (message: Message, source: UserMessageSource, ctx?: MessageObservationContext) => void;
+    onAssistantMessage?: (message: Message, ctx?: MessageObservationContext & {
+        iteration: number;
+    }) => void;
+    onToolMessage?: (message: Message, ctx?: MessageObservationContext & {
+        iteration: number;
+        toolCallId: string;
+    }) => void;
+    onMessagePersist?: (ctx: {
+        messageCount: number;
+    } & AgentRunContext) => void;
+    onModelRequestStart?: (ctx: ModelRequestStartContext) => void;
+    /**
+     * Fired for stream events that originate from the model adapter (see `isModelStreamEventType` / `MODEL_STREAM_EVENT_TYPES`).
+     * The same events are also delivered to {@link AgentCallbacks.onEvent}; subscribe to one or dedupe if both are set.
+     */
+    onModelEvent?: (event: StreamEvent) => void;
+    onModelUsage?: (ctx: {
+        usage: TokenUsage;
+        iteration?: number;
+        phase?: 'input' | 'output';
+    } & AgentRunContext) => void;
+    /** After the model stream for this iteration is fully flushed, before the assistant message is appended */
+    onModelRequestEnd?: (ctx: {
+        iteration: number;
+    } & AgentRunContext) => void;
+    /** When the model stream terminates with {@link StreamEvent} `end` and `reason: 'error'` */
+    onModelRequestError?: (error: Error, ctx: AgentErrorContext & {
+        iteration: number;
+    }) => void;
+    onToolCallPlanned?: (toolCall: ToolCall, ctx: {
+        iteration: number;
+    } & AgentRunContext) => void;
+    onToolExecutionStart?: (ctx: ToolExecutionBaseContext) => void;
+    onToolExecutionEnd?: (ctx: ToolExecutionEndContext) => void;
+    onToolResult?: (ctx: ToolResultObservationContext) => void;
+    onToolExecutionError?: (error: Error, ctx: AgentErrorContext) => void;
+    /** Bridges to {@link ToolRegistry} hook observation */
+    hooks?: ToolHookObserver;
+    /** Non-fatal agent-level errors (e.g. stream failure) */
+    onAgentError?: (error: Error, ctx: AgentErrorContext) => void;
+}
+
 /**
  * 文本内容部分
  */
@@ -228,6 +401,56 @@ interface Message {
     name?: string;
     timestamp?: number;
 }
+/**
+ * SDK 日志级别
+ */
+type SDKLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * SDK 结构化日志事件
+ */
+interface LogEvent {
+    /** 固定来源标识，便于宿主应用统一过滤 */
+    source: 'agent-sdk';
+    component: 'agent' | 'model' | 'streaming' | 'tooling' | 'memory';
+    event: string;
+    message?: string;
+    provider?: string;
+    model?: string;
+    operation?: 'stream' | 'complete' | 'compress' | 'tool_call';
+    sessionId?: string;
+    iteration?: number;
+    toolName?: string;
+    toolCallId?: string;
+    requestId?: string;
+    clientRequestId?: string;
+    statusCode?: number;
+    durationMs?: number;
+    errorName?: string;
+    errorMessage?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * SDK Logger 接口。宿主应用可将其桥接到 pino / winston / OTel 等实现。
+ */
+interface SDKLogger {
+    debug?(event: LogEvent): void;
+    info?(event: LogEvent): void;
+    warn?(event: LogEvent): void;
+    error?(event: LogEvent): void;
+}
+/**
+ * 日志脱敏与输出控制
+ */
+interface LogRedactionConfig {
+    /** 是否记录请求/响应 body，默认 false */
+    includeBodies?: boolean;
+    /** 是否记录工具调用参数，默认 false */
+    includeToolArguments?: boolean;
+    /** 单个字符串字段最大保留字符数，默认 4000 */
+    maxBodyChars?: number;
+    /** 额外需要脱敏的键名（大小写不敏感） */
+    redactKeys?: string[];
+}
 /**
  * 系统消息
  */
@@ -274,11 +497,19 @@ interface ModelParams {
     includeRawStreamEvents?: boolean;
     /** 会话标识；Agent 会在每次模型请求中填入，各适配器自行决定是否映射到 HTTP 请求。 */
     sessionId?: string;
+    /** 当前请求使用的 SDK logger。 */
+    logger?: SDKLogger;
+    /** 当前请求使用的 SDK 日志级别。 */
+    logLevel?: SDKLogLevel;
+    /** 当前请求使用的日志脱敏策略。 */
+    redaction?: LogRedactionConfig;
 }
 /**
  * 流式块类型
  */
-type StreamChunkType = 'text' | 'tool_call' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'thinking' | 'error' | 'done' | 'metadata';
+type StreamChunkType = 'text' | 'tool_call' | 'tool_call_start' | 'tool_call_delta' | 'tool_call_end' | 'thinking'
+/** Adapters emit when a discrete thinking block ends (e.g. Anthropic content_block_stop). */
+ | 'thinking_block_end' | 'error' | 'done' | 'metadata';
 /**
  * 流式块
  */
@@ -460,7 +691,7 @@ interface StorageAdapter {
 /**
  * 流式事件类型
  */
-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';
+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';
 /**
  * Optional fields on any stream event (observability, Claude-style correlation).
  */
@@ -513,10 +744,16 @@ type StreamEvent = ({
     type: 'tool_error';
     toolCallId: string;
     error: Error;
+} | {
+    type: 'thinking_start';
+    signature?: string;
 } | {
     type: 'thinking';
     content: string;
     signature?: string;
+} | {
+    type: 'thinking_end';
+    content?: string;
 } | {
     type: 'model_usage';
     usage: TokenUsage;
@@ -526,6 +763,7 @@ type StreamEvent = ({
     type: 'session_summary';
     /** Authoritative cumulative usage for the completed run (prefer over end.usage when both exist). */
     usage: TokenUsage;
+    /** Number of model rounds completed in this stream call (not message count). */
     iterations: number;
 } | {
     type: 'end';
@@ -534,8 +772,8 @@ type StreamEvent = ({
      * Optional usage (e.g. aborted mid-stream). When a session_summary event was emitted, use its usage for totals.
      */
     usage?: TokenUsage;
-    /** Omitted or `complete` = normal completion */
-    reason?: 'complete' | 'aborted' | 'error';
+    /** Omitted or `complete` = normal completion; `max_iterations` = hit `AgentConfig.maxIterations`. */
+    reason?: 'complete' | 'aborted' | 'error' | 'max_iterations';
     error?: Error;
     partialContent?: string;
 } | {
@@ -546,6 +784,16 @@ type StreamEvent = ({
         durationMs: number;
     };
 }) & StreamEventAnnotations;
+/**
+ * 模型适配器在一次请求中可能产出的流式事件类型（与 {@link isModelStreamEventType} 共用此列表，避免与 `switch` 双处维护）。
+ * 新增 `StreamEvent` 变体时：若属于模型流，请在此数组中追加对应 `type` 字符串。
+ */
+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"];
+/**
+ * 是否为由模型适配器流式产生的事件类型（用于 `lifecycle.onModelEvent` 过滤）。
+ * 排除 `start` / `end` / `session_summary` / `context_compressed` / `tool_result` / `tool_error` 等。
+ */
+declare function isModelStreamEventType(type: StreamEventType): boolean;
 /**
  * MCP 服务器配置
  */
@@ -558,6 +806,12 @@ interface MCPServerConfig {
     command?: string;
     args?: string[];
     env?: Record<string, string>;
+    /**
+     * stdio 子进程工作目录（仅 `transport === 'stdio'` 时生效）。
+     * 经 `Agent.connectMCP` 且未设置或仅空白时，使用 `AgentConfig.cwd`，再否则为当前进程的 `process.cwd()`。
+     * 直接使用 `MCPClient` 且未设置时，spawn 不传 `cwd`，子进程继承父进程工作目录（通常即当时的 `process.cwd()`）。
+     */
+    cwd?: string;
     /** HTTP 配置 */
     url?: string;
     headers?: Record<string, string>;
@@ -752,6 +1006,12 @@ interface AgentConfig {
     sessionId?: string;
     /** 回调函数 */
     callbacks?: AgentCallbacks;
+    /** SDK logger；由宿主应用决定最终输出位置。 */
+    logger?: SDKLogger;
+    /** SDK 日志级别；省略时可由环境变量控制。 */
+    logLevel?: SDKLogLevel;
+    /** 日志脱敏与 body 输出控制。 */
+    redaction?: LogRedactionConfig;
     /** 是否启用长期记忆 */
     memory?: boolean;
     /** 记忆配置 */
@@ -784,6 +1044,11 @@ interface AgentConfig {
         allowDangerousTools?: boolean;
         /** 子代理默认允许工具列表（为空时自动使用安全工具） */
         defaultAllowedTools?: string[];
+        /**
+         * 按 subagent 类型（general-purpose / explore）覆盖内置追加 system 片段；未设置的类型仍用内置文案。
+         * 设为空字符串表示该类型不追加片段。
+         */
+        subagentTypePrompts?: Partial<Record<'general-purpose' | 'explore', string>>;
     };
 }
 /**
@@ -805,17 +1070,18 @@ interface SkillConfig {
     additionalPaths?: string[];
 }
 /**
- * Agent 回调
+ * Agent 回调：流式事件 + 可选的结构化生命周期观察。
+ *
+ * - **观察**：`onEvent`、`lifecycle` — 不改变执行结果。
+ * - **拦截**：工具策略与 Hook 见 {@link AgentConfig.hookManager} / `hookConfigDir` 与 {@link ToolRegistry}。
  */
 interface AgentCallbacks {
-    /** 流式事件回调 */
+    /** 流式事件回调（与 {@link AgentLifecycleCallbacks.onModelEvent} 互补：后者仅模型侧子集） */
     onEvent?: (event: StreamEvent) => void;
-    /** 工具执行前回调 */
-    beforeToolCall?: (toolCall: ToolCall) => Promise<boolean | void>;
-    /** 工具执行后回调 */
-    afterToolCall?: (toolCall: ToolCall, result: ToolResult) => void;
-    /** 错误回调 */
-    onError?: (error: Error) => void;
+    /** 结构化生命周期观察 */
+    lifecycle?: AgentLifecycleCallbacks;
+    /** 错误回调；`context` 为可选扩展信息 */
+    onError?: (error: Error, context?: AgentErrorContext) => void;
 }
 /**
  * Agent 执行结果
@@ -899,4 +1165,4 @@ interface SkillOptions {
     path?: string;
 }
 
-export { type StreamChunkType as $, type AgentConfig as A, type HookEventType as B, type CLIConfig as C, type HookGroupConfig as D, HookManager as E, type FlatCommandHookEntry as F, type HookResult as G, type HookContext as H, type HooksSettings as I, type HooksSettingsFile as J, type ImageContent as K, type MCPOptions as L, type Message as M, type MCPPromptArgument as N, type MCPResourceContent as O, type ParsedSkill as P, type MessageRole as Q, type ModelCapabilities as R, type StorageConfig as S, type ToolResult as T, type ModelParams as U, type RunOptions as V, type SessionListOptions as W, type SkillConfig as X, type SkillDefinition as Y, type SkillMetadata as Z, type SkillOptions as _, type SessionInfo as a, type StreamEventAnnotations as a0, type StreamEventType as a1, type SystemMessage as a2, type SystemPromptConfig as a3, type TextContent as a4, type ThinkingContent as a5, type ToolCall as a6, type ToolExecutionContext as a7, type ToolExecutionPolicy as a8, type ToolHandler as a9, type ToolListOptions as aa, type ToolMessage as ab, type ToolResultMetadata as ac, type ToolSchema as ad, type UserMessage as ae, buildHookEnv as af, createAskUserQuestionTool as ag, createFunctionHook as ah, formatAnswerSummary as ai, formatAskUserQuestionPrompt as aj, getInteractionTools as ak, matchTool as al, mergeCommandHookLayers as am, questionTool as an, type StorageAdapter as b, type ToolDefinition as c, type SystemPrompt as d, type StreamEvent as e, type AgentResult as f, type ModelAdapter as g, type MCPServerConfig as h, type SessionTokenUsage as i, type TokenUsage as j, type StreamChunk as k, type MemoryConfig as l, type AgentCallbacks as m, type AgentModelConfig as n, type AskUserQuestionAnswer as o, type AskUserQuestionItem as p, type AskUserQuestionResolver as q, type AssistantMessage as r, type CanUseToolCallback as s, type ChatOptions as t, type CommandHookConfig as u, type CompletionResult as v, type ContentPart as w, type ContextManagerConfig as x, type CreateAskUserQuestionToolOptions as y, type FunctionHook as z };
+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 };